vibe-sketcherDocumentation
Source code for vibesketcher.agent.mcp_periodic_recipes
"""MCP tools for periodic scan, phonon and free-energy recipes and EOS fits (#208).
Each tool is a call to the REST routes in
:mod:`vibesketcher.server.periodic_recipes`; :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
_RECIPE_HELP = (
"recipe: {kind: volume_scan, structure, spec (vibe-qc periodic job spec: model pbc|seccm|"
"aiccm|mace, method, basis, jk, kpoints {kind gamma|gamma-centred|monkhorst-pack, mesh}, "
"max_iter), volume_fractions (>= 5, V/V_input), relax none|positions, formula_units?} | "
"{kind: coordinate_scan, structure, spec, coordinate distance|angle, sites (2 or 3 site "
"IDs, angle vertex in the middle), values (A or degrees), moving (site IDs; default the "
"last), relax none|positions} | {kind: phonons, structure, spec, supercell [n1,n2,n3], "
"displacement_angstrom (0.01), q_mesh, masses {El: amu}} | {kind: free_energy, structure, "
"spec, approximation harmonic|quasi-harmonic, temperatures_k, pressures_gpa, "
"volume_fractions, phonons?}."
)
[docs]
def tools(client: RestClient, document_id: Callable[[dict[str, Any]], str]) -> list[Tool]:
from vibesketcher.agent.mcp import Tool, _schema
document = {"type": "string", "description": "Document id; the open document when left out."}
def capabilities(arguments: dict[str, Any]) -> Any:
result: dict[str, Any] = client.call("GET", "api/periodic/recipes/capabilities")
task, model = arguments.get("task"), arguments.get("model")
result["capabilities"] = [
r for r in result["capabilities"]
if (not task or r["task"] == task) and (not model or r["model"] == model)
] # fmt: skip
return result
def plan(arguments: dict[str, Any]) -> Any:
return client.call(
"POST",
f"api/documents/{document_id(arguments)}/periodic/recipes/plan",
{"recipe": arguments["recipe"]},
)
def analyse(arguments: dict[str, Any]) -> Any:
body = {k: arguments[k] for k in ("table", "plan", "results", "qvfs",
"drop_unconverged", "svg", "title") if k in arguments} # fmt: skip
return client.call("POST", "api/periodic/recipes/eos", body)
return [
Tool("periodic_capabilities", "The pinned vibe-qc engine's periodic capability table: "
"for each task (energy, forces, relax_positions, relax_positions_frozen, stress, "
"relax_cell, hessian, phonons, ir_intensities, free_energy) and model (pbc, "
"seccm, aiccm, mace) whether it is admitted, library-only or refused, the entry "
"point and the owning issue. A model name not listed is not an admission.",
_schema({"task": {"type": "string"}, "model": {"type": "string"}}),
capabilities),
Tool("plan_periodic_recipe", "Plan a periodic recipe against the document without "
"changing it: one vibe-qc input per point plus run_all.py and the plan (fixed "
"k-mesh, convergence, normalisation per formula unit, units). Phonon and "
"free-energy plans come back with status refused and an engine-refusal report "
"(periodic Hessians fail closed) and, for free energies, the omitted terms; a "
"molecular Gamma Hessian is never a phonon spectrum. " + _RECIPE_HELP,
_schema({"document": document, "recipe": {"type": "object"}}, ("recipe",)), plan),
Tool("analyse_eos", "Fit third-order Birch-Murnaghan (Birch 1947) and Vinet (Vinet et "
"al. 1987) forms to a volume scan: table {schema: vibe-eos-table/1, formula, "
"formula_units, points [{volume_angstrom3, energy_hartree (per cell), "
"converged}]} or plan (from plan_periodic_recipe) with results "
"(scan-results.json) and/or qvfs {label: base64}. Returns V0, E0, B0 (GPa), B0' "
"per formula unit with poor-fit flags; svg true adds the E(V) plot.",
_schema({"table": {"type": "object"}, "plan": {"type": "object"},
"results": {"type": "object"}, "qvfs": {"type": "object"},
"drop_unconverged": {"type": "boolean"}, "svg": {"type": "boolean"},
"title": {"type": "string"}}), analyse),
] # fmt: skip