rankops

Operations on ranked lists: fuse multiple retrievers, then rerank. Pairs with rankfns (scoring kernels).

rankops covers the post-retrieval pipeline:

• Fusion -- combine ranked lists from heterogeneous retrievers (BM25, dense, sparse)
• Reranking -- MaxSim/ColBERT late interaction, MMR/DPP diversity, Matryoshka two-stage
• Evaluation -- NDCG, MAP, MRR, Precision@k, recall@k, Hit Rate, fusion parameter optimization
• Diagnostics -- complementarity analysis, score distribution stats, fusion recommendations

Quickstart

[dependencies]
rankops = "0.1.4"

Fusion

Fuse two ranked lists with Reciprocal Rank Fusion (score-agnostic, works across incompatible scales):

use rankops::rrf;

let bm25  = vec![("doc_a", 12.5), ("doc_b", 11.0), ("doc_c", 9.2)];
let dense = vec![("doc_b", 0.95), ("doc_c", 0.88), ("doc_d", 0.70)];

let fused = rrf(&bm25, &dense);
// doc_b ranks highest: appears in both lists
assert_eq!(fused[0].0, "doc_b");

Score-based fusion when scales are comparable:

use rankops::combmnz;

let fused = combmnz(&bm25, &dense);
// CombMNZ: sum of normalized scores * overlap count

Select the algorithm at runtime via FusionMethod:

use rankops::FusionMethod;

let method = FusionMethod::Rrf { k: 60 };
let result = method.fuse(&bm25, &dense);

Diversity reranking (requires rerank feature, on by default)

use rankops::rerank::diversity::{mmr, MmrConfig};

let candidates = vec![("d1", 0.95), ("d2", 0.90), ("d3", 0.85)];
let similarity = vec![
    1.0, 0.9, 0.2,
    0.9, 1.0, 0.3,
    0.2, 0.3, 1.0,
];

let config = MmrConfig::default().with_lambda(0.5).with_k(2);
let selected = mmr(&candidates, &similarity, config);
// Picks d1 (highest relevance), then d3 (diverse from d1)

Fusion algorithms

All two-list functions have *_multi variants for 3+ lists. Explainability variants (rrf_explain, combsum_explain, etc.) return full provenance.

Normalization

Score normalization for cross-retriever fusion via Normalization enum:

Evaluation

Diagnostics

The diagnostics module helps decide whether fusion is beneficial:

Based on Louis et al., "Know When to Fuse" (2024): high complementarity (>0.5) predicts fusion benefit; low correlation between rankers predicts fusion benefit.

Adapters

The adapt module converts retriever outputs to rankops format:

All have _mapped variants for ID type conversion (e.g., u32 doc index to &str doc name).

Pipeline

The pipeline module provides composable post-retrieval operations:

use rankops::pipeline::Pipeline;
use rankops::{FusionMethod, Normalization};

let result = Pipeline::new()
    .add_run("bm25", &bm25)
    .add_run("dense", &dense)
    .normalize(Normalization::MinMax)
    .fuse(FusionMethod::rrf())
    .top_k(10)
    .execute();

Also: compare() for method comparison, fuse_multi_query() for the N-queries x M-retrievers RAG pattern.

Reranking (feature: rerank)

Features

Examples

cargo run --example fusion            # All fusion methods side-by-side
cargo run --example hybrid_search     # End-to-end: BM25 + dense -> fuse -> rerank -> eval
cargo run --example evaluate          # Metrics, diagnostics, pipeline, method comparison
cargo run --example rerank_maxsim     # ColBERT MaxSim scoring
cargo run --example diversity         # MMR and DPP diversity reranking

See also

• rankfns -- scoring kernels (BM25, TF-IDF, cosine) that pair with rankops
• innr -- SIMD dot product and MaxSim primitives used by the rerank feature
• vicinity -- ANN vector search (HNSW, IVF-PQ) that feeds ranked candidates to rankops
• rankit -- learning-to-rank training (LTR losses, differentiable sorting, evaluation)

License

MIT OR Apache-2.0