ordvec (Python)

Python bindings for ordvec — a training-free ordinal & sign vector-quantization library for compressed nearest-neighbour retrieval over high-dimensional embeddings. Pure-Rust core, zero system dependencies; SIMD-accelerated at runtime (AVX-512 / AVX2 / scalar).

import numpy as np
import ordvec

q = ordvec.RankQuant(1024, 2)          # 1024-dim, 2 bits/coord
q.add(np.random.randn(10_000, 1024).astype(np.float32))
# asymmetric: full-precision float queries vs bucketed docs (recommended)
scores, ids = q.search_asymmetric(np.random.randn(8, 1024).astype(np.float32), k=10)

Classes

The Rust crate's b = 8 RankQuant evidence/refinement width is not exposed through the v0.5 Python RankQuant constructor and cannot be persisted to .ovrq; use bits 1, 2, or 4 from Python.

Two-stage retrieval (subset rerank)

A Bitmap / SignBitmap probe yields a candidate shortlist that RankQuant.search_asymmetric_subset(query, candidates, k) reranks exactly:

cands = bm.top_m_candidates(query, m=256)          # uint32 shortlist
scores, ids = rq.search_asymmetric_subset(query, cands, k=10)

Both returned arrays have length min(k, len(candidates)), not k. When k > len(candidates) the result is silently capped to the candidate count — the subset path never pads with sentinel rows. If you assemble a fixed-width (n_q, k) result buffer, size each row by its candidate count rather than assuming k rows back.

Theory and calibration

Bitmap exposes the constant-weight top-bucket overlap statistic formalized in ordvec-formalization. In that finite Lean model, literal bitmap overlap is the query-preserving quotient statistic, an overlap threshold is Bayes-optimal under explicit monotone-overlap assumptions, and the idealized uniform constant-weight null calibrates that threshold by the hypergeometric upper tail.

This is not a deployment guarantee for every encoder or corpus. Real-corpus recall, monotonicity, and null fit remain empirical diagnostics.

Installation

pip install ordvec

Wheels target CPython 3.10+ (abi3) and require numpy>=2.2. Building from source needs a Rust toolchain (MSRV 1.89) and maturin.

Safety contract

The Python binding releases the GIL while Rust searches, scores, and mutates indexes. Inputs that cross a GIL-released call are copied into Rust-owned buffers first, so ordinary Python in-place NumPy mutation from another thread cannot race the detached Rust scan. Large calls may temporarily require an additional input-sized buffer. The cross-language ownership and lifetime contract is maintained in docs/bindings-safety.md for this release line.

Type stubs

The package ships hand-written type stubs (_ordvec.pyi) and a py.typed marker, so editors and mypy get full signatures for the four index classes, the module-level rank-math primitives, and the MAX_* constants — the abi3 native module is otherwise opaque to static analysis.

Provenance & license

The ordvec Python package's active upstream, implementation history, issues, releases, and governance live in Project-Navi/ordvec.

Courtesy note: ordvec was developed using the early turbovec project context as a rapid-development scaffold, with thanks to that lineage. It is not a source fork of turbovec.

Dual-licensed under either of MIT or Apache-2.0 at your option.