Choice, Score, and Noul

How to choose a primitive

Use Choice when the answer is one named option: a queue, a skill, a class label, a next link. The question TypeSafe prints is "Which of these options?" Returns are choice, probabilities, and confidence. Criteria is a map of up to 255 options. If you have hundreds of Wikipedia links, you cannot stuff them into one Choice; the Wikiracing demo scores first, then chooses among a shortlist.

Use Score when the answer is a degree on a short ordered legend: calm / frustrated / very frustrated, or a 1-5 severity. Returns are score, legend, probabilities, and confidence. Criteria is an ordered array of 2 to 10 levels. Do not interpolate the score into an exact magnitude. Jev 1.13's levels are weak for reconstructing a number between two rungs; use the expectation only as a threshold check.

Use Noul when the question is yes or no: "Is this true?" Returns noul from 0 to 1. Criteria may optionally describe true and false. There is no confidence field. A Noul near 0.5 is uncertainty, not medium intensity. Do not assume Noul equals a two-option Choice, and do not carry a threshold tuned on one over to the other. TypeSafe's jaggedness page shows a refund Noul at 0.22 beside a yes Choice at 0.01 on the same ticket.

Parallel questions and IDs

Questions in one request share state, run independently in parallel, and barely change latency as they are added. Mix Choice, Score, and Noul in the same map. Keys are yours: urgency, department, frustration. The matching answer comes back under the same key. The key is not sent to the underlying model and is not used in inference.

That ID rule matters when you generate keys in a loop. The counting example on the jaggedness page asks one Noul per list item (item_0, item_1, …) and sums the answers in Python. Jev never sees those names as tokens. Keep the names stable in your logs so you can join retries to the original map.

Shared return metadata on every primitive response includes requestId, timestamp, latency, and metadata. Use requestId to join traces. Treat timestamp and latency as transport facts, not as a reason to re-ask. Metadata is optional content attached to the core payload. Compare the three primitives first; then read those shared fields as the envelope around the typed answer.

Limits in practice

255 Choice options is a hard cap, not a suggestion. Wikiracing crosses it with a Score shortlist then a Choice. If your taxonomy has 400 labels, you need the same two-stage shape or a hierarchy of Choices. Do not hope the API will accept 256.

Score's 2 to 10 levels are for short legends a human could read aloud. A 100-point quality scale is the wrong primitive; split it into atomic Scores and add in code. Between-level scores such as 1.4 are expected. Reconstructing a dollar amount from those fractions is not.

Noul has no confidence field, so your gate is the noul value plus whatever second question you add. A common pair is Noul for "is this in scope" and Choice for "which bucket" only when noul is high. The jaggedness invariants record is the warning not to treat those two numbers as the same statistic.

A request that mixes all three primitives against one ticket is the normal shape, not an advanced trick. Urgency as Noul, department as Choice, frustration as Score, then code. That is the same map the quickstart shows in curl. The compare on this page is so you pick the type before you write the JSON.

Shared envelope fields are not a fourth primitive. requestId, timestamp, latency, and metadata travel with every answer so you can trace the call. Product facts belong in state. If you find yourself stuffing a policy into metadata, move it into the object Jev actually reads.

Write criteria as if a new teammate will read them tomorrow. Option names on a Choice and level names on a Score are part of the question. Vague labels are how literal reading shows up in production.

Noul is a proper name. Keep the spelling even when the rest of the request is English prose.