Building With Typesafe Jev

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

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 object: {"what": ..., "not_for": ..., "examples": [...]}. Use the same keys on every option.
9. Phrase a Noul so that high = yes. Keep criteria aligned with the instruction. Never map true to a "no" meaning.
10. Keep math, counting, dates, and exact lookups in code. To count, ask one Noul per candidate and sum. For dates, extract the parts with Choices (include not_stated) and compare in code. For extraction, find candidates with regex or an LLM, then let Jev pick among them. To count distinct items, split into candidates in code (sentences, lines). Ask two Nouls per candidate: "is this an X?" and "is this X different from those in items[0..i-1]?". Sum the answers in code. Turn hex colors, RGB triples, and raw codes into a computed number or a named bucket before Jev sees them. The same goes for a safety condition you can write exactly, when a miss cannot be undone: a denylist of destructive commands, a spending limit, a protected branch. Check it in code before Jev runs. Jev may make that decision stricter, never looser.
11. Put questions, thresholds, and weights in one constants module. Those are what humans review and tune.