docs/GETTING_STARTED.md

Getting Started with Sovereign Engine

Welcome! This guide will get you running your first agent task in under 10 minutes.

Prerequisites

• Python 3.11 or higher — Check with: python --version
• No external dependencies — Everything uses Python stdlib (struct, hashlib, asyncio, etc.)
• Optional: NASM (for native assembly compilation)
• Optional: C compiler (for IPC core dispatcher)

Installation

Option 1: From Source

git clone https://github.com/SNAPKITTYWEST/sovereign-reverse.git
cd sovereign-reverse/engine
python -m pip install -e .

Option 2: Install Locally

cd /path/to/sovereign-reverse/engine
python -m pip install -e .

Verify Installation

python -c "from src.sovereign import SovereignEngine; print('OK')"

First Run: Hello World

Create a file hello.py:

import asyncio
from pathlib import Path
from src.sovereign import SovereignEngine, EngineConfig

async def main():
    # Create engine with default config
    config = EngineConfig(
        allowed_roots=[Path.cwd()],
        continuity_dir=Path.home() / ".sovereign" / "continuity"
    )
    engine = SovereignEngine(config)
    
    # Run a simple task
    result = await engine.run("write a Python function to calculate fibonacci(5)")
    print("\n" + "="*60)
    print("RESULT:")
    print("="*60)
    print(result)
    
    # Clean up
    engine.shutdown()

if __name__ == "__main__":
    asyncio.run(main())

Run it:

python hello.py

You should see output like:

2024-08-06 10:15:23,456 - sovereign.engine - INFO - SovereignEngine initialized
2024-08-06 10:15:23,478 - sovereign.engine - INFO - Starting task: write a Python function to calculate fibonacci(5)
...
============================================================
RESULT:
============================================================
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

print(fibonacci(5))  # Output: 5

Understanding the Output

WORM Seal

Every task execution is sealed in a Write-Once Read-Many (WORM) cryptographic ledger:

sovereign.worm                    # Binary append-only file (no text, no injection surface)
  └─ 152-byte header             # Magic + version + timestamps + Blake2b hash + Ed25519 sig
  └─ payload                     # Your task result (binary encoded)
  └─ metadata                    # Execution context (binary encoded)

Read the ledger:

from src.core.storage import WORMFile
from pathlib import Path

wf = WORMFile(Path("sovereign.worm"))
for record in wf.scan():
    print(f"Event: {record.event_type}")
    print(f"Timestamp: {record.timestamp_s}")
    print(f"Hash: {record.content_hash.hex()}")

Routing Weights

The engine routes tasks to multiple experts (specialized agents). Output shows which experts fired and their contribution:

Routing Decision:
  code_generation:    0.65        # 65% contribution
  error_checking:     0.28        # 28% contribution  
  documentation:      0.07        # 7% contribution

This is driven by Jordan algebra, not softmax:

• Non-associative grouping — expert topology matters
• Fixed-point convergence — stable routing attractors
• Spectral decomposition — provably unique expert selection

Continuity Directory

Agent state survives restarts across 4 paradigms:

~/.sovereign/continuity/
  └─ env_state.bin                # Paradigm 1: 64-bit env bitmask (hot-restart)
  └─ seed.bin                     # Paradigm 2: Blake2b seed for deterministic replay
  └─ inode/
  │   └─ agent_id.state           # Paradigm 3: Zero-byte files as boolean gates
  │   └─ agent_id.lock
  └─ shm_block.bin                # Paradigm 4: Shared memory (cross-process realtime)
  └─ checkpoints/
      └─ checkpoint_1.ckpt        # Full binary snapshot with signature
      └─ checkpoint_2.ckpt

Common First-Time Issues

Issue: "ModuleNotFoundError: No module named 'src.sovereign'"

Fix: Make sure you're in the engine directory and have run pip install -e .:

cd /path/to/sovereign-reverse/engine
python -m pip install -e .
python hello.py

Issue: "PermissionError: Cannot create continuity directory"

Fix: The engine needs to write to ~/.sovereign/continuity. Make sure it exists and is writable:

mkdir -p ~/.sovereign/continuity
chmod 700 ~/.sovereign/continuity

Or use a custom path:

config = EngineConfig(
    continuity_dir=Path("/tmp/my_continuity")
)

Issue: "ValueError: no signature in WORM record"

Fix: This is expected if no signing key is configured. The engine defaults to zero-signature (all bytes 0). To use real Ed25519 signing:

from src.core.crypto import generate_signing_key

key = generate_signing_key()
engine = SovereignEngine(config)
# engine will use key internally

Issue: "Timeout: task exceeded 30 seconds"

Fix: Increase the max step count or timeout in config:

from src.agents.react import ReActConfig

config = EngineConfig(
    max_steps=25  # More thinking steps
)
engine = SovereignEngine(config)

Or in individual agent config:

from src.agents.react import ReActAgent, ReActConfig

react_config = ReActConfig(max_steps=25, timeout_ms=60000)

Issue: "PathJail: denied /path/to/file"

Fix: The engine restricts filesystem access to allowed_roots. Add your path:

config = EngineConfig(
    allowed_roots=[
        Path("/home/user/projects"),
        Path("/tmp/scratch")
    ]
)

Next Steps

• CONFIGURATION.md — All EngineConfig options with defaults
• ROUTING.md — How the 11-stage pipeline works
• TOOLS.md — Complete tool inventory (34 tools)
• CONTINUITY.md — State recovery and replay
• SECURITY.md — PathJail, SSRFGuard, WORM verification

Production Checklist

Before shipping to production:

• Set up Ed25519 signing key (see SECURITY.md)
• Configure allowed_roots to restrict filesystem access
• Enable WORM ledger integrity checks (script in SECURITY.md)
• Set up continuity directory with proper permissions
• Test task recovery (kill agent mid-task, restart)
• Configure rate limits on destructive tools (see TOOLS.md)
• Enable shadow agent for async observation: enable_shadow=True
• Set appropriate model provider in config (Bedrock/OpenRouter/Ollama)