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
This commit is contained in:
vicrodh committed 2026-06-26 20:15:00 -06:00
1 parent 25ab1408e5
commit 65de984988
5 files changed
+425

No files matched your search

+7
View File
@@ -5817,6 +5817,13 @@ dependencies = [
"rusqlite",
]
[[package]]
name = "qbz-reco"
version = "0.1.0"
dependencies = [
"serde",
]
[[package]]
name = "qbz-secrets"
version = "0.1.0"
+1
View File
@@ -34,6 +34,7 @@ members = [
"qbz-lyrics",
"qbz-i18n",
"qbz-music-link",
"qbz-reco",
]
[workspace.package]
+9
View File
@@ -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 }
+13
View File
@@ -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;
+395
View File
@@ -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<u32>,
/// Values corresponding to indices
values: Vec<f32>,
}
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<u32>, values: Vec<f32>) -> 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<Item = (u32, f32)> + '_ {
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<u32> = result.keys().copied().collect();
indices.sort_unstable();
let values: Vec<f32> = 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<u32> = result
.iter()
.filter(|(_, v)| v.abs() > 1e-9)
.map(|(k, _)| *k)
.collect();
indices.sort_unstable();
let values: Vec<f32> = 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::<f32>().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);
}
}