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