second-brain-core 0.9.0

Core library for second-brain: KuzuDB graph storage, BGE embeddings, and weighted query engine
Documentation
use std::collections::HashMap;

use uuid::Uuid;

pub const RRF_K: f32 = 60.0;

/// Reciprocal rank fusion over any number of ranked id lists. Each list
/// contributes 1/(k + rank) with 1-based ranks; ids on multiple lists sum.
/// Ties break on the id bytes so fusion is deterministic across runs.
pub fn fuse(rankings: &[&[Uuid]], k: f32, top: usize) -> Vec<(Uuid, f32)> {
    let mut scores: HashMap<Uuid, f32> = HashMap::new();
    for list in rankings {
        for (rank, id) in list.iter().enumerate() {
            *scores.entry(*id).or_insert(0.0) += 1.0 / (k + (rank + 1) as f32);
        }
    }
    let mut fused: Vec<(Uuid, f32)> = scores.into_iter().collect();
    fused.sort_by(|a, b| {
        b.1.partial_cmp(&a.1)
            .unwrap_or(std::cmp::Ordering::Equal)
            .then_with(|| a.0.cmp(&b.0))
    });
    fused.truncate(top);
    fused
}

#[cfg(test)]
mod tests {
    use super::*;

    fn ids(n: usize) -> Vec<Uuid> {
        (0..n).map(|_| Uuid::new_v4()).collect()
    }

    #[test]
    fn id_on_both_lists_outranks_single_list_leaders() {
        let shared = Uuid::new_v4();
        let dense = [vec![shared], ids(3)].concat();
        let lexical = [ids(2), vec![shared]].concat();

        let fused = fuse(&[&dense, &lexical], RRF_K, 10);
        assert_eq!(
            fused[0].0, shared,
            "rank 1 + rank 3 must beat any single-list id"
        );
        let expected = 1.0 / (RRF_K + 1.0) + 1.0 / (RRF_K + 3.0);
        assert!((fused[0].1 - expected).abs() < 1e-6);
    }

    #[test]
    fn preserves_order_within_a_single_list() {
        let dense = ids(5);
        let fused = fuse(&[&dense], RRF_K, 10);
        let fused_ids: Vec<Uuid> = fused.iter().map(|(id, _)| *id).collect();
        assert_eq!(fused_ids, dense);
    }

    #[test]
    fn truncates_to_top() {
        let dense = ids(200);
        assert_eq!(fuse(&[&dense], RRF_K, 100).len(), 100);
    }

    #[test]
    fn deterministic_on_score_ties() {
        let a = ids(4);
        let b: Vec<Uuid> = a.iter().rev().cloned().collect();
        // Every id gets rank r in one list and (n+1-r) in the other: all tie.
        let first = fuse(&[&a, &b], RRF_K, 10);
        let second = fuse(&[&a, &b], RRF_K, 10);
        assert_eq!(first, second);
    }
}