Decision types

​

Binary

{"id": "urgent", "kind": "binary", "question": "Does the ticket state a deadline within one day?",
 "outcomes": {"yes": "An explicit deadline is today or within the next 24 hours.",
              "no": "The deadline is later, absent, or unclear."}}

"urgent": {
  "kind": "binary",
  "probabilities": {"yes": 0.912, "no": 0.088},
  "top": "yes",
  "p_top": 0.912
}

• outcomes is optional. When you send it, its keys are yes and no, each with a description of when it applies.
• probabilities.yes is the probability that the answer is yes.
• Ask the question the positive way round. “Does the ticket state a deadline?” is easier to answer and to label than “Is this not urgent?”.

​

Single

{"id": "team", "kind": "single", "question": "Which team should handle this ticket?",
 "outcomes": {"billing": "Charges, invoices, and financial exports.",
              "technical": "Other application failures.",
              "sales": "New purchases."}}

"team": {
  "kind": "single",
  "probabilities": {"billing": 0.927, "technical": 0.054, "sales": 0.019},
  "top": "billing",
  "p_top": 0.927
}

• List the outcomes as names, such as ["billing", "technical", "sales"], or as a map from each name to a description of when it applies. Descriptions help most where two outcomes meet.
• A decision has 2 to 255 outcomes, and their names differ. abstain is reserved for the abstain policy.
• If none of your outcomes might fit, add one such as other or none.

​

Ordinal

{"id": "impact", "kind": "ordinal",
 "question": "How severe is the reported impact on the customer's work?",
 "outcomes": ["0", "1", "2"],
 "rubric": ["Minor inconvenience; the task can still be completed.",
            "The task is impaired, but a workable alternative is stated.",
            "An important task is blocked and no workable alternative is stated."]}

"impact": {
  "kind": "ordinal",
  "probabilities": {"0": 0.051, "1": 0.106, "2": 0.844},
  "top": "2",
  "p_top": 0.844,
  "expected_level": 1.793
}

• outcomes lists the levels in order, lowest first. rubric describes each level, in the same order. An ordinal decision needs both.
• expected_level is the average level, weighted by the probabilities. It counts positions from 0, not the values of your labels: on a low, medium, high scale it runs from 0 to 2.
• Sort a queue by expected_level, or use top as a label.

​

Mix kinds in one request

​

Rules every decision follows

• A request asks 1 to 128 decisions. A model may take fewer: max_questions in /v1/models, which a fine-tuned model shares with the model it was trained from.
• Keep outcome names short and put the detail in descriptions. If several decisions in a request have an outcome name over 500 characters, they must all list the same outcomes in the same order. Send other decisions in a request of their own.
• Keep the order of the outcomes fixed when you reword a decision, and when you fine-tune a model on it.
• A decision that breaks a rule is refused with 422 invalid_request, and error.details names the field.