Error Handling, Update Stability, Improved Java SDK

.github/workflows/prerelease.yml

@@ -17,6 +17,38 @@ permissions:
   contents: read
 
 jobs:
+  versioning:
+    name: Update Version
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Run TinySemVer
+        uses: ashvardanian/tinysemver@v2.0.1
+        with:
+          verbose: "true"
+          version-file: "VERSION"
+          update-version-in: |
+            package.json:"version": "(\d+\.\d+\.\d+)"
+            CITATION.cff:^version: (\d+\.\d+\.\d+)
+            Cargo.toml:^version = "(\d+\.\d+\.\d+)"
+            wasmer.toml:^version = "(\d+\.\d+\.\d+)"
+            conanfile.py:version = "(\d+\.\d+\.\d+)"
+            java/README.md:<version>(\d+\.\d+\.\d+)</version>
+            README.md:version = {(\d+\.\d+\.\d+)}
+            csharp/nuget/nuget-package.props:>(\d+\.\d+\.\d+)</Version>
+            CMakeLists.txt:VERSION (\d+\.\d+\.\d+)
+          update-major-version-in: |
+            include/usearch/index.hpp:^#define USEARCH_VERSION_MAJOR (\d+)
+          update-minor-version-in: |
+            include/usearch/index.hpp:^#define USEARCH_VERSION_MINOR (\d+)
+          update-patch-version-in: |
+            include/usearch/index.hpp:^#define USEARCH_VERSION_PATCH (\d+)
+          dry-run: "true"
+
   test_ubuntu_gcc:
     name: Ubuntu (GCC 12)
     runs-on: ubuntu-22.04
@@ -75,9 +107,9 @@ jobs:
 
         # Java
       - name: Setup Java
-        uses: actions/setup-java@v3
+        uses: actions/setup-java@v4
         with:
-          java-version: "11"
+          java-version: "21"
           distribution: "adopt"
       - name: Setup Gradle
         uses: gradle/gradle-build-action@v2.4.2
@@ -93,7 +125,7 @@ jobs:
         run: |
           mkdir -p "${{ github.workspace }}/csharp/lib/runtimes/linux-x64/native"
           cp "${{ github.workspace }}/build_artifacts/libusearch_c.so" "${{ github.workspace }}/csharp/lib/runtimes/linux-x64/native"
-          dotnet test -c Release
+          dotnet test -c Debug --logger "console;verbosity=detailed"
         shell: bash
         working-directory: ${{ github.workspace }}/csharp
 
@@ -168,7 +200,7 @@ jobs:
         run: |
           mkdir -p "${{ github.workspace }}/csharp/lib/runtimes/linux-x64/native"
           cp "${{ github.workspace }}/build_artifacts/libusearch_c.so" "${{ github.workspace }}/csharp/lib/runtimes/linux-x64/native"
-          dotnet test -c Release
+          dotnet test -c Debug --logger "console;verbosity=detailed"
         shell: bash
         working-directory: ${{ github.workspace }}/csharp
 
@@ -232,7 +264,7 @@ jobs:
         run: |
           mkdir -p "${{ github.workspace }}/csharp/lib/runtimes/osx-x64/native"
           cp "${{ github.workspace }}/build_artifacts/libusearch_c.dylib" "${{ github.workspace }}/csharp/lib/runtimes/osx-x64/native"
-          dotnet test -c Release
+          dotnet test -c Debug --logger "console;verbosity=detailed" --filter "FullyQualifiedName!=Cloud.Unum.USearch.Tests.UsearchIndexTests.PersistAndRestore"
         shell: bash
         working-directory: ${{ github.workspace }}/csharp
 
@@ -288,7 +320,7 @@ jobs:
         run: |
           mkdir -p "${{ github.workspace }}\csharp\lib\runtimes\win-x64\native"
           cp "${{ github.workspace }}\build_artifacts\libusearch_c.dll" "${{ github.workspace }}\csharp\lib\runtimes\win-x64\native"
-          dotnet test -c Release
+          dotnet test -c Debug --logger "console;verbosity=detailed"
         shell: bash
         working-directory: ${{ github.workspace }}/csharp
 
