Skip to main content

Crate rankfusion

Crate rankfusion 

Source
Expand description

§rankfusion

Backend-agnostic rank aggregation, score fusion, and reranking.

This library is not a search engine. It does not perform retrieval and knows nothing about ANN, BM25, embeddings, databases, or storage. Its only responsibility: given multiple ranked candidate lists produced by external systems, combine them into a single optimized ranking using configurable fusion and reranking strategies.

External sources ──▶ RankedList / ScoredList ──▶ fusion ──▶ reranking ──▶ Vec<Scored>

§Data model

Rank-based inputs and score-based inputs are distinct types — see the core module docs for the full design rationale (score status, metadata merge policy, NaN policy):

  • RankedList: ordered candidates, rank implicit — feeds rank fusion (RRF).
  • ScoredList: ordered + uniformly scored — feeds score fusion; converts to RankedList for free.
  • Fusion always outputs Scored candidates: a fused score always exists.

§Example

use rankfusion::{Pipeline, RankedList, Rrf, Scored, TopK};

// ranked lists from two external systems (vector search, keyword search…)
let list_a: RankedList<&str> = ["a", "b", "c"].into_iter().collect();
let list_b: RankedList<&str> = ["b", "d", "a"].into_iter().collect();

let freshness_boost = |candidates: &mut Vec<Scored<&str, ()>>| {
    for c in candidates.iter_mut() {
        if *c.id() == "d" {
            c.score *= 1.5;
        }
    }
    candidates.sort_by(Scored::cmp_score_desc);
};

let results = Pipeline::new(Rrf::default())
    .reranker(freshness_boost)
    .reranker(TopK::new(3))
    .rank(vec![list_a, list_b])
    .unwrap();

assert_eq!(results.len(), 3);
assert_eq!(*results[0].id(), "b");

§Feature flags

  • ahash — faster hashing for the fusion accumulators.
  • eval — ranking-quality metrics (ndcg@k, MRR, recall@k), zero extra dependencies.
  • serde — Serialize/Deserialize on the core data model and explainability types.

Re-exports§

pub use crate::core::Candidate;
pub use crate::core::FirstWins;
pub use crate::core::MergePolicy;
pub use crate::core::RankedList;
pub use crate::core::Scored;
pub use crate::core::ScoredList;
pub use crate::explain::Explained;
pub use crate::explain::SourceContribution;
pub use crate::fusion::Fusion;
pub use crate::fusion::FusionError;
pub use crate::fusion::LinearFusion;
pub use crate::fusion::Rrf;
pub use crate::fusion::WeightedRrf;
pub use crate::normalization::MinMax;
pub use crate::normalization::Normalizer;
pub use crate::normalization::Softmax;
pub use crate::normalization::ZScore;
pub use crate::reranking::Pipeline;
pub use crate::reranking::Reranker;
pub use crate::reranking::TopK;

Modules§

core
Core data model: candidates, ranked/scored lists, and merge policy.
eval
Offline ranking evaluation — ndcg@k, MRR, recall@k.
explain
Explainability: per-source contribution tracing.
fusion
Fusion strategies: combine multiple input lists into one scored ranking.
normalization
Score normalization strategies.
reranking
Post-fusion reranking: composable, synchronous, in-place stages.