1---2name: "turbovec"3description: "Use the RyanCodrai/turbovec project when integrating its in-process Python or Rust TurboQuant vector index: create an index, quantize/search vectors, persist/load a file, apply ID filters, or choose its framework adapters. Trigger on turbovec or TurboQuantIndex. Route hosted vector databases and replication needs to a server product such as Typesense; turbovec itself is a library, not a network service."4allowed-tools: Bash Read Grep Glob5compatibility: Works with compatible agent clients that can read files and run shell commands; Python wheels include a native Rust extension and Rust use requires a 64-bit target.6metadata:7 version: "1.0.0"8 source: https://skillmd.com/skills/akillness/turbovec9 upstream: "https://github.com/RyanCodrai/turbovec"10 upstream_commit: "c3b043b992290ff223b903046af7f6683768241c"11---1213# turbovec operator1415## Instructions16171. **Check the actual checkout and source pin.** From the jeo-skills repository root run `python3 .agent-skills/turbovec/scripts/preflight.py --repo /absolute/upstream --json`; from an installed copy, use its `scripts/preflight.py`. No `--repo` means inventory only. The helper checks selected pinned-file hashes, not Git HEAD, the entire source tree, dependency installation, or execution. See [pinned source notes](references/upstream.md).182. **Choose the library surface.** Python imports `TurboQuantIndex` or `IdMapIndex` from `turbovec`; Rust uses the `turbovec` crate. This is an in-process vector index that linearly scans its compressed vectors. It does not provide a server, replication, tenancy, or distributed index.193. **Validate data shape and quality needs.** Confirm vector dimension, row-major `float32` input for Python, bit width (2 or 4), score semantics (inner product; normalize for cosine), recall target, and whether stable IDs are needed. Compare recall on representative local data before adopting quantization.204. **Get approval before effects.** Ask before installing the package/toolchain, downloading models or vector datasets, reading/embedding private source data, using paid/remote embeddings, writing/syncing/loading an index file, rebuilding or deleting an index, or starting an API/service around it. Keep file paths and credentials out of public logs. `sync(path)` persists data and later calls update it.215. **Check the pinned API and verify round-trip.** After approval, inspect the checkout's Python/Rust API docs and package help. Start with a small fixture, verify search results and persistence/load, and measure memory, recall, and latency for the target machine. Do not infer production service readiness from an in-memory library smoke test.2223## Examples2425```bash26# Offline provenance check; absolute, non-symlink source checkout.27python3 .agent-skills/turbovec/scripts/preflight.py --repo /work/turbovec --json2829# Only after install/data/file-write approval:30pip install turbovec31python - <<'PY'32import numpy as np33from turbovec import TurboQuantIndex34x = np.load("vectors.npy").astype(np.float32)35index = TurboQuantIndex(dim=x.shape[1], bit_width=4)36index.add(x)37scores, slots = index.search(x[:1], k=5)38index.sync("index.tv")39PY40```4142## Best practices4344- Use stable `uint64` IDs through `IdMapIndex` if results must survive slot changes/deletes; plain `TurboQuantIndex` returns slot positions.45- The project documents 64-bit targets only, dimensions in multiples of 8 up to 16,384, and bit widths 2/4. Quantization is lossy; low-dimensional data can lose more recall.46- Search cost scales with corpus size because the library scans vectors. For very large corpora or network clients, choose an ANN/server architecture instead of presenting turbovec as one.47- Keep upstream performance figures tied to their hardware, dataset and benchmark method; validate locally. Do not publish universal multipliers.48- Report `runtime_verified: false` after helper checks: this preflight does not install native wheels, run kernels, test recall, or exercise persistence.4950## References5152- [Pinned source behavior, limits, and evidence](references/upstream.md)53- [Pin, license, and raw file hashes](references/source.json)54- [Authored routing scenarios](evals/evals.json)55- Helper contract: `python3 .agent-skills/turbovec/scripts/preflight.py --help`; helper supports Python 3.10+ on POSIX Linux/macOS/WSL2 and fails closed when secure directory traversal is unavailable, including unsupported native Windows.