Skip to main content

qualia_semantic_library/
embedding.rs

1//! Embedding storage codec + similarity. Always compiled (the library indexes
2//! and searches vectors even when built without the HTTP LLM backend).
3//!
4//! Vectors are stored in the container's `embeddings/vectors.f32` asset as a
5//! flat, row-major little-endian `f32` matrix of shape `rows × dim`.
6
7/// Encode an embedding matrix (`rows × dim`, row-major) to little-endian f32 bytes.
8pub fn encode_f32_matrix(rows: &[Vec<f32>]) -> Vec<u8> {
9    let mut out = Vec::with_capacity(rows.iter().map(|r| r.len() * 4).sum());
10    for row in rows {
11        for &v in row {
12            out.extend_from_slice(&v.to_le_bytes());
13        }
14    }
15    out
16}
17
18/// Decode a flat little-endian f32 buffer into `rows × dim`.
19pub fn decode_f32_matrix(bytes: &[u8], dim: usize) -> Vec<Vec<f32>> {
20    if dim == 0 {
21        return Vec::new();
22    }
23    let floats: Vec<f32> = bytes
24        .chunks_exact(4)
25        .map(|b| f32::from_le_bytes([b[0], b[1], b[2], b[3]]))
26        .collect();
27    floats.chunks_exact(dim).map(|c| c.to_vec()).collect()
28}
29
30/// Cosine similarity in [-1, 1]; 0 if either vector is degenerate or mismatched.
31pub fn cosine(a: &[f32], b: &[f32]) -> f32 {
32    if a.len() != b.len() || a.is_empty() {
33        return 0.0;
34    }
35    let mut dot = 0.0f32;
36    let mut na = 0.0f32;
37    let mut nb = 0.0f32;
38    for i in 0..a.len() {
39        dot += a[i] * b[i];
40        na += a[i] * a[i];
41        nb += b[i] * b[i];
42    }
43    if na == 0.0 || nb == 0.0 {
44        return 0.0;
45    }
46    dot / (na.sqrt() * nb.sqrt())
47}
48
49/// Mean of a set of vectors (centroid). Empty input → empty vector.
50pub fn centroid(rows: &[Vec<f32>]) -> Vec<f32> {
51    let dim = rows.first().map(|r| r.len()).unwrap_or(0);
52    if dim == 0 {
53        return Vec::new();
54    }
55    let mut acc = vec![0.0f32; dim];
56    let mut n = 0usize;
57    for r in rows {
58        if r.len() != dim {
59            continue;
60        }
61        for i in 0..dim {
62            acc[i] += r[i];
63        }
64        n += 1;
65    }
66    if n == 0 {
67        return Vec::new();
68    }
69    for v in &mut acc {
70        *v /= n as f32;
71    }
72    acc
73}
74
75#[cfg(test)]
76mod tests {
77    use super::*;
78
79    #[test]
80    fn matrix_round_trips() {
81        let m = vec![vec![1.0, 2.0, 3.0], vec![-1.0, 0.5, 0.0]];
82        let bytes = encode_f32_matrix(&m);
83        let back = decode_f32_matrix(&bytes, 3);
84        assert_eq!(m, back);
85    }
86
87    #[test]
88    fn cosine_basics() {
89        assert!((cosine(&[1.0, 0.0], &[1.0, 0.0]) - 1.0).abs() < 1e-6);
90        assert!(cosine(&[1.0, 0.0], &[0.0, 1.0]).abs() < 1e-6);
91        assert_eq!(cosine(&[1.0], &[1.0, 2.0]), 0.0);
92    }
93}