sanctum-engine 0.2.0__tar.gz

sanctum_engine-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install (editable, with dev extras)
+        run: python -m pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      # Integration tests need a live Ollama server and are opt-in
+      # (SANCTUM_TEST_OLLAMA_URL); see CONTRIBUTING.md.
+      - name: Tests with coverage (integration excluded)
+        run: pytest -m "not integration" --cov=sanctum --cov-report=term

sanctum_engine-0.2.0/.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+# Build the mkdocs-material site and publish it to GitHub Pages.
+# One-time setup: repository Settings -> Pages -> Source: "GitHub Actions".
+
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package with docs extras
+        run: python -m pip install -e ".[docs]"
+
+      - name: Build site
+        run: mkdocs build
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

sanctum_engine-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,58 @@
+# Release to PyPI on version tags (v0.2.0, v1.0.0, ...).
+#
+# Uses PyPI *trusted publishing* — no API tokens stored in the repo.
+# One-time manual setup required:
+#
+#   1. On PyPI (pypi.org), open the `sanctum-engine` project (or use
+#      "Add a new pending publisher" before the first release) and add a
+#      trusted publisher with:
+#        - Owner:        zquintero246
+#        - Repository:   sanctum-engine
+#        - Workflow:     release.yml
+#        - Environment:  pypi
+#   2. On GitHub, create an environment named `pypi`
+#      (Settings -> Environments); optionally add required reviewers so a
+#      human approves every publish.
+#
+# After that: `git tag v0.2.0 && git push --tags` releases.
+
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install build
+          python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # required for PyPI trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

sanctum_engine-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv*/
+.coverage
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+site/
+*.sanctum-trace.json
+*.sanctum-trace.html

sanctum_engine-0.2.0/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+All notable changes to `sanctum-engine` are documented here. The format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
+project adheres to [Semantic Versioning](https://semver.org/) (see
+CONTRIBUTING.md for what counts as a breaking change pre-1.0).
+
+## [0.2.0] — 2026-07-14
+
+### Added
+- Production Oracle adapters, all optional (the core stays stdlib-only):
+  - `OpenAICompatibleOracle` (`[openai-compat]` extra): any
+    `/v1/chat/completions` server — Ollama `/v1`, llama-server, vLLM,
+    LM Studio — with OpenAI-format tools and SSE streaming.
+  - `LlamaCppOracle` (`[llamacpp]` extra): in-process GGUF inference, the
+    serverless option; grammar-backed tool calling where the chat format
+    supports it.
+  - `OracleError` family (`OracleConnectionError`, `OracleTimeoutError`,
+    `OracleResponseError`) with actionable messages.
+- Robust spell-calling for local 7-14B models:
+  - `PromptedSpellCalling` wrapper (schemas in the system prompt, calls
+    parsed from delimited blocks) with `"auto"` fallback when the
+    endpoint rejects tools.
+  - Repair layer applied to every spell call: tolerant JSON extraction
+    (fenced blocks, unbalanced braces, single quotes), correction
+    messages back to the Oracle for unknown Spells / invalid arguments,
+    bounded by `max_repair_rounds` before `SpellCallParseError`.
+  - `SpellCallRepaired` / `SpellCallRejected` Omens.
+- Resilience policies: `SigilPolicy` (per-attempt timeout, retries with
+  exponential backoff and jitter, selective `retry_on`, `on_error`
+  fallback Sigil), `SigilTimeoutError`, `SigilRetried` Omen, and the
+  reserved `__errors__` Conduit.
+- Wards middleware: `Ward` hooks (`before_sigil`, `after_sigil`,
+  `on_omen`, `on_compile`), `WardRejection` + `DeltaRejected` Omen, and
+  built-ins `AuditWard` (JSONL trail), `UsageWard` (token/call tally),
+  `RedactWard` (pattern masking before Seals and logs).
+- Local-first tracing: `TraceRecorder` (full `.sanctum-trace.json` per
+  Invocation), `render_trace()` self-contained HTML viewer, and the
+  `python -m sanctum.trace render` CLI; tracing overhead case added to
+  the benchmark.
+- Two-level test strategy: unit tests replay recorded fixtures through
+  `httpx.MockTransport`; opt-in integration tests against a live Ollama
+  (`SANCTUM_TEST_OLLAMA_URL`, `pytest -m integration`).
+- Packaging: extras `openai-compat`, `ollama`, `llamacpp`, `all`;
+  CONTRIBUTING.md; MIT LICENSE; CI and trusted-publishing release
+  workflows.
+
+### Changed
+- `OllamaOracle` rewritten on the native `/api/chat` endpoint via httpx
+  (`[ollama]` extra; previously stdlib urllib): native tool calling,
+  `keep_alive`, and `options` (temperature, num_ctx, ...).
+- `summon()` gained `spell_calling` ("native" / "prompted" / "auto"),
+  `max_repair_rounds`, and `wards`; Oracle `usage` counters are attached
+  to assistant messages.
+- The `all` extra excludes `llama-cpp-python` (needs a C toolchain);
+  install `[llamacpp]` explicitly for the in-process backend.
+
+## [0.1.0] — 2026-07-14
+
+### Added
+- Cyclic state-graph engine: `Ritual` builder and `Rite` executable plan,
+  compile-time validation, static fan-out edges, conditional edges with
+  `path_map`, cycles bounded by `recursion_limit`.
+- BSP superstep scheduler: concurrent frontier execution
+  (`asyncio.TaskGroup`), deterministic delta merging in Sigil insertion
+  order, fan-in "any" semantics, `SigilExecutionError` with sibling
+  cancellation.
+- State system: `AetherSchema` / `Conduit` with reducers (`overwrite`,
+  `append`, `add`, `merge_dict`, custom), `Annotated` sugar, runtime
+  schema validation naming the offending Sigil.
+- Persistence: `Seal` checkpoints per superstep, `Codex` stores
+  (`MemoryCodex`, `SqliteCodex`, optional `PostgresCodex`), resumption,
+  `interrupt()` human-in-the-loop, and time-travel from any Seal.
+- Streaming: `astream` with combinable modes (`updates`, `values`,
+  `omens`, `tokens`), typed timestamped Omens, Sigil `writer` injection
+  for live tokens, Flask/SSE example.
+- LLM layer: abstract `Oracle` + deterministic `ScriptedOracle`;
+  Grimoire: `Spell` / `@spell` (schema from type hints), `Tome` with the
+  AgentGrimoire directory convention; `summon()` ReAct loop built on the
+  public API.
+- Docs (`README`, `docs/architecture.md`), superstep-overhead benchmark,
+  98% core test coverage.

