usearch 2.8.16 → 2.9.0

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,7 +1,7 @@
 name: Report a bug
 description: Something doesn't work as expected?
 title: "Bug: "
-labels: ["bug", "invalid"]
+labels: ["bug"]
 assignees:
   - octocat
 body:

package/.github/workflows/prerelease.yml

@@ -61,9 +61,9 @@ jobs:
         with:
           node-version: 20
       - name: Build JavaScript
-        run: npm install
+        run: npm ci
       - name: Test JavaScript
-        run: npm ci && npm test
+        run: npm test
 
         # Rust
       - name: Test Rust
@@ -154,7 +154,6 @@ jobs:
           node-version: 20
       - name: Build and test JavaScript
         run: |
-          npm install
           npm ci
           npm test
 
@@ -212,9 +211,9 @@ jobs:
         with:
           node-version: 20
       - name: Build JavaScript
-        run: npm install
+        run: npm ci
       - name: Test JavaScript
-        run: npm ci && npm test
+        run: npm test
 
         # ObjC/Swift
       - name: Build ObjC/Swift
@@ -274,9 +273,9 @@ jobs:
         with:
           node-version: 20
       - name: Build JavaScript
-        run: npm install
+        run: npm ci
       - name: Test JavaScript
-        run: npm ci && npm test
+        run: npm test
 
         # C#
       - name: Setup .NET ${{ env.DOTNET_VERSION }}
@@ -303,3 +302,30 @@ jobs:
           context: .
           load: true
           push: false
