Skip to main content

hyprstream_decision_head/
scorer.rs

1//! The shared option-scorer: ONE linear projection over anchor-token hidden states,
2//! with per-primitive readouts. This is the generalist head (P1.1) — no per-question
3//! parameters, no cross-question conditioning: each question is scored exclusively
4//! from its own anchor positions, so runtime-declared questions work zero-shot and the
5//! 255-option cardinality ceiling costs nothing in parameters.
6
7use hyprstream_decision::QuestionKind;
8use tch::nn;
9use tch::{Kind, Tensor};
10
11use crate::encoder::QuestionAnchors;
12use crate::Error;
13
14/// The scored output for one question: the raw per-anchor logits plus the primitive's
15/// distribution readout, derived on demand.
16#[derive(Debug)]
17pub struct QuestionScore {
18    /// Caller-facing question id (carried through from the anchor map).
19    pub question_id: String,
20    /// The primitive type.
21    pub kind: QuestionKind,
22    /// Raw scorer logits: 1 for noul (the sigmoid logit), one per option for choice,
23    /// one per level for score.
24    pub logits: Tensor,
25}
26
27impl QuestionScore {
28    /// The distribution over the question's labels, in canonical order:
29    /// sigmoid → `[P(false), P(true)]` for noul; softmax for choice; binned softmax
30    /// over levels for score.
31    pub fn probabilities(&self) -> Tensor {
32        match self.kind {
33            QuestionKind::Noul => {
34                let p_true = self.logits.view(-1).sigmoid();
35                let p_false = p_true.neg() + 1.0;
36                Tensor::cat(&[p_false, p_true], 0)
37            }
38            QuestionKind::Choice | QuestionKind::Score => {
39                self.logits.log_softmax(0, Kind::Float).exp()
40            }
41            // Reserved v2 kinds are rejected at authoring; the scorer never sees them.
42            other => unreachable!("reserved question kind {other} cannot reach the scorer"),
43        }
44    }
45
46    /// The probability-weighted value `Σᵢ i·pᵢ` over score levels (the expectation
47    /// readout pinned by S6b2). `None` for non-score primitives — their trust object is
48    /// the distribution itself.
49    pub fn expected_value(&self) -> Option<Tensor> {
50        if self.kind != QuestionKind::Score {
51            return None;
52        }
53        let levels = self.logits.size()[0];
54        let indices = Tensor::arange(levels, (Kind::Float, self.logits.device()));
55        Some((self.probabilities() * indices).sum(Kind::Float))
56    }
57}
58
59/// KL divergence `KL(target ‖ p)` between a target distribution (the corrected
60/// teacher-average histogram in P1.4 distillation) and the scorer's readout for one
61/// question. Distribution targets are the native input of the binned-softmax
62/// parameterization (S6b2); the target must be non-negative and sum to 1 over the
63/// question's label arity (2 for noul: `[P(false), P(true)]`).
64///
65/// Computed in log space (`Σ t·(log t − log p)`) with the target clamped away from
66/// exact zero, so zero-probability target bins contribute nothing instead of NaNs.
67pub fn soft_target_kl(score: &QuestionScore, target: &Tensor) -> Tensor {
68    let log_p = match score.kind {
69        QuestionKind::Noul => {
70            let logit = score.logits.view(-1);
71            let log_p_true = logit.log_sigmoid();
72            let log_p_false = logit.neg().log_sigmoid();
73            Tensor::cat(&[log_p_false, log_p_true], 0)
74        }
75        QuestionKind::Choice | QuestionKind::Score => score.logits.log_softmax(0, Kind::Float),
76        other => unreachable!("reserved question kind {other} cannot reach the scorer"),
77    };
78    let log_target = target.clamp_min(1e-12).log();
79    (target * (log_target - log_p)).sum(Kind::Float)
80}
81
82/// One shared linear scorer over anchor-token hidden states: a single
83/// `d_model → 1` projection applied to every anchor position, of every option, of
84/// every question. Trained weights live in a [`nn::VarStore`] so checkpoints attach to
85/// the converted backbone in P1.2 without a format boundary.
86pub struct SharedScorer {
87    projection: nn::Linear,
88}
89
90impl SharedScorer {
91    /// Create the scorer under `vs.root()` with the backbone's hidden size.
92    pub fn new(vs: &nn::VarStore, hidden_dim: i64) -> Self {
93        Self {
94            projection: nn::linear(vs.root(), hidden_dim, 1, Default::default()),
95        }
96    }
97
98    /// Score every question of every sequence in the batch.
99    ///
100    /// `hidden` is the backbone's final hidden states, `[batch, tokens, d_model]`;
101    /// `batch_anchors` is one anchor map list per batch row (from
102    /// [`crate::encoder::DecisionEncoder::encode`]). Each question's logits are the
103    /// projection of its own anchor states — structurally identical per option, which
104    /// is what makes option-order permutation a data-side concern (S6b1) rather than
105    /// an architectural one.
106    pub fn forward(
107        &self,
108        hidden: &Tensor,
109        batch_anchors: &[Vec<QuestionAnchors>],
110    ) -> Result<Vec<Vec<QuestionScore>>, Error> {
111        let size = hidden.size();
112        let batch = size[0] as usize;
113        if batch != batch_anchors.len() {
114            return Err(Error::BatchMismatch {
115                batch,
116                maps: batch_anchors.len(),
117            });
118        }
119        let device = hidden.device();
120        let mut output = Vec::with_capacity(batch);
121        for (row, anchors) in batch_anchors.iter().enumerate() {
122            let states = hidden.get(row as i64);
123            let mut questions = Vec::with_capacity(anchors.len());
124            for question in anchors {
125                let positions: Vec<i64> = question
126                    .anchor_positions
127                    .iter()
128                    .map(|position| i64::from(*position))
129                    .collect();
130                let positions = Tensor::from_slice(&positions).to_device(device);
131                let gathered = states.index_select(0, &positions);
132                let logits = gathered.apply(&self.projection).squeeze_dim(1);
133                questions.push(QuestionScore {
134                    question_id: question.question_id.clone(),
135                    kind: question.kind,
136                    logits,
137                });
138            }
139            output.push(questions);
140        }
141        Ok(output)
142    }
143}
144
145#[cfg(test)]
146#[allow(clippy::unwrap_used, clippy::expect_used)]
147mod tests {
148    use super::*;
149    use crate::encoder::{DecisionEncoder, QuestionAnchors};
150    use hyprstream_decision::parse_yaml;
151    use tch::nn::VarStore;
152    use tch::Device;
153
154    fn anchors(id: &str, kind: QuestionKind, positions: &[u32]) -> QuestionAnchors {
155        QuestionAnchors {
156            question_id: id.to_owned(),
157            kind,
158            anchor_positions: positions.to_vec(),
159        }
160    }
161
162    fn probs_vec(score: &QuestionScore) -> Vec<f64> {
163        Vec::<f64>::try_from(score.probabilities().to_kind(Kind::Double)).unwrap()
164    }
165
166    #[test]
167    fn choice_and_score_readouts_are_distributions() {
168        let vs = VarStore::new(Device::Cpu);
169        let scorer = SharedScorer::new(&vs, 8);
170        let hidden = Tensor::randn([1, 6, 8], (Kind::Float, Device::Cpu));
171        let batch = vec![vec![
172            anchors("c", QuestionKind::Choice, &[0, 1, 2]),
173            anchors("s", QuestionKind::Score, &[3, 4, 5]),
174        ]];
175        let output = scorer.forward(&hidden, &batch).unwrap();
176        assert_eq!(output.len(), 1);
177        let questions = &output[0];
178        let choice_probs = probs_vec(&questions[0]);
179        assert_eq!(choice_probs.len(), 3);
180        let sum: f64 = choice_probs.iter().sum();
181        assert!((sum - 1.0).abs() < 1e-5, "choice softmax sums to 1: {sum}");
182        let score_probs = probs_vec(&questions[1]);
183        let sum: f64 = score_probs.iter().sum();
184        assert!((sum - 1.0).abs() < 1e-5, "score softmax sums to 1: {sum}");
185    }
186
187    #[test]
188    fn noul_readout_is_sigmoid_in_label_order() {
189        let vs = VarStore::new(Device::Cpu);
190        let scorer = SharedScorer::new(&vs, 8);
191        let hidden = Tensor::randn([1, 1, 8], (Kind::Float, Device::Cpu));
192        let batch = vec![vec![anchors("n", QuestionKind::Noul, &[0])]];
193        let output = scorer.forward(&hidden, &batch).unwrap();
194        let score = &output[0][0];
195        let logit = score.logits.double_value(&[0]);
196        let probs = probs_vec(score);
197        assert_eq!(probs.len(), 2);
198        let expected_p_true = 1.0 / (1.0 + (-logit).exp());
199        assert!(
200            (probs[1] - expected_p_true).abs() < 1e-5,
201            "P(true) is sigmoid(logit): {} vs {expected_p_true}",
202            probs[1]
203        );
204        assert!(
205            (probs[0] + probs[1] - 1.0).abs() < 1e-5,
206            "[P(false), P(true)] sums to 1"
207        );
208    }
209
210    #[test]
211    fn score_expected_value_is_the_expectation_over_levels() {
212        let vs = VarStore::new(Device::Cpu);
213        let scorer = SharedScorer::new(&vs, 8);
214        let hidden = Tensor::randn([1, 3, 8], (Kind::Float, Device::Cpu));
215        let batch = vec![vec![anchors("s", QuestionKind::Score, &[0, 1, 2])]];
216        let output = scorer.forward(&hidden, &batch).unwrap();
217        let score = &output[0][0];
218        let probs = probs_vec(score);
219        let expected = score
220            .expected_value()
221            .expect("score carries an expected value")
222            .double_value(&[]);
223        let manual: f64 = probs.iter().enumerate().map(|(i, p)| i as f64 * p).sum();
224        assert!((expected - manual).abs() < 1e-5, "{expected} vs {manual}");
225        assert!(
226            (0.0..=2.0).contains(&expected),
227            "expectation within level range"
228        );
229        let c = &output[0][0];
230        assert_eq!(c.kind, QuestionKind::Score);
231    }
232
233    #[test]
234    fn scorer_is_shared_and_permutation_equivariant() {
235        // The same projection applies to every anchor: permuting a question's option
236        // order permutes its logits identically (the architectural half of order
237        // robustness; the data half is P1.3's mandatory permutation augmentation).
238        let vs = VarStore::new(Device::Cpu);
239        let scorer = SharedScorer::new(&vs, 8);
240        let hidden = Tensor::randn([1, 4, 8], (Kind::Float, Device::Cpu));
241        let forward = |positions: &[u32]| {
242            let batch = vec![vec![anchors("c", QuestionKind::Choice, positions)]];
243            let output = scorer.forward(&hidden, &batch).unwrap();
244            Vec::<f64>::try_from(output[0][0].logits.to_kind(Kind::Double)).unwrap()
245        };
246        let base = forward(&[0, 1, 2]);
247        let permuted = forward(&[2, 0, 1]);
248        assert_eq!(base.len(), permuted.len());
249        assert!((permuted[0] - base[2]).abs() < 1e-5);
250        assert!((permuted[1] - base[0]).abs() < 1e-5);
251        assert!((permuted[2] - base[1]).abs() < 1e-5);
252    }
253
254    #[test]
255    fn distillation_loss_backprops_into_the_shared_projection() {
256        let vs = VarStore::new(Device::Cpu);
257        let scorer = SharedScorer::new(&vs, 8);
258        let hidden = Tensor::randn([1, 2, 8], (Kind::Float, Device::Cpu)).set_requires_grad(true);
259        let batch = vec![vec![anchors("c", QuestionKind::Choice, &[0, 1])]];
260        let output = scorer.forward(&hidden, &batch).unwrap();
261        let target = Tensor::from_slice(&[0.25, 0.75]).to_kind(Kind::Float);
262        let loss = soft_target_kl(&output[0][0], &target);
263        assert!(loss.double_value(&[]) >= 0.0);
264        loss.backward();
265        let root = vs.root();
266        let weight = root.get("weight").expect("projection weight exists");
267        let grad = weight.grad();
268        let grad_norm = grad.norm().double_value(&[]);
269        assert!(grad_norm > 0.0, "KL loss backprops into the scorer");
270    }
271
272    #[test]
273    fn soft_target_kl_ignores_zero_mass_bins() {
274        let vs = VarStore::new(Device::Cpu);
275        let scorer = SharedScorer::new(&vs, 8);
276        let hidden = Tensor::randn([1, 3, 8], (Kind::Float, Device::Cpu));
277        let batch = vec![vec![anchors("s", QuestionKind::Score, &[0, 1, 2])]];
278        let output = scorer.forward(&hidden, &batch).unwrap();
279        let target = Tensor::from_slice(&[0.0, 1.0, 0.0]).to_kind(Kind::Float);
280        let loss = soft_target_kl(&output[0][0], &target).double_value(&[]);
281        assert!(
282            loss.is_finite(),
283            "zero target bins contribute nothing: {loss}"
284        );
285    }
286
287    #[test]
288    fn varstore_checkpoint_roundtrip_preserves_logits() {
289        let dir = tempfile::tempdir().unwrap();
290        let path = dir.path().join("scorer.ot");
291        let vs = VarStore::new(Device::Cpu);
292        let scorer = SharedScorer::new(&vs, 8);
293        let hidden = Tensor::randn([1, 2, 8], (Kind::Float, Device::Cpu));
294        let batch = vec![vec![anchors("c", QuestionKind::Choice, &[0, 1])]];
295        let before = scorer.forward(&hidden, &batch).unwrap();
296        let before = Vec::<f64>::try_from(before[0][0].logits.to_kind(Kind::Double)).unwrap();
297        vs.save(&path).unwrap();
298
299        let mut vs2 = VarStore::new(Device::Cpu);
300        let scorer2 = SharedScorer::new(&vs2, 8);
301        vs2.load(&path).unwrap();
302        let after = scorer2.forward(&hidden, &batch).unwrap();
303        let after = Vec::<f64>::try_from(after[0][0].logits.to_kind(Kind::Double)).unwrap();
304        assert_eq!(before, after, "checkpoint roundtrip preserves the scorer");
305    }
306
307    #[test]
308    fn batch_mismatch_fails_loudly() {
309        let vs = VarStore::new(Device::Cpu);
310        let scorer = SharedScorer::new(&vs, 8);
311        let hidden = Tensor::randn([2, 2, 8], (Kind::Float, Device::Cpu));
312        let batch = vec![vec![anchors("n", QuestionKind::Noul, &[0])]];
313        let error = scorer.forward(&hidden, &batch).unwrap_err();
314        assert!(matches!(error, Error::BatchMismatch { batch: 2, maps: 1 }));
315    }
316
317    #[test]
318    fn encode_then_score_end_to_end() {
319        // The full contract path: authored spec → canonical serialization → token ids +
320        // anchor map → hidden states → typed distributions.
321        const TOK_JSON: &str = r#"{"version":"1.0","truncation":null,"padding":null,"added_tokens":[],"normalizer":null,"pre_tokenizer":{"type":"Whitespace"},"post_processor":null,"decoder":null,"model":{"type":"WordLevel","vocab":{"[UNK]":0},"unk_token":"[UNK]"}}"#;
322        let tokenizer = tokenizers::Tokenizer::from_bytes(TOK_JSON.as_bytes()).unwrap();
323        let encoder = DecisionEncoder::new(tokenizer).unwrap();
324        let set = parse_yaml(
325            r#"
326state: "The box was crushed."
327questions:
328  tone:
329    type: choice
330    criteria:
331      positive: "approval"
332      negative: "disapproval"
333  severe:
334    type: score
335    criteria: ["trivial", "critical"]
336  is_refund:
337    type: noul
338"#,
339        )
340        .unwrap();
341        let encoded = encoder.encode(&set).unwrap();
342        let tokens = encoded.token_count() as i64;
343        let vs = VarStore::new(Device::Cpu);
344        let scorer = SharedScorer::new(&vs, 8);
345        let hidden = Tensor::randn([1, tokens, 8], (Kind::Float, Device::Cpu));
346        let output = scorer.forward(&hidden, &[encoded.questions]).unwrap();
347        let questions = &output[0];
348        assert_eq!(questions.len(), 3);
349        assert_eq!(probs_vec(&questions[0]).len(), 2, "choice over 2 options");
350        assert_eq!(probs_vec(&questions[1]).len(), 2, "score over 2 levels");
351        assert!(questions[1].expected_value().is_some());
352        assert_eq!(
353            probs_vec(&questions[2]).len(),
354            2,
355            "noul [P(false), P(true)]"
356        );
357        assert!(questions[2].expected_value().is_none());
358    }
359}