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 []), ]