Question types

Every entry in the questions map of POST /v1/systemone specifies one of three primitives via its type field: choice, noul, or score.

Primitive	Question asks	Answer fields	Control-flow equivalent
choice	Which of these 1–1,024 named options?	choice, probabilities, logits, confidence, mouse	switch (answer.choice)
noul	Is this binary condition true?	noul (0.0 to 1.0), probabilities, logits, mouse	if (answer.noul >= threshold)
score	Which of these 2–10 ordered rubric levels applies?	score, legend, probabilities, logits, confidence, mouse	if (answer.score >= level) / sort key

Question IDs (the keys of your questions map) are for your code—they are echoed back in answers and are not sent to the model. Always write the full question in instructions and criteria.

---

choice

Use choice when the answer is one of a closed set of mutually exclusive options with no inherent numeric order: selecting a tool, routing a ticket to a department, or classifying a failure category.

Request shape

{
  "next_tool": {
    "type": "choice",
    "instructions": "Which tool should handle `task` next?",
    "criteria": {
      "edit_file": "Modify source code in a file",
      "grep_search": "Search for symbols across the repository",
      "run_tests": "Execute the test suite",
      "ask_user": "Ask the user for clarification"
    }
  }
}

• criteria is a JSON object mapping each option key (1 to 1,024 options) to a description string, a structured JSON object, or null when the option key is self-explanatory.
• Include an explicit fallback option (such as "other", "unknown", or "none") whenever your option list might not cover every possible input. Without one, probabilities are still normalized to sum to 1.0 across the supplied options.

Answer shape

{
  "type": "choice",
  "choice": "edit_file",
  "confidence": 0.88,
  "probabilities": {
    "edit_file": 0.91,
    "grep_search": 0.06,
    "run_tests": 0.02,
    "ask_user": 0.01
  },
  "logits": {
    "edit_file": 2.41,
    "grep_search": -0.31,
    "run_tests": -1.41,
    "ask_user": -2.1
  },
  "mouse": {
    "calibrated": false,
    "p_top": 0.91,
    "abstain": null,
    "confidence_winning": 0.91,
    "confidence_normalized": 0.88
  }
}

• logits are the raw per-option log-scores; softmax(logits) == probabilities. Log them with model if you fit thresholds offline.
• Always threshold on probabilities, mouse.p_top, or the margin between the top two options, not on a vendor's confidence scalar: the same distribution reads 0.91 under the winning convention and 0.88 under the normalized one. Both are returned by name in mouse so a threshold fitted elsewhere ports without arithmetic.
• Pass order_invariant: true on the request to have Mouse score the question a second time with the options reversed and average the two distributions.

---

noul

Use noul for a binary yes/no predicate: whether a command is safe to run without approval, whether a test log supports a completion claim, or whether a message requests a refund.

Request shape

{
  "safe_to_run": {
    "type": "noul",
    "instructions": "Is `proposed_command` safe to execute without human approval?",
    "criteria": {
      "true": "Read-only command, local test run, or scoped cleanup inside ./tmp",
      "false": "Force push, production mutation, credential access, or destructive rm outside ./tmp"
    }
  }
}

• Phrase instructions positively so a value near 1.0 means true (yes) and a value near 0.0 means false (no).
• Ask one atomic condition per noul. Instead of asking "Is the command safe and did the user ask for it?", ask two separate noul questions (is_safe, user_requested) in the same request and combine them with && in code.
• criteria ({ "true": ..., "false": ... }) is optional; add it when you want to pin down subtle edge cases on each side of the boundary.

Answer shape

{
  "type": "noul",
  "noul": 0.03,
  "probabilities": { "false": 0.97, "true": 0.03 },
  "logits": { "false": 1.74, "true": -1.74 },
  "mouse": {
    "calibrated": false,
    "p_top": 0.97,
    "abstain": null,
    "confidence_winning": 0.97,
    "confidence_normalized": 0.94
  }
}

• noul is the probability of true (0.0 to 1.0). probabilities carries the same distribution in the shape choice uses, so one code path can read every answer type.
• mouse.p_top is (\max(\text{noul}, 1 - \text{noul})) (0.97 above, because the model is 97% certain the answer is false).

---

score

Use score when the judgment falls along an ordered spectrum of 2 to 10 concrete levels: patch quality, bug severity, customer frustration, or action blast radius.

Request shape

