README.md [component] deterministic

Sovereign Intelligence Stack

> Intelligence is not the model. Intelligence is the accumulated decisions that shaped the model.

A self-improving AI infrastructure that captures, routes, evaluates, and compounds every AI decision into a persistent knowledge base — so your system gets smarter over time, not just faster.

**Status:** Production-ready — 70 files, 9,246 lines of Python, 26/26 modules verified (100%), comprehensive benchmark suite included.

Philosophy

Most AI systems treat each interaction as stateless. This stack inverts that: **every decision, every failure, every successful pattern is captured as an immutable recipe**. These recipes form a growing knowledge graph that enables the system to route new tasks more intelligently, evaluate its own performance autonomously, and phase into increasing autonomy.

┌─────────────────────────────────────────────────────────┐ │ Intelligence Layer │ │ Context Engineering │ Apprenticeship Engine │ Orchestration │ ├─────────────────────────────────────────────────────────┤ │ Layer 5: Intelligence Observatory │ │ Timeline │ Pattern Detection │ Reporting │ ├─────────────────────────────────────────────────────────┤ │ Layer 4: Knowledge Systems │ │ Graph Store │ Persistent Memory │ GraphRAG │ ├─────────────────────────────────────────────────────────┤ │ Layer 3: Evaluation Loop │ │ Signal Drift │ Test Generation │ Autonomous │ ├─────────────────────────────────────────────────────────┤ │ Layer 2: Signal Router │ │ Classification │ Routing Logic │ Signal Types │ ├─────────────────────────────────────────────────────────┤ │ Layer 1: Recipe Compiler │ │ Immutable Recipes │ SQLite FTS5 │ Relationships │ ├─────────────────────────────────────────────────────────┤ │ Integration Layer │ │ SovereignPipeline │ └─────────────────────────────────────────────────────────┘

Architecture

Layer 1: Recipe Compiler Captures AI interactions as immutable recipes — the foundational memory unit.

src/recipe_compiler/ ├── models.py # Recipe dataclass (objective, model, outcome, score, tags) ├── schema.py # SQLite schema with FTS5 full-text search ├── storage.py # CRUD operations, relationships, search └── api.py # FastAPI HTTP endpoints for ingestion

**Key design choices:** - Recipes are immutable by default — updates tracked via updated_at and version fields - FTS5 enables fast semantic search across all captured decisions - Relationships link recipes to documents, tags, and reasoning patterns - Version tracking for models, prompts, and memory snapshots

Layer 2: Signal Router Classifies incoming tasks and routes them through optimal evaluation paths.

src/signal_router/ ├── classifier.py # Signal classification (cheap / expert / hybrid) └── router.py # Routing logic with evaluation path selection

**Signal types:** - **Cheap** — Simple tasks routed to fast, lightweight models - **Expert** — Complex tasks routed to capable models with full context - **Hybrid** — Tasks that benefit from multi-stage evaluation

Layer 3: Evaluation Loop Autonomous self-improvement through continuous test generation and drift detection.

src/evaluation/ ├── definitions.py # Signal registry with drift detection ├── generator.py # Synthetic test case generation ├── drifter.py # Signal drift detection └── loop.py # Autonomous evaluation loop

Layer 4: Knowledge Systems Persistent knowledge representation combining graph and memory systems.

``` src/knowledge/ ├── graph_store.py # NetworkX-based knowledge graph ├── vector_store.py # ChromaDB-based vector embeddings (optional) └── graphrag.py # Hybrid retrieval combining graph + vector search

src/memory/ ├── storage.py # SQLite-based memory storage └── management.py # Memory lifecycle with relevance scoring ```

Layer 5: Intelligence Observatory Generates intelligence timelines and detects emerging patterns.

src/observatory/ ├── timeline.py # Intelligence timeline generation ├── detectors.py # Pattern detection (errors, drift, optimization) ├── reporter.py # Report generation └── visualizer.py # Timeline visualization (HTML/JSON)

Apprenticeship Engine Phased autonomy — the system progresses through 5 levels as it gains confidence.

src/apprentice/ ├── stages.py # Autonomy levels: supervised → assisted → monitored → semi-independent → fully independent └── trainer.py # Scaffolded training with example management

Context Engineering Systematic context management with templates, optimization, and analysis.

src/context/ ├── engineering.py # Context templates with variable rendering ├── optimization.py # Context optimization based on performance ├── analysis.py # Context effectiveness analysis └── templates.py # Pre-built context templates

Orchestration Multi-agent coordination with lifecycle management.

src/orchestration/ ├── manager.py # Agent lifecycle management ├── communication.py # Inter-agent communication ├── synchronization.py # State synchronization └── monitoring.py # Performance monitoring

Integration Layer Ties all layers together into a unified pipeline.

src/integration/ └── pipe.py # SovereignPipeline — connects all layers end-to-end

Quick Start

Install

bash cd sovereign-intelligence-stack python -m venv .venv source .venv/bin/activate pip install -e .

Run the Demo

bash python examples/sovereign_stack_demo.py

This simulates 30 days of AI agent activity — capturing 120 recipes, building a knowledge graph of 125+ nodes, sto