Home

Pantheon OS

An 8-agent autonomous trading system — one orchestrator (ZEUS), agents that never call each other, a single typed data contract between stages, and a hard kill-switch at every stage.

Welcome to the Pantheon OS engineering wiki. Pantheon is a multi-agent orchestration system built in the trading domain because trading forces the hard problems: strict data contracts, fault isolation, graceful degradation, and non-negotiable safety limits. Eight named agents move a market signal through a linear pipeline; ZEUS owns control flow and runs a Claude LLM reasoning step before any trade is approved. It is deployed on a Hetzner VPS and self-schedules every 15 minutes.

This is a portfolio engineering project, not an investment vehicle — paper trading only, no real money at risk, and the live-money gate is earned, not flipped (see Security-Model).

Stack: Python 3.11 · Claude (Anthropic API) · Interactive Brokers via ib_async · Supabase (PostgreSQL + pgvector) · ChromaDB · Upstash Redis · Grafana · Cloudflare Pages · Docker / GHCR · GitHub Actions · Hetzner VPS

---

Table of Contents

1. What Pantheon is
2. The 8 agents at a glance
3. How a signal flows
4. Key engineering ideas
5. Safety posture
6. Status & honesty notes

Deep-dive pages: Architecture · Workflows · Security-Model · Data-Model · Design-Decisions · Setup-and-Deployment

---

WHAT PANTHEON IS

Property	Detail
Domain	Event-driven equity trading (NYSE + XETRA / German markets)
Pattern	Single orchestrator (ZEUS) + 8 single-responsibility agents
Coupling rule	No agent imports another. Only zeus.py imports agents/*. All agents import core.types only.
Contract	One typed dataclass file (core/types.py) is the entire inter-agent contract
Reasoning	Claude LLM step (Director verdict + optional bull/bear debate) before every approval
Cadence	Self-runs every 15 min when a market is open (NYSE or XETRA), via an in-process scheduler
Execution	Interactive Brokers (ib_async), paper port 4002 — IBKR chosen because Alpaca does not serve German residents
Deployment	Dockerized, GHCR images, GitHub Actions → Hetzner VPS, React dashboard on Cloudflare Pages
Trade memory	Supabase PostgreSQL (trades, traces, hit-rate views); ChromaDB / pgvector for the knowledge base

---

THE 8 AGENTS AT A GLANCE

#	Agent	Mythology	One-line role
1	Icarus	flies closest to the sun	Signal watcher — reads unconsumed signals from Supabase, classifies, dedupes, suppresses patterns ZEUS keeps rejecting
2	Hades	judges who passes	Compliance firewall — OFAC, EU sanctions, ESG, LkSG → hard kill or severity downgrade
3	Artemis	tracks conditions	Macro context — VIX, S&P 500 regime, sector ETF momentum → suppress conflicting signals
4	Pythia	reads patterns	Learning + sizing — hit rates per {category}×{regime}×{VIX band}, Bayesian-shrunk, Kelly-inspired size
5	ZEUS	king of Olympus	Orchestrator — owns control flow, runs the Claude LLM judge, writes the audit trace
6	Ares	decisive action	Execution — IBKR bracket order (entry + stop-loss + take-profit), long-only
7	Argus	hundred eyes	Portfolio monitor — drawdown kill switch, Telegram alerts, backfills closed-trade P&L
8	Apollo	knowledge & truth	Librarian — daily research (arXiv, ticker map, self-improvement) + one-shot 4-year historical bootstrap

A ninth agent file, Atlas (universe screener), ships dark behind universe_screener_enabled: false — Phase 2. Full breakdown on the Architecture page.

---

HOW A SIGNAL FLOWS

Hermes Producer (own container, every 30 min)
   EDGAR 8-K/10-Q/10-K + Finnhub news  →  quality gate  →  Supabase `signals`
                                                                   │
   [1] Icarus    read + classify + dedupe                          ▼
   [2] Hades     compliance  ───────────────────────────► KILL (OFAC / ESG / sanctions)
   [3] Artemis   macro regime ──────────────────────────► SUPPRESS (VIX≥35, bad regime)
   [4] Pythia    hit-rate sizing ───────────────────────► SKIP (low conviction / milestone tier)
       Concentration / cooldown check ─────────────────► KILL (1 open per ticker, 48h cooldown)
   [5] ZEUS      Claude LLM debate + Director verdict ──► REJECT / resize
       Budget + max-positions + seniority cap ─────────► KILL
   [6] Ares      IBKR bracket order (entry + SL + TP)
   [7] Argus     monitor → drawdown kill switch ≥8% → feedback loop back to Pythia + KB

Every stage can independently stop the trade. A signal must survive all of them. See Workflows.

---

KEY ENGINEERING IDEAS

Idea	What it is	Where
Single orchestrator	ZEUS is the only owner of control flow; agents are leaf functions	Architecture
Typed contract	One core/types.py dataclass file is the only way to change the pipeline contract	Data-Model
Agent seniority	Agents start at Trainee L1 and earn rank on winning trades; real money gated on reaching Senior + a human arming it	Design-Decisions
Shadow learning	OutcomeResolver, PromotionGate (Bayesian), Backtester, ReplayEngine — closes the decision→outcome loop	Design-Decisions
Fault isolation	Per-agent circuit breakers + a health watchdog daemon = graceful degradation, zero-outage design	Architecture
Layered kill switches	Compliance, macro, conviction, concentration, budget, drawdown, manual /halt	Security-Model

---

SAFETY POSTURE

Control	Behaviour
Paper trading	paper_trading: true + mock_execution: true by default
Real-money gate	Requires system tier = SENIOR AND ARM_REAL_MONEY=true AND paper_trading: false — all three (an AND, never an OR)
Drawdown breaker	Emergency halt + Telegram alert at portfolio drawdown ≥ 8%
Compliance	OFAC / EU sanctions / ESG / LkSG enforced at Hades before anything reaches the LLM
Vault rule	Vault money moves one direction only — into the vault, never back; ZEUS never touches it autonomously
API auth	Mutating endpoints require an X-API-Key header when ZEUS_API_KEY is set

Details on Security-Model.

---

STATUS & HONESTY NOTES

• Paper trading, live and processing signals — waiting for a high-conviction approval to log the first paper trade.
• Kafka was built and then removed. An earlier design ran a Kafka event bus; it was torn out because the system's volume (one cycle / 15 min) never justified a broker. Signals now flow Supabase → Icarus → ZEUS directly. This is documented candidly in Design-Decisions.
• Test count — the README badge states 356 passing; treat the number as approximate (the repo's own LESSONS.md records the pain of badge counts drifting from reality). The point is a real CI quality gate that blocks every deploy.
• This is a personal engineering project. Nothing here is financial advice.

---

Wiki map

Page	What's inside
Architecture	The 8 agents in depth, the "former Kafka / now Supabase" event flow, circuit breakers + watchdog
Workflows	The full trade lifecycle, every kill stage, the research / backtest / replay cycles
Security-Model	API-key auth, the three-condition real-money gate, risk controls, the CI quality gate, secret handling
Data-Model	Supabase tables, the typed dataclass contract, hit-rate views, seniority / EXP / milestone state
Design-Decisions	Why no Kafka, why agent seniority, why Claude, how shadow learning works
Setup-and-Deployment	Local dev quickstart, env config, Docker/Hetzner deploy, CI/CD