Skip to main content

photonlayer_ruvector/
memory.rs

1//! In-memory experiment store with cosine-similarity nearest-neighbour recall
2//! (ADR-260 §11–§12).
3//!
4//! [`ExperimentMemory`] is the primary entry point. Call [`remember`] to store
5//! a finished experiment, then [`nearest`] to recall the most similar prior
6//! experiments by embedding.
7
8use photonlayer_core::prelude::{ExperimentReceipt, MetricReport, OpticalConfig};
9use ruvector_coherence::cosine_similarity;
10use serde::{Deserialize, Serialize};
11
12use crate::embedding::EMBED_DIM;
13
14/// A single stored experiment with its embedding, label, config, and receipt.
15#[derive(Clone, Debug, Serialize, Deserialize)]
16pub struct ExperimentRecord {
17    /// Unique experiment identifier (matches `receipt.experiment_id`).
18    pub id: String,
19    /// Human-readable class or outcome label, e.g. `"pass"` or `"fail"`.
20    pub label: String,
21    /// The optical configuration used.
22    pub config: OpticalConfig,
23    /// `mask_id` from the [`PhaseMask`] used.
24    pub mask_id: String,
25    /// 32-dim L2-normalised embedding (mask histogram + frame spectrum).
26    pub embedding: Vec<f32>,
27    /// Bound RVF receipt for this experiment.
28    pub receipt: ExperimentReceipt,
29    /// Benchmark metrics collected during the run.
30    pub metrics: MetricReport,
31}
32
33/// A nearest-neighbour hit returned by [`ExperimentMemory::nearest`].
34#[derive(Clone, Debug)]
35pub struct NearestHit {
36    /// Experiment identifier.
37    pub id: String,
38    /// Cosine similarity to the query embedding (higher = more similar).
39    pub score: f64,
40}
41
42/// A nearest-mask hit: lightweight result when only the mask is of interest.
43#[derive(Clone, Debug)]
44pub struct MaskSearchHit {
45    /// Experiment identifier.
46    pub id: String,
47    /// Cosine similarity to the query embedding.
48    pub score: f64,
49    /// `mask_id` of the matched experiment.
50    pub mask_id: String,
51}
52
53/// In-memory store of [`ExperimentRecord`]s supporting cosine-similarity
54/// nearest-neighbour search (ADR-260 §11–§12).
55///
56/// All searches are linear scans over stored embeddings (exact NN). This is
57/// appropriate for experiment-scale datasets (<10 k entries); swap for HNSW
58/// when larger.
59#[derive(Default, Debug)]
60pub struct ExperimentMemory {
61    records: Vec<ExperimentRecord>,
62}
63
64impl ExperimentMemory {
65    /// Create an empty experiment memory.
66    pub fn new() -> Self {
67        Self::default()
68    }
69
70    /// Store a new experiment record.
71    ///
72    /// # Panics
73    /// Panics if the embedding dimension is not [`EMBED_DIM`].
74    pub fn remember(&mut self, record: ExperimentRecord) {
75        assert_eq!(
76            record.embedding.len(),
77            EMBED_DIM,
78            "embedding must have {} dims, got {}",
79            EMBED_DIM,
80            record.embedding.len()
81        );
82        self.records.push(record);
83    }
84
85    /// Number of stored experiments.
86    pub fn len(&self) -> usize {
87        self.records.len()
88    }
89
90    /// Returns `true` when no experiments have been stored.
91    pub fn is_empty(&self) -> bool {
92        self.records.is_empty()
93    }
94
95    /// Return up to `limit` stored experiments sorted by descending cosine
96    /// similarity to `query_embedding`.
97    pub fn nearest(&self, query_embedding: &[f32], limit: usize) -> Vec<NearestHit> {
98        let mut scored: Vec<(f64, &str)> = self
99            .records
100            .iter()
101            .map(|r| {
102                (
103                    cosine_similarity(query_embedding, &r.embedding),
104                    r.id.as_str(),
105                )
106            })
107            .collect();
108        scored.sort_by(|a, b| b.0.partial_cmp(&a.0).unwrap_or(std::cmp::Ordering::Equal));
109        scored
110            .into_iter()
111            .take(limit)
112            .map(|(score, id)| NearestHit {
113                id: id.to_owned(),
114                score,
115            })
116            .collect()
117    }
118
119    /// Return all records with the given label.
120    pub fn by_label(&self, label: &str) -> Vec<&ExperimentRecord> {
121        self.records.iter().filter(|r| r.label == label).collect()
122    }
123
124    /// Iterate over all stored records.
125    pub fn records(&self) -> &[ExperimentRecord] {
126        &self.records
127    }
128
129    /// Look up a record by its exact id.
130    pub fn get(&self, id: &str) -> Option<&ExperimentRecord> {
131        self.records.iter().find(|r| r.id == id)
132    }
133}
134
135#[cfg(test)]
136mod tests {
137    use super::*;
138    use photonlayer_core::prelude::{
139        build_receipt, InputImage, OpticalConfig, OpticalSimulator, PhaseMask, Provenance,
140        ScalarSimulator,
141    };
142
143    use crate::embedding::experiment_embedding;
144
145    fn make_record(id: &str, label: &str, seed: u64) -> ExperimentRecord {
146        let n = 16;
147        let pixels: Vec<f32> = (0..n * n).map(|i| (i % n) as f32 / n as f32).collect();
148        let img = InputImage::from_norm_f32(n, n, pixels).unwrap();
149        let mask = PhaseMask::random(n, n, seed);
150        let cfg = OpticalConfig::demo(n, n);
151        let frame = ScalarSimulator.simulate(&img, &mask, &cfg).unwrap();
152        let metrics = MetricReport::default();
153        let receipt = build_receipt(
154            id,
155            &img,
156            &mask,
157            &cfg,
158            &frame,
159            &metrics,
160            &Provenance::default(),
161        );
162        let embedding = experiment_embedding(&mask, &frame);
163        ExperimentRecord {
164            id: id.to_owned(),
165            label: label.to_owned(),
166            config: cfg,
167            mask_id: mask.mask_id.clone(),
168            embedding,
169            receipt,
170            metrics,
171        }
172    }
173
174    #[test]
175    fn remember_and_len() {
176        let mut mem = ExperimentMemory::new();
177        assert!(mem.is_empty());
178        mem.remember(make_record("exp-1", "pass", 1));
179        assert_eq!(mem.len(), 1);
180        mem.remember(make_record("exp-2", "fail", 2));
181        assert_eq!(mem.len(), 2);
182    }
183
184    #[test]
185    fn nearest_finds_planted_match() {
186        let mut mem = ExperimentMemory::new();
187        // Store three different experiments.
188        let target_record = make_record("target", "pass", 42);
189        let query_emb = target_record.embedding.clone();
190        mem.remember(target_record);
191        mem.remember(make_record("other-1", "pass", 7));
192        mem.remember(make_record("other-2", "fail", 99));
193
194        let hits = mem.nearest(&query_emb, 3);
195        // The exact stored embedding must score 1.0 at rank 0.
196        assert_eq!(hits[0].id, "target");
197        assert!(
198            (hits[0].score - 1.0).abs() < 1e-5,
199            "score = {}",
200            hits[0].score
201        );
202    }
203
204    #[test]
205    fn by_label_filters_correctly() {
206        let mut mem = ExperimentMemory::new();
207        mem.remember(make_record("a", "pass", 1));
208        mem.remember(make_record("b", "fail", 2));
209        mem.remember(make_record("c", "pass", 3));
210        let passes = mem.by_label("pass");
211        assert_eq!(passes.len(), 2);
212        let fails = mem.by_label("fail");
213        assert_eq!(fails.len(), 1);
214    }
215}