to11ai-sdk 0.0.2__tar.gz

to11ai_sdk-0.0.2/.gitignore

@@ -0,0 +1,51 @@
+.worktrees/
+.worktree/
+.claude/worktrees/
+node_modules/
+dist/
+.turbo/
+test-results/
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+*.log
+*.tsbuildinfo
+.env
+.env.local
+# Per-environment overrides — never commit; secrets land in these.
+# (`.env.example` is allowlisted by being explicitly tracked.)
+.env.stg
+.env.staging
+.env.production
+.vercel/
+
+# Agent skills caches (regenerated from skills-lock.json)
+**/.junie/
+**/.windsurf/
+
+# Agent local settings
+.claude/settings.local.json
+.claude/worktrees
+.claude/scheduled_tasks.lock
+
+# Entire.io (AI session tracking)
+.entire/settings.local.json
+.entire/metadata/
+.entire/tmp/
+.entire/logs/
+.entire/current_session
+# Husky hook backups the entire plugin writes when it overlays its own
+# wrappers — local-only, regenerated on plugin (re)install.
+**/*.pre-entire
+
+# Stray per-example lockfiles. The examples/ workspace ships a single
+# `examples/bun.lock`; per-subfolder lockfiles only appear when someone
+# accidentally runs `bun install` inside an example dir, and they shadow
+# the workspace resolution.
+examples/*/bun.lock
+
+# Not tracked: ClickHouse entrypoint injects a plaintext password into this file
+# on every container start, and we don't want those changes committed to git.
+docker/clickhouse/users.d/default-user.xml
+.notes.md
+.playwright-mcp/

