From answers to an outcome

How feature answers become a score, and how your cut points turn that score into an outcome.

The examples on this page use Northpine, a fictional outdoor-gear shop whose refund-exception decision grants, escalates or denies refund requests outside its standard return policy. How Moonbounce works introduces it.

Describe a decision built Northpine’s refund-exception spec: five yes/no features, a combine that weighs them, and a calibrate on top. This page follows real numbers through it: one ticket from its answers to grant, then two more, the alternatives to the default arithmetic, and what happens when an answer is missing.

A feature’s value is P(yes)

For each boolean feature, the engine returns a number between 0 and 1: its probability that the answer to the prompt is yes, written P(yes). This is the feature’s value in the response. 0.96 means “almost certainly yes”, 0.03 “almost certainly no”, and 0.5 means the engine can’t tell.

Ticket A is a sleeping bag whose zipper ripped out on the first night: a $129 order, 42 days after delivery, from a customer with no recent refunds. Its answers:

Feature	Answer
outside_window	0.98
item_used	0.10
defective	0.96
repeat_refunder	0.03
high_value	0.02

These are illustrative engine answers; the arithmetic below is exactly what the API does with them.

The default combine: an average

Until weights are learned, a combine scores with its default weights. By default (the "mean" prior) the score is the average of the answers, after flipping every lowers answer: a lowers answer x counts as 1 − x. Flipping makes every term point the same way. For outside_window, 0.98 says the request is almost certainly late, so 0.02 is how much that answer argues for granting.

Feature	Effect	Answer	Counts as
outside_window	lowers	0.98	0.02
item_used	lowers	0.10	0.90
defective	raises	0.96	0.96
repeat_refunder	lowers	0.03	0.97
high_value	lowers	0.02	0.98

The five flipped answers sum to 3.83, and 3.83 / 5 = 0.766. That is grant_score.

The same score as weights and a bias

The API doesn’t store “flip, then average”. It stores the same arithmetic as one weight per term and a bias (a constant added to the sum), and reads the raw answers:

• a raises term has weight +1/n, a lowers term −1/n, where n is the number of terms;
• the bias is the number of lowers terms divided by n.

Each flipped answer (1 − x) / n is 1/n − x/n, and the 1/n parts collect into the bias. For Northpine, n = 5 with four lowers terms: every lowers weight is −0.2, defective’s is +0.2, and the bias is 0.8.

The response reports each term’s contribution, its weight times its raw answer. The bias is not among them, so the score is the bias plus the sum of the contributions:

Feature	Weight	Answer	Contribution
outside_window	−0.2	0.98	−0.196
item_used	−0.2	0.10	−0.020
defective	+0.2	0.96	+0.192
repeat_refunder	−0.2	0.03	−0.006
high_value	−0.2	0.02	−0.004

The contributions sum to −0.034, and 0.8 − 0.034 = 0.766. In the response:

{
  "status": "scored",
  "score": 0.766,
  "outcome": "grant",
  "nodes": {
    "outside_window": { "type": "boolean", "value": 0.98 },
    "item_used": { "type": "boolean", "value": 0.1 },
    "defective": { "type": "boolean", "value": 0.96 },
    "repeat_refunder": { "type": "boolean", "value": 0.03 },
    "high_value": { "type": "boolean", "value": 0.02 },
    "grant_score": {
      "type": "combine",
      "value": 0.766,
      "contributions": {
        "outside_window": -0.196,
        "item_used": -0.020000000000000004,
        "defective": 0.192,
        "repeat_refunder": -0.006,
        "high_value": -0.004
      }
    },
    "grant": { "type": "calibrate", "value": 0.766, "calibrated": false }
  }
}

Read contributions as the “why” of a score: outside_window pulled it down by 0.196 and defective pushed it up by 0.192, while the three answers near zero barely moved it. A lowers term contributes close to nothing when its answer is no, because the bias already assumed it would be.

The API never rounds a score or a contribution. -0.020000000000000004 is the exact floating-point result of −0.2 × 0.1. Round only for display: a score shown as 0.38 might sit just below a 0.38 cut.

Three tickets side by side

Two more Northpine tickets go through the same arithmetic:

• B: a $899 kayak, 61 days after delivery; the customer changed their mind.
• C: a $189 tent that arrived two weeks late because of the carrier, used once on the trip it was for, now 39 days after delivery.

