Skip to main content

uqa_engine/
models.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7use super::{DeepLearnOutput, DeepModel, DocId, Engine, LearnOptions, SQLError, TrainingSet};
8
9const VECTOR_CALIBRATION_MODEL_PREFIX: &str = "vector_calibration_model::";
10
11fn vector_calibration_model_key(name: &str) -> Result<String, SQLError> {
12    if name.trim().is_empty() {
13        return Err(SQLError::TypeMismatch(
14            "vector calibration model name must not be empty".into(),
15        ));
16    }
17    Ok(format!("{VECTOR_CALIBRATION_MODEL_PREFIX}{name}"))
18}
19
20impl Engine {
21    pub fn save_model(&self, name: &str, model: &DeepModel) -> Result<(), SQLError> {
22        self.with_implicit_transaction(|engine| engine.save_model_inner(name, model))
23    }
24
25    fn save_model_inner(&self, name: &str, model: &DeepModel) -> Result<(), SQLError> {
26        let json = serde_json::to_string(model)
27            .map_err(|e| SQLError::Internal(format!("model serialise: {e}")))?;
28        let mut models = self.durable.models.write();
29        if let Some(catalog) = self.storage.catalog.as_ref() {
30            catalog
31                .save_model(name, &json)
32                .map_err(|e| SQLError::Internal(format!("catalog save_model: {e}")))?;
33        }
34        models.insert(name.to_string(), model.clone());
35        drop(models);
36        self.note_catalog_registry_changed();
37        Ok(())
38    }
39
40    pub fn load_model(&self, name: &str) -> Result<Option<DeepModel>, SQLError> {
41        self.with_direct_read_snapshot(|engine| engine.load_model_in_execution(name))
42    }
43
44    pub(crate) fn load_model_in_execution(
45        &self,
46        name: &str,
47    ) -> Result<Option<DeepModel>, SQLError> {
48        let Some(catalog) = self.storage.catalog.as_ref() else {
49            return Ok(self.durable.models.read().get(name).cloned());
50        };
51        let json = catalog
52            .load_model(name)
53            .map_err(|err| SQLError::Internal(format!("catalog load_model: {err}")))?;
54        let model = json
55            .as_deref()
56            .map(serde_json::from_str::<DeepModel>)
57            .transpose()
58            .map_err(|err| SQLError::Internal(format!("catalog model decode: {err}")))?;
59        let mut cache = self.durable.models.write();
60        match model.as_ref() {
61            Some(model) => {
62                cache.insert(name.to_string(), model.clone());
63            }
64            None => {
65                cache.remove(name);
66            }
67        }
68        Ok(model)
69    }
70
71    pub fn drop_model(&self, name: &str) -> Result<bool, SQLError> {
72        self.with_implicit_transaction(|engine| engine.drop_model_inner(name))
73    }
74
75    fn drop_model_inner(&self, name: &str) -> Result<bool, SQLError> {
76        if self.load_model_in_execution(name)?.is_none() {
77            return Ok(false);
78        }
79        let mut models = self.durable.models.write();
80        if let Some(catalog) = self.storage.catalog.as_ref() {
81            catalog
82                .drop_model(name)
83                .map_err(|err| SQLError::Internal(format!("catalog drop_model: {err}")))?;
84        }
85        models.remove(name);
86        drop(models);
87        self.note_catalog_registry_changed();
88        Ok(true)
89    }
90
91    /// compatibility alias for [`Engine::drop_model`].
92    pub fn delete_model(&self, name: &str) -> Result<bool, SQLError> {
93        self.drop_model(name)
94    }
95
96    /// Train an analytical deep model and persist it under `name`.
97    pub fn deep_learn(
98        &self,
99        name: &str,
100        training_set: &TrainingSet,
101        options: &LearnOptions,
102    ) -> Result<DeepLearnOutput, SQLError> {
103        self.model_training_context()
104            .train(name, training_set, options)
105    }
106
107    /// Parse a JSON [`TrainingSet`], train it, and persist the model.
108    pub fn deep_learn_json(
109        &self,
110        name: &str,
111        training_json: &str,
112        options: &LearnOptions,
113    ) -> Result<DeepLearnOutput, SQLError> {
114        self.model_training_context()
115            .train_json(name, training_json, options)
116    }
117
118    /// Train from a table containing `features` and `label` columns.
119    pub fn deep_learn_table(
120        &self,
121        name: &str,
122        table: &str,
123        options: &LearnOptions,
124    ) -> Result<DeepLearnOutput, SQLError> {
125        // Reading the training rows materializes virtual generated columns, which evaluates SQL expressions under the session's statement context.
126        let _statement_thread = self.statement_thread_context().enter();
127        self.model_training_context()
128            .train_table(name, table, options)
129    }
130
131    /// Persist Bayesian calibration parameters for a named signal. The
132    /// Parameters arrive serialized as JSON so callers can persist arbitrary
133    /// `(alpha, beta, base_rate, ...)` shapes without a fixed struct.
134    pub fn save_scoring_params(&self, name: &str, params_json: &str) -> Result<(), SQLError> {
135        self.with_implicit_transaction(|engine| engine.save_scoring_params_inner(name, params_json))
136    }
137
138    pub(crate) fn save_scoring_params_inner(
139        &self,
140        name: &str,
141        params_json: &str,
142    ) -> Result<(), SQLError> {
143        // Physical retrieval workers publish through this adapter without reentering the public mutation scope.
144        if self.current_transaction_is_read_only() {
145            return Err(SQLError::Routine {
146                sqlstate: "25006".into(),
147                message: "cannot save scoring parameters in a read-only transaction".into(),
148            });
149        }
150        self.lock_scoring_parameter_write(name)?;
151        let mut scoring_params = self.durable.scoring_params.write();
152        if let Some(catalog) = self.storage.catalog.as_ref() {
153            catalog
154                .save_scoring_params(name, params_json)
155                .map_err(|e| SQLError::Internal(format!("catalog save_scoring_params: {e}")))?;
156        }
157        scoring_params.insert(name.to_string(), params_json.to_string());
158        drop(scoring_params);
159        self.note_catalog_registry_changed();
160        Ok(())
161    }
162
163    /// Load persisted scoring parameters for a single signal. Falls back to
164    /// the in-memory cache when the engine is not catalog-backed.
165    pub fn load_scoring_params(&self, name: &str) -> Result<Option<String>, SQLError> {
166        let Some(catalog) = self.storage.catalog.as_ref() else {
167            return Ok(self.durable.scoring_params.read().get(name).cloned());
168        };
169        let value = catalog
170            .load_scoring_params(name)
171            .map_err(|err| SQLError::Internal(format!("catalog load_scoring_params: {err}")))?;
172        let mut cache = self.durable.scoring_params.write();
173        match value.as_ref() {
174            Some(json) => {
175                cache.insert(name.to_string(), json.clone());
176            }
177            None => {
178                cache.remove(name);
179            }
180        }
181        Ok(value)
182    }
183
184    /// Fallible scoring-parameter read. Persistent sessions consult their
185    /// own catalog connection instead of trusting an engine-local snapshot;
186    /// this preserves transaction isolation and makes commits from sibling
187    /// sessions visible without reopening the engine.
188    pub fn try_load_scoring_params(&self, name: &str) -> Result<Option<String>, SQLError> {
189        self.load_scoring_params(name)
190    }
191
192    /// Snapshot every persisted `(name, params_json)` pair.
193    pub fn load_all_scoring_params(&self) -> Result<Vec<(String, String)>, SQLError> {
194        let mut out = if let Some(catalog) = self.storage.catalog.as_ref() {
195            let rows = catalog.load_all_scoring_params().map_err(|err| {
196                SQLError::Internal(format!("catalog load_all_scoring_params: {err}"))
197            })?;
198            let mut cache = self.durable.scoring_params.write();
199            cache.clear();
200            cache.extend(rows.iter().cloned());
201            rows
202        } else {
203            self.durable
204                .scoring_params
205                .read()
206                .iter()
207                .map(|(name, json)| (name.clone(), json.clone()))
208                .collect()
209        };
210        out.sort_by(|a, b| a.0.cmp(&b.0));
211        Ok(out)
212    }
213
214    /// Drop persisted scoring parameters for a single signal. Returns
215    /// `true` when something was removed.
216    pub fn drop_scoring_params(&self, name: &str) -> Result<bool, SQLError> {
217        self.with_implicit_transaction(|engine| engine.drop_scoring_params_inner(name))
218    }
219
220    /// Persist a typed vector-calibration model, including the corpus, index,
221    /// embedding-model, candidate-K, and version provenance that constrains
222    /// its safe reuse.
223    pub fn save_vector_calibration_model(
224        &self,
225        name: &str,
226        model: &uqa_scoring::VectorCalibrationModel,
227    ) -> Result<(), SQLError> {
228        let key = vector_calibration_model_key(name)?;
229        let json = model
230            .to_json()
231            .map_err(|error| SQLError::TypeMismatch(error.to_string()))?;
232        self.save_scoring_params(&key, &json)
233    }
234
235    /// Load and validate a persisted vector-calibration model. Unsupported
236    /// schema versions and invalid numeric parameters are errors rather than
237    /// silently falling back to query-pool calibration.
238    pub fn load_vector_calibration_model(
239        &self,
240        name: &str,
241    ) -> Result<Option<uqa_scoring::VectorCalibrationModel>, SQLError> {
242        let key = vector_calibration_model_key(name)?;
243        self.load_scoring_params(&key)?
244            .as_deref()
245            .map(uqa_scoring::VectorCalibrationModel::from_json)
246            .transpose()
247            .map_err(|error| SQLError::TypeMismatch(error.to_string()))
248    }
249
250    pub fn drop_vector_calibration_model(&self, name: &str) -> Result<bool, SQLError> {
251        let key = vector_calibration_model_key(name)?;
252        self.drop_scoring_params(&key)
253    }
254
255    fn drop_scoring_params_inner(&self, name: &str) -> Result<bool, SQLError> {
256        self.lock_scoring_parameter_write(name)?;
257        if self.load_scoring_params(name)?.is_none() {
258            return Ok(false);
259        }
260        let mut scoring_params = self.durable.scoring_params.write();
261        if let Some(catalog) = self.storage.catalog.as_ref() {
262            catalog
263                .drop_scoring_params(name)
264                .map_err(|err| SQLError::Internal(format!("catalog drop_scoring_params: {err}")))?;
265        }
266        scoring_params.remove(name);
267        drop(scoring_params);
268        self.note_catalog_registry_changed();
269        Ok(true)
270    }
271
272    /// Run saved-model inference through the shared operator optimizer and
273    /// plan executor. A missing model retains the public API's `None`
274    /// contract; the physical driver only receives known models.
275    pub fn deep_predict(&self, name: &str) -> Result<Option<Vec<(DocId, f64)>>, SQLError> {
276        self.with_direct_read_snapshot(|engine| {
277            if engine.load_model_in_execution(name)?.is_none() {
278                return Ok(None);
279            }
280            let tree = uqa_operators::OperatorTree::DeepPredict {
281                model: name.to_string(),
282            };
283            let entries =
284                crate::operator_tree_bridge::execute_scored_tree(engine, "", "", &[], &tree)?;
285            Ok(Some(
286                entries
287                    .into_iter()
288                    .map(|entry| (entry.doc_id, entry.score))
289                    .collect(),
290            ))
291        })
292    }
293
294    pub fn deep_predict_features(
295        &self,
296        name: &str,
297        examples: &[(DocId, Vec<f64>)],
298    ) -> Result<Vec<(DocId, f64)>, SQLError> {
299        self.with_direct_read_snapshot(|engine| {
300            let model = engine
301                .load_model_in_execution(name)?
302                .ok_or_else(|| SQLError::Unsupported(format!("unknown model {name:?}")))?;
303            let (scores, _) = model
304                .predict_features(examples)
305                .map_err(|e| SQLError::Unsupported(format!("deep_predict: {e}")))?;
306            Ok(scores)
307        })
308    }
309}