Advanced Topics

Enabling the LLM Reasoning Engine

The reasoning module works out-of-the-box with rule-based heuristics. Adding an LLM unlocks deeper pattern analysis and autonomous pipeline generation.

Setup

cp .env.template .env

Edit .env with your provider:

# Option 1: Ollama (local, free, sovereign) — recommended
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3

# Option 2: NVIDIA NIM (free tier cloud)
LLM_PROVIDER=nvidia
NVIDIA_API_KEY=your_key_here

# Option 3: OpenAI (paid cloud fallback)
LLM_PROVIDER=openai
OPENAI_API_KEY=your_key_here

Restart the runtime. The reasoning engine will automatically detect the LLM and switch from rule-based to hybrid mode.

What Changes with LLM

Capability	Rule-based	LLM-backed
Pipeline quarantine	✅	✅
Metric logging	✅	✅
Pattern analysis	❌	✅
Autonomous pipeline generation	❌	✅
Memory synthesis	❌	✅
Natural language reasoning	❌	✅

The Full Module Catalog (20+)

The starter kit has four modules. The full SovCore platform adds:

Module	File	Tick Frequency	Role
💭 Pattern Synthesis	dreams.py	Every 20th tick	Offline pattern detection during idle
🧬 Versioning	dna.py	On boot	Pipeline version registry
🧪 Selection	genetics.py	On breed cycle	Pool management, tournament selection
🍳 Replicator	breeder.py	Every 50th tick	Evolutionary reproduction of pipelines
🌐 Federation	federation.py	Every 30th tick	Peer discovery, cross-runtime sharing
👀 File Watcher	perception.py	Every 5th tick	Codebase awareness, file change detection
🔍 Code Index	code_index.py	On boot	Anti-hallucination — indexes real codebase symbols
🧠 Embedding Engine	neural_cortex.py	Every 100th tick	Embedding backfill for semantic search
📊 Working Buffer	working_memory.py	Every tick	Short-term salience-gated buffer (capacity 64)
🎯 Reinforcement	reinforcement.py	On pipeline exec	Outcome ledger, reward/penalty tracking
📈 Growth Tracker	growth.py	Every 100th tick	Composite growth score, trajectory tracking
🎓 Skill Extractor	skills.py	Every ~36 maint	Skill crystallization from repeated success
🧩 Attention Filter	cognitive_biases.py	Every tick	Attention gating, priority-aware filtering
🦴 Invariant Guard	skeleton.py	Every tick	Structural invariant enforcement
🚔 Threat Scanner	immune_patrol.py	Every tick	Active threat hunting, anomaly sweeps
🔗 Knowledge Graph	cortex_graph.py	Every ~10 maint	Knowledge graph edges, clustering
🌉 Artifact Bridge	cortex_bridge.py	Every 3rd tick	Scans agent artifacts, publishes to shared store
🛡️ Pipeline Filter	bred_filters.py	On pipeline exec	Pre/post-compile whitelist for generated pipelines

Each module is a standalone Python file. Add them one at a time to your starter runtime.

Architecture

main.py              ← FastAPI entry point (boot/shutdown lifecycle)
runtime.py           ← The persistent runtime (scheduler + tick loop)
memory.py            ← Persistent memory engine
memory_api.py        ← REST API for memory access
reasoning.py         ← Hybrid decision engine (rules + optional LLM)
monitor.py           ← Pipeline health monitoring
pipeline_engine.py   ← Pipeline CRUD + sandboxed execution
sandbox.py           ← Static analysis + runtime restriction
llm_client.py        ← Optional LLM client (Ollama/NVIDIA/OpenAI)
sovereign_lang/      ← Sovereign Script compiler
  lexer.py           ← Tokenizer
  parser.py          ← Recursive descent parser → AST
  codegen.py         ← AST → Python code generator
pipelines/           ← Your .sov pipeline files
  hello_world.sov    ← Example pipeline

Security Warning

caution

The starter kit has no authentication. Do not expose it to the public internet without adding API key auth. The full engine ships with sovereign_auth.py — a production-grade bearer token system with trust tiers.

Running Tests

python -m pytest tests/ -v