From 7049a9f0d9ce689f337a91859740decf43196591 Mon Sep 17 00:00:00 2001 From: vicrodh <103399283+vicrodh@users.noreply.github.com> Date: Fri, 26 Jun 2026 20:34:25 -0600 Subject: [PATCH] feat(reco): port ArtistVectorBuilder on the crate clients T4: 1:1 port of the artist_vectors vector builder into qbz-reco. Keeps Tauri's Arc/RwLock ownership of the store + MusicBrainz client/cache + Qobuz client (NOT the plan's by-ref pattern): MusicBrainzCache holds a !Sync rusqlite Connection, so a borrowed &cache held across the MB-API await would make the spawned suggestions future !Send. The interleaved short-lived locking (drop the guard before each await) is the faithful + Send-safe shape. Swaps only crate::api::QobuzClient -> qbz_qobuz::QobuzClient (get_similar_artists -> SearchResultsPage); the MusicBrainz types already live in qbz_integrations so extract_relationships ports verbatim. Drops the dead resolve_qobuz_to_mbid (D3). 21 qbz-reco tests green. cc --- crates/Cargo.lock | 3 + crates/qbz-reco/Cargo.toml | 3 + crates/qbz-reco/src/builder.rs | 395 +++++++++++++++++++++++++++++++++ crates/qbz-reco/src/lib.rs | 2 + 4 files changed, 403 insertions(+) create mode 100644 crates/qbz-reco/src/builder.rs diff --git a/crates/Cargo.lock b/crates/Cargo.lock index e086fe2a7..5f77ef4a0 100644 --- a/crates/Cargo.lock +++ b/crates/Cargo.lock @@ -5822,8 +5822,11 @@ name = "qbz-reco" version = "0.1.0" dependencies = [ "log", + "qbz-integrations", + "qbz-qobuz", "rusqlite", "serde", + "tokio", ] [[package]] diff --git a/crates/qbz-reco/Cargo.toml b/crates/qbz-reco/Cargo.toml index 4abe94745..a98368872 100644 --- a/crates/qbz-reco/Cargo.toml +++ b/crates/qbz-reco/Cargo.toml @@ -9,3 +9,6 @@ description = "Frontend-agnostic artist-vector recommendation engine for QBZ (po serde = { workspace = true } rusqlite = { version = "0.31", features = ["bundled"] } log = { workspace = true } +tokio = { workspace = true } +qbz-qobuz = { path = "../qbz-qobuz" } +qbz-integrations = { path = "../qbz-integrations" } diff --git a/crates/qbz-reco/src/builder.rs b/crates/qbz-reco/src/builder.rs new file mode 100644 index 000000000..4ceafca48 --- /dev/null +++ b/crates/qbz-reco/src/builder.rs @@ -0,0 +1,395 @@ +//! Vector builder - constructs artist vectors from MusicBrainz and Qobuz data +//! +//! Integrates with MusicBrainz for relationship data and Qobuz for similarity +//! data to build sparse vectors for each artist. Ported 1:1 from the Tauri +//! `artist_vectors::builder`, keeping its `Arc` ownership: the +//! MusicBrainz cache holds a `!Sync` rusqlite `Connection`, so the clients + +//! store are held behind Send+Sync handles and locked only for short, +//! await-free windows — otherwise the suggestions future (which runs on a +//! spawned task) would not be `Send`. The dead `resolve_qobuz_to_mbid` helper +//! (epic D3) is dropped. Only the Qobuz client type is swapped to +//! `qbz_qobuz::QobuzClient`; the MusicBrainz types already live in +//! `qbz_integrations`. + +use std::sync::Arc; +use tokio::sync::{Mutex, RwLock}; + +use qbz_integrations::musicbrainz::cache::MusicBrainzCache; +use qbz_integrations::musicbrainz::{ArtistFullResponse, ArtistRelationships, Period, RelatedArtist}; +use qbz_integrations::MusicBrainzClient; +use qbz_qobuz::QobuzClient; + +use crate::sparse_vector::SparseVector; +use crate::store::ArtistVectorStore; +use crate::weights::RelationshipWeights; + +/// Builder for constructing artist vectors from multiple data sources +pub struct ArtistVectorBuilder { + /// Vector store for persistence + store: Arc>>, + /// MusicBrainz client for relationship data (behind Mutex for shared ownership) + mb_client: Arc>, + /// MusicBrainz cache + mb_cache: Arc>>, + /// Qobuz client for similar artists + qobuz_client: Arc>, + /// Configurable weights + weights: RelationshipWeights, +} + +/// Result of building a vector +#[derive(Debug, Clone)] +pub struct BuildResult { + /// The built vector + pub vector: SparseVector, + /// Number of MusicBrainz relationships found + pub mb_relations_count: usize, + /// Number of Qobuz similar artists found + pub qobuz_similar_count: usize, + /// Sources that contributed to the vector + pub sources: Vec, +} + +impl ArtistVectorBuilder { + /// Create a new builder with the given dependencies + pub fn new( + store: Arc>>, + mb_client: Arc>, + mb_cache: Arc>>, + qobuz_client: Arc>, + weights: RelationshipWeights, + ) -> Self { + Self { + store, + mb_client, + mb_cache, + qobuz_client, + weights, + } + } + + /// Build a vector for an artist, fetching data from all sources. + /// + /// 1. Fetches MusicBrainz relationships (members, groups, collaborators) + /// 2. Fetches Qobuz similar artists (if Qobuz ID available) + /// 3. Combines all data into a weighted sparse vector + /// 4. Persists the vector to the store + pub async fn build_vector( + &self, + artist_mbid: &str, + artist_name: Option<&str>, + qobuz_artist_id: Option, + ) -> Result { + let mut vector = SparseVector::new(); + let mut sources = Vec::new(); + let mut mb_relations_count = 0; + let mut qobuz_similar_count = 0; + + // Store vectors for later persistence (to avoid holding the store lock + // across the network awaits). + let mut mb_vec_to_store: Option = None; + let mut qobuz_vec_to_store: Option = None; + + // 1. Get or create index for this artist + { + let mut guard__ = self.store.lock().await; + let store = guard__ + .as_mut() + .ok_or("No active session - please log in")?; + store.get_or_create_idx(artist_mbid, artist_name)?; + } + + // 2. Fetch MusicBrainz relationships + match self.build_from_musicbrainz(artist_mbid).await { + Ok((mb_vec, count)) => { + vector = vector.add(&mb_vec); + mb_relations_count = count; + if count > 0 { + sources.push("musicbrainz".to_string()); + mb_vec_to_store = Some(mb_vec); + } + } + Err(e) => { + log::warn!( + "Failed to fetch MusicBrainz relations for {}: {}", + artist_mbid, + e + ); + } + } + + // 3. Fetch Qobuz similar artists (if we have the ID) + if let Some(qobuz_id) = qobuz_artist_id { + match self.build_from_qobuz(qobuz_id).await { + Ok((qobuz_vec, count)) => { + vector = vector.add(&qobuz_vec); + qobuz_similar_count = count; + if count > 0 { + sources.push("qobuz".to_string()); + qobuz_vec_to_store = Some(qobuz_vec); + } + } + Err(e) => { + log::warn!("Failed to fetch Qobuz similar for {}: {}", qobuz_id, e); + } + } + } + + // 4. Persist the vectors (using saved vectors to avoid holding the lock + // across the awaits above). + { + let mut guard__ = self.store.lock().await; + let store = guard__ + .as_mut() + .ok_or("No active session - please log in")?; + + if let Some(mb_vec) = mb_vec_to_store { + store.set_vector(artist_mbid, &mb_vec, "musicbrainz")?; + } + + if let Some(qobuz_vec) = qobuz_vec_to_store { + store.set_vector(artist_mbid, &qobuz_vec, "qobuz")?; + } + } + + Ok(BuildResult { + vector, + mb_relations_count, + qobuz_similar_count, + sources, + }) + } + + /// Build vector component from MusicBrainz relationships + async fn build_from_musicbrainz( + &self, + artist_mbid: &str, + ) -> Result<(SparseVector, usize), String> { + // Try cache first + let cached = { + let guard__ = self.mb_cache.lock().await; + let cache = guard__ + .as_ref() + .ok_or("No active session - please log in")?; + cache.get_artist_relations(artist_mbid)? + }; + + let relations = if let Some(rel) = cached { + rel + } else { + // Fetch from API + let mb_client = self.mb_client.lock().await; + let response = mb_client + .get_artist_with_relations(artist_mbid) + .await + .map_err(|e| e.to_string())?; + drop(mb_client); + + // Extract relationships from raw response + let extracted = extract_relationships(&response); + + // Cache it + { + let guard__ = self.mb_cache.lock().await; + let cache = guard__ + .as_ref() + .ok_or("No active session - please log in")?; + cache.set_artist_relations(artist_mbid, &extracted)?; + } + + extracted + }; + + let mut vector = SparseVector::new(); + let mut count = 0; + + // Get store for index lookups + let mut guard__ = self.store.lock().await; + let store = guard__ + .as_mut() + .ok_or("No active session - please log in")?; + + // Process members (band → person) + for member in &relations.members { + let idx = store.get_or_create_idx(&member.mbid, Some(&member.name))?; + let weight = self.weights.member_of_band; + vector.set(idx, weight); + count += 1; + } + + // Process past members (slightly lower weight) + for member in &relations.past_members { + let idx = store.get_or_create_idx(&member.mbid, Some(&member.name))?; + let weight = self.weights.member_of_band * 0.8; // Past members slightly less relevant + vector.set(idx, weight); + count += 1; + } + + // Process groups (person → band) + for group in &relations.groups { + let idx = store.get_or_create_idx(&group.mbid, Some(&group.name))?; + let weight = self.weights.has_member; + vector.set(idx, weight); + count += 1; + } + + // Process collaborators + for collab in &relations.collaborators { + let idx = store.get_or_create_idx(&collab.mbid, Some(&collab.name))?; + let weight = self.weights.collaboration; + vector.set(idx, weight); + count += 1; + } + + Ok((vector, count)) + } + + /// Build vector component from Qobuz similar artists + async fn build_from_qobuz( + &self, + qobuz_artist_id: u64, + ) -> Result<(SparseVector, usize), String> { + let similar = { + let client = self.qobuz_client.read().await; + client + .get_similar_artists(qobuz_artist_id, 20, 0) + .await + .map_err(|e| format!("Qobuz API error: {}", e))? + }; + + let mut vector = SparseVector::new(); + let mut count = 0; + let mut guard__ = self.store.lock().await; + let store = guard__ + .as_mut() + .ok_or("No active session - please log in")?; + + for artist in similar.items { + // Resolve Qobuz artist to a synthetic MBID node based on Qobuz ID. + let synthetic_mbid = format!("qobuz:{}", artist.id); + + let idx = store.get_or_create_idx(&synthetic_mbid, Some(&artist.name))?; + let weight = self.weights.qobuz_similar; + vector.set(idx, weight); + count += 1; + } + + Ok((vector, count)) + } + + /// Ensure a vector exists and is fresh, building if necessary. + /// + /// Returns true if the vector was built/updated, false if an existing fresh + /// vector was used. + pub async fn ensure_vector( + &self, + artist_mbid: &str, + artist_name: Option<&str>, + qobuz_artist_id: Option, + max_age_days: i64, + ) -> Result { + let max_age_secs = max_age_days * 24 * 60 * 60; + + // Check if we have a fresh vector + let has_fresh = { + let guard__ = self.store.lock().await; + let store = guard__ + .as_ref() + .ok_or("No active session - please log in")?; + store.has_fresh_vector(artist_mbid, max_age_secs) + }; + + if has_fresh { + return Ok(false); + } + + // Build new vector + match self + .build_vector(artist_mbid, artist_name, qobuz_artist_id) + .await + { + Ok(_) => Ok(true), + Err(e) => { + log::error!( + "[VectorBuilder] Failed to build vector for {}: {}", + artist_mbid, + e + ); + Err(e) + } + } + } +} + +/// Extract ArtistRelationships from a raw MusicBrainz response (verbatim port — +/// the only two relation types production uses: `member of band` + `collaboration`). +fn extract_relationships(artist: &ArtistFullResponse) -> ArtistRelationships { + let mut members = Vec::new(); + let mut past_members = Vec::new(); + let mut groups = Vec::new(); + let mut collaborators = Vec::new(); + + if let Some(relations) = &artist.relations { + for relation in relations { + let Some(related_artist) = &relation.artist else { + continue; + }; + + let related = RelatedArtist { + mbid: related_artist.id.clone(), + name: related_artist.name.clone(), + role: relation + .attributes + .as_ref() + .and_then(|a| a.first().cloned()), + period: Some(Period { + begin: relation.begin.clone(), + end: relation.end.clone(), + }), + ended: relation.ended.unwrap_or(false), + }; + + match relation.relation_type.as_str() { + "member of band" => { + if relation.direction.as_deref() == Some("backward") { + // We're viewing a BAND, the related artist is a MEMBER + if related.ended { + past_members.push(related); + } else { + members.push(related); + } + } else { + // We're viewing a PERSON, the related artist is a BAND/GROUP + groups.push(related); + } + } + "collaboration" => { + collaborators.push(related); + } + _ => {} + } + } + } + + ArtistRelationships { + members, + past_members, + groups, + collaborators, + } +} + +#[cfg(test)] +mod tests { + use super::*; + + // Integration tests would require mocking the clients; here we cover the + // weight ordering the builder relies on. + #[test] + fn test_weights_applied() { + let weights = RelationshipWeights::default(); + + assert!(weights.member_of_band > weights.collaboration); + assert!(weights.collaboration > weights.shared_tag); + } +} diff --git a/crates/qbz-reco/src/lib.rs b/crates/qbz-reco/src/lib.rs index d7b32ae60..ebbff7134 100644 --- a/crates/qbz-reco/src/lib.rs +++ b/crates/qbz-reco/src/lib.rs @@ -8,10 +8,12 @@ //! `find_nearest` ranking path is dropped (production ranks by summed //! relationship weight via the vector store) per the epic's decision D3. +mod builder; mod sparse_vector; mod store; mod weights; +pub use builder::{ArtistVectorBuilder, BuildResult}; pub use sparse_vector::SparseVector; pub use store::{ArtistVectorStore, SimilarArtist, VECTOR_TTL_SECS}; pub use weights::RelationshipWeights;