turbovec

Clone & Build

git clone https://github.com/moses-y/turbovec
cd turbovec
# Rust library
cargo build --release
# Python bindings (requires maturin)
pip install -e turbovec-python

The Problem

Applications that need fast nearest‑neighbor search on very large vector collections often rely on trained quantizers (e.g., FAISS PQ). Training adds latency, requires re‑training when data changes, and increases operational complexity.

What This Does

turbovec implements TurboQuant, a data‑oblivious quantizer that compresses each vector to 2–4 bits per dimension without a training phase. The core Rust code lives in turbovec/src/ (codebook.rs, encode.rs, io.rs, pack.rs, rotation.rs, search.rs). Python users access the same logic through the binding in turbovec-python/src/lib.rs, exposing TurboQuantIndex. Benchmarks and result visualisations are under benchmarks/ and docs/.

How It Is Wired

Entry point – the benchmark driver benchmarks/suite/compression.py defines main (line 50) which calls load_openai, load_glove, measure_index_size, then creates a TurboQuantIndex via the Python binding.

Control flow – main → TurboQuantIndex.add (binding → Rust turbovec/src/encode.rs) → TurboQuantIndex.search (binding → Rust turbovec/src/search.rs).

External effects – only two kinds appear: file I/O (os.remove in measure_index_size) and external command execution in benchmarks/download_data.py (uses os.system to fetch datasets).

Responsibility map (high‑fan‑in files first):

File	Core duties
`benchmarks/download_data.py`	Reads/writes files, runs `wget`/`curl` to fetch GloVe and OpenAI datasets.
`benchmarks/create_diagrams.py`	Generates SVG panels (`xe`, `nice_ceil`, `style_block`, `grid_lines`, `paired_panel`).
`benchmarks/suite/compression.py`	Loads data, measures index size, invokes the Python API.
`benchmarks/suite/recall_.py` & `benchmarks/suite/speed_.py`	Load vectors, call `recall_at_1_at_k`, report timings.
`turbovec/src/search.rs`	Implements the nearest‑neighbor search loop (largest file, 940 LOC).
`turbovec/src/io.rs`	Handles serialization/deserialization of the index file.
`turbovec/src/codebook.rs`, `turbovec/src/pack.rs`	Encode/decode logic, rotation handling.

The internal call graph shows a few hot spots: the function xe (used in 7 places) and grid_lines (3 places) are visualisation helpers; load_openai and load_json are each called twice from benchmark scripts. No circular imports were detected.

How To Use It

Install – pip install turbovec (pre‑built wheels) or use the local source as shown above.
Create an index – in Python: ``python from turbovec import TurboQuantIndex idx = TurboQuantIndex(dim=1536, bit_width=4) idx.add(vectors) # vectors is a NumPy array scores, ids = idx.search(query, k=10) idx.write("my_index.tq") ``
Rust usage – after cargo add turbovec: ``rust use turbovec::TurboQuantIndex; let mut idx = TurboQuantIndex::new(1536, 4); idx.add(&vectors); let results = idx.search(&queries, 10); idx.write("my_index.tq")?; ``

No additional configuration files or environment variables are required.

Real‑World Use

A recommendation engine can store user‑item embeddings in a TurboQuant index, update it continuously (no retraining), and serve top‑k recommendations with sub‑millisecond latency. Example workflow:

# daily pipeline
idx = TurboQuantIndex(dim=200, bit_width=2)
idx.add(new_user_vectors)          # incremental add
idx.write("daily.tq")
# serving layer
idx = TurboQuantIndex.load("daily.tq")
scores, ids = idx.search(current_query, k=5)

Code Health & Issues

HIGH – Pin third‑party GitHub Actions to a commit SHA (.github/workflows/release.yml).
MEDIUM – Enable Dependabot or Renovate (.github/dependabot.yml missing).
MEDIUM – Add a dependency‑vulnerability scan to CI (dependency-review-action or osv-scanner).
MEDIUM – Expand test suite (1 test file vs 34 source files).
LOW – Set timeout-minutes on workflow jobs (release.yml lacks explicit timeout).

Additional observations: deep nesting (max depth 11) in turbovec/src/search.rs, codebook.rs, pack.rs; duplicated 6‑line blocks across many benchmark scripts; oversized search.rs (940 lines) and high branching density in io.rs. These increase cognitive load and risk when modifying the core search logic.

The Bottom Line

turbovec delivers a fast, training‑free vector index with a clean Rust core and ready‑to‑use Python bindings. It is production‑ready for static‑embedding workloads but would benefit from a richer test suite, tighter CI security controls, and refactoring of the most complex Rust modules before extensive custom development. Suitable for teams that prioritize low‑latency search and minimal data‑pipeline overhead.