Jev, from first call to useful app

Give your code
a better gut instinct.

Which team should get this ticket? Is this draft clear? Jev turns questions like these into decisions your app can use. Learn how it differs from an LLM, when it helps, and how to build with it.

Understand JevOfficial quick start
illustrative decisionstructured
State

“Checkout failed twice and our launch is today.”

Choice · which team?
technical88% probability
Route with your own code
01 / Understand the difference

Write an answer. Or make a decision.

Imagine a customer says, “Checkout failed twice.” You might need a helpful reply. Or you might just need to know which team should receive the ticket. Those are different jobs.

A speech bubble with sequential text blocks beside a branching diagram with a choice, score, and gauge
Two ways to use AI: generate a response, or evaluate a set of questions.
A language model

“What should I say?”

An LLM generates a sequence of tokens: small pieces of text. That makes it useful for writing replies, explaining ideas, creating code, and working through open-ended problems.

Example taskWrite a helpful response to this customer.

“Sorry checkout is failing. Let’s investigate…”

LLMs can also return schema-constrained JSON and select tools. Structured decisions are possible with an LLM, too.

Jev · a System One model

“Which answer fits?”

You supply the situation and define the possible answers. Jev evaluates them and returns typed values with probabilities, without composing a text response.

Example taskChoose a team: billing, technical, or sales.

choice: "technical"

Its specialty is a small judgment your software makes repeatedly: route this, rank that, or check whether a condition is true.

Why that matters

TypeSafe says Jev evaluates questions in parallel instead of generating an answer token by token. This can make frequent, narrow decisions practical inside an app. Actual speed, cost, and accuracy still depend on your workload.

How Jev works · TypeSafeLLM structured outputs · Anthropic
Does “typed” mean it cannot be wrong?

No. A Choice stays within the options you provided, but it can still choose the wrong one. If billing is the wrong team, returning a valid billing value does not fix that mistake. Test decisions against examples with known answers.

The mental model

Situation in. Decision out.

The state is simply the information the model reads. A question says what to judge. Your code decides what happens with the answer.

1
State

The text or structured data Jev should evaluate.

2
Questions

Small, typed judgments evaluated independently.

3
Answers

Values, probabilities, and confidence—not prose to parse.

4
Your code

Routes, ranks, asks for review, or safely does nothing.

Three primitives

Ask for exactly what you need.

Choose a category, rate something on a scale, or check a statement. Ask independent questions about the same situation in one call, then combine the answers in code.

Choice

Three options converging on one checked selection
Which option fits best?
Route an item into one of a small set of options, such as a support team or content category.
choice + probabilities + confidence

Score

A marker highlighting one level of an ascending rubric
How does this rate on your scale?
Describe the levels from low to high. For example: cosmetic bug, workaround available, completely blocked. The score can fall between levels.
score + probabilities + confidence

Noul

A probability marker positioned between zero and one
Is the answer yes or no?
Check one statement, such as whether a customer asks for a refund. Near 1 means likely yes; near 0 means likely no; near 0.5 means uncertain.
number from 0 to 1
02 / Read a decision

See the uncertainty. Use it.

A label tells you what won. A probability distribution tells you how the model weighed the alternatives. Try a less specific message and see why that extra information matters.

Choice / Try three situations

The winner is only half the story.

Illustrative values · no live API call

“The checkout button throws an error. We cannot accept orders.”
Technical 92%Billing 6%Sales 2%

Most of the probability is on technical. The model has a clear preference; your code still checks whether routing is appropriate.

The API’s confidence summarizes the distribution’s shape. It is not simply the largest bar, and it is not a guarantee of correctness. Noul returns its own 0–1 value, without a separate confidence field.

Read the confidence guide
Your code / Try a policy

Uncertainty changes the next step.

Separate simulation · example thresholds

A message branches toward automatic routing or a person reviewing it

Below 0.55: review · 0.55–0.79: confirm · 0.80+: route

Ask for confirmation

