Skip to main content

hyprstream_decision/
confidence.rs

1//! Confidence-from-peakedness: the normative jev-1 derivations over a raw distribution.
2//!
3//! Raw distributions are the primary contract; confidence is a derived statistic so that
4//! ecosystem thresholds port (S6a §2.3 — the formulas are normative from the MIT adapter
5//! source and reproduce the docs' non-stale numeric examples exactly; this crate's
6//! `tests/jev1_compat.rs` pins those examples). Whether the upstream service computes the
7//! identical statistic is a live-check item for P0.5/P0.7 (S6a A1) — it changes nothing
8//! here, where confidence is computed from our own distributions.
9//!
10//! Nothing in this module is stored in the schema: these are pure functions over the
11//! probability vectors that live in the Arrow columns.
12
13use thiserror::Error;
14
15use crate::spec::QuestionKind;
16
17/// Producer-side probability-sum tolerance (D5): emitted distributions must satisfy
18/// `|Σp − 1| ≤ 1e-6`. Enforced by batch construction.
19pub const PRODUCER_SUM_TOLERANCE: f32 = 1e-6;
20
21/// Consumer-side probability-sum tolerance (D5): readers must accept
22/// `|Σp − 1| ≤ 1e-2` ("approximately 1" on the wire).
23pub const CONSUMER_SUM_TOLERANCE: f32 = 1e-2;
24
25/// Why a probability vector is not a valid distribution under the profile.
26#[derive(Debug, Clone, PartialEq, Error)]
27pub enum DistributionError {
28    /// The vector is empty.
29    #[error("distribution is empty")]
30    Empty,
31    /// A component is outside [0, 1] or not finite.
32    #[error("component {index} = {value} is not a finite probability in [0, 1]")]
33    OutOfRange {
34        /// Offending component index.
35        index: usize,
36        /// Offending value.
37        value: f32,
38    },
39    /// The sum deviates from 1 beyond the applicable tolerance.
40    #[error("distribution sums to {sum}, beyond tolerance {tolerance}")]
41    SumOutOfTolerance {
42        /// The actual sum.
43        sum: f32,
44        /// The tolerance that was applied.
45        tolerance: f32,
46    },
47}
48
49/// Validate a probability vector against a tolerance. Every component must be a finite
50/// probability in [0, 1] and the sum must be within `tolerance` of 1.
51pub fn check_distribution(probabilities: &[f32], tolerance: f32) -> Result<(), DistributionError> {
52    if probabilities.is_empty() {
53        return Err(DistributionError::Empty);
54    }
55    let mut sum = 0.0f32;
56    for (index, &value) in probabilities.iter().enumerate() {
57        if !value.is_finite() || !(0.0..=1.0).contains(&value) {
58            return Err(DistributionError::OutOfRange { index, value });
59        }
60        sum += value;
61    }
62    if (sum - 1.0).abs() > tolerance {
63        return Err(DistributionError::SumOutOfTolerance { sum, tolerance });
64    }
65    Ok(())
66}
67
68/// Argmax with the profile tie-break (D6): the earliest index in canonical (insertion)
69/// order wins. Returns `None` on an empty slice.
70pub fn argmax_index(probabilities: &[f32]) -> Option<usize> {
71    let mut best: Option<(usize, f32)> = None;
72    for (index, &value) in probabilities.iter().enumerate() {
73        match best {
74            Some((_, best_value)) if value <= best_value => {}
75            _ => best = Some((index, value)),
76        }
77    }
78    best.map(|(index, _)| index)
79}
80
81/// Choice confidence: `(p_max − 1/n) / (1 − 1/n)` — the peak probability scaled against
82/// the uniform floor. A single-option distribution is certain by construction (1.0).
83pub fn choice_confidence(probabilities: &[f32]) -> f32 {
84    let n = probabilities.len();
85    if n <= 1 {
86        return 1.0;
87    }
88    let p_max = probabilities
89        .iter()
90        .copied()
91        .fold(f32::NEG_INFINITY, f32::max);
92    let uniform = 1.0 / n as f32;
93    ((p_max - uniform) / (1.0 - uniform)).clamp(0.0, 1.0)
94}
95
96/// Score confidence: `max(0, 1 − MAD_mode / MAD_uniform)` where
97/// `MAD_mode = Σᵢ pᵢ·|i − argmax|` and `MAD_uniform = (Σᵢ |i − (n−1)/2|) / n` — the
98/// distribution's mean absolute distance from its mode, normalized by the uniform
99/// distribution's mean absolute distance from the center. A single-level distribution is
100/// certain by construction (1.0).
101pub fn score_confidence(probabilities: &[f32]) -> f32 {
102    let n = probabilities.len();
103    if n <= 1 {
104        return 1.0;
105    }
106    let Some(mode) = argmax_index(probabilities) else {
107        return 1.0;
108    };
109    let mad_mode: f32 = probabilities
110        .iter()
111        .enumerate()
112        .map(|(index, &p)| p * index.abs_diff(mode) as f32)
113        .sum();
114    let center = (n - 1) as f32 / 2.0;
115    let mad_uniform: f32 = (0..n)
116        .map(|index| (index as f32 - center).abs())
117        .sum::<f32>()
118        / n as f32;
119    if mad_uniform == 0.0 {
120        return 1.0;
121    }
122    (1.0 - mad_mode / mad_uniform).max(0.0)
123}
124
125/// The normative confidence for any primitive's distribution. Noul has no confidence
126/// field upstream by design; as a superset convenience it is computed as the choice
127/// formula over the 2-label `[P(false), P(true)]` distribution.
128pub fn confidence(kind: QuestionKind, probabilities: &[f32]) -> f32 {
129    match kind {
130        QuestionKind::Noul | QuestionKind::Choice => choice_confidence(probabilities),
131        QuestionKind::Score => score_confidence(probabilities),
132        // Reserved v2 kinds carry no distribution contract in v1.
133        QuestionKind::Span | QuestionKind::Derived => 0.0,
134    }
135}
136
137/// The probability-weighted score value `Σᵢ i·pᵢ` ∈ [0, n−1]. A derived convenience —
138/// the trust contract remains the distribution itself.
139pub fn expected_score(probabilities: &[f32]) -> f32 {
140    probabilities
141        .iter()
142        .enumerate()
143        .map(|(index, &p)| index as f32 * p)
144        .sum()
145}
146
147#[cfg(test)]
148mod tests {
149    use super::*;
150
151    #[test]
152    fn argmax_breaks_ties_toward_earliest_index() {
153        assert_eq!(argmax_index(&[0.5, 0.5]), Some(0));
154        assert_eq!(argmax_index(&[0.1, 0.4, 0.4]), Some(1));
155        assert_eq!(argmax_index(&[]), None);
156    }
157
158    #[test]
159    fn degenerate_distributions_are_certain() {
160        assert_eq!(choice_confidence(&[1.0]), 1.0);
161        assert_eq!(score_confidence(&[1.0]), 1.0);
162        assert_eq!(score_confidence(&[0.0, 0.0, 0.0, 1.0]), 1.0);
163    }
164}