Install the Python SDK and make your first request: up and running in 10 minutes

You already got the key in the previous lesson. This lesson puts it to use: complete the typesafe-sdk installation and run the official example—one customer ticket, a single request asking three questions at once, and three answers: "which group to route it to, how frustrated the customer is, and whether it's urgent." The whole thing takes 10 minutes.

What you'll be able to do after this lesson

Complete the typesafe-sdk installation in an isolated virtual environment (Python 3.10+)
Run the official ticket three-question example and see the three lines of output technical / 0.67 / 0.99
Read choice, score, noul, as well as confidence and probabilities in the returned JSON
Know that the SDK reads environment variables automatically and handles rate-limit retries automatically, with no keys written in code
Know which lesson to check next when things don't run

Where you are stuck right now

You got the Key, but after installing with pip the import fails, and you can't tell whether it's a Python version or environment problem
The example runs, but the output is a blob of JSON and you don't know which field is the "answer"
You want to get it running first instead of chewing through the entire API documentation right away

When to use this technique

When you need to:

Call Jev from Python on your own computer and get your first real request working
A clean installation method that doesn't pollute the system Python

And you don't want to:

Install the SDK into the system Python and clash with other projects
Hand-write HTTP requests, auth headers, and retry logic from the start

🎒 Preparation before starting

The Key from the previous lesson is already stored in the environment variable TYPESAFE_API_KEY
Python 3.10 or higher (the official SDK's version requirement; check with python3 --version in the terminal)
pip is installed (the official documentation links to pip's official installation page; install it first if you don't have it)
Command line uses Bash (macOS / Linux / Windows WSL—the official quick start's commands are written for this environment)

Core idea

What to install. The official Python SDK's pip package name is typesafe-sdk, and its import name is typesafe_sdk. It wraps up "assembling HTTP requests, authentication, compression, and rate-limit retries," so you only write the state and the questions.

Why use venv. The official quick start's pip route is exactly "venv + pip": the virtual environment installs the SDK in the project directory's .venv, never touching the system Python, and deleting the folder is a clean uninstall.

What the first request looks like. The official example uses a customer ticket as the state and asks three questions in one request:

Question	Question type	Returned fields
Which group should handle this ticket	Choice	`choice` + `probabilities` for each option + `confidence`
How frustrated the customer sounds	Score	`score` (0–2, can fall between two levels) + `confidence`
Whether it's urgent	Noul	`noul` (probability of 0–1)

The three questions are evaluated in parallel against the same state and all returned at once—this is the core way Jev works, and the later parallel questions lesson takes it to the extreme.

Three things the SDK does for you.

Task	How the SDK does it
Authentication	Reads the environment variable `TYPESAFE_API_KEY` automatically
Model selection	`model="jev-latest"`; when not specified, the SDK also defaults to `jev-latest` (currently pointing to Jev 1.14)
Rate-limit retries	Retries automatically by default on `429`, with wait times lengthening each time, and honors `retry-after`

The standard for success. The official example's expected output is three lines:

text

technical
0.67
0.99

The official docs also remind you: these are example results, and the values may change with Jev versions.

Follow along

Step 1: create the project directory and confirm environment variables

Why: the official quick start begins from a clean directory; the Key must be in an environment variable for the SDK to read it automatically.

bash

mkdir typesafe-quickstart
cd typesafe-quickstart
export TYPESAFE_API_KEY="your-api-key"

Replace your-api-key with your Key (if you saved it in the previous lesson, you need to export it again in a newly opened terminal).

You should see: all three commands run without errors; echo $TYPESAFE_API_KEY can print your Key.

Step 2: Complete the typesafe-sdk installation (venv + pip)

Why: venv installs the SDK into the project's own .venv directory without polluting the system Python—this is the standard practice for the official pip route.

bash

python3 -m venv .venv
.venv/bin/pip install typesafe-sdk

You should see: pip lists the packages to install and reports success, with typesafe-sdk in the package list.

A .venv directory appears in the project folder

💡 For those used to uv

The official route also supports uv: uv init --bare followed by uv add typesafe-sdk. The full walkthroughs for uv, npm, and direct curl access are in the Alternative Installation Methods lesson.

Step 3: Write the official example route_ticket.py

Why: first get the official example running as-is, then modify it with your own content—this way, when troubleshooting, you always have a "known-good" baseline.

Use an editor to create route_ticket.py in the project directory, and paste in the complete example from the official quick start:

python

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

ticket = "Our API integration started returning 500 errors on every request about 20 minutes ago, and we can't process any customer orders until this is fixed."

with TypeSafeClient(model="jev-latest") as client:  # Reads TYPESAFE_API_KEY.
    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.choices["department"].choice)
print(response.scores["frustration"].score)
print(response.nouls["is_urgent"].noul)

You should see: the file is saved at typesafe-quickstart/route_ticket.py.

Step 4: Run it and get three answers

Why: this step is the goal of the whole lesson—your first real Jev call.

bash

.venv/bin/python route_ticket.py

Use .venv/bin/python instead of the system's python to make sure you're using the environment where the SDK was just installed.

You should see: three lines of output—

text

technical
0.67
0.99

I see three lines of output, the first being technical (the ticket is assigned to the technical team)

Step 5: Read and understand the full response

Why: print only output three values; in a real project you will most likely use probabilities and confidence to write branching logic.

The complete JSON response given in the official quick start (example values, subject to change with versions):

The complete JSON response of the official example

json

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "technical",
      "confidence": 1.0,
      "probabilities": {
        "technical": 1.0,
        "billing": 0.0,
        "sales": 0.0
      }
    },
    "frustration": {
      "type": "score",
      "score": 0.67,
      "confidence": 0.5,
      "legend": {
        "0": "Calm, just stating facts",
        "1": "Frustrated but civil",
        "2": "Very angry, strong language"
      },
      "probabilities": {
        "0": 0.33,
        "1": 0.67,
        "2": 0.0
      }
    },
    "is_urgent": {
      "type": "noul",
      "noul": 0.99
    }
  },
  "usage": {
    "input_tokens": 428,
    "output_tokens": 73
  }
}

