Metadata-Version: 2.5
Name: mutagent-sdk
Version: 0.3.0
Summary: Python SDK for the MutagenT Server API Documentation
License: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.9.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

```
╔══════════════════════════════════════════════════════════════════════════════╗
║                                                                              ║
║    ███╗   ███╗██╗   ██╗████████╗ █████╗  ██████╗ ███████╗███╗   ██╗████████╗ ║
║    ████╗ ████║██║   ██║╚══██╔══╝██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝ ║
║    ██╔████╔██║██║   ██║   ██║   ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║    ║
║    ██║╚██╔╝██║██║   ██║   ██║   ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║    ║
║    ██║ ╚═╝ ██║╚██████╔╝   ██║   ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║    ║
║    ╚═╝     ╚═╝ ╚═════╝    ╚═╝   ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝    ║
║                                                                              ║
║              ██████╗ ██╗   ██╗████████╗██╗  ██╗ ██████╗ ███╗   ██╗           ║
║              ██╔══██╗╚██╗ ██╔╝╚══██╔══╝██║  ██║██╔═══██╗████╗  ██║           ║
║              ██████╔╝ ╚████╔╝    ██║   ███████║██║   ██║██╔██╗ ██║           ║
║              ██╔═══╝   ╚██╔╝     ██║   ██╔══██║██║   ██║██║╚██╗██║           ║
║              ██║        ██║      ██║   ██║  ██║╚██████╔╝██║ ╚████║           ║
║              ╚═╝        ╚═╝      ╚═╝   ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝           ║
║                                                                              ║
║                    Python SDK for AI-Native Development.                     ║
║                                                                              ║
╚══════════════════════════════════════════════════════════════════════════════╝
```

<p align="center">
  <a href="https://pypi.org/project/mutagent-sdk/"><img src="https://img.shields.io/pypi/v/mutagent-sdk?style=for-the-badge&color=3776AB&logo=pypi&logoColor=white" alt="PyPI"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/Python-3.10+-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.10+"></a>
  <a href="https://www.python-httpx.org/"><img src="https://img.shields.io/badge/httpx-0.27+-yellow?style=for-the-badge" alt="httpx"></a>
  <a href="https://docs.pydantic.dev/"><img src="https://img.shields.io/badge/Pydantic-2.0+-e92063?style=for-the-badge&logo=pydantic&logoColor=white" alt="Pydantic v2"></a>
  <a href="#license"><img src="https://img.shields.io/badge/License-Apache_2.0-blue?style=for-the-badge" alt="Apache 2.0"></a>
</p>

<p align="center">
  <strong>Type-safe. Async-first. Production-ready.</strong><br>
  <em>The official Python SDK for the MutagenT AI platform.</em>
</p>

---

## 🎯 What is MutagenT Python SDK?

The **MutagenT Python SDK** is a developer-friendly, fully typed client for the MutagenT AI
platform. Built for modern AI applications, it provides:

- 🔒 **Typed Models** — a Pydantic v2 model for every request and response body in the API spec
- ⚡ **Sync + Async** — `Mutagent` (sync) and `AsyncMutagent` (async) dual surface
- 🐍 **Python 3.10+** — three runtime dependencies: `httpx`, `pydantic`, `typing-extensions`
- 🔐 **HTTPS by Default** — plain-HTTP server URLs are refused for non-local hosts unless you opt in
- 🧩 **Spec-Generated** — every namespace is emitted from the platform's OpenAPI document

### Core Capabilities

| Feature | Description |
|---------|-------------|
| **Agents** | Create, list, update, and delete agents; fetch one by id or by slug |
| **Organizations & Workspaces** | Administer organizations and workspaces, check slugs, set a default workspace |
| **Members & Invitations** | Add, re-role, and remove members; send, resend, and revoke invitations |
| **Model Providers** | Register provider credentials, browse the model catalog, test a connection |
| **Account & Sessions** | Read and update your profile, change your password, list and revoke sessions |
| **Cloud Sandboxes** | Spawn isolated sandboxes, run a command or a single agent turn, watch output live, read captured spans |

---

## 📦 Installation

```bash
pip install mutagent-sdk
```

> The PyPI distribution is `mutagent-sdk`; the import path remains `from mutagent import ...`.

```python
from mutagent import Mutagent, AsyncMutagent
```

---

## 🚀 Quick Start

### Sync client

```python
from mutagent import Mutagent

client = Mutagent(api_key="YOUR_API_KEY", server_url="https://api.mutagent.io")

agents = client.agents.list_agents(limit=10)
print(f"Found {len(agents['data'])} agents")
```