The model supplies a signal. Your application sets the rule. Moving this slider changes the rule’s outcome; it does not rerun the model or change the probability chart.

Choose real thresholds using labeled examples and the cost of a mistake. Handle timeouts and API errors with a fallback, too.

Score / A number with a meaning

1.4 out of what?

A three-level rubric uses positions 0, 1, and 2. Suppose a bug has a 60% probability of level 1 and 40% of level 2. Its score is 1.4: a position between two descriptions, not “70% correct.”

How Score is calculated
  1. 0
    Cosmetic

    Looks wrong; still works.

  2. 1
    Degraded

    Broken, but a workaround exists.

  3. 2
    Blocked

    Cannot proceed; no workaround.

Noul: a probability of “yes,” not a rating.

For “Does this message request a refund?”, 0.9 means the model assigns a 90% probability to yes. It does not mean the customer wants 90% of their money back. Use Score when you need a degree or level.

How to read a Noul
03 / Find the fit

Small decisions. Repeated everywhere.

Jev is most interesting when the answers are bounded, the context is available, and your app needs the same kind of judgment over and over.

Use case 01

Sort an inbox

Message → team + urgency

Meaning varies too much for keywords alone. Separate routing and urgency questions let code put tickets in the right queue.

Build this project
Use case 02

Check a draft

Draft → a focused checklist

Ask separately about clarity, a concrete claim, and a call to action. Show which dimension needs work; use an LLM if you want a rewrite.

Build this project
Use case 03

Choose an agent tool

Task → one allowed capability

Choose from tool IDs supplied by your app. Code checks permissions and runs the tool. Include a “none” option when no capability fits.

Build this project
A little arithmetic / 1,000 incoming items

Save the deeper work for what needs it.

Imagine Jev checks every log event and your policy sends only some to an LLM for investigation. Change the share that needs that second step.

Every item 1,000 LLM callsAfter triage 200 LLM calls

800 fewer LLM calls, plus 1,000 Jev evaluations.

This is a workload illustration, not a measured cost or speed comparison. Triage adds its own cost and latency. Measure those, and check which important events the filter misses, before deciding it helps.

They can work together

Jev selects. An LLM develops. Code acts.

For a support assistant, Jev could pick a team and flag urgency. An LLM could then draft a reply using the right context. Your application decides whether a person must approve it.

  1. JevRoute and prioritize
  2. LLMDraft the response
  3. Your codeValidate and request approval

When to reach for something else

  • Need original text or code? Use a generative model.
  • Need a long, multi-step investigation? Use a reasoning workflow with the right tools and evidence.
  • Have an exact rule or calculation? Write ordinary code. A model adds uncertainty.
  • Missing the facts? Retrieve context first. A decision model cannot make absent evidence appear.
Before you automate

Collect examples with known answers. Compare Jev, an LLM, and simple rules on the same task. Check wrong decisions, review volume, end-to-end latency, and total cost. Choose the approach that works on your data.

Check your understanding: “Summarize this ticket and pick a team.”

Split the job. An LLM can write the summary. A Jev Choice can select the team from defined options. If both evaluate the original ticket, they can run independently; if the routing uses the summary, it must wait for it.

Go to the source / Reviewed September 23, 2026

This guide combines official documentation with illustrative examples. TypeSafe’s performance claims come from its own evaluations; they are not universal guarantees.

Jev introductionArchitecture & published evaluationsProbabilities & confidenceLLM structured outputs
Before you build

From zero to the first decision.

Three things to get right before the first call. They take a few minutes and save a lot of debugging.

Step 1
Create an API key

Get a key from the TypeSafe console and save it as TYPESAFE_API_KEY.

Open console
Step 2
Keep the key server-side

Call Jev from a server route or backend. Never ship your key in a browser bundle.

Step 3
Start with one question

Test real examples, inspect probabilities, then add explicit fallback behavior.

Starter projects

Choose one. Copy. Build.

Each prompt gives a coding agent the product brief, safety boundaries, and definition of done. Paste it from the root of your project.

