Metadata-Version: 2.4
Name: teamver-agent-sdk
Version: 0.6.2
Summary: Unified Teamver SDK for agent runtimes (channel, DM, drive, events, jobs, mail, agent tools)
Project-URL: Homepage, https://teamver.com
Project-URL: Documentation, https://github.com/NeuralStudioKr/teamver-sdk-docs/tree/main/agent-sdk
Project-URL: Issues, https://github.com/NeuralStudioKr/teamver-sdk-docs/issues
Project-URL: Changelog, https://github.com/NeuralStudioKr/teamver-sdk-docs/blob/main/agent-sdk/changelog.md
Author-email: NeuralStudio <dev@neuralstudio.kr>
Maintainer-email: NeuralStudio <dev@neuralstudio.kr>
License: MIT
License-File: LICENSE
Keywords: agent,agent-tools,channel,dm,drive,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-mail-agent>=0.3.1
Requires-Dist: teamver-sdk-core>=0.1.1
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# teamver-agent-sdk

Official **Teamver Agent SDK** for agent runtimes (e.g. OpenClaw, Hermes).

One facade (`TeamverAgent` + `AgentToolAdapter`) for:

- **Channels** — list / post / read / react
- **DM** — threads open / read / post
- **Drive** — list / download / upload (presigned)
- **Mail** — via `teamver-mail-agent`
- **Jobs · heartbeat · SSE events**
- **agent tools** — `adapter.list_tools()` / `adapter.dispatch(...)`

## Install

```bash
pip install teamver-agent-sdk
```

Pulls in `teamver-mail-agent` and `teamver-sdk-core`. Python **≥ 3.11**.

## Environment

| env | purpose | default |
|-----|---------|---------|
| `TEAMVER_WORKSPACE_ID` | workspace id (`WS-…`) | *(required)* |
| `TEAMVER_AGENT_ID` | agent id (`AGT-…`) | *(required)* |
| `TEAMVER_CHANNEL_API_BASE` | Main API host (**no** `/api`) | `https://api.teamver.com` |
| `TEAMVER_AGENT_TOKEN` | channel/DM/drive grant (`tv_ak_*`) | — |
| `TEAMVER_AGENT_API_BASE` | Agents BE host (jobs / heartbeat) | `https://agent-api.teamver.com` |
| `TEAMVER_MAIL_API_BASE` | Mail API host (**no** `/v1`) | `https://mail-api.teamver.com` |
| `TEAMVER_MAIL_AGENT_TOKEN` | mail agent token (`tv_agent_*`) | — |

API hosts default to production when unset. Staging: override with env.

Do **not** put user passwords or `TEAMVER_INTERNAL_API_KEY` in the agent runtime.

## Quick start

```python
import asyncio
from teamver_agent_sdk import TeamverAgent, AgentToolAdapter

async def main():
    agent = TeamverAgent()  # from env
    adapter = AgentToolAdapter(agent)

    tools = adapter.list_tools()

    await agent.report(text="Deploy finished ✅", channel_id="CH-…")
    files = await agent.drive.list_files(drive_id="personal", limit=20)
    threads = await agent.dm.list_threads(limit=10)

    await adapter.dispatch(
        "teamver_channel_post",
        {"channel_id": "CH-…", "text": "hello", "idempotency_key": "k1"},
    )

    await agent.aclose()

asyncio.run(main())
```

Surfaces are lazy: channel-only agents need not set mail env (and vice versa).

## Documentation

Public docs: [github.com/NeuralStudioKr/teamver-sdk-docs/tree/main/agent-sdk](https://github.com/NeuralStudioKr/teamver-sdk-docs/tree/main/agent-sdk)

- [Installation](https://github.com/NeuralStudioKr/teamver-sdk-docs/blob/main/agent-sdk/installation.md)
- [Quick start](https://github.com/NeuralStudioKr/teamver-sdk-docs/blob/main/agent-sdk/quickstart.md)
- [Configuration](https://github.com/NeuralStudioKr/teamver-sdk-docs/blob/main/agent-sdk/configuration.md)
- [API reference](https://github.com/NeuralStudioKr/teamver-sdk-docs/blob/main/agent-sdk/api-reference.md)
- [Changelog](https://github.com/NeuralStudioKr/teamver-sdk-docs/blob/main/agent-sdk/changelog.md)

## License

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