Skip to main content

ruvector_learning_wasm/
trajectory.rs

1//! Trajectory tracking for reinforcement learning
2//!
3//! Records execution trajectories for post-hoc learning and pattern analysis.
4
5use wasm_bindgen::prelude::*;
6
7/// A single trajectory recording
8#[derive(Clone)]
9pub struct Trajectory {
10    /// Embedding at query start
11    pub embedding: Vec<f32>,
12    /// Operator type that was executed (0-16)
13    pub operator_type: u8,
14    /// Attention mechanism used
15    pub attention_type: u8,
16    /// Execution time in milliseconds
17    pub execution_ms: f32,
18    /// Baseline execution time (for comparison)
19    pub baseline_ms: f32,
20    /// Improvement ratio (baseline / actual - 1.0)
21    pub improvement: f32,
22    /// Timestamp (simulation time or wall clock)
23    pub timestamp: u64,
24}
25
26impl Trajectory {
27    /// Create a new trajectory
28    pub fn new(
29        embedding: Vec<f32>,
30        operator_type: u8,
31        attention_type: u8,
32        execution_ms: f32,
33        baseline_ms: f32,
34    ) -> Self {
35        let improvement = if execution_ms > 0.0 {
36            (baseline_ms / execution_ms) - 1.0
37        } else {
38            0.0
39        };
40
41        Self {
42            embedding,
43            operator_type,
44            attention_type,
45            execution_ms,
46            baseline_ms,
47            improvement,
48            timestamp: 0,
49        }
50    }
51
52    /// Get quality score (0.0 - 1.0)
53    pub fn quality(&self) -> f32 {
54        // Quality based on improvement, saturating at 2x speedup
55        ((self.improvement + 1.0) / 2.0).clamp(0.0, 1.0)
56    }
57
58    /// Check if this trajectory represents a success
59    pub fn is_success(&self) -> bool {
60        self.improvement > 0.0
61    }
62
63    /// Get the gradient direction for learning
64    pub fn gradient(&self) -> Vec<f32> {
65        if self.is_success() {
66            // Positive improvement: reinforce this direction
67            self.embedding.clone()
68        } else {
69            // Negative improvement: push away from this direction
70            self.embedding.iter().map(|x| -x).collect()
71        }
72    }
73}
74
75/// Statistics for a collection of trajectories
76#[derive(Clone, Default)]
77pub struct TrajectoryStats {
78    /// Total trajectory count
79    pub count: u64,
80    /// Mean improvement ratio
81    pub mean_improvement: f32,
82    /// Variance of improvement
83    pub variance: f32,
84    /// Best improvement seen
85    pub best_improvement: f32,
86    /// Success rate (positive improvement)
87    pub success_rate: f32,
88    /// Most common attention type
89    pub best_attention: u8,
90}
91
92impl TrajectoryStats {
93    /// Update stats with a new trajectory
94    pub fn update(&mut self, trajectory: &Trajectory) {
95        let n = self.count as f32;
96        let new_n = n + 1.0;
97
98        // Welford's online algorithm for mean and variance
99        let delta = trajectory.improvement - self.mean_improvement;
100        self.mean_improvement += delta / new_n;
101        let delta2 = trajectory.improvement - self.mean_improvement;
102        self.variance += delta * delta2;
103
104        // Update best
105        if trajectory.improvement > self.best_improvement {
106            self.best_improvement = trajectory.improvement;
107            self.best_attention = trajectory.attention_type;
108        }
109
110        // Update success rate
111        let successes = self.success_rate * n;
112        let new_successes = if trajectory.is_success() {
113            successes + 1.0
114        } else {
115            successes
116        };
117        self.success_rate = new_successes / new_n;
118
119        self.count += 1;
120    }
121
122    /// Get variance (finalized)
123    pub fn final_variance(&self) -> f32 {
124        if self.count > 1 {
125            self.variance / (self.count - 1) as f32
126        } else {
127            0.0
128        }
129    }
130}
131
132/// Ring buffer for trajectory storage
133pub struct TrajectoryBuffer {
134    /// Trajectories storage
135    trajectories: Vec<Trajectory>,
136    /// Maximum capacity
137    capacity: usize,
138    /// Write position
139    write_pos: usize,
140    /// Total count (may exceed capacity)
141    total_count: u64,
142    /// Running stats
143    stats: TrajectoryStats,
144}
145
146impl TrajectoryBuffer {
147    /// Create a new trajectory buffer
148    pub fn new(capacity: usize) -> Self {
149        Self {
150            trajectories: Vec::with_capacity(capacity),
151            capacity,
152            write_pos: 0,
153            total_count: 0,
154            stats: TrajectoryStats::default(),
155        }
156    }
157
158    /// Push a new trajectory
159    pub fn push(&mut self, trajectory: Trajectory) {
160        self.stats.update(&trajectory);
161
162        if self.trajectories.len() < self.capacity {
163            self.trajectories.push(trajectory);
164        } else {
165            self.trajectories[self.write_pos] = trajectory;
166        }
167
168        self.write_pos = (self.write_pos + 1) % self.capacity;
169        self.total_count += 1;
170    }
171
172    /// Get current buffer contents
173    pub fn trajectories(&self) -> &[Trajectory] {
174        &self.trajectories
175    }
176
177    /// Drain all trajectories (returns ownership, clears buffer)
178    pub fn drain(&mut self) -> Vec<Trajectory> {
179        let result = std::mem::take(&mut self.trajectories);
180        self.write_pos = 0;
181        result
182    }
183
184    /// Get statistics
185    pub fn stats(&self) -> &TrajectoryStats {
186        &self.stats
187    }
188
189    /// Get total count (may exceed capacity)
190    pub fn total_count(&self) -> u64 {
191        self.total_count
192    }
193
194    /// Get current buffer size
195    pub fn len(&self) -> usize {
196        self.trajectories.len()
197    }
198
199    /// Check if empty
200    pub fn is_empty(&self) -> bool {
201        self.trajectories.is_empty()
202    }
203
204    /// Get high-quality trajectories (quality > threshold)
205    pub fn high_quality(&self, threshold: f32) -> Vec<&Trajectory> {
206        self.trajectories
207            .iter()
208            .filter(|t| t.quality() > threshold)
209            .collect()
210    }
211
212    /// Get trajectories for a specific operator type
213    pub fn by_operator(&self, op_type: u8) -> Vec<&Trajectory> {
214        self.trajectories
215            .iter()
216            .filter(|t| t.operator_type == op_type)
217            .collect()
218    }
219
220    /// Reset buffer and stats
221    pub fn reset(&mut self) {
222        self.trajectories.clear();
223        self.write_pos = 0;
224        self.total_count = 0;
225        self.stats = TrajectoryStats::default();
226    }
227}
228
229impl Default for TrajectoryBuffer {
230    fn default() -> Self {
231        Self::new(1000)
232    }
233}
234
235// ============ WASM Bindings ============
236
237/// WASM-exposed trajectory buffer
238#[wasm_bindgen]
239pub struct WasmTrajectoryBuffer {
240    buffer: TrajectoryBuffer,
241    #[allow(dead_code)]
242    embedding_dim: usize,
243}
244
245#[wasm_bindgen]
246impl WasmTrajectoryBuffer {
247    /// Create a new trajectory buffer
248    ///
249    /// @param capacity - Maximum number of trajectories to store
250    /// @param embedding_dim - Dimension of embeddings (default 256)
251    #[wasm_bindgen(constructor)]
252    pub fn new(capacity: Option<usize>, embedding_dim: Option<usize>) -> Self {
253        Self {
254            buffer: TrajectoryBuffer::new(capacity.unwrap_or(1000)),
255            embedding_dim: embedding_dim.unwrap_or(256),
256        }
257    }
258
259    /// Record a trajectory
260    ///
261    /// @param embedding - Embedding vector (Float32Array)
262    /// @param op_type - Operator type (0-16)
263    /// @param attention_type - Attention mechanism used
264    /// @param execution_ms - Actual execution time
265    /// @param baseline_ms - Baseline execution time
266    #[wasm_bindgen]
267    pub fn record(
268        &mut self,
269        embedding: &[f32],
270        op_type: u8,
271        attention_type: u8,
272        execution_ms: f32,
273        baseline_ms: f32,
274    ) {
275        let traj = Trajectory::new(
276            embedding.to_vec(),
277            op_type,
278            attention_type,
279            execution_ms,
280            baseline_ms,
281        );
282        self.buffer.push(traj);
283    }
284
285    /// Get total count
286    #[wasm_bindgen]
287    pub fn total_count(&self) -> u64 {
288        self.buffer.total_count()
289    }
290
291    /// Get buffer length
292    #[wasm_bindgen]
293    pub fn len(&self) -> usize {
294        self.buffer.len()
295    }
296
297    /// Check if empty
298    #[wasm_bindgen]
299    pub fn is_empty(&self) -> bool {
300        self.buffer.is_empty()
301    }
302
303    /// Get mean improvement
304    #[wasm_bindgen]
305    pub fn mean_improvement(&self) -> f32 {
306        self.buffer.stats().mean_improvement
307    }
308
309    /// Get best improvement
310    #[wasm_bindgen]
311    pub fn best_improvement(&self) -> f32 {
312        self.buffer.stats().best_improvement
313    }
314
315    /// Get success rate
316    #[wasm_bindgen]
317    pub fn success_rate(&self) -> f32 {
318        self.buffer.stats().success_rate
319    }
320
321    /// Get best attention type
322    #[wasm_bindgen]
323    pub fn best_attention(&self) -> u8 {
324        self.buffer.stats().best_attention
325    }
326
327    /// Get variance
328    #[wasm_bindgen]
329    pub fn variance(&self) -> f32 {
330        self.buffer.stats().final_variance()
331    }
332
333    /// Reset buffer
334    #[wasm_bindgen]
335    pub fn reset(&mut self) {
336        self.buffer.reset();
337    }
338
339    /// Get high quality trajectory count
340    #[wasm_bindgen]
341    pub fn high_quality_count(&self, threshold: f32) -> usize {
342        self.buffer.high_quality(threshold).len()
343    }
344
345    /// Get trajectory count for operator
346    #[wasm_bindgen]
347    pub fn count_by_operator(&self, op_type: u8) -> usize {
348        self.buffer.by_operator(op_type).len()
349    }
350}
351
352#[cfg(test)]
353mod tests {
354    use super::*;
355
356    #[test]
357    fn test_trajectory_creation() {
358        let embedding = vec![1.0; 256];
359        let traj = Trajectory::new(embedding, 2, 0, 100.0, 150.0);
360
361        assert_eq!(traj.operator_type, 2);
362        assert!(traj.improvement > 0.0); // 150/100 - 1 = 0.5
363        assert!(traj.is_success());
364    }
365
366    #[test]
367    fn test_trajectory_quality() {
368        let embedding = vec![1.0; 256];
369
370        // 2x speedup should give quality close to 1.0
371        let fast = Trajectory::new(embedding.clone(), 0, 0, 50.0, 100.0);
372        assert!(fast.quality() > 0.5);
373
374        // Slowdown should give lower quality
375        let slow = Trajectory::new(embedding, 0, 0, 150.0, 100.0);
376        assert!(slow.quality() < 0.5);
377    }
378
379    #[test]
380    fn test_buffer_push() {
381        let mut buffer = TrajectoryBuffer::new(10);
382        let embedding = vec![1.0; 256];
383
384        for i in 0..15 {
385            let traj = Trajectory::new(embedding.clone(), 0, 0, 100.0, 100.0 + i as f32);
386            buffer.push(traj);
387        }
388
389        // Buffer should be at capacity
390        assert_eq!(buffer.len(), 10);
391        // Total count should include all pushes
392        assert_eq!(buffer.total_count(), 15);
393    }
394
395    #[test]
396    fn test_stats_update() {
397        let mut stats = TrajectoryStats::default();
398        let embedding = vec![1.0; 256];
399
400        let traj1 = Trajectory::new(embedding.clone(), 0, 0, 100.0, 150.0); // 50% improvement
401        let traj2 = Trajectory::new(embedding.clone(), 0, 1, 100.0, 200.0); // 100% improvement
402        let traj3 = Trajectory::new(embedding, 0, 0, 150.0, 100.0); // -33% (failure)
403
404        stats.update(&traj1);
405        stats.update(&traj2);
406        stats.update(&traj3);
407
408        assert_eq!(stats.count, 3);
409        assert!(stats.success_rate > 0.6); // 2/3 success
410        assert_eq!(stats.best_attention, 1); // Best was attention type 1
411    }
412
413    #[test]
414    fn test_high_quality_filter() {
415        let mut buffer = TrajectoryBuffer::new(100);
416        let embedding = vec![1.0; 256];
417
418        // Add some trajectories with varying quality
419        for i in 0..10 {
420            let baseline = 100.0 + (i as f32) * 20.0;
421            let traj = Trajectory::new(embedding.clone(), 0, 0, 100.0, baseline);
422            buffer.push(traj);
423        }
424
425        let high_quality = buffer.high_quality(0.5);
426        assert!(!high_quality.is_empty());
427    }
428}