01

Start here

Learn the primitives, then add a confidence-aware fallback.

01First call15–20 min
Start here

Signal checker

Paste a message and estimate whether one statement about it is true. The smallest useful Jev project.

How it works

Message + focused statement → Noul value → percentage meter

You’ll practice
  • Noul
  • State design
  • API setup
Agent prompt240 words
Build a tiny "Signal checker" in this repository using Jev from TypeSafe AI.

First inspect the existing project and preserve its framework, conventions, and package manager. Use the official TypeSafe skill to confirm the current SDK and API patterns. If that skill is not installed, install it with:
npx skills add typesafe-ai/skills --skill typesafe-ai

The experience should let someone paste a short piece of text, enter one focused statement such as "This message asks for urgent help", and run a Noul question against the text as state. Show the returned 0–1 value as both a percentage and a simple meter labeled "Probability of yes". Explain that near 0 means likely no, near 1 means likely yes, and near 0.5 means uncertain; it is not a measure of the degree of urgency. Include one pre-filled example so it works immediately.
02Three primitives30–45 min
Start here

Inbox triage

Turn a customer message into a team, an urgency level, and an escalation signal in one call.

How it works

Customer message → three parallel judgments → routed result

You’ll practice
  • Choice
  • Score
  • Noul
  • Parallel questions
Agent prompt241 words
Build a small "Inbox triage" app in this repository using Jev from TypeSafe AI.

Inspect the repository first and work with its existing stack and design system. Use the official TypeSafe skill to verify the current SDK usage. If it is missing, install it with:
npx skills add typesafe-ai/skills --skill typesafe-ai

The app should accept a customer-support message as the state and evaluate these independent questions in one System One call:
1. A Choice named department with billing, technical, and sales options, each described clearly.
2. A Score named urgency with an ordered three-step rubric: can wait, respond this week, respond today.
3. A Noul named needs_human that asks whether the message needs a human follow-up.
03Production pattern45–60 min
Start here

Confidence router

Use confidence to decide when software can proceed and when a person should take over.

How it works

Work request → route + confidence → proceed, confirm, or review

You’ll practice
  • Confidence gates
  • Fallbacks
  • Observable decisions
Agent prompt275 words
Build a "Confidence router" demo in this repository with Jev from TypeSafe AI.

Start by inspecting the codebase and following its established framework, package manager, and UI patterns. Use the official TypeSafe skill for current API guidance. If it is unavailable, install it with:
npx skills add typesafe-ai/skills --skill typesafe-ai

Users should paste a short work request. Send it to Jev as state and ask one Choice question that routes it to engineering, design, operations, or unclear. Give every option a precise criterion. Then implement the routing policy in normal code:
- confidence >= 0.80: mark it ready for automatic routing;
- confidence from 0.55 to 0.79: suggest the route but request confirmation;
- confidence < 0.55: do not route it and ask for human review.
02

Build a tool

Turn real inputs into a transparent queue, checklist, or report.

04Useful app45–60 min
Build a tool

Feedback prism

Turn a pile of product feedback into themes, severity, sentiment, and concrete-request signals.

How it works

Feedback batch → four focused judgments → sortable review queue

You’ll practice
  • Batching
  • Multi-axis analysis
  • Review queues
Agent prompt192 words
Build a small "Feedback prism" app in this repository with Jev from TypeSafe AI.

Inspect the repository first and preserve its stack and conventions. Use the official TypeSafe skill for current SDK guidance; if missing, install it with npx skills add typesafe-ai/skills --skill typesafe-ai.

Users paste up to 20 short feedback items. For each item, ask independent questions in one System One call: a Choice for theme (bug, usability, performance, pricing, feature request, other), a Score for severity (minor friction, meaningful blocker, prevents use), a Choice for sentiment (positive, mixed, negative), and a Noul for whether it contains a concrete request. Display a sortable table, summary counts, and a review queue for uncertain classifications.
05Creator tool45–60 min
Build a tool

