Skip to main content

aios_agent/backends/predictive/
predictor.rs

1//! Next-app predictor and ranking algorithms.
2
3use std::collections::BTreeSet;
4
5use super::ensemble::{ensemble_component_names, logistic_feature_names};
6use super::train::{order2_key, user_transition_key};
7use super::{
8    score_order, AppScore, NextAppAlgorithm, NextAppModelArtifact, NextAppPredictor,
9    PredictionFeatures, SCHEMA_VERSION,
10};
11
12impl NextAppPredictor {
13    pub fn new(artifact: NextAppModelArtifact) -> Result<Self, String> {
14        validate_artifact(&artifact)?;
15        let app_index = artifact
16            .app_vocab
17            .iter()
18            .enumerate()
19            .map(|(i, app)| (app.clone(), i))
20            .collect();
21        Ok(Self {
22            artifact,
23            app_index,
24        })
25    }
26
27    pub fn from_path(path: impl AsRef<std::path::Path>) -> Result<Self, String> {
28        let file = std::fs::File::open(path.as_ref())
29            .map_err(|err| format!("opening model artifact {}: {err}", path.as_ref().display()))?;
30        let artifact: NextAppModelArtifact = serde_json::from_reader(std::io::BufReader::new(file))
31            .map_err(|err| format!("parsing model artifact {}: {err}", path.as_ref().display()))?;
32        Self::new(artifact)
33    }
34
35    pub fn artifact(&self) -> &NextAppModelArtifact {
36        &self.artifact
37    }
38
39    pub fn rank(
40        &self,
41        features: &PredictionFeatures,
42        algorithm: NextAppAlgorithm,
43        k: usize,
44    ) -> Vec<AppScore> {
45        let mut scores = match algorithm {
46            NextAppAlgorithm::NaiveBayes => self.rank_naive_bayes(features),
47            NextAppAlgorithm::Markov => self.rank_markov(features),
48            NextAppAlgorithm::FeatureLift => self.rank_feature_lift(features),
49            NextAppAlgorithm::Ensemble => self.rank_ensemble(features),
50        };
51        if let Some(current) = features.current_app.as_deref() {
52            filter_current_app(&mut scores, current);
53        }
54        if scores.is_empty() {
55            scores = self.artifact.global_popularity.clone();
56            if let Some(current) = features.current_app.as_deref() {
57                filter_current_app(&mut scores, current);
58            }
59        }
60        scores.truncate(k);
61        scores
62    }
63
64    pub(super) fn rank_naive_bayes(&self, features: &PredictionFeatures) -> Vec<AppScore> {
65        let mut scores = self.artifact.naive_bayes.class_log_priors.clone();
66        for feature_key in feature_keys(features) {
67            if let Some(log_probs) = self
68                .artifact
69                .naive_bayes
70                .feature_log_probs
71                .get(&feature_key)
72            {
73                add_vec(&mut scores, log_probs);
74            } else {
75                add_vec(
76                    &mut scores,
77                    &self.artifact.naive_bayes.unknown_feature_log_probs,
78                );
79            }
80        }
81        rank_from_logits(&self.artifact.app_vocab, &scores)
82    }
83
84    pub(super) fn rank_markov(&self, features: &PredictionFeatures) -> Vec<AppScore> {
85        if let (Some(user), Some(current)) = (&features.user_id, &features.current_app) {
86            let key = user_transition_key(user, current);
87            if let Some(scores) = self.artifact.markov.user_transitions.get(&key) {
88                return scores.clone();
89            }
90        }
91        if let Some(current) = &features.current_app {
92            if let Some(scores) = self.artifact.markov.global_transitions.get(current) {
93                return scores.clone();
94            }
95        }
96        if let Some(prev) = features.history.last() {
97            if let Some(scores) = self.artifact.markov.global_transitions.get(prev) {
98                return scores.clone();
99            }
100        }
101        self.artifact.global_popularity.clone()
102    }
103
104    /// Global order-2 Markov ranking keyed on `(prev, current)`. Returns an
105    /// empty list when the order-2 pair was never observed, so the combiner can
106    /// simply contribute nothing rather than falling back to a weaker signal.
107    pub(super) fn rank_markov_order2(&self, features: &PredictionFeatures) -> Vec<AppScore> {
108        if let Some(current) = &features.current_app {
109            let Some(prev) = previous_feature_app(&features.history, current) else {
110                return Vec::new();
111            };
112            let key = order2_key(prev, current);
113            if let Some(scores) = self.artifact.markov.global_transitions_order2.get(&key) {
114                return scores.clone();
115            }
116        }
117        Vec::new()
118    }
119
120    /// Per-user order-1 Markov ranking (recency proxy). Uses the most recent
121    /// `(user, current)` transition distribution; empty when unseen so the
122    /// combiner contributes nothing rather than a weaker global signal.
123    pub(super) fn rank_recency(&self, features: &PredictionFeatures) -> Vec<AppScore> {
124        if let (Some(user), Some(current)) = (&features.user_id, &features.current_app) {
125            let key = user_transition_key(user, current);
126            if let Some(scores) = self.artifact.markov.user_transitions.get(&key) {
127                return scores.clone();
128            }
129        }
130        Vec::new()
131    }
132
133    /// Per-user app-usage frequency (MFU) ranking, unconditional on the current
134    /// app. Empty when the user was unseen in training, so the combiner
135    /// contributes nothing rather than a weaker global signal.
136    pub(super) fn rank_user_frequency(&self, features: &PredictionFeatures) -> Vec<AppScore> {
137        if let Some(user) = &features.user_id {
138            if let Some(scores) = self.artifact.user_frequency.get(user) {
139                return scores.clone();
140            }
141        }
142        Vec::new()
143    }
144
145    /// Hard recency pointer: the single most recent next-app this user opened
146    /// from the current app. Returns a one-element list (score 1.0) so the
147    /// combiner gives it a peaked top-1 contribution, mirroring the strong
148    /// baseline's flat recency boost. Empty when the `(user, current)` pair was
149    /// never seen.
150    pub(super) fn rank_user_recency(&self, features: &PredictionFeatures) -> Vec<AppScore> {
151        if let (Some(user), Some(current)) = (&features.user_id, &features.current_app) {
152            let key = user_transition_key(user, current);
153            if let Some(app) = self.artifact.user_recency.get(&key) {
154                return vec![AppScore {
155                    app: app.clone(),
156                    score: 1.0,
157                }];
158            }
159        }
160        Vec::new()
161    }
162
163    /// Global popularity ranking, used as the combiner's fallback component.
164    pub(super) fn rank_popularity(&self, _features: &PredictionFeatures) -> Vec<AppScore> {
165        self.artifact.global_popularity.clone()
166    }
167
168    /// Context-aware Markov ranking using temporal features. Looks up
169    /// `"{current}\t{hour}"` and `"{current}\t{weekday}"` transitions and
170    /// merges them with equal weight. Returns empty when no temporal key
171    /// matched, so the combiner contributes nothing rather than a weaker
172    /// global signal.
173    pub(super) fn rank_markov_context(&self, features: &PredictionFeatures) -> Vec<AppScore> {
174        let Some(current) = &features.current_app else {
175            return Vec::new();
176        };
177        let mut combined: std::collections::BTreeMap<String, f32> =
178            std::collections::BTreeMap::new();
179        let mut found = false;
180        if let Some(hour) = features.hour_bucket {
181            let key = format!("{current}\t{hour}");
182            if let Some(scores) = self.artifact.markov_context.get(&key) {
183                for s in scores {
184                    *combined.entry(s.app.clone()).or_default() += s.score;
185                }
186                found = true;
187            }
188        }
189        if let Some(weekday) = features.weekday {
190            let key = format!("{current}\t{weekday}");
191            if let Some(scores) = self.artifact.markov_context.get(&key) {
192                for s in scores {
193                    *combined.entry(s.app.clone()).or_default() += s.score;
194                }
195                found = true;
196            }
197        }
198        if !found {
199            return Vec::new();
200        }
201        let mut ranked: Vec<AppScore> = combined
202            .into_iter()
203            .map(|(app, score)| AppScore { app, score })
204            .collect();
205        ranked.sort_by(|a, b| score_order(a.score, b.score).then_with(|| a.app.cmp(&b.app)));
206        ranked
207    }
208
209    pub(super) fn rank_feature_lift(&self, features: &PredictionFeatures) -> Vec<AppScore> {
210        let active: BTreeSet<String> = feature_keys(features).into_iter().collect();
211        let mut scores = self.artifact.feature_lift.base_scores.clone();
212        for tree in &self.artifact.feature_lift.trees {
213            if active.contains(&tree.feature_key) {
214                for app_score in &tree.yes_scores {
215                    if let Some(index) = self.app_index.get(&app_score.app) {
216                        scores[*index] += app_score.score;
217                    }
218                }
219            }
220        }
221        rank_from_logits(&self.artifact.app_vocab, &scores)
222    }
223}
224
225fn validate_artifact(artifact: &NextAppModelArtifact) -> Result<(), String> {
226    if artifact.schema_version != SCHEMA_VERSION {
227        return Err(format!(
228            "unsupported next-app artifact schema {}; expected {SCHEMA_VERSION}",
229            artifact.schema_version
230        ));
231    }
232    let classes = artifact.app_vocab.len();
233    if classes == 0 {
234        return Err("artifact app_vocab is empty".into());
235    }
236    let mut app_vocab = BTreeSet::new();
237    for app in &artifact.app_vocab {
238        if !app_vocab.insert(app.as_str()) {
239            return Err(format!("artifact app_vocab contains duplicate app `{app}`"));
240        }
241    }
242    if artifact.naive_bayes.class_log_priors.len() != classes
243        || artifact.naive_bayes.unknown_feature_log_probs.len() != classes
244        || artifact.feature_lift.base_scores.len() != classes
245        || artifact
246            .feature_lift
247            .trees
248            .iter()
249            .any(|tree| tree.yes_scores.len() != classes)
250    {
251        return Err("artifact vector sizes do not match app_vocab".into());
252    }
253    if artifact
254        .naive_bayes
255        .feature_log_probs
256        .values()
257        .any(|probs| probs.len() != classes)
258    {
259        return Err(
260            "artifact naive_bayes feature_log_probs vector sizes do not match app_vocab".into(),
261        );
262    }
263    validate_score_list(
264        "global_popularity",
265        &artifact.global_popularity,
266        &app_vocab,
267        true,
268    )?;
269    for (current_app, scores) in &artifact.markov.global_transitions {
270        if !app_vocab.contains(current_app.as_str()) {
271            return Err(format!(
272                "artifact markov global transition key `{current_app}` is not in app_vocab"
273            ));
274        }
275        validate_score_list(
276            &format!("markov.global_transitions[{current_app}]"),
277            scores,
278            &app_vocab,
279            false,
280        )?;
281    }
282    for (key, scores) in &artifact.markov.user_transitions {
283        let Some((_, current_app)) = key.rsplit_once('\t') else {
284            return Err(format!(
285                "artifact markov user transition key `{key}` is not user_id<TAB>current_app"
286            ));
287        };
288        if !app_vocab.contains(current_app) {
289            return Err(format!(
290                "artifact markov user transition current app `{current_app}` is not in app_vocab"
291            ));
292        }
293        validate_score_list(
294            &format!("markov.user_transitions[{key}]"),
295            scores,
296            &app_vocab,
297            false,
298        )?;
299    }
300    for (key, scores) in &artifact.markov.global_transitions_order2 {
301        let Some((_, current_app)) = key.rsplit_once('\t') else {
302            return Err(format!(
303                "artifact markov order2 key `{key}` is not prev_app<TAB>current_app"
304            ));
305        };
306        if !app_vocab.contains(current_app) {
307            return Err(format!(
308                "artifact markov order2 current app `{current_app}` is not in app_vocab"
309            ));
310        }
311        validate_score_list(
312            &format!("markov.global_transitions_order2[{key}]"),
313            scores,
314            &app_vocab,
315            false,
316        )?;
317    }
318    for tree in &artifact.feature_lift.trees {
319        validate_score_list(
320            &format!("feature_lift.tree[{}].yes_scores", tree.feature_key),
321            &tree.yes_scores,
322            &app_vocab,
323            true,
324        )?;
325    }
326    for (key, scores) in &artifact.markov_context {
327        validate_score_list(&format!("markov_context[{key}]"), scores, &app_vocab, false)?;
328    }
329    for (user_id, scores) in &artifact.user_frequency {
330        validate_score_list(
331            &format!("user_frequency[{user_id}]"),
332            scores,
333            &app_vocab,
334            false,
335        )?;
336    }
337    for (key, app) in &artifact.user_recency {
338        let Some((_, current_app)) = key.rsplit_once('\t') else {
339            return Err(format!(
340                "artifact user_recency key `{key}` is not user_id<TAB>current_app"
341            ));
342        };
343        if !app_vocab.contains(current_app) {
344            return Err(format!(
345                "artifact user_recency current app `{current_app}` is not in app_vocab"
346            ));
347        }
348        if !app_vocab.contains(app.as_str()) {
349            return Err(format!(
350                "artifact user_recency target app `{app}` is not in app_vocab"
351            ));
352        }
353    }
354    validate_combiner(&artifact.ensemble_combiner)?;
355    if !(artifact.ensemble_logistic.feature_names.is_empty()
356        && artifact.ensemble_logistic.weights.is_empty())
357    {
358        let expected = logistic_feature_names();
359        if artifact.ensemble_logistic.feature_names.is_empty()
360            || artifact.ensemble_logistic.weights.is_empty()
361            || artifact.ensemble_logistic.feature_names.len()
362                != artifact.ensemble_logistic.weights.len()
363        {
364            return Err(
365                "artifact ensemble_logistic feature_names and weights must be non-empty parallel vectors"
366                    .into(),
367            );
368        }
369        if artifact.ensemble_logistic.feature_names != expected {
370            return Err(
371                "artifact ensemble_logistic feature_names do not match runtime features".into(),
372            );
373        }
374        if artifact.ensemble_logistic.weights.len() != expected.len() {
375            return Err(
376                "artifact ensemble_logistic weights length does not match feature_names".into(),
377            );
378        }
379    }
380    Ok(())
381}
382
383fn validate_combiner(combiner: &super::EnsembleCombiner) -> Result<(), String> {
384    if combiner.components.is_empty() && combiner.weights.is_empty() {
385        return Ok(());
386    }
387    if combiner.components.is_empty()
388        || combiner.weights.is_empty()
389        || combiner.components.len() != combiner.weights.len()
390    {
391        return Err(
392            "artifact ensemble_combiner components and weights must be parallel vectors".into(),
393        );
394    }
395    let known: BTreeSet<&str> = ensemble_component_names().into_iter().collect();
396    let mut seen = BTreeSet::new();
397    for (component, weight) in combiner.components.iter().zip(combiner.weights.iter()) {
398        if !known.contains(component.as_str()) {
399            return Err(format!(
400                "artifact ensemble_combiner component `{component}` is unknown"
401            ));
402        }
403        if !seen.insert(component.as_str()) {
404            return Err(format!(
405                "artifact ensemble_combiner contains duplicate component `{component}`"
406            ));
407        }
408        if !weight.is_finite() || *weight < 0.0 {
409            return Err(format!(
410                "artifact ensemble_combiner weight for `{component}` must be finite and non-negative"
411            ));
412        }
413    }
414    Ok(())
415}
416
417fn validate_score_list(
418    label: &str,
419    scores: &[AppScore],
420    app_vocab: &BTreeSet<&str>,
421    require_full_vocab: bool,
422) -> Result<(), String> {
423    if require_full_vocab && scores.len() != app_vocab.len() {
424        return Err(format!(
425            "artifact {label} must contain exactly one score per app_vocab entry"
426        ));
427    }
428    let mut seen = BTreeSet::new();
429    for score in scores {
430        if !app_vocab.contains(score.app.as_str()) {
431            return Err(format!(
432                "artifact {label} references app `{}` outside app_vocab",
433                score.app
434            ));
435        }
436        if !seen.insert(score.app.as_str()) {
437            return Err(format!(
438                "artifact {label} contains duplicate score for app `{}`",
439                score.app
440            ));
441        }
442    }
443    Ok(())
444}
445
446fn filter_current_app(scores: &mut Vec<AppScore>, current: &str) {
447    scores.retain(|score| score.app != current);
448}
449
450fn previous_feature_app<'a>(history: &'a [String], current_app: &str) -> Option<&'a str> {
451    history
452        .iter()
453        .rev()
454        .find(|app| app.as_str() != current_app)
455        .map(String::as_str)
456}
457
458pub(crate) fn feature_keys(features: &PredictionFeatures) -> Vec<String> {
459    let mut keys = Vec::new();
460    if let Some(user) = &features.user_id {
461        keys.push(format!("user={user}"));
462    }
463    if let Some(current) = &features.current_app {
464        keys.push(format!("current={current}"));
465    }
466    if let Some(prev) = features.history.last() {
467        keys.push(format!("prev={prev}"));
468    }
469    for (idx, app) in features.history.iter().rev().take(3).enumerate() {
470        keys.push(format!("hist{idx}={app}"));
471    }
472    if let Some(hour) = features.hour_bucket {
473        keys.push(format!("hour={hour}"));
474    }
475    if let Some(weekday) = features.weekday {
476        keys.push(format!("weekday={weekday}"));
477    }
478    if let Some(event_type) = &features.event_type {
479        keys.push(format!("event={event_type}"));
480    }
481    keys
482}
483
484fn add_vec(target: &mut [f32], values: &[f32]) {
485    for (target, value) in target.iter_mut().zip(values.iter()) {
486        *target += *value;
487    }
488}
489
490fn rank_from_logits(app_vocab: &[String], logits: &[f32]) -> Vec<AppScore> {
491    let max = logits.iter().copied().fold(f32::NEG_INFINITY, f32::max);
492    let exp: Vec<f32> = logits.iter().map(|score| (*score - max).exp()).collect();
493    let sum: f32 = exp.iter().sum();
494    let mut ranked: Vec<AppScore> = app_vocab
495        .iter()
496        .cloned()
497        .zip(exp)
498        .map(|(app, value)| AppScore {
499            app,
500            score: if sum > 0.0 { value / sum } else { 0.0 },
501        })
502        .collect();
503    ranked.sort_by(|a, b| score_order(a.score, b.score).then_with(|| a.app.cmp(&b.app)));
504    ranked
505}