Rust: builder-based params, per-module errors

[yan-zaretskiy]

Here we further rework the Rust bindings API to be more idiomatic, and also align closer with the underlying C++ namespacing. More specifically:

• Every param type is built with a validating builder instead of new() + chained set_*. Unset fields keep the C-library defaults; out-of-range values are rejected by build().

// before
let params = IndexParams::new()?.set_graph_degree(64).set_intermediate_graph_degree(128);
// after
let params = IndexParams::builder().graph_degree(64).intermediate_graph_degree(128).build()?;

Thus, by the time the params instance is constructed, it is guaranteed to be valid.

• Resources stream is set at construction. Instead of a post-construction setter, we provide a custom stream via unsafe { Resources::with_stream(stream) }. The Resources::new() keeps the default stream.
• Module layout mirrors C++ namespacing. ANN indexes moved under cuvs::neighbors.
• The crate-wide cuvs::Error/cuvs::Result are removed. Each module returns its own thiserror enum, e.g. CagraError or IvfFlatError. This enables individual index errors to be more granular, instead of creating a single error type encompassing all failure modes.

[tgockel]

This isn't a big deal, but might be worth noting -- the exponent p is not always honored. Over in the C code, this is only moved when metric_arg exists. Might be worth a comment...it's not a regression from the existing C code and I'm not sure how to address it without a major refactor.

[yan-zaretskiy]

In the C++ implementation the exponent p is read only when the LpUnexpanded metric is requested, and the only two places that don't reject this metric are pairwise_distance and brute_force. Both of them do read the value of p. So in this sense, the p is always honored by algos that support the Lp metric, even though the C API obscures this fact.

[tgockel]

You probably don't want to export these native cudaDataType_t, cuvsIvfPqCodebookGen, and cuvsIvfPqListLayout types publicly, since everything else is wrapped.

[tgockel]

This applies to other news in this file, too: Does the C library have a facility to handle validation of these FFI params for you? It might be worth using to avoid duplicating work.

[yan-zaretskiy]

The internal C++ impl can validate some of those params. I'd rather not split the validation logic across FFI. It makes for cleaner errors and keeps it in one place. Ideally, I'd drop them all, but then we need to strengthen the C side validation.

[tgockel]

Understandable.

[tgockel]

Very minor, but prefer .unwrap_or_else(|| unsafe { (*params.handle).algo.into() }) so you only deref in the None case. unwrap_or eagerly evaluates even when algo is Some(_).

[tgockel]

Since this is deleted, the example over in the README Rust API that uses IndexParams::new() won't work any more. For Rust, there's a clever trick you can use to make sure your READMEs always compile:

#[cfg(doctest)]
#[doc = include_str!("../../README.md")]
pub struct ReadmeDocTests;

This picks up the triple-ticks and makes sure they compile (https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.html). Rust is the assumed language, but the examples currently all specify c/python/rust/etc -- Rust doctest will ignore non-Rust languages.

There are some other things in examples/rust that use this same pattern that fail to compile. CI can catch this for you by running cargo build --examples