From 65de98498898f6c6f355842cfdfbe14a9b6abde2 Mon Sep 17 00:00:00 2001 From: vicrodh <103399283+vicrodh@users.noreply.github.com> Date: Fri, 26 Jun 2026 20:15:00 -0600 Subject: [PATCH] feat(reco): scaffold qbz-reco crate + port SparseVector math New frontend-agnostic crate qbz-reco (ADR-006) for the playlist Suggested Songs engine (sub-plan 2). T1: 1:1 port of the Tauri artist_vectors SparseVector (sorted parallel index/value arrays, set/get, dot merge-join, magnitude/ normalize, serde) with its full test suite (13/13 green). Drops the dead top_k_similar helper (its only caller find_nearest is dropped per epic D3); keeps cosine_similarity for parity + tests but not for ranking. cc --- crates/Cargo.lock | 7 + crates/Cargo.toml | 1 + crates/qbz-reco/Cargo.toml | 9 + crates/qbz-reco/src/lib.rs | 13 + crates/qbz-reco/src/sparse_vector.rs | 395 +++++++++++++++++++++++++++ 5 files changed, 425 insertions(+) create mode 100644 crates/qbz-reco/Cargo.toml create mode 100644 crates/qbz-reco/src/lib.rs create mode 100644 crates/qbz-reco/src/sparse_vector.rs diff --git a/crates/Cargo.lock b/crates/Cargo.lock index 8c06d552f..7cd2bafc2 100644 --- a/crates/Cargo.lock +++ b/crates/Cargo.lock @@ -5817,6 +5817,13 @@ dependencies = [ "rusqlite", ] +[[package]] +name = "qbz-reco" +version = "0.1.0" +dependencies = [ + "serde", +] + [[package]] name = "qbz-secrets" version = "0.1.0" diff --git a/crates/Cargo.toml b/crates/Cargo.toml index 3b79da70b..8b4e9176b 100644 --- a/crates/Cargo.toml +++ b/crates/Cargo.toml @@ -34,6 +34,7 @@ members = [ "qbz-lyrics", "qbz-i18n", "qbz-music-link", + "qbz-reco", ] [workspace.package] diff --git a/crates/qbz-reco/Cargo.toml b/crates/qbz-reco/Cargo.toml new file mode 100644 index 000000000..05d723c31 --- /dev/null +++ b/crates/qbz-reco/Cargo.toml @@ -0,0 +1,9 @@ +[package] +name = "qbz-reco" +version.workspace = true +edition.workspace = true +license.workspace = true +description = "Frontend-agnostic artist-vector recommendation engine for QBZ (ported from the Tauri artist_vectors)" + +[dependencies] +serde = { workspace = true } diff --git a/crates/qbz-reco/src/lib.rs b/crates/qbz-reco/src/lib.rs new file mode 100644 index 000000000..edc80f4d0 --- /dev/null +++ b/crates/qbz-reco/src/lib.rs @@ -0,0 +1,13 @@ +//! Frontend-agnostic artist-vector recommendation engine (ADR-006). +//! +//! Cleanroom port of Tauri's `src-tauri/src/artist_vectors/` into a shared +//! crate so the Slint frontend (and any headless caller) can produce a +//! playlist's "Suggested Songs" without a `tauri::State` dependency. +//! +//! Modules are ported 1:1 from the Tauri source. The dead cosine-similarity / +//! `find_nearest` ranking path is dropped (production ranks by summed +//! relationship weight via the vector store) per the epic's decision D3. + +mod sparse_vector; + +pub use sparse_vector::SparseVector; diff --git a/crates/qbz-reco/src/sparse_vector.rs b/crates/qbz-reco/src/sparse_vector.rs new file mode 100644 index 000000000..b15980dc5 --- /dev/null +++ b/crates/qbz-reco/src/sparse_vector.rs @@ -0,0 +1,395 @@ +//! Sparse vector implementation for artist similarity +//! +//! Efficient representation for high-dimensional vectors where most values are zero. +//! Used to represent artist relationships where each dimension is another artist. + +use serde::{Deserialize, Serialize}; +use std::collections::HashMap; + +/// A sparse vector storing only non-zero values +/// +/// Internally uses parallel vectors for indices and values for memory efficiency. +/// For operations, temporarily converts to HashMap for O(1) lookups. +#[derive(Debug, Clone, Default, Serialize, Deserialize)] +pub struct SparseVector { + /// Sorted indices of non-zero elements + indices: Vec, + /// Values corresponding to indices + values: Vec, +} + +impl SparseVector { + /// Create an empty sparse vector + pub fn new() -> Self { + Self { + indices: Vec::new(), + values: Vec::new(), + } + } + + /// Create a sparse vector with pre-allocated capacity + pub fn with_capacity(capacity: usize) -> Self { + Self { + indices: Vec::with_capacity(capacity), + values: Vec::with_capacity(capacity), + } + } + + /// Create from parallel vectors (must be same length, indices should be sorted) + pub fn from_parts(indices: Vec, values: Vec) -> Self { + debug_assert_eq!(indices.len(), values.len()); + Self { indices, values } + } + + /// Set a value at the given index + /// + /// If the value is 0 (or very close), removes the entry. + /// If the index exists, updates the value. + /// If the index doesn't exist, inserts in sorted order. + pub fn set(&mut self, idx: u32, value: f32) { + // Ignore near-zero values + if value.abs() < 1e-9 { + self.remove(idx); + return; + } + + match self.indices.binary_search(&idx) { + Ok(pos) => { + // Index exists, update value + self.values[pos] = value; + } + Err(pos) => { + // Index doesn't exist, insert at sorted position + self.indices.insert(pos, idx); + self.values.insert(pos, value); + } + } + } + + /// Get the value at the given index (returns 0 if not present) + pub fn get(&self, idx: u32) -> f32 { + match self.indices.binary_search(&idx) { + Ok(pos) => self.values[pos], + Err(_) => 0.0, + } + } + + /// Remove an entry by index + pub fn remove(&mut self, idx: u32) { + if let Ok(pos) = self.indices.binary_search(&idx) { + self.indices.remove(pos); + self.values.remove(pos); + } + } + + /// Number of non-zero elements + pub fn nnz(&self) -> usize { + self.indices.len() + } + + /// Check if vector is empty (all zeros) + pub fn is_empty(&self) -> bool { + self.indices.is_empty() + } + + /// Get indices of non-zero elements + pub fn indices(&self) -> &[u32] { + &self.indices + } + + /// Get values of non-zero elements + pub fn values(&self) -> &[f32] { + &self.values + } + + /// Iterate over (index, value) pairs + pub fn iter(&self) -> impl Iterator + '_ { + self.indices + .iter() + .copied() + .zip(self.values.iter().copied()) + } + + /// Add two sparse vectors element-wise + pub fn add(&self, other: &SparseVector) -> SparseVector { + let mut result = HashMap::new(); + + // Add all elements from self + for (idx, val) in self.iter() { + *result.entry(idx).or_insert(0.0) += val; + } + + // Add all elements from other + for (idx, val) in other.iter() { + *result.entry(idx).or_insert(0.0) += val; + } + + // Convert back to sparse vector + let mut indices: Vec = result.keys().copied().collect(); + indices.sort_unstable(); + + let values: Vec = indices.iter().map(|idx| result[idx]).collect(); + + SparseVector { indices, values } + } + + /// Subtract another vector from this one (self - other) + pub fn sub(&self, other: &SparseVector) -> SparseVector { + let mut result = HashMap::new(); + + for (idx, val) in self.iter() { + *result.entry(idx).or_insert(0.0) += val; + } + + for (idx, val) in other.iter() { + *result.entry(idx).or_insert(0.0) -= val; + } + + let mut indices: Vec = result + .iter() + .filter(|(_, v)| v.abs() > 1e-9) + .map(|(k, _)| *k) + .collect(); + indices.sort_unstable(); + + let values: Vec = indices.iter().map(|idx| result[idx]).collect(); + + SparseVector { indices, values } + } + + /// Scale vector by a scalar + pub fn scale(&self, scalar: f32) -> SparseVector { + SparseVector { + indices: self.indices.clone(), + values: self.values.iter().map(|v| v * scalar).collect(), + } + } + + /// Compute dot product with another sparse vector + pub fn dot(&self, other: &SparseVector) -> f32 { + let mut sum = 0.0; + let mut i = 0; + let mut j = 0; + + // Merge-style iteration (both vectors are sorted by index) + while i < self.indices.len() && j < other.indices.len() { + match self.indices[i].cmp(&other.indices[j]) { + std::cmp::Ordering::Less => i += 1, + std::cmp::Ordering::Greater => j += 1, + std::cmp::Ordering::Equal => { + sum += self.values[i] * other.values[j]; + i += 1; + j += 1; + } + } + } + + sum + } + + /// Compute L2 norm (magnitude) of the vector + pub fn magnitude(&self) -> f32 { + self.values.iter().map(|v| v * v).sum::().sqrt() + } + + /// Normalize the vector to unit length + /// + /// Returns a zero vector if magnitude is zero. + pub fn normalize(&self) -> SparseVector { + let mag = self.magnitude(); + if mag < 1e-9 { + return SparseVector::new(); + } + + SparseVector { + indices: self.indices.clone(), + values: self.values.iter().map(|v| v / mag).collect(), + } + } + + /// Compute cosine similarity with another vector + /// + /// Returns 0 if either vector has zero magnitude. + /// Result is in range [-1, 1], where 1 means identical direction. + /// + /// NOTE: ported for parity + test coverage, but NOT used for ranking + /// (production ranks by summed relationship weight; epic decision D3). + pub fn cosine_similarity(&self, other: &SparseVector) -> f32 { + let dot = self.dot(other); + let mag_self = self.magnitude(); + let mag_other = other.magnitude(); + + if mag_self < 1e-9 || mag_other < 1e-9 { + return 0.0; + } + + dot / (mag_self * mag_other) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_set_and_get() { + let mut vec = SparseVector::new(); + vec.set(5, 1.0); + vec.set(10, 2.0); + vec.set(3, 0.5); + + assert_eq!(vec.get(5), 1.0); + assert_eq!(vec.get(10), 2.0); + assert_eq!(vec.get(3), 0.5); + assert_eq!(vec.get(7), 0.0); // Not set + assert_eq!(vec.nnz(), 3); + + // Indices should be sorted + assert_eq!(vec.indices(), &[3, 5, 10]); + } + + #[test] + fn test_update_value() { + let mut vec = SparseVector::new(); + vec.set(5, 1.0); + vec.set(5, 2.0); + + assert_eq!(vec.get(5), 2.0); + assert_eq!(vec.nnz(), 1); + } + + #[test] + fn test_remove_on_zero() { + let mut vec = SparseVector::new(); + vec.set(5, 1.0); + vec.set(5, 0.0); + + assert_eq!(vec.get(5), 0.0); + assert_eq!(vec.nnz(), 0); + } + + #[test] + fn test_add() { + let mut a = SparseVector::new(); + a.set(1, 1.0); + a.set(3, 2.0); + + let mut b = SparseVector::new(); + b.set(2, 1.5); + b.set(3, 0.5); + + let c = a.add(&b); + + assert_eq!(c.get(1), 1.0); + assert_eq!(c.get(2), 1.5); + assert_eq!(c.get(3), 2.5); + assert_eq!(c.nnz(), 3); + } + + #[test] + fn test_dot_product() { + let mut a = SparseVector::new(); + a.set(1, 2.0); + a.set(3, 3.0); + + let mut b = SparseVector::new(); + b.set(1, 4.0); + b.set(2, 5.0); + b.set(3, 1.0); + + // dot = 2*4 + 3*1 = 11 + assert_eq!(a.dot(&b), 11.0); + } + + #[test] + fn test_magnitude() { + let mut vec = SparseVector::new(); + vec.set(0, 3.0); + vec.set(1, 4.0); + + // magnitude = sqrt(9 + 16) = 5 + assert!((vec.magnitude() - 5.0).abs() < 1e-6); + } + + #[test] + fn test_normalize() { + let mut vec = SparseVector::new(); + vec.set(0, 3.0); + vec.set(1, 4.0); + + let normalized = vec.normalize(); + + assert!((normalized.magnitude() - 1.0).abs() < 1e-6); + assert!((normalized.get(0) - 0.6).abs() < 1e-6); + assert!((normalized.get(1) - 0.8).abs() < 1e-6); + } + + #[test] + fn test_cosine_similarity_identical() { + let mut vec = SparseVector::new(); + vec.set(0, 1.0); + vec.set(1, 2.0); + + let sim = vec.cosine_similarity(&vec); + assert!((sim - 1.0).abs() < 1e-6); + } + + #[test] + fn test_cosine_similarity_orthogonal() { + let mut a = SparseVector::new(); + a.set(0, 1.0); + + let mut b = SparseVector::new(); + b.set(1, 1.0); + + let sim = a.cosine_similarity(&b); + assert!(sim.abs() < 1e-6); + } + + #[test] + fn test_cosine_similarity_similar() { + let mut a = SparseVector::new(); + a.set(0, 1.0); + a.set(1, 1.0); + + let mut b = SparseVector::new(); + b.set(0, 1.0); + b.set(1, 0.5); + + let sim = a.cosine_similarity(&b); + // Should be high but not 1.0 + assert!(sim > 0.9); + assert!(sim < 1.0); + } + + #[test] + fn test_scale() { + let mut vec = SparseVector::new(); + vec.set(0, 2.0); + vec.set(1, 3.0); + + let scaled = vec.scale(2.0); + + assert_eq!(scaled.get(0), 4.0); + assert_eq!(scaled.get(1), 6.0); + } + + #[test] + fn test_from_parts() { + let vec = SparseVector::from_parts(vec![1, 3, 5], vec![0.5, 1.0, 1.5]); + + assert_eq!(vec.get(1), 0.5); + assert_eq!(vec.get(3), 1.0); + assert_eq!(vec.get(5), 1.5); + assert_eq!(vec.nnz(), 3); + } + + #[test] + fn test_empty_vector() { + let vec = SparseVector::new(); + + assert!(vec.is_empty()); + assert_eq!(vec.magnitude(), 0.0); + assert_eq!(vec.normalize().nnz(), 0); + } +}