TypeSafe Jev Tutorial: API, Code Examples & 12 Use Cases

Jev doesn't generate text. Send it state and a set of typed questions, and it returns a typed answer with a probability for each question in a single parallel pass. TypeSafe AI states end-to-end responses of 70-500ms and 40-200x faster than frontier LLMs (a self-reported ceiling from its own workflow benchmarks, with no third-party validation). This practical guide focuses on how to write it, what to use it for, and where it breaks: three ideas carry the whole thing — decompose questions atomically, batch them into one request, and let confidence drive branching in code.

The basics (the three question types, pricing, limits) were already covered in the intro article, What is TypeSafe Jev — read that first if you haven't. This article is based on the official docs at docs.typesafe.ai and the typesafe.ai blog as of 2026-09-19.

A request has three parts. state holds whatever text or JSON you want evaluated. questions is a map of keys you choose, each pointing to a Choice ('which one?'), Score ('what stage?'), or Noul ('is this true?') question — you can mix all three in one request. Every question is evaluated against the same state in parallel and independently of the others, so adding a question never changes the answers to the others. The returned answers are typed per question: Noul carries noul (0-1); Choice carries choice, probabilities (the full distribution over options), and confidence; Score carries score (which can land between stages, e.g. 1.04), legend, probabilities, and confidence. From there it's on your code to compare confidence or noul against a threshold and branch into auto-execute, confirm, or hand off to a human.

Early-access API keys are issued at https://console.typesafe.ai/keys. Here's the HTTP API hit directly with curl.

The response carries answers per question plus a usage block with token counts. Here's the example response from the docs.

SDKs exist too. Python: pip install typesafe-sdk (or uv add typesafe-sdk, reading TYPESAFE_API_KEY from the environment). JavaScript/TypeScript: npm install @typesafe-ai/sdk (v0.6.0, Node.js 20+, ESM/CommonJS with bundled types), where the answer type is inferred from the question you send. Python ships a synchronous TypeSafeClient, an async AsyncTypeSafeClient, and a RetryPolicy.

Cloudflare Workers AI also lists it in its model catalog as typesafe/jev (32,000 context, jev-1.13.0), callable directly with env.AI.run. Here's the official sample mixing Choice, Noul, and Score in one request.

Errors come back as 401 (bad key), 422 (validation failure), 429 (rate limit), or 529 (overload). 429/529 should be retried with exponential backoff — the SDKs do this automatically. Rate limits sit at 250k tokens/sec and 1,200 requests/min, and move dynamically with demand. Only jev-1.13.0 is available in production; jev-latest (the SDK default) and jev-preview are both aliases currently pointing at that same version. Aliases move automatically on new releases, so if you need consistent behavior, pin a version ID instead of using jev-latest. The model field in the response tells you which version actually answered.

There's also a skill for coding agents. For Claude Code, install it like this.

TypeSafe notes that agents aren't especially good at writing questions on their own, so it recommends having a human refine them together and keeping questions and thresholds in one place so they're easy to review.

The core of the official "How to build with TypeSafe" guide is one idea: keep control flow, deterministic rules, and side effects in code, and never let the model choose actions the way an agent would. Take spam detection. Asking one big question — "is this spam?" — is bad design. Instead, break it into three atomic Noul questions: "does it request credentials?", "does the sender's claimed identity mismatch their email domain?", "does it announce an unexpected prize or reward?" — then combine them in code, e.g. spam_risk = 0.45*credentials + 0.30*identity + 0.25*reward. This decomposition is said to buy three things: explainability, composability, and accuracy.

Put only relevant information in state — the docs are explicit that a state cluttered with irrelevant material hurts accuracy. Structuring it as JSON and referencing fields from questions with backtick-quoted paths (e.g. ticket.messages[0].text) is the recommended pattern, and up-to-date facts should be passed in state rather than relied on from the model's own knowledge. Write instructions as complete sentences even when the key is self-explanatory, and keep each question to one judgment call a knowledgeable person could make in a few seconds. For complex instructions, an object like {question, focus, compare} is suggested; for Choice options, a contrastive {what, not_for, examples} shape is said to improve accuracy.

- Delegating deterministic logic to the model
- Asking one compound, ambiguous question instead of several atomic ones
- Stuffing state with excessive, irrelevant context
- Ignoring uncertainty (confidence and the probability distribution)
- Firing off independent questions serially when they could run in one request

Confidence is a 0-1 statistic computed from how "peaked" the Choice/Score probability distribution is, and since the distribution itself (probabilities) is also returned, you can build your own metrics on top of it. The official guideline: confidence >0.9 is where auto-executing a high-risk action is reasonable, and below 0.5 you should escalate to a human, ask for confirmation, or fall back to another approach. A different page shows a three-tier example: execute above 0.8, human review between 0.4 and 0.6, and route to a more expensive reasoning model below 0.4. The stated position is that "risk tolerance belongs in code" — thresholds are domain-dependent, and the advice is to start conservative and tune against your own data.

