Python SDK: install, clients, system_one()

TL;DR pip install typesafe-sdk (import name typesafe_sdk), set TYPESAFE_API_KEY, then with TypeSafeClient() as client: client.system_one(state, questions). Both clients are keyword-only in their constructors; system_one(state, questions, *, model, retry, timeout, extra_headers, extra_body) returns a SystemOneResponse. The async twin is AsyncTypeSafeClient with await client.system_one(...) and aclose().

Install

The distribution name is typesafe-sdk; the import name is typesafe_sdk.

Package-name traps:

• typesafe-ai on PyPI (version 0.1.0) is a redirect shim that simply depends on typesafe-sdk. Installing it works, but you still import typesafe_sdk. Prefer typesafe-sdk directly.
• typesafe 0.9.1 on PyPI is an unrelated third-party package and is not TypeSafe AI.
• The cookbook pages use a pypi.typesafe.ai index for a cooksafe helper; that host returned 404 publicly as of 2026-09-17.

Then set the API key (create one at https://console.typesafe.ai/):

export TYPESAFE_API_KEY=...

Requirements

Runtime dependencies ([project].dependencies):

Project URLs: Homepage https://typesafe.ai, Documentation https://docs.typesafe.ai/sdk/python/, Changelog https://docs.typesafe.ai/sdk/python/changelog/, Repository https://github.com/typesafe-ai/typesafe-sdk-python, Issues .../issues.

Public exports

typesafe_sdk.__all__ (38 names, verbatim from src/typesafe_sdk/__init__.py):

__version__ is also importable (from typesafe_sdk import __version__) although it is not listed in __all__; it is resolved at import time with importlib.metadata.version("typesafe-sdk").

Everything else lives under typesafe_sdk._core / typesafe_sdk._schemas and is private. __init__.py ends with del _core, so typesafe_sdk._core is not bound as an attribute of the package after import even though the submodule itself is importable.

Clients

Two clients, identical surface except for async/await and the transport types:

Constructor

Both constructors are keyword-only (def __init__(self, *, ...)); there are no positional parameters.

TypeSafeClient(
    *,
    api_key: str | None = None,
    model: str | None = None,
    retry: RetryPolicy | None = None,
    timeout: float | httpx2.Timeout | None = None,
    headers: Mapping[str, str] | None = None,
    transport: httpx2.BaseTransport | None = None,
    http_client: httpx2.Client | None = None,
    base_url: str | None = None,
)

AsyncTypeSafeClient(
    *,
    api_key: str | None = None,
    model: str | None = None,
    retry: RetryPolicy | None = None,
    timeout: float | httpx2.Timeout | None = None,
    headers: Mapping[str, str] | None = None,
    transport: httpx2.AsyncBaseTransport | None = None,
    http_client: httpx2.AsyncClient | None = None,
    base_url: str | None = None,
)

Raises:

Resolution rules (from _core/config.py):

• Explicit arguments win over environment variables.
• Empty or whitespace-only environment values are ignored and fall back to the default.
• base_url is rstrip("/")-ed.
• timeout is validated by resolve_timeout: a non-httpx2.Timeout value must be finite and > 0.
• The resolved api_key is stored on a dataclass field with repr=False, as are the default headers, so it does not leak through repr().

Attributes and lifecycle

Context-manager usage is the documented default in every upstream example. Because close()/aclose() also close a user-supplied http_client, do not share one httpx2.Client across several TypeSafeClient instances whose lifetimes differ.

system_one()

system_one(
    state: JSONContent,
    questions: Mapping[str, Question],
    *,
    model: str | None = None,
    retry: RetryPolicy | None = None,
    timeout: float | httpx2.Timeout | None = None,
    extra_headers: Mapping[str, str] | None = None,
    extra_body: Mapping[str, JSONValue | None] | None = None,
) -> SystemOneResponse

The async version has the same signature and is async def, returning SystemOneResponse when awaited.

Returns SystemOneResponse — see Python SDK responses, answers, usage, models.

Raises:

The docs' "Raises" block for system_one lists only the empty-questions and empty-score-criteria cases; _core/questions.py additionally raises TypeSafeError for a malformed question dictionary and for a choice/score dict with no "criteria" key, and _core/transport.py raises it when the body cannot be encoded as JSON.

Wire request built

_core/endpoints.py:prepare_system_one sends POST {base_url}/v1/systemone with the body:

{"state": ..., "model": "...", "questions": {...}}

model is always present (client default when the per-call override is None), then extra_body is applied with body.update(extra_body). See HTTP API: POST /v1/systemone and GET /v1/models for the wire contract.

Headers the SDK sets

Set on every request from _core/transport.py:prepare (user headers/extra_headers are merged first, then these overwrite them — so authentication, Accept, and SDK identification cannot be overridden):

The response header x-typesafe-request-id is surfaced as response.request_id and error.request_id.

Environment variables

See TYPESAFE_* environment variables across SDKs and Python SDK retries, exceptions, constants for the constants module in full.

models resource

client.models is a cached property returning Models (sync) or AsyncModels (async). It has one method:

list(
    *,
    retry: RetryPolicy | None = None,
    timeout: float | httpx2.Timeout | None = None,
    extra_headers: Mapping[str, str] | None = None,
) -> ListModelsResponse

Issues GET {base_url}/v1/models. Returns ListModelsResponse whose .models is a tuple[ModelMetadata, ...] of name, description, release_date — see Python SDK responses, answers, usage, models and Models, aliases, pricing, rate limits, context.

from typesafe_sdk import TypeSafeClient

with TypeSafeClient() as client:
    for card in client.models.list().models:
        print(card.name, card.release_date, card.description)

Select a model when constructing a client:

client = TypeSafeClient(model="jev")

Note: "jev" is the upstream usage-guide sample verbatim (raw/docs/sdk__python__usage.md), but it is not among the names listed on Models, aliases, pricing, rate limits, context (jev-latest, jev-preview, jev-1.13.0). Prefer model="jev-latest" or an explicit versioned id, and confirm with client.models.list().

Logging

The SDK logs to the typesafe_sdk logger (logging.getLogger("typesafe_sdk")) and attaches a NullHandler plus a SensitiveHeadersFilter. It never configures handlers for you.

import logging

logging.getLogger("typesafe_sdk").setLevel(logging.DEBUG)

Or set TYPESAFE_LOG_LEVEL before importing the SDK; it is applied once at import.

Redaction: header names in {authorization, proxy-authorization, x-api-key, api-key, cookie, set-cookie}, plus any header name containing token or secret (case-insensitive), are replaced with ***. Request and response bodies are not redacted — debug will print your state and the model's answers.

The SDK also logs Ignoring answer %r with unrecognized type %r at WARNING when the API returns an answer kind this version does not model.

Forward compatibility

from typesafe_sdk import Noul, TypeSafeClient

with TypeSafeClient() as client:
    client.system_one(
        "I was charged twice.",
        {"billing": Noul(instructions="About billing?")},
        extra_body={"beam_width": 4},
    )

Complete examples

Sync, verbatim style from the upstream quickstart:

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state={"document": "I was charged twice. Please fix this ASAP."},
        questions={
            "billing": Noul(instructions="Is this ticket about billing?"),
            "tone": Choice(
                instructions="What is the customer's tone?",
                criteria={"calm": None, "frustrated": None, "angry": None},
            ),
            "urgency": Score(
                instructions="How urgent is this ticket?",
                criteria=["can wait", "this week", "today"],
            ),
        },
    )

