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