Getting Started with Jev: A Practical Setup Guide

Before You Start

Jev, TypeSafe AI's System One decision model, is available in early access as of September 2026. This guide walks through the fastest path from zero to a working API call — no prior familiarity with Jev required. If you haven't read what Jev actually is and why it's different from an LLM, start with our explainer first.

Step 1: Get an API Key

Sign in at console.typesafe.ai and generate a key from the dashboard's Keys page. Set it as an environment variable so it isn't hardcoded into your project:

export TYPESAFE_API_KEY="your-key-here"

Step 2: Try It in the Playground First

Before writing any code, it's worth testing your question schema in the web playground at console.typesafe.ai/playground. Paste in a sample piece of text as your "state," add a Choice, Score, or Noul question, and see the typed response immediately. This is the fastest way to sanity-check your schema before wiring it into an application.

Step 3: Install the Python SDK

Jev requires Python 3.10+. Install the official SDK:

pip install typesafe-sdk

Step 4: Make Your First Call

The SDK reads TYPESAFE_API_KEY from your environment automatically. Here's a minimal example using a Noul (yes/no probability) question:

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

client = TypeSafeClient()

response = client.system_one(
    state="Customer says: 'This is the third time I've emailed about my refund. I need this resolved today.'",
    questions={
        "urgent": Noul(
            instructions="Does this message convey time-sensitivity or frustration?"
        ),
    },
)

print(response.answers["urgent"])

The response includes a calibrated probability for urgent, not just a blunt true/false — useful if you want to set your own threshold for escalation rather than trusting a hardcoded cutoff.

Step 5: Add a Choice Question for Routing

Most real use cases need routing, not just a single yes/no signal. A Choice question selects from a closed set of labels you define, each with its own description the model uses to disambiguate:

response = client.system_one(
    state=ticket_text,
    questions={
        "department": Choice(
            instructions="Which team should handle this ticket?",
            options={
                "billing": "Invoices, payments, refunds, subscription changes",
                "technical": "Bugs, errors, outages, broken features",
                "sales": "Pricing questions, upgrades, new contracts",
            },
        ),
    },
)

The response returns the selected key plus a probability distribution across all three options — so you can set a confidence floor and fall back to human review when Jev isn't sure, instead of silently misrouting.

Step 6: Call It Directly via REST (No SDK)

If you're not in a Python environment, hit the API directly:

curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "your text here",
    "model": "jev-latest",
    "questions": { "urgent": { "type": "noul", "instructions": "Is this urgent?" } }
  }'

Common Setup Mistakes to Avoid

• Vague option descriptions. Jev disambiguates Choice options using the description text you provide — a one-word label like "billing" with no context gives it far less to work with than a full sentence describing what belongs in that bucket.
• Ignoring the confidence score. Every answer comes back calibrated, not just a raw pick. Treat a low-confidence Choice or Noul result as a signal to route to a human or a fallback, not as noise to discard.
• Using Jev for open-ended generation. If you need prose, summaries, or conversation, that's not what Jev is for — pair it with an LLM instead of trying to force free-text output through a typed schema.

Where This Fits Into a Larger Agent Setup

On its own, a single Jev call is just a fast classification. The real value shows up when you wire it into a larger agent pipeline — as a routing step before an LLM call, as a guardrail scoring an LLM's output before it's acted on, or as the decision layer inside an MCP tool call. That's the kind of wiring we do as part of our agent harness engineering work at Vantaverse — if you're evaluating Jev for a production pipeline and want a second pair of eyes on the architecture, get in touch.