同步客户端

使用 TypeSafeClient 提问、列出模型，并配置同步的 TypeSafe API 请求。

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

为 TypeSafe AI API 创建一个 HTTP 客户端。

显式选项优先于环境变量；空值或只有空白的环境变量值会被忽略。

参数：

api_key (str | None, 默认：None ) –

必需的 API key；可以通过 TYPESAFE_API_KEY 环境变量设置。会去除首尾空白。空 key、内部空白、控制字符和非 ASCII 字符会被拒绝。
model (str | None, 默认：None ) –

模型名；可以通过 TYPESAFE_DEFAULT_MODEL 环境变量设置。
retry (RetryPolicy | None, 默认：None ) –

一个控制重试行为的 RetryPolicy；可用选项及其默认值见 RetryPolicy。传入 RetryPolicy(max_retries=0) 可禁用重试。
timeout (float | httpx2.Timeout | None, 默认：None ) –

HTTP 操作的超时时间。提供了 http_client.timeout 时继承它，否则用 SDK 默认值。
headers (Mapping[str, str] | None, 默认：None ) –

要设置的额外请求头。
transport (httpx2.BaseTransport | None, 默认：None ) –

可选的自定义 HTTP transport，在 SDK 客户端关闭时关闭。
http_client (httpx2.Client | None, 默认：None ) –

可选的 httpx2.Client；与 transport 互斥。在 SDK 客户端关闭时关闭。
base_url (str | None, 默认：None ) –

API 根地址；可以通过 TYPESAFE_BASE_URL 环境变量设置。

抛出：

TypeSafeError –

API key 缺失或无效，或者超时时间无效。
ValueError –

同时提供了 transport 和 http_client。

示例：

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

对 Models API 资源的访问器。

示例：

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

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

对文本或结构化状态回答具名问题。

详见 System One。

参数：

state (JSONContent) –

要评估的文本、JSON 对象或数组。详见状态。
questions (Mapping[str, Question]) –

从名字到问题对象或原始字典的非空映射。
model (str | None, 默认：None ) –

模型覆盖项；None 继承客户端默认值。
retry (RetryPolicy | None, 默认：None ) –

可选的重试策略，仅覆盖本次调用的客户端级取值。
timeout (float | httpx2.Timeout | None, 默认：None ) –

http 操作的可选超时时间，仅覆盖本次调用的客户端级取值，单位为秒。
extra_headers (Mapping[str, str] | None, 默认：None ) –

要设置的额外请求头。
extra_body (Mapping[str, JSONValue | None] | None, 默认：None ) –

额外的顶层请求体字段，在 state、model 和 questions 设置之后与请求体做浅合并。合并是后写者胜：与 state、model 或 questions 冲突的键会覆盖它们，对象值会被替换而不是深合并。
response_model (type[ResponseT] | None, 默认：None ) –

可选的 Pydantic BaseModel 类型，描述 JSON 响应体，包括任何嵌套的答案模型。

返回值：

SystemOneResponse | ResponseT –

未提供自定义模型时，为 response_model 的一个实例，或为带按问题名作键的答案、
SystemOneResponse | ResponseT –

以及模型和 token 用量信息的 SystemOneResponse。

抛出：

TypeSafeError –

问题为空，或某个 score 问题的 criteria 列表为空。
TypeSafeAPIError –

在任何重试之后，服务端仍返回不成功的 HTTP 响应。
TypeSafeAPIConnectionError –

在任何重试之后，请求仍无法连接或超时。
TypeSafeAPIResponseValidationError –

响应体与响应模型不匹配。

示例：

用具名参数创建问题：

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

释放网络资源并关闭底层的 HTTP 客户端，包括外部提供的那个。

Models 资源

通过 TypeSafeClient.models 访问。

typesafe_sdk.Models

访问账户可用的模型，通过 TypeSafeClient.models 到达。

list

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

列出账户可用的模型。

参数：

retry (RetryPolicy | None, 默认：None ) –

可选的重试策略，仅覆盖本次调用的客户端级取值。
timeout (float | httpx2.Timeout | None, 默认：None ) –

按操作的超时覆盖；None 继承客户端设置。
extra_headers (Mapping[str, str] | None, 默认：None ) –

对额外请求头的覆盖；认证、SDK 标识和 Accept 仍然受保护。

返回值：

ListModelsResponse –

一个 ListModelsResponse，其 models 保存每个模型的名字、描述，
ListModelsResponse –

以及发布日期。

抛出：

TypeSafeAPIError –

在任何重试之后，服务端仍返回不成功的 HTTP 响应。
TypeSafeAPIConnectionError –

在任何重试之后，请求仍无法连接或超时。

示例：

from typesafe_sdk import TypeSafeClient

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