Judgment as a primitive
A System One model does not write. It reads a piece of state, answers typed questions about it, and hands your code a probability for every possible answer. This guide is about what that buys you, and how to build on it.
Written for developers. Illustrative numbers in the labs are made up to explain a mechanism; numbers taken from the TypeSafe docs are marked as such. The official docs remain the reference for the API itself.
The mismatch you have been coding around
Every time you use a language model as a classifier, you are asking a text generator to pretend it is a function. You write a prompt that begs for JSON, the model writes prose that is usually JSON, and then you parse, validate, retry, and quietly coerce whatever comes back into the enum your code actually needed. The model was trained to produce text a person would like. Your code wanted a value it could branch on.
A System One model removes the pretence. You send it a state (a string or a JSON document) and a map of questions, each with a fixed answer space. It returns one typed answer per question, plus the full probability distribution over the answers you allowed. Nothing is generated, so nothing needs parsing. The name comes from Kahneman's "System 1": fast, intuitive judgment, as opposed to the slow deliberate reasoning of "System 2".
Two ways to ask a model the same thing
Pick an inbound message. Left: a generative model asked for JSON. Right: a System One request and its typed answers. All values are illustrative.intent can only be one of the four options you listed, urgency is a probability of "yes", and company_size is a position on the levels you wrote. The left-hand side can drift in a hundred small ways, and each one is a bug you have to catch at runtime.What a System One model is
Three properties define the class. Everything else on this site follows from them.
Constrained answers
The answer space is yours: a set of options, an ordered scale, or yes/no. The model returns a distribution over that space and never a value outside it.
Honest probabilities
The model is trained so that, across many answers, a probability of 0.8 comes true about 80% of the time. Uncertainty becomes a number your code can act on.
Independent questions
Every question in a request is answered against the same state, separately and at the same time. Adding a question does not change the others' answers.
The first (and, at the time of writing, only) System One model is Jev, built by TypeSafe. It reads text only, English best, and answers most requests in about a tenth of a second. It does not generate text, explain itself, or pick its own next step. Those omissions are the design, not a limitation to work around: a model that only ever picks from your options is a model whose output you can type-check.
A state is the material the model looks at. A question is one judgment about that state, with an explicit answer space. A primitive is a question type: Choice picks one option, Score places the state on an ordered scale, Noul returns how likely a yes/no claim is to hold. An answer is what comes back: a typed value, and always the probabilities behind it.
Where it sits in your architecture
The mental shift is that the model becomes a function call inside a normal program, not a loop that drives the program. Compare the three shapes.
In the third shape, your code still owns every branch, side effect, and retry. It calls the model only at the points where a rule cannot be written down, such as "is this message asking for a demo?" or "does this log line describe the same incident as that one?". The answer comes back as a value with a probability attached, so the surrounding code can decide how much to trust it. That is the whole programming model, and the rest of this guide is about doing it well.
The three primitives at a glance
| Primitive | The question it answers | What comes back | Reach for it when |
|---|---|---|---|
| Choice | Which one of these? | choice, a probability per option, confidence | You hold a fixed list of labels with no order between them. |
| Score | How much, on this scale? | score (expected level), a probability per level, confidence | You can describe the steps of a spectrum in words. |
| Noul | Is this true? | noul, the probability of yes | The judgment is a clean yes/no and the probability itself is the signal. |
Part 3 takes each one apart with interactive distributions. If you only remember one thing now: the answer is never just the label. It is the label and the shape of the distribution behind it, and the shape is where most of the engineering value lives.
How to read this guide
- How it thinks: calibration, the training objective, and what makes a question a "snap judgment".
- The three primitives: Choice, Score, and Noul with distribution explorers.
- Confidence and risk: turning probabilities into act / confirm / escalate decisions, with an expected-cost calculator.
- Designing questions: decomposition, state shaping, and criteria that draw sharp boundaries.
- Composition patterns: speculative fan-out, composite scoring, gated routing, cascades, select-not-generate.
- Build guide: a worked integration, a request builder, and how to evaluate before you ship.
- Pitfalls and limits: what to keep in code, and what the current model is bad at.
- Use-case explorer: find the pattern for the thing you are building.