Counterfactual analysis of a score

"What's holding the verdict down?", "If wind picked up 3 knots, would we go?", "Is there a better window today?", "Is a nearby spot better?". One endpoint, four answers — pure math, no LLM.

What it answers

Four analyses returned in a single response:

• binding_constraint — which dimension is dragging the verdict down hardest.
• marginal_sensitivities — ∂score/∂metric for the top-5 dimensions, so you can answer "by how much does X need to change to flip the verdict?".
• best_window_24h — hourly scan over the next 24h, top-3 windows ranked by score.
• best_nearby_spots — sub-spots within radius re-scored against the same request (baseline excluded by slug).

Request

{
 "session_id": "a3f2...", // or pass scoreResult inline
 "include": ["binding", "sensitivities", "bestWindow", "nearbySpots"],
 "radiusKm": 25,
 "naturalLanguage": true
}

binding_constraint

Drag analysis on the dimension level: which dimension's curve, if relaxed by one standard deviation, would lift the score the most. The result carries the dimension name, its current value vs threshold, and the modeled lift if the constraint were removed. Useful for UI copy like "wind is OK but waves are the blocker — try after 3pm when the swell drops".

marginal_sensitivities

Numerical Jacobian: for each of the top-5 dimensions, the engine perturbs the metric by ±σ and ±2σ and observes the score response. Returns the least-squares slope ∂score/∂metric. Use for: "by how much does the wind need to increase to push us from marginal to favorable?".

best_window_24h

Hourly scan over the next 24h from the request's window start, scoring each hour with the same activity profile. Returns top-3 windows ranked by score, with the dominant driver(s) that explain each window's lift over the baseline.

best_nearby_spots

Finds sub-spots within radiusKm via the spatial resolver's R-tree, scores each against the same (activity, window), excludes the baseline by slug (so the source spot doesn't appear twice), and returns the top results. The score difference vs baseline tells you whether a nearby spot is meaningfully better.