ruvector — Python SDK, CLI, and MCP server

Ultra-low-latency vector similarity search, backed by a Rust RaBitQ 1-bit quantization core (ruvector_rabitq::RabitqPlusIndex) with native NumPy interop — zero-copy reads, GIL released on every heavy call. Ships three things from one pip install ruvector:

• ruvector — the Python library (Collection, RabitqIndex).
• ruvector console script — a CLI for scripting/ops (create/insert-batch/search/delete/export/import/info/ benchmark/serve), installed with the base package.
• ruvector serve — an MCP server (stdio or streamable-HTTP) exposing the same surface as tools, plus a ChatGPT Apps SDK ui:// widget for visual search exploration, install with the mcp extra.

This crate is the Python half of the ruvector workspace; the underlying algorithm lives in crates/ruvector-rabitq/ and is unchanged by this binding. Scope, benchmarks, and the milestone roadmap (M1 here → M2 ruLake/ HNSW → M3 embeddings → M4 A2A client) are in docs/adr/ADR-352-ruvector-python-sdk-cli-mcp.md and docs/sdk/.

Install

pip install ruvector            # library + the `ruvector` console script (numpy, click, rich)
pip install ruvector[mcp]       # + `ruvector serve` (MCP server)
pip install ruvector[all]       # everything

For local development from a checkout:

cd crates/ruvector-py
maturin develop --release   # builds the Rust cdylib in-place, links as ruvector._native
pip install -e '.[all]'     # pulls click/rich/mcp for the cli/mcp extras
pytest tests/

The --release flag matters: a debug build is dramatically slower on the search loop and will fail the latency acceptance tests.

30-second example (library)

import numpy as np
from ruvector import Collection

vectors = np.random.default_rng(42).standard_normal((100_000, 128)).astype(np.float32)
coll = Collection.from_vectors(vectors, rerank_factor=20)

hits = coll.search(vectors[0], k=10)
for h in hits:
    print(h.id, h.score)          # ascending squared-L2 distance

coll.save("my.rbpx")              # writes my.rbpx + my.rbpx.meta.json
coll2 = Collection.load("my.rbpx")

Collection adds ids, per-vector metadata, soft delete, and filtering on top of the lower-level RabitqIndex (which is still available directly for the ~50 lines/row case where you don't need any of that):

coll = Collection.create(dim=128)
coll.insert(vectors[0], metadata={"category": "news"})
coll.insert_batch(vectors[1:100], metadatas=[{"category": "sports"}] * 99)

hits = coll.search(vectors[0], k=5, filter={"category": "news"})  # client-side filter
coll.delete(hits[0].id)           # soft delete (tombstone)
coll.vacuum()                     # physically rebuild without tombstoned rows

Filtering is applied client-side (the Rust scan has no filter pushdown in M1.5) — documented in Collection.search's docstring, not hidden.

CLI

ruvector create --path my.rbpx --dim 128
ruvector insert-batch --path my.rbpx --vectors vecs.npy --metadata meta.json
ruvector search --path my.rbpx --query q.npy -k 10 --json
ruvector delete --path my.rbpx --id 42 --vacuum
ruvector export --path my.rbpx --out snapshot
ruvector import --path new.rbpx --vectors vecs.npy
ruvector info --path my.rbpx
ruvector benchmark -n 100000 --dim 128     # in-process latency/QPS, no external comparator
ruvector serve                             # MCP server over stdio
ruvector serve --http --port 8420          # MCP server over streamable-HTTP (loopback)
ruvector serve --read-only                 # no create/insert/delete tools
ruvector serve --max-vectors 50000         # cap vectors per collection (default 1,000,000)

serve --http on a non-loopback --host refuses to start unless RUVECTOR_MCP_TOKEN is set to a non-empty secret (bearer auth); an empty or whitespace-only value counts as unset.

ruvector --help starts in ~20ms — every subcommand lazily imports numpy/ click/rich inside its own function body (see ruvector/cli.py's module docstring), so nothing pays for them until it actually runs.

MCP server

ruvector serve exposes: vector_create_collection, vector_insert, vector_insert_batch, vector_search, vector_delete, vector_stats, vector_list_collections, and vector_explore — a widget-backed tool that renders results in an HTML table (ui://ruvector/explore.html), following the ChatGPT Apps SDK convention (_meta["openai/outputTemplate"]).

Tool arguments name a collection by name, never by filesystem path — names are restricted to [A-Za-z0-9_-] and resolved under RUVECTOR_MCP_DATA_DIR (default ~/.ruvector/collections), so there is no directory-traversal surface regardless of what a remote MCP client sends. See ruvector/mcp_server.py's module docstring for the full security model.

Write size is capped. Per call: 10,000 rows, 2,000,000 floats in total, and 64 KiB of serialized metadata per row. Per collection: 1,000,000 vectors by default, counting deleted-but-not-vacuumed rows; vector_insert and vector_insert_batch fail with a ToolError that names the limit once it would be exceeded. Change it with ruvector serve --max-vectors N or RUVECTOR_MCP_MAX_VECTORS=N (the option wins; a non-positive or non-integer value stops the server at startup). The server re-saves the whole collection on every write, so keep this cap well below what your disk and latency budget can take.

# point an MCP client at: ruvector serve   (stdio)
# or:                      ruvector serve --http --port 8420

API summary (library)

Non-contiguous or wrong-dtype inputs raise TypeError at the boundary rather than silently copying — predictable beats fast. Ids must fit in u32 (the index's storage width); a larger id raises CollectionError (library) or ValueError (RabitqIndex directly) rather than silently truncating.

Benchmark

Real numbers (this host, random-Gaussian data — adversarial for ANN in general, see the caveat in ADR-352) are in docs/adr/ADR-352-ruvector-python-sdk-cli-mcp.md. ruvector benchmark runs an in-process build+search latency check with no external comparator.

Links

• ADR-352 — scope, benchmark, security, publishing status
• SDK plan and milestones — binding strategy + M1-M4 roadmap
• ruvector-rabitq — the Rust crate this wraps

License

MIT, matching the rest of the ruvector workspace (see LICENSE).

Python capability packages

The Python portfolio maps the ten most downloaded RuVector npm distributions to scoped Python APIs. Version 0.1.3 adds native KVCache (full precision cache attention, no text generation) and RvfStore (trusted local RVF vector storage). Existing vector, graph, GNN, attention and SONA APIs remain available.

from ruvector import KVCache
cache = KVCache(2, max_tokens=8)
cache.append([1.0, 0.0], [0.25, 0.75])
assert cache.attend([1.0, 0.0]) == [0.25, 0.75]

Native version changes merged into main automatically build, audit, test and publish all supported wheel platforms. A failed gate blocks upload.