From c8094be836bd1f8089eda4bdf46d6c5e8ddd9ca3 Mon Sep 17 00:00:00 2001 From: ruvnet Date: Wed, 11 Nov 2026 14:54:17 -0500 Subject: [PATCH 1/2] docs(crates): ADR-356 metadata for ruvector-core, ruvector-pq-search, ruvector-rairs - homepage https://ruv.io on all three; keywords and categories for ruvector-core. - Animated SVG banners (new for pq-search and rairs; core reuses core.svg). - ruvector-pq-search README: the quick start used types that do not exist (FlatPq, PqIndex, a different PqConfig). It is replaced with one that compiles and runs, including e-means training. Table names fixed. - ruvector-rairs: new README with a quick start that was run as written. Co-Authored-By: claude-flow --- .../ruvector/packages/ruvector-pq-search.svg | 1 + assets/ruvector/packages/ruvector-rairs.svg | 1 + crates/ruvector-core/Cargo.toml | 3 ++ crates/ruvector-core/README.md | 2 + crates/ruvector-pq-search/Cargo.toml | 1 + crates/ruvector-pq-search/README.md | 43 ++++++++++-------- crates/ruvector-rairs/Cargo.toml | 2 + crates/ruvector-rairs/README.md | 45 +++++++++++++++++++ 8 files changed, 79 insertions(+), 19 deletions(-) create mode 100644 assets/ruvector/packages/ruvector-pq-search.svg create mode 100644 assets/ruvector/packages/ruvector-rairs.svg create mode 100644 crates/ruvector-rairs/README.md diff --git a/assets/ruvector/packages/ruvector-pq-search.svg b/assets/ruvector/packages/ruvector-pq-search.svg new file mode 100644 index 0000000000..5fa10c0e7a --- /dev/null +++ b/assets/ruvector/packages/ruvector-pq-search.svg @@ -0,0 +1 @@ +ruvector-pq-search — Product quantization with asymmetric distance computationAnimated RuVector crate banner. A vector splits into sub-vectors that light up one by one as each becomes a one-byte code.RUVECTOR / CRATE / PRODUCT QUANTIZATIONruvector-pq-searchFlat, IVF and residual PQ indexes with ADC search.Lloyd or e-means codebook training; u8 codes per sub-space.cargo add ruvector-pq-searchf32 sub-vectorsu8 codes, scanned with ADC distance tables diff --git a/assets/ruvector/packages/ruvector-rairs.svg b/assets/ruvector/packages/ruvector-rairs.svg new file mode 100644 index 0000000000..aa7adc74d7 --- /dev/null +++ b/assets/ruvector/packages/ruvector-rairs.svg @@ -0,0 +1 @@ +ruvector-rairs — IVF with redundant assignment and amplified inverse residualAnimated RuVector crate banner. Points link to a primary centroid and, with a dashed line, to a secondary centroid.RUVECTOR / CRATE / IVF INDEXruvector-rairsIVF-Flat, RAIRS and SEIL indexes for low-nprobe recall.Vectors get a primary and a secondary list; SEIL shares blocks.cargo add ruvector-rairsprimary list + residual-amplified secondary list diff --git a/crates/ruvector-core/Cargo.toml b/crates/ruvector-core/Cargo.toml index 2f4d481132..e3250f02f9 100644 --- a/crates/ruvector-core/Cargo.toml +++ b/crates/ruvector-core/Cargo.toml @@ -8,6 +8,9 @@ authors.workspace = true repository.workspace = true readme = "README.md" description = "High-performance Rust vector database core with HNSW indexing" +homepage = "https://ruv.io" +keywords = ["vector-database", "hnsw", "ann", "embeddings", "quantization"] +categories = ["database-implementations", "algorithms", "data-structures"] [dependencies] # Core functionality diff --git a/crates/ruvector-core/README.md b/crates/ruvector-core/README.md index 18dbc71816..74a0d781a6 100644 --- a/crates/ruvector-core/README.md +++ b/crates/ruvector-core/README.md @@ -1,5 +1,7 @@ # Ruvector Core +

ruvector-core: HNSW vector database core

