/jev-engineering

name: jev-engineering
description: >-
  Design and build use cases, POCs and production systems with TypeSafe's Jev decision model (System One): choose a design mode and a use-case archetype, build decision state, write typed questions, combine Jev with generative models, durable workflows, retrieval and perception tools, aggregate and gate in code, keep failures and costs visible, evaluate and roll out; covers the jev-1.14 danger-zone features (images, Box, long context). Use when building anything with Jev, from a first POC to a product, or when reviewing an existing Jev integration. Ships dependency-free reference clients (TypeSafe API, OpenRouter Decisions, Vercel AI Gateway) and a POC skeleton. For primitives and live docs alone use TypeSafe's typesafe-ai skill; not for generic LLM prompting.

Jev Engineering

Jev judges the text (and, behind a danger-zone header, the images) you send against the criteria you write and returns typed answers with probabilities: Noul (P of yes), Choice (option + distribution + confidence), Score (expected level + distribution + confidence), and on jev-1.14 Box (one bounding box + confidence). It does not generate text, count, do arithmetic, read dates as quantities, establish truth, confer permission, or prove that a side effect happened. Everything else is ordinary software you own: state builders, candidate lists, arithmetic and dates, policy and thresholds, workflows, execution and verification. Generative models write artifacts and literals; Jev routes before and checks after. That division is what makes use cases like editorial studios, diagnostic banks, obligation trackers, dossiers, corpus atlases, rule packs, memory judges, signal observatories and agent loops cheap, fast and inspectable.

Facts to design around (jev-1.13 and jev-1.14, checked live 2026-10-17; re-check https://docs.typesafe.ai/models.md when they matter)

| | | |---|---| | Models | `jev-1.14.0` (released 2026-10-14: small gains everywhere, largest in non-English) and `jev-1.13.0`, same price and limits. `jev-preview` → 1.14; `jev-latest` → 1.13 until TypeSafe moves it to 1.14 (announced for about 2026-10-21). 1.13 gets 60 days' notice before deprecation, 1.14 gets 30. OpenRouter slug `typesafe/jev-1.14`; Gateway lists `typesafe-ai/jev-1.14.0` | | Request | `state` (string or JSON) + a map of typed questions evaluated independently against the same state in one call; no question sees another's answer; optional `assets` map of images referenced from state, instructions or criteria | | Limits | 32k tokens for state + longest question, 64k for state + all questions (262k for both with the long-context header); Choice ≤ 255 options; Score 2–10 levels; English is the primary language | | Answers | Noul has no separate confidence. Choice/Score `confidence` is distribution concentration, not accuracy. Score levels are 0-indexed. Box returns four edges as fractions and has no "not found" answer | | Danger zone (not production-grade by TypeSafe's own word) | `TypeSafe-Danger-Zone-Images: true` for images and Box (Box needs 1.14), `TypeSafe-Danger-Zone-Long-Context: true` for 262k; TypeSafe API only for images (OpenRouter drops `assets` silently). See `references/images.md` | | Speed, price | 0.2–0.6 s per call at 1–4k tokens in production runs; list price US$ 0.042 per million input tokens, output free, images billed as input (≈ width × height / 390 tokens); tens of parallel calls sustained; hundreds of questions per text and thousands of texts per dollar are the normal design space | | Documented weaknesses | counting; numeric comparison; large state full of irrelevant detail (accuracy falls); adversarial text in the state (can move answers); instructions that contradict criteria; extra levels of indirection; literal reading of the question you wrote; images are worse than text on every model, so decompose them further |

Procedure

Read by task: a new idea → `references/design-modes.md` and the closest archetype in `references/use-cases.md`; a transport or reliability review → `references/transport.md` and `references/reliability.md`; question or rubric work → `references/questions.md`; scoring or gates → `references/aggregation-and-gates.md`; images, Box, long context or a model upgrade → `references/images.md`. The steps below are the full build path; take only the ones the request needs.

1. **Choose the mode and the archetype.** Read `references/design-modes.md` (whole decision in one state · question bank as instrument · multi-stage state machine, and how they combine) and pick the closest shape in `references/use-cases.md` (twelve built archetypes with loop, state, questions, code, tools, gates, evaluation and observed numbers). 2. **Define one decision with known outcomes**, an existing fallback and examples you can label. Write it as: given [named evidence], decide [one property] using [explicit criteria]. 3. **Build the state in code** (`references/state.md`): what the decision needs, nothing else, provenance fields, candidates proposed by code. 4. **Write the questions in a versioned file** (`references/questions.md`; bank shape in `assets/question-bank.example.json`): guard prefix, polarity that matches the criteria, an abstention with a distinct meaning, counter-examples inside the criteria, no double negatives. 5. **Pick mechanisms and tools** (`references/mechanisms.md`, `references/tooling.md`): unit and candidate builders, relation/closure pairs, staging, aggregators; what a generative model, a workflow engine, retrieval, vision/STT/PDF extraction and storage each own. 6. **Run the POC** with `assets/poc_skeleton.py` (question map over a JSONL, cache, table of distributions, confidence, cost, latency) on ~100 items; read the table; label ~30; fix vocabulary and criteria before thresholds. 7. **Aggregate and gate in code** (`references/aggregation-and-gates.md`): persist raw answers, name the gate quantity, thresholds per action risk from labeled cases,