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