+ [![Crates.io](https://img.shields.io/crates/v/ruvector-core.svg)](https://crates.io/crates/ruvector-core) [![Documentation](https://docs.rs/ruvector-core/badge.svg)](https://docs.rs/ruvector-core) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) diff --git a/crates/ruvector-pq-search/Cargo.toml b/crates/ruvector-pq-search/Cargo.toml index 42ceeec11d..e25d226c0d 100644 --- a/crates/ruvector-pq-search/Cargo.toml +++ b/crates/ruvector-pq-search/Cargo.toml @@ -8,6 +8,7 @@ authors.workspace = true repository.workspace = true description = "Product Quantization with Asymmetric Distance Computation (ADC) for compressed approximate nearest-neighbor search — Flat PQ, IVF+PQ, and Residual-corrected PQ variants in safe Rust" readme = "README.md" +homepage = "https://ruv.io" keywords = ["vector-search", "ann", "product-quantization", "compression", "approximate-search"] categories = ["algorithms", "data-structures", "science"] diff --git a/crates/ruvector-pq-search/README.md b/crates/ruvector-pq-search/README.md index be51395d44..a9f0bac680 100644 --- a/crates/ruvector-pq-search/README.md +++ b/crates/ruvector-pq-search/README.md @@ -1,5 +1,7 @@ # ruvector-pq-search +

ruvector-pq-search: product quantization with ADC search

+ **Product Quantization with Asymmetric Distance Computation (ADC) for compressed approximate nearest-neighbor search — 64× compression in safe Rust.** [![crates.io](https://img.shields.io/crates/v/ruvector-pq-search)](https://crates.io/crates/ruvector-pq-search) @@ -19,35 +21,38 @@ a fraction of the storage and compute cost. | Variant | Description | Recall | Memory | |---------|-------------|--------|--------| -| `FlatPq` | Flat scan over PQ codes with ADC | ≥0.85 | **64× less** | -| `IvfPq` | IVF coarse quantizer + PQ codes | ≥0.80 | **64× less** | -| `ResidualPq` | Residual-corrected PQ for higher recall | ≥0.90 | **64× less** | +| `FlatPqIndex` | Flat scan over PQ codes with ADC | ≥0.85 | **64× less** | +| `IvfPqIndex` | IVF coarse quantizer + PQ codes | ≥0.80 | **64× less** | +| `ResidualPqIndex` | Residual-corrected PQ for higher recall | ≥0.90 | **64× less** | ## Quick start ```rust -use ruvector_pq_search::{FlatPq, PqConfig, PqIndex}; - -let cfg = PqConfig { - dims: 128, - m_subvecs: 8, // 8 sub-vectors of 16 dims each - k_centroids: 256, // 256 centroids per sub-vector (8-bit codes) - n_train: 50_000, // training set size for k-means -}; +use ruvector_pq_search::{FlatPqIndex, PqCodebook, PqConfig, PqSearch}; -let mut idx = FlatPq::new(cfg); +let dim = 32; +// 1,000 vectors of 32 dims, flat row-major (use your embeddings here). +let data: Vec = (0..1_000 * dim).map(|i| ((i * 7919) % 1000) as f32 / 1000.0).collect(); -// Train on representative data -let train_data: Vec> = /* ... */; -idx.train(&train_data); +// 8 sub-spaces x 16 centroids per sub-space (one u8 code each), Lloyd training. +let codebook = PqCodebook::train(PqConfig { m: 8, k: 16, iterations: 10, seed: 42 }, &data, dim); -// Insert (stored as 8-byte PQ codes) -idx.insert(0, &[0.1_f32; 128]); +// Or train the same codebook layout with e-means (ruvector-e-means): +let options = ruvector_e_means::Config { clusters: 16, epochs: 3, seed: 42, ..Default::default() }; +let e_means_codebook = PqCodebook::train_e_means(8, &data, dim, &options).unwrap(); -// Search with ADC (query stays at full precision) -let results: Vec<(u64, f32)> = idx.search(&[0.1_f32; 128], 10); +let mut index = FlatPqIndex::new(codebook); +for row in data.chunks_exact(dim) { + index.insert(row); +} +let hits = index.search(&data[..dim], 5); // ADC: the query stays full precision +println!("{:?}", hits.iter().map(|h| h.id).collect::>()); ``` +`IvfPqIndex::new_e_means` trains the coarse lists with e-means too, and +`try_insert` / `try_search` validate shape and finiteness first. Lloyd training +stays the default. + ## Compression tradeoffs | Method | Compression | Recall@10 | Build time | diff --git a/crates/ruvector-rairs/Cargo.toml b/crates/ruvector-rairs/Cargo.toml index 5c864a174f..a095e0929a 100644 --- a/crates/ruvector-rairs/Cargo.toml +++ b/crates/ruvector-rairs/Cargo.toml @@ -6,6 +6,8 @@ description = "RAIRS IVF: Redundant Assignment with Amplified Inverse Residual authors = ["ruvnet", "claude-flow"] license = "MIT OR Apache-2.0" repository = "https://github.com/ruvnet/ruvector" +homepage = "https://ruv.io" +readme = "README.md" keywords = ["ann", "ivf", "vector-search", "nearest-neighbor", "ruvector"] categories = ["algorithms", "data-structures"] diff --git a/crates/ruvector-rairs/README.md b/crates/ruvector-rairs/README.md new file mode 100644 index 0000000000..b93b3b4de0 --- /dev/null +++ b/crates/ruvector-rairs/README.md @@ -0,0 +1,45 @@ +# ruvector-rairs + +

ruvector-rairs: IVF with redundant assignment

+ +Inverted-file (IVF) indexes that keep recall high at low `nprobe`. Each vector +goes to its primary list and to a residual-amplified secondary list, so +neighbours near a cell boundary are still found when few lists are probed. + +| Index | Assignment | Layout | +|---|---|---| +| `IvfFlat` | single | flat lists (baseline) | +| `RairsStrict` | primary + secondary | flat lists | +| `RairsSeil` | primary + secondary | shared 32-vector blocks, deduplicated at query time | + +All three implement `AnnIndex`. Train with Lloyd's k-means (`train`) or with the +shared e-means optimizer (`train_e_means`, via `ruvector-e-means`). + +## Quick start + +```rust +use ruvector_rairs::{AnnIndex, RairsSeil}; + +let dim = 16; +// 2,000 vectors of 16 dims (use your embeddings here). +let corpus: Vec> = (0..2_000) + .map(|i| (0..dim).map(|d| ((i * 31 + d * 7) % 97) as f32 / 97.0).collect()) + .collect(); + +// 32 lists, 10 Lloyd iterations, seed 42, RAIR lambda 1.0. +let mut index = RairsSeil::new(dim, 32, 10, 42, 1.0); +index.train(&corpus).unwrap(); +// Or: index.train_e_means(&corpus, &ruvector_e_means::Config { clusters: 32, ..Default::default() }) +index.add(&corpus).unwrap(); + +let hits = index.search(&corpus[0], 5, 4).unwrap(); // k = 5, nprobe = 4 +println!("{:?}", hits.iter().map(|h| h.id).collect::>()); +``` + +The "RAIRS / SEIL" names follow the design notes in ADR-193; treat this crate as +an original implementation of redundant assignment and judge it on the +benchmarks in `src/main.rs`. + +## License + +MIT. Part of [RuVector](https://github.com/ruvnet/ruvector), see [ruv.io](https://ruv.io). From 2169baf81c3e5f6ecae706adc8b50ac248d7376a Mon Sep 17 00:00:00 2001 From: ruvnet Date: Wed, 11 Nov 2026 15:03:57 -0500 Subject: [PATCH 2/2] docs(crates): add docs.rs documentation links for core, pq-search, rairs Co-Authored-By: claude-flow --- crates/ruvector-core/Cargo.toml | 1 + crates/ruvector-pq-search/Cargo.toml | 1 + crates/ruvector-rairs/Cargo.toml | 1 + 3 files changed, 3 insertions(+) diff --git a/crates/ruvector-core/Cargo.toml b/crates/ruvector-core/Cargo.toml index e3250f02f9..0644d2c8ce 100644 --- a/crates/ruvector-core/Cargo.toml +++ b/crates/ruvector-core/Cargo.toml @@ -9,6 +9,7 @@ repository.workspace = true readme = "README.md" description = "High-performance Rust vector database core with HNSW indexing" homepage = "https://ruv.io" +documentation = "https://docs.rs/ruvector-core" keywords = ["vector-database", "hnsw", "ann", "embeddings", "quantization"] categories = ["database-implementations", "algorithms", "data-structures"] diff --git a/crates/ruvector-pq-search/Cargo.toml b/crates/ruvector-pq-search/Cargo.toml index e25d226c0d..df6b409de6 100644 --- a/crates/ruvector-pq-search/Cargo.toml +++ b/crates/ruvector-pq-search/Cargo.toml @@ -9,6 +9,7 @@ repository.workspace = true description = "Product Quantization with Asymmetric Distance Computation (ADC) for compressed approximate nearest-neighbor search — Flat PQ, IVF+PQ, and Residual-corrected PQ variants in safe Rust" readme = "README.md" homepage = "https://ruv.io" +documentation = "https://docs.rs/ruvector-pq-search" keywords = ["vector-search", "ann", "product-quantization", "compression", "approximate-search"] categories = ["algorithms", "data-structures", "science"] diff --git a/crates/ruvector-rairs/Cargo.toml b/crates/ruvector-rairs/Cargo.toml index a095e0929a..50217e5851 100644 --- a/crates/ruvector-rairs/Cargo.toml +++ b/crates/ruvector-rairs/Cargo.toml @@ -7,6 +7,7 @@ authors = ["ruvnet", "claude-flow"] license = "MIT OR Apache-2.0" repository = "https://github.com/ruvnet/ruvector" homepage = "https://ruv.io" +documentation = "https://docs.rs/ruvector-rairs" readme = "README.md" keywords = ["ann", "ivf", "vector-search", "nearest-neighbor", "ruvector"] categories = ["algorithms", "data-structures"]