vibe-sketcherDocumentation

Source code for vibesketcher.agent.mcp_solid_reactions

"""MCP tools for solid-state and surface reaction schemes (#192).

Each tool is a call to the REST routes in
:mod:`vibesketcher.server.solid_reactions`; :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

_PARTICIPANT_HELP = (
    "participants: [{id, kind (bulk_phase, slab, adsorbed_slab, empty_site, surface_vacancy, "
    "adsorbate, gas, solution, electron), label (CO*, CuO(s), *, e^-), formula {El: n}?, "
    "charge?, sites {type: n}? ('*' for adsorption sites, default 1 for empty sites and "
    "adsorbates; a vacancy names its lattice site, e.g. {O_site: 1}), structure? (periodic "
    "structure ID; formula derived from it or from atoms [site IDs]), parent?, species?}]. "
    "Participants sharing a structure or parent keep their own IDs."
)
_STEP_HELP = (
    "steps: [{id, kind (adsorption, desorption, dissociation, diffusion, "
    "surface_transformation, bulk_synthesis), reactants/products [{participant, "
    "coefficient}], arrow (forward, equilibrium), reservoirs [{quantity (element, 'charge' "
    "or 'site:*'), description, participant?}], conditions {facet, temperature_k, pressures "
    "[{value, unit, of}], potential {value_v, reference}, notes}, coverages {participant: "
    "ML}, site_map [{from {participant, site}, to {participant, site}, image [i,j,k]}] "
    "(required for diffusion), atom_map, schematic}]. Atoms, charge and sites must balance "
    "unless a reservoir names the open quantity; bulk_synthesis takes no reservoirs. "
    "Conditions imply no kinetics."
)


[docs] def tools( client: RestClient, document_id: Callable[[dict[str, Any]], str], edit: Callable[[dict[str, Any], str, str, dict[str, Any]], Any], ) -> list[Tool]: from vibesketcher.agent.mcp import Tool, _schema document = {"type": "string", "description": "Document id; the open document when left out."} def solid_reactions(arguments: dict[str, Any]) -> Any: if arguments.get("example"): return client.call("GET", f"api/solid-reactions/examples/{arguments['example']}") if arguments.get("step"): body = {"step": arguments["step"], "participants": arguments.get("participants", [])} return client.call( "POST", f"api/documents/{document_id(arguments)}/solid-reactions/check", body ) return client.call("GET", f"api/documents/{document_id(arguments)}/solid-reactions") def edit_solid_reactions(arguments: dict[str, Any]) -> Any: if arguments.get("remove"): return edit(arguments, "POST", "solid-reactions/remove", {"ids": arguments["remove"]}) if arguments.get("example"): return edit( arguments, "POST", "solid-reactions/example", {"name": arguments["example"]} ) keys: tuple[str, ...] = ("participants", "steps", "replace") body = {k: arguments[k] for k in keys if k in arguments} return edit(arguments, "POST", "solid-reactions", body) def solid_reaction_figure(arguments: dict[str, Any]) -> Any: body = {k: arguments[k] for k in ("steps", "style") if k in arguments} content, _ = client.raw( "POST", f"api/documents/{document_id(arguments)}/solid-reactions/figure", body ) return {"format": "svg", "svg": content.decode("utf-8")} return [ Tool("solid_reactions", "Read-only report of the document's solid-state and surface " "reaction scheme: participants with formula, charge and sites, and steps with " "atom/charge/site balances, open reservoirs, conditions, coverages and periodic " "site-map hops (image, vector, minimum-image flag). With step (and extra " "participants) it is a dry-run check of one step; with example (co-adsorption, " "cuo-reduction) it returns that worked scheme.", _schema({"document": document, "step": {"type": "object"}, "participants": {"type": "array", "items": {"type": "object"}}, "example": {"type": "string"}}), solid_reactions), Tool("edit_solid_reactions", "Add or (replace=true) change solid-state and surface " "reaction participants and steps as one revision-checked edit; remove=[ids] " "removes them; example=name adds a worked scheme. " + _PARTICIPANT_HELP + " " + _STEP_HELP + " Molecular exports (MOL, RXN, SMILES ...) refuse documents with " "these participants; VSK and QVF keep them.", _schema({"document": document, "participants": {"type": "array", "items": {"type": "object"}}, "steps": {"type": "array", "items": {"type": "object"}}, "replace": {"type": "boolean"}, "remove": {"type": "array", "items": {"type": "string"}}, "example": {"type": "string"}}), edit_solid_reactions), Tool("solid_reaction_figure", "The solid reaction scheme (all steps, or those named) " "as an editable SVG: one text element per participant label with its ID, " "conditions at the arrow, the step kind beside it.", _schema({"document": document, "steps": {"type": "array", "items": {"type": "string"}}, "style": {"type": "string"}}), solid_reaction_figure), ] # fmt: skip