What package do I install for Jev in Python?

typesafe-sdk, via pip or uv. Official docs require Python >= 3.10.

TypeSafeClient is sync. AsyncTypeSafeClient is the async client. Both call the same HTTP API.

Jev Python Tutorial | Jev AI Hub

Install typesafe-sdk 0.7.5 and call TypeSafe Jev from Python with Choice, Score, and Noul questions.

This tutorial is the Python path into Jev. It is not a copy of the SDK reference. For request fields see the API guide.

Install

pip install typesafe-sdk==0.7.5

uv add typesafe-sdk

Official quickstart: Python >= 3.10. Set TYPESAFE_API_KEY.

Which release you are installing

SDK release notes checked on 2026-10-20; the text example remains a documented template, not a live API test:

Version	Date	What it changes for callers
0.7.5	2026-10-14	Image assets, Box, and default zstd request compression.
0.7.4	2026-10-09	Serialize non-finite numbers as strings.
0.7.3	2026-10-09	TLS concurrency fix, request validation, and connection-pool improvements.
0.7.2	2026-09-26	Optional extra `typesafe-sdk[http2]`. No other code change is listed.
0.7.1	2026-09-21	The API key is checked before the request and kept out of logged exceptions. Gateway examples were added.
0.7.0	2026-09-18	Breaking: serialization moved from msgspec to pydantic. `system_one` accepts `response_model`.
0.6.0	2026-09-15	Breaking: `Score.criteria` is an ordered list, not a dict keyed by integers.

pip install typesafe-sdk follows the current release. The Score examples below already use a list. A 0.5.7 call shaped like Score(..., criteria={0: "low", 1: "high"}) needs to become criteria=["low", "high"]. Index 0 is still the lowest level.

The JavaScript package is separate; release 0.7.0 requires Node.js 22+. See the TypeScript tutorial.

First sync call

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

ticket = (
    "Hi, I have been trying to connect my Stripe account for 3 days "
    "and the integration keeps failing. I am losing sales. Please help ASAP."
)

with TypeSafeClient() as client:
    response = client.system_one(
        state=ticket,
        questions={
            "department": Choice(
                instructions="Which team should handle this",
                criteria={
                    "billing": "Payment or subscription issues",
                    "technical": "Bugs or integration problems",
                    "sales": "Pricing or account questions",
                },
            ),
            "frustration": Score(
                instructions="How frustrated the customer appears",
                criteria=[
                    "Calm, just stating facts",
                    "Frustrated but civil",
                    "Very angry, strong language",
                ],
            ),
            "is_urgent": Noul(
                instructions="The message conveys urgency or time-sensitivity",
            ),
        },
    )

print(response.answers["department"].choice)
print(response.answers["frustration"].score)
print(response.answers["is_urgent"].noul)
print(response.model)

Some SDK examples also expose response.nouls, response.choices, and response.scores. Prefer the typed accessors your installed version documents.

Async

from typesafe_sdk import AsyncTypeSafeClient, Choice, Noul, Score

async def main() -> None:
    async with AsyncTypeSafeClient() as client:
        response = await client.system_one(
            state={"document": "I was charged twice. Please fix this ASAP."},
            questions={
                "billing": Noul(instructions="Is this ticket about billing?"),
                "tone": Choice(
                    instructions="What is the customer's tone?",
                    criteria={"calm": None, "frustrated": None, "angry": None},
                ),
                "urgency": Score(
                    instructions="How urgent is this ticket?",
                    criteria=["can wait", "this week", "today"],
                ),
            },
        )
    print(response.answers["billing"].noul)

Structured state

state = {
    "ticket_message": "My flight was cancelled. Can I get a refund?",
    "refund_policy": "Cancelled flights are eligible for a full refund.",
}

questions = {
    "refund_requested": Noul(
        instructions="Does `ticket_message` request a refund?",
    )
}

Backticks plus paths are the official way to point at fields. See Choice when you add routing.

Errors and retries

Official HTTP errors: 401, 422, 429, 529. The Python SDK documents RetryPolicy and retries retryable statuses by default. Do not write your own tight retry loop around 422.

Pydantic AI

Pydantic documents a TypeSafeModel for agents whose job is a decision. Each field of the output_type becomes one Jev question, and the prompt is the state. That client is Pydantic's, not typesafe-sdk:

pip install "pydantic-ai-slim[typesafe]"

Set TYPESAFE_API_KEY. Pydantic's page says jev-latest moves when TypeSafe ships a release, and that a tuned threshold should pin jev-1.13.0. Their reference is the source for the class name and install extra: TypeSafe (Jev).

When to use the Python SDK

Backend workers, notebooks, and FastAPI services that already live in Python.

When not to

Browser code — keep the key on a server. One-off probes can stay on cURL.

Common mistakes

Installing a similarly named package that is not typesafe-sdk. Pydantic AI's extra is a different package.
Passing Score.criteria as {0: "low", 1: "high"} on 0.6.0 or newer. Use a list.
Putting the English question only in the dict key.
Comparing floats from two different model versions without logging response.model.
Load-testing without reading pricing.

Next: examples or the same workflow in TypeScript.

Jev Python Tutorial

Quick answer