Metadata-Version: 2.4
Name: agentsmcp
Version: 0.1.1
Summary: Context-sync protocol for AI agents. Every agent has a mailbox. No agent ever starts cold.
Author: AgentMailbox contributors
License: MIT
Project-URL: Homepage, https://github.com/RagavRida/agentsmcp
Project-URL: Issues, https://github.com/RagavRida/agentsmcp/issues
Project-URL: Source, https://github.com/RagavRida/agentsmcp
Keywords: agents,ai,context,protocol,mailbox,llm,agentsmcp,agentmailbox
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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Communications
Classifier: Framework :: AsyncIO
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: anyio>=4.0; extra == "dev"
Dynamic: license-file

# AgentMailbox — Python SDK

Python client for [AgentMailbox](../README.md), the context-sync protocol
for AI agents. Mirrors the JS SDK feature-for-feature.

## Install

```bash
pip install agentsmcp
```

The PyPI distribution is named `agentsmcp` (matching the npm SDK); the
import name stays `agentmailbox`:

```python
from agentmailbox import AgentMailbox
```

For local development from a clone:

```bash
pip install -e ".[dev]"
```

Requires Python 3.10+.

## Start the server

The Python SDK is a pure HTTP client — it talks to the AgentMailbox
Node server. Start it first:

```bash
cd ~/agentmailbox
npm start
```

## Async usage

```python
import asyncio
from agentmailbox import AgentMailbox

async def main():
    async with AgentMailbox("researcher@demo", server="http://localhost:3000") as a:
        await a.connect()
        result = await a.send(
            "writer@demo",
            {"task": "summarize diffusion models"},
            context_snapshot={"step": "research_complete", "paper_count": 2},
        )
        print(result.thread_id)

asyncio.run(main())
```

## Multi-agent (CC/BCC/ReplyAll)

```python
async with AgentMailbox("orchestrator@demo", server=SERVER) as orchestrator:
    await orchestrator.connect()
    sent = await orchestrator.send(
        "researcher@demo",
        {"task": "find 50 papers on diffusion models"},
        cc=["writer@demo"],
        bcc=["logger@demo"],
        context_snapshot={"step": "task_dispatched", "priority": "high"},
    )

async with AgentMailbox("researcher@demo", server=SERVER) as researcher:
    await researcher.connect()
    inbound = await researcher.receive()
    # inbound.context.snapshot → {"step": "task_dispatched", "priority": "high"}
    # inbound.messages[0].cc   → ["writer@demo"]
    # inbound.messages[0].bcc  → None  (stripped from non-sender's view)

    await researcher.reply_all(
        sent.thread_id,
        {"result": "found 50 papers"},
        context_snapshot={"step": "research_complete", "paper_count": 50},
    )
```

Run the bundled demos:

```bash
python examples/basic.py
python examples/multi_agent.py
```

## Sync usage

For scripts and notebooks that aren't async-friendly:

```python
from agentmailbox import AgentMailboxSync

agent = AgentMailboxSync("researcher@demo")
agent.connect()
result = agent.send("writer@demo", {"task": "..."})
print(result.thread_id)
```

`AgentMailboxSync` drives a fresh event loop per call via `asyncio.run`.
It's convenient but slower than the async client.

## API

All methods return typed dataclasses (`SendResult`, `ReceiveResult`,
`Thread`, `ContextFrame`, `Message`, `ParticipantRole`, `Context`).
No untyped dicts in the public surface.

| Method                          | HTTP                                |
| ------------------------------- | ----------------------------------- |
| `connect()`                     | `POST /agents/register`             |
| `send(to, payload, ...)`        | `POST /messages/send`               |
| `reply_all(thread_id, payload)` | `POST /messages/reply-all`          |
| `unread()`                      | `GET /mailbox/:id/unread`           |
| `receive(from_agent=None)`      | `GET /mailbox/:id/unread` + filter  |
| `threads()`                     | `GET /mailbox/:id`                  |
| `sync(thread_id)`               | `GET /threads/:id/sync?as=:id`      |
| `participants(thread_id)`       | `GET /threads/:id/participants?as=` |
| `mark_read(thread_id)`          | `POST /mailbox/:id/read`            |

## Exceptions

- `AgentMailboxError` — base class. `.status_code` set when raised from HTTP.
- `NotFoundError` — 404
- `ServerError` — 5xx
- `ConnectionError` — server unreachable

## License

MIT
