vectro

⚠️ Requirements

Python-Only Mode (Works Everywhere) - Python 3.10+ - NumPy - For INT8 throughput benefits: squish_quant Rust extension (auto-installed, optional) - Achieved throughput: ~167K–210K vec/s on Apple Silicon / modern x86 (d=768, batch=10000, measured)

Mojo-Accelerated Mode (Optional, for 5M+ vec/s) - Requires: pixi (available at modular.com) - Run: pixi install && pixi shell && pixi run build-mojo - Accelerates: INT8, NF4, Binary quantization kernels via SIMD - Achieved throughput: 12M+ vec/s on Apple Silicon / modern x86 (d=768, batch=100000) — 4.85× faster than FAISS C++

Optional Vector DB Support - pip install "vectro[integrations]" for Qdrant, Weaviate connectors - pip install "vectro[data]" for Arrow/Parquet export - pip install "vectro[integrations] langchain-core" for LangChain VectorStore - pip install "vectro[integrations] llama-index-core" for LlamaIndex VectorStore - pip install "vectro[integrations] haystack-ai" for Haystack 2.x DocumentStore - pip install "vectro[integrations] dspy-ai" for DSPy retriever module - pip install "vectro[integrations] openai voyageai cohere sentence-transformers" for the built-in embedding-provider bridges (any subset)

All core functions work in Python-only mode. Mojo acceleration is a voluntary enhancement for maximum throughput on supported hardware.

---

Cloud backends (requires pip install fsspec[s3])

from python.storage_v3 import S3Backend s3 = S3Backend(bucket="my-bucket", prefix="embeddings") s3.save_vqz(quantized, scales, dims=768, remote_name="prod.vqz") ```

---

AWS S3 (requires pip install fsspec[s3])

s3 = S3Backend(bucket="my-vectors", prefix="prod") s3.save_vqz(quantized, scales, dims=768, remote_name="batch1.vqz")

Python API (Works Immediately, No Setup Required)

```python from python.v3_api import VectroV3, auto_compress import numpy as np

1. Clone and setup

git clone https://github.com/wesleyscholl/vectro.git cd vectro pixi install && pixi shell

4. Build and verify the Mojo binary

pixi run build-mojo # builds vectro_quantizer at project root pixi run selftest # verifies INT8/NF4/Binary correctness ```

Build store from texts — same interface as FAISS.from_texts, Chroma.from_texts

store = LangChainVectorStore.from_texts( texts=["Paris is the capital of France", "Berlin is cold in winter"], embedding=OpenAIEmbeddings(), compression_profile="balanced", # INT8 ~4× compression )

Build candidates: (doc_id, document, original_score)

candidates = [(doc.metadata.get("id", str(i)), doc, score) for i, (doc, score) in enumerate(initial)]

⚡ Quick Start

🔄 Migration Guide (v1/v2 to v3)

Artifacts saved with Vectro < 2.0 use NPZ format version 1.

from python.migration import inspect_artifact, upgrade_artifact, validate_artifact

info = inspect_artifact("old.npz")          # {"format_version": 1, ...}
upgrade_artifact("old.npz", "new.npz")
result = validate_artifact("new.npz")       # {"valid": True}

vectro inspect old.npz
vectro upgrade old.npz new.npz --dry-run
vectro validate new.npz

See docs/migration-guide.md for the complete guide.

---

2. Run visual demo

python demos/demo_v3.py

Train codebook on representative sample

codebook = PQCodebook.train(training_vectors, n_subspaces=96, n_centroids=256) codebook.save("codebook.vqz")

v3 = VectroV3(profile="pq-96", codebook=codebook) result = v3.compress(vectors) # cosine_sim >= 0.95, 32x compression

codebook48 = PQCodebook.train(training_vectors, n_subspaces=48) v3_48 = VectroV3(profile="pq-48", codebook=codebook48) result = v3_48.compress(vectors) # ~16x compression ```

Mojo (Ultra-High Performance - Optional)

```bash

Python API (Easy Integration)

```python pip install vectro # basic pip install "vectro[data]" # + Arrow / Parquet pip install "vectro[integrations]" # + Qdrant, Weaviate, PyTorch

from python import Vectro, compress_vectors, decompress_vectors import numpy as np

vectors = np.random.randn(1000, 768).astype(np.float32)

v3.0.0 New APIs

```python from python.v3_api import VectroV3, PQCodebook, HNSWIndex, auto_compress

🐍 Python API

v3.0.0: All prior v2 capabilities plus seven new v3 modules.

Async variants (FastAPI / asyncio services)

docs = await store.asimilarity_search("async query", k=2) mmr_docs = await store.amax_marginal_relevance_search("async query", k=4)

LoRAResult(profile='lora-nf4', rank=16, module='q_proj',

Compress a full adapter (all target modules)

```python adapter = { "q_proj": (A_q, B_q), "v_proj": (A_v, B_v), "k_proj": (A_k, B_k), } compressed = compress_lora_adapter(adapter, profile="lora-nf4")

Returns: Dict[str, LoRAResult] — one entry per module

```

🔗 Vector Database Integrations

from python.integrations import QdrantConnector

conn = QdrantConnector(url="http://localhost:6333", collection="docs")
conn.store_batch(vectors, metadata={"source": "wiki"})
results = conn.search(query_vec, top_k=10)

See docs/integrations.md for full configuration.

---

🔗 RAG Framework Integrations

Vectro provides drop-in compressed vector stores for the three dominant RAG frameworks. Embeddings are compressed at write time (INT8 or NF4) and decompressed on-the-fly at query time via Mojo SIMD.

Per-module

python -m pytest tests/test_v3_api.py -v # v3 unified API python -m pytest tests/test_hnsw.py -v # HNSW index python -m pytest tests/test_pq.py -v # Product quantization python -m pytest tests/test_nf4.py -v # NF4 python -m pytest tests/test_binary.py -v # Binary python -m pytest tests/test_rq.py -v # Residual quantization python -m pytest tests/test_storage_v3.py -v # VQZ format

Voyage 3 (asymmetric: documents vs queries use different input_type)

embed = VoyageEmbeddings(model="voyage-3", cache_dir="...")

Memory comparison (768-dim, 1M documents)

---