vibe-sketcherDocumentation

Source code for vibesketcher.agent.mcp_symmetry_ops

"""MCP tools for adopting symmetry, enantiomorphs and subgroup descent (#199).

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


[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."} number = {"type": "number"} def base(arguments: dict[str, Any]) -> str: return f"periodic/{arguments['structure']}/symmetry" def pick(arguments: dict[str, Any], *keys: str) -> dict[str, Any]: return {k: arguments[k] for k in keys if k in arguments} def adopt_periodic_symmetry(arguments: dict[str, Any]) -> Any: if arguments.get("undo"): return edit(arguments, "POST", base(arguments) + "/undo", {}) options = pick(arguments, "symprec", "idealize", "diagnostic_symprec") preview = client.call( "POST", f"api/documents/{document_id(arguments)}/{base(arguments)}/adopt/preview", options, ) # fmt: skip if not arguments.get("apply"): return preview body = {**options, "source_sha256": preview["source_sha256"]} return edit(arguments, "POST", base(arguments) + "/adopt", body) def invert_periodic_structure(arguments: dict[str, Any]) -> Any: options = pick(arguments, "symprec", "diagnostic_symprec") if not arguments.get("identifier"): return client.call( "POST", f"api/documents/{document_id(arguments)}/{base(arguments)}/enantiomorph/preview", options, ) body = {**options, "identifier": arguments["identifier"]} return edit(arguments, "POST", base(arguments) + "/enantiomorph", body) def descend_periodic_subgroup(arguments: dict[str, Any]) -> Any: options = pick(arguments, "transformation", "subgroup", "symprec") if not arguments.get("identifier"): return client.call( "POST", f"api/documents/{document_id(arguments)}/{base(arguments)}/descend/preview", options, ) body = {**options, "identifier": arguments["identifier"]} return edit(arguments, "POST", base(arguments) + "/descend", body) def drop_periodic_displacements(arguments: dict[str, Any]) -> Any: body = {"reason": arguments["reason"]} return edit(arguments, "POST", base(arguments) + "/drop-displacements", body) return [ Tool( "drop_periodic_displacements", "Drop a periodic structure's measured anisotropic displacement tensors (from a " "CIF _atom_site_aniso loop) with a recorded reason; the dropped record is kept " "under provenance displacement_parameters_dropped. Supercells, primitive, " "conventional, standard, reduced and setting cells, slabs, defects, translations " "and rotations carry the tensors; cell strain, idealised standardisation and " "element changes on measured sites refuse until they are dropped with this tool.", _schema( { "document": document, "structure": {"type": "string"}, "reason": {"type": "string"}, }, ("structure", "reason"), ), # fmt: skip drop_periodic_displacements, ), Tool( "adopt_periodic_symmetry", "Preview (default) or apply=true adoption of the space group spglib detects at " "symprec (angstrom) as a 3-D structure's recorded symmetry: operations in the " "structure's own basis, the tabulated setting if it matches, orbits with Wyckoff " "letters, merges and splits against the previously recorded orbits, every site's " "symmetrisation displacement, the cell change, and sites near a special position at " "diagnostic_symprec (0.1 A). Nothing moves unless idealize=true (positions and " "metric symmetrised; displacement tensors too). The apply step is revision-checked " "against the preview's source digest; undo=true reverts the last adoption. " "Disordered and magnetic structures are refused.", _schema( { "document": document, "structure": {"type": "string"}, "symprec": number, "idealize": {"type": "boolean"}, "diagnostic_symprec": number, "apply": {"type": "boolean"}, "undo": {"type": "boolean"}, }, ("structure",), ), # fmt: skip adopt_periodic_symmetry, ), Tool( "invert_periodic_structure", "Invert a chiral 3-D structure through the origin (x -> -x) with its space group " "transformed, (R, t) -> (R, -t): an enantiomorphic pair changes type (P3_121 <-> " "P3_221, P4_1 <-> P4_3, P6_122 <-> P6_522, ...), other Sohncke groups keep theirs. " "Achiral structures, and ones achiral within diagnostic_symprec (ambiguous " "handedness), are refused. Without identifier it previews; with identifier it adds " "the new structure (bonds and displacement tensors carried). Undo with " "adopt_periodic_symmetry structure=<new id> undo=true.", _schema( { "document": document, "structure": {"type": "string"}, "identifier": {"type": "string"}, "symprec": number, "diagnostic_symprec": number, }, ("structure",), ), # fmt: skip invert_periodic_structure, ), Tool( "descend_periodic_subgroup", "Describe a 3-D structure in a subgroup H of its space group: transformation is " "the ITA setting (P, p), e.g. 'a,b,c' or '2a,2b,2c;0,0,0' or 'a-b,a+b,c;0,0,1/4', " "subgroup H's Hall or Hermann-Mauguin symbol in that basis. Every operation of H " "must be a symmetry in the new basis (verified by spglib detection). Reports the " "index with its t and k parts, the type (translationengleiche or klassengleiche; " "general subgroups are refused by Hermann's theorem), Wyckoff splitting of every " "parent orbit and the changed independent sites. Automatic enumeration of maximal " "subgroups is not offered yet. Without identifier it previews; with identifier it " "adds the new structure.", _schema( { "document": document, "structure": {"type": "string"}, "transformation": {"type": "string"}, "subgroup": {"type": "string"}, "identifier": {"type": "string"}, "symprec": number, }, ("structure", "transformation", "subgroup"), ), # fmt: skip descend_periodic_subgroup, ), ]