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