Give people a clear answer, or give systems the exact constraints behind the score.
Explanation endpoints never change the underlying score, verdict or safety gates. They only render or analyse the existing decision record. The physics engine produces the decision; the LLM, when configured, is the optional renderer, not the product.
The same decision record feeds a readable answer and a quantified constraint view. The request on the left produces a score; the natural-language surface renders it; the decision-logic surface shows what is holding it back.
POST /v1/score
{
"activity": "kitesurfing",
"spot": { "lat": 36.013,
"lng": -5.604 },
"window": {
"from": "2026-07-04T14:00:00Z",
"to": "2026-07-04T18:00:00Z"
},
"rider_skill_level": "intermediate"
}rider_skill_level is a Pro+ input on /v1/score. Without it, the score uses the standard intermediate profile. The example names it so the explanation stays honest about what it knows.
Saturday afternoon at Tarifa Balneario looks favorable for the intermediate rider profile, scoring 87/100. The 22-knot cross-onshore wind suits the conditions in this window. Two factors hold it below the 90s: the chop is slightly above the flat-water ideal (1.5m at 10s adds work for freestyle), and the gust factor of 1.18 is steady but not glassy. No safety gates triggered: clear sightlines, no convective activity within 50km. Suggested planning signal: Conditions suit intermediate kitesurfing. For flat-water freestyle, the calmer window around 14:00 UTC may be a better fit.
22 kt cross-onshore, well inside the working band
1.5 m at 10 s sits above the flat-water ideal
1.18 is steady but not glassy
confidence_note: Wave confidence is moderate because no representative buoy is available. How to read source_type.
See what is limiting the score, how much it matters and what would improve the plan.
Sensitivities are local to this activity profile, place and forecast window; they are not universal thresholds.
Same question, two product shapes, one decision record. The natural-language surface produces copy a booking flow can show a customer. The decision-logic surface produces structured output a workflow can route on. Pick the one your consumer needs; the other is ready when you need it.
A grounded, evidence-based explanation of the score. The LLM renders the existing breakdown into readable copy; it never changes the decision. Every numeric claim is re-validated, and the surface falls back to a deterministic template when no key is set or a check fails.
Binding constraint, marginal sensitivities, best 24h window and best nearby spots, computed directly from the breakdown. No LLM involved, fully deterministic, defensible for systems that route on the output rather than read it.
For booking platforms, tour operators and outdoor apps.
Show the natural-language paragraph next to the confirmation: the three conditions behind the verdict, in plain language. Customers stop asking why a slot was held or released.
A morning briefing across spots and windows, a paragraph plus a best-window table for each candidate. It replaces the analyst juggling five tabs before the day starts.
An in-app card with a one-line summary and a 'what would change' chip, plus an edge-case nudge when a favorable score hides real uncertainty. Warn without blocking.
LLMs can drift. Booking flows cannot. The natural-language surface is safe to put in front of a customer because it renders a structured record, re-validates every number, isolates user input, and always has a template to fall back to.
Explanations are built from the score breakdown, not from free text. The model renders the decision record it is given; it does not decide anything.
Every number the model produces is re-validated against the breakdown. A mismatch triggers a one-shot retry with a tightened prompt; a second failure falls back to the deterministic template.
User-controlled text is not used as instruction content. Identifiers are sanitized, and generated output is validated against the structured decision record.
Every LLM call has a template fallback. If the provider is unavailable, the token budget is exhausted, or validation fails, the response still ships, rendered from a template instead of generated.
An explanation is only as trustworthy as the numbers under it. Each driver carries a source_type (forecast model, in-situ station, buoy, reanalysis) and a staleness_minutes, and the surface adds a confidence note when a value rests on thin coverage, for example when no representative buoy is nearby. This is the same provenance the score response exposes.
Feature status: counterfactual analysis is available now. Natural-language explanations require a configured Anthropic key; without one, the intelligence endpoints return 503 INTELLIGENCE_UNAVAILABLE and the counterfactual natural-language block degrades to a template.
POST /v1/intelligence/explainOne-paragraph, grounded natural-language summary of a score. Claude-backed when a tenant key is set; every numeric claim is re-validated against the breakdown, with a deterministic template fallback.
POST /v1/intelligence/edge-caseSurfaces the cases that a favorable score can hide: high uncertainty, provider disagreement, or a nearby safety gate. So a risk-aware flow can warn without blocking.
POST /v1/score/explain-counterfactualAnalytical, no LLM. Returns the binding constraint, marginal sensitivities, the best 24h window and the best nearby alternative spots. Pure math from the existing breakdown.
POST /v1/intelligence/briefingMulti-spot, multi-window briefing for a guide or operator. Returns a paragraph plus a tabular best-window summary per candidate.
None of these endpoints change the score, verdict or safety gates. They render or analyse the record that /v1/score already produced.
Use your own Anthropic API key, subject to Anthropic account availability and terms. The three intelligence endpoints run on that key and draw on your Anthropic token budget, and a flat 500,000-token monthly guard applies as a runaway-loop check on your own spend.
BYOK data flow and securityEach counterfactual analysis consumes one score-equivalent from your plan quota; it is pure math and needs no key. Its optional natural-language block additionally uses your Anthropic key. The explain, briefing and edge-case endpoints do not draw on your score quota; they run on your Anthropic key and count against your Anthropic token budget.