Content preflight

Check a draft’s hook, clarity, specificity, and call to action before it goes live.

How it works

Draft → transparent checklist → compare revisions

You’ll practice
  • Composite scoring
  • Rubrics
  • Actionable UI
Agent prompt193 words
Build a "Content preflight" tool in this repository using Jev from TypeSafe AI.

Inspect the project and use its existing framework, styling, and package manager. Follow the official TypeSafe skill; install it with npx skills add typesafe-ai/skills --skill typesafe-ai only if needed.

The user pastes a short post or ad draft. Evaluate independent dimensions in one call: Noul questions for a clear hook, a concrete claim, and a specific call to action; a Score for clarity using three explicit rubric levels; and a Choice for dominant tone (educational, conversational, provocative, promotional). Combine the dimensions in ordinary code into a transparent preflight checklist—never a vague single "quality" score. Let users edit the draft and compare the latest result with the previous one.
06Developer tool60–90 min
Build a tool

Log first responder

Score noisy log events before sending only the useful ones to expensive analysis or a human.

How it works

Redacted logs → classify + score → filtered escalation queue

You’ll practice
  • Triage pipeline
  • Cost control
  • Safe logging
Agent prompt190 words
Build a local "Log first responder" dashboard in this repository with Jev from TypeSafe AI.

First inspect the repo and follow its existing architecture. Use the official TypeSafe skill for current patterns, installing it with npx skills add typesafe-ai/skills --skill typesafe-ai if absent.

Accept pasted newline-delimited JSON log events. Validate and redact likely secrets locally before any API call. For each safe event, ask Jev for a Choice category (routine, application error, dependency failure, security signal, unknown), a Score severity rubric, and a Noul indicating whether immediate human attention is warranted. Show a filterable queue and a clearly explained policy that escalates only high-severity or high-attention results above a configurable confidence floor.
03

Agent loops

Give an agent a bounded choice while deterministic code stays in charge.

07Agent routing60–90 min
Agent loops

Skill caddy

Pick the one capability a coding agent needs now instead of loading every tool into context.

How it works

Task + capability list → bounded choice → one safe tool or none

You’ll practice
  • Dynamic choices
  • Tool routing
  • Abstention
Agent prompt191 words
Build a "Skill caddy" prototype in this repository using Jev from TypeSafe AI.

Inspect the existing stack first. Use the official TypeSafe skill to implement current SDK patterns; install it with npx skills add typesafe-ai/skills --skill typesafe-ai if it is not available.

The tool receives a user task and a small JSON manifest of available agent capabilities. Build a dynamic Choice question whose options are stable capability IDs and whose criteria come from concise descriptions. Include an explicit none option. Show the selected capability, probabilities, and confidence, then render the exact context snippet that would be handed to an agent. Do not actually invoke tools in this version.
08Controlled agent loop90 min
Agent loops

Browser next-step lab

Let Jev choose among indexed page actions while a deterministic harness owns the browser.

How it works

Visible page state → next-action choice → validated browser step

You’ll practice
  • Action spaces
  • Observe/decide/act
  • Loop limits
Agent prompt198 words
Build a safe "Browser next-step lab" in this repository with Jev from TypeSafe AI and the browser automation library already present in the project, or Playwright if there is none.

Inspect the repo and follow its conventions. Use the official TypeSafe skill, installing it with npx skills add typesafe-ai/skills --skill typesafe-ai if necessary.

Create a local demo page with a three-step form. The harness observes only visible, indexed interactive elements plus the current goal. Ask Jev one Choice question to select the next allowed action ID, with stop and ask_for_help options. Deterministic code validates and executes the selected action. Show an event timeline with observation, probabilities, chosen action, and outcome.
09Safety pattern60–90 min
Agent loops

Command warden

Add a fail-closed judgment layer before an agent runs a shell command—without pretending it is a sandbox.

How it works

Command + goal → local rules + Jev checks → allow, confirm, or deny

