README.md

```
╔══════════════════════════════════════════════════════════════════════════════╗
║                                                                              ║
║    ⬡  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*