vibe-sketcherDocumentation

Source code for vibesketcher.agent.mcp_porous_carbon

"""MCP tools for net-derived porous and negative-curvature carbon models (#204).

Each tool is a call to the REST routes in :mod:`vibesketcher.server.porous_carbon`;
:func:`tools` is joined to the list in :func:`vibesketcher.agent.mcp.make_tools`.
Building uses ``build_periodic`` with a ``kind=porous_carbon`` recipe.
"""

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

_RECIPE_HELP = (
    "recipe = {identifier, net pcu, construction truncated_mucube, bond_length, "
    "edge_bond_length, bond_tolerance, repeat [a, b, c] (1-3), vacancies, stone_wales (90-degree "
    "bond rotations, Stone and Wales 1986), stone_wales_bond edge|ring, seed, "
    "min_distance, max_ring_size, termination none}"
)


[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."} def models(arguments: dict[str, Any]) -> Any: return client.call("GET", "api/periodic/porous-carbon-models") def preview(arguments: dict[str, Any]) -> Any: return client.call( "POST", f"api/documents/{document_id(arguments)}/periodic/porous-carbon/preview", {"recipe": arguments["recipe"], "structure": bool(arguments.get("structure"))}, ) def report(arguments: dict[str, Any]) -> Any: body = {k: arguments[k] for k in ("structure", "max_ring_size", "probe_radius", "probe_species") if k in arguments} # fmt: skip return client.call( "POST", f"api/documents/{document_id(arguments)}/periodic/porous-carbon/report", body ) return [ Tool( "porous_carbon_models", "The porous-carbon model plan: constructions (truncated_mucube on pcu is built; " "D-surface, TPMS remeshing and zeolite-templated carbons are planned and refused), " "bounds, checks, references and the status 'geometric model, unrelaxed, not a " "stable material'.", _schema({}), models, ), Tool( "preview_porous_carbon", f"Preview a kind=porous_carbon build without storing it. {_RECIPE_HELP}. Returns " "the generating net, surface, cell and parameters, the pristine topology (V, E, " "F, Euler characteristic, genus, face census, curvature check), the graph checks " "(coordination, bond lengths, vertex symbols, ring census), contacts, the " "pristine/defect map, or refusals with stable codes (porous_carbon.*). Build it " "with build_periodic.", _schema( { "document": document, "recipe": {"type": "object"}, "structure": {"type": "boolean"}, }, ("recipe",), ), # fmt: skip preview, ), Tool( "porous_carbon_report", "Ring, coordination and bond checks of a stored carbon structure, with its model " "record (stale after edits) and, given probe_radius, a porosity plan for " "plan_porosity (validated, not run). Read-only.", _schema( { "document": document, "structure": {"type": "string"}, "max_ring_size": {"type": "integer"}, "probe_radius": {"type": "number"}, "probe_species": {"type": "string"}, }, ("structure",), ), # fmt: skip report, ), ]