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}