Jev: A Practical Reference

Contents

1. The short version
2. What Jev is
3. The three question types
4. Probabilities, confidence, and uncertainty
5. When Jev is a good fit
6. When to use code, an LLM, or a human
7. How to design a Jev request
8. Four core workflow patterns
9. The cookbook atlas
10. Industry use-case map
11. Reference architectures
12. Evaluation and deployment
13. Known limitations and failure modes
14. Current technical and commercial facts
15. Further reading

1. The short version

Jev is TypeSafe AI’s first System One model: it reads text or structured text and returns typed judgments that software can use directly. A request contains a state (the material to judge) and one or more questions. The answers are restricted to three forms: a choice among supplied options, a score on supplied levels, or a yes/no probability. Jev does not generate prose, write code, browse, execute a tool, or perform a multi-step plan. Introduction · System One

A useful division of work:

This is a division of responsibilities, not a requirement that every workflow use all four components. For a closed classification task, code plus Jev may be enough. For an agent that writes answers, Jev may serve as a router or verifier around an LLM. How Jev differs from a coding-agent model · Intent routing

The fastest fit test: Can the needed judgment be phrased as one question a knowledgeable reviewer could answer quickly from a compact piece of evidence, with the answer constrained to known options or a defined scale? If yes, Jev is worth testing. If the task primarily needs exact computation or new text, start elsewhere. Primitives · Jev 1.13 jaggedness

2. What Jev is

TypeSafe calls Jev a decision model rather than a conversational LLM. Its output contract is structured and probabilistic: software receives a typed answer and, where applicable, a distribution over the permitted answers. TypeSafe says its training objective, reinforcement learning for calibrated decisions (RLCD), is aimed at making probabilities useful across groups of predictions. That does not guarantee any individual decision is right or that calibration transfers unchanged to a particular business dataset. System One · AI primer

The basic API shape is:

{
  "state": {"message": "My card was charged twice. Please fix this."},
  "model": "jev-1.13.0",
  "questions": {
    "intent": {
      "type": "choice",
      "instructions": "What is the customer's main request?",
      "criteria": {
        "refund": "Return a charge to the customer.",
        "explanation": "Explain a charge without changing it.",
        "other": "Neither of the listed requests."
      }
    },
    "duplicate_charge_reported": {
      "type": "noul",
      "instructions": "Does the customer report being charged twice?"
    }
  }
}

The response contains an answer under each question key, the versioned model ID, and token usage. The question keys identify answers for code; the model judges the instruction and criteria, not the key name. The example above illustrates the request contract; it is not a recorded Jev response. The endpoint is POST /v1/systemone, with Bearer API-key authentication. API reference · Quick start

The state may be a string or a JSON object or array of text-oriented values. When a question compares parts of the state, name them clearly, for example, message, policy, transaction, and candidate. All questions in one request see the same state and are evaluated independently. An answer to one question is not automatically supplied as context to another question in that request. If a later question truly depends on a first answer to retrieve evidence or construct its options, make a second request. State · Primitives

3. The three question types

These are the documented response types. A Choice can have at most 255 options. A Score has 2–10 levels. Scores may land between levels because the reported score is a probability-weighted mean of the level positions; it is not an exact real-world measurement. Primitives · Choice · Score · Noul · API reference

Examples:

• Choice: Which team should own this support ticket: billing, technical, sales, or other?
• Score: How severe is this bug: cosmetic; feature broken but a workaround exists; blocking with no workaround?
• Noul: Does the supplied passage support the specific claim?

A Choice selects relative to its offered options. It can still pick the “best” bad option, so an escape option or a separate “is there enough evidence?” check matters. Several Noul questions are not interchangeable with one Choice: each Noul judges an absolute proposition, while Choice compares options. Do not assume their probabilities obey arithmetic identities or reuse a threshold tuned for one primitive on another. Primitives · Jev 1.13 jaggedness · Line-by-line search cookbook

4. Probabilities, confidence, and uncertainty

