usearch 0.22.2 → 1.0.0

package/python/usearch/io.py

@@ -1,11 +1,48 @@
+import os
 import struct
+import typing
 
 import numpy as np
 
 
+def numpy_scalar_size(dtype) -> int:
+    return {
+        np.float64: 8,
+        np.int64: 8,
+        np.uint64: 8,
+        np.float32: 4,
+        np.int32: 4,
+        np.uint32: 4,
+        np.float16: 2,
+        np.int16: 2,
+        np.uint16: 2,
+        np.int8: 1,
+        np.uint8: 1,
+    }[dtype]
+
+
+def guess_numpy_dtype_from_filename(filename) -> typing.Optional[type]:
+    if filename.endswith(".fbin"):
+        return np.float32
+    elif filename.endswith(".dbin"):
+        return np.float64
+    elif filename.endswith(".hbin"):
+        return np.float16
+    elif filename.endswith(".ibin"):
+        return np.int32
+    elif filename.endswith(".bbin"):
+        return np.uint8
+    else:
+        return None
+
+
 def load_matrix(
-    filename: str, start_row: int = 0, count_rows: int = None, view: bool = False
-) -> np.ndarray:
+    filename: str,
+    start_row: int = 0,
+    count_rows: int = None,
+    view: bool = False,
+    dtype: typing.Optional[type] = None,
+) -> typing.Optional[np.ndarray]:
     """Read *.ibin, *.bbib, *.hbin, *.fbin, *.dbin files with matrices.
 
     :param filename: path to the matrix file
@@ -16,25 +53,14 @@ def load_matrix(
     :return: parsed matrix
     :rtype: numpy.ndarray
     """
-    dtype = np.float32
-    scalar_size = 4
-    if filename.endswith(".fbin"):
-        dtype = np.float32
-        scalar_size = 4
-    elif filename.endswith(".dbin"):
-        dtype = np.float64
-        scalar_size = 8
-    elif filename.endswith(".hbin"):
-        dtype = np.float16
-        scalar_size = 2
-    elif filename.endswith(".ibin"):
-        dtype = np.int32
-        scalar_size = 4
-    elif filename.endswith(".bbin"):
-        dtype = np.uint8
-        scalar_size = 1
-    else:
-        raise Exception("Unknown file type")
+    if dtype is None:
+        dtype = guess_numpy_dtype_from_filename(filename)
+        if dtype is None:
+            raise Exception("Unknown file type")
+    scalar_size = numpy_scalar_size(dtype)
+
+    if not os.path.exists(filename):
+        return None
 
     with open(filename, "rb") as f:
         rows, cols = np.fromfile(f, count=2, dtype=np.int32)