Ticket	outside_window	item_used	defective	repeat_refunder	high_value	Score
A	0.98	0.10	0.96	0.03	0.02	0.766
B	0.99	0.20	0.02	0.03	0.99	0.362
C	0.95	0.35	0.05	0.02	0.03	0.540

B’s flipped answers are 0.01, 0.80, 0.02, 0.97 and 0.01, averaging 0.362 (the response reads 0.36200000000000004). Nothing argues for it. C’s are 0.05, 0.65, 0.05, 0.98 and 0.97, averaging 0.54: no defect, a little use, and late. Northpine’s owner says C should be granted, because the carrier delay ate the return window. No feature in the spec captures that, which is why C lands in the middle.

When one answer should be enough: prior: "any"

An average dilutes. In a five-term mean, one term can move the score by at most 1/5. That suits Northpine, where every reason should be weighed against the others, but not a decision where any single reason is enough.

Say Northpine also checks whether a ticket needs a person at all, with three features where any one yes should send it to someone:

"needs_person": {
  "type": "combine",
  "terms": [{ "node": "legal_threat" }, { "node": "safety_issue" }, { "node": "public_complaint" }]
}

A customer reports a camp stove that caught fire: legal_threat 0.02, safety_issue 0.97, public_complaint 0.03. The mean is 0.34, which looks like a ticket nobody needs to see.

Set "prior": "any" on the combine and its default weights change: every raises term gets +8, every lowers term −8, the bias is −4, and the sum goes through a logistic curve, 1 / (1 + e^−s). The curve squeezes any number onto 0 to 1: a sum of 0 maps to 0.5, +4 to about 0.98 and −4 to about 0.02. For the stove:

• sum: −4 + 8 × (0.02 + 0.97 + 0.03) = 4.16
• score: 1 / (1 + e^−4.16) = 0.9846

One confident yes is now enough. With the logistic curve the score is no longer the bias plus the contributions: it is the curve applied to that sum. The contributions here are 0.16, 7.76 and 0.24.

any is a sum, not a maximum, so answers add up:

Answers (legal_threat, safety_issue, public_complaint)	Mean	any
0.02, 0.97, 0.03	0.34	0.985
0.02, 0.03, 0.01	0.02	0.029
0.30, 0.02, 0.30	0.207	0.723
0.40, 0.40, 0.40	0.40	0.996

Two weak maybes reach 0.723, and three unsure answers score higher than one certain one. A strong lowers answer cancels a strong raises one. any needs at least one raises term. Writing "prior": "mean" is the same as leaving prior out; "any" changes the structure hash. Either prior only sets the default weights: any other weights document replaces it.

Numbers fixed in code

When you know the numbers you want, write them into the combine as fixed:

"grant_score": {
  "type": "combine",
  "terms": [
    { "node": "outside_window", "effect": "lowers" },
    { "node": "item_used", "effect": "lowers" },
    { "node": "defective" },
    { "node": "repeat_refunder", "effect": "lowers" },
    { "node": "high_value", "effect": "lowers" }
  ],
  "fixed": {
    "link": "identity",
    "weights": { "outside_window": -0.1, "item_used": -0.2, "defective": 0.4, "repeat_refunder": -0.2, "high_value": -0.1 },
    "bias": 0.6
  }
}

• link is identity (the score is the bias plus the contributions, clamped to 0 to 1) or logistic (the curve above).
• weights has one number per term, and its sign must match the term’s effect: zero or more for raises, zero or less for lowers.
• bias is any finite number.

Fixed numbers are used ahead of any weights document, the defaults or a pinned hash: Moonbounce’s weights never override them. They are part of the spec, so changing one creates a new version, and they can’t be combined with prior: "any". With these numbers ticket A scores 0.858, B 0.364 and C 0.448.

Calibrate

grant is a calibrate node, and today it passes its input through: A’s grant is 0.766 with "calibrated": false. Once a calibration has been fitted from feedback, it will map the score onto the probability that the target (“The refund exception should be granted.”) is true, and calibrated will be true. Fitting is not available yet.

version.weights_fitted

Every response has a version object. version.weights_fitted is true only when the weights in use were fitted on feedback. Default weights, whether sent as "weights": "default" or pinned by their hash, and weights carried over by a suggestion are not fitted. Today every call reports false. fixed combines and per-node calibrated are reported on the nodes, not here.

