## 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](/content/site-root.html). 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](https://docs.typesafe.ai/concepts/system-one) for details.

### Parameters:

- **`state`** (`JSONContent`) – Text, a JSON object, or an array to evaluate. See [state](https://docs.typesafe.ai/concepts/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`](https://docs.typesafe.ai/sdk/python/api/clients/sync#typesafe_sdk.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()
```