snapvec 0.11.0

Fast compressed ANN search via randomized Hadamard transform and optimal Gaussian scalar quantization. NumPy + Cython compiled kernels.

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)

Headline number: recall@10 = 0.977 at 441 us/query on BEIR FIQA (N = 57,638, BGE-small), 25-125x faster than sqlite-vec at comparable recall.

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.