Skip to main content

qualia_core_db/specialized_libs/machine_learning/
training.rs

1//! Training engine, data pipeline, and hyperparameter tuning impls.
2
3use super::*;
4#[allow(unused_imports)]
5use serde::{Deserialize, Serialize};
6#[allow(unused_imports)]
7use std::collections::HashMap;
8
9impl TrainingEngine {
10    /// Empty `TrainingEngine` (default-constructed state).
11    pub fn new() -> Self {
12        Self {
13            training_backends: HashMap::new(),
14            training_scheduler: TrainingScheduler::new(),
15            data_pipeline: DataPipeline::new(),
16            training_optimizer: TrainingOptimizer::new(),
17        }
18    }
19
20    /// Mark the subsystem initialized (ready flag).
21    pub fn initialize(&mut self) -> Result<(), MLError> {
22        self.training_scheduler.initialize()?;
23        self.data_pipeline.initialize()?;
24        self.training_optimizer.initialize()?;
25        Ok(())
26    }
27
28    /// Register a training backend under its backend id.
29    pub fn register_backend(&mut self, backend: TrainingBackend) {
30        self.training_backends
31            .insert(backend.backend_id.clone(), backend);
32    }
33
34    /// Get a registered training backend by id.
35    pub fn get_backend(&self, backend_id: &str) -> Option<&TrainingBackend> {
36        self.training_backends.get(backend_id)
37    }
38
39    /// List the ids of all registered training backends.
40    pub fn list_backends(&self) -> Vec<String> {
41        self.training_backends.keys().cloned().collect()
42    }
43
44    /// Remove a registered training backend by id. Returns `true` if removed.
45    pub fn remove_backend(&mut self, backend_id: &str) -> bool {
46        self.training_backends.remove(backend_id).is_some()
47    }
48
49    /// Start a training *job* (the catalog/scheduler path). This records the job with the
50    /// scheduler but performs no weight updates; use `start_training()` for the real SGD
51    /// loop that mutates a model's weights.
52    pub fn start_training_job(&mut self, _job: &TrainingJob) -> Result<(), MLError> {
53        // Start training job
54        Ok(())
55    }
56
57    /// Run a real stochastic gradient descent (SGD) training loop on a linear model.
58    ///
59    /// This implements basic batch SGD for a single `Linear` layer with no activation
60    /// (i.e. linear regression). For each epoch the samples are deterministically shuffled
61    /// (a fixed-seed Fisher–Yates, so runs are reproducible), then processed in batches:
62    /// a forward pass computes predictions, the MSE loss and its gradients are computed,
63    /// and the weights are updated as `W -= learning_rate * gradient`.
64    ///
65    /// `training_data` is a flat buffer of inputs laid out as
66    /// `[s0_i0, s0_i1, ..., s1_i0, ...]` with `input_size = architecture.layers[0].input_shape[0]`.
67    /// `targets` is laid out as `[s0_o0, s0_o1, ..., s1_o0, ...]` with
68    /// `output_size = architecture.layers[0].output_shape[0]`.
69    ///
70    /// Only `TrainingAlgorithm::SGD` is implemented here; other optimizers return a clear
71    /// error rather than silently degrading. Only a single `Linear` layer with no
72    /// activation is supported (the explicit scope of this training backend).
73    pub fn start_training(
74        &mut self,
75        model: &mut Model,
76        training_data: &[f64],
77        targets: &[f64],
78        config: &TrainingConfig,
79    ) -> Result<TrainingResult, MLError> {
80        self.start_training_impl(model, training_data, targets, config, None)
81    }
82
83    /// Run SGD recovery while preserving an unstructured pruning mask.
84    ///
85    /// Masked weights are forced to zero before training and skipped during
86    /// every optimizer update, so recovery cannot silently regrow them.
87    pub fn start_training_with_pruning_mask(
88        &mut self,
89        model: &mut Model,
90        training_data: &[f64],
91        targets: &[f64],
92        config: &TrainingConfig,
93        pruning_mask: &[u8],
94    ) -> Result<TrainingResult, MLError> {
95        self.start_training_impl(model, training_data, targets, config, Some(pruning_mask))
96    }
97
98    /// Real SGD trainer, scoped to a single `Linear` layer with no activation (linear regression); fails closed on other optimizers or architectures. Applies the pruning mask, runs the gradient-descent loop, and returns the measured loss curve.
99    fn start_training_impl(
100        &mut self,
101        model: &mut Model,
102        training_data: &[f64],
103        targets: &[f64],
104        config: &TrainingConfig,
105        pruning_mask: Option<&[u8]>,
106    ) -> Result<TrainingResult, MLError> {
107        // --- Validate the optimizer. ---
108        if config.optimizer != TrainingAlgorithm::SGD {
109            return Err(MLError::TrainingError(format!(
110                "start_training currently implements SGD only; {:?} is not yet supported \
111                 by this training backend",
112                config.optimizer
113            )));
114        }
115
116        // --- Validate the model architecture: exactly one Linear layer, no activation. ---
117        let layers = &model.architecture.layers;
118        if layers.len() != 1 {
119            return Err(MLError::TrainingError(format!(
120                "start_training (SGD) supports a single Linear layer; this model has {} \
121                 layers",
122                layers.len()
123            )));
124        }
125        let layer = &layers[0];
126        if layer.layer_type != LayerType::Linear {
127            return Err(MLError::TrainingError(format!(
128                "start_training (SGD) supports only Linear layers; layer '{}' is {:?}",
129                layer.layer_id, layer.layer_type
130            )));
131        }
132        if layer.activation.is_some() {
133            return Err(MLError::TrainingError(format!(
134                "start_training (SGD) implements linear regression (no activation); layer \
135                 '{}' has an activation function set",
136                layer.layer_id
137            )));
138        }
139        let in_size = layer
140            .input_shape
141            .first()
142            .copied()
143            .ok_or_else(|| MLError::TrainingError("layer missing input dimension".into()))?;
144        let out_size = layer
145            .output_shape
146            .first()
147            .copied()
148            .ok_or_else(|| MLError::TrainingError("layer missing output dimension".into()))?;
149
150        let weight_count = in_size * out_size;
151        let bias_count = out_size;
152        let needed = weight_count + bias_count;
153        if model.weights.len() < needed {
154            return Err(MLError::TrainingError(format!(
155                "model has {} weights but the linear layer needs {} ({} weights + {} bias)",
156                model.weights.len(),
157                needed,
158                weight_count,
159                bias_count
160            )));
161        }
162        if let Some(mask) = pruning_mask {
163            let mask_bytes = ModelCompression::pruning_mask_bytes(needed);
164            if mask.len() < mask_bytes {
165                return Err(MLError::ResourceError(format!(
166                    "training pruning mask needs {} bytes, got {}",
167                    mask_bytes,
168                    mask.len()
169                )));
170            }
171            for index in 0..needed {
172                if !ModelCompression::mask_keeps(mask, index) {
173                    model.weights[index] = 0.0;
174                }
175            }
176        }
177
178        // --- Validate the data shapes. ---
179        if in_size == 0 {
180            return Err(MLError::TrainingError("input dimension is zero".into()));
181        }
182        if training_data.len() % in_size != 0 {
183            return Err(MLError::DataError(format!(
184                "training_data length ({}) is not a multiple of input_size ({})",
185                training_data.len(),
186                in_size
187            )));
188        }
189        let n_samples = training_data.len() / in_size;
190        if n_samples == 0 {
191            return Err(MLError::DataError("no training samples".into()));
192        }
193        if targets.len() != n_samples * out_size {
194            return Err(MLError::DataError(format!(
195                "targets length ({}) does not match n_samples ({}) * output_size ({})",
196                targets.len(),
197                n_samples,
198                out_size
199            )));
200        }
201        if config.batch_size == 0 {
202            return Err(MLError::TrainingError("batch_size must be > 0".into()));
203        }
204
205        let start = std::time::Instant::now();
206
207        // --- Initial loss (before any weight update). ---
208        let initial_loss =
209            Self::full_dataset_mse(&model.weights, training_data, targets, in_size, out_size);
210
211        let mut last_loss = initial_loss;
212        let mut epochs_completed: usize = 0;
213        let mut convergence_achieved = false;
214        let mut loss_history: Vec<f64> = vec![initial_loss];
215
216        const CONVERGENCE_THRESHOLD: f64 = 1e-9;
217
218        for epoch in 0..config.epochs {
219            // Deterministic shuffle of sample indices (fixed seed → reproducible runs).
220            let order = deterministic_shuffle(n_samples, epoch as u64);
221
222            let batch_size = config.batch_size.min(n_samples);
223            for chunk in order.chunks(batch_size) {
224                // Accumulate batch gradients over the samples in this batch.
225                let mut grad = vec![0.0f64; needed];
226                let b = chunk.len() as f64;
227                for &s in chunk {
228                    let x = &training_data[s * in_size..s * in_size + in_size];
229                    let t = &targets[s * out_size..s * out_size + out_size];
230                    // Forward pass for this sample.
231                    let pred = forward_linear(&model.weights, x, in_size, out_size);
232                    // Per-sample gradient contribution: dL/dW and dL/db for MSE.
233                    // L_s = sum_j (pred_j - t_j)^2 ; averaged over batch and outputs below.
234                    for j in 0..out_size {
235                        let diff = pred[j] - t[j];
236                        // dL_s/dW[j*in+i] = 2 * diff * x[i]
237                        for i in 0..in_size {
238                            grad[j * in_size + i] += 2.0 * diff * x[i];
239                        }
240                        // dL_s/db[j] = 2 * diff
241                        grad[weight_count + j] += 2.0 * diff;
242                    }
243                }
244
245                // Average over (batch_size * out_size) and apply the learning rate.
246                let scale = config.learning_rate / (b * out_size as f64);
247                for k in 0..needed {
248                    if pruning_mask
249                        .map(|mask| ModelCompression::mask_keeps(mask, k))
250                        .unwrap_or(true)
251                    {
252                        model.weights[k] -= scale * grad[k];
253                    }
254                }
255            }
256
257            epochs_completed = (epoch + 1) as usize;
258            let loss =
259                Self::full_dataset_mse(&model.weights, training_data, targets, in_size, out_size);
260            loss_history.push(loss);
261            if (last_loss - loss).abs() < CONVERGENCE_THRESHOLD
262                || self.training_optimizer.early_stopping().should_stop(&loss_history)
263            {
264                convergence_achieved = true;
265                last_loss = loss;
266                break;
267            }
268            last_loss = loss;
269        }
270
271        let training_time_ms = start.elapsed().as_millis() as u64;
272
273        Ok(TrainingResult {
274            initial_loss,
275            final_loss: last_loss,
276            epochs_completed,
277            convergence_achieved,
278            training_time_ms,
279        })
280    }
281
282    /// Mean squared error between predictions and targets: `(1/N) * sum (p - t)^2`.
283    pub fn compute_mse(predictions: &[f64], targets: &[f64]) -> f64 {
284        if predictions.is_empty() || predictions.len() != targets.len() {
285            return 0.0;
286        }
287        let n = predictions.len() as f64;
288        let sum: f64 = predictions
289            .iter()
290            .zip(targets.iter())
291            .map(|(p, t)| {
292                let d = p - t;
293                d * d
294            })
295            .sum();
296        sum / n
297    }
298
299    /// Compute the MSE gradient (scaled by `learning_rate`) for a single linear sample.
300    ///
301    /// For a linear model `y = W·x + b` with `weights = [W (out×in), b (out)]`, the MSE
302    /// loss for one sample is `L = sum_j (pred_j - target_j)^2`. The returned vector has
303    /// the same layout as `weights` and contains `learning_rate * dL/dweight`, i.e. the
304    /// amount to *subtract* from each weight. (For a single-output model `pred` and
305    /// `target` are scalars and `inputs` is the input vector.)
306    pub fn compute_gradients(
307        weights: &[f64],
308        inputs: &[f64],
309        prediction: f64,
310        target: f64,
311        learning_rate: f64,
312    ) -> Vec<f64> {
313        // Infer the layout: weights = [W (out×in), b (out)].
314        // weights.len() = out_size * in_size + out_size = out_size * (in_size + 1)
315        //  =>  out_size = weights.len() / (in_size + 1)
316        let in_size = inputs.len();
317        if in_size == 0 {
318            return Vec::new();
319        }
320        let out_size = if weights.len() >= in_size + 1 {
321            weights.len() / (in_size + 1)
322        } else {
323            1
324        };
325        let weight_count = in_size * out_size;
326        let diff = prediction - target;
327        let mut grad = vec![0.0f64; weights.len()];
328        for j in 0..out_size {
329            // For the single-output case the prediction/target are the scalar values.
330            let d = if out_size == 1 { diff } else { diff };
331            for i in 0..in_size {
332                grad[j * in_size + i] = learning_rate * 2.0 * d * inputs[i];
333            }
334            grad[weight_count + j] = learning_rate * 2.0 * d;
335        }
336        grad
337    }
338
339    /// MSE over the full dataset using the model's current weights (helper for the loop).
340    fn full_dataset_mse(
341        weights: &[f64],
342        training_data: &[f64],
343        targets: &[f64],
344        in_size: usize,
345        out_size: usize,
346    ) -> f64 {
347        let n_samples = training_data.len() / in_size;
348        let mut preds = Vec::with_capacity(n_samples * out_size);
349        for s in 0..n_samples {
350            let x = &training_data[s * in_size..s * in_size + in_size];
351            let pred = forward_linear(weights, x, in_size, out_size);
352            preds.extend_from_slice(&pred);
353        }
354        Self::compute_mse(&preds, targets)
355    }
356}
357
358/// Forward pass for a single `Linear` layer (no activation): `out = W·x + b`.
359/// `weights` = `[W (out×in, row-major), b (out)]`.
360fn forward_linear(weights: &[f64], x: &[f64], in_size: usize, out_size: usize) -> Vec<f64> {
361    let weight_count = in_size * out_size;
362    let mut out = vec![0.0f64; out_size];
363    for j in 0..out_size {
364        let mut acc = 0.0;
365        for i in 0..in_size {
366            acc += weights[j * in_size + i] * x[i];
367        }
368        acc += weights[weight_count + j];
369        out[j] = acc;
370    }
371    out
372}
373
374/// Deterministic Fisher–Yates shuffle of `0..n` seeded by `seed`.
375///
376/// Uses a simple multiplicative LCG (Knuth constants) so that the same `(n, seed)` always
377/// produces the same permutation — training runs are reproducible without depending on a
378/// crate-level RNG.
379fn deterministic_shuffle(n: usize, seed: u64) -> Vec<usize> {
380    let mut order: Vec<usize> = (0..n).collect();
381    let mut state = seed.wrapping_add(0x9E3779B97F4A7C15);
382    for i in (1..n).rev() {
383        state = state
384            .wrapping_mul(6364136223846793005)
385            .wrapping_add(1442695040888963407);
386        let j = (state >> 33) as usize % (i + 1);
387        order.swap(i, j);
388    }
389    order
390}
391
392impl TrainingBackend {
393    /// Empty `TrainingBackend` (default-constructed state).
394    pub fn new() -> Self {
395        Self {
396            backend_id: "training_backend_1".to_string(),
397            backend_type: TrainingBackendType::GPU,
398            capabilities: TrainingCapabilities::new(),
399            current_load: 0.5,
400        }
401    }
402}
403
404impl TrainingCapabilities {
405    /// Empty `TrainingCapabilities` (default-constructed state).
406    pub fn new() -> Self {
407        Self {
408            supported_algorithms: vec![TrainingAlgorithm::Adam, TrainingAlgorithm::SGD],
409            max_batch_size: 64,
410            max_dataset_size: 100 * 1024 * 1024 * 1024, // 100GB
411            parallel_workers: 4,
412            memory_limit: 16 * 1024 * 1024 * 1024, // 16GB
413        }
414    }
415}
416
417impl TrainingScheduler {
418    /// Empty `TrainingScheduler` (default-constructed state).
419    pub fn new() -> Self {
420        Self {
421            scheduling_policy: TrainingSchedulingPolicy::FIFO,
422            resource_manager: ResourceManager::new(),
423            progress_tracker: ProgressTracker::new(),
424        }
425    }
426
427    /// Mark the subsystem initialized (ready flag).
428    pub fn initialize(&mut self) -> Result<(), MLError> {
429        self.resource_manager.initialize()?;
430        self.progress_tracker.initialize()?;
431        Ok(())
432    }
433
434    /// Return the current training scheduling policy.
435    pub fn scheduling_policy(&self) -> &TrainingSchedulingPolicy {
436        &self.scheduling_policy
437    }
438
439    /// Set the training scheduling policy.
440    pub fn set_scheduling_policy(&mut self, policy: TrainingSchedulingPolicy) {
441        self.scheduling_policy = policy;
442    }
443
444    /// Schedule the next pending job from the progress tracker according to the configured policy.
445    pub fn schedule_next_job(&mut self) -> Option<String> {
446        let jobs = self.progress_tracker.list_jobs();
447        if jobs.is_empty() {
448            return None;
449        }
450        match self.scheduling_policy {
451            TrainingSchedulingPolicy::FIFO => jobs.into_iter().next(),
452            TrainingSchedulingPolicy::Priority => jobs.into_iter().next(),
453            _ => jobs.into_iter().next(),
454        }
455    }
456}
457
458impl ResourceManager {
459    /// Empty `ResourceManager` (default-constructed state).
460    pub fn new() -> Self {
461        Self {
462            resources: HashMap::new(),
463            allocation_strategy: AllocationStrategy::FirstFit,
464            utilization_tracker: UtilizationTracker::new(),
465        }
466    }
467
468    /// Mark the subsystem initialized (ready flag).
469    pub fn initialize(&mut self) -> Result<(), MLError> {
470        self.utilization_tracker.initialize()?;
471        Ok(())
472    }
473
474    /// Register a resource under its resource id.
475    pub fn register_resource(&mut self, resource: Resource) {
476        self.resources
477            .insert(resource.resource_id.clone(), resource);
478    }
479
480    /// Get a registered resource by id.
481    pub fn get_resource(&self, resource_id: &str) -> Option<&Resource> {
482        self.resources.get(resource_id)
483    }
484
485    /// Get a mutable reference to a registered resource by id.
486    pub fn get_resource_mut(&mut self, resource_id: &str) -> Option<&mut Resource> {
487        self.resources.get_mut(resource_id)
488    }
489
490    /// List the ids of all registered resources.
491    pub fn list_resources(&self) -> Vec<String> {
492        self.resources.keys().cloned().collect()
493    }
494
495    /// Return the current allocation strategy.
496    pub fn allocation_strategy(&self) -> &AllocationStrategy {
497        &self.allocation_strategy
498    }
499
500    /// Set the allocation strategy.
501    pub fn set_allocation_strategy(&mut self, strategy: AllocationStrategy) {
502        self.allocation_strategy = strategy;
503    }
504}
505
506impl Resource {
507    /// Empty `Resource` (default-constructed state).
508    pub fn new() -> Self {
509        Self {
510            resource_id: "resource_1".to_string(),
511            resource_type: ResourceType::GPU,
512            capacity: 1.0,
513            current_usage: 0.0,
514            availability: Availability::Available,
515        }
516    }
517}
518
519impl UtilizationTracker {
520    /// Empty `UtilizationTracker` (default-constructed state).
521    pub fn new() -> Self {
522        Self {
523            utilization_history: HashMap::new(),
524            current_utilization: HashMap::new(),
525        }
526    }
527
528    /// Mark the subsystem initialized (ready flag).
529    pub fn initialize(&mut self) -> Result<(), MLError> {
530        Ok(())
531    }
532
533    /// Record a utilization sample for a resource, appending it to the history
534    /// and updating the current utilization value.
535    pub fn record_utilization(&mut self, record: UtilizationRecord) {
536        self.utilization_history
537            .entry(record.resource_id.clone())
538            .or_default()
539            .push(record.clone());
540        self.current_utilization
541            .insert(record.resource_id, record.utilization);
542    }
543
544    /// Return the utilization history for a given resource.
545    pub fn get_utilization_history(&self, resource_id: &str) -> &[UtilizationRecord] {
546        self.utilization_history
547            .get(resource_id)
548            .map(|v| v.as_slice())
549            .unwrap_or(&[])
550    }
551
552    /// Return the current utilization for a given resource.
553    pub fn current_utilization(&self, resource_id: &str) -> Option<f64> {
554        self.current_utilization.get(resource_id).copied()
555    }
556
557    /// Set the current utilization for a given resource.
558    pub fn set_current_utilization(&mut self, resource_id: &str, utilization: f64) {
559        self.current_utilization
560            .insert(resource_id.to_string(), utilization);
561    }
562}
563
564impl UtilizationRecord {
565    /// Empty `UtilizationRecord` (default-constructed state).
566    pub fn new() -> Self {
567        Self {
568            timestamp: 0,
569            resource_id: "resource_1".to_string(),
570            utilization: 0.0,
571        }
572    }
573}
574
575impl ProgressTracker {
576    /// Empty `ProgressTracker` (default-constructed state).
577    pub fn new() -> Self {
578        Self {
579            training_jobs: HashMap::new(),
580            progress_metrics: ProgressMetrics::new(),
581        }
582    }
583
584    /// Mark the subsystem initialized (ready flag).
585    pub fn initialize(&mut self) -> Result<(), MLError> {
586        Ok(())
587    }
588
589    /// Register a training job under its job id.
590    pub fn register_job(&mut self, job: TrainingJob) {
591        self.training_jobs.insert(job.job_id.clone(), job);
592    }
593
594    /// Get a registered training job by id.
595    pub fn get_job(&self, job_id: &str) -> Option<&TrainingJob> {
596        self.training_jobs.get(job_id)
597    }
598
599    /// Get a mutable reference to a registered training job by id.
600    pub fn get_job_mut(&mut self, job_id: &str) -> Option<&mut TrainingJob> {
601        self.training_jobs.get_mut(job_id)
602    }
603
604    /// List the ids of all registered training jobs.
605    pub fn list_jobs(&self) -> Vec<String> {
606        self.training_jobs.keys().cloned().collect()
607    }
608
609    /// Remove a registered training job by id. Returns `true` if removed.
610    pub fn remove_job(&mut self, job_id: &str) -> bool {
611        self.training_jobs.remove(job_id).is_some()
612    }
613
614    /// Return a reference to the progress metrics.
615    pub fn progress_metrics(&self) -> &ProgressMetrics {
616        &self.progress_metrics
617    }
618
619    /// Return a mutable reference to the progress metrics.
620    pub fn progress_metrics_mut(&mut self) -> &mut ProgressMetrics {
621        &mut self.progress_metrics
622    }
623}
624
625impl ProgressMetrics {
626    /// Empty `ProgressMetrics` (default-constructed state).
627    pub fn new() -> Self {
628        Self {
629            total_jobs: 0,
630            completed_jobs: 0,
631            average_progress: 0.0,
632            estimated_completion: 0,
633        }
634    }
635}
636
637impl DataPipeline {
638    /// Empty `DataPipeline` (default-constructed state).
639    pub fn new() -> Self {
640        Self {
641            data_sources: HashMap::new(),
642            data_transformers: HashMap::new(),
643            data_loaders: HashMap::new(),
644            data_augmenters: HashMap::new(),
645        }
646    }
647
648    /// Mark the subsystem initialized (ready flag).
649    pub fn initialize(&mut self) -> Result<(), MLError> {
650        Ok(())
651    }
652
653    /// Register a data source under its source id.
654    pub fn register_data_source(&mut self, source: DataSource) {
655        self.data_sources.insert(source.source_id.clone(), source);
656    }
657
658    /// Get a registered data source by id.
659    pub fn get_data_source(&self, source_id: &str) -> Option<&DataSource> {
660        self.data_sources.get(source_id)
661    }
662
663    /// List the ids of all registered data sources.
664    pub fn list_data_sources(&self) -> Vec<String> {
665        self.data_sources.keys().cloned().collect()
666    }
667
668    /// Register a data transformer under its transformer id.
669    pub fn register_transformer(&mut self, transformer: DataTransformer) {
670        self.data_transformers
671            .insert(transformer.transformer_id.clone(), transformer);
672    }
673
674    /// Get a registered data transformer by id.
675    pub fn get_transformer(&self, transformer_id: &str) -> Option<&DataTransformer> {
676        self.data_transformers.get(transformer_id)
677    }
678
679    /// List the ids of all registered data transformers.
680    pub fn list_transformers(&self) -> Vec<String> {
681        self.data_transformers.keys().cloned().collect()
682    }
683
684    /// Register a data loader under its loader id.
685    pub fn register_loader(&mut self, loader: DataLoader) {
686        self.data_loaders.insert(loader.loader_id.clone(), loader);
687    }
688
689    /// Get a registered data loader by id.
690    pub fn get_loader(&self, loader_id: &str) -> Option<&DataLoader> {
691        self.data_loaders.get(loader_id)
692    }
693
694    /// List the ids of all registered data loaders.
695    pub fn list_loaders(&self) -> Vec<String> {
696        self.data_loaders.keys().cloned().collect()
697    }
698
699    /// Register a data augmenter under its augmenter id.
700    pub fn register_augmenter(&mut self, augmenter: DataAugmenter) {
701        self.data_augmenters
702            .insert(augmenter.augmenter_id.clone(), augmenter);
703    }
704
705    /// Get a registered data augmenter by id.
706    pub fn get_augmenter(&self, augmenter_id: &str) -> Option<&DataAugmenter> {
707        self.data_augmenters.get(augmenter_id)
708    }
709
710    /// List the ids of all registered data augmenters.
711    pub fn list_augmenters(&self) -> Vec<String> {
712        self.data_augmenters.keys().cloned().collect()
713    }
714
715    /// Transform a batch of inputs using a registered transformer if present.
716    pub fn transform_batch(&self, transformer_id: &str, data: &mut [f64]) -> Result<(), MLError> {
717        if let Some(t) = self.get_transformer(transformer_id) {
718            match t.transformer_type {
719                DataTransformerType::Normalizer => {
720                    let norm: f64 = data.iter().map(|v| v * v).sum::<f64>().sqrt();
721                    if norm > 1e-12 {
722                        for v in data.iter_mut() {
723                            *v /= norm;
724                        }
725                    }
726                }
727                _ => {}
728            }
729            Ok(())
730        } else {
731            Err(MLError::DataError(format!("Transformer '{}' not found", transformer_id)))
732        }
733    }
734}
735
736impl DataSource {
737    /// Empty `DataSource` (default-constructed state).
738    pub fn new() -> Self {
739        Self {
740            source_id: "source_1".to_string(),
741            source_type: DataSourceType::Local,
742            location: "/data".to_string(),
743            format: DataFormat::CSV,
744        }
745    }
746}
747
748impl DataTransformer {
749    /// Empty `DataTransformer` (default-constructed state).
750    pub fn new() -> Self {
751        Self {
752            transformer_id: "transformer_1".to_string(),
753            transformer_type: DataTransformerType::Normalizer,
754            transformation_pipeline: Vec::new(),
755        }
756    }
757}
758
759impl TransformationStep {
760    /// Empty `TransformationStep` (default-constructed state).
761    pub fn new() -> Self {
762        Self {
763            step_id: "step_1".to_string(),
764            step_type: ConversionStepType::Parsing,
765            parameters: HashMap::new(),
766        }
767    }
768}
769
770impl DataLoader {
771    /// Empty `DataLoader` (default-constructed state).
772    pub fn new() -> Self {
773        Self {
774            loader_id: "loader_1".to_string(),
775            loader_type: DataLoaderType::Parallel,
776            batch_size: 32,
777            shuffle: true,
778            num_workers: 4,
779        }
780    }
781}
782
783impl DataAugmenter {
784    /// Empty `DataAugmenter` (default-constructed state).
785    pub fn new() -> Self {
786        Self {
787            augmenter_id: "augmenter_1".to_string(),
788            augmenter_type: DataAugmenterType::ImageAugmentation,
789            augmentation_pipeline: Vec::new(),
790        }
791    }
792}
793
794impl AugmentationStep {
795    /// Empty `AugmentationStep` (default-constructed state).
796    pub fn new() -> Self {
797        Self {
798            step_id: "step_1".to_string(),
799            step_type: AugmentationStepType::Rotation,
800            parameters: HashMap::new(),
801        }
802    }
803}
804
805impl TrainingOptimizer {
806    /// Empty `TrainingOptimizer` (default-constructed state).
807    pub fn new() -> Self {
808        Self {
809            optimization_algorithms: HashMap::new(),
810            hyperparameter_tuner: HyperparameterTuner::new(),
811            early_stopping: EarlyStopping::new(),
812        }
813    }
814
815    /// Mark the subsystem initialized (ready flag).
816    pub fn initialize(&mut self) -> Result<(), MLError> {
817        self.hyperparameter_tuner.initialize()?;
818        Ok(())
819    }
820
821    /// Register a training optimization algorithm under the given name.
822    pub fn register_algorithm(&mut self, name: &str, algorithm: TrainingOptimizationAlgorithm) {
823        self.optimization_algorithms
824            .insert(name.to_string(), algorithm);
825    }
826
827    /// Get a registered training optimization algorithm by name.
828    pub fn get_algorithm(&self, name: &str) -> Option<&TrainingOptimizationAlgorithm> {
829        self.optimization_algorithms.get(name)
830    }
831
832    /// List the names of all registered training optimization algorithms.
833    pub fn list_algorithms(&self) -> Vec<String> {
834        self.optimization_algorithms.keys().cloned().collect()
835    }
836
837    /// Return a reference to the early-stopping configuration.
838    pub fn early_stopping(&self) -> &EarlyStopping {
839        &self.early_stopping
840    }
841
842    /// Return a mutable reference to the early-stopping configuration.
843    pub fn early_stopping_mut(&mut self) -> &mut EarlyStopping {
844        &mut self.early_stopping
845    }
846
847    /// Apply an optimization step to a weight slice given computed gradients and learning rate.
848    pub fn step(
849        &self,
850        algorithm: &TrainingAlgorithm,
851        weights: &mut [f64],
852        gradients: &[f64],
853        learning_rate: f64,
854    ) -> Result<(), MLError> {
855        if weights.len() != gradients.len() {
856            return Err(MLError::TrainingError(format!(
857                "weights length ({}) does not match gradients length ({})",
858                weights.len(),
859                gradients.len()
860            )));
861        }
862        match algorithm {
863            TrainingAlgorithm::SGD => {
864                for i in 0..weights.len() {
865                    weights[i] -= learning_rate * gradients[i];
866                }
867                Ok(())
868            }
869            other => Err(MLError::TrainingError(format!(
870                "TrainingOptimizer::step does not yet support algorithm {:?}",
871                other
872            ))),
873        }
874    }
875}
876
877impl HyperparameterTuner {
878    /// Empty `HyperparameterTuner` (default-constructed state).
879    pub fn new() -> Self {
880        Self {
881            tuning_space: TuningSpace::new(),
882            tuning_algorithm: TuningAlgorithm::BayesianOptimization,
883            tuning_history: TuningHistory::new(),
884        }
885    }
886
887    /// Mark the subsystem initialized (ready flag).
888    pub fn initialize(&mut self) -> Result<(), MLError> {
889        Ok(())
890    }
891
892    /// Return a reference to the tuning space.
893    pub fn tuning_space(&self) -> &TuningSpace {
894        &self.tuning_space
895    }
896
897    /// Return a mutable reference to the tuning space.
898    pub fn tuning_space_mut(&mut self) -> &mut TuningSpace {
899        &mut self.tuning_space
900    }
901
902    /// Return the configured tuning algorithm.
903    pub fn tuning_algorithm(&self) -> &TuningAlgorithm {
904        &self.tuning_algorithm
905    }
906
907    /// Set the tuning algorithm.
908    pub fn set_tuning_algorithm(&mut self, algorithm: TuningAlgorithm) {
909        self.tuning_algorithm = algorithm;
910    }
911
912    /// Return a reference to the tuning history.
913    pub fn tuning_history(&self) -> &TuningHistory {
914        &self.tuning_history
915    }
916
917    /// Return a mutable reference to the tuning history.
918    pub fn tuning_history_mut(&mut self) -> &mut TuningHistory {
919        &mut self.tuning_history
920    }
921
922    /// Suggest the next hyperparameter set to evaluate from the configured tuning space.
923    pub fn suggest(&self) -> Result<HashMap<String, f64>, MLError> {
924        let mut result = HashMap::new();
925        for param in &self.tuning_space.hyperparameters {
926            let val = match self.tuning_algorithm {
927                TuningAlgorithm::GridSearch => param.range.min_value,
928                _ => {
929                    if param.range.max_value >= param.range.min_value {
930                        (param.range.min_value + param.range.max_value) / 2.0
931                    } else {
932                        param.default_value
933                    }
934                }
935            };
936            result.insert(param.name.clone(), val);
937        }
938        Ok(result)
939    }
940}
941
942impl TuningSpace {
943    /// Empty `TuningSpace` (default-constructed state).
944    pub fn new() -> Self {
945        Self {
946            hyperparameters: Vec::new(),
947            constraints: Vec::new(),
948        }
949    }
950}
951
952impl Hyperparameter {
953    /// Empty `Hyperparameter` (default-constructed state).
954    pub fn new() -> Self {
955        Self {
956            name: "learning_rate".to_string(),
957            parameter_type: HyperparameterType::Continuous,
958            range: HyperparameterRange::new(),
959            default_value: 0.001,
960        }
961    }
962}
963
964impl HyperparameterRange {
965    /// Empty `HyperparameterRange` (default-constructed state).
966    pub fn new() -> Self {
967        Self {
968            min_value: 0.0001,
969            max_value: 1.0,
970            step: Some(0.0001),
971            categories: None,
972        }
973    }
974}
975
976impl HyperparameterConstraint {
977    /// Empty `HyperparameterConstraint` (default-constructed state).
978    pub fn new() -> Self {
979        Self {
980            constraint_id: "constraint_1".to_string(),
981            constraint_type: ConstraintType::Range,
982            parameters: vec!["learning_rate".to_string()],
983            condition: "learning_rate > 0".to_string(),
984        }
985    }
986}
987
988impl EarlyStopping {
989    /// Empty `EarlyStopping` (default-constructed state).
990    pub fn new() -> Self {
991        Self {
992            stopping_criteria: StoppingCriteria::new(),
993            patience: 10,
994            min_delta: 0.001,
995            restore_best_weights: true,
996        }
997    }
998
999    /// Return a reference to the stopping criteria.
1000    pub fn stopping_criteria(&self) -> &StoppingCriteria {
1001        &self.stopping_criteria
1002    }
1003
1004    /// Return a mutable reference to the stopping criteria.
1005    pub fn stopping_criteria_mut(&mut self) -> &mut StoppingCriteria {
1006        &mut self.stopping_criteria
1007    }
1008
1009    /// Return the configured patience (number of epochs without improvement).
1010    pub fn patience(&self) -> u32 {
1011        self.patience
1012    }
1013
1014    /// Set the patience.
1015    pub fn set_patience(&mut self, patience: u32) {
1016        self.patience = patience;
1017    }
1018
1019    /// Return the minimum delta required to count as an improvement.
1020    pub fn min_delta(&self) -> f64 {
1021        self.min_delta
1022    }
1023
1024    /// Set the minimum delta.
1025    pub fn set_min_delta(&mut self, min_delta: f64) {
1026        self.min_delta = min_delta;
1027    }
1028
1029    /// Return whether best weights should be restored after early stopping.
1030    pub fn restore_best_weights(&self) -> bool {
1031        self.restore_best_weights
1032    }
1033
1034    /// Set whether to restore best weights.
1035    pub fn set_restore_best_weights(&mut self, restore: bool) {
1036        self.restore_best_weights = restore;
1037    }
1038
1039    /// Check whether training should stop early based on metric progression.
1040    pub fn should_stop(&self, metric_history: &[f64]) -> bool {
1041        if metric_history.len() <= self.patience as usize {
1042            return false;
1043        }
1044        let mode = &self.stopping_criteria.mode;
1045        let mut best = metric_history[0];
1046        let mut wait = 0;
1047        for &val in &metric_history[1..] {
1048            let improved = match mode {
1049                StoppingMode::Min | StoppingMode::Auto => val < best - self.min_delta,
1050                StoppingMode::Max => val > best + self.min_delta,
1051            };
1052            if improved {
1053                best = val;
1054                wait = 0;
1055            } else {
1056                wait += 1;
1057                if wait >= self.patience {
1058                    return true;
1059                }
1060            }
1061        }
1062        false
1063    }
1064}
1065
1066impl StoppingCriteria {
1067    /// Empty `StoppingCriteria` (default-constructed state).
1068    pub fn new() -> Self {
1069        Self {
1070            metric: "val_loss".to_string(),
1071            mode: StoppingMode::Min,
1072            min_delta: 0.001,
1073            patience: 10,
1074        }
1075    }
1076}