[FEA] Establish "streaming batched build" example for CAGRA

[cjnolet]

Oracle has asked that we overlap batches as much as possible to support the ability to stream batches into an API so that we can start building a large CAGRA graph on the batches prior to the last batch being received. The idea is that we immediately start building so that we don't have to wait for the last batch to arrive.

We need to find a good API to enable this option without having to provide yet another completely new interface and code path.

One idea is that we once again provide a separate optimize() function in cuvs::neighbors::cagra::helpers so that we can build the all-neighbors graph in a streaming fashion (using a variant of our new cuvs::neighbors::all_neighbors APIs) and then run that graph through the optimization process.

This, of course, assumes the optimization process doesn't end up becoming the bottleneck. If it does, we might need to separate that our further.

[cjnolet]

cc @abc99lr

cc @jinsolp for awareness.

[abc99lr]

Thanks @cjnolet for creating this issue.

One idea is that we once again provide a separate optimize() function in cuvs::neighbors::cagra::helpers

It seems cuvs already have two versions cuvs::neighbor::cagra::optimize defined here. However, there are no declarations for these methods in any headers. The first step of this work would be adding a public headers for these two optimize methods, but do we want to keep using cuvs::neighbor::cagra namespace as showed in the code or declare them under cuvs::neighbor::cagra::helpers as you suggested here?

[cjnolet]

Hey @abc99lr, welcome back! Glad you are picking this up.

there are no declarations for these methods in any headers.

There are no declarations because these functions aren't part of the public APIs (yet). They used to be at one point when they were in RAFT, but we had removed them when bringing them over to cuVS while we determined whether they should be public again or not.

namespace as showed in the code or declare them under cuvs::neighbor::cagra::helpers as you suggested here?

As mentioned, the public functions should be exposed in the cagra::helpers namespace. This to separate them from the other standard-use CAGRA APIs and designate them as "special functions that not everyone will use, but which provide additional useful capabilities".

[jinsolp]

@cjnolet @abc99lr Is there anything I could help with here?

[cjnolet]

@jinsolp nope, I don’t want this to distract from other things (like HDBSCAN). This is a different batching that we are adding as an example in the examples.