# OpenPod

**A zero-dependency multi-agent framework.** A K-addressed message bus, agents that route
each call to the cheapest capable model tier (your keys, your spend caps), persistent memory,
hot-reload skills — and it runs as an MCP server. No cloud account, no phone-home, MIT.

```bash
pip install openpod          # once published
# or, from a clone:
pip install -e .
```

## The two things it does

**1. Route each call to the cheapest model that can do the job.**

```python
from openpod import Agent

agent = Agent("my-agent")               # uses ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY from env

@agent.on_message
def handle(msg):
    return agent.think(msg.text)        # K-classified → cheapest capable tier, tracks $ saved vs a flat baseline

agent.run()
```

Free tiers (template + local Ollama) cost nothing and need no key. Paid tiers use **your** provider
keys — OpenPod never bills you and never checks a license. (An optional hosted-tier gate exists in the
code but is **off by default**.)

**2. Pass messages between agents with a K-addressed bus.**

```python
from openpod import Pod

pod = Pod("my_cell", roles=["alpha", "beta", "gamma"])
pod.send("alpha", "beta", "Build the widget", suit="+7D", self_rank=9)   # suit = K-coordinate, rank = confidence

for msg in pod.inbox("beta"):           # priority-sorted, TTL-filtered
    print(f"[{msg.from_role}] {msg.body}")

pod.close_session("alpha", "Widget built. Tests pass.")                  # hand off state, kill amnesia
```

## CLI

```bash
openpod send alpha beta "Do the thing" --suit "+7S"
openpod inbox beta
openpod close alpha "Session done."
openpod stats                 # tokens routed, $ spent, $ saved vs baseline
openpod demo
```

## Also in the box

- **Memory** — BM25 + cosine retrieval, persistent across sessions.
- **Skills** — a hot-reloading skill system that doubles as a native MCP server.
- **Channels** — optional ntfy / Telegram / Discord transports (extras: `pip install openpod[all]`).

## Why "pod", and why 143

The addressing is **K-104**: 4 suits × 13 ranks × 2 polarities = 104 content coordinates, plus 39
relational primitives (3 axes × 13 ranks) = **143** — the same vocabulary size as sperm-whale codas,
which is where the "pod" comes from. It's a compact, human-legible coordinate for *what a message is
about* and *how sure the sender is* — not a required concept; you can ignore the suits and use plain
strings. It exists because addressing beats free text when many agents talk.

## Status

Alpha (0.2). Zero-dependency core; extras are opt-in. Test suite included (`pytest`, 10 behavioral tests, green on 3.14); CI configured for Python 3.10–3.12.
See `ROADMAP.md` for v0.3 — folding hard-won multi-agent-comms lessons into the message schema.

## License

MIT