Rust: builder-based params, per-module errors

.github/CODEOWNERS

@@ -16,7 +16,6 @@ python/            @NVIDIA/cuvs-python-codeowners
 
 #rust code owners
 rust/              @NVIDIA/cuvs-rust-codeowners
-examples/rust/     @NVIDIA/cuvs-rust-codeowners
 
 #docs code owners
 docs/              @NVIDIA/cuvs-docs-codeowners

README.md

@@ -143,66 +143,49 @@ For more code examples of the C APIs, including drop-in Cmake project templates,
 
 ### Rust API
 
-```rust
-use cuvs::cagra::{Index, IndexParams, SearchParams};
-use cuvs::{ManagedTensor, Resources, Result};
-
-use ndarray::s;
-use ndarray_rand::rand_distr::Uniform;
-use ndarray_rand::RandomExt;
+```rust,no_run
+use cuvs::distance::DistanceType;
+use cuvs::neighbors::cagra::{Index, IndexParams, SearchParams};
+use cuvs::{AsDlTensor, AsDlTensorMut, DLPackError, DLTensorView, DLTensorViewMut, Resources};
+
+// cuVS is agnostic about where your vectors live: `build` and `search` accept
+// any type implementing `AsDlTensor` (inputs) / `AsDlTensorMut` (outputs). Wrap
+// your own GPU buffer by implementing these traits. See `rust/cuvs/examples`
+// for a complete, runnable CUDA-backed implementation.
+struct GpuTensor;
+impl AsDlTensor for GpuTensor {
+    fn as_dl_tensor(&self) -> Result<DLTensorView<'_>, DLPackError> {
+        unimplemented!("wrap your device buffer; see rust/cuvs/examples")
+    }
+}
+impl AsDlTensorMut for GpuTensor {
+    fn as_dl_tensor_mut(&mut self) -> Result<DLTensorViewMut<'_>, DLPackError> {
+        unimplemented!("wrap your device buffer; see rust/cuvs/examples")
+    }
+}
 