You’ll practice
  • Guardrails
  • Fail closed
  • Policy layering
Agent prompt186 words
Build a non-executing "Command warden" demo in this repository using Jev from TypeSafe AI.

Inspect the codebase and preserve its stack. Follow the official TypeSafe skill, installing it with npx skills add typesafe-ai/skills --skill typesafe-ai if needed.

The UI accepts a proposed shell command plus a short stated goal. It must never run the command. First apply deterministic deny rules for destructive patterns, privilege escalation, secret access, and network exfiltration. Only commands not denied locally go to Jev, with separate Noul questions for goal alignment, reversibility, and whether human confirmation is warranted, plus a Choice risk tier. Show which local and model signals produced the final allow_for_demo, confirm, or deny result.
04

Play & explore

Make the model visible through simulations, games, and evaluation.

10Game loop60–90 min
Play & explore

Snake instinct

Build a tiny game where code owns physics and Jev chooses one legal move per tick.

How it works

Board + legal moves → next-move choice → deterministic game tick

You’ll practice
  • Structured state
  • Legal actions
  • Replayability
Agent prompt184 words
Build a small "Snake instinct" game in this repository where Jev from TypeSafe AI controls the snake.

Inspect the existing project and use its framework and testing conventions. Use the official TypeSafe skill for current API usage; install it with npx skills add typesafe-ai/skills --skill typesafe-ai if absent.

Deterministic game code owns the board, collision rules, food, score, and legal moves. On each slow, user-triggered step, serialize compact state: head, body, food, direction, board size, and legal moves. Ask Jev a Choice question using only legal move IDs. Animate the chosen move and show its probabilities. Include manual play, Jev step, auto-play with a conservative rate limit, pause, reset, seeded boards, and a replay log.
11Speculative fan-out60–90 min
Play & explore

Home anticipator

Simulate a smart home that evaluates many possible needs at once, but changes nothing without approval.

How it works

Home state → parallel needs → one confirmable suggestion

You’ll practice
  • Fan-out
  • Contextual relevance
  • Human approval
Agent prompt193 words
Build a "Home anticipator" simulator in this repository using Jev from TypeSafe AI.

Inspect the repo and preserve its architecture. Use the official TypeSafe skill for current System One patterns, installing it with npx skills add typesafe-ai/skills --skill typesafe-ai if needed.

Create a fictional home-state editor for time, occupancy, temperature, open windows, light levels, and a calendar note. In one call, ask independent Noul questions about whether heating, cooling, lighting, ventilation, or a reminder would be useful, plus a Choice for the single most relevant suggestion. Display all answers, but use application code to surface only contextually valid suggestions. Every action is a simulation requiring explicit user confirmation.
12Evaluation lab90–120 min
Play & explore

Calibration arcade

Create a tiny labeled benchmark and learn whether confidence matches correctness—not just accuracy.

How it works

Labeled examples → predictions → accuracy + calibration report

You’ll practice
  • Evals
  • Calibration
  • Selective risk
Agent prompt191 words
Build a local "Calibration arcade" in this repository for evaluating Jev from TypeSafe AI on a tiny, transparent dataset.

Inspect the project and follow its conventions. Use the official TypeSafe skill for current SDK and evaluation guidance; install it with npx skills add typesafe-ai/skills --skill typesafe-ai if missing.

Ship a synthetic labeled dataset of 40 short issue titles classified as bug, feature, question, or maintenance. Let users inspect and edit examples, run Jev Choice predictions, and compare predicted labels with ground truth. Report accuracy, coverage above a selectable confidence threshold, accuracy at that coverage, a simple reliability diagram, latency, and errors grouped by true/predicted label. Save run artifacts locally as downloadable JSON.
A good Jev habit

Model judgment. Code policy.

Ask one thing at a time.

Split broad evaluations into focused questions.

Make uncertainty useful.

Define what your app does at low confidence.

Keep control in code.

Thresholds and side effects belong in deterministic logic.