Metadata-Version: 2.4
Name: mutagent-sdk
Version: 0.1.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:

- 🔒 **Full Type Safety** — Pydantic v2 models throughout; passes `mypy --strict`
- ⚡ **Sync + Async** — `Mutagent` (sync) and `AsyncMutagent` (async) dual surface
- 🐍 **Python 3.10+** — CPython and PyPy compatible
- 🔁 **Built-in Retries** — exponential back-off with jitter, configurable per-call or globally
- 📡 **Live Tracing** — OTel-aligned observability via `mutagent.tracing`

### Core Capabilities

| Feature | Description |
|---------|-------------|
| **Prompt Management** | Create, version, and iterate on prompts programmatically |
| **Dataset Operations** | Import, export, and manage evaluation datasets |
| **Evaluation Engine** | Run automated evaluations against your prompts |
| **Auto-Optimization** | Let the MetaTuner improve your prompts based on metrics |
| **Trace Collection** | Native OTel-aligned observability — no external collector needed |

---

## 📦 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")

prompts = client.prompt.list_prompts()
print(f"Found {len(prompts.data)} prompts")
```

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") as client:
        # Create a prompt
        prompt = await client.prompt.create_prompt(
            name="Support Template",
            content="You are a helpful agent. User query: {{query}}",
        )
        print(f"Created prompt: {prompt.id}")

        # List datasets for the prompt
        datasets = await client.prompt_datasets.list_datasets_for_prompt(id=prompt.id)
        print(f"Datasets: {len(datasets.data)}")

asyncio.run(main())
```

---

## 🔍 Tracing

The tracing module provides OTel-aligned span instrumentation with no external collector required.

### Initialize

```python
from mutagent.tracing import init_tracing, shutdown_tracing

init_tracing(api_key="YOUR_API_KEY")

# ... your application code ...

await shutdown_tracing()  # flushes remaining spans
```

### Decorate functions

```python
from mutagent.tracing import trace

@trace(kind="agent")
async def run_support_agent(query: str) -> str:
    # Function is automatically traced — input, output, and duration captured
    response = await call_llm(query)
    return response
```

---

## 🧪 Testing

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

```bash
pip install "mutagent[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 intentionally hand-written and is **not** tracked in `gen.lock`.
> It will not be overwritten by regeneration.

---

## 📜 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>
