sanctum-engine 0.2.0__py3-none-any.whl

sanctum/__init__.py

@@ -0,0 +1,66 @@
+"""Sanctum — the chamber where rituals of invocation are prepared and performed.
+
+A minimal, local-first orchestration engine for AI agents. Sanctum executes
+cyclic state graphs by supersteps (Pregel/BSP model): Sigils (nodes) run in
+parallel over a shared Aether (state), their partial deltas are merged through
+each Conduit's reducer, and conditional edges decide the next active set until
+END or the recursion limit is reached.
+"""
+
+from sanctum.aether import AetherSchema, AetherValidationError, Conduit
+from sanctum.codex import Codex, Seal, SealError
+from sanctum.grimoire import (
+    Spell,
+    SpellCallParseError,
+    SpellExecutionError,
+    Tome,
+    spell,
+    summon,
+)
+from sanctum.oracle import Oracle
+from sanctum.ritual import (
+    END,
+    START,
+    Interrupt,
+    RecursionLimitError,
+    Rite,
+    Ritual,
+    RitualValidationError,
+    SigilExecutionError,
+    SigilPolicy,
+    SigilTimeoutError,
+    interrupt,
+)
+from sanctum.wards import Ward, WardRejection
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "END",
+    "START",
+    "AetherSchema",
+    "AetherValidationError",
+    "Codex",
+    "Conduit",
+    "Interrupt",
+    "Oracle",
+    "RecursionLimitError",
+    "Rite",
+    "Ritual",
+    "RitualValidationError",
+    "Seal",
+    "SealError",
+    "SigilExecutionError",
+    "SigilPolicy",
+    "SigilTimeoutError",
+    "Spell",
+    "SpellCallParseError",
+    "SpellExecutionError",
+    "Tome",
+    "Ward",
+    "WardRejection",
+    "__version__",
+    "interrupt",
+    "spell",
+    "summon",
+]

sanctum/aether/__init__.py

@@ -0,0 +1,23 @@
+"""Aether — the shared energy all invoked entities draw upon.
+
+Shared state management. The Aether is a typed dict whose channels are
+Conduits, each declaring a reducer (overwrite, append, add, merge_dict, or
+custom) that merges the partial deltas returned by Sigils. An AetherSchema
+defines the Conduits available to a Ritual.
+"""
+
+from sanctum.aether.core import Aether, AetherSchema, Conduit
+from sanctum.aether.errors import AetherValidationError
+from sanctum.aether.reducers import Reducer, add, append, merge_dict, overwrite
+
+__all__ = [
+    "Aether",
+    "AetherSchema",
+    "AetherValidationError",
+    "Conduit",
+    "Reducer",
+    "add",
+    "append",
+    "merge_dict",
+    "overwrite",
+]

sanctum/aether/core.py

