state and returns a probability for every answer each question allows. This page defines the three question types, the fields that link questions together, the bounds a question set must fit, and the exact shape of every answer. Read it when you design a question set; the Decision runs guide then shows how to act on the answers.
The parts of a decision run
Question types
Every question has atype and instructions. Unknown keys inside a question are refused.
- noul (yes/no)
- choice (one of N)
- score (ordered level)
A yes/no question. The answer names are always
criteria is optional; when present, true and false describe each side.yes and no. Use them in ask_if.probability is P(yes). There is no confidence field on a noul.Linking questions
Three optional fields work on every question type.
Rules for
depends_on and ask_if:
- Every id must name another question in the same set. A question cannot name itself. Forward references are fine.
- There must be no cycle; a cycle is refused with “the questions depend on each other in a cycle”.
- Every
ask_iflist must be non-empty and name answers the target can produce:yesornofor anoul, an option name for achoice, a level name for ascore.
Stages
OpenType schedules questions into stages. A stage holds every question whosedepends_on questions are all in earlier stages. Within a stage, questions are read in question_order, or in sorted id order when you send none. The response’s decision.stages lists the schedule that ran, one array of ids per stage.
This questions object adds a gated question that is only asked when the ticket is not about billing:
bucket came back billing, so sales_lead is skipped. The decision object:
bucket, tone and urgent depend on nothing, so they share the first stage, in sorted id order. sales_lead depends on bucket, so it lands in the second stage. It would have been asked only if bucket had answered other.
Answer shapes
decision.answers has one entry per question id, with keys in sorted order. Each entry has a type.
A skipped answer is never
null; check type before you read probabilities.
Every noul, choice and score answer may also carry:
label_mass: the total probability the model put on your legal labels, before the probabilities were renormalized over them.answered_within_labels: whether the model’s single most likely token was one of your labels. When it isfalse, the probabilities you see are a renormalization over labels the model did not favour, so do not treat them as calibrated. Rephrase the question or the labels.
decision, on a live response:
A stored run, read with
GET /v1/runs/{run_id} or replayed, keeps answers, draws and read but drops model, stages and the thought fields. See Runs.
Bounds
A question set outside these bounds is refused with400 invalid_decision_questions before anything is created or charged. The message starts with “the decision questions are not acceptable:” and names the reason.
Two more limits apply after a question set passes these bounds:
- Total input. The state and questions together must fit the 262,144-token context of Neon 1.1, else
413input_too_large. See Models and pricing. - Label shape. Each label is read as an answer token. Labels that cannot be read that way, or a set that does not fit the answer format, fail later with
503decision_unavailable. Short, common, single-word labels such asbilling,calmorhighare the safest choice.
Related
- Decision runs - a full request, thresholds, and how to act on each answer type.
- Conditional questions -
depends_on,ask_ifandalonein depth. - Choice questions - design options that the model can tell apart.
- Score questions - scales, the 0-indexed legend, and thresholds on a score.
- invalid_decision_questions - every refusal reason and its fix.