| ``` |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| β β |
| β ⬑ F R A N K E N S T E I N β |
| β β |
| β βββββββββββββββββββββββββββββββββββββββββββββ β |
| β π§ BRAIN Β· π€² HANDS Β· 𦡠LEGS Β· Ξ© SEALED β |
| β Rust Tokio Β· AWS Bedrock Β· pgvector Β· vLLM β |
| β βββββββββββββββββββββββββββββββββββββββββββββ β |
| β β |
| β ⬑ Ξ© βΊ Ξ¨ Ξ Ξ Ξ£ Ξ¦ Ξ± β powered by BOB β |
| β β |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| ``` |
|
|
| sovereign-35 (FRANKENSTEIN) is a Rust Tokio web server implementing a three-stage sovereign AI workflow engine: a **Brain** (Claude Sonnet 4.6 via AWS Bedrock) that architects plans and injects Trust Deed governance, **Hands** (a Python FastAPI sidecar on port 5433 running FAISS + Neo4j + RDF + NetworkX + spaCy for corpus retrieval), and **Legs** (Devstral 123B via Bedrock, spawned in a Tokio `JoinSet` with a 120-second timeout, that executes the Brain's specification into working code). Every step is sealed with a running SHA-256 WORM chain. The server also exposes a **CODE BATTLE** mode that fires Claude Sonnet 4.6, Claude Opus 4.6, and Devstral 123B concurrently on the same prompt and returns all three answers side-by-side, plus an **ASK** mode for sovereign queries without the code path. The dark-terminal HTML UI renders at `http://localhost:4300`. Two binaries are compiled from the same codebase: `sovereign` (CLI REPL) and `frankenstein` (web server). |
|
|
| ## Architecture |
| **Version:** v1.0.0 |
|
|
|
|
| ```mermaid |
| sequenceDiagram |
| participant User |
| participant Web as Frankenstein Web<br/>:4300 (Axum) |
| participant Brain as BRAIN<br/>Claude Sonnet 4.6<br/>(Bedrock) |
| participant Hands as HANDS<br/>FastAPI :5433<br/>(FAISS+Neo4j+RDF) |
| participant Legs as LEGS<br/>Devstral 123B<br/>(Bedrock / Tokio JoinSet) |
| participant WORM as WORM Chain<br/>SHA-256 |
| |
| User->>Web: POST /workflow {prompt} |
| Web->>Brain: Trust Deed + architect spec |
| Brain-->>WORM: seal("BRAIN") |
| Brain-->>Web: architecture plan |
| |
| Web->>Hands: POST /retrieve {query, k=5} |
| Note over Hands: spaCy NLP β FAISS<br/>β Neo4j β RDF<br/>β NetworkX PageRank |
| Hands-->>WORM: seal("HANDS") |
| Hands-->>Web: ranked context |
| |
| alt is_code prompt |
| Web->>Legs: spec + context (JoinSet, 120s timeout) |
| Legs-->>WORM: seal("LEGS") |
| Legs-->>Web: implementation code |
| end |
| |
| Web->>Brain: review / merge / verdict |
| Brain-->>WORM: seal("REVIEW") |
| Brain-->>Web: PASS / PATCH / REJECT + notes |
| Web-->>User: WorkflowResponse {steps, final_out, worm} |
| ``` |
|
|
| ## File Tree |
| **Version:** v1.0.0 |
|
|
|
|
| ``` |
| sovereign-35/ |
| βββ src/ |
| β βββ main.rs # `sovereign` binary β CLI REPL (Tokio async, Lean4+Prolog+Tavily+DDG) |
| **Version:** v1.0.0 |
| |
| β βββ web.rs # `frankenstein` binary β Axum web server + HTML UI |
| **Version:** v1.0.0 |
| |
| β βββ inject/ |
| β β βββ trust_deed.rs # Trust Deed v1.0 system prompt (7 articles) + EmojiScript layer |
| **Version:** v1.0.0 |
| |
| β βββ models/ |
| β β βββ bedrock.rs # AWS Bedrock invocation (Claude + Devstral) |
| **Version:** v1.0.0 |
| |
| β β βββ vllm.rs # vLLM HTTP client (local Granite / Qwen) |
| **Version:** v1.0.0 |
| |
| β βββ tools/ |
| β β βββ tavily.rs # Tavily search API |
| **Version:** v1.0.0 |
| |
| β β βββ ddg.rs # DuckDuckGo fallback search |
| **Version:** v1.0.0 |
| |
| β βββ gates/ |
| β βββ lean4.rs # Lean 4 formal gate (Pass/Warn/Reject verdict) |
| **Version:** v1.0.0 |
| |
| β βββ prolog.rs # Prolog constraint engine |
| **Version:** v1.0.0 |
| |
| βββ hands/ |
| β βββ hands_server.py # FastAPI sidecar: FAISS+Neo4j+RDF+NetworkX+spaCy+NLTK |
| **Version:** v1.0.0 |
| |
| β βββ requirements.txt # Python dependencies |
| **Version:** v1.0.0 |
| |
| βββ Cargo.toml # Two binaries: sovereign + frankenstein |
| **Version:** v1.0.0 |
| |
| βββ .env # TAVILY_API_KEY, NEO4J_URI, etc. |
| **Version:** v1.0.0 |
| |
| ``` |
|
|
| ## Quick Start |
| **Version:** v1.0.0 |
|
|
|
|
| **Prerequisites:** Rust 1.78+, AWS credentials configured (`~/.aws/credentials`, region `us-east-1`), Python 3.10+ (for Hands sidecar) |
|
|
| ```bash |
| # Clone |
| **Version:** v1.0.0 |
| |
| git clone <repo> |
| cd sovereign-35 |
| |
| # Configure |
| **Version:** v1.0.0 |
| |
| cp .env.example .env # add TAVILY_API_KEY if you have one |
| **Version:** v1.0.0 |
| |
| |
| # Build both binaries |
| **Version:** v1.0.0 |
| |
| cargo build --release |
| |
| # ββ Run FRANKENSTEIN web server (recommended) ββββββββββββββββββ |
| **Version:** v1.0.0 |
| |
| cargo run --release --bin frankenstein |
| # β http://localhost:4300 |
| **Version:** v1.0.0 |
| |
| |
| # ββ Or run the CLI REPL βββββββββββββββββββββββββββββββββββββββ |
| **Version:** v1.0.0 |
| |
| cargo run --release --bin sovereign |
| |
| # ββ Optional: start the HANDS sidecar for corpus retrieval ββββ |
| **Version:** v1.0.0 |
| |
| cd hands |
| pip install -r requirements.txt |
| python hands_server.py |
| # β http://localhost:5433 |
| **Version:** v1.0.0 |
| |
| # Without hands: Frankenstein degrades gracefully (HANDS_OFFLINE) |
| **Version:** v1.0.0 |
| |
| ``` |
|
|
| **Models used (all via AWS Bedrock β no direct API keys):** |
|
|
| | Role | Model ID | |
| |---|---| |
| | Brain (architect + review) | `us.anthropic.claude-sonnet-4-6` | |
| | Battle: Opus | `us.anthropic.claude-opus-4-6-v1` | |
| | Legs / Battle: Code | `mistral.devstral-2-123b` | |
| | CLI code path | `Qwen/Qwen2.5-Coder-7B-Instruct` (vLLM) | |
|
|
| **Web API endpoints:** |
|
|
| | Method | Path | Description | |
| |---|---|---| |
| | GET | `/` | Dark terminal HTML UI | |
| | POST | `/workflow` | Full BrainβHandsβLegsβReview pipeline | |
| | POST | `/battle` | 3-way concurrent model comparison | |
| | POST | `/ask` | Sovereign query (Brain + Tavily, no code path) | |
| | GET | `/worm` | Current WORM chain hash + seal count | |
|
|
| ## Key Features |
| **Version:** v1.0.0 |
|
|
|
|
| - **BRAIN β HANDS β LEGS pipeline** β Claude Sonnet 4.6 architects, pgvector corpus retrieves context, Devstral 123B implements code; all stages independently WORM-sealed |
| - **Tokio JoinSet Legs execution** β Legs runs as an independent async task with a configurable timeout (120s); Brain never blocks waiting for Legs; graceful `LEGS_TIMEOUT` on miss |
| - **CODE BATTLE mode** β fires Frankenstein (Sonnet 4.6 + Trust Deed), raw Claude Opus 4.6, and Devstral 123B concurrently via `tokio::join!`; three-column terminal UI |
| - **Trust Deed injection** β seven-article sovereign constitution baked into every Brain system prompt (Identity, Truth Mandate, Search Protocol, Formal Gate, Code Protocol, EmojiScript, No Institutional Capture) |
| - **HANDS retrieval sidecar** β five-layer knowledge pipeline: spaCy NLP parse β FAISS vector search β Neo4j graph traversal β RDF triple extraction β NetworkX PageRank re-ranking; each layer degrades gracefully if its backend is offline |
| - **Lean 4 + Prolog gates** β formal verification and constraint satisfaction run concurrently with search on every CLI query |
| - **Tavily + DuckDuckGo search** β primary and fallback web search fired concurrently via `tokio::join!` |
| - **SHA-256 WORM chain** β genesis block `FRANKENSTEIN_GENESIS`, every pipeline step appended; hash and seal count returned in every API response |
| - **Dark terminal HTML UI** β green-on-black monospace, three-panel tabbed interface (Workflow / Battle / Ask), live WORM bar, four-column pipeline step display, no framework dependencies |
|
|
| --- |
|
|
| *Apache 2.0 Β· SnapKitty Collective 2026 Β· Evidence or Silence* |
|
|
