vibe-sketcherDocumentation

Source code for vibesketcher.agent.mcp_polymer_packing

"""MCP tools for amorphous polymer boxes and membranes (#205).

Each tool is a call to the REST routes in
:mod:`vibesketcher.server.polymer_packing`; :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

_PACKING_HELP = (
    "packing = {identifier, units {LABEL: {smiles (two * markers, [*:1] head [*:2] tail) | "
    "template (a polymer template ID) | generic (a bracketed generic drawn in the document)}}, "
    "chains [{unit | sequence [LABEL...] | composition {LABEL: fraction} with arrangement "
    "random|alternating|block, count, length | lengths [n per chain], tacticity isotactic|"
    "syndiotactic|atactic (required when a unit has a backbone stereocentre), head/tail end "
    "groups 'H' or a SMILES with one * (e.g. '*C'), label}], seed, cell {kind box "
    "(lengths_angstrom [a,b,c] | density_g_cm3) | membrane (lateral_angstrom [a,b], "
    "thickness_angstrom | density_g_cm3, vacuum_angstrom)}, torsion_states [{angle_deg, "
    "weight}] (default trans 1, gauche +-60 0.5), torsion_jitter_deg, radii vdw|covalent, "
    "radius_overrides, collision_scale (0.6), max_attempts, step_retries, max_backtracks, "
    "max_regrowths, on_exhausted refuse|partial, excluded [{lower, upper} fractional boxes], "
    "crosslinking {chemistry, conversion} (refused: not implemented)}"
)


[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 preview_polymer_packing(arguments: dict[str, Any]) -> Any: return client.call( "POST", f"api/documents/{document_id(arguments)}/periodic/polymer/preview", {"packing": arguments.get("packing", {})}, ) def apply_polymer_packing(arguments: dict[str, Any]) -> Any: if arguments.get("undo"): return edit( arguments, "POST", "periodic/polymer/undo", {"structure": arguments["undo"]} ) return edit( arguments, "POST", "periodic/polymer", {"packing": arguments.get("packing", {})} ) return [ Tool( "preview_polymer_packing", "Preview an amorphous polymer box or membrane grown from stated repeat units " f"as a derived periodic model; the document is unchanged. {_PACKING_HELP}. Returns " "the packed and requested chain counts, attempts, backtracks, regrowths and " "rejected placements by cause, each chain's sequence, tacticity (meso diad " "fraction), end groups and formula, the checks (one component per chain, no " "interchain bonds, RDKit valence, bond-image lengths, stoichiometry, unrelaxed " "density) and refusals with stable codes (polymer.budget_exhausted, " "polymer.tacticity_unstated, ...). An unrelaxed packing is not an equilibrated " "morphology.", _schema({"document": document, "packing": {"type": "object"}}, ("packing",)), preview_polymer_packing, ), Tool( "apply_polymer_packing", "Add a previewed polymer packing to the document (revision-checked; refused while " "the preview has refusals). undo=<packed ID> removes a packed model again while " "it is unchanged.", _schema( {"document": document, "packing": {"type": "object"}, "undo": {"type": "string"}} ), apply_polymer_packing, ), ]