> `server_url` defaults to `MUTAGENT_SERVER_URL`, and to `http://localhost:3003` when that is unset —
> point it at your host explicitly when you are not running the platform locally.

Set `MUTAGENT_API_KEY` in your environment and omit the argument entirely:

```bash
export MUTAGENT_API_KEY="sk_live_xxxxxxxx"
```

```python
from mutagent import Mutagent

client = Mutagent()  # reads MUTAGENT_API_KEY automatically
```

### Async client

```python
import asyncio
from mutagent import AsyncMutagent

async def main():
    async with AsyncMutagent(
        api_key="YOUR_API_KEY",
        server_url="https://api.mutagent.io",
    ) as client:
        # Who am I?
        profile = await client.user_profile.get_profile()
        print(profile)

        # Which workspaces can I see?
        workspaces = await client.workspaces.list_workspaces()
        print(workspaces)

asyncio.run(main())
```

---

## 📚 Namespaces

The client exposes one namespace per API tag. Every method has a sync and an async form:

| Namespace | Covers |
|-----------|--------|
| `client.user_profile` | Profile, password, and active sessions |
| `client.agents` | Agent CRUD and slug lookup |
| `client.organizations` | Organization CRUD, slug checks, member counts |
| `client.workspaces` | Workspace CRUD and default-workspace selection |
| `client.organization_members` | Organization membership and roles |
| `client.workspace_members` | Workspace membership and roles |
| `client.provider_configs` | Provider credentials, model catalog, connection tests |
| `client.invitations` | Organization invitations |

Per-method reference lives in [`docs/sdks/`](./docs/sdks/).

---

## ☁️ Cloud Sandboxes

The platform runs disposable, isolated cloud sandboxes: you spawn one, execute commands or a single
agent turn inside it, watch its output as it happens, read the spans it captured, and tear it down.

| Operation | Route |
|-----------|-------|
| Spawn a sandbox | `POST /api/sandbox` |
| List sandboxes | `GET /api/sandbox` |
| Get sandbox status | `GET /api/sandbox/{id}` |
| Tear down a sandbox | `DELETE /api/sandbox/{id}` |
| Run a command in a sandbox | `POST /api/sandbox/{id}/exec` |
| Watch a sandbox's output live | `GET /api/sandbox/{id}/stream` |
| Read a sandbox's captured spans | `GET /api/sandbox/{id}/traces` |
| Run one command in a fresh sandbox | `POST /api/sandbox/run` |
| Run one agent turn in a fresh sandbox | `POST /api/sandbox/agent/run` |
| List sandbox presets | `GET /api/sandbox/presets` |
| List sandbox providers | `GET /api/sandbox/providers` |
| Preflight a sandbox definition | `POST /api/sandbox/preflight` |
| Exchange an API key for a sandbox operator token | `POST /api/sandbox/token` |
| Ingest OTLP spans from inside a sandbox | `POST /api/sandbox/telemetry/v1/traces` |

> **Availability:** these routes are live in the platform API. This release of the Python client does
> not yet generate a `sandbox` namespace for them — until it does, call them over HTTPS with your
> API key in the `x-api-key` header.

---

## 🧪 Testing

The SDK ships a `dev` extras group with everything needed for testing:

```bash
pip install "mutagent-sdk[dev]"
# Includes: pytest, pytest-asyncio, pytest-httpx, ruff, mypy
```

Run the test suite:

```bash
pytest tests/
```

`pytest-httpx` is used to mock outgoing HTTP calls without spinning up a server. Tests live in
`tests/` at the package root.

---

## 🏗️ Generated by mutagent-xgen

This package is generated by [mutagent-xgen](../mutagent-xgen/) — MutagenT's proprietary
in-house SDK generator. The generator ensures the Python client stays in sync with the API
specification.

To regenerate after API changes:

```bash
# Fetch latest spec from running server
bash scripts/dump-spec.sh

# Regenerate SDK
mutagent-xgen run
```

> **Note:** `README.md` is emitted **once** and is never rewritten by a regeneration, so the
> hand-written content here is safe.

---

## 📜 License

This SDK is released under the [Apache License 2.0](./LICENSE).

Copyright 2026 MutagenT. All rights reserved.

---

<p align="center">
  <sub>Built with care by the MutagenT Team &bull; <a href="https://mutagent.io">mutagent.io</a></sub>
</p>
