API.md [component] deterministic

Sovereign Intelligence Stack — API Documentation

**Version:** 1.0.0 **Last Updated:** July 5, 2026 **Repository:** [sovereign-intelligence-stack](https://github.com/kliewerdaniel/sovereign-intelligence-stack)

---

Overview

The Sovereign Intelligence Stack provides a unified API for capturing, routing, evaluating, and compounding AI decisions. This document describes the public API surface.

**Key Principles:** - Every interaction is captured as an immutable recipe - Recipes form a persistent knowledge graph - The system improves autonomously through evaluation loops - All components are designed for local-first operation

---

Core API

1. Recipe Compiler (src/recipe_compiler/)

**Purpose:** Capture AI interactions as immutable recipes.

**Key Classes:** - Recipe — Immutable AI decision record - RecipeStorage — SQLite-based recipe storage with FTS5 - RecipeAPI — FastAPI HTTP endpoints for ingestion

#### Recipe Dataclass

```python from src.recipe_compiler.models import Recipe

Create a recipe recipe = Recipe( objective="Explain quantum computing", model="qwen3.5", memory_version=1, evaluation_score=0.92, outcome="accepted", tags=["quantum", "explanation"] )

Access recipe data print(recipe.id) print(recipe.objective) print(recipe.evaluation_score) ```

#### RecipeStorage Class

```python from src.recipe_compiler.storage import RecipeStorage

Initialize storage storage = RecipeStorage("recipes.db")

Store a recipe recipe_id = storage.create_recipe(recipe)

Search recipes results = storage.search("quantum computing")

Update a recipe storage.update_recipe(recipe.id, evaluation_score=0.95)

Delete a recipe storage.delete_recipe(recipe.id) ```

#### RecipeAPI Endpoints

**POST /recipes** — Create a new recipe ``bash curl -X POST http://localhost:8000/recipes \ -H "Content-Type: application/json" \ -d '{ "objective": "Explain quantum computing", "model": "qwen3.5", "evaluation_score": 0.92, "outcome": "accepted" }'

**GET /recipes** — Search recipes ``bash curl "http://localhost:8000/recipes?q=quantum"

**GET /recipes/{id}** — Get a specific recipe ``bash curl "http://localhost:8000/recipes/recipe-20260705-123456-abc123"

**PUT /recipes/{id}** — Update a recipe ``bash curl -X PUT "http://localhost:8000/recipes/recipe-20260705-123456-abc123" \ -H "Content-Type: application/json" \ -d '{"evaluation_score": 0.95}'

**DELETE /recipes/{id}** — Delete a recipe ``bash curl -X DELETE "http://localhost:8000/recipes/recipe-20260705-123456-abc123"

---

2. Signal Router (src/signal_router/)

**Purpose:** Classify incoming tasks and route them through optimal evaluation paths.

**Key Classes:** - SignalClassifier — Signal classification (cheap / expert / hybrid) - SignalRouter — Routing logic with evaluation path selection

#### SignalClassifier Class

```python from src.signal_router.classifier import SignalClassifier, SignalType

classifier = SignalClassifier()

Classify a signal signal_type = classifier.classify( objective="Explain quantum computing", context="user_query", available_models=["qwen3.5", "llama3.1", "gpt-4"] )

Check signal type if signal_type == SignalType.CHEAP: # Route to fast, lightweight model pass elif signal_type == SignalType.EXPERT: # Route to capable model with full context pass elif signal_type == SignalType.HYBRID: # Route to multi-stage evaluation pass ```

#### SignalRouter Class

```python from src.signal_router.router import SignalRouter

router = SignalRouter()

Route a signal routing_result = router.route( signal_type=SignalType.CHEAP, available_models=["qwen3.5"], context="user_query" )

Get routing recommendations print(routing_result.recommended_model) print(routing_result.evaluation_path) ```

---

3. Evaluation Loop (src/evaluation/)

**Purpose:** Autonomous self-improvement through continuous test generation and drift detection.

**Key Classes:** - EvaluationLoop — Autonomous evaluation loop - DriftDetector — Signal drift detection - TestGenerator — Synthetic test case generation

#### EvaluationLoop Class

```python from src.evaluation.loop import EvaluationLoop

loop = EvaluationLoop()

Run evaluation loop results = loop.run( recipes=recipe_storage.search("quantum"), evaluation_metrics=["accuracy", "completeness", "relevance"] )

Get evaluation summary print(results.summary())

Get drift alerts print(results.drift_alerts) ```

#### DriftDetector Class

```python from src.evaluation.drifter import DriftDetector

detector = DriftDetector()

Detect drift drift_report = detector.detect_drift( old_recipes=recipe_storage.search("quantum", limit=100), new_recipes=recipe_storage.search("quantum", limit=100) )

Check if drift occurred if drift_report.drift_detected: print(f"Drift detected: {drift_report.drift_score}") print(f"Drift type: {drift_report.drift_type}") ```

---

4. Knowledge Systems (src/knowledge/, src/memory/)

**Purpose:** Persistent knowledge representation combining graph and memory systems.

**Key Classes:** - GraphStore — NetworkX-based knowledge graph - VectorStore — ChromaDB-based vector embeddings - MemoryStorage — SQLite-based memory storage - MemoryManager — Memory lifecycle with relevance scoring

#### GraphStore Class

```python from src.knowledge.graph_store import GraphStore

graph = GraphStore()

Add nodes graph.add_node("quantum_computing", type="concept", importance=0.8) graph.add_node("qubit", type="concept", importance=0.7)

Add edges graph.add_edge("quantum_computing", "qubit", relation="uses")

Query graph subgraph = graph.get_subgraph("quantum_computing", depth=2) print(subgraph.nodes) print(subgraph.edges) ```

#### VectorStore Class

```python from src.knowledge.vector_store import VectorStore

store = VectorStore("chroma.db")

Add documents store.add_documents([