mutagent-sdk 0.1.1

Python SDK for the MutagenT Server API Documentation

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

Type-safe. Async-first. Production-ready.
The official Python SDK for the MutagenT AI platform.

---

🎯 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

pip install mutagent-sdk

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

from mutagent import Mutagent, AsyncMutagent

---

🚀 Quick Start

Sync client

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:

export MUTAGENT_API_KEY="sk_live_xxxxxxxx"

from mutagent import Mutagent

client = Mutagent()  # reads MUTAGENT_API_KEY automatically

Async client

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

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

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:

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

Run the test suite:

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's proprietary in-house SDK generator. The generator ensures the Python client stays in sync with the API specification.

To regenerate after API changes:

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

Copyright 2026 MutagenT. All rights reserved.

---

_{Built with care by the MutagenT Team • mutagent.io}