synkit 1.6.5__py3-none-win_amd64.whl

synkit/Mechanism/schema.py

@@ -0,0 +1,264 @@
+"""Small, dependency-free JSON-schema view of the v2 public record."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .model import SCHEMA_VERSION
+
+
+def mechanism_record_schema() -> dict[str, Any]:
+    """Return the frozen draft-1 JSON schema used by public serializers."""
+    return {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "title": "SynKit MechanismRecord",
+        "type": "object",
+        "required": ["schema_version", "mapped_reaction", "steps"],
+        "properties": {
+            "schema_version": {"const": SCHEMA_VERSION},
+            "mapped_reaction": {"type": "string", "pattern": ">>"},
+            "steps": {
+                "type": "array",
+                "items": {"$ref": "#/$defs/mechanisticStep"},
+            },
+            "provenance": {"type": "object"},
+            "metadata": {"type": "object"},
+            "endpoint_stereo": {
+                "type": "object",
+                "properties": {
+                    "reactant": {"$ref": "#/$defs/stereoRegistry"},
+                    "product": {"$ref": "#/$defs/stereoRegistry"},
+                },
+                "additionalProperties": False,
+            },
+        },
+        "additionalProperties": False,
+        "$defs": {
+            "electronLocus": {
+                "type": "object",
+                "required": ["locus", "atom_maps"],
+                "properties": {
+                    "locus": {"enum": ["lp", "σ", "π", "∙"]},
+                    "atom_maps": {
+                        "type": "array",
+                        "items": {"type": "integer", "minimum": 1},
+                        "minItems": 1,
+                        "maxItems": 2,
+                    },
+                },
+                "additionalProperties": False,
+            },
+            "electronMove": {
+                "type": "object",
+                "required": [
+                    "source",
+                    "target",
+                    "electron_count",
+                    "arrow_type",
+                    "group_id",
+                ],
+                "properties": {
+                    "event_id": {"type": ["string", "null"]},
+                    "source": {"$ref": "#/$defs/electronLocus"},
+                    "target": {"$ref": "#/$defs/electronLocus"},
+                    "electron_count": {"enum": [1, 2]},
+                    "arrow_type": {"enum": ["fishhook", "curved"]},
+                    "group_id": {"type": "string", "minLength": 1},
+                    "coupling_id": {"type": ["string", "null"]},
+                    "metadata": {"type": "object"},
+                },
+                "additionalProperties": False,
+            },
+            "electronMoveGroup": {
+                "type": "object",
+                "required": ["group_id", "moves"],
+                "properties": {
+                    "group_id": {"type": "string", "minLength": 1},
+                    "macro": {"type": ["string", "null"]},
+                    "moves": {
+                        "type": "array",
+                        "minItems": 1,
+                        "items": {"$ref": "#/$defs/electronMove"},
+                    },
+                    "metadata": {"type": "object"},
+                },
+                "additionalProperties": False,
+            },
+            "mechanisticStep": {
+                "type": "object",
+                "required": ["step_id", "groups"],
+                "properties": {
+                    "step_id": {"type": "string", "minLength": 1},
+                    "groups": {
+                        "type": "array",
+                        "items": {"$ref": "#/$defs/electronMoveGroup"},
+                    },
+                    "stereo_effects": {
+                        "type": "array",
+                        "items": {"$ref": "#/$defs/stereoEffect"},
+                    },
+                    "stereo_motions": {
+                        "type": "array",
+                        "items": {"$ref": "#/$defs/electrocyclicStereoMotion"},
+                    },
+                    "metadata": {"type": "object"},
+                },
+                "additionalProperties": False,
+            },
+            "stereoDescriptor": {
+                "type": "object",
+                "required": [
+                    "descriptor_class",
+                    "atoms",
+                    "parity",
+                    "state",
+                    "provenance",
+                ],
+                "properties": {
+                    "descriptor_class": {
+                        "enum": [
+                            "tetrahedral",
+                            "square_planar",
+                            "trigonal_bipyramidal",
+                            "octahedral",
+                            "planar_bond",
+                            "atrop_bond",
+                            "unknown",
+                        ]
+                    },
+                    "atoms": {
+                        "type": "array",
+                        "items": {
+                            "anyOf": [
+                                {"type": "integer"},
+                                {
+                                    "type": "string",
+                                    "pattern": "^@(H|LP):-?[0-9]+$",
+                                },
+                            ]
+                        },
+                    },
+                    "parity": {"type": ["integer", "null"], "enum": [-1, 0, 1, None]},
+                    "state": {
+                        "enum": ["specified", "unknown", "unspecified", "absent"]
+                    },
+                    "provenance": {"type": ["string", "null"]},
+                },
+                "additionalProperties": False,
+            },
+            "electrocyclicStereoMotion": {
+                "type": "object",
+                "required": [
+                    "kind",
+                    "mode",
+                    "direction",
+                    "termini",
+                    "substituents",
+                    "terminal_motion",
+                    "pi_electrons",
+                    "activation",
+                    "provenance",
+                ],
+                "properties": {
+                    "kind": {"const": "ELECTROCYCLIC"},
+                    "mode": {"enum": ["CONROTATORY", "DISROTATORY"]},
+                    "direction": {"enum": ["RING_CLOSURE", "RING_OPENING"]},
+                    "termini": {
+                        "type": "array",
+                        "items": {"type": "integer", "minimum": 1},
+                        "minItems": 2,
+                        "maxItems": 2,
+                        "uniqueItems": True,
+                    },
+                    "substituents": {
+                        "type": "array",
+                        "items": {
+                            "anyOf": [
+                                {"type": "integer", "minimum": 1},
+                                {
+                                    "type": "string",
+                                    "pattern": "^@(H|LP):-?[0-9]+$",
+                                },
+                            ]
+                        },
+                        "minItems": 2,
+                        "maxItems": 2,
+                    },
+                    "terminal_motion": {
+                        "type": "array",
+                        "items": {"enum": [-1, 1]},
+                        "minItems": 2,
+                        "maxItems": 2,
+                    },
+                    "pi_electrons": {
+                        "type": "integer",
+                        "minimum": 2,
+                        "multipleOf": 2,
+                    },
+                    "activation": {"enum": ["THERMAL", "PHOTOCHEMICAL", None]},
+                    "provenance": {"type": "string"},
+                },
+                "additionalProperties": False,
+            },
+            "stereoEffect": {
+                "type": "object",
+                "required": [
+                    "descriptor_target",
+                    "effect",
+                    "before",
+                    "after",
+                    "provenance",
+                ],
+                "properties": {
+                    "descriptor_target": {
+                        "type": "array",
+                        "prefixItems": [
+                            {"enum": ["atom", "bond"]},
+                            {
+                                "oneOf": [
+                                    {"type": "integer", "minimum": 1},
+                                    {
+                                        "type": "array",
+                                        "items": {"type": "integer", "minimum": 1},
+                                        "minItems": 2,
+                                        "maxItems": 2,
+                                        "uniqueItems": True,
+                                    },
+                                ]
+                            },
+                        ],
+                        "minItems": 2,
+                        "maxItems": 2,
+                    },
+                    "effect": {
+                        "enum": [
+                            "PRESERVE",
+                            "INVERT",
+                            "BREAK",
+                            "FORM",
+                            "FLEETING",
+                            "UNSPECIFIED",
+                        ]
+                    },
+                    "before": {
+                        "anyOf": [
+                            {"$ref": "#/$defs/stereoDescriptor"},
+                            {"type": "null"},
+                        ]
+                    },
+                    "after": {
+                        "anyOf": [
+                            {"$ref": "#/$defs/stereoDescriptor"},
+                            {"type": "null"},
+                        ]
+                    },
+                    "provenance": {"type": "string"},
+                },
+                "additionalProperties": False,
+            },
+            "stereoRegistry": {
+                "type": "object",
+                "additionalProperties": {"$ref": "#/$defs/stereoDescriptor"},
+            },
+        },
+    }

synkit/Mechanism/stereo_state.py

@@ -0,0 +1,416 @@
+"""Stepwise lifecycle validation for supplied relative stereochemistry."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+import hashlib
+import json
+from typing import Any, Mapping
+from typing import Iterable
+
+import networkx as nx
+
+from synkit.Graph.Stereo import (
+    classify_stereo_change,
+    descriptor_graph_support_errors,
+    stereo_from_dict,
+)
+
+from .model import StereoDescriptor, StereoEffect, VerificationIssue
+
+
+@dataclass(frozen=True)
+class StereoStateTimeline:
+    """Typed, checksum-bound mechanism stereo-state history."""
+
+    verification_mode: str
+    history: Mapping[str, tuple[Mapping[str, Any] | None, ...]]
+    proof_digest: str
+
+    @staticmethod
+    def _digest(payload: Mapping[str, Any]) -> str:
+        normalized = dict(payload)
+        normalized.pop("proof_digest", None)
+        encoded = json.dumps(
+            normalized,
+            ensure_ascii=True,
+            separators=(",", ":"),
+            sort_keys=True,
+        ).encode()
+        return hashlib.sha256(encoded).hexdigest()
+
+    @classmethod
+    def create(
+        cls,
+        states: Iterable[nx.Graph],
+        *,
+        verification_mode: str,
+    ) -> "StereoStateTimeline":
+        history = {
+            target: tuple(values) for target, values in stereo_timeline(states).items()
+        }
+        payload = {
+            "schema": "synkit.mechanism-stereo-timeline/1",
+            "verification_mode": verification_mode,
+            "history": {target: list(values) for target, values in history.items()},
+        }
+        return cls(
+            verification_mode,
+            history,
+            cls._digest(payload),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema": "synkit.mechanism-stereo-timeline/1",
+            "verification_mode": self.verification_mode,
+            "history": {
+                target: list(values) for target, values in sorted(self.history.items())
+            },
+            "proof_digest": self.proof_digest,
+        }
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> "StereoStateTimeline":
+        if value.get("schema") != "synkit.mechanism-stereo-timeline/1" or value.get(
+            "proof_digest"
+        ) != cls._digest(value):
+            raise ValueError("MECHANISM_STEREO_TIMELINE_TAMPERED")
+        return cls(
+            str(value["verification_mode"]),
+            {target: tuple(history) for target, history in value["history"].items()},
+            str(value["proof_digest"]),
+        )
+
+
+def descriptor_key(descriptor: StereoDescriptor) -> str:
+    if descriptor.descriptor_class in {
+        "tetrahedral",
+        "square_planar",
+        "trigonal_bipyramidal",
+        "octahedral",
+    }:
+        return f"atom:{descriptor.atoms[0]}"
+    if descriptor.descriptor_class in {"planar_bond", "atrop_bond"}:
+        return f"bond:{min(descriptor.atoms[2:4])}-{max(descriptor.atoms[2:4])}"
+    return "unknown"
+
+
+def stereo_effect_target_key(effect: StereoEffect) -> str:
+    """Return the registry key addressed by one validated stereo effect."""
+    kind, reference = effect.descriptor_target
+    if kind == "atom":
+        return f"atom:{reference}"
+    left, right = reference
+    return f"bond:{left}-{right}"
+
+
+def descriptor_support_errors(
+    graph: nx.Graph,
+    descriptor: StereoDescriptor,
+    *,
+    registry_key: str | None = None,
+) -> tuple[str, ...]:
+    """Return topology/resource reasons a descriptor is unsupported."""
+    if descriptor.descriptor_class == "unknown":
+        return ("unknown descriptor class has no executable locus",)
+    return descriptor_graph_support_errors(
+        graph,
+        stereo_from_dict(descriptor.to_dict()),
+        registry_key=registry_key,
+    )
+
+
+def descriptor_is_supported(
+    graph: nx.Graph,
+    descriptor: StereoDescriptor,
+    *,
+    registry_key: str | None = None,
+) -> bool:
+    return not descriptor_support_errors(
+        graph,
+        descriptor,
+        registry_key=registry_key,
+    )
+
+
+def _descriptor_identity(descriptor: StereoDescriptor) -> tuple[object, ...]:
+    if descriptor.descriptor_class == "unknown":
+        return ("unknown", descriptor.state)
+    native = stereo_from_dict(descriptor.to_dict())
+    return (descriptor.state, *native.canonical_form())
+
+
+def _descriptors_equal(
+    left: StereoDescriptor | None,
+    right: StereoDescriptor | None,
+) -> bool:
+    return (
+        left is None
+        and right is None
+        or (
+            left is not None
+            and right is not None
+            and _descriptor_identity(left) == _descriptor_identity(right)
+        )
+    )
+
+
+def _inverted(descriptor: StereoDescriptor) -> StereoDescriptor:
+    return descriptor.inverted()
+
+
+def _change_kind(
+    before: StereoDescriptor,
+    after: StereoDescriptor,
+) -> str:
+    """Classify relative stereo, including one mapped ligand replacement."""
+    return classify_stereo_change(
+        stereo_from_dict(before.to_dict()),
+        stereo_from_dict(after.to_dict()),
+    )
+
+
+def apply_stereo_effects(
+    graph: nx.Graph,
+    effects: Iterable[StereoEffect],
+    *,
+    step_id: str,
+) -> tuple[nx.Graph, tuple[VerificationIssue, ...]]:
+    """Apply declared effects without inferring reaction stereochemistry."""
+    result = deepcopy(graph)
+    registry = dict(result.graph.get("mechanism_stereo_descriptors", {}))
+    issues: list[VerificationIssue] = []
+    for effect in effects:
+        target = stereo_effect_target_key(effect)
+        present = registry.get(target)
+        code = effect.effect
+        if code in {"PRESERVE", "INVERT", "BREAK"} and present is None:
+            issues.append(
+                VerificationIssue(
+                    "STEREO_TRANSITION_FROM_ABSENT",
+                    f"{code} requires a present descriptor at {target}.",
+                    step_id=step_id,
+                )
+            )
+            continue
+        if code in {"PRESERVE", "INVERT", "BREAK"}:
+            if effect.before is None:
+                issues.append(
+                    VerificationIssue(
+                        "MISSING_STEREO_BEFORE",
+                        f"{code} requires the declared pre-step descriptor at {target}.",
+                        step_id=step_id,
+                    )
+                )
+                continue
+            if not _descriptors_equal(effect.before, present):
+                issues.append(
+                    VerificationIssue(
+                        "STEREO_BEFORE_MISMATCH",
+                        f"Declared stereo pre-state does not match {target}.",
+                        step_id=step_id,
+                        expected=present.to_dict() if present else None,
+                        observed=effect.before.to_dict(),
+                    )
+                )
+                continue
+        if code == "PRESERVE":
+            candidate = effect.after or present
+            if (
+                candidate is None
+                or _change_kind(present, candidate) != "RETAINED"
+                or not descriptor_is_supported(
+                    result,
+                    candidate,
+                    registry_key=target,
+                )
+            ):
+                issues.append(
+                    VerificationIssue(
+                        "INVALID_STEREO_PRESERVATION",
+                        f"Descriptor references are not valid after step {step_id}.",
+                        step_id=step_id,
+                    )
+                )
+            else:
+                registry[target] = candidate
+        elif code == "INVERT":
+            candidate = effect.after or _inverted(present)
+            if _change_kind(
+                present, candidate
+            ) != "INVERTED" or not descriptor_is_supported(
+                result,
+                candidate,
+                registry_key=target,
+            ):
+                issues.append(
+                    VerificationIssue(
+                        "INVALID_STEREO_INVERSION",
+                        f"Inverted descriptor is incomplete at {target}.",
+                        step_id=step_id,
+                    )
+                )
+            else:
+                registry[target] = candidate
+        elif code == "BREAK":
+            if effect.after is not None and effect.after.state != "absent":
+                issues.append(
+                    VerificationIssue(
+                        "INVALID_STEREO_BREAK",
+                        f"BREAK cannot retain an endpoint descriptor at {target}.",
+                        step_id=step_id,
+                    )
+                )
+                continue
+            registry.pop(target, None)
+        elif code == "FORM":
+            if present is not None:
+                issues.append(
+                    VerificationIssue(
+                        "STEREO_TRANSITION_FROM_PRESENT",
+                        f"FORM requires an absent descriptor at {target}.",
+                        step_id=step_id,
+                    )
+                )
+            elif effect.after is None or effect.after.state != "specified":
+                issues.append(
+                    VerificationIssue(
+                        "INCOMPLETE_STEREO_FORMATION",
+                        f"Specified formation requires a complete descriptor at {target}.",
+                        step_id=step_id,
+                    )
+                )
+            elif not descriptor_is_supported(
+                result,
+                effect.after,
+                registry_key=target,
+            ):
+                issues.append(
+                    VerificationIssue(
+                        "INVALID_STEREO_FORMATION",
+                        f"Formed descriptor references invalid topology at {target}.",
+                        step_id=step_id,
+                    )
+                )
+            else:
+                registry[target] = effect.after
+        elif code == "UNSPECIFIED":
+            unknown = effect.after or effect.before
+            if effect.before is not None and not _descriptors_equal(
+                effect.before,
+                present,
+            ):
+                issues.append(
+                    VerificationIssue(
+                        "STEREO_BEFORE_MISMATCH",
+                        f"Declared stereo pre-state does not match {target}.",
+                        step_id=step_id,
+                        expected=present.to_dict() if present else None,
+                        observed=effect.before.to_dict(),
+                    )
+                )
+            elif effect.before is None and present is not None:
+                issues.append(
+                    VerificationIssue(
+                        "MISSING_STEREO_BEFORE",
+                        f"UNSPECIFIED requires the present descriptor at {target}.",
+                        step_id=step_id,
+                    )
+                )
+            elif unknown is None:
+                issues.append(
+                    VerificationIssue(
+                        "INCOMPLETE_STEREO_FORMATION",
+                        f"UNSPECIFIED requires descriptor topology at {target}.",
+                        step_id=step_id,
+                    )
+                )
+            else:
+                candidate = StereoDescriptor(
+                    unknown.descriptor_class,
+                    unknown.atoms,
+                    None,
+                    "unknown",
+                    unknown.provenance,
+                )
+                if not descriptor_is_supported(
+                    result,
+                    candidate,
+                    registry_key=target,
+                ):
+                    issues.append(
+                        VerificationIssue(
+                            "INVALID_STEREO_FORMATION",
+                            f"Unknown descriptor references are invalid at {target}.",
+                            step_id=step_id,
+                        )
+                    )
+                    continue
+                registry[target] = StereoDescriptor(
+                    unknown.descriptor_class,
+                    unknown.atoms,
+                    None,
+                    "unknown",
+                    unknown.provenance,
+                )
+        elif code == "FLEETING":
+            if effect.before is not None and not _descriptors_equal(
+                effect.before,
+                present,
+            ):
+                issues.append(
+                    VerificationIssue(
+                        "STEREO_BEFORE_MISMATCH",
+                        f"Declared fleeting pre-state does not match {target}.",
+                        step_id=step_id,
+                    )
+                )
+        else:
+            issues.append(
+                VerificationIssue(
+                    "UNSUPPORTED_STEREO_EFFECT",
+                    f"Unsupported stereo effect {code!r}.",
+                    step_id=step_id,
+                )
+            )
+    for key, descriptor in tuple(registry.items()):
+        if not descriptor_is_supported(result, descriptor, registry_key=key):
+            registry.pop(key)
+            issues.append(
+                VerificationIssue(
+                    "UNDECLARED_STEREO_DESTRUCTION",
+                    f"Topology no longer supports descriptor {key}; declare BREAK or UNSPECIFIED.",
+                    step_id=step_id,
+                )
+            )
+    if issues:
+        return deepcopy(graph), tuple(issues)
+    result.graph["mechanism_stereo_descriptors"] = registry
+    return result, ()
+
+
+def stereo_timeline(states: Iterable[nx.Graph]) -> dict[str, list[dict | None]]:
+    """Return a rectangular descriptor-state history for MTG serialization."""
+    registries = [
+        state.graph.get("mechanism_stereo_descriptors", {}) for state in states
+    ]
+    keys = sorted({key for registry in registries for key in registry})
+    result = {}
+    for key in keys:
+        history = [
+            registry[key].to_dict() if key in registry else None
+            for registry in registries
+        ]
+        if (
+            history
+            and history[0] is None
+            and history[-1] is None
+            and any(history[1:-1])
+        ):
+            for value in history:
+                if value is not None:
+                    value["lifecycle"] = "FLEETING"
+        result[key] = history
+    return result