@@ -299,7 +331,7 @@ jobs:
       - uses: actions/checkout@v4
       - run: git submodule update --init --recursive
       - name: Build
-        uses: docker/build-push-action@v4
+        uses: docker/build-push-action@v6
         with:
           context: .
           load: true

.github/workflows/release.yml

@@ -18,23 +18,44 @@ permissions:
 
 jobs:
   versioning:
-    name: Semantic Release
-    runs-on: ubuntu-22.04
+    name: Update Version
+    runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout
+        uses: actions/checkout@v4
         with:
+          fetch-depth: 0
           persist-credentials: false
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
       - name: Set up Cargo
         uses: actions-rs/toolchain@v1
         with:
           toolchain: stable
           override: true
-      - name: Bump version
-        run: npm install --save-dev --prefix ./package-ci @semantic-release/exec @semantic-release/git conventional-changelog-eslint semantic-release && npx --prefix ./package-ci semantic-release
+      - name: Run TinySemVer
+        uses: ashvardanian/tinysemver@v2.0.1
+        with:
+          verbose: "true"
+          version-file: "VERSION"
+          update-version-in: |
+            package.json:"version": "(\d+\.\d+\.\d+)"
+            CITATION.cff:^version: (\d+\.\d+\.\d+)
+            Cargo.toml:^version = "(\d+\.\d+\.\d+)"
+            wasmer.toml:^version = "(\d+\.\d+\.\d+)"
+            conanfile.py:version = "(\d+\.\d+\.\d+)"
+            java/README.md:<version>(\d+\.\d+\.\d+)</version>
+            README.md:version = {(\d+\.\d+\.\d+)}
+            csharp/nuget/nuget-package.props:>(\d+\.\d+\.\d+)</Version>
+            CMakeLists.txt:VERSION (\d+\.\d+\.\d+)
+          update-major-version-in: |
+            include/usearch/index.hpp:^#define USEARCH_VERSION_MAJOR (\d+)
+          update-minor-version-in: |
+            include/usearch/index.hpp:^#define USEARCH_VERSION_MINOR (\d+)
+          update-patch-version-in: |
+            include/usearch/index.hpp:^#define USEARCH_VERSION_PATCH (\d+)
+          dry-run: "false"
+          push: "true"
+          create-release: "true"
+          github-token: ${{ secrets.SEMANTIC_RELEASE_TOKEN }}
 
   rebase:
     name: Rebase Dev. Branch
@@ -469,7 +490,8 @@ jobs:
         os:
           - macos-latest
           - ubuntu-22.04
-          - windows-latest
+          # Windows pre-buld is not working
+          # - windows-latest
         exclude:
           - arch: x86
             os: macos-latest
@@ -614,9 +636,9 @@ jobs:
       - name: Pull Git submodules
         run: git submodule update --init --recursive
       - name: Set up Java
-        uses: actions/setup-java@v3
+        uses: actions/setup-java@v4
         with:
-          java-version: "11"
+          java-version: "21"
           distribution: "adopt"
       - name: Setup Gradle
         uses: gradle/gradle-build-action@v2.4.2
@@ -678,7 +700,7 @@ jobs:
             unum/usearch
             ghcr.io/${{ github.repository }}
       - name: Build and push
-        uses: docker/build-push-action@v4
+        uses: docker/build-push-action@v6
         with:
           context: .
           push: true

.gitignore

@@ -10,10 +10,12 @@ bin
 .cache
 
 # C++ builds
-build
-build_release
-build_debug
-build_artifacts
+/build
+/build_release
+/build_debug
+/build_relwithdebinfo
+/build_profile
+/build_artifacts
 _deps
 CMakeCache.txt
 CMakeFiles

.vscode/launch.json

@@ -176,6 +176,19 @@
                 "datasets/wiki_1M/groundtruth.public.100K.ibin",
             ],
             "justMyCode": true
