Expose graph and dataset accessors for CAGRA to C/Python

[benfred]

Add the ability to get the graph and dataset from a CAGRA index to the c-api and python apis, as well as being able to reconstruct the cagra index from a graph and dataset.

The eventual goal here is to be more flexible in terms of allowing other serialization formats. Rather than supporting every format inside of cuvs, by exposing the raw data needed to recreate a cagra index - we can let consumers of cuvs decide how they want to serialize an index.

[mythrocks]

👍

[mythrocks]

👍

[ldematte]

@benfred I tried to check this out and build locally, but it does not compile, claiming template errors around matrix_vector_op.
However, I have the same problem on the current "main" branch-25.08 -- so I suppose it's unrelated to your changes, and something else broke it (I'm 100% sure it was compiling a week ago)

Scratch that, I needed to update my conda environment as the raft include files changed.

[ldematte]

Some minor comments while I was writing a Java wrapper for this

[ldematte]

TL;DR: I liked the API as it was in 2f22d53 (cuvsCagraIndexGetGraphView + cuvsCagraIndexCopyGraph), but I like the last implementation ("view" + cuvsCopyMatrix) even more.

If anything, in a follow-up PR, it would be great to have partial copy (e.g. cuvsCopyMatrix with fromRow, toRow or something similar) so in the Java side I don't have to replicate what is done there and/or in raft::copy_matrix<T>.

[benfred]

If anything, in a follow-up PR, it would be great to have partial copy (e.g. cuvsCopyMatrix with fromRow, toRow or something similar) so in the Java side I don't have to replicate what is done there and/or in raft::copy_matrix.

How about having something like a cuvsSliceMatrix or cuvsSliceRows functions to do this ? (where the cuvsSliceRows function doesn't copy data, just adjusts the shape / strides / data pointer to slice the matrix without copying data). We could then pass the slice to the copy matrix function , like:

// get the cagra graph
DLManagedTensor graph;
cuvsCagraIndexGetGraph(index, &graph);

// get the first 1K rows from the graph
DLManagedTensor subgraph;
cuvsSliceMatrix(&graph, 0, 1024,  &subgraph);

// copy the subgraph to host  memory
cuvsCopyMatrix(&subgraph,  &subgraphHost);

(this actually makes me think that I should rename cuvsCopyMatrix to cuvsMatrixCopy , so that we can have cuvsMatrixSlice etc - and to be consistent with other cuvs API's)

[mythrocks]

if you think there is value for C users too, and want to add a specific C API, I can use that. My 2c: it's not worth the effort: C users can/will just use cudaMemcpy/cudaMemcpy2D (but I'll let you decide on this point)...

@benfred / @cjnolet will keep me honest here.

I think the C-lang user should not use cudaMemcpy directly. The dataset is likely to be padded to an 8-byte boundary when stored in __device__ memory. A naive cudaMemcpy will copy/interpret padding bytes that aren't actual data.

Using a cuVS-specific copy() API would be preferable to insulate the user from padding. If a future CAGRA implementation does away with the padding, the cuVSMatrixCopy() user would be insulated from the change. The cudaMemcpy() user might not.

[ldematte]

How about having something like a cuvsSliceMatrix or cuvsSliceRows functions to do this

That's even better!

this actually makes me think that I should rename cuvsCopyMatrix to cuvsMatrixCopy

++

[mythrocks]

A couple of nitpicks, but this looks good to go.

[mythrocks]

/merge

[lowener]

Can't we return device_matrix_view without intermediate copies? I am not 100% sure I see the benefits of adding this class compared to device views?

[benfred]

The python API is using the c-api (instead of the c++ api) - meaning we can't use device_matrix_view directly inside python. Instead we're using dlpack.DLManagedTensor inside our C-API.

Previous to this PR, our c-api only accepted dlpack arrays as inputs (and would either use the contents in functions like cagra::build - or fill pre-allocated arrays with the outputs in functions like cagra::search). We hadn't yet exposed memory that was allocated in our C++ codebase to python.

This PR changes that - and we are now returning dlpack DLManagedTensor objects that return memory that is owned by and allocated inside our C++ codebase. This code does that without copying the data , with the flow going : device_matrix_view (c++) -> DLManagedTensor (C) -> DeviceTensorView (python) . At each step we aren't copying the data, there isn't an intermediate copy - so much as intermediate objects that have a pointer to the original data, and also extra information such as the shape/dtype/strides etc.

This DeviceTensorView code is necessary because we didn't have anything that would take a DLManagedTensor and return something that could be easily consumed in python. the closest object we had was the pylibraft.device_ndarray object - but that object wouldn't have worked here.

[cjnolet]

Nitpick- can we please rename this to cuvsCagraIndexFromParams or cuvsCagraIndexFromArgs? I'd like to keep tthe API design consistent and having to specify specific args in the name will get unwieldy quickly.

[benfred]

I renamed to cuvsCagraIndexFromArgs in the last commit - (went with FromArgs instead of FromParams - since I think the FromParams could be confused with the Index Params we use to build the index)

[bdice]

Approving packaging changes.