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