+        },
+        {
+            "name": "Unit Test C#",
+            "type": "coreclr",
+            "request": "launch",
+            "program": "dotnet",
+            "args": [
+                "test",
+                "-c",
+                "Debug"
+            ],
+            "cwd": "${workspaceFolder}/csharp",
+            "stopAtEntry": false
         }
     ]
 }

.vscode/settings.json

@@ -120,7 +120,8 @@
     "xstring": "cpp",
     "xtr1common": "cpp",
     "xtree": "cpp",
-    "xutility": "cpp"
+    "xutility": "cpp",
+    "execution": "cpp"
   },
   "cSpell.words": [
     "allclose",
@@ -139,6 +140,7 @@
     "dtype",
     "DUSEARCH",
     "emcmake",
+    "endregion",
     "equi",
     "equidimensional",
     "FAISS",
@@ -151,6 +153,11 @@
     "hnswlib",
     "ibin",
     "jaccard",
+    "Jemalloc",
+    "Kullback",
+    "Leibler",
+    "libjemalloc",
+    "libomp",
     "libusearch",
     "linalg",
     "longlong",
@@ -174,10 +181,13 @@
     "SLOC",
     "Sonatype",
     "sorensen",
+    "Sørensen",
     "sqeuclidean",
+    "stringzilla",
     "Struct",
     "swar",
     "tanimoto",
+    "tparam",
     "tqdm",
     "uninitialize",
     "unumusearch",

.vscode/tasks.json

@@ -3,7 +3,7 @@
     "tasks": [
         {
             "label": "Linux Build Debug",
-            "command": "cmake -DCMAKE_CXX_COMPILER=gcc-12 -DCMAKE_CXX_COMPILER=g++-12 -DUSEARCH_BUILD_TEST_CPP=1 -DUSEARCH_BUILD_TEST_C=1 -DUSEARCH_BUILD_LIB_C=1 -DUSEARCH_USE_OPENMP=1 -DUSEARCH_USE_SIMSIMD=1 -DUSEARCH_USE_JEMALLOC=1 -DCMAKE_BUILD_TYPE=Debug -B ./build_debug && cmake --build ./build_debug --config Debug",
+            "command": "cmake -DCMAKE_CXX_COMPILER=gcc-12 -DCMAKE_CXX_COMPILER=g++-12 -DUSEARCH_BUILD_TEST_CPP=1 -DUSEARCH_BUILD_TEST_C=1 -DUSEARCH_BUILD_LIB_C=1 -DUSEARCH_USE_OPENMP=0 -DUSEARCH_USE_SIMSIMD=1 -DUSEARCH_USE_JEMALLOC=1 -DCMAKE_BUILD_TYPE=Debug -B ./build_debug && cmake --build ./build_debug --config Debug",
             "args": [],
             "type": "shell",
             "problemMatcher": [
@@ -12,7 +12,7 @@
         },
         {
             "label": "Linux Build Release",
-            "command": "cmake -DCMAKE_CXX_COMPILER=gcc-12 -DCMAKE_CXX_COMPILER=g++-12 -DUSEARCH_BUILD_TEST_CPP=1 -DUSEARCH_BUILD_TEST_C=1 -DUSEARCH_BUILD_LIB_C=1 -DUSEARCH_USE_OPENMP=1 -DUSEARCH_USE_SIMSIMD=1 -DUSEARCH_USE_JEMALLOC=1 -DCMAKE_BUILD_TYPE=Release -B ./build_release && cmake --build ./build_release --config RelWithDebInfo",
+            "command": "cmake -DCMAKE_CXX_COMPILER=gcc-12 -DCMAKE_CXX_COMPILER=g++-12 -DUSEARCH_BUILD_TEST_CPP=1 -DUSEARCH_BUILD_TEST_C=1 -DUSEARCH_BUILD_LIB_C=1 -DUSEARCH_USE_OPENMP=0 -DUSEARCH_USE_SIMSIMD=1 -DUSEARCH_USE_JEMALLOC=1 -DCMAKE_BUILD_TYPE=Release -B ./build_release && cmake --build ./build_release --config RelWithDebInfo",
             "args": [],
             "type": "shell",
             "problemMatcher": [

BENCHMARKS.md

@@ -61,19 +61,19 @@ Within this repository you will find two commonly used utilities:
 To achieve best highest results we suggest compiling locally for the target architecture.
 
 ```sh
-cmake -B ./build_release -USEARCH_BUILD_BENCH_CPP=1 -DUSEARCH_BUILD_TEST_C=1 -DUSEARCH_USE_OPENMP=1 -DUSEARCH_USE_SIMSIMD=1 
-cmake --build ./build_release --config Release -j
-./build_release/bench_cpp --help
+cmake -USEARCH_BUILD_BENCH_CPP=1 -DUSEARCH_BUILD_TEST_C=1 -DUSEARCH_USE_OPENMP=1 -DUSEARCH_USE_SIMSIMD=1 -DCMAKE_BUILD_TYPE=RelWithDebInfo -B build_profile
+cmake --build build_profile --config RelWithDebInfo -j
+build_profile/bench_cpp --help
 ```
 
 Which would print the following instructions.
 
 ```txt
 SYNOPSIS
-        ./build_release/bench_cpp [--vectors <path>] [--queries <path>] [--neighbors <path>] [-b] [-j
-                                  <integer>] [-c <integer>] [--expansion-add <integer>]
-                                  [--expansion-search <integer>] [--native|--f16quant|--i8quant]
-                                  [--ip|--l2sq|--cos|--haversine] [-h]
+        build_profile/bench_cpp [--vectors <path>] [--queries <path>] [--neighbors <path>] [-b] [-j
+                                <integer>] [-c <integer>] [--expansion-add <integer>]
+                                [--expansion-search <integer>] [--native|--f16quant|--i8quant]
+                                [--ip|--l2sq|--cos|--haversine] [-h]
 
 OPTIONS
         --vectors <path>
@@ -111,12 +111,12 @@ OPTIONS
 Here is an example of running the C++ benchmark:
 
 ```sh
-./build_release/bench_cpp \
+build_profile/bench_cpp \
     --vectors datasets/wiki_1M/base.1M.fbin \
     --queries datasets/wiki_1M/query.public.100K.fbin \
     --neighbors datasets/wiki_1M/groundtruth.public.100K.ibin
 
-./build_release/bench_cpp \
+build_profile/bench_cpp \
     --vectors datasets/t2i_1B/base.1B.fbin \
     --queries datasets/t2i_1B/query.public.100K.fbin \
     --neighbors datasets/t2i_1B/groundtruth.public.100K.ibin \
@@ -201,17 +201,17 @@ With `perf`:
 
 ```sh
 # Pass environment variables with `-E`, and `-d` for details
-sudo -E perf stat -d ./build_release/bench_cpp ...
-sudo -E perf mem -d ./build_release/bench_cpp ...
+sudo -E perf stat -d build_profile/bench_cpp ...
+sudo -E perf mem -d build_profile/bench_cpp ...
 # Sample on-CPU functions for the specified command, at 1 Kilo Hertz:
-sudo -E perf record -F 1000 ./build_release/bench_cpp ...
-perf record -d -e arm_spe// -- ./build_release/bench_cpp ..
+sudo -E perf record -F 1000 build_profile/bench_cpp ...
+perf record -d -e arm_spe// -- build_profile/bench_cpp ..
 ```
 
 ### Caches
 
 ```sh
-sudo perf stat -e 'faults,dTLB-loads,dTLB-load-misses,cache-misses,cache-references' ./build_release/bench_cpp ...
+sudo perf stat -e 'faults,dTLB-loads,dTLB-load-misses,cache-misses,cache-references' build_profile/bench_cpp ...
 ```
 
 Typical output on a 1M vectors dataset is:

CITATION.cff

@@ -5,7 +5,7 @@ authors:
     given-names: "Ash"
     orcid: "https://orcid.org/0000-0002-4882-1815"
 title: "USearch by Unum Cloud"
-version: 2.12.0
+version: 2.13.0
 doi: 10.5281/zenodo.7949416
 date-released: 2023-10-22
 url: "https://github.com/unum-cloud/usearch"