Jev SDK Developer Guide

How to get access to Jev

Jev is currently in early-access waitlist via the TypeSafe AI official site. There is no public download of model weights. You call a hosted API after you have a key from TypeSafe or from a supported gateway.

Where to access Jev

1. Official TypeSafe AI waitlist: apply on typesafe.ai, then create a key in the TypeSafe console when invited.
2. Third-party gateways: OpenRouter, Vercel AI Gateway, and Cloudflare AI also expose Jev / System One decision routes for teams that already use those platforms.

Important limitation: There is no downloadable model file. You cannot self-host Jev locally. All inference runs on TypeSafe-managed cloud (or on a gateway that proxies that cloud service).

Pricing note

Input tokens cost $0.042 per million tokens. Output tokens are completely free. You will not be charged for Jev decision outputs on the published TypeSafe rate card.

Gateway providers may apply additional markup or billing units on top of the base model price. Always check the gateway price page before estimating production cost. See also the pricing FAQ.

Three core primitives of Jev

Jev requests are built from three primitive question types. Every request sends state (your input context or program data) plus a list of typed questions. Jev returns structured typed results with calibrated probabilities.

1. Choice: Pick one answer from your predefined option list. Typical for agent routing and classification.
2. Score: Return a graded numerical position on a defined scale or rubric. Typical for risk scoring and severity rating.
3. Noul: Return a probability for a yes/no judgement. Typical for moderation gates and simple boolean filters.

Short definitions also live in the glossary.

Installation

There is no required official public npm or pip package named for Jev that you must install just to send a request. The minimal path is a normal HTTP POST to the System One endpoint. Node.js 18+ can use built-in fetch. For Python, install the widely used requests library:

pip install requests

If you call Jev through OpenRouter, use that gateway's documented Decisions API and its own API key. Do not invent or hardcode package names such as a fictional @typesafe/jev-sdk.

# Store keys outside source control
export JEV_API_KEY="YOUR_API_KEY"
# Or, when calling through OpenRouter:
# export OPENROUTER_API_KEY="YOUR_OPENROUTER_KEY"

Minimal full API request JSON

Endpoint used in the examples below: POST https://api.typesafe.ai/v1/systemone. Confirm the latest path and field names against TypeSafe docs before production cutover.

{
  "state": "Customer message: my order has not arrived",
  "questions": {
    "ticket_routing": {
      "type": "choice",
      "options": ["support", "logistics", "billing"]
    },
    "is_urgent": {
      "type": "noul"
    },
    "severity_level": {
      "type": "score",
      "criteria": ["calm", "frustrated", "angry"]
    }
  }
}

Copy-paste API examples

These are minimal community examples using raw HTTP. They are not an official SDK wrapper. Replace the environment variable with a real key from waitlist or a gateway.

Node.js

// Minimal raw API call example for Jev
// Replace YOUR_API_KEY with a real key from waitlist or a gateway
async function callJev() {
  const apiKey = process.env.JEV_API_KEY;

  const payload = {
    state: "Customer message: my order has not arrived",
    questions: {
      ticket_routing: {
        type: "choice",
        options: ["support", "logistics", "billing"],
      },
    },
  };

  const res = await fetch("https://api.typesafe.ai/v1/systemone", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });

  if (!res.ok) {
    throw new Error(`Jev request failed: ${res.status}`);
  }

  return res.json();
}

Python

# Minimal raw API call example for Jev
# Requires: pip install requests
# Replace YOUR_API_KEY with a real key from waitlist or a gateway
import os
import requests

def call_jev():
    api_key = os.environ["JEV_API_KEY"]
    payload = {
        "state": "Customer message: my order has not arrived",
        "questions": {
            "ticket_routing": {
                "type": "choice",
                "options": ["support", "logistics", "billing"],
            }
        },
    }
    response = requests.post(
        "https://api.typesafe.ai/v1/systemone",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

SDK Best Practices

1. Keep API keys in environment variables, never expose keys on frontend code.
2. Add request caching for repeated decision tasks to reduce API calls and cost.
3. Add retry logic for transient network failures.
4. Validate all input schemas before sending requests to the model.
5. Prefer Choice / Score / Noul over free-text prompts when you need automation.

Implementation notes

Cache by decision identity, not raw prompt text

Hash the question set plus normalized state fields. If two requests represent the same routing decision, reuse the prior result. This is especially useful for hot paths such as moderation scoring and tool selection.

Fail closed on schema mismatch

If the response does not match your expected decision schema, do not silently coerce it into a default branch. Log the incident, return a safe fallback route, and alert.

Keep generative LLMs behind the decision gate

Call Jev first. Only invoke a chat-style model after the route is known. See production use cases for concrete examples.