@@ -0,0 +1,166 @@
+"""The Conduits are drawn: the shape the shared energy must take.
+
+State schema. A Conduit declares how one key of the Aether merges deltas
+(its reducer); an AetherSchema is the complete set of Conduits a Ritual
+operates on. When a Ritual has a schema, every delta key must name a
+declared Conduit and is merged through that Conduit's reducer instead of
+plain overwrite.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Annotated, Any, get_args, get_origin, get_type_hints
+
+from sanctum.aether.errors import AetherValidationError
+from sanctum.aether.reducers import Reducer, overwrite
+
+Aether = dict[str, Any]
+"""The shared state dict, keyed by Conduit name."""
+
+
+@dataclass(frozen=True, slots=True)
+class Conduit:
+    """One channel of the Aether and the way it merges new energy.
+
+    Declares the reducer ``(current, update) -> new`` applied when a
+    Sigil's delta writes to this key. Defaults to `overwrite`. The reducer
+    is skipped when the key is not yet present in the Aether: the delta
+    value is set directly, so custom reducers never receive a missing
+    current value.
+    """
+
+    reducer: Reducer = overwrite
+
+
+def _as_conduit(value: Conduit | Any) -> Conduit:
+    """Coerce a schema declaration into a Conduit.
+
+    Accepts a Conduit instance, an ``Annotated[T, reducer]`` (the first
+    callable metadata item becomes the reducer), or any plain type
+    (overwrite). Types themselves are not enforced at runtime; the schema
+    governs keys and reducers.
+    """
+    if isinstance(value, Conduit):
+        return value
+    if get_origin(value) is Annotated:
+        for item in get_args(value)[1:]:
+            if callable(item):
+                return Conduit(reducer=item)
+    return Conduit()
+
+
+class AetherSchema:
+    """The declared shape of the shared energy.
+
+    Maps each Aether key to its Conduit. Values in the constructor mapping
+    may be Conduit instances, ``Annotated[T, reducer]`` forms, or plain
+    types (which default to overwrite):
+
+        AetherSchema({
+            "messages": Conduit(reducer=append),
+            "score": Annotated[int, add],
+            "verdict": str,
+        })
+
+    Delta application is deterministic: within a superstep, deltas are
+    applied in Sigil insertion order (the order Sigils were bound to the
+    Ritual), and each key merges through its Conduit's reducer.
+    """
+
+    def __init__(self, conduits: Mapping[str, Conduit | Any]) -> None:
+        self._conduits: dict[str, Conduit] = {
+            name: _as_conduit(value) for name, value in conduits.items()
+        }
+
+    @classmethod
+    def from_class(cls, source: type) -> AetherSchema:
+        """Read the Conduits from a class's annotations.
+
+        Sugar for declaring the schema as an annotated class::
+
+            class ChantAether:
+                messages: Annotated[list, append]
+                score: int  # plain annotation -> overwrite
+
+        ``Annotated[T, reducer]`` fields use the first callable metadata
+        item as the Conduit's reducer.
+        """
+        hints = get_type_hints(source, include_extras=True)
+        return cls(hints)
+
+    @property
+    def conduits(self) -> dict[str, Conduit]:
+        """A copy of the mapping from Aether key to its Conduit."""
+        return dict(self._conduits)
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._conduits
+
+    def validate_input(self, input: Mapping[str, Any]) -> None:
+        """Check that the initial Aether only uses declared Conduits.
+
+        Raises:
+            AetherValidationError: If `input` contains keys not declared in
+                the schema.
+        """
+        unknown = sorted(set(input) - set(self._conduits))
+        if unknown:
+            raise AetherValidationError(
+                f"Invocation input contains unknown Conduit(s): "
+                f"{', '.join(unknown)}; declared Conduits: "
+                f"{', '.join(sorted(self._conduits)) or '(none)'}."
+            )
+
+    def apply_delta(
+        self, aether: Mapping[str, Any], delta: Mapping[str, Any], *, sigil: str
+    ) -> Aether:
+        """Merge one Sigil's delta into the Aether through the Conduits.
+
+        Each delta key must name a declared Conduit; its value merges via
+        the Conduit's reducer, or is set directly when the key is not yet
+        present. Returns a new dict; `aether` is not mutated.
+
+        Args:
+            aether: Current state.
+            delta: Partial update returned by the Sigil.
+            sigil: Name of the Sigil that produced the delta, for error
+                attribution.
+
+        Raises:
+            AetherValidationError: If the delta writes to a key not
+                declared in the schema; the message names the Sigil.
+        """
+        merged: Aether = dict(aether)
+        for key, update in delta.items():
+            if key not in self._conduits:
+                raise AetherValidationError(
+                    f"Sigil '{sigil}' wrote to unknown Conduit '{key}'; "
+                    f"declared Conduits: "
+                    f"{', '.join(sorted(self._conduits)) or '(none)'}."
+                )
+            if key in merged:
+                merged[key] = self._conduits[key].reducer(merged[key], update)
+            else:
+                merged[key] = update
+        return merged
+
+    def apply_deltas(
+        self,
+        aether: Mapping[str, Any],
+        deltas: Sequence[tuple[str, Mapping[str, Any]]],
+    ) -> Aether:
+        """Merge one superstep's deltas into the Aether, deterministically.
+
+        Deltas are applied strictly in the order given as ``(sigil_name,
+        delta)`` pairs; the engine passes them in Sigil insertion order
+        (the order Sigils were bound to the Ritual). This makes concurrent
+        writes to the same Conduit within a superstep deterministic: the
+        Conduit's reducer folds each delta in, in that fixed order.
+        Returns a new dict; `aether` is not mutated.
+        """
+        merged: Aether = dict(aether)
+        for sigil, delta in deltas:
+            merged = self.apply_delta(merged, delta, sigil=sigil)
+        return merged

sanctum/aether/errors.py

@@ -0,0 +1,13 @@
+"""The ways the Aether rejects what does not belong to it.
+
+Exceptions raised by the Aether layer.
+"""
+
+
+class AetherValidationError(Exception):
+    """Energy tried to flow outside the declared Conduits.
+
+    Raised at invocation time when a Sigil's delta — or the initial input —
+    writes to a key not declared in the AetherSchema. The message names the
+    offending Sigil (when one is involved) and the unknown key.
+    """

sanctum/aether/reducers.py

@@ -0,0 +1,43 @@
+"""How new energy folds into each Conduit of the Aether.
+
+Built-in reducers. A reducer is any callable ``(current, update) -> new``
+that merges a Sigil's delta value into a Conduit's current value:
+`overwrite` (the default) replaces, `append` concatenates lists, `add` sums
+numbers, and `merge_dict` shallow-merges dicts. Any custom callable with
+the same signature is a valid reducer. Reducers are only called when the
+Conduit already holds a value; a delta to a missing key sets it directly.
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+Reducer = Callable[[Any, Any], Any]
+"""A Conduit's merge function: ``(current, update) -> new value``."""
+
+
+def overwrite(current: Any, update: Any) -> Any:
+    """Replace the current value with the update (the default reducer)."""
+    return update
+
+
+def append(current: list[Any], update: list[Any]) -> list[Any]:
+    """Concatenate the update list after the current list.
+
+    The delta value must be a list of items to append (wrap single items).
+    Returns a new list; neither input is mutated.
+    """
+    return list(current) + list(update)
+
+
+def add(current: Any, update: Any) -> Any:
+    """Sum the update into the current value (numeric accumulation)."""
+    return current + update
+
+
+def merge_dict(current: dict[str, Any], update: dict[str, Any]) -> dict[str, Any]:
+    """Shallow-merge the update dict over the current dict.
+
+    Keys present in both take the update's value. Returns a new dict;
+    neither input is mutated.
+    """
+    return {**current, **update}

