███████╗ ██████╗ ██╗   ██╗███████╗██████╗ ███████╗██╗ ██████╗ ███╗   ██╗
 ██╔════╝██╔═══██╗██║   ██║██╔════╝██╔══██╗██╔════╝██║██╔═══██╗████╗  ██║
 ███████╗██║   ██║██║   ██║█████╗  ██████╔╝█████╗  ██║██║   ██║██╔██╗ ██║
 ╚════██║██║   ██║╚██╗ ██╔╝██╔══╝  ██╔══██╗██╔══╝  ██║██║   ██║██║╚██╗██║
 ███████║╚██████╔╝ ╚████╔╝ ███████╗██║  ██║██║     ██║╚██████╔╝██║ ╚████║
 ╚══════╝ ╚═════╝   ╚═══╝  ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝ ╚═════╝ ╚═╝  ╚═══╝
      ██████╗ ███████╗
     ██╔═══██╗██╔════╝
     ██║   ██║███████╗
     ██║   ██║╚════██║
     ╚██████╔╝███████║
      ╚═════╝ ╚══════╝

Sovereign-OS

One command. One Charter. A digital corporation that thinks, spends, and answers for every token.

Not another chatbot. Not another “AI agent framework.” Sovereign-OS is the constitution-first substrate: one YAML defines who the entity is, what it may spend, and how success is measured. The CEO plans. The CFO gates. The Auditor judges. The Ledger never lies.

Quick Start • Why • Architecture • Features • Docs

---

⚡ Quick Start

CLI — 30 seconds:

git clone https://github.com/Justin0504/Sovereign-OS.git && cd Sovereign-OS
pip install -e .
sovereign run --charter charter.example.yaml "Summarize the market in one paragraph."

You get: task plan → CFO approval → execution → audit report. Done.

Web Dashboard — paid jobs, 24/7:

pip install -e ".[llm]"
# Set STRIPE_API_KEY + OPENAI_API_KEY or ANTHROPIC_API_KEY in .env
python -m sovereign_os.web.app
# Open http://localhost:8000 — run missions, approve jobs, watch balance & token usage.

Want to charge for work? 3-step guide → (Stripe + one LLM key; 16 built-in workers out of the box.)

One-click deploy: DEPLOY.md — Docker Compose, volumes, graceful shutdown.

---

🧠 Why Sovereign-OS?

	Typical agent frameworks	Sovereign-OS
💰 Money	API key = burn until empty.	Real ledger. Every cent and token tracked. CFO approves before every task. Daily caps, runway, P&L.
🛡️ Quality	Hope the output is right.	Audited. Every task verified against Charter KPIs. Fail audit → TrustScore drops. Proof hash on every report.
⚖️ Control	All or nothing.	Earned. Agents start in a sandbox. They earn spend and capabilities via TrustScore.

One YAML = mission, budget, and rules. The rest is governance.

---

🏛️ Architecture

Five layers. Data flows down; accountability flows back.

Charter (who we are) → Governance (CEO + CFO) → Registry (workers) → Ledger (every $ & token) → Auditor (pass/fail → TrustScore)

• Charter — Mission, competencies, fiscal bounds, KPIs. One file.
• Governance — CEO decomposes goals into tasks; CFO approves or denies budget per task.
• Registry — Maps skills to workers (13 built-in: summarize, research, reply, write_article, translate, …).
• Ledger — Append-only. Runway, burn rate, income. Never lies.
• Auditor — KPI verification. Pass → TrustScore ↑. Fail → TrustScore ↓.

Diagram & roadmap

flowchart LR
  Charter --> CEO[CEO · Plan]
  CEO --> CFO[CFO · Approve]
  CFO --> Registry[Workers]
  Registry --> Ledger[Ledger]
  Registry --> Auditor[Auditor]
  Auditor --> CFO

Loading

Phases 1–6a done (governance, ledger, MCP, audit trail, Stripe, webhook). Phase 6b: on-chain/compliance stubs. See PHASE6 and OPTIMIZATION_ROADMAP.

---

🚀 Features