@@ -43,11 +69,18 @@ def load_matrix(
 
         if view:
             return np.memmap(
-                f, dtype=dtype, mode="r", offset=8 + row_offset, shape=(rows, cols)
+                f,
+                dtype=dtype,
+                mode="r",
+                offset=8 + row_offset,
+                shape=(rows, cols),
             )
         else:
             return np.fromfile(
-                f, count=rows * cols, dtype=dtype, offset=row_offset
+                f,
+                count=rows * cols,
+                dtype=dtype,
+                offset=row_offset,
             ).reshape(rows, cols)
 
 
@@ -59,7 +92,6 @@ def save_matrix(vectors: np.ndarray, filename: str):
     :param filename: path to the matrix file
     :type filename: str
     """
-    dtype = np.float32
     if filename.endswith(".fbin"):
         dtype = np.float32
     elif filename.endswith(".dbin"):
@@ -71,7 +103,7 @@ def save_matrix(vectors: np.ndarray, filename: str):
     elif filename.endswith(".bbin"):
         dtype = np.uint8
     else:
-        raise Exception("Unknown file type")
+        dtype = vectors.dtype
 
     assert len(vectors.shape) == 2, "Input array must have 2 dimensions"
     with open(filename, "wb") as f:

package/python/usearch/numba.py

@@ -44,7 +44,7 @@ def jit(
     )
 
     numba_supported_types = (
-        ScalarKind.F8,
+        ScalarKind.I8,
         # Half-precision is still unsupported
         # https://github.com/numba/numba/issues/4402
         # ScalarKind.F16: np.float16,
@@ -55,7 +55,7 @@ def jit(
         return metric
 
     scalar_kind_to_accumulator_type = {
-        ScalarKind.F8: types.int32,
+        ScalarKind.I8: types.int32,
         ScalarKind.F16: types.float16,
         ScalarKind.F32: types.float32,
         ScalarKind.F64: types.float64,
@@ -98,7 +98,7 @@ def jit(
         return types.float32(ab_delta_sq)
 
     scalar_kind_to_signature = {
-        ScalarKind.F8: signature_i8args,
+        ScalarKind.I8: signature_i8args,
         ScalarKind.F16: signature_f16args,
         ScalarKind.F32: signature_f32args,
         ScalarKind.F64: signature_f64args,
@@ -110,7 +110,7 @@ def jit(
         MetricKind.L2sq: numba_l2sq,
     }
 
-    if dtype == ScalarKind.F8 and metric == MetricKind.IP:
+    if dtype == ScalarKind.I8 and metric == MetricKind.IP:
         metric = MetricKind.Cos
 
     pointer = cfunc(scalar_kind_to_signature[dtype])(metric_kind_to_function[metric])

package/python/usearch/server.py

@@ -7,13 +7,13 @@ import numpy as np
 from typing import List
 
 from ucall.rich_posix import Server
-from usearch.index import Index, Matches, Label
+from usearch.index import Index, Matches, Key
 
 
 def _ascii_to_vector(string: str) -> np.ndarray:
     """
     WARNING: A dirty performance hack!
-    Assuming the `f8` vectors in our implementations are just integers,
+    Assuming the `i8` vectors in our implementations are just integers,
     and generally contain scalars in the [0, 100] range, we can transmit
     them as JSON-embedded strings. The only symbols we must avoid are
     the double-quote '"' (code 22) and backslash '\' (code 60).
@@ -59,15 +59,15 @@ def serve(
         return index.connectivity()
 
     @server
-    def add_one(label: int, vector: np.ndarray):
-        print("adding", label, vector)
-        labels = np.array([label], dtype=Label)
+    def add_one(key: int, vector: np.ndarray):
+        print("adding", key, vector)
+        keys = np.array([key], dtype=Key)
         vectors = vector.flatten().reshape(vector.shape[0], 1)
-        index.add(labels, vectors)
+        index.add(keys, vectors)
 
     @server
-    def add_many(labels: np.ndarray, vectors: np.ndarray):
-        index.add(labels, vectors, threads=threads)
+    def add_many(keys: np.ndarray, vectors: np.ndarray):
+        index.add(keys, vectors, threads=threads)
 
     @server
     def search_one(vector: np.ndarray, count: int) -> List[dict]:
@@ -82,8 +82,8 @@ def serve(
         return results.to_list()
 
     @server
-    def add_ascii(label: int, string: str):
-        return add_one(label, _ascii_to_vector(string))
+    def add_ascii(key: int, string: str):
+        return add_one(key, _ascii_to_vector(string))
 
     @server
     def search_ascii(string: str, count: int):

package/rust/lib.cpp

@@ -7,46 +7,45 @@ using namespace unum;
 using index_t = typename Index::index_t;
 using add_result_t = typename index_t::add_result_t;
 using search_result_t = typename index_t::search_result_t;
-using serialization_result_t = typename index_t::serialization_result_t;
 
 Index::Index(std::unique_ptr<index_t> index) : index_(std::move(index)) {}
 
-void Index::add_in_thread(label_t label, rust::Slice<float const> vector, size_t thread) const {
-    add_config_t config;
+void Index::add_in_thread(key_t key, rust::Slice<float const> vector, size_t thread) const {
+    index_update_config_t config;
     config.thread = thread;
-    index_->add(label, vector.data(), config).error.raise();
+    config.expansion = index_->expansion_add();
+    index_->add(key, vector.data(), config).error.raise();
 }
 
 Matches Index::search_in_thread(rust::Slice<float const> vector, size_t count, size_t thread) const {
     Matches matches;
-    matches.labels.reserve(count);
+    matches.keys.reserve(count);
     matches.distances.reserve(count);
     for (size_t i = 0; i != count; ++i)
-        matches.labels.push_back(0), matches.distances.push_back(0);
-    search_config_t config;
+        matches.keys.push_back(0), matches.distances.push_back(0);
+    index_search_config_t config;
     config.thread = thread;
+    config.expansion = index_->expansion_search();
     search_result_t result = index_->search(vector.data(), count, config);
     result.error.raise();
-    matches.count = result.dump_to(matches.labels.data(), matches.distances.data());
-    matches.labels.truncate(matches.count);
+    matches.count = result.dump_to(matches.keys.data(), matches.distances.data());
+    matches.keys.truncate(matches.count);
     matches.distances.truncate(matches.count);
     return matches;
 }
 
-void Index::add(label_t label, rust::Slice<float const> vector) const {
-    index_->add(label, vector.data()).error.raise();
-}
+void Index::add(key_t key, rust::Slice<float const> vector) const { index_->add(key, vector.data()).error.raise(); }
 
 Matches Index::search(rust::Slice<float const> vector, size_t count) const {
     Matches matches;
-    matches.labels.reserve(count);
+    matches.keys.reserve(count);
     matches.distances.reserve(count);
     for (size_t i = 0; i != count; ++i)
-        matches.labels.push_back(0), matches.distances.push_back(0);
+        matches.keys.push_back(0), matches.distances.push_back(0);
     search_result_t result = index_->search(vector.data(), count);
     result.error.raise();
-    matches.count = result.dump_to(matches.labels.data(), matches.distances.data());
-    matches.labels.truncate(matches.count);
+    matches.count = result.dump_to(matches.keys.data(), matches.distances.data());
+    matches.keys.truncate(matches.count);
     matches.distances.truncate(matches.count);
     return matches;
 }
@@ -62,7 +61,7 @@ void Index::save(rust::Str path) const { index_->save(std::string(path).c_str())
 void Index::load(rust::Str path) const { index_->load(std::string(path).c_str()); }
 void Index::view(rust::Str path) const { index_->view(std::string(path).c_str()); }
 
-scalar_kind_t accuracy(rust::Str quant) { return scalar_kind_from_name(quant.data(), quant.size()); }
+scalar_kind_t quantization(rust::Str quant) { return scalar_kind_from_name(quant.data(), quant.size()); }
 
 std::unique_ptr<Index> wrap(index_t&& index) {
     std::unique_ptr<index_t> punned_ptr;
@@ -72,12 +71,6 @@ std::unique_ptr<Index> wrap(index_t&& index) {
     return result;
 }
 
-index_config_t config(size_t connectivity) {
-    index_config_t result;
-    result.connectivity = connectivity ? connectivity : default_connectivity();
-    return result;
-}
-
 metric_kind_t rust_to_cpp_metric(MetricKind value) {
     switch (value) {
     case MetricKind::IP: return metric_kind_t::ip_k;
@@ -94,7 +87,7 @@ metric_kind_t rust_to_cpp_metric(MetricKind value) {
 
 scalar_kind_t rust_to_cpp_scalar(ScalarKind value) {
     switch (value) {
-    case ScalarKind::F8: return scalar_kind_t::f8_k;
+    case ScalarKind::I8: return scalar_kind_t::i8_k;
     case ScalarKind::F16: return scalar_kind_t::f16_k;
     case ScalarKind::F32: return scalar_kind_t::f32_k;
     case ScalarKind::F64: return scalar_kind_t::f64_k;
@@ -104,7 +97,9 @@ scalar_kind_t rust_to_cpp_scalar(ScalarKind value) {
 }
 
 std::unique_ptr<Index> new_index(IndexOptions const& options) {
-    return wrap(index_t::make(options.dimensions, rust_to_cpp_metric(options.metric), config(options.connectivity),
-                              rust_to_cpp_scalar(options.quantization), options.expansion_add,
-                              options.expansion_search));
+    metric_kind_t metric_kind = rust_to_cpp_metric(options.metric);
+    scalar_kind_t scalar_kind = rust_to_cpp_scalar(options.quantization);
+    metric_punned_t metric(options.dimensions, metric_kind, scalar_kind);
+    index_dense_config_t config(options.connectivity, options.expansion_add, options.expansion_search);
+    return wrap(index_t::make(metric, config));
 }

package/rust/lib.hpp

@@ -3,27 +3,26 @@
 
 #include <memory> // `std::shared_ptr`
 
-#include <usearch/index_punned_dense.hpp>
+#include <usearch/index_dense.hpp>
 
 struct Matches;
 struct IndexOptions;
 
 class Index {
   public:
-    using metric_t = unum::usearch::index_punned_dense_metric_t;
-    using distance_t = unum::usearch::punned_distance_t;
-    using index_t = unum::usearch::punned_small_t;
-    using add_result_t = typename index_t::add_result_t;
-    using search_result_t = typename index_t::search_result_t;
-    using label_t = typename index_t::label_t;
-    using id_t = typename index_t::id_t;
+    using metric_t = unum::usearch::metric_punned_t;
+    using distance_t = unum::usearch::distance_punned_t;
+    using index_dense_t = unum::usearch::index_dense_t;
+    using add_result_t = typename index_dense_t::add_result_t;
+    using search_result_t = typename index_dense_t::search_result_t;
+    using key_t = typename index_dense_t::key_t;
 
-    Index(std::unique_ptr<index_t> index);
+    Index(std::unique_ptr<index_dense_t> index);
 
     void reserve(size_t) const;
 
-    void add(label_t label, rust::Slice<float const> vector) const;
-    void add_in_thread(label_t label, rust::Slice<float const> vector, size_t thread) const;
+    void add(key_t key, rust::Slice<float const> vector) const;
+    void add_in_thread(key_t key, rust::Slice<float const> vector, size_t thread) const;
 
     Matches search(rust::Slice<float const> vector, size_t count) const;
     Matches search_in_thread(rust::Slice<float const> vector, size_t count, size_t thread) const;
@@ -38,7 +37,7 @@ class Index {
     void view(rust::Str path) const;
 
   private:
-    std::unique_ptr<index_t> index_;
+    std::unique_ptr<index_dense_t> index_;
 };
 
 std::unique_ptr<Index> new_index(IndexOptions const& options);

package/rust/lib.rs

@@ -4,7 +4,7 @@ pub mod ffi {
     // Shared structs with fields visible to both languages.
     struct Matches {
         count: usize,
-        labels: Vec<u64>,
+        keys: Vec<u64>,
         distances: Vec<f32>,
     }
 
@@ -23,7 +23,7 @@ pub mod ffi {
         F64,
         F32,
         F16,
-        F8,
+        I8,
         B1,
     }
 
@@ -51,7 +51,7 @@ pub mod ffi {
         pub fn size(self: &Index) -> usize;
         pub fn capacity(self: &Index) -> usize;
 
-        pub fn add(self: &Index, label: u64, vector: &[f32]) -> Result<()>;
+        pub fn add(self: &Index, key: u64, vector: &[f32]) -> Result<()>;
         pub fn search(self: &Index, query: &[f32], count: usize) -> Result<Matches>;
 
         pub fn save(self: &Index, path: &str) -> Result<()>;

package/setup.py

@@ -14,7 +14,8 @@ macros_args = [
 
 if sys.platform == "linux":
     compile_args.append("-std=c++11")
-    compile_args.append("-O3")
+    compile_args.append("-O3")  # Maximize performance
+    compile_args.append("-g")  # Simplify debugging
     compile_args.append("-Wno-unknown-pragmas")
 
     macros_args.append(("USEARCH_USE_OPENMP", "1"))
@@ -26,7 +27,8 @@ if sys.platform == "darwin":
     # https://github.com/unum-cloud/usearch/actions/runs/4975434891/jobs/8902603392
     compile_args.append("-mmacosx-version-min=10.15")
     compile_args.append("-std=c++11")
-    compile_args.append("-O3")
+    compile_args.append("-O3")  # Maximize performance
+    compile_args.append("-g")  # Simplify debugging
     compile_args.append("-Wno-unknown-pragmas")
 
     # Linking OpenMP requires additional preparion in CIBuildWheel
@@ -63,6 +65,7 @@ setup(
     packages=["usearch"],
     package_dir={"usearch": "python/usearch"},
     description="Smaller & Faster Single-File Vector Search Engine from Unum",
+    author="Ash Vardanian",
     long_description=long_description,
     long_description_content_type="text/markdown",
     license="Apache-2.0",

package/simsimd/.github/workflows/prerelease.yml

@@ -0,0 +1,73 @@
+name: Pre-Release
+
+on:
+  push:
+    branches: ["main-dev"]
+  pull_request:
+    branches: ["main-dev"]
+
+env:
+  BUILD_TYPE: Release
+  GH_TOKEN: ${{ secrets.SEMANTIC_RELEASE_TOKEN }}
+  PYTHONUTF8: 1
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+
+jobs:
+
+  test_python_311:
+    name: Test Python
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-20.04, macOS-11, windows-2022]
+        python-version: ["3.11"]
+
+    steps:
+      - uses: actions/checkout@v3
+      - run: git submodule update --init --recursive
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --no-cache-dir --upgrade pip
+          pip install --no-cache-dir pytest
+      - name: Build locally
+        run: python -m pip install .
+      - name: Test with PyTest
+        run: pytest python/test.py
+
+
+  test_python_37:
+    name: Test Python 3.7
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-20.04]
+        python-version: ["3.7"]
+
+    steps:
+      - uses: actions/checkout@v3
+      - run: git submodule update --init --recursive
+      
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --no-cache-dir --upgrade pip
+          pip install --no-cache-dir pytest
+
+      - name: Build locally
+        run: python -m pip install .
+
+      - name: Test with PyTest
+        run: pytest python/test.py
+
+

package/simsimd/.github/workflows/release.yml

@@ -0,0 +1,110 @@
+name: Release
+
+on:
+  push:
+    branches: ["main"]
+
+env:
+  BUILD_TYPE: Release
+  GH_TOKEN: ${{ secrets.SEMANTIC_RELEASE_TOKEN }}
+  PYTHONUTF8: 1
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+
+  versioning:
+    name: Semantic Release
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        persist-credentials: false
+    - uses: actions/setup-node@v3
+    - run: npm install --save-dev @semantic-release/exec @semantic-release/git conventional-changelog-eslint semantic-release && npx semantic-release
+
+
+  rebase:
+    name: Rebase Development Branch
+    needs: versioning
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the latest code
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Perform rebase
+        run: |
+          git checkout main-dev
+          git rebase main
+          
+      - name: Push changes
+        uses: CasperWA/push-protected@v2
+        with:
+          token: ${{ secrets.SEMANTIC_REBASE_TOKEN }}
+          branch: main-dev
+          unprotect_reviews: True
+          force: True
+
+  build_wheels:
+    name: Build Wheels for ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    needs: versioning
+    strategy:
+      matrix:
+        os: [ubuntu-20.04, macOS-11, windows-2022]
+
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: 'main'      
+      - uses: actions/setup-python@v3
+      
+      - name: Setup Docker
+        if: matrix.os != 'windows-2022'
+        uses: crazy-max/ghaction-setup-docker@v1.0.0
+        with:
+          version: 23.0.1
+
+      - name: Setup QEMU
+        if: matrix.os != 'windows-2022'
+        uses: docker/setup-qemu-action@v2.1.0
+
+      - name: Install CIBuildWheel
+        run: python -m pip install --no-cache-dir cibuildwheel
+
+      - name: Build wheels
+        run: python -m cibuildwheel
+
+      - uses: actions/upload-artifact@v3
+        with:
+          path: ./wheelhouse/*.whl
+  
+  
+  publish_python:
+    name: Publish Python
+    needs: build_wheels
+    runs-on: ubuntu-20.04
+    environment:
+      name: pypi
+      url: https://pypi.org/p/stringzilla
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v3.0.2
+        with:
+          path: ./dist/
+
+      - name: Publish to PyPi
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: ./dist/artifact
+          verbose: true
+          print-hash: true

package/simsimd/.github/workflows/update_version.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+echo $1 > VERSION

package/simsimd/.releaserc

@@ -0,0 +1,77 @@
+{
+    "branches": [
+        "main"
+    ],
+    "debug": true,
+    "ci": true,
+    "dryRun": false,
+    "plugins": [
+        [
+            "@semantic-release/commit-analyzer",
+            {
+                "preset": "eslint",
+                "releaseRules": [
+                    {
+                        "tag": "Add",
+                        "release": "minor"
+                    },
+                    {
+                        "tag": "Improve",
+                        "release": "patch"
+                    },
+                    {
+                        "tag": "Make",
+                        "release": "patch"
+                    },
+                    {
+                        "tag": "Refactor",
+                        "release": false
+                    }
+                ]
+            }
+        ],
+        [
+            "@semantic-release/release-notes-generator",
+            {
+                "preset": "eslint",
+                "releaseRules": [
+                    {
+                        "tag": "Add",
+                        "release": "minor"
+                    },
+                    {
+                        "tag": "Improve",
+                        "release": "patch"
+                    },
+                    {
+                        "tag": "Make",
+                        "release": "patch"
+                    },
+                    {
+                        "tag": "Refactor",
+                        "release": false
+                    }
+                ]
+            }
+        ],
+        "@semantic-release/github",
+        [
+            "@semantic-release/exec",
+            {
+                "prepareCmd": "bash .github/workflows/update_version.sh '${nextRelease.version}'"
+            }
+        ],
+        [
+            "@semantic-release/git",
+            {
+                "assets": [
+                    "VERSION",
+                    "conanfile.py",
+                    "package.json",
+                    "Cargo.toml",
+                ],
+                "message": "Build: Released ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+            }
+        ]
+    ]
+}