sanctum/codex/__init__.py

@@ -0,0 +1,21 @@
+"""Codex — the ledger where every step of the ritual is inscribed.
+
+Persistence and checkpointing. A Seal is the snapshot of the Aether taken at
+the end of each superstep; a Codex stores and retrieves Seals per Invocation
+(execution session, keyed by `invocation_id`). Implementations: MemoryCodex,
+SqliteCodex, and PostgresCodex (optional extra, lazy imports; import it
+explicitly from `sanctum.codex.postgres`).
+"""
+
+from sanctum.codex.core import Codex, Seal
+from sanctum.codex.errors import SealError
+from sanctum.codex.memory import MemoryCodex
+from sanctum.codex.sqlite import SqliteCodex
+
+__all__ = [
+    "Codex",
+    "MemoryCodex",
+    "Seal",
+    "SealError",
+    "SqliteCodex",
+]

sanctum/codex/core.py

@@ -0,0 +1,60 @@
+"""Seals — the wax impressions each superstep leaves behind.
+
+Checkpoint model and storage contract. A Seal is the snapshot written at
+the end of a superstep: the full Aether, the frontier of the next
+superstep, the superstep number, a timestamp, and free-form metadata. A
+Codex stores Seals per Invocation (keyed by `invocation_id`) and yields
+them back to enable resumption, human-in-the-loop pauses, and time-travel.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class Seal:
+    """The wax impression of one superstep.
+
+    Immutable checkpoint. `aether` is the full state after the superstep's
+    deltas were applied; `frontier` the Sigils active in the *next*
+    superstep — resumption continues from it; `superstep` the 1-based
+    count within the Invocation; `timestamp` epoch seconds; `metadata`
+    free-form context (e.g. interrupt details). `seal_id` uniquely
+    identifies the Seal for time-travel.
+    """
+
+    aether: dict[str, Any]
+    frontier: list[str]
+    superstep: int
+    timestamp: float = field(default_factory=time.time)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    seal_id: str = field(default_factory=lambda: uuid.uuid4().hex)
+
+
+class Codex(ABC):
+    """The ledger where Seals are inscribed and consulted.
+
+    Abstract async storage contract for Seals, keyed by `invocation_id`.
+    Histories are append-only: resuming an Invocation appends new Seals
+    after the old ones, and `get` returns the most recently written Seal
+    (not the highest superstep number). Implementations: MemoryCodex
+    (ephemeral, for tests), SqliteCodex (local file), PostgresCodex
+    (optional extra, `sanctum.codex.postgres`).
+    """
+
+    @abstractmethod
+    async def put(self, invocation_id: str, seal: Seal) -> None:
+        """Append a Seal to the Invocation's history."""
+
+    @abstractmethod
+    async def get(self, invocation_id: str) -> Seal | None:
+        """Return the Invocation's most recently written Seal, or None."""
+
+    @abstractmethod
+    async def list(self, invocation_id: str) -> list[Seal]:
+        """Return the Invocation's full Seal history, oldest first."""

