mutagent-sdk 0.2.0

╔══════════════════════════════════════════════════════════════════════════════╗
║                                                                              ║
║    ███╗   ███╗██╗   ██╗████████╗ █████╗  ██████╗ ███████╗███╗   ██╗████████╗ ║
║    ████╗ ████║██║   ██║╚══██╔══╝██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝ ║
║    ██╔████╔██║██║   ██║   ██║   ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║    ║
║    ██║╚██╔╝██║██║   ██║   ██║   ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║    ║
║    ██║ ╚═╝ ██║╚██████╔╝   ██║   ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║    ║
║    ╚═╝     ╚═╝ ╚═════╝    ╚═╝   ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝    ║
║                                                                              ║
║              ██████╗ ██╗   ██╗████████╗██╗  ██╗ ██████╗ ███╗   ██╗           ║
║              ██╔══██╗╚██╗ ██╔╝╚══██╔══╝██║  ██║██╔═══██╗████╗  ██║           ║
║              ██████╔╝ ╚████╔╝    ██║   ███████║██║   ██║██╔██╗ ██║           ║
║              ██╔═══╝   ╚██╔╝     ██║   ██╔══██║██║   ██║██║╚██╗██║           ║
║              ██║        ██║      ██║   ██║  ██║╚██████╔╝██║ ╚████║           ║
║              ╚═╝        ╚═╝      ╚═╝   ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝           ║
║                                                                              ║
║                    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

📦 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}