ruvector 0.1.1__tar.gz → 0.1.2__tar.gz

{ruvector-0.1.1 → ruvector-0.1.2}/Cargo.lock

@@ -10759,7 +10759,7 @@ dependencies = [
 
 [[package]]
 name = "ruvector-py"
-version = "0.1.1"
+version = "0.1.2"
 dependencies = [
  "numpy",
  "pyo3",

{ruvector-0.1.1 → ruvector-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ruvector
-Version: 0.1.1
+Version: 0.1.2
 Classifier: Development Status :: 3 - Alpha
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
@@ -137,6 +137,7 @@ ruvector benchmark -n 100000 --dim 128     # in-process latency/QPS, no external
 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
@@ -162,6 +163,16 @@ 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.
+
 ```sh
 # point an MCP client at: ruvector serve   (stdio)
 # or:                      ruvector serve --http --port 8420

{ruvector-0.1.1 → ruvector-0.1.2}/README.md

@@ -88,6 +88,7 @@ ruvector benchmark -n 100000 --dim 128     # in-process latency/QPS, no external
 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
@@ -113,6 +114,16 @@ 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.
+
 ```sh
 # point an MCP client at: ruvector serve   (stdio)
 # or:                      ruvector serve --http --port 8420

{ruvector-0.1.1 → ruvector-0.1.2}/crates/ruvector-py/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ruvector-py"
-version = "0.1.1"
+version = "0.1.2"
 edition = "2021"
 rust-version.workspace = true
 license = "MIT"

{ruvector-0.1.1 → ruvector-0.1.2}/crates/ruvector-py/README.md

@@ -88,6 +88,7 @@ ruvector benchmark -n 100000 --dim 128     # in-process latency/QPS, no external
 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
@@ -113,6 +114,16 @@ 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.
+
 ```sh
 # point an MCP client at: ruvector serve   (stdio)
 # or:                      ruvector serve --http --port 8420

ruvector-0.1.2/crates/ruvector-py/tests/perf/bench_collection.py

@@ -0,0 +1,84 @@
+"""Micro-benchmark for Collection insert / insert_batch / search / save / load.
+
+Not collected by pytest (no ``test_`` prefix). Run on a quiet machine:
+
+    python tests/perf/bench_collection.py --n 50000 --dim 256 --repeat 5
+
+Each figure is the median of ``--repeat`` runs; the spread (min..max) is printed
+beside it. Data is seeded, so runs are comparable across commits on one machine.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import statistics
+import tempfile
+import time
+from pathlib import Path
+from typing import Callable, Dict, List
+
+import numpy as np
+
+from ruvector.collection import Collection
+
+
+def timed(fn: Callable[[], object]) -> float:
+    t0 = time.perf_counter()
+    fn()
+    return time.perf_counter() - t0
+
+
+def summarize(samples: List[float]) -> str:
+    return f"{statistics.median(samples) * 1000:9.2f} ms  [{min(samples) * 1000:.2f}..{max(samples) * 1000:.2f}]"
+
+
+def bench_backend(backend: str, n: int, dim: int, repeat: int, with_meta: bool) -> Dict[str, List[float]]:
+    rng = np.random.default_rng(0)
+    vecs = rng.standard_normal((n, dim)).astype(np.float32)
+    queries = rng.standard_normal((200, dim)).astype(np.float32)
+    metas = [{"i": i, "tag": f"t{i % 50}", "txt": "x" * 40} for i in range(n)] if with_meta else None
+    n_single = min(2000, n)
+    out: Dict[str, List[float]] = {k: [] for k in ("insert_x2000", "insert_batch", "from_vectors", "search_x200", "save", "load")}
+    for _ in range(repeat):
+        c = Collection.create(dim=dim, backend=backend)
+        if backend == "rabitq":  # first row builds; time the add() path after it
+            c.insert(vecs[0])
+        out["insert_x2000"].append(timed(lambda: [c.insert(vecs[i]) for i in range(1, n_single)]))
+        c = Collection.create(dim=dim, backend=backend)
+        out["insert_batch"].append(timed(lambda: c.insert_batch(vecs, metadatas=metas)))
+        out["from_vectors"].append(timed(lambda: Collection.from_vectors(vecs, backend=backend, metadatas=metas)))
+        if backend == "rabitq":
+            for i in range(0, n, 10):  # 10% tombstones, so search exercises the filter path
+                c.delete(i)
+        out["search_x200"].append(timed(lambda: [c.search(q, 10) for q in queries]))
+        with tempfile.TemporaryDirectory() as d:
+            p = Path(d) / "c.idx"
+            out["save"].append(timed(lambda: c.save(p)))
+            out["load"].append(timed(lambda: Collection.load(p)))
+    return out
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--n", type=int, default=50_000)
+    ap.add_argument("--dim", type=int, default=256)
+    ap.add_argument("--repeat", type=int, default=5)
+    ap.add_argument("--backends", default="hnsw,rabitq")
+    ap.add_argument("--no-metadata", action="store_true")
+    ap.add_argument("--json", action="store_true")
+    a = ap.parse_args()
+    results = {}
+    for backend in a.backends.split(","):
+        results[backend] = bench_backend(backend, a.n, a.dim, a.repeat, not a.no_metadata)
+    if a.json:
+        print(json.dumps({b: {k: statistics.median(v) for k, v in r.items()} for b, r in results.items()}))
+        return
+    print(f"n={a.n} dim={a.dim} repeat={a.repeat} metadata={'no' if a.no_metadata else 'yes'}")
+    for backend, r in results.items():
+        for name, samples in r.items():
+            print(f"{backend:7s} {name:14s} {summarize(samples)}")
+
+
+if __name__ == "__main__":
+    main()

{ruvector-0.1.1 → ruvector-0.1.2}/crates/ruvector-py/tests/test_cli.py

@@ -6,6 +6,7 @@ from __future__ import annotations
 
 import json
 from pathlib import Path
+from typing import Any, List, Optional
 
 import numpy as np
 import pytest
@@ -165,6 +166,41 @@ def test_benchmark_human_readable_has_data(runner: CliRunner) -> None:
     assert "dim=16" in r.output
 
 
+@pytest.mark.parametrize("backend", ["hnsw", "rabitq"])
+def test_benchmark_reports_recall(runner: CliRunner, backend: str) -> None:
+    r = runner.invoke(
+        main, ["benchmark", "-n", "400", "--dim", "16", "--queries", "15", "--backend", backend, "--json"]
+    )
+    assert r.exit_code == 0, r.output
+    result = json.loads(r.output)
+    assert result["backend"] == backend
+    assert result["recall_k"] == 10
+    assert 0.5 <= result["recall_at_10"] <= 1.0
+    # the existing latency fields are unchanged
+    for key in ("n", "dim", "k", "queries", "build_seconds", "p50_ms", "p99_ms", "qps"):
+        assert key in result
+
+
+def test_benchmark_recall_k_is_configurable_and_in_human_output(runner: CliRunner) -> None:
+    r = runner.invoke(main, ["benchmark", "-n", "300", "--dim", "8", "--queries", "10", "--recall-k", "5"])
+    assert r.exit_code == 0, r.output
+    assert "recall@5=" in r.output
+    j = json.loads(runner.invoke(main, ["benchmark", "-n", "300", "--dim", "8", "--queries", "10", "--recall-k", "5", "--json"]).output)
+    assert "recall_at_5" in j and "recall_at_10" not in j
+
+
+def test_benchmark_recall_is_exact_for_tiny_corpus(runner: CliRunner) -> None:
+    # n <= recall-k: every vector is in the top-k, so recall must be exactly 1.0
+    r = runner.invoke(main, ["benchmark", "-n", "6", "--dim", "8", "--queries", "5", "--recall-k", "10", "--json"])
+    assert r.exit_code == 0, r.output
+    assert json.loads(r.output)["recall_at_10"] == 1.0
+
+
+def test_benchmark_rejects_nonpositive_recall_k(runner: CliRunner) -> None:
+    r = runner.invoke(main, ["benchmark", "-n", "50", "--dim", "8", "--recall-k", "0"])
+    assert r.exit_code != 0
+
+
 def test_search_no_color_flag_forces_plain(runner: CliRunner, tmp_path: Path) -> None:
     """--no-color is a no-op in terms of data under CliRunner (already
     non-TTY => already plain), but exercise the flag itself end to end so
@@ -263,3 +299,39 @@ def test_serve_without_mcp_sdk_gives_install_hint(runner: CliRunner, monkeypatch
     assert result.exit_code != 0
     assert "ruvector[mcp]" in result.output
     assert "Traceback" not in result.output
+
+
+# ── serve --max-vectors ─────────────────────────────────────────────────────
+
+
+def test_serve_max_vectors_option_sets_cap(runner: CliRunner, monkeypatch: pytest.MonkeyPatch) -> None:
+    pytest.importorskip("mcp")
+    import ruvector.mcp_server as m
+
+    monkeypatch.delenv("RUVECTOR_MCP_MAX_VECTORS", raising=False)
+    monkeypatch.setattr(m.server, "run", lambda *a, **kw: None)
+    try:
+        result = runner.invoke(main, ["serve", "--max-vectors", "123"])
+        assert result.exit_code == 0, result.output
+        assert m.max_vectors() == 123
+    finally:
+        m.set_max_vectors(None)
+
+
+@pytest.mark.parametrize("args,env", [(["--max-vectors", "0"], None), ([], "nope")])
+def test_serve_rejects_bad_max_vectors(
+    runner: CliRunner, monkeypatch: pytest.MonkeyPatch, args: List[str], env: Optional[str]
+) -> None:
+    pytest.importorskip("mcp")
+    import ruvector.mcp_server as m
+
+    ran: List[Any] = []
+    monkeypatch.setattr(m.server, "run", lambda *a, **kw: ran.append(1))
+    if env is None:
+        monkeypatch.delenv("RUVECTOR_MCP_MAX_VECTORS", raising=False)
+    else:
+        monkeypatch.setenv("RUVECTOR_MCP_MAX_VECTORS", env)
+    result = runner.invoke(main, ["serve", *args])
+    assert result.exit_code != 0
+    assert "positive integer" in result.output
+    assert not ran

{ruvector-0.1.1 → ruvector-0.1.2}/crates/ruvector-py/tests/test_mcp_server.py

@@ -524,3 +524,82 @@ def test_validation_errors_reach_the_client():
         assert "no such collection" in str(e)
     else:
         raise AssertionError("expected ToolError")
+
+
+# ── per-collection vector cap ────────────────────────────────────────────
+
+
+@pytest.fixture
+def capped(server_module: ModuleType, monkeypatch: pytest.MonkeyPatch) -> ModuleType:
+    monkeypatch.delenv("RUVECTOR_MCP_MAX_VECTORS", raising=False)
+    server_module.set_max_vectors(None)
+    yield server_module
+    server_module.set_max_vectors(None)
+
+
+def test_default_vector_cap_is_one_million(capped: ModuleType) -> None:
+    assert capped.max_vectors() == 1_000_000
+
+
+def test_env_var_sets_vector_cap_and_option_wins(capped: ModuleType, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("RUVECTOR_MCP_MAX_VECTORS", "7")
+    assert capped.max_vectors() == 7
+    capped.set_max_vectors(3)
+    assert capped.max_vectors() == 3
+    capped.set_max_vectors(None)
+    monkeypatch.setenv("RUVECTOR_MCP_MAX_VECTORS", "  ")
+    assert capped.max_vectors() == 1_000_000  # blank counts as unset
+
+
+@pytest.mark.parametrize("bad", ["0", "-5", "abc", "1.5"])
+def test_invalid_vector_cap_is_rejected(capped: ModuleType, monkeypatch: pytest.MonkeyPatch, bad: str) -> None:
+    monkeypatch.setenv("RUVECTOR_MCP_MAX_VECTORS", bad)
+    with pytest.raises(ValueError, match="RUVECTOR_MCP_MAX_VECTORS"):
+        capped.max_vectors()
+    with pytest.raises(ValueError):
+        capped.set_max_vectors(int(bad) if bad.lstrip("-").isdigit() else 0)
+
+
+def test_insert_stops_at_vector_cap(capped: ModuleType) -> None:
+    m = capped
+    m.set_max_vectors(2)
+    _call(m, "vector_create_collection", name="cap1", dim=2)
+    _call(m, "vector_insert", name="cap1", vector=[1.0, 0.0])
+    _call(m, "vector_insert", name="cap1", vector=[0.0, 1.0])
+    with _raises_chain(r"vector limit.*maximum of 2"):
+        _call(m, "vector_insert", name="cap1", vector=[1.0, 1.0])
+    assert _call(m, "vector_stats", name="cap1")["count"] == 2
+
+
+def test_batch_insert_is_all_or_nothing_at_cap(capped: ModuleType) -> None:
+    m = capped
+    m.set_max_vectors(3)
+    _call(m, "vector_create_collection", name="cap2", dim=2)
+    _call(m, "vector_insert_batch", name="cap2", vectors=[[1.0, 0.0], [0.0, 1.0]])
+    with _raises_chain("maximum of 3"):
+        _call(m, "vector_insert_batch", name="cap2", vectors=[[1.0, 1.0], [2.0, 2.0]])
+    assert _call(m, "vector_stats", name="cap2")["count"] == 2  # nothing partially written
+    _call(m, "vector_insert_batch", name="cap2", vectors=[[1.0, 1.0]])  # exactly reaches the cap
+    assert _call(m, "vector_stats", name="cap2")["count"] == 3
+
+
+def test_cap_message_is_a_tool_error(capped: ModuleType) -> None:
+    """mcp 2.x hides non-ToolError messages from the client; the cap text must survive."""
+    from mcp.server.mcpserver.exceptions import ToolError
+
+    m = capped
+    m.set_max_vectors(1)
+    _call(m, "vector_create_collection", name="cap3", dim=2)
+    _call(m, "vector_insert", name="cap3", vector=[1.0, 0.0])
+    with pytest.raises(ToolError, match="vector limit"):
+        asyncio.run(m.server.call_tool("vector_insert", {"name": "cap3", "vector": [0.0, 1.0]}))
+
+
+@pytest.mark.parametrize("backend", ["hnsw", "rabitq"])
+def test_deleted_rows_count_until_vacuumed(capped: ModuleType, backend: str) -> None:
+    m = capped
+    m.set_max_vectors(2)
+    _call(m, "vector_create_collection", name=f"cap4{backend}", dim=2, backend=backend)
+    ids = _call(m, "vector_insert_batch", name=f"cap4{backend}", vectors=[[1.0, 0.0], [0.0, 1.0]])["ids"]
+    _call(m, "vector_delete", name=f"cap4{backend}", id=ids[0], vacuum=True)
+    _call(m, "vector_insert", name=f"cap4{backend}", vector=[1.0, 1.0])  # vacuumed -> room again

{ruvector-0.1.1 → ruvector-0.1.2}/crates/ruvector-py/tests/test_smoke.py

@@ -26,7 +26,7 @@ import ruvector
 def test_version() -> None:
     assert ruvector.__version__
     # Cargo.toml ships 0.1.0; if you bump there, bump here.
-    assert ruvector.__version__ == "0.1.1"
+    assert ruvector.__version__ == "0.1.2"
 
 
 def test_build_and_search() -> None:

{ruvector-0.1.1 → ruvector-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "ruvector"
-version = "0.1.1"
+version = "0.1.2"
 description = "Ultra-low-latency vector search (RaBitQ, Rust core) with a CLI and MCP server"
 readme = "README.md"
 license = { text = "MIT" }

{ruvector-0.1.1 → ruvector-0.1.2}/python/ruvector/cli.py

@@ -335,18 +335,67 @@ def info(path: str, as_json: bool, no_color: bool) -> None:
     console.print(Panel(table, title=f"[bold]{p.name}[/bold]", expand=False))
 
 
+def _recall_at_k(coll: "Collection", vecs: "NDArray[np.float32]", qs: "NDArray[np.float32]", k: int) -> float:
+    """Mean recall@k of ``coll.search`` against exact brute-force top-k.
+
+    Ground truth uses the collection's own metric (cosine, or squared L2 for
+    rabitq). Ids are row indices because the benchmark builds with the
+    default ``ids=range(n)``. Ties at the k-th distance are resolved by the
+    stable sort, so recall can differ from 1.0 only through the index.
+    """
+    import numpy as np
+
+    k = min(k, vecs.shape[0])
+    if coll.metric == "squared_l2":
+        # |v|^2 - 2 v.q  (|q|^2 is constant per query and does not change the order)
+        scores = (vecs * vecs).sum(axis=1)[None, :] - 2.0 * (qs @ vecs.T)
+    else:
+        vn = vecs / np.maximum(np.linalg.norm(vecs, axis=1, keepdims=True), 1e-30)
+        scores = -(qs @ vn.T)  # cosine order = order of v.q / |v|, |q| is per-query constant
+    truth = np.argsort(scores, axis=1, kind="stable")[:, :k]
+    total = 0.0
+    for i in range(qs.shape[0]):
+        got = {hit.id for hit in coll.search(qs[i], k)}
+        total += len(got.intersection(truth[i].tolist())) / k
+    return total / qs.shape[0]
+
+
 @main.command()
 @click.option("-n", default=10_000, show_default=True, type=int, help="Number of vectors.")
 @click.option("--dim", default=128, show_default=True, type=int)
 @click.option("--k", default=10, show_default=True, type=int)
 @click.option("--queries", default=100, show_default=True, type=int)
-@click.option("--rerank-factor", default=20, show_default=True, type=int)
+@click.option("--rerank-factor", default=20, show_default=True, type=int, help="Only used by --backend rabitq.")
+@click.option(
+    "--backend",
+    default="hnsw",
+    show_default=True,
+    type=click.Choice(["hnsw", "rabitq"]),
+    help="Index backend to benchmark.",
+)
+@click.option(
+    "--recall-k",
+    default=10,
+    show_default=True,
+    type=int,
+    help="k for recall@k, measured against exact brute-force search over the same vectors.",
+)
 @click.option("--json", "as_json", is_flag=True, default=False)
-def benchmark(n: int, dim: int, k: int, queries: int, rerank_factor: int, as_json: bool) -> None:
-    """Run an in-memory build+search latency benchmark (no comparator — see
-    the ADR-352 benchmark methodology for a real side-by-side)."""
+def benchmark(
+    n: int, dim: int, k: int, queries: int, rerank_factor: int, backend: str, recall_k: int, as_json: bool
+) -> None:
+    """Run an in-memory build+search benchmark: latency, QPS and recall@k
+    against exact brute-force search (no comparator — see the ADR-352
+    benchmark methodology for a real side-by-side).
+
+    Recall is computed on the same queries as the latency loop, using the
+    index's own distance (cosine for hnsw, squared L2 for rabitq), and is
+    not included in the timings."""
     import time
 
+    if n < 1 or dim < 1 or k < 1 or queries < 1 or recall_k < 1:
+        raise click.ClickException("-n, --dim, --k, --queries and --recall-k must all be >= 1")
+
     import numpy as np
 
     from ruvector.collection import Collection
@@ -355,7 +404,7 @@ def benchmark(n: int, dim: int, k: int, queries: int, rerank_factor: int, as_jso
     vecs = rng.standard_normal((n, dim)).astype(np.float32)
 
     t0 = time.perf_counter()
-    coll = Collection.from_vectors(vecs, rerank_factor=rerank_factor)
+    coll = Collection.from_vectors(vecs, backend=backend, rerank_factor=rerank_factor)
     build_s = time.perf_counter() - t0
 
     qs = rng.standard_normal((queries, dim)).astype(np.float32)
@@ -368,8 +417,13 @@ def benchmark(n: int, dim: int, k: int, queries: int, rerank_factor: int, as_jso
     p50 = latencies[len(latencies) // 2]
     p99 = latencies[int(len(latencies) * 0.99) - 1]
 
+    recall = _recall_at_k(coll, vecs, qs, recall_k)
+
     result = {
         "n": n, "dim": dim, "k": k, "queries": queries, "rerank_factor": rerank_factor,
+        "backend": backend,
+        f"recall_at_{recall_k}": recall,
+        "recall_k": recall_k,
         "build_seconds": build_s,
         "p50_ms": p50 * 1000,
         "p99_ms": p99 * 1000,
@@ -381,7 +435,8 @@ def benchmark(n: int, dim: int, k: int, queries: int, rerank_factor: int, as_jso
     else:
         _secho(
             f"n={n} dim={dim} build={build_s:.3f}s p50={result['p50_ms']:.3f}ms "
-            f"p99={result['p99_ms']:.3f}ms qps={result['qps']:.0f}",
+            f"p99={result['p99_ms']:.3f}ms qps={result['qps']:.0f} "
+            f"recall@{recall_k}={recall:.4f}",
             fg="cyan",
         )
 
@@ -396,7 +451,14 @@ def benchmark(n: int, dim: int, k: int, queries: int, rerank_factor: int, as_jso
     default=False,
     help="Do not register mutating tools (create/insert/insert_batch/delete) or the Salesforce upsert route.",
 )
-def serve(use_http: bool, host: str, port: int, read_only: bool) -> None:
+@click.option(
+    "--max-vectors",
+    default=None,
+    type=int,
+    help="Maximum vectors per collection a client may write "
+    "(default 1000000; also settable with RUVECTOR_MCP_MAX_VECTORS; this option wins).",
+)
+def serve(use_http: bool, host: str, port: int, read_only: bool, max_vectors: Optional[int]) -> None:
     """Launch the ruvector MCP server (stdio by default).
 
     If ``RUVECTOR_ENABLE_SALESFORCE_ACTIONS`` is set, also mounts the
@@ -423,6 +485,18 @@ def serve(use_http: bool, host: str, port: int, read_only: bool) -> None:
     if read_only:
         apply_read_only()
 
+    try:
+        if max_vectors is not None:
+            from ruvector.mcp_server import set_max_vectors
+
+            set_max_vectors(max_vectors)
+        else:
+            from ruvector.mcp_server import max_vectors as _effective_max_vectors
+
+            _effective_max_vectors()  # fail at startup, not on the first insert, if the env var is malformed
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+
     if use_http and os.environ.get("RUVECTOR_ENABLE_SALESFORCE_ACTIONS"):
         from ruvector.salesforce_routes import SalesforceAuthNotConfiguredError, maybe_register
 

{ruvector-0.1.1 → ruvector-0.1.2}/python/ruvector/mcp_server.py

@@ -78,7 +78,7 @@ import re
 import sys
 import threading
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Dict, List, Optional
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
 
 from mcp.server.auth.middleware.auth_context import get_access_token
 from mcp.server.auth.provider import AccessToken, TokenVerifier
@@ -105,6 +105,13 @@ _NAME_RE = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
 MAX_BATCH_ROWS = 10_000
 MAX_BATCH_ELEMENTS = 2_000_000  # rows * dim floats per insert_batch call (~8 MB as float32)
 MAX_METADATA_BYTES = 65_536  # serialized JSON, per row
+# Total vectors a client may write into ONE collection (a cumulative cap, unlike
+# the per-call caps above). Every write re-saves the whole collection, so an
+# unbounded collection also makes each later write slower. Override with the
+# RUVECTOR_MCP_MAX_VECTORS environment variable or `ruvector serve --max-vectors`.
+DEFAULT_MAX_VECTORS = 1_000_000
+_MAX_VECTORS_ENV_VAR = "RUVECTOR_MCP_MAX_VECTORS"
+_max_vectors_override: Optional[int] = None
 
 _TOKEN_ENV_VAR = "RUVECTOR_MCP_TOKEN"
 # Self-referential placeholder — this design does not do real OAuth
@@ -263,6 +270,52 @@ def _save(name: str, coll: "Collection") -> None:
     _cache[name] = coll
 
 
+def parse_max_vectors(raw: Union[str, int], source: str) -> int:
+    """Validate a vectors-per-collection cap; raises ``ValueError`` if not a positive int."""
+    try:
+        value = int(str(raw).strip())
+    except ValueError:
+        raise ValueError(f"{source} must be a positive integer, got {raw!r}") from None
+    if value < 1:
+        raise ValueError(f"{source} must be a positive integer, got {raw!r}")
+    return value
+
+
+def set_max_vectors(value: Optional[int]) -> None:
+    """Set (or with ``None`` clear) the cap given on the command line; it wins over the environment."""
+    global _max_vectors_override
+    _max_vectors_override = None if value is None else parse_max_vectors(value, "max vectors")
+
+
+def max_vectors() -> int:
+    """Effective per-collection cap: ``--max-vectors``, else the env var, else the default.
+
+    An empty env var counts as unset.
+    """
+    if _max_vectors_override is not None:
+        return _max_vectors_override
+    raw = os.environ.get(_MAX_VECTORS_ENV_VAR, "").strip()
+    return parse_max_vectors(raw, _MAX_VECTORS_ENV_VAR) if raw else DEFAULT_MAX_VECTORS
+
+
+def _check_capacity(coll: "Collection", incoming: int) -> None:
+    """Reject a write that would take the collection past the cap.
+
+    Counts tombstoned rows too: they still occupy the index and the saved
+    files until ``vector_delete(..., vacuum=True)`` runs.
+    """
+    cap = max_vectors()
+    stats = coll.stats()
+    used = stats.count + stats.tombstoned
+    if used + incoming > cap:
+        raise ValueError(
+            f"collection is at its vector limit: it holds {used} vectors"
+            f"{f' ({stats.tombstoned} deleted, not yet vacuumed)' if stats.tombstoned else ''}, "
+            f"adding {incoming} would exceed the maximum of {cap} per collection "
+            f"(set {_MAX_VECTORS_ENV_VAR} or `ruvector serve --max-vectors` to change it)"
+        )
+
+
 def _check_vector_len(vec: "List[float]", what: str) -> None:
     if len(vec) > MAX_DIM:
         raise ValueError(f"{what} has {len(vec)} elements; the maximum dimension is {MAX_DIM}")
@@ -297,7 +350,7 @@ _token_verifier, _auth_settings = _build_auth()
 server = MCPServer(
     name="ruvector",
     title="RuVector",
-    version="0.1.1",
+    version="0.1.2",
     instructions=(
         "ultra-low-latency vector search backed by a Rust RaBitQ core. "
         "Create a collection, insert vectors with optional metadata, search "
@@ -369,6 +422,7 @@ def vector_insert(name: str, vector: List[float], metadata: Optional[Dict[str, A
     _check_metadata(metadata)
     with _lock:
         coll = _load(name)
+        _check_capacity(coll, 1)
         new_id = coll.insert(np.asarray(vector, dtype=np.float32), metadata=metadata)
         _save(name, coll)
         return {"id": new_id, "count": len(coll)}
@@ -388,6 +442,7 @@ def vector_insert_batch(
     _check_batch(vectors, metadatas)
     with _lock:
         coll = _load(name)
+        _check_capacity(coll, len(vectors))
         ids = coll.insert_batch(np.asarray(vectors, dtype=np.float32), metadatas=metadatas)
         _save(name, coll)
         return {"ids": ids, "count": len(coll)}
@@ -619,4 +674,13 @@ def run_http(host: str = "127.0.0.1", port: int = 8420) -> None:
     server.run(transport="streamable-http", host=host, port=port)
 
 
-__all__ = ["server", "run_stdio", "run_http", "StaticTokenVerifier", "apply_read_only", "UnsafeBindError"]
+__all__ = [
+    "server",
+    "run_stdio",
+    "run_http",
+    "StaticTokenVerifier",
+    "apply_read_only",
+    "UnsafeBindError",
+    "set_max_vectors",
+    "max_vectors",
+]