Decisions

A decide request asks 1 to 128 questions about one case, its data and context. Grayson, Finic's decision model, answers each with calibrated probabilities. Nothing is generated: no rationale or text, only probabilities.

"questions": {
  "is_fraud": { "type": "noul", "instructions": "Is this account engaged in or the victim of fraud?" },
  "escalate_to": {
    "type": "choice",
    "instructions": "Which team should this alert be escalated to?",
    "criteria": { "ato": "Account security / ATO team", "aml": "AML investigations", "none": "No escalation needed" }
  }
}

Each question's key names it, and its answer comes back under the same key. Keys and option keys match ^[A-Za-z_][A-Za-z0-9_]{0,63}$. The model never sees them: everything it needs goes in the instructions and criteria. In a choice, the key (ato) comes back in the answer; the description ("Account security / ATO team") is what the model reads.

Question typesCopy Anchor Link

Every question has type and instructions (not blank). Fields that don't belong to the type are rejected. Every answer repeats its question's type.

"answers": {
  "is_fraud": { "type": "noul", "noul": 0.92 },
  "primary_typology": { "type": "choice", "choice": "ato", "confidence": 0.85, "probabilities": { "ato": 0.88, "synthetic_id": 0.02, "mule": 0.05, "first_party": 0.03, "none": 0.02 } },
  "typologies_present": { "type": "multi_choice", "multi_choice": ["ato", "mule"], "probabilities": { "ato": 0.93, "synthetic_id": 0.04, "mule": 0.61, "first_party": 0.03, "scam": 0.07 } },
  "risk": { "type": "score", "score": 3.46, "legend": { "0": "very low", "1": "low", "2": "medium", "3": "high", "4": "very high" }, "confidence": 0.5, "probabilities": { "0": 0.01, "1": 0.02, "2": 0.07, "3": 0.3, "4": 0.6 } }
}

• Option descriptions must not be blank and must be unique, ignoring case and whitespace. A null description reads as the key with spaces for underscores (first_party reads "first party"), but a real description works better.
• A choice spreads all its probability over its options, so include one for "none of these" when that can happen. If two options can both be true, use multi_choice: a choice has to split probability between them, and neither may reach 0.5.
• A multi_choice asks about each option separately. With up to 16 options, each is judged with the full list in view; with more, each on its own, like a separate noul.
• A score's levels are numbered from 0. For "How likely…" questions, use the standard levels, the same for every question so answers compare: ["Very unlikely (under 10%)", "Unlikely (10-40%)", "Uncertain (40-60%)", "Likely (60-90%)", "Very likely (over 90%)"]. A score question is separate from the 0–1000 scores you create from examples.

Score answers and confidenceCopy Anchor Link

A score's score is the expected level: each level's number times its probability, added up, so it can fall between levels. confidence, for a choice or a score, is (K × the top probability − 1) / (K − 1) over K options or levels: 0 when all are equally likely, 1 when one has all the probability.

With the standard likelihood levels and probabilities 0.02, 0.06, 0.25, 0.44 and 0.23, the score is 0×0.02 + 1×0.06 + 2×0.25 + 3×0.44 + 4×0.23 = 2.80, a little under "Likely", and the confidence (5×0.44 − 1) / 4 = 0.30, because the probability is spread over three levels. A high score with low confidence means a split answer: check the probabilities. To act when an answer is at least "Likely", add those levels: 0.44 + 0.23 = 0.67.

choice, multi_choice and score summarize the probabilities; base decisions on the probabilities themselves, unrounded. See Choosing thresholds.

Writing good questionsCopy Anchor Link

• Ask one thing. "Is this account takeover or a scam?" is two questions: use a choice, or two nouls.
• Name the subject: "the outbound ACH on September 20", not "this", when the data holds several transactions.
• Make yes mean the action: "Should this wire be held?" thresholds more directly than "Is this wire safe to release?"
• Define your terms and standards. "High risk: two or more of a new device, a new payee and a changed email in the last 24 hours" gets answers that follow your policy; "High risk" leaves it to the model.
• Write descriptions that stand alone: "Hold the payment and verify the customer another way", not "Hold".
• Keep wording and order fixed. A choice reads its options and a score its levels together, in the order given. Changing the wording or order can change the answers, so choose thresholds with the exact questions you run in production.
• Ask about signals directly when you need to record why: "Did the account log in from a new device shortly before the transfer?" gives a probability you can log and show a reviewer.

Determinism and isolationCopy Anchor Link

• The same request always gets the same answers, so retrying is safe. Any change (instructions, option order, data, context, key order) makes it a different request. Whitespace between JSON tokens in data doesn't matter; whitespace inside strings does.
• Each question sees only the case and its own text, never the other questions: adding, removing or renaming one can't feed into another's answer. Numerical rounding can still move other answers slightly, under 1 percentage point on average.

Requests and answers are kept only as your data retention allows. To keep them for audits, appeals or threshold tuning, store the request and response, with its id and request_id, with your own decision record.