Skip to main content

uqa_execution/query/
model_training.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Model training invocation and scalar report materialization.
8
9use std::collections::BTreeMap;
10use uqa_core::{DocId, Value};
11use uqa_ml::{DeepLearnOutput, DeepModel, LearnOptions, TrainingSet};
12use uqa_sql::{
13    semantics::{
14        runtime_scalars::{deep_learn_arguments, deep_learn_source, DeepLearnSource},
15        source_filters::checked_integer_value,
16    },
17    SQLError, ScalarExpr,
18};
19use uqa_storage::{document_store::Document, StorageBackendResult};
20mod data;
21
22/// A retained table generation whose document-store read guard covers the ID scan.
23pub trait TrainingTable {
24    fn doc_ids(&self) -> StorageBackendResult<Vec<DocId>>;
25}
26
27/// Session-bound physical reads, including generated-column materialization.
28pub trait TrainingTables {
29    fn training_table(
30        &self,
31        name: &str,
32    ) -> StorageBackendResult<Option<Box<dyn TrainingTable + '_>>>;
33    fn training_documents(
34        &self,
35        table: &str,
36        doc_ids: &[DocId],
37        projection: &[String],
38    ) -> Result<BTreeMap<DocId, Document>, SQLError>;
39}
40
41/// Model persistence enters the caller's existing implicit transaction boundary.
42pub trait TrainedModels {
43    fn save_model(&self, name: &str, model: &DeepModel) -> Result<(), SQLError>;
44}
45
46pub struct ModelTrainingContext<'a> {
47    pub tables: &'a dyn TrainingTables,
48    pub models: &'a dyn TrainedModels,
49}
50
51impl ModelTrainingContext<'_> {
52    pub fn train(
53        &self,
54        name: &str,
55        training_set: &TrainingSet,
56        options: &LearnOptions,
57    ) -> Result<DeepLearnOutput, SQLError> {
58        let output = uqa_ml::deep_learn(training_set, options)
59            .map_err(|e| SQLError::Unsupported(format!("deep_learn: {e}")))?;
60        self.models.save_model(name, &output.model)?;
61        Ok(output)
62    }
63
64    pub fn train_json(
65        &self,
66        name: &str,
67        training_json: &str,
68        options: &LearnOptions,
69    ) -> Result<DeepLearnOutput, SQLError> {
70        let training_set: TrainingSet = serde_json::from_str(training_json).map_err(|e| {
71            SQLError::TypeMismatch(format!("invalid deep_learn training JSON: {e}"))
72        })?;
73        self.train(name, &training_set, options)
74    }
75
76    pub fn train_table(
77        &self,
78        name: &str,
79        table: &str,
80        options: &LearnOptions,
81    ) -> Result<DeepLearnOutput, SQLError> {
82        let training_set = data::training_set_from_table(self.tables, table, "features", "label")?;
83        self.train(name, &training_set, options)
84    }
85}
86
87pub fn run_deep_learn_projection(
88    models: &ModelTrainingContext<'_>,
89    args: &[ScalarExpr],
90    evaluate: &mut dyn FnMut(&ScalarExpr) -> Result<Value, SQLError>,
91) -> Result<Value, SQLError> {
92    let (model_name, training_source) = deep_learn_arguments(args, evaluate)?;
93    let output = match deep_learn_source(&training_source) {
94        DeepLearnSource::Json(source) => {
95            models.train_json(&model_name, source, &LearnOptions::default())?
96        }
97        DeepLearnSource::Table(source) => {
98            models.train_table(&model_name, source, &LearnOptions::default())?
99        }
100    };
101    let mut report = BTreeMap::new();
102    report.insert("model".into(), Value::Str(model_name));
103    report.insert(
104        "examples".into(),
105        checked_integer_value(output.report.examples, "training example count")?,
106    );
107    report.insert(
108        "feature_dimensions".into(),
109        checked_integer_value(output.report.feature_dimensions, "feature dimension count")?,
110    );
111    report.insert(
112        "class_count".into(),
113        checked_integer_value(output.report.class_count, "class count")?,
114    );
115    Ok(Value::Map(report))
116}
117
118#[cfg(test)]
119mod tests;