aios_agent/backends/predictive/
predictor.rs1use 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 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 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 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 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 pub(super) fn rank_popularity(&self, _features: &PredictionFeatures) -> Vec<AppScore> {
165 self.artifact.global_popularity.clone()
166 }
167
168 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}