Skip to main content

ruvector_learning_wasm/
operator_scope.rs

1//! Per-Operator-Type Scoped LoRA
2//!
3//! Maintains separate LoRA adapters for different operator types,
4//! enabling specialized learning for each query operator.
5
6use crate::lora::{LoRAConfig, LoRAPair};
7use wasm_bindgen::prelude::*;
8
9/// Operator types for scoping (matches ruvector-dag OperatorType)
10#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
11#[repr(u8)]
12pub enum OperatorScope {
13    // Scan operators (0-3)
14    SeqScan = 0,
15    IndexScan = 1,
16    HnswScan = 2,
17    IvfFlatScan = 3,
18
19    // Join operators (4-6)
20    NestedLoopJoin = 4,
21    HashJoin = 5,
22    MergeJoin = 6,
23
24    // Aggregation (7-8)
25    Aggregate = 7,
26    GroupBy = 8,
27
28    // Filter/Project (9-10)
29    Filter = 9,
30    Project = 10,
31
32    // Sort/Limit (11-12)
33    Sort = 11,
34    Limit = 12,
35
36    // Vector operations (13-14)
37    VectorDistance = 13,
38    Rerank = 14,
39
40    // Utility (15-16)
41    Materialize = 15,
42    Result = 16,
43}
44
45impl OperatorScope {
46    /// Convert from u8
47    pub fn from_u8(v: u8) -> Option<Self> {
48        match v {
49            0 => Some(Self::SeqScan),
50            1 => Some(Self::IndexScan),
51            2 => Some(Self::HnswScan),
52            3 => Some(Self::IvfFlatScan),
53            4 => Some(Self::NestedLoopJoin),
54            5 => Some(Self::HashJoin),
55            6 => Some(Self::MergeJoin),
56            7 => Some(Self::Aggregate),
57            8 => Some(Self::GroupBy),
58            9 => Some(Self::Filter),
59            10 => Some(Self::Project),
60            11 => Some(Self::Sort),
61            12 => Some(Self::Limit),
62            13 => Some(Self::VectorDistance),
63            14 => Some(Self::Rerank),
64            15 => Some(Self::Materialize),
65            16 => Some(Self::Result),
66            _ => None,
67        }
68    }
69
70    /// Get category for grouped learning
71    pub fn category(&self) -> OperatorCategory {
72        match self {
73            Self::SeqScan | Self::IndexScan | Self::HnswScan | Self::IvfFlatScan => {
74                OperatorCategory::Scan
75            }
76            Self::NestedLoopJoin | Self::HashJoin | Self::MergeJoin => OperatorCategory::Join,
77            Self::Aggregate | Self::GroupBy => OperatorCategory::Aggregation,
78            Self::Filter | Self::Project => OperatorCategory::Transform,
79            Self::Sort | Self::Limit => OperatorCategory::Order,
80            Self::VectorDistance | Self::Rerank => OperatorCategory::Vector,
81            Self::Materialize | Self::Result => OperatorCategory::Utility,
82        }
83    }
84}
85
86/// High-level operator categories for shared learning
87#[derive(Debug, Clone, Copy, PartialEq, Eq)]
88#[repr(u8)]
89pub enum OperatorCategory {
90    Scan = 0,
91    Join = 1,
92    Aggregation = 2,
93    Transform = 3,
94    Order = 4,
95    Vector = 5,
96    Utility = 6,
97}
98
99/// Scoped LoRA manager with per-operator-type adapters
100///
101/// Maintains 17 separate LoRA pairs (one per OperatorScope) for
102/// specialized learning based on query operator type.
103pub struct ScopedLoRA {
104    /// Per-operator-type LoRA pairs (17 total)
105    adapters: [LoRAPair; 17],
106    /// Per-category LoRA pairs for fallback (7 total)
107    category_adapters: [LoRAPair; 7],
108    /// Configuration (kept for potential future use)
109    #[allow(dead_code)]
110    config: LoRAConfig,
111    /// Whether to use category fallback when operator has no history
112    use_category_fallback: bool,
113    /// Per-operator forward counts
114    forward_counts: [u64; 17],
115}
116
117impl ScopedLoRA {
118    /// Create a new scoped LoRA manager
119    pub fn new(config: LoRAConfig) -> Self {
120        // Initialize all 17 operator adapters
121        let adapters = std::array::from_fn(|_| LoRAPair::new(&config));
122        let category_adapters = std::array::from_fn(|_| LoRAPair::new(&config));
123
124        Self {
125            adapters,
126            category_adapters,
127            config,
128            use_category_fallback: true,
129            forward_counts: [0; 17],
130        }
131    }
132
133    /// Forward pass for a specific operator type
134    #[inline]
135    pub fn forward(&mut self, scope: OperatorScope, input: &[f32]) -> Vec<f32> {
136        let idx = scope as usize;
137        self.forward_counts[idx] += 1;
138
139        // Use operator-specific adapter
140        let output = self.adapters[idx].forward(input);
141
142        // If using fallback and this operator has little history,
143        // blend with category adapter
144        if self.use_category_fallback && self.adapters[idx].adapt_count() < 10 {
145            let cat_idx = scope.category() as usize;
146            let cat_output = self.category_adapters[cat_idx].forward(input);
147
148            // Blend based on relative experience
149            let op_exp = self.adapters[idx].adapt_count() as f32;
150            let weight = (op_exp / 10.0).min(1.0);
151
152            let mut blended = output;
153            for i in 0..blended.len().min(cat_output.len()) {
154                blended[i] = blended[i] * weight + cat_output[i] * (1.0 - weight);
155            }
156            return blended;
157        }
158
159        output
160    }
161
162    /// Adapt the adapter for a specific operator type
163    #[inline]
164    pub fn adapt(&mut self, scope: OperatorScope, gradient: &[f32]) {
165        let idx = scope as usize;
166        self.adapters[idx].adapt(gradient);
167
168        // Also update category adapter for transfer learning
169        let cat_idx = scope.category() as usize;
170        self.category_adapters[cat_idx].adapt(gradient);
171    }
172
173    /// Adapt with improvement reward
174    #[inline]
175    pub fn adapt_with_reward(&mut self, scope: OperatorScope, gradient: &[f32], improvement: f32) {
176        let idx = scope as usize;
177        self.adapters[idx].adapt_with_reward(gradient, improvement);
178
179        // Also update category adapter
180        let cat_idx = scope.category() as usize;
181        self.category_adapters[cat_idx].adapt_with_reward(gradient, improvement);
182    }
183
184    /// Reset a specific operator's adapter
185    pub fn reset_scope(&mut self, scope: OperatorScope) {
186        let idx = scope as usize;
187        self.adapters[idx].reset();
188        self.forward_counts[idx] = 0;
189    }
190
191    /// Reset all adapters
192    pub fn reset_all(&mut self) {
193        for adapter in &mut self.adapters {
194            adapter.reset();
195        }
196        for adapter in &mut self.category_adapters {
197            adapter.reset();
198        }
199        self.forward_counts = [0; 17];
200    }
201
202    /// Get statistics for a specific operator
203    pub fn stats(&self, scope: OperatorScope) -> (u64, u64, f32) {
204        let idx = scope as usize;
205        (
206            self.forward_counts[idx],
207            self.adapters[idx].adapt_count(),
208            self.adapters[idx].delta_norm(),
209        )
210    }
211
212    /// Get total statistics across all operators
213    pub fn total_stats(&self) -> (u64, u64, f32) {
214        let total_forwards: u64 = self.forward_counts.iter().sum();
215        let total_adapts: u64 = self.adapters.iter().map(|a| a.adapt_count()).sum();
216        let max_delta: f32 = self
217            .adapters
218            .iter()
219            .map(|a| a.delta_norm())
220            .fold(0.0, f32::max);
221
222        (total_forwards, total_adapts, max_delta)
223    }
224
225    /// Get the most active operator scopes
226    pub fn most_active(&self, top_n: usize) -> Vec<(OperatorScope, u64)> {
227        let mut counts: Vec<(usize, u64)> = self
228            .forward_counts
229            .iter()
230            .enumerate()
231            .map(|(i, &c)| (i, c))
232            .collect();
233
234        counts.sort_by(|a, b| b.1.cmp(&a.1));
235
236        counts
237            .into_iter()
238            .take(top_n)
239            .filter_map(|(idx, count)| {
240                OperatorScope::from_u8(idx as u8).map(|scope| (scope, count))
241            })
242            .collect()
243    }
244
245    /// Set category fallback mode
246    pub fn set_category_fallback(&mut self, enabled: bool) {
247        self.use_category_fallback = enabled;
248    }
249
250    /// Get reference to operator adapter
251    pub fn adapter(&self, scope: OperatorScope) -> &LoRAPair {
252        &self.adapters[scope as usize]
253    }
254
255    /// Get mutable reference to operator adapter
256    pub fn adapter_mut(&mut self, scope: OperatorScope) -> &mut LoRAPair {
257        &mut self.adapters[scope as usize]
258    }
259}
260
261impl Default for ScopedLoRA {
262    fn default() -> Self {
263        Self::new(LoRAConfig::default())
264    }
265}
266
267// ============ WASM Bindings ============
268
269pub mod wasm_exports {
270    use super::*;
271    #[allow(unused_imports)]
272    use wasm_bindgen::prelude::*;
273
274    /// WASM-exposed Scoped LoRA manager
275    #[wasm_bindgen]
276    pub struct WasmScopedLoRA {
277        inner: ScopedLoRA,
278        input_buffer: Vec<f32>,
279        output_buffer: Vec<f32>,
280    }
281
282    #[wasm_bindgen]
283    impl WasmScopedLoRA {
284        /// Create a new scoped LoRA manager
285        ///
286        /// @param dim - Embedding dimension (max 256)
287        /// @param alpha - Scaling factor (default 0.1)
288        /// @param learning_rate - Learning rate (default 0.01)
289        #[wasm_bindgen(constructor)]
290        pub fn new(dim: Option<usize>, alpha: Option<f32>, learning_rate: Option<f32>) -> Self {
291            let config = LoRAConfig {
292                dim: dim.unwrap_or(256).min(256),
293                rank: 2,
294                alpha: alpha.unwrap_or(0.1),
295                learning_rate: learning_rate.unwrap_or(0.01),
296                dropout: 0.0,
297            };
298
299            let actual_dim = config.dim;
300            Self {
301                inner: ScopedLoRA::new(config),
302                input_buffer: vec![0.0; actual_dim],
303                output_buffer: vec![0.0; actual_dim],
304            }
305        }
306
307        /// Get input buffer pointer
308        #[wasm_bindgen]
309        pub fn get_input_ptr(&mut self) -> *mut f32 {
310            self.input_buffer.as_mut_ptr()
311        }
312
313        /// Get output buffer pointer
314        #[wasm_bindgen]
315        pub fn get_output_ptr(&self) -> *const f32 {
316            self.output_buffer.as_ptr()
317        }
318
319        /// Forward pass for operator type (uses internal buffers)
320        ///
321        /// @param op_type - Operator type (0-16)
322        #[wasm_bindgen]
323        pub fn forward(&mut self, op_type: u8) {
324            if let Some(scope) = OperatorScope::from_u8(op_type) {
325                let output = self.inner.forward(scope, &self.input_buffer);
326                let n = output.len().min(self.output_buffer.len());
327                self.output_buffer[..n].copy_from_slice(&output[..n]);
328            }
329        }
330
331        /// Forward pass with typed array
332        #[wasm_bindgen]
333        pub fn forward_array(&mut self, op_type: u8, input: &[f32]) -> Vec<f32> {
334            if let Some(scope) = OperatorScope::from_u8(op_type) {
335                self.inner.forward(scope, input)
336            } else {
337                input.to_vec()
338            }
339        }
340
341        /// Adapt for operator type using input buffer as gradient
342        #[wasm_bindgen]
343        pub fn adapt(&mut self, op_type: u8) {
344            if let Some(scope) = OperatorScope::from_u8(op_type) {
345                self.inner.adapt(scope, &self.input_buffer.clone());
346            }
347        }
348
349        /// Adapt with typed array
350        #[wasm_bindgen]
351        pub fn adapt_array(&mut self, op_type: u8, gradient: &[f32]) {
352            if let Some(scope) = OperatorScope::from_u8(op_type) {
353                self.inner.adapt(scope, gradient);
354            }
355        }
356
357        /// Adapt with improvement reward
358        #[wasm_bindgen]
359        pub fn adapt_with_reward(&mut self, op_type: u8, improvement: f32) {
360            if let Some(scope) = OperatorScope::from_u8(op_type) {
361                self.inner
362                    .adapt_with_reward(scope, &self.input_buffer.clone(), improvement);
363            }
364        }
365
366        /// Reset specific operator adapter
367        #[wasm_bindgen]
368        pub fn reset_scope(&mut self, op_type: u8) {
369            if let Some(scope) = OperatorScope::from_u8(op_type) {
370                self.inner.reset_scope(scope);
371            }
372        }
373
374        /// Reset all adapters
375        #[wasm_bindgen]
376        pub fn reset_all(&mut self) {
377            self.inner.reset_all();
378        }
379
380        /// Get forward count for operator
381        #[wasm_bindgen]
382        pub fn forward_count(&self, op_type: u8) -> u64 {
383            if let Some(scope) = OperatorScope::from_u8(op_type) {
384                self.inner.stats(scope).0
385            } else {
386                0
387            }
388        }
389
390        /// Get adapt count for operator
391        #[wasm_bindgen]
392        pub fn adapt_count(&self, op_type: u8) -> u64 {
393            if let Some(scope) = OperatorScope::from_u8(op_type) {
394                self.inner.stats(scope).1
395            } else {
396                0
397            }
398        }
399
400        /// Get delta norm for operator
401        #[wasm_bindgen]
402        pub fn delta_norm(&self, op_type: u8) -> f32 {
403            if let Some(scope) = OperatorScope::from_u8(op_type) {
404                self.inner.stats(scope).2
405            } else {
406                0.0
407            }
408        }
409
410        /// Get total forward count
411        #[wasm_bindgen]
412        pub fn total_forward_count(&self) -> u64 {
413            self.inner.total_stats().0
414        }
415
416        /// Get total adapt count
417        #[wasm_bindgen]
418        pub fn total_adapt_count(&self) -> u64 {
419            self.inner.total_stats().1
420        }
421
422        /// Enable/disable category fallback
423        #[wasm_bindgen]
424        pub fn set_category_fallback(&mut self, enabled: bool) {
425            self.inner.set_category_fallback(enabled);
426        }
427
428        /// Get operator scope name
429        #[wasm_bindgen]
430        pub fn scope_name(op_type: u8) -> String {
431            match op_type {
432                0 => "SeqScan".to_string(),
433                1 => "IndexScan".to_string(),
434                2 => "HnswScan".to_string(),
435                3 => "IvfFlatScan".to_string(),
436                4 => "NestedLoopJoin".to_string(),
437                5 => "HashJoin".to_string(),
438                6 => "MergeJoin".to_string(),
439                7 => "Aggregate".to_string(),
440                8 => "GroupBy".to_string(),
441                9 => "Filter".to_string(),
442                10 => "Project".to_string(),
443                11 => "Sort".to_string(),
444                12 => "Limit".to_string(),
445                13 => "VectorDistance".to_string(),
446                14 => "Rerank".to_string(),
447                15 => "Materialize".to_string(),
448                16 => "Result".to_string(),
449                _ => "Unknown".to_string(),
450            }
451        }
452    }
453}
454
455#[cfg(test)]
456mod tests {
457    use super::*;
458
459    #[test]
460    fn test_scoped_lora_creation() {
461        let lora = ScopedLoRA::default();
462        let (forwards, adapts, delta) = lora.total_stats();
463        assert_eq!(forwards, 0);
464        assert_eq!(adapts, 0);
465        assert_eq!(delta, 0.0);
466    }
467
468    #[test]
469    fn test_scoped_forward() {
470        let mut lora = ScopedLoRA::default();
471        let input = vec![1.0; 256];
472
473        let output = lora.forward(OperatorScope::HnswScan, &input);
474        assert_eq!(output.len(), 256);
475
476        let (forwards, _, _) = lora.stats(OperatorScope::HnswScan);
477        assert_eq!(forwards, 1);
478    }
479
480    #[test]
481    fn test_scoped_adapt() {
482        let mut lora = ScopedLoRA::default();
483        let gradient = vec![0.1; 256];
484
485        lora.adapt(OperatorScope::Filter, &gradient);
486
487        let (_, adapts, delta) = lora.stats(OperatorScope::Filter);
488        assert_eq!(adapts, 1);
489        assert!(delta > 0.0);
490    }
491
492    #[test]
493    fn test_category_transfer() {
494        let mut lora = ScopedLoRA::default();
495        let gradient = vec![0.1; 256];
496
497        // Adapt HnswScan (category: Scan)
498        lora.adapt(OperatorScope::HnswScan, &gradient);
499
500        // SeqScan should benefit from category adapter via fallback
501        let input = vec![1.0; 256];
502        let output = lora.forward(OperatorScope::SeqScan, &input);
503
504        // With fallback enabled and SeqScan having no history,
505        // it should use the category adapter which was updated
506        // This is a behavioral test - output should differ from input
507        let mut diff = 0.0f32;
508        for i in 0..256 {
509            diff += (output[i] - input[i]).abs();
510        }
511        // Due to category transfer, there should be some difference
512        assert!(diff > 0.0, "Category transfer should affect output");
513    }
514
515    #[test]
516    fn test_operator_scope_conversion() {
517        for i in 0..=16u8 {
518            let scope = OperatorScope::from_u8(i);
519            assert!(scope.is_some(), "Scope {} should be valid", i);
520        }
521        assert!(OperatorScope::from_u8(17).is_none());
522    }
523}