同步客戶端

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