Metadata-Version: 2.4
Name: mumega
Version: 0.10.1
Summary: Sovereign Operating System for AI Agents - Multi-model, autonomous, edge-native
Author-email: Mumega Labs <hello@mumega.com>
License: MIT
Project-URL: Homepage, https://mumega.com
Project-URL: Documentation, https://docs.mumega.com
Project-URL: Repository, https://github.com/servathadi/sos
Project-URL: Issues, https://github.com/servathadi/sos/issues
Keywords: ai,agents,llm,autonomous,sovereign,multi-agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: alembic>=1.13
Requires-Dist: fastapi>=0.100
Requires-Dist: httpx>=0.24
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: redis>=4.0
Requires-Dist: requests>=2.31
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: sse-starlette>=2.1.3
Requires-Dist: uvicorn>=0.20
Requires-Dist: PyNaCl>=1.5
Provides-Extra: gemini
Requires-Dist: google-genai>=1.0.0; extra == "gemini"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: all-llms
Requires-Dist: google-genai>=1.0.0; extra == "all-llms"
Requires-Dist: openai>=1.0.0; extra == "all-llms"
Provides-Extra: telemetry
Requires-Dist: opentelemetry-api>=1.25; extra == "telemetry"
Requires-Dist: opentelemetry-sdk>=1.25; extra == "telemetry"
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.25; extra == "telemetry"
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.46b0; extra == "telemetry"
Requires-Dist: opentelemetry-instrumentation-httpx>=0.46b0; extra == "telemetry"
Requires-Dist: opentelemetry-instrumentation-redis>=0.46b0; extra == "telemetry"
Provides-Extra: cloudflare
Requires-Dist: httpx>=0.24; extra == "cloudflare"
Provides-Extra: local
Requires-Dist: chromadb>=0.4; extra == "local"
Requires-Dist: sentence-transformers>=2.2; extra == "local"
Provides-Extra: solana
Requires-Dist: solana>=0.30.2; extra == "solana"
Requires-Dist: solders>=0.18.0; extra == "solana"
Requires-Dist: base58>=2.1.1; extra == "solana"
Provides-Extra: full
Requires-Dist: google-genai>=1.0.0; extra == "full"
Requires-Dist: openai>=1.0.0; extra == "full"
Requires-Dist: chromadb>=0.4; extra == "full"
Requires-Dist: sentence-transformers>=2.2; extra == "full"
Requires-Dist: solana>=0.30.2; extra == "full"
Requires-Dist: solders>=0.18.0; extra == "full"
Requires-Dist: base58>=2.1.1; extra == "full"
Requires-Dist: prometheus-client>=0.17; extra == "full"
Requires-Dist: opentelemetry-api>=1.25; extra == "full"
Requires-Dist: opentelemetry-sdk>=1.25; extra == "full"
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.25; extra == "full"
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.46b0; extra == "full"
Requires-Dist: opentelemetry-instrumentation-httpx>=0.46b0; extra == "full"
Requires-Dist: opentelemetry-instrumentation-redis>=0.46b0; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: import-linter>=2.0; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Requires-Dist: alembic>=1.13; extra == "dev"
Requires-Dist: bcrypt>=4.0; extra == "dev"
Requires-Dist: jsonschema>=4.0; extra == "dev"

# SOS — Sovereign Operating System

**MCP-native AI agent OS. Redis bus. Squad service. Multi-model engine. One URL to connect any agent.**

