Skip to main content

hyprstream_decision_stub/
mock.rs

1//! The deterministic mock decision model.
2//!
3//! Distributions are a pure function of (model id, canonical question serialization,
4//! state, row index): blake3-drawn uniforms, normalized, with the largest component
5//! corrected so the sum meets the producer tolerance (D5) exactly. Determinism is the
6//! point — contract tests, golden vectors, and the wire-overhead floor all pin exact
7//! bytes.
8//!
9//! Test hook: a question whose instructions contain the literal `[abstain]` is answered
10//! with an abstention, so null-probability paths are exercisable on demand.
11
12use hyprstream_decision::answer::{AnswerValue, QuestionAnswer};
13use hyprstream_decision::arrow::AnswerRow;
14use hyprstream_decision::serialize;
15use hyprstream_decision::spec::{QuestionBody, QuestionSet};
16
17/// The resolved model id the stub reports on every response. Alias resolution is part of
18/// the serving contract: any requested alias resolves to this versioned id.
19pub const STUB_MODEL_VERSION: &str = "jev-stub-1.0.0";
20
21/// The alias listed by `GET /v1/models` (and accepted, like every string, on requests).
22pub const STUB_MODEL_ALIAS: &str = "jev-stub-latest";
23
24/// The deterministic mock.
25#[derive(Debug, Clone, Default)]
26pub struct MockDecisionModel;
27
28/// Draw one uniform in (0, 1) from the hash of `key` and `index`.
29fn draw(key: &[u8], index: u64) -> f64 {
30    let mut hasher = blake3::Hasher::new();
31    hasher.update(key);
32    hasher.update(&index.to_le_bytes());
33    let output = hasher.finalize();
34    let bits = u64::from_le_bytes(
35        output.as_bytes()[..8]
36            .try_into()
37            .unwrap_or_else(|error| panic!("8 bytes: {error}")),
38    );
39    // Map to (0, 1) exclusive: exact 0/1 components would pin confidence to 1.0 and hide
40    // the derived-statistic paths the contract tests exercise.
41    (bits as f64 + 0.5) / (u64::MAX as f64 + 1.0)
42}
43
44/// A normalized distribution of width `cardinality`, exact to producer tolerance (D5).
45fn distribution(key: &[u8], cardinality: usize) -> Vec<f32> {
46    debug_assert!(cardinality >= 1);
47    let draws: Vec<f64> = (0..cardinality as u64).map(|i| draw(key, i)).collect();
48    let total: f64 = draws.iter().sum();
49    let mut probabilities: Vec<f32> = draws.iter().map(|d| (d / total) as f32).collect();
50    // Correct the largest component so the f32 sum is exactly 1; the correction is far
51    // below the 1e-6 producer tolerance.
52    let sum: f32 = probabilities.iter().sum();
53    if let Some((max_index, _)) = probabilities
54        .iter()
55        .enumerate()
56        .max_by(|(_, a), (_, b)| a.total_cmp(b))
57    {
58        probabilities[max_index] += 1.0 - sum;
59    }
60    probabilities
61}
62
63impl MockDecisionModel {
64    /// Answer every question in `set` for one state row (`row` is the batch row index,
65    /// 0 for single-request facade calls).
66    pub fn answer_row(&self, set: &QuestionSet, state_text: &str, row: usize) -> AnswerRow {
67        let mut answers = std::collections::BTreeMap::new();
68        for question in &set.questions {
69            let abstain = question
70                .instructions
71                .as_ref()
72                .is_some_and(|entry| entry.canonical_text().contains("[abstain]"));
73            if abstain {
74                answers.insert(question.id.clone(), QuestionAnswer::abstained());
75                continue;
76            }
77            let key = format!(
78                "{STUB_MODEL_VERSION}\x00{}\x00{state_text}\x00{row}",
79                serialize::serialize_question(question)
80            );
81            let value = match &question.body {
82                QuestionBody::Noul { .. } => AnswerValue::Noul {
83                    p_true: draw(key.as_bytes(), 0) as f32,
84                },
85                QuestionBody::Choice { options } => AnswerValue::Choice {
86                    probabilities: distribution(key.as_bytes(), options.len()),
87                },
88                QuestionBody::Score { levels } => AnswerValue::Score {
89                    probabilities: distribution(key.as_bytes(), levels.len()),
90                },
91            };
92            answers.insert(question.id.clone(), QuestionAnswer::answered(value));
93        }
94        AnswerRow { answers }
95    }
96}
97
98#[cfg(test)]
99mod tests {
100    use super::*;
101    use hyprstream_decision::author;
102    use hyprstream_decision::confidence::{self, PRODUCER_SUM_TOLERANCE};
103
104    fn fixture() -> QuestionSet {
105        author::parse_yaml(
106            r#"
107state: "The box was crushed."
108questions:
109  is_refund:
110    type: noul
111    instructions: "The customer wants money back."
112  tone:
113    type: choice
114    criteria:
115      angry: "Hostile message"
116      calm: ~
117  severity:
118    type: score
119    criteria: ["cosmetic", "usable", "unusable"]
120"#,
121        )
122        .unwrap_or_else(|error| panic!("fixture parses: {error}"))
123    }
124
125    #[test]
126    fn distributions_are_deterministic_and_normalized() {
127        let set = fixture();
128        let mock = MockDecisionModel;
129        let first = mock.answer_row(&set, "The box was crushed.", 0);
130        let second = mock.answer_row(&set, "The box was crushed.", 0);
131        assert_eq!(first, second, "the mock is a pure function");
132        for (id, answer) in &first.answers {
133            let value = answer.value.as_ref().unwrap_or_else(|| panic!("answered"));
134            let question = set.question(id).unwrap_or_else(|| panic!("declared"));
135            assert_eq!(value.probabilities().len(), question.cardinality());
136            confidence::check_distribution(&value.probabilities(), PRODUCER_SUM_TOLERANCE)
137                .unwrap_or_else(|error| panic!("producer tolerance: {error}"));
138        }
139    }
140
141    #[test]
142    fn state_and_row_change_the_answer() {
143        let set = fixture();
144        let mock = MockDecisionModel;
145        let a = mock.answer_row(&set, "state A", 0);
146        let b = mock.answer_row(&set, "state B", 0);
147        let c = mock.answer_row(&set, "state A", 1);
148        assert_ne!(a, b);
149        assert_ne!(a, c);
150    }
151
152    #[test]
153    fn abstain_hook_abstains() {
154        let set = author::parse_yaml(
155            r#"
156questions:
157  q:
158    type: noul
159    instructions: "Judge this. [abstain]"
160"#,
161        )
162        .unwrap_or_else(|error| panic!("parses: {error}"));
163        let row = MockDecisionModel.answer_row(&set, "anything", 0);
164        assert_eq!(
165            row.answers.get("q"),
166            Some(&QuestionAnswer::abstained()),
167            "[abstain] in instructions yields an abstention"
168        );
169    }
170}