vibe-sketcherDocumentation

Source code for vibesketcher.agent.mcp_diffraction

"""MCP tools for powder diffraction planning (#207).

Each tool is a call to the REST routes in :mod:`vibesketcher.server.diffraction`;
:func:`tools` is joined to the list in :func:`vibesketcher.agent.mcp.make_tools`.
"""

from __future__ import annotations

from collections.abc import Callable
from typing import TYPE_CHECKING, Any

from vibesketcher.agent.client import RestClient

if TYPE_CHECKING:
    from vibesketcher.agent.mcp import Tool

_SETTINGS_HELP = (
    "settings = {wavelength CuKa1 (default)|MoKa1|angstrom, two_theta_min, two_theta_max, "
    "b_iso/u_iso {site ID, CIF label or element: value}, default_b_iso, occupancy overrides, "
    "monochromator_two_theta, preferred_orientation {model march_dollase, hkl [h, k, l] "
    "(reciprocal direction: platelet normal or needle axis), r (1 random, <1 plates, "
    ">1 needles)}, profile {shape gaussian|lorentzian|pseudo_voigt, fwhm_deg | "
    "caglioti [U, V, W], eta, step_deg}}"
)


[docs] def tools(client: RestClient, document_id: Callable[[dict[str, Any]], str]) -> list[Tool]: from vibesketcher.agent.mcp import Tool, _schema document = {"type": "string", "description": "Document id; the open document when left out."} source = {"document": document, "structure": {"type": "string"}, "cif": {"type": "string"}, "block": {"type": "string"}, "setting": {"type": "string"}, "settings": {"type": "object"}} # fmt: skip def calculate_powder_pattern(arguments: dict[str, Any]) -> Any: settings = arguments.get("settings", {}) if arguments.get("cif"): body = {"cif": arguments["cif"], "settings": settings} body.update({k: arguments[k] for k in ("block", "setting") if arguments.get(k)}) return client.call("POST", "api/diffraction/cif-pattern", body) return client.call( "POST", f"api/documents/{document_id(arguments)}/diffraction/pattern", {"structure": arguments.get("structure"), "settings": settings}, ) def read_measured_pattern(arguments: dict[str, Any]) -> Any: keys = ("filename", "text", "data_base64", "settings", "points") body = {k: arguments[k] for k in keys if k in arguments} return client.call("POST", "api/diffraction/measured", body) def powder_overlay_figure(arguments: dict[str, Any]) -> Any: keys = ("structure", "cif", "block", "setting", "settings", "measured", "options") body = {k: arguments[k] for k in keys if k in arguments} content, _ = client.raw( "POST", f"api/documents/{document_id(arguments)}/diffraction/figure", {**body, "format": "svg"}, ) return {"format": "svg", "svg": content.decode("utf-8")} return [ Tool("calculate_powder_pattern", "Calculated X-ray powder pattern of a periodic " "structure, or of posted CIF text with its occupancies and U_iso/B_iso: " "reflections with hkl (in the stated cell's basis), multiplicity over the full " "sphere, d, 2theta, Q, |F|^2, Lp and intensities, plus assumptions and the source " f"digest. {_SETTINGS_HELP}. Waasmaier-Kirfel neutral-atom form factors; " "anisotropic ADPs and unknown elements are refused. Kinematic, no absorption; " "optional March-Dollase preferred orientation; not a refinement.", _schema(source), calculate_powder_pattern), Tool("read_measured_pattern", "Read a measured powder pattern from two-column XY or " "CSV text (or data_base64 bytes) with its file name. settings = {axis " "two_theta_deg|d_angstrom|q_inv_angstrom (required, never guessed), " "intensity_unit counts|counts_per_second|arbitrary, wavelength_angstrom, format " "xy|csv, instrument {field: value} kept as given, sample}. Vendor or binary " "formats and unknown axes are refused. Returns points and provenance (SHA-256 of " "the bytes, header lines, ranges); points=false returns provenance only.", _schema({"filename": {"type": "string"}, "text": {"type": "string"}, "data_base64": {"type": "string"}, "settings": {"type": "object"}, "points": {"type": "boolean"}}, ("filename", "settings")), read_measured_pattern), Tool("powder_overlay_figure", "SVG publication overlay of a measured pattern " "(measured = {filename, text | data_base64, settings} as for " "read_measured_pattern) against the calculated pattern of structure (or cif) with " "settings as for calculate_powder_pattern: reflection tick marks and provenance " "lines with both digests. options = {axis two_theta_deg|d_angstrom|q_inv_angstrom, " "x_range, ticks, label_reflections n, width, height, title, provenance}. A 2theta " "overlay needs equal wavelengths; the calculated curve is scaled for display only.", _schema({**source, "measured": {"type": "object"}, "options": {"type": "object"}}), powder_overlay_figure), ] # fmt: skip