vibe-sketcherDocumentation
Source code for vibesketcher.agent.mcp_cnt_composites
"""MCP tools for representative coated and disordered CNT fibre composites (#241).
Each tool is a call to the REST routes in
:mod:`vibesketcher.server.cnt_composites`; :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
_COMPOSITE_HELP = (
"composite = {identifier, label, tube {n, m (m <= n), outer_walls [{n, m}] (concentric, "
"commensurate), form periodic (through c, the fibre axis) | segment (finite, H-terminated), "
"periods}, bundle {count (<= 61), packing hexagonal (pitch 2R + gap) | random (seeded "
"positions in a disc of radius_angstrom, rotation, axial shift, max_tilt_deg for segments, "
"max_attempts), gap_angstrom (3.4)}, cell {kind matrix (periodic box, lateral_angstrom "
"[a, b]) | coated_fibre (periodic along c, coating_thickness_angstrom, infiltrate, "
"vacuum_angstrom), length_angstrom (segments)}, polymer {units {LABEL: {smiles | template "
"| generic}}, chain {unit | sequence | composition, arrangement, length, tacticity, head, "
"tail}, collision_scale, max_attempts, ...}, composition {chains | target_density_g_cm3 | "
"polymer_weight_fraction}, seed, macroscopic [{quantity, value, unit nm|um|mm|cm|m, "
"spread, source, note}] (labelled metadata only), references [DOI...]}"
)
[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 composite_of(arguments: dict[str, Any]) -> dict[str, Any]:
if arguments.get("example"):
listed = client.call(
"GET", f"api/documents/{document_id(arguments)}/periodic/cnt-composite/examples"
)
found = listed["examples"].get(arguments["example"])
if found is None:
raise ValueError(
f"unknown example {arguments['example']!r}; choose one of "
f"{sorted(listed['examples'])}"
)
return dict(found)
return dict(arguments.get("composite", {}))
def preview_cnt_composite(arguments: dict[str, Any]) -> Any:
base = f"api/documents/{document_id(arguments)}/periodic/cnt-composite"
if arguments.get("list_examples"):
return client.call("GET", f"{base}/examples")
return client.call("POST", f"{base}/preview", {"composite": composite_of(arguments)})
def apply_cnt_composite(arguments: dict[str, Any]) -> Any:
if arguments.get("undo"):
return edit(
arguments, "POST", "periodic/cnt-composite/undo", {"structure": arguments["undo"]}
)
return edit(
arguments, "POST", "periodic/cnt-composite", {"composite": composite_of(arguments)}
)
return [
Tool(
"preview_cnt_composite",
"Preview a representative CNT fibre composite: a bounded nanotube bundle "
"(hexagonal or seeded random with clash refusal) in a periodic matrix or a coated "
"fibre section, with polymer chains grown around the tubes (no chain atom overlaps "
"a tube atom or enters a tube); the document is unchanged. "
f"{_COMPOSITE_HELP}. example=<name> uses a representative example tied to a source "
"paper; list_examples=true lists them. Returns the tubes (centres, axes, tilts), "
"bundle, composition (CNT and polymer weight fractions, unrelaxed density), the "
"polymer growth counts, brute-force checks and refusals with stable codes "
"(composite.disorder_exhausted, composite.cell_too_small, ...). The result is an "
"unrelaxed representative model; no electrical, mechanical or biological property "
"is inferred.",
_schema(
{
"document": document,
"composite": {"type": "object"},
"example": {"type": "string"},
"list_examples": {"type": "boolean"},
}
),
preview_cnt_composite,
),
Tool(
"apply_cnt_composite",
"Add a previewed CNT composite to the document (revision-checked; refused while "
"the preview has refusals); composite or example=<name>. undo=<model ID> removes "
"a composite again while it is unchanged.",
_schema(
{
"document": document,
"composite": {"type": "object"},
"example": {"type": "string"},
"undo": {"type": "string"},
}
),
apply_cnt_composite,
),
]