• 📦 16 built-in workers — summarize, research, reply, write_article, solve_problem, write_email, write_post, meeting_minutes, translate, rewrite_polish, collect_info, extract_structured, spec_writer, assistant_chat, code_assistant, code_review. No code; configure Stripe + one LLM key and run paid jobs. QUICKSTART
• 🔄 Multi-model — Strategist and workers can use different backends (e.g. GPT-4o for planning, cheaper models for execution).
• 🔐 SovereignAuth — RBAC by TrustScore. READ_FILES, WRITE_FILES, SPEND_USD, CALL_API gated; agents earn capabilities.
• 🌐 Web Dashboard (24/7) — Run missions, job queue, approve/retry, health, token usage, audit trail. Optional ingest from URL; Stripe charges; webhook on completion.
• 🌍 Ingest bridge — Pull real orders from Reddit (PRAW), any JSON/HTML URL, or Shopify/WooCommerce; feed Sovereign-OS via a single URL or direct POST. INGEST_BRIDGE
• 🔌 MCP native — Plug into the same tool graph as the rest of the ecosystem.
• 📊 Observability — OpenTelemetry, Prometheus metrics (GET /metrics: job counters, duration, queue gauges), verifiable audit trail with proof_hash.
• 🔒 Security — API key via env; constant-time comparison; job input validation; optional IP whitelist and rate limit. CONFIG.

_{Add docs/dashboard.png for a Dashboard screenshot; link and size above are ready.}

---

📁 Project layout

sovereign_os/
├── models/         # Charter (Pydantic)
├── ledger/         # UnifiedLedger (cents + tokens)
├── governance/     # CEO (Strategist) + CFO (Treasury) + Engine
├── agents/         # Workers, Registry, SovereignAuth
├── auditor/        # ReviewEngine, AuditReport (proof_hash)
├── jobs/           # JobStore (SQLite), RedisJobStore (Redis queue)
├── ingest/         # Poll URL → enqueue jobs
├── ingest_bridge/  # Reddit, scrapers, Shopify/WooCommerce → jobs (optional)
├── web/            # FastAPI dashboard, /api/jobs, /health, Stripe webhook
└── ui/             # Textual TUI (optional)
docs/               # QUICKSTART, CONFIG, INGEST_BRIDGE, DEMO_SCRIPT, …
tests/              # pytest

---

📖 Docs

Doc	What’s inside
Quick Start	Stripe + LLM key, first paid job, curl examples, troubleshooting.
Config & env	All SOVEREIGN_*, Stripe, Redis, webhook, rate limit, retry.
Charter	How to write mission, competencies, KPIs, fiscal bounds.
Worker	How to add and register custom workers.
Monetization	Job queue, Stripe, approval, compliance, human-out-of-loop.
Demo script	End-to-end: auto ingest → CEO/CFO → permissions (firewall) → delivery → Stripe.
Ingest bridge	Industrial bridge: Reddit, scrapers, Shopify/WooCommerce → Sovereign-OS.
Audit proof	Verifiable trail, proof_hash, integrity check.
Optimization roadmap	Next steps: reliability, observability, security, scale.
Future development plan	Wave-by-wave plan: stability, UX/deploy, workers/scale, community.
Deploy (Docker)	One-click deploy, volumes, health, graceful shutdown.
Backup	Back up job DB and ledger for disaster recovery.
Multi-instance	Concurrency, Redis queue for multi-instance workers, scaling.
Good first issues	Contribution ideas: docs, tests, examples.
Release process	How to cut a release and update CHANGELOG.

---

🧪 Test & run

pip install -e ".[dev]"
pytest tests/ -v

Docker (Web UI + Redis):

docker compose up -d redis web
# http://localhost:8000

Ingest bridge (real orders from Reddit, scrapers, retail):

pip install -e ".[bridge]"   # praw, requests, beautifulsoup4
python -m sovereign_os.ingest_bridge   # serves on :9000 by default
# Then set SOVEREIGN_INGEST_URL=http://localhost:9000/jobs?take=true and start the Web app.

See INGEST_BRIDGE for Reddit, scraper, and Shopify/WooCommerce config.

Troubleshooting: Payments still “Dummy” or no real LLM? Set STRIPE_API_KEY and OPENAI_API_KEY or ANTHROPIC_API_KEY in .env; restart. Check GET /health for config_warnings. QUICKSTART.

---

🔒 Security & contributing

• Secrets: Use env vars only (e.g. STRIPE_API_KEY, OPENAI_API_KEY). CONFIG.
• Vulnerabilities: SECURITY.md.
• Contribute: CONTRIBUTING.md. Run tests before PR.

📜 License

MIT

---

Sovereign-OS — Think. Audit. Execute.

_{If you run a digital corp, run it on a ledger.}