Expose Vamana build and serialize through a public cuvs-java API

cuVS provides a GPU Vamana builder and DiskANN-compatible serialization,
and the generated Panama bindings for it already exist in cuvs-java, but
there is no public API, so nothing can call Vamana from Java. This adds
VamanaIndex and VamanaIndexParams beside CagraIndex.

Scope is build and serialize only, matching the native surface. cuVS
exposes no Vamana search entry point, so neither does this.

serialize takes a Path prefix rather than an OutputStream, because one
native call writes two files, the graph at the prefix and the dataset at
prefix + ".data".

VamanaIndexParams.Builder mirrors the native RAFT_EXPECTS checks so an
invalid configuration fails in Java with a readable message instead of
inside a GPU kernel.

The native index may retain a non-owning device view of the dataset, so
the index holds a reference to keep it alive and closes it only when it
created the matrix from a float[][].

newVamanaIndexBuilder is added to CuVSProvider as a default method rather
than an abstract one so that providers written against an earlier version
of the interface keep compiling.

Author: shaunakkapur

fern/pages/neighbors/vamana.md

@@ -10,7 +10,7 @@ Vamana works well when you want to build large DiskANN-compatible graph indexes
 
 [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.
+Vamana currently supports build and serialize operations in NVIDIA cuVS. Search is performed by loading the serialized index with DiskANN. Java exposes build and serialize through `VamanaIndex`; Go does not currently expose standalone Vamana bindings.
 
 ### Building an index
 
@@ -82,6 +82,30 @@ index_params = vamana.IndexParams(
 index = vamana.build(index_params, dataset)
 ```
 
+</Tab>
+<Tab title="Java">
+
+```java
+import com.nvidia.cuvs.*;
+
+float[][] dataset = loadData();
+
+try (CuVSResources resources = CuVSResources.create()) {
+  VamanaIndexParams indexParams = new VamanaIndexParams.Builder()
+      .withGraphDegree(64)
+      .withVisitedSize(128)
+      .withQueueSize(255)
+      .build();
+
+  try (VamanaIndex index = VamanaIndex.newBuilder(resources)
+      .withDataset(dataset)
+      .withIndexParams(indexParams)
+      .build()) {
+    // ...
+  }
+}
+```
+
 </Tab>
 <Tab title="Rust">
 
@@ -164,6 +188,23 @@ index = vamana.build(vamana.IndexParams(), dataset)
 vamana.save("/tmp/cuvs-vamana/index", index, include_dataset=True)
 ```
 
+</Tab>
+<Tab title="Java">
+
+```java
+import com.nvidia.cuvs.*;
+import java.nio.file.Path;
+
+try (CuVSResources resources = CuVSResources.create();
+     VamanaIndex index = VamanaIndex.newBuilder(resources)
+         .withDataset(loadData())
+         .build()) {
+
+  // Writes DiskANN-compatible files using this path prefix.
+  index.serialize(Path.of("/tmp/cuvs-vamana/index"), true);
+}
+```
+
 </Tab>
 <Tab title="Rust">
 

java/cuvs-java/src/main/java/com/nvidia/cuvs/VamanaIndex.java

@@ -0,0 +1,126 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package com.nvidia.cuvs;
+
+import com.nvidia.cuvs.spi.CuVSProvider;
+import java.nio.file.Path;
+import java.util.Objects;
+
+/**
+ * {@link VamanaIndex} encapsulates a Vamana index, along with methods to build
+ * it on the GPU and serialize it in the DiskANN file format.
+ * <p>
+ * Vamana is the graph construction algorithm behind DiskANN. cuVS currently
+ * provides build and serialize only. There is no Vamana search API, so a
+ * serialized index is searched by loading it with DiskANN.
+ *
+ * @since 26.10
+ */
+public interface VamanaIndex extends AutoCloseable {
+
+  @Override
+  void close() throws Exception;
+
+  /**
+   * Gets the dimensionality of the vectors in this index.
+   *
+   * @return the number of dimensions
+   */
+  int getDimensions() throws Throwable;
+
+  /**
+   * Serializes the index in the DiskANN file format, including the dataset.
+   * <p>
+   * This writes <b>two</b> files, {@code filePrefix} holding the graph and
+   * {@code filePrefix + ".data"} holding the dataset.
+   *
+   * @param filePrefix the prefix that output file names are derived from
+   */
+  default void serialize(Path filePrefix) throws Throwable {
+    serialize(filePrefix, true);
+  }
+
+  /**
+   * Serializes the index in the DiskANN file format.
+   * <p>
+   * When {@code includeDataset} is true this writes {@code filePrefix} holding
+   * the graph and {@code filePrefix + ".data"} holding the dataset. When it is
+   * false only {@code filePrefix} is written.
+   * <p>
+   * The argument is a prefix and not a complete file name, matching the native
+   * {@code file_prefix} parameter.
+   *
+   * @param filePrefix     the prefix that output file names are derived from
+   * @param includeDataset whether to write the dataset alongside the graph
+   */
+  void serialize(Path filePrefix, boolean includeDataset) throws Throwable;
+
+  /**
+   * Gets an instance of {@link CuVSResources}
+   *
+   * @return an instance of {@link CuVSResources}
+   */
+  CuVSResources getCuVSResources();
+
+  /**
+   * Creates a new Builder with an instance of {@link CuVSResources}.
+   *
+   * @param cuvsResources an instance of {@link CuVSResources}
+   * @throws UnsupportedOperationException if the provider does not support cuvs
+   */
+  static Builder newBuilder(CuVSResources cuvsResources) {
+    Objects.requireNonNull(cuvsResources);
+    return CuVSProvider.provider().newVamanaIndexBuilder(cuvsResources);
+  }
+
+  /**
+   * Builder helps configure and create an instance of {@link VamanaIndex}.
+   */
+  interface Builder {
+
+    /**
+     * Sets the dataset for building the {@link VamanaIndex}.
+     *
+     * @param vectors a two-dimensional float array
+     * @return an instance of this Builder
+     */
+    Builder withDataset(float[][] vectors);
+
+    /**
+     * Sets the dataset for building the {@link VamanaIndex}.
+     * <p>
+     * The native builder accepts {@code float}, {@code half}, {@code uint8},
+     * and {@code int8} datasets. Of those, {@link CuVSMatrix.DataType#FLOAT},
+     * {@link CuVSMatrix.DataType#HALF}, and {@link CuVSMatrix.DataType#BYTE}
+     * are reachable from Java today, where {@code BYTE} is unsigned.
+     * {@code int8} has no corresponding {@code DataType}.
+     * <p>
+     * The native index may retain a non-owning device view of the dataset
+     * rather than copying it, so the caller must keep this matrix open for at
+     * least as long as the index and close it afterwards. A dataset supplied as
+     * a {@code float[][]} is created and closed by the index instead.
+     *
+     * @param dataset a {@link CuVSMatrix} object containing the vectors
+     * @return an instance of this Builder
+     */
+    Builder withDataset(CuVSMatrix dataset);
+
+    /**
+     * Registers an instance of configured {@link VamanaIndexParams} with this
+     * Builder.
+     *
+     * @param vamanaIndexParameters An instance of VamanaIndexParams
+     * @return An instance of this Builder
+     */
+    Builder withIndexParams(VamanaIndexParams vamanaIndexParameters);
+
+    /**
+     * Builds and returns an instance of {@link VamanaIndex}.
+     *
+     * @return an instance of {@link VamanaIndex}
+     */
+    VamanaIndex build() throws Throwable;
+  }
+}