Jev concepts & primitives

How to get access

Fastest path on this site: sign in, buy a small prepaid pack, create a jv_live_ key, then POST to /api/v1/decide. Upstream TypeSafe keys stay on our servers. Official waitlist and third-party gateways are optional if you need raw TypeSafe credentials.

Access options

1. Hosted on this site (recommended for quick start): Pricing + Account — prepaid tokens and jv_live_ keys for /api/v1/decide and tools.
2. Official / gateway alternatives: TypeSafe waitlist on typesafe.ai, plus OpenRouter, Vercel AI Gateway, and Cloudflare AI if you already bill through those platforms.

Important limitation: There is no downloadable model file. You cannot self-host Jev locally. All inference runs in the cloud (this host, TypeSafe, or a gateway).

Pricing note

Published TypeSafe card: input about $0.042 per million tokens. Output tokens are free on that card. This site’s retail packs are listed on Pricing (often higher to cover hosting).

For prepaid packs and live metering on this host, see Pricing. Gateway markups may still apply if you call upstream elsewhere.

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

You do not need an official Jev npm/pip package to call decide. Prefer our hosted guide for live examples. Minimal HTTP POST works in any language. Node.js 18+ can use built-in fetch. For Python, install the widely used requests library:

pip install requests

For this site, create a jv_live_ key on Account. Do not invent package names such as @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

Hosted endpoint used below: POST https://jevtypesafe.org/api/v1/decide. For interactive test + curl/Python/TypeScript tabs, open the API guide.

{
  "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

Community HTTP examples against this site’s decide API. Replace JEV_API_KEY with a jv_live_ key from Account. Full guide: /docs/api.

Node.js

// Minimal raw API call — hosted decide on this site
// Replace with a jv_live_ key from Account
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",
        instructions: "Route this ticket",
        criteria: { support: "product help", logistics: "shipping", billing: "payment" },
      },
    },
  };

  const res = await fetch("https://jevtypesafe.org/api/v1/decide", {
    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 — hosted decide on this site
# Requires: pip install requests
# Replace with a jv_live_ key from Account
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",
                "instructions": "Route this ticket",
                "criteria": {"support": "product help", "logistics": "shipping", "billing": "payment"},
            }
        },
    }
    response = requests.post(
        "https://jevtypesafe.org/api/v1/decide",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

Best practices

1. Keep API keys in environment variables, never expose keys on frontend code (except the intentional browser key tester).
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.