How to Get Started With Jev in Python

Prerequisites

Jev is a model by TypeSafe AI, and like many AI companies, TypeSafe AI publishes a Python SDK for its model. Instead of sending a prompt and getting prose back, as you do with LLMs like Claude or ChatGPT, Jev answers every question in a typed format. You get a number or a key from a set of options, which you can conveniently parse in your Python code.

Your project needs at least Python 3.10 and the TypeSafe SDK. You’ll manage both with uv because uv installs the right Python version for you and reads your dependencies from pyproject.toml.

You also need an API key to talk to Jev. You can get one straight from TypeSafe AI, but for this tutorial, you’ll use OpenRouter. OpenRouter is a good place to try out a model without creating a separate account and entering your credit card details with every provider.

The OpenRouter video course covers the platform in depth. For now, all you need is an OpenRouter account with a few dollars of credit on it and an API key from the keys page of your account. Jev is cheap, but not free, so a request from an empty account fails.

You don’t need to pick a model version. The SDK asks for jev-latest by default, which OpenRouter resolves to the newest Jev release. If you’d rather pin a version so that your results stay reproducible, then you can pass an argument like model="jev-1.13" when you create the client later on.

Step 1: Set Up Your Jev Python Project

To get a feel for when Jev can come in handy, it’s a good idea to start with a script that doesn’t use any AI at all. The scenario takes place at a train station. A visitor walks up to the counter, and your script asks if they lost something.

Create a new folder called jev-python/, head over to it in your terminal, and add a file named plain_python.py:

 1def respond(lost_something):
 2    if lost_something:
 3        print("You can find the lost and found counter on the right.")
 4    else:
 5        print("What can I help you with?")
 6
 7def ask():
 8    while True:
 9        answer = input("Did you lose something? (Y/N) ")
10        if answer == "Y":
11            return True
12        if answer == "N":
13            return False
14        print("Please answer with Y or N.")
15
16def main():
17    lost_something = ask()
18    respond(lost_something)
19
20if __name__ == "__main__":
21    main()

In line 9, you ask the visitor if they lost something, and you want a clear answer. If the input is an uppercase Y or N, then ask() returns True or False. Otherwise, you stay in the while loop until you get one of the two letters.

Run the script with uv run, which picks a suitable Python interpreter for you:

$ uv run plain_python.py
Did you lose something? (Y/N) y
Please answer with Y or N.
Did you lose something? (Y/N) Y
You can find the lost and found counter on the right.

Even a lowercase y doesn’t count. You could add .upper() to the answer, so that lowercase input works, too. But now imagine that the visitor says, “Yeah, I’ve lost something.” Where does this stop? Every phrasing that a real person could come up with is another case that your script would need to handle.

That’s where Jev comes into the picture. To work with Jev in Python, you need the TypeSafe SDK. Create a pyproject.toml file next to your script and declare the dependency:

[project]
name = "jev-python"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "typesafe-sdk==0.7.1",
]

The dependencies list is the most important part of this file. When you run a script with uv run inside this folder, uv reads your pyproject.toml file. It creates a virtual environment and installs typesafe-sdk before your script starts.

Next, create a file named .env and paste the API key from your OpenRouter account into it:

OPENROUTER_API_KEY=your-openrouter-api-key

The variable name must be OPENROUTER_API_KEY in uppercase because that’s the name your script will look up in a moment.

You now have a working script, a project file that knows about the TypeSafe SDK, and a secret key. In the next step, you’ll connect the three.

Step 2: Ask Jev a Yes-or-No Question With Noul

The code that talks to Jev isn’t that different from your plain Python script, which is why you’ll enhance what you have rather than start from scratch. Copy plain_python.py to a new file named jev_noul.py. Noul is the name of the first Jev primitive that you’ll use, and it’s the one that answers yes-or-no questions.

 1import os
 2
 3from typesafe_sdk import Noul, TypeSafeClient
 4
 5client = TypeSafeClient(
 6    api_key=os.environ["OPENROUTER_API_KEY"],
 7    base_url="https://openrouter.ai/api",
 8)
 9
10def respond(lost_something):
11    if lost_something:
12        print("You can find the lost and found counter on the right.")
13    else:
14        print("What can I help you with?")
15
16def ask():
17    while True:
18        answer = input("Did you lose something? ")
19        r = client.system_one(
20            state=answer,
21            questions={
22                "lost_something": Noul(
23                    instructions="Is the answer from the user affirmative?"
24                ),
25            },
26        )
27        lost_something = r.answers["lost_something"].noul
28        if lost_something > 0.8:
29            return True
30        if lost_something < 0.2:
31            return False
32        print("Sorry, I didn't get that.")
33
34def main():
35    lost_something = ask()
36    respond(lost_something)
37
38if __name__ == "__main__":
39    main()