/building-with-typesafe-jev

name: building-with-typesafe-jev
description: Use when code needs a judgment about natural language that rules or regex cannot make (classify, route, triage, moderate, score, rank, match, dedupe, filter, extract, verify, or gate an action), when brainstorming where AI could fit in an app, when an LLM call exists only to pick a label, score, or yes/no, or when code uses TypeSafe AI, Jev, System One, typesafe-sdk, or @typesafe-ai/sdk.

Building with TypeSafe Jev

Overview

Jev is a **System One model**: it takes a `state` plus named, typed questions and returns typed answers with calibrated probabilities. It never generates text. **Code owns the workflow. Jev supplies narrow snap judgments.** It is not a chat or coding LLM and cannot power a coding agent.

**Before you design anything new, check prior art:** open `prior-art/INDEX.md`. It maps intents (control loop, gate, rerank, stream filter, incremental, agent memory, LLM pairing, and more) to shape files. Each shape file has a code sketch, field lessons, and linked community projects. Or grep `prior-art/` for a domain word. It also lists the known bad fits.

Exact request/response shapes, SDK signatures, limits, and errors: see `api-reference.md`. It ends with a map of which live docs page to read for which task. Patterns and the cookbook index: see `patterns.md`. The live docs win on conflict: fetch `https://docs.typesafe.ai/llms.txt`, and append `.md` to any page path. Do not guess field names. Check them there. If the docs cannot be reached, read the installed SDK's types, tell the user you did, and do not invent details that depend on the version.

**Open-ended request** ("where could AI help in this app?"): work backward from what the app should show, select, change, or hand off. Offer two or three directions from `prior-art/INDEX.md` and recommend one. **Concrete request:** pick the shape and build. Either way, keep the user's stack and scope, and add Jev only where code needs a judgment.

Test against the live API when you can

You get better results when you check a design against the real endpoint. A live call catches a wrong field name, and it shows when Jev reads a question differently than you meant. If `TYPESAFE_API_KEY` is set in your shell, run a small probe before the code reaches the project. One call costs a fraction of a cent (input tokens only, 4.2 cents per million). If the key is not set, design from `api-reference.md` and say that you did. Do not go looking for the key in `.env` files, shell profiles, or key files. Point the user to the README section "If the agent cannot see the key".

**Rules for the key:**

• Do not print, echo, log, or commit it.
• Do not hardcode it or pass `api_key=` in code. Let the SDK read `TYPESAFE_API_KEY`. Keep it server-side.
• `TYPESAFE_LOG_LEVEL=debug` logs request bodies without redaction. Headers stay redacted.
• A `401` or `TypeSafeAuthenticationError` means the key is wrong or rotated. Ask the user to replace it where they stored it, never in the chat.
• Keep a task to about 10 test calls, and probe loops to about 8 workers or fewer. Rate limits are shared across the account.

Pick the primitive

| Answer shape | Primitive | Returns | Branch on | |---|---|---|---| | One of an unordered set | `Choice` (≤255 options, map) | `choice`, `probabilities`, `confidence` | `choice`; gate with `confidence` | | Position on a spectrum you can describe | `Score` (2–10 levels, ordered list) | `score` (0…n-1, can be fractional), `legend`, `probabilities`, `confidence` | threshold or sort `score` | | Yes/no | `Noul` (optional `true`/`false` criteria) | `noul` = P(yes), **no `confidence`** | `noul > threshold` |

A Noul of 0.5 means "unsure", never "medium". Degree questions ("how strong in Python") need a Score. Several labels that can apply at once need one Noul per label, not a Choice.

Rules

1. **One snap judgment per question.** Pose something a knowledgeable person decides in a second. Split "angry AND wants refund" into two questions and combine them in code. Atomic does not mean trivial: picking one bounded action or reading one message in context is a single judgment. Do not split apart a relationship the question is about (does this passage support that claim?). 2. **Put every question for one state in one request**, including speculative ones. They run in parallel and in isolation. Extra questions add almost no latency, but each one adds input tokens, so check `usage.input_tokens` on a real request. Write the premise into the text: `"If this is a technical problem, how severe is it?"`. Code ignores the answers on branches it does not take. 3. **A second request only when the first answer is needed to build it**: to fetch more state, to build new state, or to pick the next options (hierarchical walk, shortlist then full text). 4. **Question IDs are never sent to the model.** Write the full question in `instructions`. 5. **Write the exact condition.** Jev reads literally: it answers the question you wrote, not the one you meant. Scope words, negations, and implied conditions count at face value. When a wrong answer makes you explain what you really meant, that explanation is the missing half of the instruction. Put boundary cases in the criteria. Avoid double negatives and property-of-a-property hops. Name the state path instead. 6. **Structure state as a named JSON object.** Point at parts with backticked paths: ``"Does `ticket.messages[0].text` request a refund?"``. Send only what the question needs. Irrelevant state lowers accuracy. Include metadata (plan, timestamps) only when a question refers to it. 7. **Score levels describe situations, not degrees.** Write `"Broken feature, workaround exists"`, not `"moderate"` or `"2"`. Each level is judged alone, so "worse than the previous level" means nothing. Give each level one dimension. 8. **Choice: give the full option list plus `other` / `none_of_the_above`**. When two options get confused, make each value an objec