Sync client - TypeSafe AI

typesafe_sdk.TypeSafeClient

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,
)

Create an HTTP client for TypeSafe AI API. Explicit options take precedence over environment variables; empty or whitespace-only environment values are ignored.

Logging setup The SDK logs to the typesafe_sdk logger; configure it through standard logging, or set TYPESAFE_LOG_LEVEL (debug, info, …) for a quick default. Secret headers are redacted from log output; request and response bodies are not.

Parameters:

api_key (str | None, default: None) – Required API key; may be set via the TYPESAFE_API_KEY environment variable.
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.

Raises:

TypeSafeError – The API key is missing or the timeout is invalid.
ValueError – Both transport and http_client are supplied.

Examples:

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

cached``property

models: Models

An accessor for the Models API resource. Examples:

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

system_one

Implementation
Overload 1
Overload 2

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,
    response_model: type[ResponseT] | None = None,
) -> SystemOneResponse | ResponseT

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,
    response_model: None = None,
) -> SystemOneResponse

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,
    response_model: type[ResponseT],
) -> ResponseT

Answer named questions about text or structured state. See System One for details.

Parameters:

state (JSONContent) – Text, 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.
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, and questions are set. Merging is last-write-wins: a key that collides with state, model, or questions 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.

Returns:

SystemOneResponse | ResponseT – An instance of response_model, or SystemOneResponse with answers keyed by question.

Raises:

TypeSafeError – Questions are empty or a score question’s criteria list is empty.
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.

Examples:

Create questions with named arguments:

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

Pass questions as dictionaries:

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

Release network resources and close the underlying HTTP client, including a supplied one.

Models resource

Reached through TypeSafeClient.models.

typesafe_sdk.Models

Access to the models available to the account, reached through TypeSafeClient.models.

list

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

Parameters:

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.

Returns:

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

Raises:

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

Examples:

from typesafe_sdk import TypeSafeClient

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