Writing questions

The state

state is whatever the questions are about. It can be a string, or any JSON object or array, which is sent to the model as JSON. Put all the context the model needs here, because each question sees only the state and its own instructions and criteria.

{"state": {"subject": "Refund?", "body": "I was charged twice in September.", "plan": "team"}}

noul: yes or no

A noul answers a yes/no question with the probability of yes. You can define what yes and no mean with criteria; it is optional.

"wants_refund": {
  "type": "noul",
  "instructions": "The customer is asking for a refund",
  "criteria": {"true": "explicitly asks for money back", "false": "anything else"}
}

"wants_refund": {"type": "noul", "noul": 0.93}

choice: pick one

A choice picks one of up to 128 named options. The criteria object maps each option name to a description, or to null when the name speaks for itself. The answer contains the most likely option, the probability of every option and a confidence.

"topic": {
  "type": "choice",
  "instructions": "Primary topic of the message",
  "criteria": {"billing": "charges, invoices, refunds", "bug": "something is broken", "other": null}
}

"topic": {
  "type": "choice",
  "choice": "bug",
  "probabilities": {"billing": 0.04, "bug": 0.95, "other": 0.01},
  "confidence": 0.81
}

score: a scale

A score places the state on an ordered scale of 2 to 10 levels, listed from lowest to highest. The answer's score is the expected level, Σ i·pᵢ with levels numbered from 0, so it can fall between levels. legend echoes your levels.

"sentiment": {
  "type": "score",
  "instructions": "Overall sentiment",
  "criteria": ["negative", "neutral", "positive"]
}

"sentiment": {
  "type": "score",
  "score": 1.62,
  "legend": {"0": "negative", "1": "neutral", "2": "positive"},
  "probabilities": {"0": 0.03, "1": 0.32, "2": 0.65},
  "confidence": 0.62
}

Many questions at once

Put every question about the same state in one request. They share one read of the state, so ten questions cost far less than ten requests. Large sets are split into chunks and answered in parallel. Question ids only key the answers and are never shown to the model, so name them for your code rather than for the model.

Tips

• Be concrete. "Does the customer need a reply within the hour?" beats "urgent?".
• Describe options by what they contain, not just by their names, especially when names overlap.
• Add an explicit fallback such as "other" to choices, so the model is never forced into a bad fit.
• Instructions and descriptions can be JSON when you already have structured definitions.