The numbers here are just one cookbook example — thresholds shift with the task and dataset. It also helps to look past a single confidence number at the full probabilities distribution, and handle cases where the top two options are close together as a special case.

The mark in the # column shows where each idea comes from: ★ maps to an official cookbook, use-case map entry or demo, while ☆ is a proposal from this article, not something TypeSafe has measured. Each idea is spelled out as what goes into state, which questions (and types) to ask, and what the code does.

Inquiry triage is the easiest place to start. Put the subject, body, and optionally the customer segment into state, and bundle a department Choice, urgency/sales-pitch Noul questions, and a frustration Score into one request. Below is a full request showing the questions block, with instructions in English and a Japanese inquiry text left as-is in state.

Filtering RAG search results improves both quality and safety of internal knowledge search. Ask each retrieved passage four questions — relevance, whether it's usable as evidence, whether it contradicts the query's premise, whether it's attempting to manipulate the system — and process them in this order: exclude if injection>0.70, route to a contradiction block if >0.70, exclude if relevance<0.45, keep only if evidence>0.55. In an official validation across 72 passages, an injected passage that ranked #1 by similarity (0.584) was caught with injection score 0.99. Thresholds are corpus-dependent and need tuning on your own data.

A pre-execution gate for AI agents matters more the more write access the agent has. Put the pending tool call (a command or diff) and the project's rules into state, then ask Noul questions like "does this write to a production database?", "does it violate a rule?", "does it send secrets externally?". Holding for human approval whenever any answer exceeds 0.5 is a proposal made in this article, but npm packages that check a coding agent's writes against a rules document have already started appearing, so the same idea is emerging in the ecosystem independently.

Checklist matching for contracts, quotes, and invoices pairs well with the fact that batching questions is cheaper. Send 10-20 Noul questions about a single document in one request — payment terms stated, delivery date stated, subcontracting clause present, damages cap present, and so on — and have code list out whatever came back false. Never let Jev do the arithmetic on amounts or dates; extract values and compute/verify them in code.

Pricing is $0.042 per million input tokens, with output free. You can estimate cost as token count x $0.042/1M.

Batching questions has a measured effect on its own. In an official benchmark asking 13 questions about the GDPR Wikipedia article (~54,000 characters), sending them in one request cost $0.000497 and took 0.27s, versus $0.006090 and 2.71s when split into 13 separate requests — 12.2x cheaper and 10.0x faster in the batched case, with no change in answers and no increase in variance. The reason is that state only needs to be sent once, which also backs up the "speculative fan-out" pattern mentioned earlier: throw every question that might be relevant into one request and let code decide which answers to actually use.

The Register makes the point that "doesn't hallucinate" only means the output isn't free-form natural language — a probability-scored judgment can still be wrong, just in a different way. It's also worth keeping in mind that the benchmarks are TypeSafe's own.

TypeSafe AI's own docs state that Jev's primary language is English — CJK input, including Japanese, is accepted but currently has lower accuracy. Since fine-tuning isn't an option either, the following adjustments are a realistic starting point for Japanese-language work (these are proposals made in this article, unverified, and assume you'll run your own evaluation).

- (a) Write instructions/criteria in English, and pass state in Japanese as-is
- (b) Measure accuracy against confidence on 100-200 of your own examples before setting thresholds
- (c) Escalate low-confidence cases to an LLM or a human
- (d) Also compare a variant where state is machine-translated before being sent

None of these have been validated — the accuracy/operational-cost tradeoff has to be measured on your own data.

Using Jev in practice comes down to repeating the same three moves: decompose questions atomically, batch them into one request, and let code branch on confidence. As long as you hold to the design principle of keeping deterministic logic and side effects entirely in code — rather than letting the model generate text or choose actions — the same idea applies whether you're triaging inquiries, filtering RAG results, or gating an agent's next action.

Calling it from Cloudflare Workers AI fits naturally with the stack covered in Building a web app on the Cloudflare stack, and if you're wiring it into an internal knowledge-search RAG pipeline, a good starting point is adding it as a filter on top of the search results from Building internal knowledge search with OpenClaw. Since this is still an early-access model, validating confidence thresholds against your own data before production use is a step worth insisting on.

- https://docs.typesafe.ai/introduction
- https://docs.typesafe.ai/primitives
- https://docs.typesafe.ai/confidence
- https://docs.typesafe.ai/patterns
- https://docs.typesafe.ai/model-jaggedness/jev-1.13
- https://docs.typesafe.ai/models
- https://typesafe.ai/blog/introducing-system-one-models-and-jev
- https://developers.cloudflare.com/ai/models/typesafe/jev/
- The Register: https://www.theregister.com/ai-and-ml/2026/09/16/typesafe-ai-debuts-model-for-machines-that-plays-doom/5296711