vibe-sketcherDocumentation

Source code for vibesketcher.agent.mcp_figures

"""MCP tools for cyclic-topology schematics, multi-panel figures, figure math and diagrams (#247).

Each tool is a call to the REST routes in :mod:`vibesketcher.server.figures`;
:func:`tools` is joined to the list in :func:`vibesketcher.agent.mcp.make_tools`.
Figures come back as SVG text.
"""

from __future__ import annotations

from collections.abc import Callable
from typing import Any

from vibesketcher.agent.client import RestClient
from vibesketcher.agent.mcp import Tool, _schema

_OPTIONS = (
    "options = {axes [0] | [0, 1] (needed in 3D), atoms, bonds, seams, unrolled, "
    "cell_labels, elevation_deg 10-80, aspect 1.5-6, atom_scale, width (pt), font_size (pt), "
    "title ($...$ math), caption}"
)


[docs] def tools(client: RestClient, document_id: Callable[[dict[str, Any]], str]) -> list[Tool]: document = {"type": "string", "description": "Document id; the open document when left out."} def cyclic_topology_figure(arguments: dict[str, Any]) -> Any: options = arguments.get("options", {}) if arguments.get("record") is not None: content, _ = client.raw( "POST", "api/periodic/topology", {"record": arguments["record"], "options": options, "format": "svg"}, ) # fmt: skip else: if not arguments.get("structure") or not arguments.get("repeats"): raise ValueError("give structure and repeats, or an AICCM record") content, _ = client.raw( "POST", f"api/documents/{document_id(arguments)}/periodic/" f"{arguments['structure']}/topology", {"repeats": arguments["repeats"], "options": options, "format": "svg"}, ) return {"format": "svg", "svg": content.decode("utf-8")} def compose_figure_panels(arguments: dict[str, Any]) -> Any: body = {"panels": arguments.get("panels", []), "options": arguments.get("options", {}), "format": "svg"} # fmt: skip content, _ = client.raw("POST", "api/figures/panels", body) return {"format": "svg", "svg": content.decode("utf-8")} def figure_math(arguments: dict[str, Any]) -> Any: body = {"text": arguments.get("text", ""), "format": "svg"} if "size" in arguments: body["size"] = arguments["size"] content, _ = client.raw("POST", "api/figures/math", body) return {"format": "svg", "svg": content.decode("utf-8")} def figure_diagram(arguments: dict[str, Any]) -> Any: content, _ = client.raw( "POST", "api/figures/diagram", {"spec": arguments.get("spec", {}), "format": "svg"} ) return {"format": "svg", "svg": content.decode("utf-8")} return [ Tool("cyclic_topology_figure", "SVG schematic of a cyclic cluster's topology: a ring " "(one periodic axis) or a projected torus (two) with the cells as a grid, the atoms " "on it, the identified seams and the wrap-around bonds in the accent colour, beside " "the unrolled sheet (true geometry, opposite edges marked). Give structure and " "repeats [n1, n2, n3], or record = an AICCM convention record " f"(vibesketcher.aiccm-record/1). {_OPTIONS}. The model is not changed; the torus " "is not to scale.", _schema({"document": document, "structure": {"type": "string"}, "repeats": {"type": "array", "items": {"type": "integer"}}, "record": {"type": "object"}, "options": {"type": "object"}}), cyclic_topology_figure), Tool("compose_figure_panels", "One labelled multi-panel SVG from figure SVGs: panels = " "[{svg, caption ($...$ math), angstrom_per_unit}] in reading order, labelled (a), " "(b), ... in that order. options = {columns 1-6, column single (85 mm) | double " "(178 mm), width_mm, gap_mm, labels (a)|a|a)|(A)|A|none, label_size_pt, label_bold, " "caption_size_pt, scale fit|uniform|angstrom, scale_bar_angstrom, max_height_mm, " "title}. Panel SVG with scripts, images, external references or style sheets is " "refused.", _schema({"panels": {"type": "array", "items": {"type": "object"}}, "options": {"type": "object"}}, ("panels",)), compose_figure_panels), Tool("figure_math", "Render one figure string as a tight SVG: plain text with $...$ " "math holding sub/superscripts (_ ^ with braces), Greek letters (\\alpha ... " "\\Omega), \\times \\cdot \\pm \\leq \\geq \\neq \\approx \\infty \\partial \\sum " "\\int \\AA, \\frac{a}{b}, \\overline{x}, \\mathrm{...}; anything else is refused " "with the reason. GET api/figures/math lists the subset.", _schema({"text": {"type": "string"}, "size": {"type": "number"}}, ("text",)), figure_math), Tool("figure_diagram", "SVG workflow or taxonomy diagram from spec = {schema " "'vibesketcher.diagram/1', layout layered (workflows, Sugiyama) | tree (taxonomies) " "| manual, direction down | right, nodes [{id, label ($...$ math, up to 4 lines " "split by newlines), group, position [x, y] pt (pins it), shape rounded|box|plain, " "fill, stroke, min_width, bold}], edges [{source, target, label, style " "solid|dashed, arrow, colour}], groups [{id, label, stroke, fill}], font_size, " "layer_gap, node_gap, padding, width_pt, title}. Connectors are computed from the " "boxes. At most 120 nodes; overlapping boxes, unknown ids, self-loops and a second " "parent in a tree are refused. GET api/figures/diagram/schema gives the schema.", _schema({"spec": {"type": "object"}}, ("spec",)), figure_diagram), ] # fmt: skip