Metadata-Version: 2.4
Name: to11ai-sdk
Version: 0.1.0
Summary: Python SDK for the to11.ai platform
Project-URL: Homepage, https://to11.ai
Project-URL: Repository, https://github.com/to11ai/platform
License-Expression: MPL-2.0
License-File: LICENSE
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# to11ai-sdk

Python SDK for [to11.ai](https://to11.ai) — the AI engineering platform for prompt management, tracing, and evals.

## Installation

```bash
pip install to11ai-sdk
# or with uv
uv add to11ai-sdk
```

## Getting started

```python
from to11ai_sdk import create_client

client = create_client(
    base_url="https://api.to11.ai",
    api_key="...",
)

result = client.prompts.resolve(
    project_id="proj_abc123",
    slug="chat-system-prompt",
    labels=["production"],
    variables={"user_name": "Alice"},
)

print(result.rendered.text)  # "Hello, Alice!"
```

## Features

- Prompt resolution with label-based version selection and Liquid template rendering
- Project label registry CRUD, reverse-lookup, and immutable event history
- Typed errors for auth, rate limiting, validation, and network failures
- Compatible with Python 3.10+

## Project label registry

The project label registry is the source of truth for which labels exist
on a project. Strict-mode projects reject `move_label` calls for labels
that are not in the registry; the SDK surfaces those as a typed
`PromptLabelNotRegisteredError`.

```python
from to11ai_sdk import create_client, PromptLabelNotRegisteredError

client = create_client(base_url="https://api.to11.ai", api_key="...")

# Register a new label
client.prompts.create_project_label(
    project_id="proj_abc123",
    label="staging",
    is_default=False,
    description="rolling staging pointer",
    display_color="amber",
)

# List active labels
labels = client.prompts.list_project_labels(project_id="proj_abc123")

# List prompts currently pointed at by a label
usages = client.prompts.list_project_label_usages(
    project_id="proj_abc123", label="production",
)

# Inspect the immutable move history at any scope
events = client.prompts.list_label_events(
    scope="project", project_id="proj_abc123", limit=50,
)

# Strict-mode-friendly move
try:
    client.prompts.move_label(
        project_id="proj_abc123",
        prompt_id="prompt_xyz",
        label="production",
        version_id="ver_42",
    )
except PromptLabelNotRegisteredError as exc:
    # exc.project_id, exc.label carry the structured payload
    print(f"Register {exc.label!r} first")
```

`update_project_label(description=None)` means "leave unchanged"; pass
`description=""` to clear it.

## Documentation

Full API reference and guides: <https://docs.to11.ai>

## License

MPL-2.0