sanctum/codex/errors.py

@@ -0,0 +1,14 @@
+"""The ways the ledger refuses an inscription or a consultation.
+
+Exceptions raised by the Codex layer.
+"""
+
+
+class SealError(Exception):
+    """A Seal could not be written, found, or restored.
+
+    Raised when persistence fails (e.g. the Aether is not
+    JSON-serializable for a storage backend) or when resumption cannot
+    proceed: no Codex attached, no Seals recorded for the Invocation, or an
+    unknown `seal_id`.
+    """

sanctum/codex/memory.py

@@ -0,0 +1,33 @@
+"""A Codex written in breath: it fades when the session ends.
+
+In-memory Seal store, the reference implementation for tests and
+ephemeral invocations. Not shared across processes and not persistent.
+"""
+
+from __future__ import annotations
+
+from sanctum.codex.core import Codex, Seal
+
+
+class MemoryCodex(Codex):
+    """Ephemeral in-memory ledger of Seals.
+
+    Stores histories in a plain dict keyed by `invocation_id`. Intended
+    for tests and short-lived local runs; contents vanish with the object.
+    """
+
+    def __init__(self) -> None:
+        self._seals: dict[str, list[Seal]] = {}
+
+    async def put(self, invocation_id: str, seal: Seal) -> None:
+        """Append a Seal to the Invocation's history."""
+        self._seals.setdefault(invocation_id, []).append(seal)
+
+    async def get(self, invocation_id: str) -> Seal | None:
+        """Return the Invocation's most recently written Seal, or None."""
+        history = self._seals.get(invocation_id)
+        return history[-1] if history else None
+
+    async def list(self, invocation_id: str) -> list[Seal]:
+        """Return the Invocation's full Seal history, oldest first."""
+        return list(self._seals.get(invocation_id, ()))

sanctum/codex/postgres.py

