snapvec

Fast compressed approximate nearest-neighbor search. NumPy + Cython compiled kernels.

Four index types for embedding vector search, each targeting a different point on the accuracy / storage / latency frontier:

Index	Training	Compression	Recall	Use when
SnapIndex	none	6-12x	0.92+	Any distribution, no corpus sample
ResidualSnapIndex	none	4-8x	0.96	Higher recall, still training-free
PQSnapIndex	one-off fit	24-96x	0.95	Modern LLM embeddings, aggressive compression
IVFPQSnapIndex	one-off fit	24-96x	0.98	Sub-linear search at scale (N > 100k)

Three numbers from v0.11.0 on BEIR FIQA (N = 57,638, dim = 384 BGE-small, Apple M4 Pro, single-thread, 200 queries, point area proportional to on-disk footprint):

• 0.945 recall @ 345 us: IVFPQ + fp16 rerank. Pareto-dominant under 500 us on this corpus.
• 0.895 recall @ 319 us: IVFPQ at matched FAISS M=192 budget (12.6 MB). 1.4x faster than FAISS at essentially the same recall.
• 0.649 recall @ 263 us at 4.9 MB: IVFPQ + OPQ at the aggressive M=48 corner. Beats FAISS IVFPQ M=48 on recall (+4.6 pp) at comparable disk; FAISS wins the same corner on latency (144 us).

Scope: one dataset, one hardware class. Run python experiments/bench_competitive.py on your own corpus before citing these as general claims. See benchmarks for the full matched-budget table, OPQ recall-vs-M sweep, threading curve, and N-scaling comparison vs sqlite-vec.

Install

pip install snapvec

On macOS you also need brew install libomp to build from source; the wheels on PyPI bundle it.

Quickstart

import numpy as np
from snapvec import SnapIndex

rng = np.random.default_rng(0)
corpus = rng.standard_normal((10_000, 384)).astype(np.float32)

idx = SnapIndex(dim=384, bits=4, seed=0)
idx.add_batch(list(range(10_000)), corpus)

query = rng.standard_normal(384).astype(np.float32)
for doc_id, score in idx.search(query, k=10):
    print(doc_id, score)

idx.save("my.snpv")

Runnable end-to-end scripts for every index live in examples/.

Documentation

Full docs: https://stffns.github.io/snapvec/

• Installation
• Choosing an index
• Architecture (RHT, Lloyd-Max, PQ, IVF)
• Benchmarks
• API reference

Context

snapvec was developed as the quantization layer for vstash, a local-first hybrid retrieval system, to extend it to corpora beyond the float32 memory budget while preserving its dependency-minimal design. It stands alone as a quantization library, but the design constraints (NumPy-only base install, predictable latency, reproducible index files) come from vstash's local-first requirements.

Roadmap

See ROADMAP.md for planned work and explicit non-goals.

Contributing

See CONTRIBUTING.md for dev setup, the test matrix, and the release process. Bugs and feature requests go to issues; questions and usage help to discussions.

License

MIT (c) 2025 Jayson Steffens.

The TurboQuant algorithm is described in arXiv:2504.19874 by Zandieh et al. (Google Research / ICLR 2026). This package is an independent implementation.