Build with Jev (TypeSafe)

Jev is TypeSafe's flagship System One model. You send a state and typed questions; it returns structured answers — chosen options, probability distributions, confidence — that code can branch, sort, and route on. No text generation, no parsing.

The live docs are the source of truth. Discover pages at docs.typesafe.ai/llms.txt; append .md to any docs URL for clean Markdown. Read the relevant primitive, SDK, or cookbook page as part of the task before writing an integration. Never invent request or response fields beyond what this skill or the live docs state.

The three primitives

Mix all three in one request — every question sees the same state, evaluated independently and in parallel. Adding questions barely changes latency; no context rot.

HTTP contract

POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer $TYPESAFE_API_KEY
Content-Type: application/json

{
  "state": "My running shoes arrived in the wrong size. Can I swap them for a size 10?",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "returns": "Exchanges, refunds, wrong or damaged items",
        "shipping": "Delivery status, delays, lost packages",
        "billing": "Charges, invoices, payment problems"
      }
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated the customer appears",
      "criteria": ["Calm, just stating facts", "Frustrated but civil", "Very angry, strong language"]
    },
    "is_urgent": { "type": "noul", "instructions": "The message conveys urgency or time-sensitivity" }
  }
}

Answer shapes, keyed by your question ids:

• choice → { "type": "choice", "choice": "returns", "probabilities": { … sums to 1 }, "confidence": 0.82 }
• score → { "type": "score", "score": 1.035, "legend": { "0": …, "1": … }, "probabilities": { "0": … }, "confidence": 0.842 } — score is probability-weighted and can land between levels; criteria is 2–10 ordered levels, low to high
• noul → { "type": "noul", "noul": 0.91 } — no confidence field
• top-level usage: { "input_tokens": N, "output_tokens": N }

SDKs

Python (pip install typesafe-sdk, ≥3.10) reads TYPESAFE_API_KEY, defaults to jev-latest:

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state=ticket,
        questions={
            "department": Choice(instructions="Which team should handle this?", criteria={…}),
            "frustration": Score(instructions="How frustrated the customer appears", criteria=[…]),
            "is_urgent": Noul(instructions="The message conveys urgency or time-sensitivity"),
        },
    )
response.answers["department"].choice  # "returns"

JavaScript/TypeScript (npm install @typesafe-ai/sdk, Node ≥20):

import { choice, TypeSafeClient } from "@typesafe-ai/sdk";
const client = new TypeSafeClient();
const response = await client.systemOne({
  state: { document: ticket },
  questions: { category: choice("What is this ticket about?", { billing: null, technical: null, other: null }) },
});
response.answers.category.choice;

Question design

• One snap judgment per question. If it needs extended reasoning or weighs several factors, decompose: ask each factor separately, combine in code. Change a coefficient, not a prompt, when priorities shift.
• State carries content; questions carry judgment. Prefer named JSON fields ({"ticket": …, "policy": …}) when context has parts. Reference nested state with backticked paths like `ticket.messages[0].text`.
• Question ids are for your code — the model never sees them. Write complete meaning in instructions.
• Choice criteria values are descriptions shown to the model — write what separates options; null is allowed when a name suffices. Include an other/none option when the list might not cover every input.
• Score levels must describe concrete situations that stand on their own.
• Noul: phrase so high probability means "yes". ~0.5 means equal yes/no probability, not "medium" — measure degrees with a Score instead. Optional criteria: {true, false} clarifies nuance.

Confidence

confidence (0–1) is derived from the answer's probability distribution: concentrated → confident; flat → uncertain. Use it as a second axis:

• High → act automatically. Medium → confirm/flag/gather more. Low → route to a human or fall back.
• Thresholds scale with risk: a read-only action needs a lower bar than a destructive one (approve-transfer at >0.9, show-balance above the ~0.5 floor). Tune on your own data.
• If you only want the best option, take choice — don't threshold. Use raw probabilities when implementing your own statistical rule. Noul answers carry none.

Patterns and cookbooks

Start from the behavior the app must show, select, or hand off; work backward to the judgments; keep known rules, exact lookups, and execution in code. Patterns: speculative fan-out (many questions, one call, code picks relevant answers), confidence-gated routing, composite scoring, intent routing. Cookbooks index covers reranking, function calling, extraction cascades, citation checks, guardrails, hierarchical classification, entity alignment — read the closest one before inventing a decomposition.

Keep questions and thresholds in one file so humans can review them in one place; agents write mediocre questions — expect collaborative edits. Batch extra questions still costs tokens; measure end-to-end. Typed output guarantees the interface, not truth: validate in your domain. Keep API keys server-side.