@@ -0,0 +1,164 @@
+"""A Codex kept in a distant archive: PostgreSQL.
+
+Durable Seal store for multi-process or remote deployments. This is an
+optional module: it requires the `psycopg` (v3) driver, declared as the
+``postgres`` extra (``pip install sanctum-engine[postgres]``). The import
+is lazy — importing this module never fails; instantiating PostgresCodex
+without psycopg installed raises ImportError with install instructions.
+
+Same contract and limitation as SqliteCodex: the Aether, frontier, and
+metadata are stored as JSONB, so every value must be JSON-serializable.
+
+Schema (created automatically on first use):
+
+    CREATE TABLE IF NOT EXISTS seals (
+        id BIGSERIAL PRIMARY KEY,
+        seal_id TEXT NOT NULL UNIQUE,
+        invocation_id TEXT NOT NULL,
+        superstep INTEGER NOT NULL,
+        aether JSONB NOT NULL,
+        frontier JSONB NOT NULL,
+        timestamp DOUBLE PRECISION NOT NULL,
+        metadata JSONB NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS seals_invocation_idx
+        ON seals (invocation_id, id);
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from sanctum.codex.core import Codex, Seal
+from sanctum.codex.errors import SealError
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS seals (
+    id BIGSERIAL PRIMARY KEY,
+    seal_id TEXT NOT NULL UNIQUE,
+    invocation_id TEXT NOT NULL,
+    superstep INTEGER NOT NULL,
+    aether JSONB NOT NULL,
+    frontier JSONB NOT NULL,
+    timestamp DOUBLE PRECISION NOT NULL,
+    metadata JSONB NOT NULL
+);
+CREATE INDEX IF NOT EXISTS seals_invocation_idx
+    ON seals (invocation_id, id);
+"""
+
+
+def _psycopg() -> Any:
+    """Import psycopg lazily, with install guidance on failure."""
+    try:
+        import psycopg
+    except ImportError as exc:
+        raise ImportError(
+            "PostgresCodex requires the optional dependency 'psycopg'; "
+            "install it with: pip install sanctum-engine[postgres]"
+        ) from exc
+    return psycopg
+
+
+class PostgresCodex(Codex):
+    """Durable PostgreSQL ledger of Seals.
+
+    Persists Seals via async psycopg connections opened per operation
+    against `dsn` (e.g. ``postgresql://user:pass@host/db``). The schema is
+    created on first use. Requires JSON-serializable Aether and metadata.
+    """
+
+    def __init__(self, dsn: str) -> None:
+        _psycopg()  # fail fast, with guidance, if the driver is missing
+        self._dsn = dsn
+        self._schema_ready = False
+
+    async def _connect(self) -> Any:
+        """Open an async connection, creating the schema on first use."""
+        connection = await _psycopg().AsyncConnection.connect(self._dsn)
+        if not self._schema_ready:
+            await connection.execute(_SCHEMA)
+            await connection.commit()
+            self._schema_ready = True
+        return connection
+
+    async def put(self, invocation_id: str, seal: Seal) -> None:
+        """Append a Seal to the Invocation's history.
+
+        Raises:
+            SealError: If the Seal's Aether, frontier, or metadata cannot
+                be serialized to JSON.
+        """
+        try:
+            aether = json.dumps(seal.aether)
+            frontier = json.dumps(seal.frontier)
+            metadata = json.dumps(seal.metadata)
+        except (TypeError, ValueError) as exc:
+            raise SealError(
+                f"Seal '{seal.seal_id}' of Invocation '{invocation_id}' is "
+                f"not JSON-serializable: {exc}. PostgresCodex requires the "
+                "Aether and metadata to hold only JSON-serializable values."
+            ) from exc
+        connection = await self._connect()
+        try:
+            await connection.execute(
+                "INSERT INTO seals (seal_id, invocation_id, superstep, "
+                "aether, frontier, timestamp, metadata) "
+                "VALUES (%s, %s, %s, %s, %s, %s, %s)",
+                (
+                    seal.seal_id,
+                    invocation_id,
+                    seal.superstep,
+                    aether,
+                    frontier,
+                    seal.timestamp,
+                    metadata,
+                ),
+            )
+            await connection.commit()
+        finally:
+            await connection.close()
+
+    async def get(self, invocation_id: str) -> Seal | None:
+        """Return the Invocation's most recently written Seal, or None."""
+        connection = await self._connect()
+        try:
+            cursor = await connection.execute(
+                "SELECT seal_id, superstep, aether, frontier, timestamp, "
+                "metadata FROM seals WHERE invocation_id = %s "
+                "ORDER BY id DESC LIMIT 1",
+                (invocation_id,),
+            )
+            row = await cursor.fetchone()
+        finally:
+            await connection.close()
+        return _row_to_seal(row) if row is not None else None
+
+    async def list(self, invocation_id: str) -> list[Seal]:
+        """Return the Invocation's full Seal history, oldest first."""
+        connection = await self._connect()
+        try:
+            cursor = await connection.execute(
+                "SELECT seal_id, superstep, aether, frontier, timestamp, "
+                "metadata FROM seals WHERE invocation_id = %s "
+                "ORDER BY id ASC",
+                (invocation_id,),
+            )
+            rows = await cursor.fetchall()
+        finally:
+            await connection.close()
+        return [_row_to_seal(row) for row in rows]
+
+
+def _row_to_seal(row: tuple[Any, ...]) -> Seal:
+    """Rehydrate a Seal from a seals-table row."""
+    seal_id, superstep, aether, frontier, timestamp, metadata = row
+    return Seal(
+        aether=aether if isinstance(aether, dict) else json.loads(aether),
+        frontier=frontier if isinstance(frontier, list) else json.loads(frontier),
+        superstep=superstep,
+        timestamp=timestamp,
+        metadata=metadata if isinstance(metadata, dict) else json.loads(metadata),
+        seal_id=seal_id,
+    )