Architecture
Sovereign Engine v2 is a multi-language repository with several execution paths. The Python research router, engine task router, provider adapters, native runtimes, and desktop clients have distinct interfaces and validation scopes.
Python execution paths
flowchart TD
Runner[run.py] --> Routing[RoutingPipeline]
Runner --> Agent[ReActAgent]
Agent --> Model[Model interface]
Runner --> Bedrock[BedrockBackend]
Bridge[HTTPBridge] --> Multi[MultiProvider]
Bridge --> Registry[ToolRegistry]
Bridge --> BridgeAgent[Bridge ReActAgent]
Engine[SovereignEngine draft wiring] --> Routing
Engine --> Agent
Engine --> Continuity[ContinuityManager]
Engine --> Ledger[WORMLedger]
This diagram shows construction/call relationships in the source, not a successful end-to-end run. The unified engine and bridge agent paths contain interface mismatches described in deployment readiness.
| Component | Contract |
|---|---|
| RoutingPipeline | Text/context to trace and expert dispatch result |
| AgentDispatch | Async expert callbacks returning dictionaries |
| ReActAgent | Task entity and optional initial context to a reasoning/tool loop |
| ToolRegistry | Tool definitions, lookup, schemas, and policy metadata |
| ContinuityManager | Synchronous state transitions and backend coordination |
| WORMLedger | Synchronous event append, scan, and chain checks |
| HTTPBridge | HTTP handlers for provider chat, tools, keys, and routing traces |
Routing boundaries
The engine routes task text through parsing, symbolic/Jordan/Jacobian analysis, constraints, sparse activation, and dispatch. Its selected experts need real asynchronous implementations supplied by the caller.
The independent research router instead operates on a graph model. It measures synthetic edge costs and rank, proposes topology changes, verifies invariants, and commits accepted states. Its benchmark does not time the agent's LLM generation.
MultiProvider chooses a provider/model using task classification and fallback. This is distinct from the eleven-stage RoutingPipeline; /chat calls MultiProvider directly.
Native and desktop layers
- Python machine runtime: bytecode/IR utilities, stack VM, native interop, and x86 code generation.
- native/: NASM sources and C dispatcher.
- ide/CMakeLists.txt: native Windows C/C++ client.
- ide/desktop/: Electron/TypeScript workbench sources with separate package scripts.
- ide/beam/: WebAssembly experiments.
These layers are not interchangeable implementations of one validated executable. See IDE and Machine runtime.
Models and research
src/models/ contains recurrent memory, BURT-IMMA, checkpoint/pruning helpers, and text output modules. hf/ provides model packaging and corpus schema artifacts. training/ provides the Swift corpus/swarm visualization library.
cobalt/, kernels/, magma/, narm/, and catn/ use their own compiler and runtime assumptions. Formal sources and manuscripts are under research/. Source presence, formal assumptions, compilation, and measured behavior must be reported separately.
Further reading
Use the documentation index for starter and technical guides. Security describes enforcement boundaries; Validation records the checks actually performed.