rank-refine

SIMD-accelerated similarity scoring for vector search and RAG. Provides MaxSim (ColBERT/ColPali), cosine similarity, diversity selection (MMR, DPP), token pooling, token-level alignment/highlighting, and Matryoshka refinement. Supports both text (ColBERT) and multimodal (ColPali) late interaction.

Why Late Interaction?

Dense embeddings compress query and document into single vectors, losing token-level matching. Late interaction (MaxSim) computes token-level similarities and aggregates them, preserving semantic matching while enabling efficient retrieval.

This repository contains a Cargo workspace with multiple crates:

• rank-refine — Core library (SIMD-accelerated)
• rank-refine-python — Python bindings using PyO3
• fuzz — Fuzzing targets

Quick Start

Rust

cargo add rank-refine

use rank_refine::simd;

// Dense scoring
let score = simd::cosine(&[1.0, 0.0], &[0.707, 0.707]);

// Late interaction (ColBERT MaxSim)
let query = vec![vec![1.0, 0.0], vec![0.0, 1.0]];
let doc = vec![vec![0.9, 0.1], vec![0.1, 0.9]];
let score = simd::maxsim_vecs(&query, &doc);

Python

Install from PyPI:

pip install rank-refine

import rank_refine

# Dense cosine similarity
query = [1.0, 0.0]
doc = [0.707, 0.707]
score = rank_refine.cosine(query, doc)

# MaxSim (late interaction)
query_tokens = [[1.0, 0.0], [0.0, 1.0]]
doc_tokens = [[0.9, 0.1], [0.1, 0.9]]
score = rank_refine.maxsim_vecs(query_tokens, doc_tokens)

For development/contributing:

cd rank-refine-python
uv venv
source .venv/bin/activate
uv tool install maturin
maturin develop --uv

Or using pip:

cd rank-refine-python
pip install maturin
maturin develop --release

Node.js / WebAssembly

Install from npm:

npm install @arclabs561/rank-refine

Usage in Node.js:

const { cosine, maxsim_vecs } = require('@arclabs561/rank-refine');

// Dense cosine similarity
const query = new Float32Array([1.0, 0.0]);
const doc = new Float32Array([0.707, 0.707]);
const score = cosine(query, doc);

// MaxSim (late interaction / ColBERT)
const query_tokens = [
  new Float32Array([1.0, 0.0]),
  new Float32Array([0.0, 1.0])
];
const doc_tokens = [
  new Float32Array([0.9, 0.1]),
  new Float32Array([0.1, 0.9])
];
const maxsim_score = maxsim_vecs(query_tokens, doc_tokens);

Usage in TypeScript:

import { cosine, maxsim_vecs } from '@arclabs561/rank-refine';

const query = new Float32Array([1.0, 0.0]);
const doc = new Float32Array([0.707, 0.707]);
const score = cosine(query, doc);

Usage in Browser (ES Modules):

import init, { cosine, maxsim_vecs } from '@arclabs561/rank-refine';

async function computeSimilarity() {
  // Initialize WASM module
  await init();
  
  // Dense similarity
  const query = new Float32Array([1.0, 0.0]);
  const doc = new Float32Array([0.707, 0.707]);
  const score = cosine(query, doc);
  
  // MaxSim for late interaction
  const query_tokens = [
    new Float32Array([1.0, 0.0]),
    new Float32Array([0.0, 1.0])
  ];
  const doc_tokens = [
    new Float32Array([0.9, 0.1]),
    new Float32Array([0.1, 0.9])
  ];
  const maxsim_score = maxsim_vecs(query_tokens, doc_tokens);
  
  console.log("Cosine:", score);
  console.log("MaxSim:", maxsim_score);
}

computeSimilarity();

Documentation

• Core crate documentation
• Python bindings
• Additional Documentation - Integration guides, design docs, and more

Development

# Build core crate (fast, no Python required)
cargo build -p rank-refine

# Build all workspace members
cargo build --workspace

# Test core crate
cargo test -p rank-refine

# Test all workspace members
cargo test --workspace

# Check Python bindings (requires Python installed)
cargo check -p rank-refine-python

# Build Python bindings with uv
cd rank-refine-python
uv venv
source .venv/bin/activate
uv tool install maturin
maturin develop --uv

Workspace Structure

This repository uses a Cargo workspace to organize the codebase:

• Shared target directory — All crates compile to one target/ directory
• Workspace inheritance — Dependencies and versions defined once at workspace root
• Path dependencies — Python crate depends on core via path (no version conflicts)
• Default members — Only core crate builds by default (cargo build)

See Also

• rank-fusion: Combine ranked lists from multiple retrievers (RRF, CombMNZ, etc.)
• rank-relax: Differentiable ranking and sorting operations
• rank-eval: IR evaluation metrics and TREC format parsing
• Integration Examples: Complete pipelines using multiple rank-* crates together