+
+
+  build_wheels:
+    name: Build Python ${{ matrix.python-version }} for ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    needs: [test_ubuntu_gcc, test_ubuntu_clang, test_macos, test_windows]
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["37", "38", "39", "310", "311", "312"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+        # We only need QEMU for Linux builds
+      - name: Setup QEMU
+        if: matrix.os == 'ubuntu-latest'
+        uses: docker/setup-qemu-action@v3
+      - name: Install cibuildwheel
+        run: python -m pip install cibuildwheel
+      - name: Build wheels
+        run: cibuildwheel --output-dir wheelhouse
+        env:
+          CIBW_BUILD: cp${{ matrix.python-version }}-*

package/.github/workflows/release.yml

@@ -349,39 +349,36 @@ jobs:
             * ${{ steps.hashes.outputs.asset_name_15 }} : `${{ steps.hashes.outputs.asset_hash_15 }}`
 
   build_wheels:
-    name: Build Python
-    needs: versioning
+    name: Build Python ${{ matrix.python-version }} for ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
+    needs: versioning
     strategy:
-      fail-fast: false
       matrix:
-        os: [ubuntu-22.04, macOS-11, windows-2022]
-
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["37", "38", "39", "310", "311", "312"]
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           ref: "main"
-      - uses: actions/setup-python@v3
-
-      - name: Setup Docker
-        if: matrix.os == 'ubuntu-22.04'
-        uses: crazy-max/ghaction-setup-docker@v1.0.0
+      - name: Set up Python
+        uses: actions/setup-python@v5
         with:
-          version: 23.0.1
-
+          python-version: 3.x
       - name: Setup QEMU
-        if: matrix.os == 'ubuntu-22.04'
-        uses: docker/setup-qemu-action@v2.1.0
-
-      - name: Install CIBuildWheel
+        if: matrix.os == 'ubuntu-latest' # We only need QEMU for Linux builds
+        uses: docker/setup-qemu-action@v3
+      - name: Install cibuildwheel
         run: python -m pip install cibuildwheel
-
       - name: Build wheels
-        run: python -m cibuildwheel
-
-      - uses: actions/upload-artifact@v3
+        run: cibuildwheel --output-dir wheelhouse
+        env:
+          CIBW_BUILD: cp${{ matrix.python-version }}-*
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
         with:
+          name: cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }}
           path: ./wheelhouse/*.whl
+          overwrite: true
 
   publish_python:
     name: Publish Python
@@ -395,17 +392,20 @@ jobs:
 
     steps:
       - name: Download artifacts
-        uses: actions/download-artifact@v3.0.2
+        uses: actions/download-artifact@v4
         with:
-          path: ./dist/
+          # unpacks all CIBW artifacts into dist/
+          pattern: cibw-*
+          path: dist
+          merge-multiple: true
 
       - name: Publish to PyPi
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
-          packages-dir: ./dist/artifact
+          packages-dir: dist
           verbose: true
           print-hash: true
-
+          
   publish_javascript:
     name: Publish JavaScript
     needs: versioning
@@ -432,7 +432,6 @@ jobs:
 
       - name: Build and Test
         run: |
-          npm install
           npm ci
           npm test
           npm run typegen

package/.gitmodules

@@ -3,4 +3,7 @@
 	url = https://github.com/ashvardanian/simsimd
 [submodule "fp16"]
 	path = fp16
-	url = https://github.com/maratyszcza/fp16
+	url = https://github.com/maratyszcza/fp16
+[submodule "stringzilla"]
+	path = stringzilla
+	url = https://github.com/ashvardanian/stringzilla

package/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.8.16
+version: 2.9.0
 doi: 10.5281/zenodo.7949416
 date-released: 2023-10-22
 url: "https://github.com/unum-cloud/usearch"

package/CMakeLists.txt

@@ -13,6 +13,11 @@ if (CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
     set(USEARCH_IS_MAIN_PROJECT ON)
 endif ()
 
+# Allow CMake 3.13+ to override options when using FetchContent / add_subdirectory
+if (POLICY CMP0077)
+    cmake_policy(SET CMP0077 NEW)
+endif ()
+
 # Options
 option(USEARCH_INSTALL "Install CMake targets" OFF)
 
@@ -31,11 +36,6 @@ option(USEARCH_BUILD_WOLFRAM "Compile Wolfram Language bindings" OFF)
 set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake ${CMAKE_MODULE_PATH})
 include(ExternalProject)
 
-# Allow CMake 3.13+ to override options when using FetchContent / add_subdirectory
-if (POLICY CMP0077)
-    cmake_policy(SET CMP0077 NEW)
-endif ()
-
 # Configuration
 include(GNUInstallDirs)
 set(USEARCH_TARGET_NAME ${PROJECT_NAME})
@@ -186,9 +186,7 @@ function (setup_target TARGET_NAME)
             target_link_libraries(${TARGET_NAME} PRIVATE OpenMP::OpenMP_CXX)
         endif ()
 
-        if (CMAKE_HOST_SYSTEM_NAME MATCHES "Darwin")
-            target_link_libraries(${TARGET_NAME} PRIVATE Threads::Threads)
-        endif ()
+        target_link_libraries(${TARGET_NAME} PRIVATE Threads::Threads)
 
     elseif (CMAKE_CXX_COMPILER_ID MATCHES "Clang")
         target_compile_options(

package/CONTRIBUTING.md

@@ -130,7 +130,26 @@ Still, if you have Docker running on any desktop OS, you can use it to build and
 
 ```sh
 pip install cibuildwheel
-cibuildwheel --platform linux
+cibuildwheel
+cibuildwheel --platform linux                   # works on any OS and builds all Linux backends
+cibuildwheel --platform linux --archs x86_64    # 64-bit x86, the most common on desktop and servers
+cibuildwheel --platform linux --archs aarch64   # 64-bit Arm for mobile devices, Apple M-series, and AWS Graviton
+cibuildwheel --platform linux --archs i686      # 32-bit Linux
+cibuildwheel --platform linux --archs s390x     # emulating big-endian IBM Z
+cibuildwheel --platform macos                   # works only on MacOS
+cibuildwheel --platform windows                 # works only on Windows
+```
+
+You may need root previligies for multi-architecture builds:
+
+```sh
+sudo $(which cibuildwheel) --platform linux
+```
+
+On Windows and MacOS, to avoid frequent path resolution issues, you may want to use:
+
+```sh
+python -m cibuildwheel --platform windows
 ```
 
 ## JavaScript

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "usearch"
-version = "2.8.16"
+version = "2.9.0"
 authors = ["Ash Vardanian <1983160+ashvardanian@users.noreply.github.com>"]
 description = "Smaller & Faster Single-File Vector Search Engine from Unum"
 edition = "2021"

package/README.md

@@ -30,7 +30,8 @@ Spatial • Binary • Probabilistic • User-Defined Metrics
 <a href="https://unum-cloud.github.io/usearch/swift">Swift</a> •
 <a href="https://unum-cloud.github.io/usearch/csharp">C#</a> •
 <a href="https://unum-cloud.github.io/usearch/golang">GoLang</a> •
-<a href="https://unum-cloud.github.io/usearch/wolfram">Wolfram</a>
+<a href="https://unum-cloud.github.io/usearch/wolfram">Wolfram</a> •
+<a href="https://unum-cloud.github.io/usearch/sqlite">SQLite3</a>
 <br/>
 Linux • MacOS • Windows • iOS • WebAssembly
 </p>
@@ -47,10 +48,10 @@ Linux • MacOS • Windows • iOS • WebAssembly
 
 ---
 
-- ✅ [10x faster][faster-than-faiss] [HNSW][hnsw-algorithm] implementation than [FAISS][faiss].
-- ✅ Simple and extensible [single C++11 header][usearch-header] implementation.
+- ✅ __[10x faster][faster-than-faiss]__ [HNSW][hnsw-algorithm] implementation than [FAISS][faiss].
+- ✅ Simple and extensible [single C++11 header][usearch-header] __library__.
 - ✅ Compatible with a dozen programming languages out of the box.
-- ✅ [Trusted](#integrations) by some of the most loved Datalakes and Databases, like [ClickHouse][clickhouse-docs].
+- ✅ [Trusted](#integrations) by giants like Google and databases like [ClickHouse][clickhouse-docs].
 - ✅ [SIMD][simd]-optimized and [user-defined metrics](#user-defined-functions) with JIT compilation.
 - ✅ Hardware-agnostic `f16` & `i8` - [half-precision & quarter-precision support](#memory-efficiency-downcasting-and-quantization).
 - ✅ [View large indexes from disk](#serving-index-from-disk) without loading into RAM.
@@ -60,7 +61,7 @@ Linux • MacOS • Windows • iOS • WebAssembly
 - ✅ Space-efficient point-clouds with `uint40_t`, accommodating 4B+ size.
 - ✅ Compatible with OpenMP and custom "executors" for fine-grained control over CPU utilization.
 - ✅ Near-real-time [clustering and sub-clustering](#clustering) for Tens or Millions of clusters.
-- ✅ [Semantic Search](#usearch--ai--multi-modal-semantic-search) and [Joins](#joins).
+- ✅ [Semantic Search](#usearch--ai--multi-modal-semantic-search) and [Joins](#joins-one-to-one-one-to-many-and-many-to-many-mappings).
 
 [faiss]: https://github.com/facebookresearch/faiss
 [usearch-header]: https://github.com/unum-cloud/usearch/blob/main/include/usearch/index.hpp
@@ -433,7 +434,7 @@ doi = {10.5281/zenodo.7949416},
 author = {Vardanian, Ash},
 title = {{USearch by Unum Cloud}},
 url = {https://github.com/unum-cloud/usearch},
-version = {2.8.16},
+version = {2.9.0},
 year = {2023},
 month = oct,
 }

package/VERSION

@@ -1 +1 @@
-2.8.16
+2.9.0

package/conanfile.py

@@ -7,7 +7,7 @@ required_conan_version = ">=1.53.0"
 class USearchConan(ConanFile):
 
     name = "usearch"
-    version = '2.8.16'
+    version = '2.9.0'
     license = "Apache-2.0"
     description = "Smaller & Faster Single-File Vector Search Engine from Unum"
     homepage = "https://github.com/unum-cloud/usearch"

package/cpp/test.cpp

@@ -209,7 +209,14 @@ void test_cosine(std::size_t collection_size, std::size_t dimensions) {
             metric_punned_t metric(dimensions, metric_kind_t::cos_k, scalar_kind<scalar_at>());
             index_dense_config_t config(connectivity);
             config.multi = multi;
-            index_t index = index_t::make(metric, config);
+            index_t index;
+            {
+                index_t index_tmp1 = index_t::make(metric, config);
+                // move construction
+                index_t index_tmp2 = std::move(index_tmp1);
+                // move assignment
+                index = std::move(index_tmp2);
+            }
             test_cosine<true>(index, matrix);
         }
     }
@@ -313,4 +320,4 @@ int main(int, char**) {
             test_tanimoto<std::int64_t, std::uint32_t>(dimensions, connectivity);
 
     return 0;
-}
+}

package/include/usearch/index.hpp

@@ -10,8 +10,8 @@
 #define UNUM_USEARCH_HPP
 
 #define USEARCH_VERSION_MAJOR 2
-#define USEARCH_VERSION_MINOR 8
-#define USEARCH_VERSION_PATCH 16
+#define USEARCH_VERSION_MINOR 9
+#define USEARCH_VERSION_PATCH 0
 
 // Inferring C++ version
 // https://stackoverflow.com/a/61552074
@@ -1362,7 +1362,7 @@ class output_file_t {
     serialization_result_t write(void const* begin, std::size_t length) noexcept {
         serialization_result_t result;
         std::size_t written = std::fwrite(begin, length, 1, file_);
-        if (!written)
+        if (length && !written)
             return result.failed(std::strerror(errno));
         return result;
     }
@@ -1404,7 +1404,7 @@ class input_file_t {
     serialization_result_t read(void* begin, std::size_t length) noexcept {
         serialization_result_t result;
         std::size_t read = std::fread(begin, length, 1, file_);
-        if (!read)
+        if (length && !read)
             return result.failed(std::feof(file_) ? "End of file reached!" : std::strerror(errno));
         return result;
     }
@@ -1942,7 +1942,7 @@ class index_gt {
     std::size_t connectivity() const noexcept { return config_.connectivity; }
     std::size_t capacity() const noexcept { return nodes_capacity_; }
     std::size_t size() const noexcept { return nodes_count_; }
-    std::size_t max_level() const noexcept { return static_cast<std::size_t>(max_level_); }
+    std::size_t max_level() const noexcept { return nodes_count_ ? static_cast<std::size_t>(max_level_) : 0; }
     index_config_t const& config() const noexcept { return config_; }
     index_limits_t const& limits() const noexcept { return limits_; }
     bool is_immutable() const noexcept { return bool(viewed_file_); }
@@ -3362,7 +3362,7 @@ class index_gt {
         visits.clear();
 
         // Optional prefetching
-        if (!std::is_same<typename std::decay<prefetch_at>::type, dummy_prefetch_t>::value)
+        if (!is_dummy<prefetch_at>())
             prefetch(citerator_at(closest_slot), citerator_at(closest_slot + 1));
 
         distance_t closest_dist = context.measure(query, citerator_at(closest_slot), metric);
@@ -3374,7 +3374,7 @@ class index_gt {
                 neighbors_ref_t closest_neighbors = neighbors_non_base_(node_at_(closest_slot), level);
 
                 // Optional prefetching
-                if (!std::is_same<typename std::decay<prefetch_at>::type, dummy_prefetch_t>::value) {
+                if (!is_dummy<prefetch_at>()) {
                     candidates_range_t missing_candidates{*this, closest_neighbors, visits};
                     prefetch(missing_candidates.begin(), missing_candidates.end());
                 }
@@ -3416,7 +3416,7 @@ class index_gt {
             return false;
 
         // Optional prefetching
-        if (!std::is_same<typename std::decay<prefetch_at>::type, dummy_prefetch_t>::value)
+        if (!is_dummy<prefetch_at>())
             prefetch(citerator_at(start_slot), citerator_at(start_slot + 1));
 
         distance_t radius = context.measure(query, citerator_at(start_slot), metric);
@@ -3441,7 +3441,7 @@ class index_gt {
             neighbors_ref_t candidate_neighbors = neighbors_(candidate_ref, level);
 
             // Optional prefetching
-            if (!std::is_same<typename std::decay<prefetch_at>::type, dummy_prefetch_t>::value) {
+            if (!is_dummy<prefetch_at>()) {
                 candidates_range_t missing_candidates{*this, candidate_neighbors, visits};
                 prefetch(missing_candidates.begin(), missing_candidates.end());
             }
@@ -3490,7 +3490,7 @@ class index_gt {
             return false;
 
         // Optional prefetching
-        if (!std::is_same<typename std::decay<prefetch_at>::type, dummy_prefetch_t>::value)
+        if (!is_dummy<prefetch_at>())
             prefetch(citerator_at(start_slot), citerator_at(start_slot + 1));
 
         distance_t radius = context.measure(query, citerator_at(start_slot), metric);
@@ -3510,7 +3510,7 @@ class index_gt {
             neighbors_ref_t candidate_neighbors = neighbors_base_(node_at_(candidate.slot));
 
             // Optional prefetching
-            if (!std::is_same<typename std::decay<prefetch_at>::type, dummy_prefetch_t>::value) {
+            if (!is_dummy<prefetch_at>()) {
                 candidates_range_t missing_candidates{*this, candidate_neighbors, visits};
                 prefetch(missing_candidates.begin(), missing_candidates.end());
             }

package/include/usearch/index_plugins.hpp

@@ -1820,7 +1820,8 @@ class flat_hash_multi_set_gt {
         }
 
         // Reset populated slots count
-        std::memset(data_, 0, buckets_ * bytes_per_bucket());
+        if (data_)
+            std::memset(data_, 0, buckets_ * bytes_per_bucket());
         populated_slots_ = 0;
     }
 

package/javascript/usearch.js

@@ -303,7 +303,7 @@ class Index {
      */
     remove(keys) {
         let normalizedKeys = normalizeKeys(keys);
-        normalizedResults = this._compiledIndex.remove(normalizedKeys);
+        let normalizedResults = this._compiledIndex.remove(normalizedKeys);
         if (isOneKey(keys))
             return normalizedResults[0];
         else

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "usearch",
-    "version": "2.8.16",
+    "version": "2.9.0",
     "description": "Smaller & Faster Single-File Vector Search Engine from Unum",
     "author": "Ash Vardanian (https://ashvardanian.com/)",
     "license": "Apache 2.0",

package/pyproject.toml

@@ -16,7 +16,7 @@ filterwarnings = ["error"]
 test-requires = []
 test-command = ""
 build-verbosity = 0
-skip = ["*musllinux*", "*i686*", "pp*", "cp36-*", "cp312-*"]
+skip = ["*musllinux*", "*i686*", "pp*", "cp36-*"]
 
 [tool.cibuildwheel.linux]
 before-build = [
@@ -48,4 +48,4 @@ before-build = [
     "git submodule update --init --recursive",
 ]
 archs = ["x86", "AMD64"]
-skip = ["*win32*", "pp*", "cp36-*", "cp312-*"]
+skip = ["*win32*", "pp*", "cp36-*"]

package/setup.py

@@ -5,6 +5,7 @@ from setuptools import setup
 
 from pybind11.setup_helpers import Pybind11Extension
 
+sources = ["python/lib.cpp"]
 compile_args = []
 link_args = []
 macros_args = []
@@ -127,12 +128,14 @@ if is_windows:
             ]
         )
 