Three things worth noting:

Field	Where	Meaning
`confidence`	In the Choice / Score answers	The model's confidence in this answer (Noul answers don't have this field)
`probabilities`	In each answer	The full probability distribution: department is 100% on `technical`
`usage`	Top level	This call's consumption: 428 input tokens, 73 output tokens (billing is based on input; output is free)

The "model": "jev-1.13.0" in the example JSON is the value from when the official documentation example was recorded; if you run jev-latest now, the model field in the response depends on the current model version. How to write branching with confidence is covered in detail in the Confidence lesson.

Checkpoint ✅

typesafe-sdk is installed in .venv, not the system Python
No API Key appears in my code (the SDK reads the environment variable automatically)
I got three lines of output and know they are the Choice / Score / Noul answers respectively
I know the answers are stored by question ID in response.choices / .scores / .nouls
I know the example values may change with versions, so no need to worry about 0.67 vs. 0.66

Pitfall warnings

❌ ModuleNotFoundError: No module named 'typesafe_sdk'

The package isn't installed in the Python you're currently using. The most common cause: running a project installed in .venv with the system python. The correct approach: run it with .venv/bin/python route_ticket.py as in the official example; for those accustomed to activating the environment first, source .venv/bin/activate followed by python also works (general venv usage; the official example doesn't include this step).

❌ Python version below 3.10

The official SDK requires Python 3.10 or higher. Check with python3 --version; if the version is too low, upgrade Python first, or rebuild the venv with a 3.10+ interpreter.

❌ It runs, but the values don't match 0.67 / 0.99

It's not broken—the official docs explicitly state that example results change with Jev versions. Check whether the structure is right: the first line is one of billing / technical / sales, the second line is a number in 0–2, and the third line is a number in 0–1. If the structure is right, it works.

❌ I modified the example and it no longer runs, and I don't know what broke

Return to the baseline: first get the official example running as-is, then change it one small step at a time—first the state text, then the questions, and finally the question types, running it after each change. If you're truly stuck, the Getting Started with Troubleshooting lesson covers each error one by one.

Advanced tips (optional)

Two sets of clients: synchronous and asynchronous. The SDK provides both TypeSafeClient (synchronous, used in this lesson) and AsyncTypeSafeClient (asynchronous), with identically named interfaces (system_one); switch to the async version for high-concurrency scenarios.

The SDK has optional add-ons. You can install with extras: http2 enables HTTP/2 support, pil sends Pillow images, and zstd compresses the request body on Python 3.13 and earlier. Image-related techniques are in the Box and Images lesson.

Don't want to use Python? The JavaScript / TypeScript SDK and direct API access via curl are both covered in the Alternative Installation Methods lesson.

Lesson summary

✅ typesafe-sdk installation complete: venv + pip, installed in the project's .venv, Python 3.10+.

✅ First request successful: one ticket, three questions, one response—technical / 0.67 / 0.99.

✅ You already know how to read the return values: answers are stored by question ID in choices / scores / nouls, with both probabilities and confidence included.

Key configuration fields recap:

Field	Recommended value	Description
Package name	`typesafe-sdk`	pip install name; the import name is `typesafe_sdk`
`model`	`jev-latest`	Alias, currently pointing to Jev 1.14; when not specified, the SDK defaults to it as well
`state`	String / JSON object / array of texts	This lesson used a single ticket string
`questions`	`{ID: Choice/Score/Noul(...)}`	IDs are chosen by you; answers are retrieved by ID from `choices` / `scores` / `nouls`
Environment variable	`TYPESAFE_API_KEY`	Read automatically by the SDK; no key is written in code

Next lesson preview

Python is not the only route: Installation alternatives: uv, npm, and curl direct API access.

You will learn:

Install the same SDK with two or three uv commands
Node.js 20+ Run the same example with @typesafe-ai/sdk
curl 7.76+ Access the API directly and see what the raw JSON looks like
Choose which route fits your project

Install the Python SDK and make your first request: up and running in 10 minutes ​

What you'll be able to do after this lesson ​

Where you are stuck right now ​

When to use this technique ​

🎒 Preparation before starting ​

Core idea ​

Follow along ​

Step 1: create the project directory and confirm environment variables ​

Step 2: Complete the typesafe-sdk installation (venv + pip) ​

Step 3: Write the official example route_ticket.py ​

Step 4: Run it and get three answers ​

Step 5: Read and understand the full response ​

Checkpoint ✅ ​

Pitfall warnings ​

❌ ModuleNotFoundError: No module named 'typesafe_sdk' ​

❌ Python version below 3.10 ​

❌ It runs, but the values don't match 0.67 / 0.99 ​

❌ I modified the example and it no longer runs, and I don't know what broke ​

Advanced tips (optional) ​

Lesson summary ​

Next lesson preview ​

Install the Python SDK and make your first request: up and running in 10 minutes

What you'll be able to do after this lesson

Where you are stuck right now

When to use this technique

🎒 Preparation before starting

Core idea

Follow along

Step 1: create the project directory and confirm environment variables

Step 2: Complete the typesafe-sdk installation (venv + pip)

Step 3: Write the official example route_ticket.py

Step 4: Run it and get three answers

Step 5: Read and understand the full response

Checkpoint ✅

Pitfall warnings

❌ ModuleNotFoundError: No module named 'typesafe_sdk'

❌ Python version below 3.10

❌ It runs, but the values don't match 0.67 / 0.99

❌ I modified the example and it no longer runs, and I don't know what broke

Advanced tips (optional)

Lesson summary

Next lesson preview