Skip to main content

hyprstream_decision/
answer.rs

1//! Answer-side IR: distributions, abstention, and the batch version triple.
2//!
3//! Raw probability distributions are the primary answer payload. Everything else —
4//! labels, confidence, expected values — is derived ([`crate::confidence`]). A `null`
5//! answer is an **abstention**: the model declined to commit, and consumers build
6//! selective prediction on top of that value. Abstention is data, not an error.
7
8/// The batch-level version triple carried by every emitted Arrow batch.
9///
10/// - `schema`: question-set schema version (see
11///   [`crate::arrow::DecisionSchema::check_evolution`] — label-set evolution requires a
12///   new schema version and fails loudly).
13/// - `model`: resolved model id. Alias resolution is part of the serving contract: the
14///   emitted value is the resolved versioned id, which may differ from the requested
15///   alias.
16/// - `calib`: calibration-fit version; `None` = uncalibrated (raw distribution). The
17///   calibration *parameters* themselves are rows in the P0.3 metrics tables, never
18///   schema content.
19#[derive(Debug, Clone, PartialEq, Eq)]
20pub struct VersionTriple {
21    /// Question-set schema version.
22    pub schema: String,
23    /// Resolved model id.
24    pub model: String,
25    /// Calibration-fit version (`None` = uncalibrated).
26    pub calib: Option<String>,
27}
28
29/// A typed answer payload: one probability distribution over the question's labels.
30#[derive(Debug, Clone, PartialEq)]
31pub enum AnswerValue {
32    /// Noul: P(true). Emitted as the 2-wide distribution `[1 − p, p]` over labels
33    /// `["false", "true"]`.
34    Noul {
35        /// Probability the statement is true.
36        p_true: f32,
37    },
38    /// Choice: one probability per option, aligned with canonical option order.
39    Choice {
40        /// Per-option probabilities (length = option count; producer tolerance D5).
41        probabilities: Vec<f32>,
42    },
43    /// Score: one probability per level, in ascending level order.
44    Score {
45        /// Per-level probabilities (length = level count; producer tolerance D5).
46        probabilities: Vec<f32>,
47    },
48}
49
50impl AnswerValue {
51    /// The distribution over the question's labels, in canonical label order.
52    pub fn probabilities(&self) -> Vec<f32> {
53        match self {
54            Self::Noul { p_true } => vec![1.0 - p_true, *p_true],
55            Self::Choice { probabilities } | Self::Score { probabilities } => probabilities.clone(),
56        }
57    }
58}
59
60/// The answer to one question on one row.
61#[derive(Debug, Clone, PartialEq)]
62pub struct QuestionAnswer {
63    /// `None` = **abstained** (emitted as null probabilities + null label).
64    pub value: Option<AnswerValue>,
65    /// Conformal prediction set (labels). **Reserved in schema v1** — the column is
66    /// emitted but may be entirely unpopulated; `None` = no set on this row. An abstained
67    /// answer must not carry a set (abstention already says "no commitment").
68    pub conformal_set: Option<Vec<String>>,
69}
70
71impl QuestionAnswer {
72    /// An abstained answer with no conformal set.
73    pub fn abstained() -> Self {
74        Self {
75            value: None,
76            conformal_set: None,
77        }
78    }
79
80    /// An answered question with no conformal set.
81    pub fn answered(value: AnswerValue) -> Self {
82        Self {
83            value: Some(value),
84            conformal_set: None,
85        }
86    }
87}