Metadata-Version: 2.4
Name: teamver-mail-agent
Version: 0.3.0
Summary: Teamver Mail BE client for AI agent runtimes (inbox, events, processing, reply)
Project-URL: Homepage, https://teamver.com
Project-URL: Documentation, https://github.com/NeuralStudioKr/ns-teamver-packages/tree/main/packages/python/teamver-mail-agent-python
Project-URL: Repository, https://github.com/NeuralStudioKr/ns-teamver-packages
Project-URL: Issues, https://github.com/NeuralStudioKr/ns-teamver-packages/issues
Project-URL: Changelog, https://github.com/NeuralStudioKr/ns-teamver-packages/blob/main/packages/python/teamver-mail-agent-python/CHANGELOG.md
Author-email: Teamver <dev@teamver.com>
Maintainer-email: Teamver <dev@teamver.com>
License: MIT
License-File: LICENSE
Keywords: agent,async,mail,sdk,teamver
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx<0.28,>=0.27.0
Requires-Dist: pydantic<3,>=2.0
Requires-Dist: teamver-sdk-core>=0.1.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# teamver-mail-agent

Async Python client for the **Teamver Mail BE** Agent API (`/v1/agent/*`).  
Built for agents, Hermes, and other AI agent runtimes.

## Install

```bash
pip install teamver-mail-agent
```

Depends on `teamver-sdk-core`. Python **≥ 3.11**.

For the unified agent facade (channel + DM + Drive + mail), install
[`teamver-agent-sdk`](https://pypi.org/project/teamver-agent-sdk/) instead.

## Quick start

```python
import asyncio
from teamver_mail_agent import TeamverMailAgentClient

async def main():
    async with TeamverMailAgentClient.from_env() as client:
        events = await client.list_events(limit=10)
        for ev in events.events:
            if ev.message_id:
                await client.ack_event(ev.event_id)
                msg = await client.get_message(ev.message_id)
                print(msg.subject, msg.body_text)

asyncio.run(main())
```

## Environment

| Field | Env | Description |
|-------|-----|-------------|
| `api_base_url` | `TEAMVER_MAIL_API_BASE` or `TEAMVER_MAIL_API_BASE_URL` | Mail host, **no** `/v1` suffix |
| `agent_token` | `TEAMVER_MAIL_AGENT_TOKEN` | Bearer `tv_agent_…` |
| `internal_api_key` | `TEAMVER_INTERNAL_API_KEY` | Optional — M2M provisioning only (not for edge agents) |

## Scopes

`agent:read`, `agent:events`, `agent:reply` — issued with the mail agent token.

## Recommended loop

```text
list/stream events → ack → get_message → processing_start
→ handle → reply (Idempotency-Key) → processing_complete
```

Helper: `run_standard_inbound_loop` (see package docs on GitHub).

## Documentation

- [AI Agent Guide](https://github.com/NeuralStudioKr/ns-teamver-packages/blob/main/packages/python/teamver-mail-agent-python/docs/teamver_mail_agent_AI_AGENT_GUIDE.md)
- [API Quickref](https://github.com/NeuralStudioKr/ns-teamver-packages/blob/main/packages/python/teamver-mail-agent-python/docs/teamver_mail_agent_API_QUICKREF.md)

## Development

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

## License

MIT — see [LICENSE](./LICENSE).