print(response.nouls["billing"].noul)
print(response.choices["tone"].choice)
print(response.scores["urgency"].score)

Async:

import asyncio

from typesafe_sdk import AsyncTypeSafeClient, Choice, Noul, Score


async def main() -> None:
    async with AsyncTypeSafeClient() as client:
        result = await client.system_one(
            "I was charged twice. Please help ASAP.",
            {
                "billing": Noul(instructions="Is this about billing?"),
                "tone": Choice(
                    instructions="What is the tone?",
                    criteria={"calm": None, "angry": None},
                ),
                "urgency": Score(
                    instructions="How urgent is this?",
                    criteria=["low", "medium", "high"],
                ),
            },
        )
        print(
            result.nouls["billing"].noul,
            result.choices["tone"].choice,
            result.scores["urgency"].score,
        )


asyncio.run(main())

Per-call overrides plus error handling:

from typesafe_sdk import Noul, RetryPolicy, TypeSafeAPIError, TypeSafeClient

with TypeSafeClient(model="jev") as client:
    try:
        result = client.system_one(
            "I was charged twice.",
            {"billing": Noul(instructions="Is this about billing?")},
            model="jev-latest",
            retry=RetryPolicy(max_retries=3, backoff_max=0.2, timeout=1.0),
            timeout=5.0,
            extra_headers={"X-Request-Source": "support-bot"},
        )
    except TypeSafeAPIError as error:
        print(error.status, error.request_id)
    else:
        print(result.model, result.usage.input_tokens, result.request_id)