-print("macros_args", macros_args)
+if is_linux or is_macos:
+    sources.append("sqlite/lib.cpp")
+    link_args.append("-lsqlite3")
 
 ext_modules = [
     Pybind11Extension(
         "usearch.compiled",
-        ["python/lib.cpp"],
+        sources,
         extra_compile_args=compile_args,
         extra_link_args=link_args,
         define_macros=macros_args,
@@ -147,7 +150,11 @@ with open(os.path.join(this_directory, "README.md")) as f:
     long_description = f.read()
 
 # Depending on the macros, adjust the include directories
-include_dirs = ["include"]
+include_dirs = [
+    "include",
+    "python",
+    "stringzilla/include",
+]
 if use_simsimd:
     include_dirs.append("simsimd/include")
 if use_fp16lib:
@@ -190,6 +197,5 @@ setup(
     install_requires=[
         "numpy",
         "tqdm",
-        'ucall; python_version >= "3.9"',
     ],
 )

package/simsimd/.releaserc

@@ -74,9 +74,10 @@
             {
                 "assets": [
                     "VERSION",
-                    "conanfile.py",
                     "package.json",
-                    "Cargo.toml"
+                    "Cargo.toml",
+                    "CMakeLists.txt",
+                    "include/simsimd/simsimd.h"
                 ],
                 "message": "Build: Released ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
             }