TL;DR

  • Use Choice for unordered closed-set selection.
  • Use Score when the levels have a meaningful order.
  • Use Noul for a true yes-or-no proposition, not a disguised intensity scale.
  • Split multi-dimensional judgments and combine them in code.

Choice, Score, and Noul are the three question types in TypeSafe’s System One API. They share the same state, but they describe different decision shapes. Picking the wrong primitive can produce an answer that looks precise while asking the model the wrong question.

The shortest rule is simple: use Choice for categories, Score for ordered levels, and Noul for a proposition that can be answered yes or no.

When should you use Choice?

A Choice selects one option from a closed set. The result includes the chosen option, probabilities for every option, and confidence derived from that distribution.

Good Choice questions include:

  • Which support queue fits this ticket?
  • Which tool should an agent call?
  • Which product taxonomy node fits this listing?
  • Which retrieved document is most relevant?

The options are unordered. billing is not greater than technical, and search is not a stronger version of calculator.

const route = choice("Which team should handle this request?", {
  billing: "Payment, refund, or subscription issue",
  technical: "Bug or integration issue",
  account: "Login or account access",
  other: "None of the listed categories",
});

Include other or none_of_the_above when the taxonomy may not cover every valid input. Otherwise the model must select the least-wrong listed option.

Choice can accept many options, but a large overlapping taxonomy still needs design work. Clear descriptions and a hierarchical approach often work better than one flat list whose categories differ only by internal company language.

When should you use Score?

A Score uses ordered, descriptive levels. It returns an expected score, probabilities across levels, and confidence.

Good Score questions include:

  • How severe is this incident?
  • How relevant is this passage to the query?
  • How frustrated is the customer?
  • How much risk would the proposed action create?
Score(
    instructions="How urgent is this request?",
    criteria=[
        "can wait",
        "needs attention soon",
        "needs attention today",
    ],
)

The level descriptions do the real work. Labels such as low, medium, and high leave more room for interpretation than descriptions tied to observable conditions.

The expected score is useful for sorting or thresholding, but keep the distribution. An average near the middle can mean the model strongly prefers the middle level, or that probability is split between the two extremes. Those situations may deserve different behavior.

TypeSafe’s known Jev 1.13 limitations warn against treating Score as a calculator. It is a semantic rubric, not a way to reconstruct an exact amount between levels.

When should you use Noul?

A Noul asks whether a proposition is true and returns the probability of yes.

const asksForRefund = noul(
  "Does this message ask the company to return a payment?",
);

Values near 1 support yes. Values near 0 support no. A value near 0.5 means the model sees similar probability on both sides.

Noul does not return a separate confidence property because its single probability already describes the yes/no distribution.

Use Noul when both sides are meaningful. “Does this request mention a cancellation?” has a clear yes and no. “Is this customer medium-skilled?” does not. Skill is an ordered concept, so Score is a better fit.

A decision table for the three primitives

Decision shape Primitive Example
Pick one unordered option Choice route to billing, technical, account, or other
Evaluate ordered intensity Score calm, concerned, frustrated, very frustrated
Test a proposition Noul does the passage support this claim?
Return a new string Neither use extraction code or a generative model
Calculate an exact number Neither calculate in code
Apply a multi-part business policy Several questions plus code evaluate dimensions, then apply rules

The last row is where many integrations go wrong. A policy may contain semantic judgments, but the policy itself should stay visible and testable in application code.

Do not turn one broad question into a hidden model policy

Consider this question:

Should we block this user action?

It may hide several independent concerns: policy category, severity, confidence in the evidence, account eligibility, and whether the action is reversible.

A safer design asks narrow questions such as:

  • Choice: which policy category applies?
  • Score: how severe is the content under that category?
  • Noul: is the evidence sufficient to take action?

Code then checks exact account state and applies the threshold for the proposed action. That makes the result easier to debug and gives product owners control over the consequence.

TypeSafe’s composite scoring pattern applies the same idea to weighted evaluations. Ask each dimension separately, normalize it, and combine it with weights owned by code.

Ask parallel questions only when they are independent

All three primitives can appear in one request. TypeSafe evaluates them independently against the same state.

That is useful for classifying a ticket, rating its urgency, and checking for a refund request at once. It is not useful when the second question needs the first answer.

For a dependent flow:

  1. Ask the first question.
  2. Let code choose the next state or candidate set.
  3. Make a second request.

Trying to imply a dependency through question wording makes the flow harder to test and does not change how the API evaluates questions.

Check the boundaries with examples

Before production, write cases around the boundary between neighboring options or levels. If billing and account are often confused, add examples that isolate the distinction and review whether the taxonomy matches how customers describe their problem.

Also test missing information. A low-confidence result may indicate an ambiguous input, overlapping criteria, or a question that asks for facts not present in the state. The right response may be to request clarification rather than tune the prompt until the model sounds certain.

For a complete integration, use the TypeScript quickstart or Python tutorial.

Sources

FAQ

What is a Jev Choice?
Choice selects one option from a developer-defined set and returns the selected option, a probability for every option, and confidence.
What is a Jev Score?
Score evaluates state against ordered descriptive levels and returns an expected score, the level distribution, and confidence.
What is a Jev Noul?
Noul evaluates a yes-or-no proposition and returns the probability that the answer is yes.