Synchronous client

Use TypeSafeClient to ask questions, list models, and configure synchronous TypeSafe API requests.

export function SdkSignature({children}) { async function copy(event) { const button = event.currentTarget; const code = button.parentElement.querySelector("pre code"); try { await navigator.clipboard.writeText(code.textContent); button.setAttribute("aria-label", "Signature copied"); button.dataset.copied = "true"; } catch { button.setAttribute("aria-label", "Copy failed; select the signature to copy"); } setTimeout(() => { button.setAttribute("aria-label", "Copy signature"); delete button.dataset.copied; }, 2000); } return

{children}

; }

typesafe\_sdk.TypeSafeClient

TypeSafeClient(\n *,\n api_key: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | None = None,\n model: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | None = None,\n retry: [RetryPolicy](../retries.md#typesafe_sdk.RetryPolicy) | None = None,\n timeout: [float](https://docs.python.org/3/builtins/functions.html#float)\n | httpx2.Timeout\n | None = None,\n headers: [Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str)] | None = None,\n transport: httpx2.BaseTransport\n | None = None,\n http_client: httpx2.[Client](https://pydantic.dev/docs/httpx2/api/api/#httpx2.Client) | None = None,\n base_url: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | None = None,\n)\n

Create an HTTP client for TypeSafe AI API.

Explicit options take precedence over environment variables; empty or whitespace-only environment values are ignored.

Tip

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. 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.

Raises:

• TypeSafeError –

The API key is missing or invalid, 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](sync.md#typesafe_sdk.Models) \n

An accessor for the Models API resource.

Examples:

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

system\_one

Implementation

system_one(\n state: [JSONContent](../types/common.md#typesafe_sdk.JSONContent),\n questions: [Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Question](../types/questions.md#typesafe_sdk.Question)],\n *,\n model: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | None = None,\n retry: [RetryPolicy](../retries.md#typesafe_sdk.RetryPolicy) | None = None,\n timeout: [float](https://docs.python.org/3/builtins/functions.html#float)\n | httpx2.Timeout\n | None = None,\n extra_headers: [Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str)]\n | None = None,\n extra_body: [Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [JSONValue](../types/common.md#typesafe_sdk.JSONValue) | None]\n | None = None,\n response_model: [type](https://docs.python.org/3/builtins/functions.html#type)[ResponseT]\n | None = None,\n) -> [SystemOneResponse](../types/responses.md#typesafe_sdk.SystemOneResponse) | ResponseT\n

Overload 1

system_one(\n state: [JSONContent](../types/common.md#typesafe_sdk.JSONContent),\n questions: [Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Question](../types/questions.md#typesafe_sdk.Question)],\n *,\n model: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | None = None,\n retry: [RetryPolicy](../retries.md#typesafe_sdk.RetryPolicy) | None = None,\n timeout: [float](https://docs.python.org/3/builtins/functions.html#float)\n | httpx2.Timeout\n | None = None,\n extra_headers: [Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str)]\n | None = None,\n extra_body: [Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [JSONValue](../types/common.md#typesafe_sdk.JSONValue) | None]\n | None = None,\n response_model: None = None,\n) -> [SystemOneResponse](../types/responses.md#typesafe_sdk.SystemOneResponse)\n

Overload 2

system_one(\n state: [JSONContent](../types/common.md#typesafe_sdk.JSONContent),\n questions: [Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Question](../types/questions.md#typesafe_sdk.Question)],\n *,\n model: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | None = None,\n retry: [RetryPolicy](../retries.md#typesafe_sdk.RetryPolicy) | None = None,\n timeout: [float](https://docs.python.org/3/builtins/functions.html#float)\n | httpx2.Timeout\n | None = None,\n extra_headers: [Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str)]\n | None = None,\n extra_body: [Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [JSONValue](../types/common.md#typesafe_sdk.JSONValue) | None]\n | None = None,\n response_model: [type](https://docs.python.org/3/builtins/functions.html#type)[ResponseT],\n) -> ResponseT\n

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 * SystemOneResponse | ResponseT –

name and model and token usage details when no custom model is supplied.

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(\n *,\n retry: [RetryPolicy](../retries.md#typesafe_sdk.RetryPolicy) | None = None,\n timeout: [float](https://docs.python.org/3/builtins/functions.html#float)\n | httpx2.Timeout\n | None = None,\n extra_headers: [Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str)]\n | None = None,\n) -> [ListModelsResponse](../types/responses.md#typesafe_sdk.ListModelsResponse)\n

List the models available to the account.

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, * ListModelsResponse –

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