Python guide

Python ≥ 3.10 projects should prefer the official SDK; dependency-free environments can call the same endpoint with the standard library.

Option 1: the official SDK

Install

pip install typesafe-sdk

example.py

from typesafe_sdk import Choice, Noul, TypeSafeClient  # AsyncTypeSafeClient is the async twin

with TypeSafeClient() as client:  # reads TYPESAFE_API_KEY; the model defaults to jev-latest
    response = client.system_one(
        state="Hi, my Stripe integration keeps failing. Please refund my subscription.",
        questions={
            "department": Choice(
                instructions="Which team should handle this",
                criteria={
                    "billing": "Payment or subscription issues",
                    "technical": "Bugs or integration problems",
                },
            ),
            "asks_refund": Noul(
                instructions="The customer explicitly requests a refund",
            ),
        },
    )

department = response.choices["department"]
print(department.choice, department.confidence)
print(response.nouls["asks_refund"].noul)

The SDK provides TypeSafeClient / AsyncTypeSafeClient and the Choice / Score / Noul question types; it also accepts plain question dictionaries with a type key (the same shape as the JSON in the API reference). The model defaults to jev-latest; pass model= to system_one to pin a version. A built-in RetryPolicy covers attempts, retryable statuses, and backoff. Repo: typesafe-ai/typesafe-sdk-python (MIT, 178★, verified 2026-09-22).

There is also the official system-one-adapter-python: it emulates TypeSafeClient on top of ordinary LLM APIs — handy for A/B comparisons or fallbacks (see Ecosystem).

Option 2: standard-library urllib

The complete runnable example, triage.py, is a direct download (standard library only):

Download and run in simulated mode (offline, no key needed)

curl -O https://typesafe-jev.com/examples/python/triage.py
TYPESAFE_USE_FIXTURE=1 python3 triage.py

Real call (requires a key)

TYPESAFE_API_KEY=your-key python3 triage.py

The example asks a department Choice, a frustration Score, and a refund Noul in one request, then applies confidence thresholds for auto-assign versus human triage. The core:

triage.py (excerpt)

request = urllib.request.Request(
    API_URL,
    data=json.dumps(PAYLOAD).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(request, timeout=30) as response:
    return json.loads(response.read().decode("utf-8"))

About the simulated mode

Fixture mode returns a fixed simulated response (output prefixed [SIMULATED]) to demonstrate parsing and routing; it is not a real API call.

Where your logic lives

The Python side follows the same official pattern: the model answers questions; thresholds, routing, and merge weights stay in your code (Confidence-gated routing, via the llms.txt index). The example’s CONFIDENCE_THRESHOLD = 0.7 is a demo value — calibrate on your own labeled samples; the full walkthrough is Ticket triage.

Related pages

API reference · JavaScript guide · Capabilities