sanctum_engine-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,164 @@
+# Contributing to Sanctum
+
+The design rationale, execution model, trade-offs, and the full glossary
+live in [`docs/architecture.md`](docs/architecture.md) — read it before
+changing the core.
+
+## Engineering principles
+
+1. **Zero-dependency core**: the engine is Python stdlib only; extras
+   (HTTP, Postgres, in-process inference, docs) are optional modules with
+   lazy imports.
+2. **Local-first**: never assume a proprietary LLM API in the core.
+3. Everything public is **typed** and documented with dual docstrings
+   (metaphor first line, precise technical explanation below).
+4. **Every feature ships with tests**; tests script LLM behavior with
+   `ScriptedOracle` and never touch real models or live services.
+5. The **public API stays small and stable** (see Versioning below).
+6. **Async-first**: the engine is native asyncio; synchronous entry
+   points are thin wrappers.
+7. Spells load from directory trees by convention
+   (`Tome.load_from_directory`), keeping the tool library decoupled.
+
+## Setup
+
+```sh
+python -m venv .venv
+.venv/Scripts/activate          # Windows; use source .venv/bin/activate elsewhere
+pip install -e ".[dev]"
+```
+
+## Running the tests
+
+```sh
+pytest                          # unit suite — always green, no services needed
+pytest --cov=sanctum            # with core coverage
+python benchmarks/superstep_overhead.py
+```
+
+Unit tests never touch real models or servers: LLM behavior is scripted
+with `ScriptedOracle`, and the HTTP Oracle adapters are tested by
+replaying recorded responses (in `tests/fixtures/`) through
+`httpx.MockTransport`.
+
+## Integration tests (opt-in)
+
+The suite includes smoke tests against **live local model servers**,
+marked `@pytest.mark.integration` and skipped unless the matching
+environment variable is set:
+
+- `SANCTUM_TEST_OPENAI_COMPAT_URL` — exercises `OpenAICompatibleOracle`
+  and the robust tool-calling loop end-to-end against **any** server
+  exposing `/v1/chat/completions` (llama.cpp's `llama-server`, Ollama's
+  `/v1`, vLLM, LM Studio). Set it to the exact base URL, version prefix
+  included.
+- `SANCTUM_TEST_OLLAMA_URL` — exercises the native `OllamaOracle`
+  (`/api/chat`) against an Ollama daemon. Base URL without `/v1`.
+
+With llama.cpp's `llama-server` (any small instruct GGUF works):
+
+```sh
+llama-server -m qwen2.5-0.5b-instruct-q4_k_m.gguf --port 8080 -c 4096 --jinja
+
+# bash
+SANCTUM_TEST_OPENAI_COMPAT_URL=http://127.0.0.1:8080/v1 pytest -m integration
+
+# PowerShell
+$env:SANCTUM_TEST_OPENAI_COMPAT_URL = "http://127.0.0.1:8080/v1"
+pytest -m integration
+```
+
+With Ollama (`ollama serve` + `ollama pull qwen2.5:0.5b`), both adapters
+can run in one pass:
+
+```sh
+SANCTUM_TEST_OLLAMA_URL=http://127.0.0.1:11434 \
+SANCTUM_TEST_OPENAI_COMPAT_URL=http://127.0.0.1:11434/v1 \
+pytest -m integration
+```
+
+Model overrides: `SANCTUM_TEST_OLLAMA_MODEL` and
+`SANCTUM_TEST_OPENAI_COMPAT_MODEL` (both default `qwen2.5:0.5b`;
+`llama-server` ignores the name and serves whatever model it loaded).
+These tests assert transport, parsing, and loop survival against a real
+server — never model quality — so any chat-capable model works.
+
+## Style
+
+- `ruff check .` must pass (config in `pyproject.toml`; black-compatible
+  formatting, line length 88). CI runs it on every push and PR.
+- Code and docstrings in English. The metaphor appears in names and in
+  the first line of each docstring, followed by the precise technical
+  explanation — never instead of it.
+- Tone of the metaphor: classical occultism and alchemy — mystery and
+  precision. Avoid jokey copy, RPG/gamer aesthetics, pop-fantasy
+  references, and cartoonish names. Documentation is technically precise
+  first; the metaphor is identity, never a substitute for clarity.
+- Error messages must be actionable: name the endpoint/file involved and
+  state the most likely fix.
+
+### The two-layer naming policy
+
+Domain concepts use the glossary vocabulary (Ritual, Sigil, Aether,
+Conduit, Seal, Codex, Omen, Oracle, Spell, Tome, Ward, summon — full
+glossary with technical equivalences in
+[`docs/architecture.md`](docs/architecture.md) §8). Universal infrastructure stays
+technical and is never themed: `compile`, `invoke`, `ainvoke`, `astream`,
+`add_edge`, `add_conditional_edge`, `reducer`, `recursion_limit`,
+`interrupt`, START, END, superstep. Exceptions combine a domain name with
+a technical suffix (`RitualValidationError`, `SigilTimeoutError`,
+`SpellCallParseError`, ...). Don't invent new glossary terms or mystical
+synonyms for technical ones.
+
+## Commit convention
+
+Conventional Commits: `<type>(<scope>): <imperative summary>` where type
+is one of `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `chore` and
+scope is the subsystem (`ritual`, `aether`, `codex`, `omens`, `oracle`,
+`grimoire`, `wards`, `ci`). Examples:
+
+```
+feat(oracle): add OpenAI-compatible adapter with SSE streaming
+fix(ritual): count fallback supersteps toward recursion_limit
+docs(architecture): document fan-in trade-offs
+```
+
+Breaking changes add a `!` (`feat(ritual)!: ...`) and a `BREAKING CHANGE:`
+footer explaining the migration.
+
+## Versioning (SemVer)
+
+The **public API** is the contract (engineering principle 5):
+`Ritual`, `Rite`, `add_sigil`, `add_edge`, `add_conditional_edge`,
+`compile`, `invoke`/`ainvoke`, `astream`, `Codex` (and the `Seal` shape),
+`Tome`, `Oracle` (and `OracleResponse`/`SpellCall`), `summon` — plus the
+documented Omen types, `SigilPolicy`, `Ward` hooks, and the exception
+hierarchy exported from `sanctum`.
+
+A **breaking change** is anything that makes existing correct code fail
+or change meaning: removing/renaming those names, changing signatures or
+return shapes, changing documented semantics (delta merge order, Seal
+format, stream mode contents), or raising different exception types.
+
+While the project is pre-1.0: breaking changes bump the **minor** version
+(0.2.0 → 0.3.0) and are listed under a "Changed"/"Removed" heading in
+CHANGELOG.md with migration notes; everything else bumps the patch. From
+1.0.0 on, standard SemVer applies (breaking = major).
+
+## Releasing
+
+1. Update `CHANGELOG.md` (move Unreleased to the new version) and the
+   version in `pyproject.toml` + `sanctum/__init__.py`.
+2. Tag: `git tag vX.Y.Z && git push --tags`.
+3. `release.yml` builds with `python -m build` and publishes to PyPI via
+   **trusted publishing** — the one-time PyPI/GitHub setup is documented
+   at the top of `.github/workflows/release.yml`.
+
+## Scope guardrails
+
+Sanctum competes in the local-first niche, not on feature parity with
+larger frameworks. Priorities: reliability with local 7-14B models
+(including their tool-calling failure modes), developer experience, and
+observability without external services. Don't add advanced graph
+features without a concrete use case that demands them. Use-case code
+belongs in `examples/`, never in the core or the main docs.

sanctum_engine-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zabdiel Quintero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sanctum_engine-0.2.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: sanctum-engine
+Version: 0.2.0
+Summary: A minimal, local-first orchestration engine for AI agents: cyclic state graphs executed by supersteps (Pregel/BSP).
+Project-URL: Repository, https://github.com/zquintero246/sanctum-engine
+Project-URL: Documentation, https://github.com/zquintero246/sanctum-engine/blob/main/docs/architecture.md
+Project-URL: Changelog, https://github.com/zquintero246/sanctum-engine/blob/main/CHANGELOG.md
+Author: Zabdiel Quintero
+License: MIT
+License-File: LICENSE
+Keywords: agents,llama-cpp,llm,local-first,ollama,orchestration,pregel,state-graph
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: all
+Requires-Dist: httpx>=0.27; extra == 'all'
+Requires-Dist: psycopg>=3.1; extra == 'all'
+Requires-Dist: transformers>=4.40; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
+Provides-Extra: llamacpp
+Requires-Dist: llama-cpp-python>=0.3; extra == 'llamacpp'
+Provides-Extra: ollama
+Requires-Dist: httpx>=0.27; extra == 'ollama'
+Provides-Extra: openai-compat
+Requires-Dist: httpx>=0.27; extra == 'openai-compat'
+Provides-Extra: postgres
+Requires-Dist: psycopg>=3.1; extra == 'postgres'
+Provides-Extra: transformers
+Requires-Dist: transformers>=4.40; extra == 'transformers'
+Description-Content-Type: text/markdown
+
+# Sanctum
+
+[![CI](https://github.com/zquintero246/sanctum-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/zquintero246/sanctum-engine/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/sanctum-engine)](https://pypi.org/project/sanctum-engine/)
+[![coverage](https://img.shields.io/badge/coverage-94%25-6d8f6a)](https://github.com/zquintero246/sanctum-engine/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-b49b5e)](LICENSE)
+[![python](https://img.shields.io/pypi/pyversions/sanctum-engine)](pyproject.toml)
+
+*Where agents are summoned, bound, and set to work — a minimal, local-first
+orchestration engine for cyclic state graphs.*
+
+Sanctum models multi-agent orchestration as a ritual of invocation:
+knowledge lives in the Grimoire (tools), the Sanctum prepares and controls
+the ritual (the engine), entities are summoned (agents), and all of them
+cooperate over a shared energy — the Aether (state) — until a result is
+manifested. Beneath the metaphor sits a precise execution model: a **cyclic
+state graph** run by supersteps (Pregel/BSP), where nodes execute in
+parallel, return partial state deltas merged through per-channel reducers,
+and conditional edges close the loops that make agentic behavior
+(think → act → observe → …) possible. The core is pure Python standard
+library — no proprietary APIs, no mandatory dependencies — designed to run
+entirely on local models.
+
+**[Documentation](https://zquintero246.github.io/sanctum-engine/)** ·
+[Getting started](https://zquintero246.github.io/sanctum-engine/getting-started/) ·
+[Comparison with LangGraph / n8n / ADK](https://zquintero246.github.io/sanctum-engine/comparison/) ·
+[Design document](docs/architecture.md)
+
+![The self-contained trace viewer (illustration of render_trace output)](docs/assets/trace-viewer.svg)
+
+## Features
+
+| | |
+|---|---|
+| **Cyclic state graphs** | BSP supersteps, static fan-out, conditional edges, cycles bounded by `recursion_limit` — not a DAG |
+| **Deterministic state** | Per-Conduit reducers applied in Sigil insertion order; identical runs, even under parallelism |
+| **Local-first Oracles** | Ollama (native & `/v1`), llama-server, vLLM, LM Studio, in-process GGUF — never a proprietary API in the core |
+| **Robust tool-calling** | Malformed JSON repaired, unknown Spells corrected conversationally, prompted fallback for models without tools |
+| **Seals & time-travel** | JSON checkpoints per superstep (memory/SQLite/Postgres), resume, `interrupt()` human-in-the-loop, replay from any Seal |
+| **Streaming Omens** | Typed, timestamped events; combinable modes; live tokens from inside a Sigil |
+| **Resilience policies** | Per-Sigil timeout, retries with backoff+jitter, fallback Sigils reading `__errors__` |
+| **Wards middleware** | Transform or veto deltas, observe every event: audit JSONL, usage tally, redaction |
+| **Local tracing** | One-file HTML viewer, zero external requests: `python -m sanctum.trace render run.sanctum-trace.json` |
+| **Zero-dependency core** | Python stdlib only; everything else is an optional extra |
+
+## Quickstart
+
+```sh
+pip install sanctum-engine
+```
+
+```python
+from sanctum import END, Ritual
+
+ritual = Ritual()
+ritual.add_sigil("cleanse", lambda aether: {"text": aether["text"].strip()})
+ritual.add_sigil("transmute", lambda aether: {"text": aether["text"].upper()})
+ritual.set_entry_point("cleanse")
+ritual.add_edge("cleanse", "transmute")
+ritual.add_edge("transmute", END)
+
+rite = ritual.compile()
+print(rite.invoke({"text": "  fiat lux  "}))
+# {'text': 'FIAT LUX'}
+```
+
+## Summoning an Entity
+
+`summon()` builds the canonical ReAct loop (oracle → spells → oracle → …
+→ END) entirely on the public primitives:
+
+```python
+import asyncio
+from sanctum import Tome, spell, summon
+from sanctum.oracle.ollama import OllamaOracle   # pip install "sanctum-engine[ollama]"
+
+@spell
+def word_count(text: str) -> int:
+    """Count the words in a text."""
+    return len(text.split())
+
+entity = summon(
+    OllamaOracle(arcana="qwen2.5:7b"),
+    Tome([word_count]),
+    role="You are a scribe.",
+    spell_calling="auto",   # prompted fallback if the model lacks native tools
+)
+result = asyncio.run(entity.ainvoke(
+    {"messages": [{"role": "user", "content": "How many words in 'fiat lux'?"}]}
+))
+print(result["messages"][-1]["content"])
+```
+
+## Examples
+
+The [`examples/`](examples/) gallery runs on scripted oracles by default —
+no model required — and every script takes `--oracle ollama`:
+
+- [`quickstart_ollama.py`](examples/quickstart_ollama.py) — chat with a
+  tool in thirty lines.
+- [`research_ritual/`](examples/research_ritual/) — two entities scout in
+  parallel (fan-out), a third synthesizes (fan-in, append reducer).
+- [`human_in_the_loop/`](examples/human_in_the_loop/) — `interrupt()` +
+  Codex: pause for approval, resume where it stopped.
+- [`resilient_pipeline/`](examples/resilient_pipeline/) — retries,
+  timeouts, and a fallback Sigil in one observable run.
+- [`sse_flask.py`](examples/sse_flask.py) — bridge `astream` to
+  Server-Sent Events.
+
+## Ecosystem
+
+Sanctum owns execution; [AgentGrimoire](https://github.com/zquintero246/AgentGrimoire)
+owns capability — a folder-per-Spell tool library loadable by convention
+with `Tome.load_from_directory(path)`. Either side evolves without
+touching the other.
+
+## Development
+
+```sh
+pip install -e ".[dev]"
+ruff check . && pytest --cov=sanctum      # unit suite: no models, no services
+python benchmarks/superstep_overhead.py  # engine overhead: tens of µs/superstep
+```
+
+Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) (includes
+how to run the opt-in integration tests against a local Ollama) and the
+[design document](docs/architecture.md) for the rationale behind every
+trade-off. Licensed [MIT](LICENSE).