Skip to main content

aios_agent/backends/predictive/
train.rs

1//! Offline training for the next-app predictive model.
2
3use std::collections::{BTreeMap, BTreeSet};
4
5use super::ensemble::fit_ensemble_models;
6use super::predictor::feature_keys;
7use super::{
8    prediction_features_for_example, score_order, AppScore, EnsembleCombiner, FeatureLiftModel,
9    FeatureLiftTree, LogisticRerankerModel, MarkovModel, NaiveBayesModel, NextAppModelArtifact,
10    NextAppModelConfig, NextAppTrainingExample, TrainingSummary, MAX_TRAINED_FEATURES, MODEL_NAME,
11    SCHEMA_VERSION,
12};
13
14pub fn train_next_app_artifact(
15    dataset_id: impl Into<String>,
16    config: NextAppModelConfig,
17    examples: &[NextAppTrainingExample],
18) -> Result<NextAppModelArtifact, String> {
19    let dataset_id = dataset_id.into();
20    // Train the base model (Naive Bayes, Markov, feature-lift) on all examples,
21    // then fit the learned ensemble combiner on a held-out validation slice.
22    let mut artifact = train_base_artifact(&dataset_id, config.clone(), examples)?;
23    let ensemble_models = fit_ensemble_models(&dataset_id, &config, examples);
24    artifact.ensemble_combiner = ensemble_models.rrf;
25    artifact.ensemble_logistic = ensemble_models.logistic;
26    Ok(artifact)
27}
28
29/// Train only the base component models (no ensemble combiner fit). Used both
30/// for the final artifact's base and for the combiner's fit-slice model, so the
31/// combiner fit never recurses into itself.
32pub(super) fn train_base_artifact(
33    dataset_id: &str,
34    config: NextAppModelConfig,
35    examples: &[NextAppTrainingExample],
36) -> Result<NextAppModelArtifact, String> {
37    if examples.is_empty() {
38        return Err("cannot train next-app model with zero examples".into());
39    }
40
41    let mut app_set = BTreeSet::new();
42    let mut user_set = BTreeSet::new();
43    for example in examples {
44        app_set.insert(example.current_app.clone());
45        app_set.insert(example.label_app.clone());
46        user_set.insert(example.user_id.clone());
47    }
48    let app_vocab: Vec<String> = app_set.into_iter().collect();
49    let app_index: BTreeMap<String, usize> = app_vocab
50        .iter()
51        .enumerate()
52        .map(|(i, app)| (app.clone(), i))
53        .collect();
54    let classes = app_vocab.len();
55
56    let mut class_counts = vec![0_u32; classes];
57    let mut feature_counts: BTreeMap<String, Vec<u32>> = BTreeMap::new();
58    let mut feature_frequency: BTreeMap<String, u32> = BTreeMap::new();
59    let mut global_transitions: BTreeMap<String, BTreeMap<String, u32>> = BTreeMap::new();
60    let mut user_transitions: BTreeMap<String, BTreeMap<String, u32>> = BTreeMap::new();
61    let mut global_transitions_order2: BTreeMap<String, BTreeMap<String, u32>> = BTreeMap::new();
62    // Temporal Markov transitions: keyed by "{current}\t{hour}" or
63    // "{current}\t{weekday}" for context-aware next-app prediction.
64    let mut temporal_transitions: BTreeMap<String, BTreeMap<String, u32>> = BTreeMap::new();
65    // Per-user app-usage frequency (MFU): counts each observed next app per
66    // user, unconditional on the current app.
67    let mut user_frequency_counts: BTreeMap<String, BTreeMap<String, u32>> = BTreeMap::new();
68    // Hard recency pointer: last observed next app per (user, current), in
69    // example order (last write wins). Examples are chronological per user.
70    let mut user_recency: BTreeMap<String, String> = BTreeMap::new();
71
72    for example in examples {
73        let label_idx = *app_index
74            .get(&example.label_app)
75            .ok_or_else(|| format!("label not in vocab: {}", example.label_app))?;
76        class_counts[label_idx] += 1;
77
78        *user_frequency_counts
79            .entry(example.user_id.clone())
80            .or_default()
81            .entry(example.label_app.clone())
82            .or_default() += 1;
83
84        user_recency.insert(
85            user_transition_key(&example.user_id, &example.current_app),
86            example.label_app.clone(),
87        );
88
89        let features = training_features(example);
90        for feature in features {
91            let counts = feature_counts
92                .entry(feature.clone())
93                .or_insert(vec![0; classes]);
94            counts[label_idx] += 1;
95            *feature_frequency.entry(feature).or_default() += 1;
96        }
97
98        *global_transitions
99            .entry(example.current_app.clone())
100            .or_default()
101            .entry(example.label_app.clone())
102            .or_default() += 1;
103        *user_transitions
104            .entry(user_transition_key(&example.user_id, &example.current_app))
105            .or_default()
106            .entry(example.label_app.clone())
107            .or_default() += 1;
108
109        // Order-2 transitions keyed (prev, current). The "previous app" is the
110        // most recent history entry that is not the current app itself, so that
111        // repeated current-app foreground records do not collapse the key into
112        // (current, current). This matches how the strong baseline derives its
113        // order-2 previous app and how `prev=` is intended to behave.
114        if let Some(prev) = previous_app(example) {
115            *global_transitions_order2
116                .entry(order2_key(prev, &example.current_app))
117                .or_default()
118                .entry(example.label_app.clone())
119                .or_default() += 1;
120        }
121
122        // Temporal transitions keyed by hour and weekday.
123        let hour_key = format!("{}\t{}", example.current_app, example.hour_bucket);
124        *temporal_transitions
125            .entry(hour_key)
126            .or_default()
127            .entry(example.label_app.clone())
128            .or_default() += 1;
129        let weekday_key = format!("{}\t{}", example.current_app, example.weekday);
130        *temporal_transitions
131            .entry(weekday_key)
132            .or_default()
133            .entry(example.label_app.clone())
134            .or_default() += 1;
135    }
136
137    let global_popularity = counts_to_scores(&class_counts, &app_vocab);
138    let total_examples = examples.len() as f32;
139    let class_log_priors: Vec<f32> = class_counts
140        .iter()
141        .map(|count| ((*count as f32 + 1.0) / (total_examples + classes as f32)).ln())
142        .collect();
143    let unknown_feature_log_probs = class_counts
144        .iter()
145        .map(|count| (1.0 / (*count as f32 + 2.0)).ln())
146        .collect();
147    let feature_log_probs = feature_counts
148        .iter()
149        .map(|(feature, counts)| {
150            let probs = counts
151                .iter()
152                .enumerate()
153                .map(|(idx, count)| ((*count as f32 + 1.0) / (class_counts[idx] as f32 + 2.0)).ln())
154                .collect();
155            (feature.clone(), probs)
156        })
157        .collect();
158
159    let mut feature_order: Vec<(String, u32)> = feature_frequency.into_iter().collect();
160    feature_order.sort_by(|a, b| b.1.cmp(&a.1).then_with(|| a.0.cmp(&b.0)));
161    let trees = feature_order
162        .into_iter()
163        .take(MAX_TRAINED_FEATURES)
164        .filter_map(|(feature, _)| {
165            feature_counts.get(&feature).map(|counts| FeatureLiftTree {
166                feature_key: feature,
167                yes_scores: counts_to_log_lift_scores(counts, &class_counts, &app_vocab),
168            })
169        })
170        .collect();
171
172    Ok(NextAppModelArtifact {
173        schema_version: SCHEMA_VERSION.into(),
174        model_id: MODEL_NAME.into(),
175        dataset_id: dataset_id.to_string(),
176        trained_at_ms: 0,
177        config,
178        app_vocab,
179        global_popularity,
180        naive_bayes: NaiveBayesModel {
181            class_log_priors: class_log_priors.clone(),
182            unknown_feature_log_probs,
183            feature_log_probs,
184        },
185        markov: MarkovModel {
186            global_transitions: transition_scores(global_transitions),
187            user_transitions: transition_scores(user_transitions),
188            global_transitions_order2: transition_scores(global_transitions_order2),
189        },
190        feature_lift: FeatureLiftModel {
191            base_scores: class_log_priors,
192            trees,
193        },
194        user_frequency: transition_scores(user_frequency_counts),
195        user_recency,
196        markov_context: transition_scores(temporal_transitions),
197        ensemble_combiner: EnsembleCombiner::default(),
198        ensemble_logistic: LogisticRerankerModel::default(),
199        training_summary: TrainingSummary {
200            examples: examples.len(),
201            users: user_set.len(),
202            apps: classes,
203        },
204    })
205}
206
207fn training_features(example: &NextAppTrainingExample) -> Vec<String> {
208    feature_keys(&prediction_features_for_example(example))
209}
210
211fn counts_to_scores(counts: &[u32], app_vocab: &[String]) -> Vec<AppScore> {
212    let total: u32 = counts.iter().sum();
213    let denom = total as f32 + app_vocab.len() as f32;
214    let mut scores: Vec<AppScore> = app_vocab
215        .iter()
216        .cloned()
217        .zip(counts.iter())
218        .map(|(app, count)| AppScore {
219            app,
220            score: (*count as f32 + 1.0) / denom,
221        })
222        .collect();
223    scores.sort_by(|a, b| score_order(a.score, b.score).then_with(|| a.app.cmp(&b.app)));
224    scores
225}
226
227fn counts_to_log_lift_scores(
228    feature_counts: &[u32],
229    class_counts: &[u32],
230    app_vocab: &[String],
231) -> Vec<AppScore> {
232    let feature_total: u32 = feature_counts.iter().sum();
233    let class_total: u32 = class_counts.iter().sum();
234    let class_len = app_vocab.len() as f32;
235    let mut scores: Vec<AppScore> = app_vocab
236        .iter()
237        .enumerate()
238        .map(|(idx, app)| {
239            let p_label_given_feature =
240                (feature_counts[idx] as f32 + 1.0) / (feature_total as f32 + class_len);
241            let p_label = (class_counts[idx] as f32 + 1.0) / (class_total as f32 + class_len);
242            AppScore {
243                app: app.clone(),
244                score: (p_label_given_feature / p_label).ln(),
245            }
246        })
247        .collect();
248    scores.sort_by(|a, b| score_order(a.score, b.score).then_with(|| a.app.cmp(&b.app)));
249    scores
250}
251
252fn transition_scores(
253    transitions: BTreeMap<String, BTreeMap<String, u32>>,
254) -> BTreeMap<String, Vec<AppScore>> {
255    transitions
256        .into_iter()
257        .map(|(from, counts)| {
258            let total: u32 = counts.values().sum();
259            let mut scores: Vec<AppScore> = counts
260                .into_iter()
261                .map(|(app, count)| AppScore {
262                    app,
263                    score: count as f32 / total.max(1) as f32,
264                })
265                .collect();
266            scores.sort_by(|a, b| score_order(a.score, b.score).then_with(|| a.app.cmp(&b.app)));
267            (from, scores)
268        })
269        .collect()
270}
271
272pub(crate) fn user_transition_key(user_id: &str, current_app: &str) -> String {
273    format!("{user_id}\t{current_app}")
274}
275
276pub(crate) fn order2_key(prev_app: &str, current_app: &str) -> String {
277    format!("{prev_app}\t{current_app}")
278}
279
280/// The most recent history entry that is not the current app itself. Skipping
281/// repeated current-app records prevents the order-2 key from collapsing into
282/// `(current, current)`.
283pub(crate) fn previous_app(example: &NextAppTrainingExample) -> Option<&str> {
284    example
285        .history
286        .iter()
287        .rev()
288        .find(|app| app.as_str() != example.current_app)
289        .map(String::as_str)
290}