Official Python SDK Guide (typesafe-sdk)

What It Solves & Overview

The official typesafe-sdk package provides idiomatic Python bindings for TypeSafe AI. It features both synchronous (TypeSafeClient) and asynchronous (AsyncTypeSafeClient) interfaces, automatic connection pooling, built-in retries, and strict Pydantic integration for input state and output probability models.

Suitability & Fit

When to Use

FastAPI, Django, Flask, or Celery backend systems requiring high-throughput, low-latency decision routing.
High-concurrency async workloads where speculative decision fan-out is evaluated in parallel.
Python AI agent pipelines where structured decision gating precedes expensive generative agent steps.

When NOT to Use

Scenarios requiring subjective generative text, multi-turn roleplay conversations, or summarization.
Offline air-gapped environments without mock adapters.

Installation & Setup

pip install typesafe-sdk
# or via uv
uv add typesafe-sdk

Offline Contract Verification Example

Verification Notice: The code snippet below demonstrates local structural validation of inputs and choice schemas without requiring live network credentials. Real-world API execution requires active connectivity and API credentials.

from dataclasses import dataclass
from typing import List

# Offline contract schema demonstration (does not call remote LLM)
@dataclass
class OfflineRoutingContract:
    user_tier: str
    risk_score: float
    options: List[str]

def validate_offline_contract(contract: OfflineRoutingContract) -> bool:
    assert contract.user_tier in ['free', 'pro', 'enterprise']
    assert 0.0 <= contract.risk_score <= 1.0
    return True

contract = OfflineRoutingContract(user_tier='enterprise', risk_score=0.15, options=['pass', 'review'])
print('Python contract verified offline:', validate_offline_contract(contract))

Prerequisites & Operational Boundaries

Prerequisites

Python 3.10 or newer.
TYPESAFE_API_KEY environment variable configured.

Known Limitations

Real evaluations require live network roundtrips to the TypeSafe decision engine API.
No local weights execution included in the SDK package.

Official Source Provenance

This guide is compiled and fact-checked against official upstream assets: