Density extension: shrug.distributions

By default shrug.ai draws every answer from a uniform distribution — the honest “I have no idea” baseline. The shrug.distributions block lets you bias that draw per question, so you can model a specific null hypothesis (a known base rate, a prior from historical data) instead of pure uniformity.

It works identically on both endpoints. Add a shrug object alongside your request body, keyed by question name:

{
  "shrug": {
    "distributions": {
      "color": { "weights": { "red": 0.5, "blue": 0.3, "green": 0.2 } },
      "is_daytime": { "p_true": 0.7 }
    }
  }
}

weights — choice and score questions

For a choice (or score) question, supply weights as a map from option name (the choice value, or the score level label) to a non-negative number. Each weight is treated as absolute probability mass. You only need to list the options you want to pin — any options you leave out share whatever mass is left over (see Normalization rules below).

"color": { "weights": { "red": 0.5, "blue": 0.3, "green": 0.2 } }

p_true — predicate / noul questions

For a predicate (Decisions) or noul (System One) question, supply a single p_true: the probability the answer is true. The probability of false is 1 - p_true.

"is_daytime": { "p_true": 0.7 }

p_true must be within [0, 1].

Normalization rules

Weights are absolute probability mass, not relative ratios. Let S be the sum of the weights you provide, and let the omitted options be any declared options you didn’t list. shrug.ai resolves them like this:

  • If you left some options out and S ≤ 1: your listed options keep exactly the mass you gave them, and the omitted options split the remaining 1 − S evenly. For a red/blue/green choice, { "red": 0.3 } → red 0.30, blue 0.35, green 0.35 (blue and green share the remaining 0.7).
  • Otherwise (you listed every option, or S > 1): every listed weight is divided by S (renormalized to sum to 1), and any omitted option gets 0. So { "red": 0.6, "blue": 0.6 } → red 0.5, blue 0.5, green 0.0, and { "red": 2.0 } → red 1.0, blue 0.0, green 0.0.
  • To force an option to zero, give it an explicit 0 (as long as another option is positive), or cover all the mass with the others.
  • Weights must be finite and non-negative, with at least one positive. An all-zero/empty map, a negative/NaN weight, or a name that isn’t a declared option (or a distribution for a question that isn’t in the request) is rejected with a 400. Omit the weights/distribution for a question entirely and it falls back to uniform.
  • p_true is used directly (no division); it must be within [0, 1].
  • The returned probabilities are these resolved values — the response shows exactly the distribution the answer was drawn from (see the color probabilities in the /v1/decisions response).