[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
[![Status: Active](https://img.shields.io/badge/status-active-brightgreen)](https://mumega.com)

---

SOS is the runtime for teams of AI agents. It runs on a single server — a $20/mo VPS works fine. Agents connect via MCP SSE (one URL, one config snippet). The Redis bus wakes agents on message. The squad service manages tasks. The engine routes to the right model and falls back automatically when one is unavailable.

Built for teams who want to run a real multi-agent system without cloud lock-in or framework overhead.

---

## Why SOS?

| Feature | SOS | CrewAI | AutoGen | LangGraph |
|---|---|---|---|---|
| MCP-native from day one | Yes | Bolted on later | Bolted on later | Bolted on later |
| Real-time bus (wake on message) | Redis Streams + SSE | No | No | No |
| Connect any agent with one URL | Yes (SSE) | No | No | No |
| Shared agent memory | Mirror (pgvector) | No | No | No |
| Multi-model failover | Built in | Manual | Manual | Manual |
| Local-first (no cloud required) | Yes | No | No | No |
| Task queues with atomic claim | Squad Service | Basic | No | No |
| Runs on a $20/mo VPS | Yes | Needs more | Cloud-first | Cloud-first |

The core difference: **the bus IS MCP SSE**. Not a wrapper. Not an adapter added in v2. Every tool call, every agent message, every task update flows through the same MCP transport Claude Code already speaks.

---

## Docs

- [Agent Wiring — Claude Code + Codex + SOS](docs/architecture/AGENT_WIRING.md) — Mermaid diagrams, sequence flows, transport comparison, quick connect reference

## Architecture

```
  Claude Code / Cursor / any MCP client
        │
        │  SSE (one URL)
        ▼
  ┌─────────────────────────────────────────────┐
  │            SOS MCP Server (:6070)           │
  │   12 tools: send · inbox · peers · ask      │
  │   remember · recall · search_code           │
  │   task_create · task_list · task_update     │
  │   onboard · broadcast · status              │
  └──────────┬──────────────────────────────────┘
             │
    ┌────────▼────────┐
    │   Redis Bus     │  ← streams, pub/sub, wake-on-message
    └────┬──────┬─────┘
         │      │
   ┌─────▼──┐ ┌─▼──────────┐ ┌────────────┐
   │ Squad  │ │   Engine   │ │   Mirror   │
   │ :8060  │ │   :6060    │ │   :8844    │
   │ tasks  │ │ model route│ │  memory    │
   │ skills │ │ failover   │ │  pgvector  │
   └────────┘ └────────────┘ └────────────┘
```

Agents are not processes SOS manages. They are external — Claude Code sessions, Python scripts, whatever. They connect to the MCP SSE endpoint, get 12 tools, and can talk to each other, create tasks, read memory, and route work.

---

## Quick Start

**Prerequisites:** Python 3.11+, Redis, git

```bash
# 1. Clone
git clone https://github.com/Mumega-com/sos.git
cd sos

# 2. Install
pip install -e .

# 3. Configure
cp .env.example .env
# Edit .env: add REDIS_URL, ANTHROPIC_API_KEY, GEMINI_API_KEY, etc.
cp sos/bus/tokens.json.example sos/bus/tokens.json
# Edit tokens.json: add your agent tokens

# 4. Start core services
python3 -m sos.services.engine    # model engine      :6060
python3 -m sos.services.squad     # squad + tasks     :8060
python3 -m sos.mcp.sos_mcp_sse    # MCP SSE server    :6070

# Or use systemd (see systemd/ directory for unit files)
```

**Connect Claude Code (or any MCP client):**

```json
{
  "mcpServers": {
    "sos": {
      "url": "https://your-server.com/sse/YOUR_TOKEN"
    }
  }
}
```

That's it. Your agent now has 12 tools to communicate, manage tasks, and access shared memory.

---

## MCP Tools

All 12 tools are available the moment an agent connects.

| Tool | Description |
|---|---|
| `send` | Send a message to another agent by name |
| `inbox` | Read your incoming messages |
| `peers` | See which agents are online |
| `ask` | Send a message and wait for a reply |
| `broadcast` | Send a message to all connected agents |
| `remember` | Store something in shared Mirror memory |
| `recall` | Retrieve from Mirror memory by query |
| `search_code` | Semantic search across the codebase |
| `memories` | List recent memories |
| `task_create` | Create a task in the squad service |
| `task_list` | List tasks for a squad or agent |
| `task_update` | Update task status or result |
| `onboard` | Provision a new agent or project |
| `status` | Check system health |

---

## Services

| Service | Port | What it does |
|---|---|---|
| Engine | 6060 | Multi-model routing, failover, model selection |
| Squad | 8060 | Task queues, skills, pipelines, connectors |
| MCP SSE | 6070 | SSE endpoint — agents connect here |
| Mirror | 8844 | Memory API (pgvector, engrams) — separate repo |
| Gateway | 6062 | Auth, rate limiting, JSON-RPC entrypoint |

---

## Multi-Model Config

SOS routes to the right model for each task. Cheaper models handle high-volume work. Expensive models handle complex reasoning. If a model is down or rate-limited, SOS falls back automatically.

```bash
# .env
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIza...
OPENAI_API_KEY=sk-...
GROK_API_KEY=...
OLLAMA_URL=http://localhost:11434   # local models, no API key needed
```

**Tiers:**

| Tier | Models | When used |
|---|---|---|
| diesel | Gemma 4 31B (free), Claude Haiku | High-volume, routine tasks |
| aviation | Claude Opus, GPT-5 | Complex reasoning, architecture |

The engine selects tier based on task labels. You can also specify a model directly in task metadata.

---

## Agent Tokens

Agents authenticate with bearer tokens. Each token has a name, project scope, and label.

```bash
# Generate a token
python3 -c "import secrets; print('sk-sos-' + secrets.token_hex(16))"

# Add to sos/bus/tokens.json
```

See `sos/bus/tokens.json.example` for the format.

---

## Works with Mirror

[Mirror](https://github.com/Mumega-com/mirror) is the shared memory layer. Agents use `remember` and `recall` MCP tools to store and retrieve information across sessions. Mirror uses PostgreSQL + pgvector for semantic search.

Without memory, agents forget everything between sessions. With Mirror, they accumulate context over time — learnings, decisions, customer data, codebase knowledge.

```bash
# Start Mirror separately
git clone https://github.com/Mumega-com/mirror
cd mirror && python mirror_api.py  # :8844

# Configure in SOS
MIRROR_URL=http://localhost:8844
MIRROR_TOKEN=your-token
```

---

## Project Structure

```
sos/
├── sos/
│   ├── bus/             # Redis messaging, token auth
│   ├── mcp/             # MCP SSE server (:6070)
│   ├── services/
│   │   ├── engine/      # Multi-model routing, failover
│   │   ├── squad/       # Tasks, skills, pipelines
│   │   └── gateway/     # Auth, rate limiting
│   ├── skills/          # 13 packaged skills (each with SKILL.md)
│   ├── kernel/          # schema, identity, capability, config
│   ├── agents/          # agent definitions
│   └── contracts/       # service boundary types
├── sovereign/
│   ├── cortex.py        # portfolio scoring brain
│   └── cortex_events.py # event-driven brain
├── systemd/             # systemd service units
├── scripts/             # ops scripts
└── tests/
```

---

Built by [Mumega Labs](https://mumega.com) — the company that runs companies with AI agents.

- **Mumega** — [mumega.com](https://mumega.com) — managed AI operations platform powered by SOS
- **Mirror** — shared agent memory layer (pgvector + hybrid search)
- **Inkwell** — agent-first content and publishing framework
