[CuVS-Java] Automate panama bindings generation, Include IVF_PQ parameters in CAGRA index parameters and other changes (rapidsai#831)

The PR includes code changes for the following:

- Automation of Panama bindings generation using jextract.
- Adding the ability to configure IVF_PQ index and search parameters via the cuvs-java API (to adapt with the following [underlying changes](rapidsai@18a3d90)). 
- Updating HNSW example to show the above.
- Updating the readme files.
- Simplifying logging in examples.
- Bumping up the maven-javadoc-plugin version.
- Updating and consolidating gitignore file.
- Removing unused imports etc.

Please note that the existing Panama classes are being deleted because they were manually created and managed. With the new cleaner approach, this will not be needed anymore. Now these binding classes will be generated at build time and so no need to be in the codebase.

Authors:
  - Vivek Narang (https://github.com/narangvivek10)
  - Ishan Chattopadhyaya (https://github.com/chatman)

Approvers:
  - rhdong (https://github.com/rhdong)
  - James Lamb (https://github.com/jameslamb)

URL: rapidsai#831

Author: narangvivek10

java/.gitignore

@@ -0,0 +1,7 @@
+# cuvs-java
+/cuvs-java/target/
+/cuvs-java/bin/
+/cuvs-java/src/main/java22/com/nvidia/cuvs/internal/panama/
+/cuvs-java/*.cag
+# examples
+/examples/target/

java/README.md

@@ -1,14 +1,27 @@
-Prerequisites
--------------
+# CuVS Java API
 
-* JDK 22
-* Maven 3.9.6 or later
 
-To build this API, please do `./build.sh java` in the top level directory. Since this API is dependent on `libcuvs` it must be noted that `libcuvs` gets built automatically before building this API.
+CuVS Java API provides a Java based simple, efficient, and a robust vector search API.
 
-Alternatively, please build libcuvs (`./build.sh libcuvs` from top level directory) before building the Java API with `./build.sh` from this directory.
+> [!CAUTION]
+> CuVS 25.06 contains an experimental version and updates to this API are expected in the coming release.
 
-Building
---------
+## Prerequisites
 
-`./build.sh` will generate the `libcuvs_java.so` file in the `internal/` directory, and then build the final jar file for the cuVS Java API in the `cuvs-java/` directory.
+- [CuVS libraries](https://docs.rapids.ai/api/cuvs/stable/build/#build-from-source)
+- [maven 3.9.6 or above](https://maven.apache.org/download.cgi)
+- [JDK 22](https://openjdk.org/projects/jdk/22/)
+- [jextract for JDK 22](https://jdk.java.net/jextract/) (If not already installed, the build script downloads it)
+
+
+## Building
+
+The libcuvs C and C++ libraries are needed for this API. If libcuvs libraries have not been built and installed, use `./build.sh libcuvs java` in the top level directory to build this API.
+
+Alternatively, if libcuvs libraries are already built and you just want to build this API, please
+do `./build.sh java` in the top level directory or just do `./build.sh` in this directory.
+
+
+## Examples
+
+A few starter examples of CAGRA, HNSW, and Bruteforce index are provided in the `examples` directory.

java/build.sh

@@ -1,14 +1,23 @@
+#!/bin/bash
+
+set -e -u -o pipefail
+
 VERSION="25.06.0" # Note: The version is updated automatically when ci/release/update-version.sh is invoked
 GROUP_ID="com.nvidia.cuvs"
-SO_FILE_PATH="./internal"
+SO_FILE_PATH="./internal/build"
 
-if [ -z "$CMAKE_PREFIX_PATH" ]; then
-    export CMAKE_PREFIX_PATH=`pwd`/../cpp/build
+if [ -z "${CMAKE_PREFIX_PATH:=}" ]; then
+  export CMAKE_PREFIX_PATH="$(pwd)/../cpp/build"
 fi
 
-cd internal && cmake . && cmake --build . \
-  && cd .. \
-  && mvn install:install-file -DgroupId=$GROUP_ID -DartifactId=cuvs-java-internal -Dversion=$VERSION -Dpackaging=so -Dfile=$SO_FILE_PATH/libcuvs_java.so \
+cmake -B ./internal/build -S ./internal
+cmake --build ./internal/build
+
+# Generate Panama FFM API bindings and update (if any of them changed)
+./panama-bindings/generate-bindings.sh
+
+# Build the java layer
+mvn install:install-file -DgroupId=$GROUP_ID -DartifactId=cuvs-java-internal -Dversion=$VERSION -Dpackaging=so -Dfile=$SO_FILE_PATH/libcuvs_java.so \
   && cd cuvs-java \
   && mvn verify \
   && mvn install:install-file -Dfile=./target/cuvs-java-$VERSION-jar-with-dependencies.jar -DgroupId=$GROUP_ID -DartifactId=cuvs-java -Dversion=$VERSION -Dpackaging=jar

java/cuvs-java/.gitignore

@@ -258,7 +258,7 @@
         <plugin>
             <groupId>org.apache.maven.plugins</groupId>
             <artifactId>maven-javadoc-plugin</artifactId>
-            <version>2.9.1</version>
+            <version>3.11.2</version>
             <executions>
                 <execution>
                     <id>attach-javadocs</id>
@@ -298,7 +298,4 @@
         </plugin>
         </plugins>
     </build>
-
-
-
 </project>

java/cuvs-java/pom.xml

@@ -16,13 +16,12 @@
 
 package com.nvidia.cuvs;
 
-import com.nvidia.cuvs.spi.CuVSProvider;
-
 import java.io.InputStream;
 import java.io.OutputStream;
 import java.nio.file.Path;
 import java.util.Objects;
-import java.util.UUID;
+
+import com.nvidia.cuvs.spi.CuVSProvider;
 
 /**
  *

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

@@ -40,7 +40,7 @@ public class BruteForceQuery {
    * @param queryVectors 2D float query vector array
    * @param mapping      an instance of ID mapping
    * @param topK         the top k results to return
-   * @param prefilter    the prefilter data to use while searching the BRUTEFORCE
+   * @param prefilters   the prefilters data to use while searching the BRUTEFORCE
    *                     index
    * @param numDocs      Maximum of bits in each prefilter, representing number of documents in this index.
    *                     Used only when prefilter(s) is/are passed.

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

@@ -20,7 +20,6 @@
 import java.io.OutputStream;
 import java.nio.file.Path;
 import java.util.Objects;
-import java.util.UUID;
 
 import com.nvidia.cuvs.spi.CuVSProvider;
 

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

@@ -29,6 +29,7 @@ public class CagraIndexParams {
   private final int graphDegree;
   private final int nnDescentNiter;
   private final int numWriterThreads;
+  private final CuVSIvfPqParams cuVSIvfPqParams;
 
   /**
    * Enum that denotes which ANN algorithm is used to build CAGRA graph.
@@ -158,15 +159,106 @@ private CuvsDistanceType(int value) {
 
   }
 
-  private CagraIndexParams(int intermediateGraphDegree, int graphDegree,
-      CagraGraphBuildAlgo CuvsCagraGraphBuildAlgo, int nnDescentNiter, int writerThreads,
-      CuvsDistanceType cuvsDistanceType) {
+  /**
+   * Enum that denotes codebook gen options.
+   */
+  public enum CodebookGen {
+
+    PER_SUBSPACE(0),
+
+    PER_CLUSTER(1);
+
+    /**
+     * The value for the enum choice.
+     */
+    public final int value;
+
+    private CodebookGen(int value) {
+      this.value = value;
+    }
+  }
+
+  /**
+   * Enum that denotes cuda datatypes.
+   */
+  public enum CudaDataType {
+
+    CUDA_R_16F(2),
+
+    CUDA_C_16F(6),
+
+    CUDA_R_16BF(14),
+
+    CUDA_C_16BF(15),
+
+    CUDA_R_32F(0),
+
+    CUDA_C_32F(4),
+
+    CUDA_R_64F(1),
+
+    CUDA_C_64F(5),
+
+    CUDA_R_4I(16),
+
+    CUDA_C_4I(17),
+
+    CUDA_R_4U(18),
+
+    CUDA_C_4U(19),
+
+    CUDA_R_8I(3),
+
+    CUDA_C_8I(7),
+
+    CUDA_R_8U(8),
+
+    CUDA_C_8U(9),
+
+    CUDA_R_16I(20),
+
+    CUDA_C_16I(21),
+
+    CUDA_R_16U(22),
+
+    CUDA_C_16U(23),
+
+    CUDA_R_32I(10),
+
+    CUDA_C_32I(11),
+
+    CUDA_R_32U(12),
+
+    CUDA_C_32U(13),
+
+    CUDA_R_64I(24),
+
+    CUDA_C_64I(25),
+
+    CUDA_R_64U(26),
+
+    CUDA_C_64U(27),
+
+    CUDA_R_8F_E4M3(28),
+
+    CUDA_R_8F_E5M2(29);
+
+    public final int value;
+
+    private CudaDataType(int value) {
+      this.value = value;
+    }
+  }
+
+  private CagraIndexParams(int intermediateGraphDegree, int graphDegree, CagraGraphBuildAlgo CuvsCagraGraphBuildAlgo,
+      int nnDescentNiter, int writerThreads, CuvsDistanceType cuvsDistanceType, CuVSIvfPqParams cuVSIvfPqParams) {
     this.intermediateGraphDegree = intermediateGraphDegree;
     this.graphDegree = graphDegree;
     this.cuvsCagraGraphBuildAlgo = CuvsCagraGraphBuildAlgo;
     this.nnDescentNiter = nnDescentNiter;
     this.numWriterThreads = writerThreads;
     this.cuvsDistanceType = cuvsDistanceType;
+    this.cuVSIvfPqParams = cuVSIvfPqParams;
   }
 
   /**
@@ -216,11 +308,19 @@ public int getNumWriterThreads() {
     return numWriterThreads;
   }
 
+  /**
+   * Gets the IVF_PQ parameters.
+   */
+  public CuVSIvfPqParams getCuVSIvfPqParams() {
+    return cuVSIvfPqParams;
+  }
+
   @Override
   public String toString() {
     return "CagraIndexParams [cuvsCagraGraphBuildAlgo=" + cuvsCagraGraphBuildAlgo + ", cuvsDistanceType="
         + cuvsDistanceType + ", intermediateGraphDegree=" + intermediateGraphDegree + ", graphDegree=" + graphDegree
-        + ", nnDescentNiter=" + nnDescentNiter + ", numWriterThreads=" + numWriterThreads + "]";
+        + ", nnDescentNiter=" + nnDescentNiter + ", numWriterThreads=" + numWriterThreads + ", cuVSIvfPqParams="
+        + cuVSIvfPqParams + "]";
   }
 
   /**
@@ -234,8 +334,10 @@ public static class Builder {
     private int graphDegree = 64;
     private int nnDescentNumIterations = 20;
     private int numWriterThreads = 2;
+    private CuVSIvfPqParams cuVSIvfPqParams = new CuVSIvfPqParams.Builder().build();
 
-    public Builder() { }
+    public Builder() {
+    }
 
     /**
      * Sets the degree of input graph for pruning.
@@ -305,14 +407,25 @@ public Builder withNumWriterThreads(int numWriterThreads) {
       return this;
     }
 
+    /**
+     * Sets the IVF_PQ index parameters.
+     *
+     * @param cuVSIvfPqParams the IVF_PQ index parameters
+     * @return an instance of Builder
+     */
+    public Builder withCuVSIvfPqParams(CuVSIvfPqParams cuVSIvfPqParams) {
+      this.cuVSIvfPqParams = cuVSIvfPqParams;
+      return this;
+    }
+
     /**
      * Builds an instance of {@link CagraIndexParams}.
      *
      * @return an instance of {@link CagraIndexParams}
      */
     public CagraIndexParams build() {
-      return new CagraIndexParams(intermediateGraphDegree, graphDegree, cuvsCagraGraphBuildAlgo,
-          nnDescentNumIterations, numWriterThreads, cuvsDistanceType);
+      return new CagraIndexParams(intermediateGraphDegree, graphDegree, cuvsCagraGraphBuildAlgo, nnDescentNumIterations,
+          numWriterThreads, cuvsDistanceType, cuVSIvfPqParams);
     }
   }
 }