When to use / when not to use

• Use TypeSafeClient for scripts, sync web frameworks, and notebooks; use AsyncTypeSafeClient inside asyncio services and when fanning out many calls concurrently (see Speculative fan-out).
• Do not create a client per request: construction resolves config and builds an httpx2 client. Build one per process and reuse it.
• If you only need one call in one language-agnostic place, the raw HTTP API: POST /v1/systemone and GET /v1/models is equivalent; the SDK adds typed questions/answers and the default retry policy.

Version notes

• Version documented here: typesafe-sdk 0.6.0 (repo commit 420ef4ffb612d5a539a1e0f0fe883ff6770340af, 2026-09-15). See Python SDK changelog.
• 0.6.0 changed Score.criteria from an int-keyed dict to an ordered sequence — see Python SDK question types (Noul, Choice, Score).
• Usage.billing_units exists in the generated wire schema but not on the public Usage type; details in Python SDK responses, answers, usage, models.

Related

• Python SDK question types (Noul, Choice, Score) — Noul, Choice, Score and their dict forms
• Python SDK responses, answers, usage, models — SystemOneResponse, answers, usage, models
• Python SDK retries, exceptions, constants — RetryPolicy, exceptions, constants
• Python SDK changelog — release history
• HTTP API: POST /v1/systemone and GET /v1/models — the wire contract the SDK speaks
• TYPESAFE_* environment variables across SDKs — TYPESAFE_* across SDKs
• JavaScript/TypeScript SDK: install, client, choice/score/noul — the JS/TS equivalent
• system-one-adapter: LLM-backed drop-in for TypeSafeClient — LLM-backed drop-in for TypeSafeClient
• Quickstart: first call in HTTP, Python, JS — first call in HTTP, Python, JS
• State: what you send Jev — what state may contain
• Primitives: Choice, Score, Noul — Choice, Score, Noul

Sources

• raw/docs/sdk.md (https://docs.typesafe.ai/sdk.md)
• raw/docs/sdk__python.md (https://docs.typesafe.ai/sdk/python.md)
• raw/docs/sdk__python__usage.md (https://docs.typesafe.ai/sdk/python/usage.md)
• raw/docs/sdk__python__api.md (https://docs.typesafe.ai/sdk/python/api.md)
• raw/docs/sdk__python__api__clients__sync__client.md (https://docs.typesafe.ai/sdk/python/api/clients/sync/client.md)
• raw/docs/sdk__python__api__clients__async__client.md (https://docs.typesafe.ai/sdk/python/api/clients/async/client.md)
• raw/docs/sdk__python__api__clients__sync__models.md (https://docs.typesafe.ai/sdk/python/api/clients/sync/models.md)
• raw/docs/sdk__python__api__clients__async__models.md (https://docs.typesafe.ai/sdk/python/api/clients/async/models.md)
• raw/docs/sdk__python__api__constants.md (https://docs.typesafe.ai/sdk/python/api/constants.md)
• raw/github/typesafe-sdk-python/README.md, pyproject.toml, src/typesafe_sdk/init.py, src/typesafe_sdk/_core/{config,transport,endpoints,logging,constants}.py (https://github.com/typesafe-ai/typesafe-sdk-python @ 420ef4ffb612d5a539a1e0f0fe883ff6770340af)
• PyPI package facts (typesafe-sdk, typesafe-ai shim, unrelated typesafe) collected 2026-09-17 and recorded in CLAUDE.md