For Choice, Jev returns a probability distribution across the options. For Score, it returns a distribution across the levels. Confidence is TypeSafe’s one-number summary of how concentrated that distribution is; it is not simply the winning option’s probability, and it is not a measured accuracy rate. Noul returns its yes probability but no separate confidence value. TypeSafe recommends setting action thresholds according to the consequences of an error, then testing them on the application’s own data. Confidence · Score

Useful distinctions:

TypeSafe’s Choice self-consistency cookbook repeats eight moderation questions about one borderline post 15 times. Jev’s raw picked-label agreement with its plurality labels is reported as 90.8%; adding an uncertain outcome below the cookbook’s illustrative top-option probability threshold of 0.60 increases reported application-decision agreement to 99.2%, with automatic decisions on 74.2% of answers. That is a repeatability and abstention experiment, not proof that majority voting improves classification accuracy. The Noul version similarly uses a review band around uncertain probabilities. Use repeated calls to study stability; adopt voting only if a labeled evaluation shows it improves the intended metric.

5. When Jev is a good fit

Jev is worth a trial when most of these statements are true:

1. The input can be represented as compact text or JSON with the relevant evidence present.
2. The required output is a fixed label, an ordered rubric, a yes/no property, or a ranking based on such judgments.
3. The judgment requires natural-language understanding that exact rules or ordinary search do not supply reliably.
4. The downstream action can be expressed in code, including a path for uncertainty.
5. The question can be evaluated quickly without multi-step reasoning or precise arithmetic.
6. There are enough examples with trusted outcomes to measure the benefit against a baseline.

Common good fits are ticket and document triage; fixed-taxonomy classification; detecting a stated intent or property; scoring a passage for relevance; comparing two candidate entities; checking whether supplied evidence supports a claim; choosing among typed tools; and turning text into numeric features for a conventional predictive model. These are candidate uses, not automatic guarantees of quality. Example use cases · Cookbooks

A decision table

6. When to use code, an LLM, or a human

Use code for exact operations. TypeSafe explicitly identifies arithmetic, counting, date comparison, and exact validation as poor Jev tasks. Extract a date’s stated components with Jev if needed; assemble and compare dates in code. Find candidate amount strings with a parser or regular expression; let Jev select the relevant span if its role is ambiguous; copy the span and parse its number in code. Jev 1.13 jaggedness · Date extraction · Pre-parsed value extraction

Use a generative LLM when the output must be created rather than selected. Jev does not write a customer response, report, contract revision, or program. It also cannot reliably produce arbitrary new strings for unconstrained extraction. A generative model may draft or propose candidates; Jev can choose among them or check specific claims against source text. Jev is not a replacement for the LLM that operates a coding agent. Jev with coding agents · SDE cascade

Use a person when the evidence is missing or the cost of a mistaken action warrants review. A high-confidence distribution can still be wrong. The review decision should use the actual consequences of the action and measured error rates on similar cases; illustrative cookbook thresholds are starting examples, not portable defaults. Confidence · Confidence-gated routing

7. How to design a Jev request

1. Define the action first. Specify what code will do with each answer and what it will do when evidence is inadequate.
2. Keep the state relevant. Include the source text and the records or policy needed for the judgment. Retrieve and filter large collections before sending them; irrelevant detail can reduce accuracy.
3. Write one judgment per question. Split “Is this urgent, valid, and eligible?” into separate judgments; combine them in code.
4. Make criteria concrete. State what belongs in each option and, for commonly confused options, what does not. Describe Score levels as observable situations.
5. Provide an escape path. Include other, none, unknown, or “not stated” where the offered choices may not fit.
6. Point at specific fields. When state is structured, name the relevant field paths in the instruction.
7. Batch independent questions about the same state. Include speculative questions your code may later ignore; extra questions still cost input tokens.
8. Use a second call only for a real dependency. Examples: the first decision determines what evidence to fetch, which candidate options to offer, or which newly formed blocks to classify.
9. Keep exact source evidence. For extraction, select from candidate spans and copy the source value verbatim; validate it in code.
10. Version everything. Log the original input reference, question and criteria version, model version, answer distributions, routing decision, and any reviewer correction.

