Skip to main content

spider_optimize/
model.rs

1//! The scoring boundary.
2//!
3//! A [`Scorer`] estimates, for one candidate, how likely the request is to
4//! succeed, how long it takes and what it costs, and how much evidence stands
5//! behind that estimate. It answers from the [`Input`] alone, with no input
6//! or output of any kind.
7//!
8//! [`NoModel`] abstains on every field. [`Compact`] reads numeric artifacts
9//! and performs calibrated FP32 inference without allocation.
10
11use crate::features::Input;
12use std::sync::Arc;
13
14/// The version of a set of weights, which moves independently of the crate.
15#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
16pub struct ModelVersion(pub u16);
17
18/// A scorer's estimate for one candidate.
19///
20/// A NaN in any field means the scorer does not know, and the gate keeps the
21/// request as it is.
22#[derive(Debug, Clone, Copy, PartialEq)]
23pub struct Score {
24    /// The chance the request gets what the caller asked for, zero to one.
25    pub p_success: f32,
26    /// The expected time for the page, in milliseconds.
27    pub latency_ms: f32,
28    /// The expected spend, in credits.
29    pub credits: f32,
30    /// How much evidence the estimate rests on. Zero is none.
31    pub support: f32,
32}
33
34impl Score {
35    /// No estimate at all.
36    pub const fn unknown() -> Score {
37        Score {
38            p_success: f32::NAN,
39            latency_ms: f32::NAN,
40            credits: f32::NAN,
41            support: 0.0,
42        }
43    }
44
45    /// Whether any field is NaN.
46    pub fn has_nan(&self) -> bool {
47        self.p_success.is_nan()
48            || self.latency_ms.is_nan()
49            || self.credits.is_nan()
50            || self.support.is_nan()
51    }
52}
53
54/// Estimates what a candidate edit does.
55pub trait Scorer: Send + Sync {
56    /// Score one candidate. Must not allocate or reach outside the process.
57    fn score(&self, input: &Input) -> Score;
58
59    /// Which weights answered, or `None` when no model is involved.
60    fn version(&self) -> Option<ModelVersion>;
61}
62
63/// The scorer with no weights. It abstains on everything.
64#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
65pub struct NoModel;
66
67impl Scorer for NoModel {
68    fn score(&self, _input: &Input) -> Score {
69        Score::unknown()
70    }
71
72    fn version(&self) -> Option<ModelVersion> {
73        None
74    }
75}
76
77impl<T: Scorer + ?Sized> Scorer for Arc<T> {
78    fn score(&self, input: &Input) -> Score {
79        (**self).score(input)
80    }
81
82    fn version(&self) -> Option<ModelVersion> {
83        (**self).version()
84    }
85}
86
87impl<T: Scorer + ?Sized> Scorer for Box<T> {
88    fn score(&self, input: &Input) -> Score {
89        (**self).score(input)
90    }
91
92    fn version(&self) -> Option<ModelVersion> {
93        (**self).version()
94    }
95}
96
97impl<T: Scorer + ?Sized> Scorer for &T {
98    fn score(&self, input: &Input) -> Score {
99        (**self).score(input)
100    }
101
102    fn version(&self) -> Option<ModelVersion> {
103        (**self).version()
104    }
105}
106
107use crate::artifact::{Calibration, Compact, Head, MAX_WIDTH};
108use crate::features::EDIT_DIM;
109use spider_route::features::FEATURES_USED;
110
111fn sigmoid(x: f32) -> f32 {
112    1.0 / (1.0 + (-x).exp())
113}
114impl Calibration {
115    pub(crate) fn apply(&self, x: f32) -> f32 {
116        match self {
117            Self::Identity => x,
118            Self::Platt(a, b) => sigmoid(a * x + b),
119            Self::Isotonic(pairs) => {
120                let Some(first) = pairs.first() else {
121                    return f32::NAN;
122                };
123                if x <= first.0 {
124                    return first.1;
125                }
126                for pair in pairs.windows(2) {
127                    if let [a, b] = pair {
128                        if x <= b.0 {
129                            return a.1 + (b.1 - a.1) * ((x - a.0) / (b.0 - a.0));
130                        }
131                    }
132                }
133                pairs.last().map_or(f32::NAN, |p| p.1)
134            }
135        }
136    }
137}
138impl Compact {
139    /// Score exactly 152 base slots and 96 edit slots. Invalid lengths abstain.
140    /// Non-finite values use zero in dense nets, and the encoded missing branch
141    /// in trees; either way success becomes NaN so the gate abstains.
142    /// An empty support table means no support restriction.
143    pub fn score_slices(&self, base: &[f32], edit: &[f32], cell: u32) -> Score {
144        if base.len() != FEATURES_USED || edit.len() != EDIT_DIM {
145            return Score::unknown();
146        }
147        let nonfinite = base.iter().chain(edit).any(|v| !v.is_finite());
148        let mut a = [0.0; MAX_WIDTH];
149        let mut b = [0.0; MAX_WIDTH];
150        let mut outputs = [0.0f32; 3];
151        for ((head, calibration), output) in
152            self.heads.iter().zip(&self.calibration).zip(&mut outputs)
153        {
154            let raw = match head {
155                Head::Mlp(layers) => {
156                    for (dest, src) in a.iter_mut().zip(base.iter().chain(edit)) {
157                        *dest = if src.is_finite() { *src } else { 0.0 };
158                    }
159                    for layer in layers {
160                        for ((dest, weights), bias) in b
161                            .iter_mut()
162                            .take(layer.rows)
163                            .zip(layer.weights.chunks_exact(layer.cols))
164                            .zip(&layer.bias)
165                        {
166                            let mut sum = *bias;
167                            for (weight, input) in weights.iter().zip(&a) {
168                                sum += weight * input;
169                            }
170                            *dest = match layer.activation {
171                                1 => sum.max(0.0),
172                                2 => sigmoid(sum),
173                                _ => sum,
174                            };
175                        }
176                        (a, b) = (b, a);
177                    }
178                    a.first().copied().unwrap_or(f32::NAN)
179                }
180                Head::Gbdt(base_score, trees) => {
181                    let mut sum = *base_score;
182                    for tree in trees {
183                        let mut at = 0;
184                        // Validated acyclic trees terminate in at most node count steps.
185                        for _ in 0..tree.len() {
186                            let Some(node) = tree.get(at) else {
187                                return Score::unknown();
188                            };
189                            if node.left == 65535 && node.right == 65535 {
190                                sum += node.value;
191                                break;
192                            }
193                            let feature = usize::from(node.feature & 0x7fff);
194                            let x = if feature < FEATURES_USED {
195                                base.get(feature)
196                            } else {
197                                edit.get(feature - FEATURES_USED)
198                            }
199                            .copied()
200                            .unwrap_or(f32::NAN);
201                            let left = if x.is_finite() {
202                                x <= node.threshold
203                            } else {
204                                node.feature & 0x8000 != 0
205                            };
206                            at = usize::from(if left { node.left } else { node.right });
207                        }
208                    }
209                    sum
210                }
211            };
212            *output = calibration.apply(raw);
213        }
214        let [success, latency, credits] = outputs;
215        Score {
216            p_success: if nonfinite { f32::NAN } else { success },
217            latency_ms: latency.exp_m1(),
218            credits: credits.exp_m1(),
219            support: if self.support.is_empty() || self.supported(cell) {
220                1.0
221            } else {
222                0.0
223            },
224        }
225    }
226    /// Score an input with a known support cell, using only the base slots in use.
227    pub fn score_in_cell(&self, input: &Input, cell: u32) -> Score {
228        let base = input.base.as_slice();
229        let Some(used) = base.get(..FEATURES_USED) else {
230            return Score::unknown();
231        };
232        let mut score = self.score_slices(used, input.edit.as_slice(), cell);
233        if base.iter().any(|x| !x.is_finite()) {
234            score.p_success = f32::NAN;
235        }
236        score
237    }
238}
239impl Scorer for Compact {
240    /// Without a cell, support is one only when the support table is empty.
241    fn score(&self, input: &Input) -> Score {
242        let mut score = self.score_in_cell(input, 0);
243        score.support = if self.support.is_empty() { 1.0 } else { 0.0 };
244        score
245    }
246    fn version(&self) -> Option<ModelVersion> {
247        Some(Compact::version(self))
248    }
249}
250
251#[cfg(test)]
252mod tests {
253    #![allow(
254        clippy::unwrap_used,
255        clippy::expect_used,
256        clippy::panic,
257        clippy::unreachable,
258        clippy::indexing_slicing,
259        clippy::string_slice
260    )]
261    use super::*;
262
263    #[test]
264    fn no_model_abstains_through_every_wrapper() {
265        let input = Input::default();
266        let scorers: [Box<dyn Scorer>; 4] = [
267            Box::new(NoModel),
268            Box::new(Arc::new(NoModel)),
269            Box::new(Box::new(NoModel) as Box<dyn Scorer>),
270            Box::new(&NoModel),
271        ];
272        for scorer in &scorers {
273            let score = scorer.score(&input);
274            assert!(score.p_success.is_nan() && score.latency_ms.is_nan());
275            assert!(score.credits.is_nan());
276            assert_eq!(score.support, 0.0);
277            assert!(score.has_nan());
278            assert_eq!(scorer.version(), None);
279        }
280    }
281}