Cut points: from a score to an outcome

You turn the score into an outcome, the name of what your app should do, with cut points sent in each request’s outcomes:

"outcomes": {
  "below": "deny",
  "cuts": [
    { "at": 0.38, "outcome": "escalate" },
    { "at": 0.6, "outcome": "grant" }
  ]
}

• below is the outcome under the first cut.
• cuts holds 1 to 9 cuts, with at values strictly ascending.
• Outcome names follow the node-name rules (lowercase slugs), and below plus the cut outcomes are all distinct.

The outcome is the last cut whose at is at or below the score, or below if there is none. A score exactly at a cut takes that cut’s outcome: 0.38 is escalate, and 0.60 is grant. A request that breaks a rule is a 400 with param outcomes.cuts.

The three Northpine tickets on the scale:

0 ────── deny ──────┼─── escalate ───┼────── grant ────── 1
                   0.38             0.60
                ▲             ▲               ▲
             B 0.362       C 0.540         A 0.766

Score range	Outcome	Ticket
below 0.38	deny	B (0.362)
0.38 up to, not including, 0.60	escalate	C (0.540)
0.60 and above	grant	A (0.766)

Status and abstain

Every response has a status:

• scored: there is a score and your cut points turned it into an outcome.
• no_outcomes: there is a score, but the request sent no outcomes, so there is no outcome. Cut the score in your own code, or treat the call as observe-only.
• abstained: the output has no answer, so there is no score. outcome is outcomes.abstain when you set it, and absent otherwise.

abstain names the outcome for the case where there is nothing to cut, and it may reuse a name on the scale. Northpine could send "abstain": "escalate" so that an unanswerable ticket goes to a person. That is why you tell an abstention apart by status, never by the outcome name: escalate alone doesn’t say whether the score landed between the cuts or there was no score.

{
  "status": "abstained",
  "outcome": "escalate",
  "nodes": {
    "item_used": { "type": "boolean", "abstained": true },
    "grant_score": { "type": "combine", "abstained": true, "reason": "input \"item_used\" had no answer" },
    "grant": { "type": "calibrate", "abstained": true, "reason": "input \"grant_score\" had no answer" }
  }
}

This excerpt leaves out the four features that answered.

When a feature has no answer

A feature can come back without a value in two ways, and they lead to different results:

• Abstained: the engine ran and declined to answer. The abstention passes to every node that reads the feature: with default weights a combine reads all its terms, so one abstained feature makes grant_score and then grant abstain. The call succeeds with status abstained, as above.
• Failed: the engine call itself failed. If the score depends on the feature, the output fails too. The call is a 502 ENGINE_FAILED, details.features lists the failed features, and nothing is stored. When every failure that sank the output was temporary, such as a rate limit, the call is a 503 ENGINE_UNAVAILABLE with Retry-After instead: retry it with the same Idempotency-Key.

When a node has both an abstained and a failed input, failed wins.

A feature the score doesn’t depend on can fail without failing the call. That is an observe-only feature: one no aggregator reads, which the engine answers and the evaluation records but which never moves the score. If Northpine added a carrier_delay feature without putting it in grant_score’s terms and it failed, the call would still answer 200 with A’s score of 0.766 and grant, show carrier_delay as {"type": "boolean", "failed": true, ...}, and add a warning:

"warnings": [
  { "code": "FEATURE_FAILED", "message": "\"carrier_delay\" had no answer: timeout", "param": "nodes.carrier_delay" }
]

Choosing cut points

Cut points live in your code, next to the spec. They are not part of either hash, they travel with every call and the response echoes them back in outcomes, so your logs and Moonbounce’s records agree on which cuts produced an outcome. Changing them never creates a new version, and a preview replays a spec at the cut points you send, so you can try new ones against past cases before you ship them.

Middle outcomes like escalate are a capacity choice. Moving Northpine’s grant cut from 0.60 up to 0.80 sends ticket A (0.766) to a person instead of granting it. Make the middle band as wide as the number of tickets your people can take, and narrow it as the decision earns trust.

Next

Evaluate content covers the request that carries these answers and cut points, and everything in the response besides the score. Feedback explains how a ticket like C gets corrected.