Choice

Select one option from a defined set. The answer has the chosen option, a probability for every option, and a confidence.

Request

{"state": "My running shoes arrived in the wrong size.",
 "model": "jers-latest",
 "questions": {"department": {"type": "choice", "instructions": "Which team should handle this?",
                              "criteria": {"returns": "Exchanges, wrong or damaged items",
                                           "shipping": "Delivery status, delays, lost packages",
                                           "billing": "Charges, invoices, payment problems"}}}}

criteria is a map of 1 to 255 option names to descriptions. Descriptions may be strings or JSON objects.

Up to 20 options are read in one pass. With more, the engine's one-pass answer collapses toward a few options, so Jers asks in two rounds: the options in groups of up to 20, then the group winners against each other. Measured on 2026-09-23: 8 of 8 right at 40, 80 and 255 options, 53 to 222 ms. The answer then has "rounds": 2, and usage.engine_answers counts every group; the extra rounds are not billed.

The engine is sensitive to the order of the options: the engine's authors report 15 to 23% of answers changing when the options of a 20-option choice are reordered. "robust": true asks each choice in up to three fixed orders built from the sorted option names and averages them, so the caller's order no longer matters; the answer has orders and agreement (the share of orders that picked the winner). A 2-option choice has only 2 orders; {"orders": n} sets 1 to 5. Each order is billed as an answer. This applies to choices of up to 20 options: a larger choice is answered in two rounds, in groups that follow the order you wrote, and is not asked in several orders.

Answer

{
 "department": {
  "type": "choice",
  "choice": "returns",
  "confidence": 0.249,
  "probabilities": {
   "returns": 0.623,
   "shipping": 0.319,
   "billing": 0.058
  }
 }
}

choice is the option with the highest probability. confidence is reported when the engine computes it (Jers does); it summarises how concentrated the probabilities are.

Guidance

• Include other or none_of_these when the options may not cover the state.
• Keep options mutually exclusive; overlapping descriptions split the probability.
• For deep hierarchies, chain Choice questions level by level, or put the children inside each parent's description so the engine sees the subtree.
• Gate actions on confidence; see Confidence.
• Do not name a forbidden option in a rule you put in memory; see Rules in memory.