These steps combine the state guide, primitives guide, structured criteria guidance, fan-out pattern, and TypeSafe’s documented failure modes. The logging recommendation is an implementation inference: it makes a changing model and policy inspectable.

8. Four core workflow patterns

Speculative fan-out

Ask all independent questions against one state in one call, even if some will only matter on one route. TypeSafe’s support example asks for ticket category, bug severity, reproducibility, refund intent, and frustration together; code ignores bug answers if the ticket is not a bug. This avoids a second round trip for information that could have been asked up front. It is one shared state with independent questions, not a chain of reasoning among answers. Pattern · Parallel-questions cookbook

Confidence-gated routing

The chosen label says what Jev thinks; the distribution or confidence informs whether the workflow should act. Lower-stakes routes can have different thresholds from irreversible or consequential actions. The published voice-banking example uses different gates for checking a balance and approving a transfer. Treat its numeric cutoffs as illustration, then tune your own against labeled outcomes. Pattern · Confidence

Composite scoring

Ask for separate, single-dimension Scores and combine normalized results with explicit weights in code. The resume example scores Python depth, leadership, system design, and generalist breadth, then weights them differently for a senior individual-contributor role and an engineering-manager role. The weights are a business rule; Jev supplies the semantic measurements. Evaluate whether those dimensions and weights match the intended decisions before automating them. Pattern

Intent routing

Classify an incoming request and send it to ordinary code, a specialist LLM, or a person. TypeSafe’s customer-service example handles order status with code, sends product or return questions to specialist LLMs, and routes unclear or complex complaints to a person. Jev can therefore replace an LLM used merely to decide what handler to call, while retaining an LLM where a generated answer is needed. Pattern

9. The cookbook atlas

The cookbook index currently lists 18 worked recipes. Each row below states the reusable mechanism, not a claim that the published result transfers to another dataset.

Three transferable lessons stand out:

• First find candidates, then judge them. This recurs in reranking, entity alignment, span extraction, and skill suggestion. Candidate recall puts a ceiling on the system’s recall.
• A forced best option is not evidence of a valid option. The line-search recipe pairs selection with an existence check; classification recipes add other, none, uncertainty, or a broader label.
• Verification should compare against evidence. Repeating the same judgment over the same thin state may reveal instability, but a receipt, source passage, policy, or detailed candidate record gives a second-stage checker a stronger basis.

10. Industry use-case map

TypeSafe’s example use-case map is an idea catalog. The following are concrete Jev-sized judgments that one could test within those domains; they are not validated deployments.

The map also includes search, scientific discovery, model routing, LLM guardrails, semantic code linting, and feature extraction. Software modernization is an adjacent inference rather than a named industry in that map: Jev could classify legacy artifacts against explicit migration criteria or flag convention violations; a coding model or developer would perform the actual transformation. Example use cases · Structure recovery

11. Reference architectures

A. Jev plus code: closed decisions

Flow: acquire input → exact parsing and validation → build a compact state → ask narrow Jev questions → apply code thresholds and policy → act or review → store evidence and outcome.

Use this for classification, triage, matching, and scoring when the outputs and actions are known in advance. A personal-expense category is one example, but the pattern applies equally to ticket routing and product normalization. Exact totals and dates stay in code. Primitives · Confidence-gated routing

B. Jev as a selector before an LLM

Flow: classify request or retrieve candidates → Jev decides the route or useful context → code invokes the selected specialist LLM only where text generation is necessary.

Use this when a general LLM is currently spending time merely identifying intent, deciding which tool to use, or reading irrelevant retrieved passages. Intent routing · Classifying RAG passages · Function calling

C. Jev as a verifier after an LLM

Flow: LLM proposes an answer or extraction → code performs exact source/schema checks → Jev asks narrow source-grounded verification questions → code accepts, escalates, or requests correction.

