Connect Jev to your app

The decision flow

1. App input
2. Fixed labels
3. Jev decision
4. Check confidence
5. Route or review

1. Pick a narrow decision

Start with something your code can act on: choose a help topic, score a passage, or answer a yes/no question. Define the permitted results before making a request. In this walkthrough, Jev picks account, export or other; your code decides which screen to show.

The native API takes a state and named questions. It returns structured answers under those names. This is a decision step inside an app; use a text-generating model separately when you need a written reply. Official API contract ↗

2. Install and set your key

You need Python 3.10 or newer, access to the TypeSafe API and a key from the TypeSafe console ↗. Run the commands for your operating system in your project directory.

Windows · PowerShell

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install typesafe-sdk==0.7.2

These commands call the environment's Python directly, so PowerShell script activation is unnecessary.

macOS / Linux

python3 -m venv .venv
.venv/bin/python -m pip install typesafe-sdk==0.7.2

Set TYPESAFE_API_KEY in the same terminal or through your secret manager. The SDK reads it automatically. Keep the key in the server or local process, outside browser bundles and source control. SDK setup ↗

$env:TYPESAFE_API_KEY = '<your-key>'

export TYPESAFE_API_KEY='<your-key>'

The example pins SDK 0.7.2. Review the SDK changelog ↗ before upgrading.

3. Make one typed call

Save the example below as connect-jev.py. It sends one fictional support message. Choice describes a fixed set of help topics; the other option gives the question a route for messages outside the two specific topics. Official SDK source ↗

Run on Windows · PowerShell

.\.venv\Scripts\python.exe connect-jev.py

Run on macOS / Linux

.venv/bin/python connect-jev.py

"""Jevland example: run with your own TYPESAFE_API_KEY. Makes one live request."""
import os

from typesafe_sdk import Choice, TypeSafeClient


def decide_route(client, message):
    response = client.system_one(
        model="jev-latest",
        state={"message": message},
        questions={
            "route": Choice(
                instructions="Which help topic best matches the message?",
                criteria={
                    "account": "Sign-in or account access",
                    "export": "Downloading or exporting a file",
                    "other": "Another topic or too little information",
                },
            )
        },
    )
    answer = response.choices["route"]
    # A starting policy for this example; tune on your own labelled cases.
    route = answer.choice if answer.confidence >= 0.8 else "review"
    return route, answer, response.model


if __name__ == "__main__":
    if not os.environ.get("TYPESAFE_API_KEY"):
        raise SystemExit("Set TYPESAFE_API_KEY in this terminal before running.")
    with TypeSafeClient() as client:
        route, answer, model = decide_route(
            client, "Where can I download my project as a PDF?"
        )
    print("Model:", model)
    print("Route:", route)
    print("Choice:", answer.choice)
    print("Confidence:", answer.confidence)
    print("Probabilities:", answer.probabilities)

4. Read the result before acting

Inspect the selected label, probability distribution and confidence. The script prints actual returned values, so it does not promise a particular answer. It also prints the returned model: jev-latest is an alias and may resolve to a different model over time. Response reference ↗

The 0.8 confidence gate is an illustrative policy. Low confidence sends the result to review; a confident other still stays outside the account/export paths. Confidence describes the answer distribution, not an independently measured correctness rate. Tune the policy on labelled examples from your own task. How confidence works ↗

What the output looks like

This illustration uses an offline response fixture, not a live model result. Actual labels, confidence and probabilities depend on your request.

Model: jev-offline-fixture
Route: export
Choice: export
Confidence: 0.9
Probabilities: {'account': 0.0, 'export': 1.0, 'other': 0.0}

5. Add the official skill to a coding agent

If a coding agent is implementing the integration, TypeSafe publishes a skill that teaches its request and response contracts. The official installation route supports selecting your agent; installing a skill does not itself connect your app or supply an API key. Official skill instructions ↗

npx skills add typesafe-ai/skills --skill typesafe-ai

A focused brief for the agent:

Use the TypeSafe skill to add one server-side Jev decision to this app. Define the permitted labels, keep an other/review path, read the API key from the environment, and test application behavior using fixtures. Show the request and response handling before connecting real traffic.

6. Check the integration

• Missing credentials should stop the script before it sends a request. Check the same environment in your terminal and deployment.
• Confirm that each response key matches the question you sent. Include unrelated and incomplete messages in your test set.
• Keep network failures separate from a model answer; do not turn an API error into a confident label.
• Record the model and policy used when evaluating results. A valid label can still be wrong.

Verification scope: the example is reviewed against the cited SDK and checked offline with response fixtures. Jevland has not run a live model request for this guide. Running it with your key uses your TypeSafe account; review your account's current usage terms first.

Next: select relevant context before generation →

Troubleshooting

ModuleNotFoundError: typesafe_sdk

Use the same .venv Python for both installation and execution. Re-run the SDK installation commands above.

Missing TYPESAFE_API_KEY or an authentication error

Set the key in the terminal that launches the script. Check access in your TypeSafe account without printing the key.

Timeout, rate limit or server error

Keep API errors separate from decisions. Inspect the error and use a bounded retry policy in your app; do not replace a failed request with a label or score. SDK reference ↗

Projects to explore

These are catalog records with their own sources and evidence labels.

• typesafe-sdk (Python) official

  The official Python client (`uv add typesafe-sdk`) with sync and async variants; the quickstart classifies support tickets into billing, technical or other.

• @typesafe-ai/sdk (TypeScript) official

  The official TypeScript/JavaScript client, shipping ESM, CJS and type declarations for Node 20+; same ticket-classification quickstart as the Python SDK.

• Agent Squad: typed Jev routing source-backed

  Agent Squad includes JevClassifier implementations in TypeScript and Python. A typed Choice question selects among configured agents using the request and conversation context.