rankfusion
Backend-agnostic rank aggregation, score fusion, and reranking for Rust.
[]
= "0.1"
What it is
rankfusion is not a search engine. It does not perform retrieval and knows
nothing about ANN indexes, BM25, embeddings, databases, documents, or storage.
Its single responsibility: given multiple ranked candidate lists produced by external systems, combine them into one optimized ranking using configurable fusion and reranking strategies.
External sources
│
┌────┼────┐
│ │ │
List A List B List C
│ │ │
└────┼────┘
▼
Rank aggregation (RRF, weighted RRF, linear fusion)
▼
Reranking pipeline (composable, in-place stages)
▼
Final ranked results
It is a generic ranking layer usable by search engines, recommendation systems, RAG pipelines, personalization systems, data discovery — anything that produces ranked candidate lists. Retrieval and ranking are separate concerns; this crate is only the second one.
Quick start
Two retrieval systems answered the same query. Their scores are not comparable — only their order is. RRF turns that into one ranking:
use ;
let vector_search: = .into_iter.collect;
let keyword_search: = .into_iter.collect;
let freshness_boost = ;
let results = new
.reranker
.reranker
.rank
.unwrap;
assert_eq!; // ranked highly by both sources
Runnable examples live in examples/: cargo run --example basic_rrf, --example explain, --example pipeline.
Features
- Core data model —
Candidate<Id, Metadata>with generic identifiers (u64, UUID,String, custom) and opaque metadata; explicit merge policy for candidates appearing in multiple lists. - Fusion strategies — Reciprocal Rank Fusion (RRF), weighted RRF, linear
score fusion.
O(total_candidates + n log n), hash-map accumulation, no quadratic scans. - Score normalization — min-max, z-score, softmax, with explicit edge-case policies (single-element lists, NaN, ±inf).
- Reranking pipeline — composable, synchronous, in-place
Rerankerstages (freshness boost, business rules, custom scoring). Async rerankers adapt outside the core. - Explainability — per-source score contribution tracing via
fuse_explained, off the hot path.
Optional feature flags
| Feature | Effect |
|---|---|
ahash |
Faster hashing for the fusion accumulators; std::collections::HashMap by default. |
eval |
Ranking-quality metrics: ndcg@k, MRR, recall@k. Zero extra dependencies. |
serde |
Serialize/Deserialize on the core data model and explainability types. |
Minimum supported Rust version: 1.71, verified in CI against the committed
Cargo.lock. Raising it is a breaking change and comes with a minor version
bump.
Evaluating your fusion config
The optional eval feature ships ndcg@k, MRR and recall@k to compare
fusion configurations against your own ground truth — RRF k=60 vs k=20,
RRF vs linear fusion, weight tuning:
= { = "0.1", = ["eval"] }
use ndcg_at_k;
// fuse with each candidate config, then score the rankings against judgments
let quality = ndcg_at_k;
Criterion benchmarks live in benches/ (cargo bench) and back the
O(total + n log n) complexity claim.
Non-goals
ANN indexes, vector databases, BM25, tokenizers, embeddings, document storage, query parsing. Those belong to the external systems feeding this library.
Contributing
See CONTRIBUTING.md for the design invariants and the checks CI enforces. Vulnerabilities: SECURITY.md.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.