to11ai_sdk-0.0.2/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.0.2](https://github.com/to11ai/platform/compare/python-sdk-v0.0.1...python-sdk-v0.0.2) (2026-05-06)
+
+
+### Documentation
+
+* **python-sdk:** add README + wire into pyproject ([#552](https://github.com/to11ai/platform/issues/552)) ([0e0d48f](https://github.com/to11ai/platform/commit/0e0d48febbdbcaa229bc0d076111c0f7d782d5bf))

to11ai_sdk-0.0.2/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: to11ai-sdk
+Version: 0.0.2
+Summary: Python SDK for the to11.ai platform
+Project-URL: Homepage, https://to11.ai
+Project-URL: Repository, https://github.com/to11ai/platform
+License-Expression: MIT
+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
+- Typed errors for auth, rate limiting, validation, and network failures
+- Compatible with Python 3.10+
+
+## Documentation
+
+Full API reference and guides: <https://docs.to11.ai>
+
+## License
+
+MIT

to11ai_sdk-0.0.2/README.md

@@ -0,0 +1,45 @@
+# 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
+- Typed errors for auth, rate limiting, validation, and network failures
+- Compatible with Python 3.10+
+
+## Documentation
+
+Full API reference and guides: <https://docs.to11.ai>
+
+## License
+
+MIT

to11ai_sdk-0.0.2/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "to11ai-sdk"
+version = "0.0.2"
+description = "Python SDK for the to11.ai platform"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = []
+
+[project.urls]
+Homepage = "https://to11.ai"
+Repository = "https://github.com/to11ai/platform"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/to11ai_sdk"]
+
+[tool.uv]
+dev-dependencies = [
+    "pytest>=8.0",
+]

to11ai_sdk-0.0.2/src/to11ai_sdk/__init__.py

@@ -0,0 +1,47 @@
+from .client import To11aiClient, create_client
+from .errors import (
+    To11aiApiError,
+    To11aiAuthError,
+    To11aiError,
+    To11aiNetworkError,
+    To11aiRateLimitError,
+    To11aiValidationError,
+)
+from .gateway import gateway_auth_headers, gateway_prompt_headers
+from .prompts.resource import PromptResource
+from .prompts.types import (
+    ChatMessage,
+    ChatRendered,
+    PaginatedResult,
+    PaginationInfo,
+    Prompt,
+    PromptLabelPointer,
+    PromptVersion,
+    RenderedPrompt,
+    ResolvedPrompt,
+    TextRendered,
+)
+
+__all__ = [
+    "create_client",
+    "To11aiClient",
+    "PromptResource",
+    "gateway_auth_headers",
+    "gateway_prompt_headers",
+    "ResolvedPrompt",
+    "Prompt",
+    "PromptVersion",
+    "PromptLabelPointer",
+    "PaginatedResult",
+    "PaginationInfo",
+    "ChatMessage",
+    "TextRendered",
+    "ChatRendered",
+    "RenderedPrompt",
+    "To11aiError",
+    "To11aiApiError",
+    "To11aiAuthError",
+    "To11aiNetworkError",
+    "To11aiRateLimitError",
+    "To11aiValidationError",
+]

to11ai_sdk-0.0.2/src/to11ai_sdk/client.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .prompts.resource import PromptResource
+from .transport import Transport, TransportConfig
+
+
+@dataclass
+class To11aiClient:
+    prompts: PromptResource
+
+
+def create_client(
+    *,
+    api_key: str,
+    base_url: str,
+    timeout_s: float = 30.0,
+    max_retries: int = 3,
+    ttl_seconds: int = 300,
+    max_cache_entries: int = 100,
+) -> To11aiClient:
+    if not api_key:
+        raise ValueError("api_key must not be empty")
+    if not base_url:
+        raise ValueError("base_url must not be empty")
+    transport = Transport(TransportConfig(base_url=base_url, api_key=api_key, timeout_s=timeout_s, max_retries=max_retries))
+    return To11aiClient(prompts=PromptResource(transport, ttl_seconds=ttl_seconds, max_cache_entries=max_cache_entries))

to11ai_sdk-0.0.2/src/to11ai_sdk/errors.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class To11aiError(Exception):
+    """Base class for all to11ai SDK errors."""
+
+
+class To11aiApiError(To11aiError):
+    """Raised when the API returns a non-2xx response."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        error_code: Optional[str] = None,
+        details: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+        self.details = details
+
+
+class To11aiAuthError(To11aiApiError):
+    """Raised on 401 or 403 responses."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        error_code: Optional[str] = None,
+        details: Any = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, error_code=error_code, details=details)
+
+
+class To11aiRateLimitError(To11aiApiError):
+    """Raised on 429 responses."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retry_after_seconds: Optional[float] = None,
+        error_code: Optional[str] = None,
+        details: Any = None,
+    ) -> None:
+        super().__init__(message, status_code=429, error_code=error_code, details=details)
+        self.retry_after_seconds = retry_after_seconds
+
+
+class To11aiValidationError(To11aiApiError):
+    """Raised on 400 responses."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        error_code: Optional[str] = None,
+        details: Any = None,
+    ) -> None:
+        super().__init__(message, status_code=400, error_code=error_code, details=details)
+
+
+class To11aiNetworkError(To11aiError):
+    """Raised on network failure or timeout."""
+
+    def __init__(self, message: str, *, cause: Optional[BaseException] = None) -> None:
+        super().__init__(message)
+        if cause is not None:
+            self.__cause__ = cause

to11ai_sdk-0.0.2/src/to11ai_sdk/gateway.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from .prompts.types import ResolvedPrompt
+
+
+def gateway_auth_headers(*, api_key: str, project_id: str) -> dict[str, str]:
+    """
+    Build auth headers required for every request through the to11 gateway.
+
+    Example::
+
+        headers = gateway_auth_headers(api_key=api_key, project_id=project_id)
+        response = anthropic_client.messages.create(..., extra_headers=headers)
+    """
+    return {
+        "x-to11-authorization": f"Bearer {api_key}",
+        "x-to11-project-id": project_id,
+    }
+
+
+def gateway_prompt_headers(prompt: ResolvedPrompt) -> dict[str, str]:
+    """
+    Build prompt provenance headers from a resolved prompt.
+
+    Omits ``x-to11-prompt-labels`` when the prompt has no labels —
+    the gateway rejects empty header values.
+
+    Example::
+
+        prompt = client.prompts.resolve(project_id=..., slug="my-prompt", labels=["production"])
+        headers = gateway_prompt_headers(prompt)
+        response = anthropic_client.messages.create(..., extra_headers=headers)
+    """
+    headers: dict[str, str] = {
+        "x-to11-prompt-id": prompt.prompt_id,
+        "x-to11-prompt-version": str(prompt.version),
+    }
+    if prompt.labels:
+        headers["x-to11-prompt-labels"] = ",".join(prompt.labels)
+    return headers

to11ai_sdk-0.0.2/src/to11ai_sdk/prompts/resource.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import copy
+import json
+import threading
+import time as _time
+from typing import Any, Optional
+from urllib.parse import quote
+
+from ..errors import To11aiNetworkError
+from ..transport import Transport
+from .types import (
+    PaginatedResult, PaginationInfo, Prompt, PromptLabelPointer,
+    PromptVersion, ResolvedPrompt,
+)
+
+DEFAULT_TTL_SECONDS = 300
+DEFAULT_MAX_ENTRIES = 100
+
+
+def _build_cache_key(project_id: str, slug: str, labels: list[str], variables: Optional[dict[str, Any]] = None) -> str:
+    def _sort(obj: Any) -> Any:
+        if isinstance(obj, dict):
+            return {k: _sort(v) for k, v in sorted(obj.items())}
+        if isinstance(obj, list):
+            return [_sort(v) for v in obj]
+        return obj
+    vars_part = json.dumps(_sort(variables), sort_keys=True) if variables is not None else None
+    return f"{json.dumps(project_id)}|{json.dumps(slug)}|{json.dumps(sorted(labels))}|{json.dumps(vars_part)}"
+
+
+class _CacheEntry:
+    __slots__ = ("expires_at", "value")
+    def __init__(self, value: ResolvedPrompt, expires_at: float) -> None:
+        self.value = value
+        self.expires_at = expires_at
+
+
+class _Cache:
+    def __init__(self, ttl_s: int, max_entries: int) -> None:
+        self._ttl = ttl_s
+        self._max = max_entries
+        self._store: dict[str, _CacheEntry] = {}
+        self._lock = threading.Lock()
+
+    def get(self, key: str) -> Optional[ResolvedPrompt]:
+        with self._lock:
+            entry = self._store.get(key)
+            if entry is None:
+                return None
+            if _time.time() > entry.expires_at:
+                self._store.pop(key, None)
+                return None
+            del self._store[key]
+            self._store[key] = entry
+            return copy.deepcopy(entry.value)
+
+    def set(self, key: str, value: ResolvedPrompt) -> None:
+        if self._max <= 0:
+            return
+        with self._lock:
+            self._store.pop(key, None)
+            while len(self._store) >= self._max:
+                del self._store[next(iter(self._store))]
+            self._store[key] = _CacheEntry(value=copy.deepcopy(value), expires_at=_time.time() + self._ttl)
+
+
+def _prompts_path(project_id: str) -> str:
+    return f"/v1/projects/{quote(project_id, safe='')}/prompts"
+
+
+def _prompt_path(project_id: str, prompt_id: str) -> str:
+    return f"{_prompts_path(project_id)}/{quote(prompt_id, safe='')}"
+
+
+def _unwrap(envelope: dict[str, Any]) -> Any:
+    data = envelope.get("data")
+    if data is None:
+        raise RuntimeError("API returned success but data is null")
+    return data
+
+
+class PromptResource:
+    def __init__(self, transport: Transport, ttl_seconds: int = DEFAULT_TTL_SECONDS, max_cache_entries: int = DEFAULT_MAX_ENTRIES) -> None:
+        self._transport = transport
+        self._cache = _Cache(ttl_s=ttl_seconds, max_entries=max_cache_entries)
+
+    def create(self, *, project_id: str, name: str, slug: str, description: Optional[str] = None, tags: Optional[list[str]] = None) -> Prompt:
+        body: dict[str, Any] = {"name": name, "slug": slug}
+        if description is not None:
+            body["description"] = description
+        if tags is not None:
+            body["tags"] = tags
+        return Prompt.from_dict(_unwrap(self._transport.request("POST", _prompts_path(project_id), body=body)))
+
+    def list(self, *, project_id: str, status: Optional[str] = None, sort_by: Optional[str] = None, tags: Optional[str] = None, page: Optional[int] = None, limit: Optional[int] = None) -> PaginatedResult:
+        query: dict[str, Any] = {}
+        if status is not None:
+            query["status"] = status
+        if sort_by is not None:
+            query["sortBy"] = sort_by
+        if tags is not None:
+            query["tags"] = tags
+        if page is not None:
+            query["page"] = page
+        if limit is not None:
+            query["limit"] = limit
+        envelope = self._transport.request("GET", _prompts_path(project_id), query=query)
+        raw = _unwrap(envelope)
+        if isinstance(raw, list):
+            items = [Prompt.from_dict(d) for d in raw]
+            pag_data = envelope.get("pagination") or {"page": 1, "limit": len(items), "total": len(items), "totalPages": 1}
+        else:
+            items = [Prompt.from_dict(d) for d in raw.get("items", [])]
+            pag_data = envelope.get("pagination") or raw.get("pagination") or {"page": 1, "limit": len(items), "total": len(items), "totalPages": 1}
+        return PaginatedResult(items=items, pagination=PaginationInfo.from_dict(pag_data))
+
+    def get(self, *, project_id: str, prompt_id: str) -> Prompt:
+        return Prompt.from_dict(_unwrap(self._transport.request("GET", _prompt_path(project_id, prompt_id))))
+
+    def update(self, *, project_id: str, prompt_id: str, name: Optional[str] = None, description: Optional[str] = None, tags: Optional[list[str]] = None) -> Prompt:
+        body: dict[str, Any] = {}
+        if name is not None:
+            body["name"] = name
+        if description is not None:
+            body["description"] = description
+        if tags is not None:
+            body["tags"] = tags
+        return Prompt.from_dict(_unwrap(self._transport.request("PATCH", _prompt_path(project_id, prompt_id), body=body)))
+
+    def archive(self, *, project_id: str, prompt_id: str) -> Prompt:
+        return Prompt.from_dict(_unwrap(self._transport.request("DELETE", _prompt_path(project_id, prompt_id))))
+
+    def create_version(self, *, project_id: str, prompt_id: str, format: str, template_json: Any, variables_schema: Any, model_config: Any = None, changelog: Optional[str] = None) -> PromptVersion:  # noqa: A002
+        body: dict[str, Any] = {"format": format, "templateJson": template_json, "variablesSchema": variables_schema}
+        if model_config is not None:
+            body["modelConfig"] = model_config
+        if changelog is not None:
+            body["changelog"] = changelog
+        return PromptVersion.from_dict(_unwrap(self._transport.request("POST", f"{_prompt_path(project_id, prompt_id)}/versions", body=body)))
+
+    def list_versions(self, *, project_id: str, prompt_id: str) -> list[PromptVersion]:
+        return [PromptVersion.from_dict(d) for d in _unwrap(self._transport.request("GET", f"{_prompt_path(project_id, prompt_id)}/versions"))]
+
+    def get_version(self, *, project_id: str, prompt_id: str, version_number: int) -> PromptVersion:
+        return PromptVersion.from_dict(_unwrap(self._transport.request("GET", f"{_prompt_path(project_id, prompt_id)}/versions/{quote(str(version_number), safe='')}")))
+
+    def move_label(self, *, project_id: str, prompt_id: str, label: str, version_id: str, reason: Optional[str] = None) -> PromptLabelPointer:
+        body: dict[str, Any] = {"versionId": version_id}
+        if reason is not None:
+            body["reason"] = reason
+        return PromptLabelPointer.from_dict(_unwrap(self._transport.request("PUT", f"{_prompt_path(project_id, prompt_id)}/labels/{quote(label, safe='')}", body=body)))
+
+    def list_labels(self, *, project_id: str, prompt_id: str) -> list[PromptLabelPointer]:
+        return [PromptLabelPointer.from_dict(d) for d in _unwrap(self._transport.request("GET", f"{_prompt_path(project_id, prompt_id)}/labels"))]
+
+    def resolve(self, *, project_id: str, slug: str, labels: list[str], variables: Optional[dict[str, Any]] = None, cache: bool = True, fallback: Optional[ResolvedPrompt] = None) -> ResolvedPrompt:
+        key = _build_cache_key(project_id, slug, labels, variables)
+        if cache:
+            cached = self._cache.get(key)
+            if cached is not None:
+                return cached
+        try:
+            body: dict[str, Any] = {"slug": slug, "labels": labels}
+            if variables is not None:
+                body["variables"] = variables
+            result = ResolvedPrompt.from_dict(_unwrap(self._transport.request("POST", f"{_prompts_path(project_id)}:resolve", body=body)))
+            if cache:
+                self._cache.set(key, result)
+            return result
+        except To11aiNetworkError:
+            if fallback is not None:
+                return fallback
+            raise