How confidence is computed

Each score carries both a scalar confidence (0–1) and a rich confidenceDetail block. The scalar is a deterministic fold of the detail; read the detail when you want to show users how certain the model is about the inputs behind a verdict.

The scalar

confidence is a number between 0 and 1 — the deterministic product of five [0,1] factors: forecast_skill × provider_agreement × profile_maturity × hierarchical_calibration × coverage. Closer to 1 means the engine has high agreement with itself: a short lead time, tight ensemble spread, a mature profile, a calibrated sub-spot, low drift. Because it's a product, no single factor can lift the score on its own, and a far-out forecast against a brand-new profile compounds toward a low number — the cold-start near-term baseline sits around 0.55–0.62. Below 0.5 means the score is workable but the underlying signal is sparse or uncertain; treat it as a directional hint, not a verdict you'd bet a session on. It measures the model's certainty about its own inputs and data coverage, not a guarantee that the verdict is correct.

The detail block

confidenceDetail is a discriminated union by mode: forecast, historical or climate. The fields you get depend on which scoring surface produced the response. The values below are illustrative.

{
 "mode": "forecast",
 "forecast_skill": 0.78, // horizon-decaying skill prior: ~0.90 nowcast → ~0.51 at 16 days
 "provider_agreement": 0.88, // ensemble / provider-chain spread
 "profile_maturity": 0.95, // provisional 0.75 · reviewed 0.85 · calibrated 0.95
 "hierarchical_calibration": 0.95,
 "data_coverage": 0.95 // fraction of scoring weight with live data
}

Forecast mode

Returned by /v1/score only. /v1/score/series and /v1/score/multi carry just the scalar confidence, not the detail block. Factors:

• Forecast skill (forecast_skill): a horizon-decaying skill prior. Confidence is highest for a near-term verdict and falls as the lead time grows — ≈ 0.90 for a nowcast, ≈ 0.78 at 24h, ≈ 0.69 at 72h, ≈ 0.60 at 7 days, down to ≈ 0.51 at the 16-day horizon limit. On the ensemble path it additionally folds in member spread. This is an honest prior, not yet a measured per-stratum skill; as paired outcomes accumulate it will be replaced by measurement.
• Provider agreement (provider_agreement): how much the consensus provider chain agrees for this request. A single source is 1.0 — one provider is not penalised for being alone. On the ensemble path, confidence additionally folds in member spread — narrow distribution = high confidence, wide = chaotic state.
• Profile maturity (profile_maturity): rises as a profile is calibrated against outcomes — provisional (0.75), reviewed (0.85), calibrated (0.95). A fresh profile with no operator outcomes scores lower confidence than one calibrated against many paired outcomes.
• Hierarchical calibration (hierarchical_calibration): how locally the spot resolved. A sub-spot with n≥100 outcomes scores 1.0. Falling back to cluster or regional level scores 0.85–0.95.

Historical mode

Returned by /v1/score/historical. Confidence reflects sample size and reanalysis coverage: older years (pre-1979 for marine, pre-1940 for atmospheric) carry lower confidence even when the score distribution looks tight.

Climate mode

Returned by /v1/projections. Per-decade entries carry their own confidence detail folded from CMIP6 ensemble spread + the sub-spot bias correction's posterior. Long-horizon projections are intrinsically less confident than near-term forecasts; that's encoded explicitly here rather than hidden in the scalar.

drift_flag