File size: 3,856 Bytes
e547dfd | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 | # 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
```mermaid
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](docs/PRODUCTION_HARDENING.md).
| Component | Contract |
|---|---|
| [RoutingPipeline](src/routing/pipeline.py) | Text/context to trace and expert dispatch result |
| [AgentDispatch](src/routing/dispatch.py) | Async expert callbacks returning dictionaries |
| [ReActAgent](src/agents/react.py) | Task entity and optional initial context to a reasoning/tool loop |
| [ToolRegistry](src/tools/registry.py) | Tool definitions, lookup, schemas, and policy metadata |
| [ContinuityManager](src/continuity/manager.py) | Synchronous state transitions and backend coordination |
| [WORMLedger](src/core/evidence.py) | Synchronous event append, scan, and chain checks |
| [HTTPBridge](src/bridge/http_server.py) | 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](research/sparse-routing/) 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](src/runtime/providers/multi.py) 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](src/runtime/machine/): bytecode/IR utilities, stack VM, native interop, and x86 code generation.
- [native/](native/): NASM sources and C dispatcher.
- [ide/CMakeLists.txt](ide/CMakeLists.txt): native Windows C/C++ client.
- [ide/desktop/](ide/desktop/): Electron/TypeScript workbench sources with separate package scripts.
- [ide/beam/](ide/beam/): WebAssembly experiments.
These layers are not interchangeable implementations of one validated executable. See [IDE](docs/IDE.md) and [Machine runtime](docs/MACHINE_CODE.md).
## Models and research
[src/models/](src/models/) contains recurrent memory, BURT-IMMA, checkpoint/pruning helpers, and text output modules. [hf/](hf/) provides model packaging and corpus schema artifacts. [training/](training/) provides the Swift corpus/swarm visualization library.
[cobalt/](cobalt/), [kernels/](kernels/), [magma/](magma/), [narm/](narm/), and [catn/](catn/) use their own compiler and runtime assumptions. Formal sources and manuscripts are under [research/](research/). Source presence, formal assumptions, compilation, and measured behavior must be reported separately.
## Further reading
Use the [documentation index](docs/README.md) for starter and technical guides. [Security](docs/SECURITY.md) describes enforcement boundaries; [Validation](docs/VALIDATION.md) records the checks actually performed.
|