Synchronous client

​

typesafe_sdk.TypeSafeClient

• api_key (str | None, default: None ) – Required API key; may be set via the TYPESAFE_API_KEY environment variable. Leading and trailing whitespace is stripped. Empty keys, internal whitespace, control characters, and non-ASCII characters are rejected.
• model (str | None, default: None ) – Model name; may be set via the TYPESAFE_DEFAULT_MODEL environment variable.
• retry (RetryPolicy | None, default: None ) – A RetryPolicy controlling retry behavior; see RetryPolicy for the available options and their defaults. Pass RetryPolicy(max_retries=0) to disable retries.
• timeout (float | httpx2.Timeout | None, default: None ) – Timeout for HTTP operations. Inherits http_client.timeout when supplied, otherwise the SDK default.
• headers (Mapping[str, str] | None, default: None ) – Additional request headers to set.
• transport (httpx2.BaseTransport | None, default: None ) – Optional custom HTTP transport, closed when this SDK client closes.
• http_client (httpx2.Client | None, default: None ) – Optional httpx2.Client; mutually exclusive with transport. Closed when this SDK client closes.
• base_url (str | None, default: None ) – API root; may be set via the TYPESAFE_BASE_URL environment variable.
• compression (Literal[‘zstd’, False] | None, default: None ) – Request body compression: "zstd", or False to send bodies uncompressed. Defaults to zstd when available.

• TypeSafeError – The API key is missing or invalid, the timeout is invalid, or zstd compression is unavailable.
• ValueError – Both transport and http_client are supplied.

from typesafe_sdk import Choice, Noul, TypeSafeClient

with TypeSafeClient() as client:
    result = client.system_one(
        state="I was charged twice. Please help.",
        questions={
            "billing": Noul(instructions="Is this about billing?"),
            "tone": Choice(
                instructions="What is the tone?",
                criteria={"calm": None, "angry": None},
            ),
        },
    )
    assert 0 <= result.nouls["billing"].noul <= 1
    assert result.choices["tone"].choice in {"calm", "angry"}

​

models

with TypeSafeClient() as client:
    models = client.models.list()

​

attach_assets

• assets (Asset | Sequence[Asset]) – An asset, or a sequence of them.

• TypeSafeError – An attached value is not an asset.

from pathlib import Path

from typesafe_sdk import Image, Noul, SystemOneResponse, TypeSafeClient


def inspect(client: TypeSafeClient, path: Path) -> SystemOneResponse:
    photo = Image(path)
    with client.attach_assets(photo):
        return client.system_one(
            state=f"Product: {photo}",
            questions={"damaged": Noul(instructions="Is the product damaged?")},
        )

​

system_one

• state (Content) – Text, an asset, a JSON object, or an array to evaluate. See state for details.
• questions (Mapping[str, Question]) – Nonempty mapping of names to question objects or raw dictionaries.
• model (str | None, default: None ) – Model override; None inherits the client default.
• assets (Mapping[str, Asset] | None, default: None ) – Assets keyed by the reference used for them in state or questions; see Attaching media assets.
• retry (RetryPolicy | None, default: None ) – An optional retry policy to override the client-level value for this call only.
• timeout (float | httpx2.Timeout | None, default: None ) – An optional timeout for http operations to override the client-level value for this call only, in seconds.
• extra_headers (Mapping[str, str] | None, default: None ) – Additional request headers to set.
• extra_body (Mapping[str, JSONValue | None] | None, default: None ) – Additional top-level request-body fields, shallow-merged over the body after state, model, questions, and assets are set. Merging is last-write-wins: a key that collides with those fields overrides it, and object values are replaced rather than deep-merged.
• response_model (type[ResponseT] | None, default: None ) – Optional Pydantic BaseModel type describing the JSON response body, including any nested answer models.

• SystemOneResponse | ResponseT – An instance of response_model, or SystemOneResponse with answers keyed by question
• SystemOneResponse | ResponseT – name and model and token usage details when no custom model is supplied.

• TypeSafeError – The request is invalid before it’s sent, such as empty questions or an unreadable asset.
• TypeSafeAPIError – The server returns an unsuccessful HTTP response after any retries.
• TypeSafeAPIConnectionError – The request cannot connect or times out after any retries.
• TypeSafeAPIResponseValidationError – The response body does not match the response model.

with TypeSafeClient() as client:
    result = client.system_one(
        state="I was charged twice. Please help.",
        questions={
            "billing": Noul(instructions="Is this about billing?"),
            "tone": Choice(
                instructions="What is the tone?",
                criteria={"calm": None, "angry": None},
            ),
        },
    )
    assert 0 <= result.nouls["billing"].noul <= 1
    assert result.choices["tone"].choice in {"calm", "angry"}

with TypeSafeClient() as client:
    result = client.system_one(
        state={"message": "I was charged twice. Please help."},
        questions={
            "billing": {"type": "noul", "instructions": "Is this about billing?"},
            "tone": {
                "type": "choice",
                "instructions": "What is the tone?",
                "criteria": {"calm": None, "angry": None},
            },
        },
    )
    assert 0 <= result.nouls["billing"].noul <= 1
    assert result.choices["tone"].choice in {"calm", "angry"}

​

close

close() -> None

​

Models resource

​

typesafe_sdk.Models

​

list

• retry (RetryPolicy | None, default: None ) – An optional retry policy to override the client-level value for this call only.
• timeout (float | httpx2.Timeout | None, default: None ) – Per-operation timeout override; None inherits the client setting.
• extra_headers (Mapping[str, str] | None, default: None ) – Overrides for additional request headers; authentication, SDK identification, and Accept remain protected.

• ListModelsResponse – A ListModelsResponse whose models holds each model’s name, description,
• ListModelsResponse – and release date.

• TypeSafeAPIError – The server returns an unsuccessful HTTP response after any retries.
• TypeSafeAPIConnectionError – The request cannot connect or times out after any retries.

from typesafe_sdk import TypeSafeClient

with TypeSafeClient() as client:
    models = client.models.list()