Use this for claim support, field extraction, policy checks, and agent guardrails. Verification is strongest when the source evidence is provided and the failure mode is stated precisely. Citation checking · SDE cascade · LLM guardrails

D. Jev as a feature generator

Flow: define semantic questions → Jev converts text to probabilities or scores → join with structured features → train and evaluate a conventional model → monitor performance over time.

Use this when there are many labeled examples and a prediction target, such as demand or churn. Do not assume more Jev features automatically help; hold out data and compare against simpler baselines. Autoresearch feature discovery · Example use cases

12. Evaluation and deployment

The cookbooks establish possible designs. Before using Jev for a new decision, measure that decision on representative local data.

1. Define the outcome and its errors. Specify the labels or action, acceptable abstention, cost of false positives and false negatives, and what a reviewer should see.
2. Build a trusted evaluation set. Include common cases, rare cases, neighboring labels, missing evidence, messy inputs, adversarial wording, and examples from different time periods or data sources. Keep a held-out portion for final selection.
3. Compare realistic baselines. Test code-only rules or search; Jev plus code; and an LLM workflow when one exists. Include latency, billed input tokens, total cost, accuracy by class, and the number routed to review.
4. Test the whole route. A high category accuracy is insufficient if the workflow takes the wrong action when confidence is low or evidence is absent. Report both automatic coverage and error rate among automatic decisions.
5. Check probabilities empirically. Measure whether answers grouped by predicted probability achieve corresponding observed frequencies on your task. Test thresholds against the cost of each action. The documented confidence value alone is not a substitute for this check.
6. Audit changes. Pin a versioned model ID once tuned, retain the question and criteria version, and rerun the evaluation before switching a model alias, changing descriptions, adding classes, or changing retrieval.
7. Monitor production cases. Sample accepted decisions for review, record corrections, and look for shifts by input source, language, category, and time.

This is an evaluation recommendation derived from Jev’s documented probabilities, routing patterns, and version behavior. TypeSafe itself says its example thresholds depend on the application and that a moving alias can change answers. Confidence · Models · Self-consistency: Choices

Suggested decision record: source identifier; the exact relevant source excerpt or a retrievable reference; state/question/criteria versions; returned model ID; typed answers and full distributions; code threshold and chosen route; reviewer correction; final outcome. Keep sensitive data retention and access consistent with the application’s policy.

13. Known limitations and failure modes

TypeSafe maintains a Jev 1.13 jaggedness page, last reviewed 17 September 2026. The important limitations are:

Other practical limits: text only; bounded request context; a maximum of 255 Choice options and 10 Score levels; rate limits; and candidate-generation recall in any shortlist-based workflow. A closed output shape prevents invalid free-form formatting, but it does not prevent a semantically wrong label or a high-confidence error. Models · API reference · Re-ranking cookbook

14. Current technical and commercial facts

Snapshot, 24 September 2026. These facts can change; recheck the models page before budgeting or deployment.

Sources: Models · API reference · SDKs · Legal documents

For production, prefer the versioned model ID after an evaluation; record the response’s model field. The SDKs retry rate-limited or overloaded calls with backoff by default. Direct HTTP integrations should handle 429 and 529 with backoff, and should treat 401 and 422 as configuration or validation errors rather than normal semantic uncertainty. The Python SDK can log request and response bodies at debug level, so avoid debug logging sensitive state without an appropriate policy. Models · API errors and rate limits · Python SDK usage

The Python SDK documents TypeSafe-compatible routes through OpenRouter and Vercel AI Gateway. Those routes use their own base URLs, credentials, and model IDs. Verify gateway pricing, limits, and data terms separately; the direct TypeSafe figures above do not automatically describe an intermediary. Python SDK usage

15. Further reading

Start here: Introduction → State → Primitives → Confidence → Patterns → Cookbooks.

To integrate: Quick start · API reference · Python SDK · JavaScript SDK · Models.

To challenge a proposed use: Jev 1.13 jaggedness · Self-consistency: Choices · Classification using confidence · Example use cases.