-/// Example showing how to index and search data with CAGRA
-fn cagra_example() -> Result<()> {
+fn main() -> Result<(), Box<dyn std::error::Error>> {
     let res = Resources::new()?;
 
-    // Create a new random dataset to index
-    let n_datapoints = 65536;
-    let n_features = 512;
-    let dataset =
-        ndarray::Array::<f32, _>::random((n_datapoints, n_features), Uniform::new(0., 1.0));
-
-    // build the cagra index
-    let build_params = IndexParams::new()?;
-    let index = Index::build(&res, &build_params, &dataset)?;
-    println!(
-        "Indexed {}x{} datapoints into cagra index",
-        n_datapoints, n_features
-    );
-
-    // use the first 4 points from the dataset as queries : will test that we get them back
-    // as their own nearest neighbor
-    let n_queries = 4;
-    let queries = dataset.slice(s![0..n_queries, ..]);
-
-    let k = 10;
-
-    // CAGRA search API requires queries and outputs to be on device memory
-    // copy query data over, and allocate new device memory for the distances/ neighbors
-    // outputs
-    let queries = ManagedTensor::from(&queries).to_device(&res)?;
-    let mut neighbors_host = ndarray::Array::<u32, _>::zeros((n_queries, k));
-    let neighbors = ManagedTensor::from(&neighbors_host).to_device(&res)?;
-
-    let mut distances_host = ndarray::Array::<f32, _>::zeros((n_queries, k));
-    let distances = ManagedTensor::from(&distances_host).to_device(&res)?;
-
-    let search_params = SearchParams::new()?;
-
-    index.search(&res, &search_params, &queries, &neighbors, &distances)?;
-
-    // Copy back to host memory
-    distances.to_host(&res, &mut distances_host)?;
-    neighbors.to_host(&res, &mut neighbors_host)?;
-
-    // nearest neighbors should be themselves, since queries are from the
-    // dataset
-    println!("Neighbors {:?}", neighbors_host);
-    println!("Distances {:?}", distances_host);
+    // Build a CAGRA index over your dataset.
+    let dataset = GpuTensor;
+    let index_params = IndexParams::builder()
+        .metric(DistanceType::L2Expanded)
+        .graph_degree(64)
+        .build()?;
+    let index = Index::build(&res, &index_params, &dataset)?;
+
+    // Search for the k nearest neighbors of each query, writing the results into
+    // the neighbor and distance device buffers.
+    let queries = GpuTensor;
+    let (mut neighbors, mut distances) = (GpuTensor, GpuTensor);
+    let search_params = SearchParams::builder().itopk_size(64).build()?;
+    index.search(&res, &search_params, &queries, &mut neighbors, &mut distances)?;
+
     Ok(())
 }
 ```
 
-For more code examples of the Rust APIs, including a drop-in project templates, please refer to the [Rust examples](https://github.com/rapidsai/cuvs/tree/main/examples/rust).
 
 ## Contributing
 

fern/docs.yml

@@ -536,44 +536,38 @@ navigation:
             path: "./pages/rust_api/rust-api-cuvs-dlpack.md"
           - page: "cuVS Error"
             path: "./pages/rust_api/rust-api-cuvs-error.md"
+          - page: "cuVS Neighbors"
+            path: "./pages/rust_api/rust-api-cuvs-neighbors.md"
           - page: "cuVS Resources"
             path: "./pages/rust_api/rust-api-cuvs-resources.md"
           - page: "cuVS Distance"
             path: "./pages/rust_api/rust-api-cuvs-distance.md"
-          - page: "cuVS Distance Type"
-            path: "./pages/rust_api/rust-api-cuvs-distance-type.md"
-          - page: "cuVS Brute Force"
-            path: "./pages/rust_api/rust-api-cuvs-brute-force.md"
-          - page: "cuVS Cagra"
-            path: "./pages/rust_api/rust-api-cuvs-cagra.md"
-          - page: "cuVS Cagra Index"
-            path: "./pages/rust_api/rust-api-cuvs-cagra-index.md"
-          - page: "cuVS Cagra Index Params"
-            path: "./pages/rust_api/rust-api-cuvs-cagra-index-params.md"
-          - page: "cuVS Cagra Search Params"
-            path: "./pages/rust_api/rust-api-cuvs-cagra-search-params.md"
-          - page: "cuVS IVF Flat"
-            path: "./pages/rust_api/rust-api-cuvs-ivf-flat.md"
-          - page: "cuVS IVF Flat Index"
-            path: "./pages/rust_api/rust-api-cuvs-ivf-flat-index.md"
-          - page: "cuVS IVF Flat Index Params"
-            path: "./pages/rust_api/rust-api-cuvs-ivf-flat-index-params.md"
-          - page: "cuVS IVF Flat Search Params"
-            path: "./pages/rust_api/rust-api-cuvs-ivf-flat-search-params.md"
-          - page: "cuVS IVF PQ"
-            path: "./pages/rust_api/rust-api-cuvs-ivf-pq.md"
-          - page: "cuVS IVF PQ Index"
-            path: "./pages/rust_api/rust-api-cuvs-ivf-pq-index.md"
-          - page: "cuVS IVF PQ Index Params"
-            path: "./pages/rust_api/rust-api-cuvs-ivf-pq-index-params.md"
-          - page: "cuVS IVF PQ Search Params"
-            path: "./pages/rust_api/rust-api-cuvs-ivf-pq-search-params.md"
-          - page: "cuVS Vamana"
-            path: "./pages/rust_api/rust-api-cuvs-vamana.md"
-          - page: "cuVS Vamana Index"
-            path: "./pages/rust_api/rust-api-cuvs-vamana-index.md"
-          - page: "cuVS Vamana Index Params"
-            path: "./pages/rust_api/rust-api-cuvs-vamana-index-params.md"
+          - page: "cuVS Neighbors Brute Force"
+            path: "./pages/rust_api/rust-api-cuvs-neighbors-brute-force.md"
+          - page: "cuVS Neighbors Cagra"
+            path: "./pages/rust_api/rust-api-cuvs-neighbors-cagra.md"
+          - page: "cuVS Neighbors Cagra Index"
+            path: "./pages/rust_api/rust-api-cuvs-neighbors-cagra-index.md"
+          - page: "cuVS Neighbors Cagra Params"
+            path: "./pages/rust_api/rust-api-cuvs-neighbors-cagra-params.md"
+          - page: "cuVS Neighbors IVF Flat"
+            path: "./pages/rust_api/rust-api-cuvs-neighbors-ivf-flat.md"
+          - page: "cuVS Neighbors IVF Flat Index"
+            path: "./pages/rust_api/rust-api-cuvs-neighbors-ivf-flat-index.md"
+          - page: "cuVS Neighbors IVF Flat Params"
+            path: "./pages/rust_api/rust-api-cuvs-neighbors-ivf-flat-params.md"
+          - page: "cuVS Neighbors IVF PQ"
+            path: "./pages/rust_api/rust-api-cuvs-neighbors-ivf-pq.md"
+          - page: "cuVS Neighbors IVF PQ Index"
+            path: "./pages/rust_api/rust-api-cuvs-neighbors-ivf-pq-index.md"
+          - page: "cuVS Neighbors IVF PQ Params"
+            path: "./pages/rust_api/rust-api-cuvs-neighbors-ivf-pq-params.md"
+          - page: "cuVS Neighbors Vamana"
+            path: "./pages/rust_api/rust-api-cuvs-neighbors-vamana.md"
+          - page: "cuVS Neighbors Vamana Index"
+            path: "./pages/rust_api/rust-api-cuvs-neighbors-vamana-index.md"
+          - page: "cuVS Neighbors Vamana Params"
+            path: "./pages/rust_api/rust-api-cuvs-neighbors-vamana-params.md"
       - section: "Go API Documentation"
         path: "./pages/go_api/index.md"
         contents:

fern/pages/neighbors/bruteforce.md

@@ -6,7 +6,7 @@ Brute-force works well when exact results matter, the dataset is small enough to
 
 ## Example API Usage
 
-[C API](/api-reference/c-api-neighbors-brute-force) | [C++ API](/api-reference/cpp-api-neighbors-brute-force) | [Python API](/api-reference/python-api-neighbors-brute-force) | [Java API](/api-reference/java-api-com-nvidia-cuvs-bruteforceindex) | [Rust API](/api-reference/rust-api-cuvs-brute-force) | [Go API](/api-reference/go-api-brute-force)
+[C API](/api-reference/c-api-neighbors-brute-force) | [C++ API](/api-reference/cpp-api-neighbors-brute-force) | [Python API](/api-reference/python-api-neighbors-brute-force) | [Java API](/api-reference/java-api-com-nvidia-cuvs-bruteforceindex) | [Rust API](/api-reference/rust-api-cuvs-neighbors-brute-force) | [Go API](/api-reference/go-api-brute-force)
 
 ### Building an index
 

fern/pages/neighbors/cagra.md

@@ -6,7 +6,7 @@ CAGRA works well when you want strong recall, high GPU throughput, and fast grap
 
 ## Example API Usage
 
-[C API](/api-reference/c-api-neighbors-cagra) | [C++ API](/api-reference/cpp-api-neighbors-cagra) | [Python API](/api-reference/python-api-neighbors-cagra) | [Java API](/api-reference/java-api-com-nvidia-cuvs-cagraindex) | [Rust API](/api-reference/rust-api-cuvs-cagra) | [Go API](/api-reference/go-api-cagra)
+[C API](/api-reference/c-api-neighbors-cagra) | [C++ API](/api-reference/cpp-api-neighbors-cagra) | [Python API](/api-reference/python-api-neighbors-cagra) | [Java API](/api-reference/java-api-com-nvidia-cuvs-cagraindex) | [Rust API](/api-reference/rust-api-cuvs-neighbors-cagra) | [Go API](/api-reference/go-api-cagra)
 
 ### Building an index
 

fern/pages/neighbors/ivfflat.md

@@ -8,7 +8,7 @@ IVF-Flat works well when the index fits in GPU memory, exact recall is not requi
 
 ## Example API Usage
 
-[C API](/api-reference/c-api-neighbors-ivf-flat) | [C++ API](/api-reference/cpp-api-neighbors-ivf-flat) | [Python API](/api-reference/python-api-neighbors-ivf-flat) | [Rust API](/api-reference/rust-api-cuvs-ivf-flat) | [Go API](/api-reference/go-api-ivf-flat)
+[C API](/api-reference/c-api-neighbors-ivf-flat) | [C++ API](/api-reference/cpp-api-neighbors-ivf-flat) | [Python API](/api-reference/python-api-neighbors-ivf-flat) | [Rust API](/api-reference/rust-api-cuvs-neighbors-ivf-flat) | [Go API](/api-reference/go-api-ivf-flat)
 
 ### Building an index
 

fern/pages/neighbors/ivfpq.md

@@ -8,7 +8,7 @@ IVF-PQ works well when the dataset is too large for full-precision storage on th
 
 ## Example API Usage
 
-[C API](/api-reference/c-api-neighbors-ivf-pq) | [C++ API](/api-reference/cpp-api-neighbors-ivf-pq) | [Python API](/api-reference/python-api-neighbors-ivf-pq) | [Java IVF-PQ Params](/api-reference/java-api-com-nvidia-cuvs-cuvsivfpqparams) | [Rust API](/api-reference/rust-api-cuvs-ivf-pq) | [Go API](/api-reference/go-api-ivf-pq)
+[C API](/api-reference/c-api-neighbors-ivf-pq) | [C++ API](/api-reference/cpp-api-neighbors-ivf-pq) | [Python API](/api-reference/python-api-neighbors-ivf-pq) | [Java IVF-PQ Params](/api-reference/java-api-com-nvidia-cuvs-cuvsivfpqparams) | [Rust API](/api-reference/rust-api-cuvs-neighbors-ivf-pq) | [Go API](/api-reference/go-api-ivf-pq)
 
 Java currently exposes IVF-PQ parameter classes for CAGRA graph construction, not a standalone IVF-PQ index/search binding. The runnable standalone examples below cover C, C++, Python, Rust, and Go.
 

fern/pages/neighbors/vamana.md

@@ -8,7 +8,7 @@ Vamana works well when you want to build large DiskANN-compatible graph indexes
 
 ## Example API Usage
 
-[C API](/api-reference/c-api-neighbors-vamana) | [C++ API](/api-reference/cpp-api-neighbors-vamana) | [Python API](/api-reference/python-api-neighbors-vamana) | [Rust API](/api-reference/rust-api-cuvs-vamana)
+[C API](/api-reference/c-api-neighbors-vamana) | [C++ API](/api-reference/cpp-api-neighbors-vamana) | [Python API](/api-reference/python-api-neighbors-vamana) | [Rust API](/api-reference/rust-api-cuvs-neighbors-vamana)
 
 Vamana currently supports build and serialize operations in NVIDIA cuVS. Search is performed by loading the serialized index with DiskANN. Java and Go do not currently expose standalone Vamana bindings.
 

fern/pages/rust_api/index.md

@@ -13,28 +13,25 @@ These pages are generated from the Rust crate sources under `rust/cuvs/src`.
 - [`cuvs`](/api-reference/rust-api-cuvs)
 - [`cuvs::dlpack`](/api-reference/rust-api-cuvs-dlpack)
 - [`cuvs::error`](/api-reference/rust-api-cuvs-error)
+- [`cuvs::neighbors`](/api-reference/rust-api-cuvs-neighbors)
 - [`cuvs::resources`](/api-reference/rust-api-cuvs-resources)
 
 ## Distance
 
 - [`cuvs::distance`](/api-reference/rust-api-cuvs-distance)
-- [`cuvs::distance_type`](/api-reference/rust-api-cuvs-distance-type)
 
 ## Nearest Neighbors
 
-- [`cuvs::brute_force`](/api-reference/rust-api-cuvs-brute-force)
-- [`cuvs::cagra`](/api-reference/rust-api-cuvs-cagra)
-- [`cuvs::cagra::index`](/api-reference/rust-api-cuvs-cagra-index)
-- [`cuvs::cagra::index_params`](/api-reference/rust-api-cuvs-cagra-index-params)
-- [`cuvs::cagra::search_params`](/api-reference/rust-api-cuvs-cagra-search-params)
-- [`cuvs::ivf_flat`](/api-reference/rust-api-cuvs-ivf-flat)
-- [`cuvs::ivf_flat::index`](/api-reference/rust-api-cuvs-ivf-flat-index)
-- [`cuvs::ivf_flat::index_params`](/api-reference/rust-api-cuvs-ivf-flat-index-params)
-- [`cuvs::ivf_flat::search_params`](/api-reference/rust-api-cuvs-ivf-flat-search-params)
-- [`cuvs::ivf_pq`](/api-reference/rust-api-cuvs-ivf-pq)
-- [`cuvs::ivf_pq::index`](/api-reference/rust-api-cuvs-ivf-pq-index)
-- [`cuvs::ivf_pq::index_params`](/api-reference/rust-api-cuvs-ivf-pq-index-params)
-- [`cuvs::ivf_pq::search_params`](/api-reference/rust-api-cuvs-ivf-pq-search-params)
-- [`cuvs::vamana`](/api-reference/rust-api-cuvs-vamana)
-- [`cuvs::vamana::index`](/api-reference/rust-api-cuvs-vamana-index)
-- [`cuvs::vamana::index_params`](/api-reference/rust-api-cuvs-vamana-index-params)
+- [`cuvs::neighbors::brute_force`](/api-reference/rust-api-cuvs-neighbors-brute-force)
+- [`cuvs::neighbors::cagra`](/api-reference/rust-api-cuvs-neighbors-cagra)
+- [`cuvs::neighbors::cagra::index`](/api-reference/rust-api-cuvs-neighbors-cagra-index)
+- [`cuvs::neighbors::cagra::params`](/api-reference/rust-api-cuvs-neighbors-cagra-params)
+- [`cuvs::neighbors::ivf_flat`](/api-reference/rust-api-cuvs-neighbors-ivf-flat)
+- [`cuvs::neighbors::ivf_flat::index`](/api-reference/rust-api-cuvs-neighbors-ivf-flat-index)
+- [`cuvs::neighbors::ivf_flat::params`](/api-reference/rust-api-cuvs-neighbors-ivf-flat-params)
+- [`cuvs::neighbors::ivf_pq`](/api-reference/rust-api-cuvs-neighbors-ivf-pq)
+- [`cuvs::neighbors::ivf_pq::index`](/api-reference/rust-api-cuvs-neighbors-ivf-pq-index)
+- [`cuvs::neighbors::ivf_pq::params`](/api-reference/rust-api-cuvs-neighbors-ivf-pq-params)
+- [`cuvs::neighbors::vamana`](/api-reference/rust-api-cuvs-neighbors-vamana)
+- [`cuvs::neighbors::vamana::index`](/api-reference/rust-api-cuvs-neighbors-vamana-index)
+- [`cuvs::neighbors::vamana::params`](/api-reference/rust-api-cuvs-neighbors-vamana-params)