Four types. Every type names its answer: choice (one of your labels), score (a level on your scale), truth (a probability), number (a value on your grid).
| Type | Goal | What comes back |
|---|---|---|
Choice choice | Pick one option from the list you give | choice (always one of your keys), probabilities per option, confidence |
Score score | Place the input on your ordered scale or rubric | score (expected level, for example 2.31 of 0 to 3), probabilities per level, legend, confidence |
Truth truth | Is this statement true? | truth, one probability from 0.00 to 1.00 that the statement is true |
Number number | How many, or what value? | number (a value on your grid), expected, confidence, probabilities per value |
The questions map#
questions is an object. Its keys are your names for the questions, and the answers come back under the same keys. Use short, stable names your code can read, such as route or refund. The keys are labels for your code: the model reads the type, the instructions and the criteria.
{
"questions": {
"route": {
"type": "choice",
"instructions": "Where should this go?",
"criteria": { "billing": "money", "bug": "broken", "account": "login" }
},
"urgency": {
"type": "score",
"instructions": "How urgent is this?",
"criteria": ["routine", "today", "urgent", "critical"]
},
"refund": {
"type": "truth",
"instructions": "Refund this automatically?"
}
}
}Question fields#
type"choice" | "score" | "truth" | "number"required- Fixes the answer's shape: choice, score, truth or number.
instructionsstring- What to decide, in plain words. Optional on every type, but almost always worth one sentence, and a number question reads best with one.
criteriaobject | string[]- Choice: an object of option keys to what each option means (up to 255), required. Score: an array of levels from lowest to highest (up to 10), required. Truth: optional
{ "true": "...", "false": "..." }describing what true and false mean. Number: not used. min, max, stepnumber- Number only: the grid of values the answer can take. Default 0 to 255, step 1; up to 256 values in the first release. See Number.
Writing questions that work#
- Ask one thing. "Is this urgent and about billing?" is two questions. Split it and you get two calibrated answers.
- Describe every option.
"bug": "something is broken"beats a bare key. The description is what the model compares against. - Cover the space. If an input can fit none of your options, add one for that, such as
"other": "none of these". A choice always returns one of your keys. - Order scales from low to high. Score levels are indexed from 0 in the order you send them, and the expected score depends on that order.
- Phrase a Truth question as a statement that can be true. "Does the receipt show the same total as the claim?" reads better than "check the receipt".
- Give a number question the range it can really take. "How many cars are visible?" on 0 to 50 for a ten-bay row, not the default 0 to 255. A tight grid puts the probability where it belongs.