同步客户端

使用 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 客户端。

显式选项优先于环境变量；为空或仅含空白字符的环境变量值会被忽略。

💡提示

日志设置

SDK 会向 typesafe_sdk 记录器输出日志；可通过标准 logging 进行配置，或设置 TYPESAFE_LOG_LEVEL（debug、info 等）以获得快速默认值。机密请求头会在日志输出中被脱敏；请求与响应正文则不会。

参数：

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

必需的 API 密钥；可通过 TYPESAFE_API_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 密钥缺失或无效，或超时设置无效。
ValueError –

同时提供了 transport 和 http_client。

示例：

python

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 资源的访问器。

示例：

python

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
</pre></div></div><div class="tab-pane" data-title="Overload 2">    <div class="sdk-signature"><pre> 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

</pre></div></div></div>
针对文本或结构化状态回答具名问题。
详情请参阅 System One。
参数：
state (JSONContent) –
要评估的文本、JSON 对象或数组。详情请参阅 state。
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 之后浅合并到请求体上。合并采取"后写覆盖"（last-write-wins）策略：与 state、model 或 questions 冲突的键会覆盖原值，对象值会被整体替换而非深度合并。
response_model (type[ResponseT] | None, 默认值：None ) –
可选的 Pydantic BaseModel 类型，用于描述 JSON 响应体，包括所有嵌套的答案模型。
返回：
SystemOneResponse | ResponseT –
response_model 的实例，或 SystemOneResponse，其中的答案以问题
SystemOneResponse | ResponseT –
名称为键，并在未提供自定义模型时附带模型与 token 用量详情。
抛出异常：
TypeSafeError –
问题为空，或某个 score 问题的 criteria 列表为空。
TypeSafeAPIError –
在所有重试之后，服务器仍返回不成功的 HTTP 响应。
TypeSafeAPIConnectionError –
在所有重试之后，请求仍无法连接或超时。
TypeSafeAPIResponseValidationError –
响应体与响应模型不匹配。
示例：
使用具名参数创建问题：
pythonwith 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"}
以字典形式传入问题：
pythonwith 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

pythonclose() -> 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 –
在所有重试之后，请求仍无法连接或超时。
示例：
pythonfrom typesafe_sdk import TypeSafeClient

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