CuVS-Java: Update readme files

java/README.md

@@ -1,14 +1,42 @@
-Prerequisites
--------------
+# CuVS Java API
 
-* JDK 22
-* Maven 3.9.6 or later
+CuVS Java API provides a Java based simple, efficient, and a robust vector search API.
 
-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.
+> [!CAUTION]
+> cuVS 25.02 contains an experimental version and updates to this API are expected in the coming release.
 
-Alternatively, please build libcuvs (`./build.sh libcuvs` from top level directory) before building the Java API with `./build.sh` from this directory.
 
-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.
+- gcc 11.4
+- [nvcc 12.4 or above](https://developer.nvidia.com/cuda-downloads)
+- [cmake 3.28 or above](https://cmake.org/download/)
+- [maven 3.9.6 or above](https://maven.apache.org/download.cgi)
+- [JDK 22](https://openjdk.org/projects/jdk/22/)
+- [Ubuntu 22.04](https://releases.ubuntu.com/jammy/)
+
+
+## Building
+
+libcuvs libraries are needed for this API. If libcuvs libraries are already not built please do `./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.
+
+:warning: If you notice the tests failing please replace `mvn verify` with `mvn clean package` in the `build.sh` script found in this directory and try again. This should build the API (and skip the tests).
+
+
+## Examples
+
+A few starter examples of CAGRA, HNSW, and Bruteforce index are provided in the `examples` directory.
+
+
+## Javadocs
+
+To generate javadocs, in this directory (after building the API) please do:
+
+```
+cd cuvs-java && mvn javadoc:javadoc
+```
+
+The generated javadocs can be found in `cuvs-java/target/apidocs`

java/examples/README.md

@@ -1,8 +1,55 @@
-Building and Running
---------------------
+# CuVS Java API Examples
 
-Make sure to have JDK 22 and Maven 3.9.6+.
+This maven project contains simple examples for CAGRA, HNSW, and Bruteforce algorithms.
 
-    mvn clean compile assembly:single
+## Prerequisites
+- All the prerequisites in the CuVS Java API readme
+- libcuvs libraries and Java API should already be built
+- In this directory do `mvn package`
 
-    java --enable-native-access=ALL-UNNAMED -jar ./target/cagra-sample-1.0-SNAPSHOT-jar-with-dependencies.jar
+## Run Examples
+
+### CAGRA Example
+Doing the following in the current directory:
+```
+java --enable-native-access=ALL-UNNAMED -cp target/cuvs-java-examples-25.02.0.jar:$HOME/.m2/repository/com/nvidia/cuvs/cuvs-java/25.02.0/cuvs-java-25.02.0.jar com.nvidia.cuvs.examples.CagraExample
+```
+Should output the following (with different timestamps):
+```
+[2025-02-07 13:08:45.640] [RAFT] [info] optimizing graph
+[2025-02-07 13:08:45.641] [RAFT] [info] Graph optimized, creating index
+[2025-02-07 13:08:45.650] [RAFT] [info] Saving CAGRA index with dataset
+Feb 07, 2025 1:08:45 PM com.nvidia.cuvs.examples.CagraExample main
+INFO: [{3=0.038782578, 2=0.3590463, 0=0.83774555}, {0=0.12472608, 2=0.21700792, 1=0.31918612}, {3=0.047766715, 2=0.20332818, 0=0.48305473}, {1=0.15224178, 0=0.59063464, 3=0.5986642}]
+Feb 07, 2025 1:08:45 PM com.nvidia.cuvs.examples.CagraExample main
+INFO: [{3=0.038782578, 2=0.3590463, 0=0.83774555}, {0=0.12472608, 2=0.21700792, 1=0.31918612}, {3=0.047766715, 2=0.20332818, 0=0.48305473}, {1=0.15224178, 0=0.59063464, 3=0.5986642}]
+```
+
+### HNSW Example
+Doing the following in the current directory:
+```
+java --enable-native-access=ALL-UNNAMED -cp target/cuvs-java-examples-25.02.0.jar:$HOME/.m2/repository/com/nvidia/cuvs/cuvs-java/25.02.0/cuvs-java-25.02.0.jar com.nvidia.cuvs.examples.HnswExample
+```
+Should output the following (with different timestamps):
+```
+[2025-02-07 13:09:51.443] [RAFT] [warning] Intermediate graph degree cannot be larger than dataset size, reducing it to 4
+[2025-02-07 13:09:51.443] [RAFT] [warning] Graph degree (64) cannot be larger than intermediate graph degree (3), reducing graph_degree.
+using ivf_pq::index_params nrows 4, dim 2, n_lists 4, pq_dim 8
+[2025-02-07 13:09:51.524] [RAFT] [info] optimizing graph
+[2025-02-07 13:09:51.525] [RAFT] [info] Graph optimized, creating index
+Feb 07, 2025 1:09:51 PM com.nvidia.cuvs.examples.HnswExample main
+INFO: [{3=0.038782578, 2=0.35904628, 0=0.8377455}, {0=0.12472608, 2=0.21700794, 1=0.31918612}, {3=0.047766715, 2=0.20332818, 0=0.48305473}, {1=0.15224178, 0=0.59063464, 3=0.59866416}]
+```
+
+### Bruteforce Example
+Doing the following in the current directory:
+```
+java --enable-native-access=ALL-UNNAMED -cp target/cuvs-java-examples-25.02.0.jar:$HOME/.m2/repository/com/nvidia/cuvs/cuvs-java/25.02.0/cuvs-java-25.02.0.jar com.nvidia.cuvs.examples.BruteForceExample
+```
+Should output the following (with different timestamps):
+```
+Feb 07, 2025 1:10:33 PM com.nvidia.cuvs.examples.BruteForceExample main
+INFO: [{3=0.038782537, 2=0.35904616, 0=0.83774555}, {0=0.12472606, 2=0.21700788, 1=0.3191862}, {3=0.047766685, 2=0.20332813, 0=0.48305476}, {1=0.15224183, 0=0.5906347, 3=0.5986643}]
+Feb 07, 2025 1:10:33 PM com.nvidia.cuvs.examples.BruteForceExample main
+INFO: [{3=0.038782537, 2=0.35904616, 0=0.83774555}, {0=0.12472606, 2=0.21700788, 1=0.3191862}, {3=0.047766685, 2=0.20332813, 0=0.48305476}, {1=0.15224183, 0=0.5906347, 3=0.5986643}]
+```

java/examples/pom.xml

@@ -20,17 +20,6 @@
       <!-- NOTE: The version automatically gets updated when ci/release/update-version.sh is invoked. -->
       <!--CUVS_JAVA#VERSION_UPDATE_MARKER_START--><version>25.02.0</version><!--CUVS_JAVA#VERSION_UPDATE_MARKER_END-->
     </dependency>
-    <dependency>
-      <groupId>org.slf4j</groupId>
-      <artifactId>slf4j-api</artifactId>
-      <version>2.0.13</version>
-    </dependency>
-    <dependency>
-      <groupId>org.slf4j</groupId>
-      <artifactId>slf4j-simple</artifactId>
-      <version>2.0.13</version>
-      <scope>runtime</scope>
-   </dependency>
   </dependencies>
 
   <build>

java/examples/src/main/java/com/nvidia/cuvs/examples/BruteForceExample.java

@@ -4,12 +4,10 @@
 import java.io.FileInputStream;
 import java.io.FileOutputStream;
 import java.io.InputStream;
-import java.lang.invoke.MethodHandles;
 import java.util.UUID;
+import java.util.logging.Logger;
 
 import com.nvidia.cuvs.SearchResults;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
 
 import com.nvidia.cuvs.BruteForceIndex;
 import com.nvidia.cuvs.BruteForceIndexParams;
@@ -18,7 +16,7 @@
 
 public class BruteForceExample {
 
-  private static final Logger log = LoggerFactory.getLogger(MethodHandles.lookup().lookupClass());
+  private static final Logger log = Logger.getLogger(BruteForceExample.class.getName());
 
   public static void main(String[] args) throws Throwable {
 

java/examples/src/main/java/com/nvidia/cuvs/examples/CagraExample.java

@@ -4,12 +4,10 @@
 import java.io.FileInputStream;
 import java.io.FileOutputStream;
 import java.io.InputStream;
-import java.lang.invoke.MethodHandles;
 import java.util.UUID;
+import java.util.logging.Logger;
 
 import com.nvidia.cuvs.SearchResults;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
 
 import com.nvidia.cuvs.CagraIndex;
 import com.nvidia.cuvs.CagraIndexParams;
@@ -21,7 +19,7 @@
 
 public class CagraExample {
 
-  private static final Logger log = LoggerFactory.getLogger(MethodHandles.lookup().lookupClass());
+  private static final Logger log = Logger.getLogger(CagraExample.class.getName());
 
   public static void main(String[] args) throws Throwable {
 

java/examples/src/main/java/com/nvidia/cuvs/examples/HnswExample.java

@@ -4,12 +4,8 @@
 import java.io.FileInputStream;
 import java.io.FileOutputStream;
 import java.io.InputStream;
-import java.lang.invoke.MethodHandles;
 import java.util.UUID;
-
-import com.nvidia.cuvs.SearchResults;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
+import java.util.logging.Logger;
 
 import com.nvidia.cuvs.CagraIndex;
 import com.nvidia.cuvs.CagraIndexParams;
@@ -20,10 +16,12 @@
 import com.nvidia.cuvs.HnswIndexParams;
 import com.nvidia.cuvs.HnswQuery;
 import com.nvidia.cuvs.HnswSearchParams;
+import com.nvidia.cuvs.SearchResults;
+
 
 public class HnswExample {
 
-  private static final Logger log = LoggerFactory.getLogger(MethodHandles.lookup().lookupClass());
+  private static final Logger log = Logger.getLogger(HnswExample.class.getName());
 
   public static void main(String[] args) throws Throwable {