vibe-sketcherDocumentation
Source code for vibesketcher.agent.mcp_porosity
"""MCP tools for probe-defined porosity plans (#206).
Each tool is a call to the REST routes in :mod:`vibesketcher.server.porosity`;
:func:`tools` is joined to the list in :func:`vibesketcher.agent.mcp.make_tools`.
"""
from __future__ import annotations
import urllib.parse
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
_PLAN_HELP = (
"plan = {structure, probe {species, radius_angstrom, radius_source}, radii {name "
"vdw|covalent (RDKit), overrides {element: angstrom}}, surface accessible|connolly|none, "
"sampling {spacings_angstrom coarse to fine, tolerance_diameter_angstrom, "
"tolerance_fraction, surface_samples_per_atom, seed}, window_delta_angstrom, psd "
"{bin_width_angstrom, region total|accessible, normalisation cell_fraction|"
"region_fraction}, engine reference (others refused), slab_policy refuse|cell_box}"
)
[docs]
def tools(
client: RestClient,
document_id: Callable[[dict[str, Any]], str],
edit: Callable[[dict[str, Any], str, str, dict[str, Any]], Any] | None = None,
) -> list[Tool]:
from vibesketcher.agent.mcp import Tool, _schema
document = {"type": "string", "description": "Document id; the open document when left out."}
plan = {"document": document, "plan": {"type": "object"}}
def route(arguments: dict[str, Any], name: str) -> str:
return f"api/documents/{document_id(arguments)}/porosity/{name}"
def plan_porosity(arguments: dict[str, Any]) -> Any:
return client.call("POST", route(arguments, "plan"), {"plan": arguments.get("plan", {})})
def estimate_porosity(arguments: dict[str, Any]) -> Any:
return client.call(
"POST", route(arguments, "estimate"), {"plan": arguments.get("plan", {})}
)
def porosity_psd_figure(arguments: dict[str, Any]) -> Any:
body = {
"plan": arguments.get("plan", {}),
"options": arguments.get("options", {}),
"format": "svg",
}
content, _ = client.raw("POST", route(arguments, "psd-figure"), body)
return {"format": "svg", "svg": content.decode("utf-8")}
def porosity_handoff(arguments: dict[str, Any]) -> Any:
body = {"plan": arguments.get("plan", {}), "files": arguments.get("files", {})}
return client.call("POST", route(arguments, "handoff"), body)
def store_porosity_estimate(arguments: dict[str, Any]) -> Any:
assert edit is not None
if arguments.get("undo"):
return edit(arguments, "POST", "porosity/undo", {"structure": arguments["undo"]})
body: dict[str, Any] = {"plan": arguments.get("plan", {})}
if arguments.get("estimate_id"):
body["estimate_id"] = arguments["estimate_id"]
return edit(arguments, "POST", "porosity/store", body)
def list_porosity_estimates(arguments: dict[str, Any]) -> Any:
structure = urllib.parse.quote(str(arguments["structure"]), safe="")
if arguments.get("estimate"):
one = urllib.parse.quote(str(arguments["estimate"]), safe="")
return client.call("GET", route(arguments, f"stored/{structure}/{one}"))
return client.call("GET", route(arguments, f"stored/{structure}"))
def porosity_table(arguments: dict[str, Any]) -> Any:
structure = urllib.parse.quote(str(arguments["structure"]), safe="")
fmt = str(arguments.get("format") or "csv")
query = {"format": fmt}
if arguments.get("estimate"):
query["estimate"] = str(arguments["estimate"])
path = route(arguments, f"table/{structure}") + "?" + urllib.parse.urlencode(query)
content, _ = client.raw("GET", path)
return {"format": fmt, "text": content.decode("utf-8")}
stored_tools = [
Tool(
"store_porosity_estimate",
"Run the reference estimate of a plan (as for estimate_porosity) and store it on "
"its structure as one revision-checked, undoable edit, with the structure digest "
"(estimate_id optional, porosity-N by default). Stored estimates travel in the "
".vsk file and the QVF (vendor section x_vibesketch.porosity). undo=<structure "
"ID> removes the last stored estimate while the structure is unchanged "
"(porosity.stale_estimate once it changed).",
_schema(
{
**plan,
"estimate_id": {"type": "string"},
"undo": {"type": "string"},
}
),
store_porosity_estimate,
),
Tool(
"list_porosity_estimates",
"The porosity estimates stored on a structure, each marked stale (the structure "
"changed since) or current; estimate=<id> returns one with its full payload.",
_schema(
{
"document": document,
"structure": {"type": "string"},
"estimate": {"type": "string"},
},
("structure",),
),
list_porosity_estimates,
),
Tool(
"porosity_table",
"Publication table (format csv|svg|tex) of a current stored porosity estimate "
"(the latest unless estimate=<id>): Di, Df, dimensionality, outcome, void, "
"probe-occupiable and accessible fractions, pore volume, the accessible or "
"Connolly surface area per cell, volume and mass, excluded volume and density, "
"with units, the structure digest and the label 'geometric planning estimate, not "
"BET/adsorption capacity'. A stale estimate is refused.",
_schema(
{
"document": document,
"structure": {"type": "string"},
"estimate": {"type": "string"},
"format": {"type": "string", "enum": ["csv", "svg", "tex"]},
},
("structure",),
),
porosity_table,
),
]
return [
Tool(
"plan_porosity",
"Validate a probe-defined porosity plan for a periodic "
f"structure. {_PLAN_HELP}. Returns the stated plan, the radius table with its "
"name and version, definitions (geometric void, probe-centre, probe-occupiable, "
"accessible and non-accessible volume; Di, Df; accessible and Connolly surface), "
"the grid ladder, the work against the bounds, and refusals with stable codes "
"(porosity.periodicity_unsupported, porosity.engine_unavailable, ...). No change.",
_schema(plan, ("plan",)),
plan_porosity,
),
Tool(
"estimate_porosity",
"Run the bounded reference geometric estimate of a plan "
"(as for plan_porosity): Di, Df (overall and per axis), void, probe-centre, "
"probe-occupiable, accessible and non-accessible fractions, channel "
"dimensionality from periodic connectivity, window sensitivity at r +/- delta "
"(outcome open|uncertain|blocked|zero), ladder convergence, the accessible "
"surface area or (surface=connolly) the Connolly surface area, total and "
"accessible, with the excluded and occupiable volumes (Ų per cell, m²/cm³, "
"m²/g; cm³/g), and the Gelb-Gubbins PSD with units and "
"normalisation. A geometric planning estimate: not adsorption capacity or BET area.",
_schema(plan, ("plan",)),
estimate_porosity,
),
Tool(
"porosity_psd_figure",
"SVG figure of the estimate's pore-size distribution "
"(bars) and cumulative curve, with provenance lines (structure digest, probe, "
"radii, grid, outcome). options = {quantity fraction|density_per_angstrom, "
"cumulative, width, height, title, provenance}. An empty distribution is refused.",
_schema({**plan, "options": {"type": "object"}}, ("plan",)),
porosity_psd_figure,
),
Tool(
"porosity_handoff",
"The Viewer handoff record of an estimate: structure digest "
"and vibe-viewer fingerprint, grid shape and spacing, the parameters of the "
"Viewer's own pore grid estimate, results, window and convergence, and files "
"{name: sha256} as given. Write it as a sidecar JSON next to the CSV/figure.",
_schema({**plan, "files": {"type": "object"}}, ("plan",)),
porosity_handoff,
),
*(stored_tools if edit is not None else []),
]