{
  "patch_quality": {
    "type": "score",
    "instructions": "How completely does the patch address `objective`?",
    "criteria": [
      "Tests fail, build breaks, or objective is missed",
      "Partial fix or missing regression test",
      "Addresses objective cleanly and all checks pass"
    ]
  }
}

• criteria is an ordered array of level descriptions from index 0 (lowest) to N - 1 (highest).
• Describe concrete situations, never bare numbers or vague degrees: Write "Broken feature, but a workaround exists", not "Medium" or "1". Each level is scored against state on its own wording.

Answer shape

{
  "type": "score",
  "score": 1.88,
  "confidence": 0.85,
  "legend": {
    "0": "Tests fail, build breaks, or objective is missed",
    "1": "Partial fix or missing regression test",
    "2": "Addresses objective cleanly and all checks pass"
  },
  "probabilities": {
    "0": 0.02,
    "1": 0.08,
    "2": 0.90
  },
  "logits": {
    "0": -3.81,
    "1": -2.42,
    "2": 0.0
  },
  "mouse": {
    "calibrated": false,
    "p_top": 0.90,
    "abstain": null,
    "confidence_winning": 0.90,
    "confidence_normalized": 0.85
  }
}

• score is the expectation-weighted average level index: [ \text{score} = \sum_{i=0}^{k-1} i \cdot p_i = 0 \times 0.02 + 1 \times 0.08 + 2 \times 0.90 = 1.88 ]
• To combine multiple score questions of different lengths in code, normalize each score to 0.0 .. 1.0 by dividing by len(criteria) - 1.

---

How confidence is calculated

choice and score answers include a confidence field in 0.0 .. 1.0 computed deterministically from probabilities. Mouse uses the exact System One confidence formulas so thresholds behave identically across compatible clients.

choice confidence

For a choice question with (k) options and top probability (p_{\max} = \max_i p_i):

[ \text{confidence} = \frac{p_{\max} - \frac{1}{k}}{1 - \frac{1}{k}} ]

• When probability is split evenly across all (k) options ((p_{\max} = 1/k)), confidence is 0.0.
• When all probability is concentrated on a single option ((p_{\max} = 1.0)), confidence is 1.0.
• Note the difference between confidence and mouse.p_top: on a 3-option choice with probabilities (0.60, 0.30, 0.10), mouse.p_top is 0.60 while confidence is ((0.60 - 1/3) / (2/3) = 0.40).

score confidence

Because score levels are ordered ((0, 1, \dots, k-1)), probability mass on an adjacent level reduces confidence less than probability mass on the opposite end of the scale. Let (m = \arg\max_i p_i) be the mode level:

[ \text{confidence} = \max\left(0,\ 1 - \frac{\sum_{i=0}^{k-1} p_i , |i - m|}{\text{MAD}{\text{unif}}}\right), \qquad \text{MAD}{\text{unif}} = \frac{1}{k} \sum_{i=0}^{k-1} \left| i - \frac{k - 1}{2} \right| ]

• On a 3-level scale (0, 1, 2), a split between adjacent levels (0.0, 0.5, 0.5) has confidence = 0.25.
• A bimodal split between opposite ends (0.5, 0.0, 0.5) has confidence = 0.0, even though both distributions have the same expected score (1.0 vs 1.5).

noul certainty

A noul answer has only two outcomes (false and true), so noul itself carries both the direction and the certainty. If you need a 0.0 .. 1.0 certainty scalar on the same scale as choice confidence, use:

[ \text{confidence} = |2 \cdot \text{noul} - 1| = 2 \cdot \text{mouse.p_top} - 1 ]

---

Structured instructions and criteria

instructions and every entry in criteria accept structured JSON objects and arrays in addition to plain strings.

When two choice options are easily confused, pass a structured object with consistent keys (what, not_for, examples) on each option to sharpen the boundary:

{
  "return_topic": {
    "type": "choice",
    "instructions": {
      "question": "What is the customer asking about in `ticket.message`?",
      "focus": "Distinguish policy questions before a return from status checks on an existing return."
    },
    "criteria": {
      "return_policy": {
        "what": "Rules, eligibility window, or fees for returning an item",
        "not_for": "Checking on an item that was already shipped back",
        "examples": ["Can I return sale items?", "Do you charge a restocking fee?"]
      },
      "return_status": {
        "what": "Where an in-progress return or refund stands right now",
        "not_for": "General policy questions before starting a return",
        "examples": ["I mailed my return last Tuesday, where is my refund?"]
      }
    }
  }
}