usearch 0.19.0 → 0.19.1

package/Cargo.toml

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

package/README.md

@@ -387,6 +387,10 @@ index = Index(ndim=ndim, metric=CompiledMetric(
 ))
 ```
 
+```sh
+conda install -c conda-forge cppyy
+```
+
 ##### [PeachPy][peachpy]
 
 We have covered JIT-ing Python with Numba and C++ with Cppyy and Cling.
@@ -641,6 +645,7 @@ https://github.com/unum-cloud/usearch
 let index = Index.l2sq(dimensions: 3, connectivity: 8)
 let vectorA: [Float32] = [0.3, 0.5, 1.2]
 let vectorB: [Float32] = [0.4, 0.2, 1.2]
+index.reserve(2)
 index.add(label: 42, vector: vectorA[...])
 index.add(label: 43, vector: vectorB[...])
 
@@ -717,22 +722,16 @@ server.run()
 
 We have pre-processed some commonly used datasets, cleaning the images, producing the vectors, and pre-building the index.
 
-| Dataset                             | Size | Images |          Preprocessed |
-| :---------------------------------- | ---: | -----: | --------------------: |
-| [Unsplash 25K][unsplash-25k-origin] |    - |   25 K | [HF][unsplash-25k-hf] |
-| [Unsplash 2M][unsplash-2m-origin]   |    - |    2 M |  [HF][unsplash-2m-hf] |
-| [LAION 400M][laion-400m-origin]     |    - |  400 M |   [HF][laion-400m-hf] |
-| [LAION 5B][laion-5b-origin]         |    - |    5 B |     [HF][laion-5b-hf] |
+| Dataset                              | Size | Images |          Preprocessed |
+| :----------------------------------- | ---: | -----: | --------------------: |
+| [Unsplash 25K][unsplash-25k-origin]  |    - |   25 K | [HF][unsplash-25k-hf] |
+| [Createve Captions 3M][cc-3m-origin] |    - |    3 M |        [HF][cc-3m-hf] |
 
 
 [unsplash-25k-origin]: https://unum.cloud
-[unsplash-2m-origin]: https://unum.cloud
-[laion-400m-origin]: https://unum.cloud
-[laion-5b-origin]: https://unum.cloud
+[cc-3m-origin]: https://unum.cloud
 [unsplash-25k-hf]: https://unum.cloud
-[unsplash-2m-hf]: https://unum.cloud
-[laion-400m-hf]: https://unum.cloud
-[laion-5b-hf]: https://unum.cloud
+[cc-3m-hf]: https://unum.cloud
 
 ### USearch + RDKit = Molecular Search
 
@@ -763,31 +762,9 @@ index.add(labels, fingerprints)
 matches = index.search(fingerprints, 10)
 ```
 
-RDKit [provides][rdkit-fingerprints] following fingerprinting techniques:
-
-- Atom-Pair, 
-- Topological Torsion, 
-- Morgan,
-- Layered Fingerprints.
-
-We have preprocessed some of the most commonly used datasets, and made it available for free on the HuggingFace portal, together with visual interface.
-
-| Dataset                   |     Size |   Molecules |     Preprocessed |
-| :------------------------ | -------: | ----------: | ---------------: |
-| [PubChem][pubchem-origin] |     8 GB | 115'034'339 | [HF][pubchem-hf] |
-| [GDB 13][gdb13-origin]    |   2.3 GB | 977'468'301 |   [HF][gdb13-hf] |
-| [REAL][real-origin]       | > 100 GB |         6 B |    [HF][real-hf] |
-
 [smiles]: https://en.wikipedia.org/wiki/Simplified_molecular-input_line-entry_system
 [rdkit-fingerprints]: https://www.rdkit.org/docs/RDKit_Book.html#additional-information-about-the-fingerprints
 
-[gdb13-origin]: https://zenodo.org/record/5172018/files/gdb13.tgz?download=1
-[pubchem-origin]: ftp://ftp.ncbi.nlm.nih.gov/pubchem/Compound/Extras/CID-SMILES.gz
-[real-origin]: https://enamine.net/compound-collections/real-compounds/real-database
-[pubchem-hf]: https://unum.cloud
-[gdb13-hf]: https://unum.cloud
-[real-hf]: https://unum.cloud
-
 ## TODO
 
 - JavaScript: Allow calling from "worker threads".

package/c/lib.cpp

@@ -1,4 +1,6 @@
-#include "../src/index_punned_dense.hpp"
+#include <cassert>
+
+#include <usearch/index_punned_dense.hpp>
 
 extern "C" {
 #include "usearch.h"
@@ -12,10 +14,11 @@ using distance_t = usearch_distance_t;
 using index_t = index_punned_dense_gt<label_t>;
 using add_result_t = index_t::add_result_t;
 using search_result_t = index_t::search_result_t;
-using seerialization_result_t = index_t::seerialization_result_t;
+using serialization_result_t = index_t::serialization_result_t;
 
 using span_t = span_gt<float>;
 
+// helper functions that are not part of the C ABI
 metric_kind_t to_native_metric(usearch_metric_kind_t kind) {
     switch (kind) {
     case usearch_metric_ip_k: return metric_kind_t::ip_k;
@@ -37,30 +40,76 @@ scalar_kind_t to_native_scalar(usearch_scalar_kind_t kind) {
     case usearch_scalar_f64_k: return scalar_kind_t::f64_k;
     case usearch_scalar_f16_k: return scalar_kind_t::f16_k;
     case usearch_scalar_f8_k: return scalar_kind_t::f8_k;
-    case usearch_scalar_b1_k: return scalar_kind_t::b1_k;
+    case usearch_scalar_b1_k: return scalar_kind_t::b1x8_k;
     default: return scalar_kind_t::unknown_k;
     }
 }
 
-void usearch_init(usearch_init_options_t* options, usearch_index_t* index, usearch_error_t* error) {
+add_result_t add_(index_t* index, usearch_label_t label, void const* vector, scalar_kind_t kind) {
+    switch (kind) {
+    case scalar_kind_t::f32_k: return index->add(label, (f32_t const*)vector);
+    case scalar_kind_t::f64_k: return index->add(label, (f64_t const*)vector);
+    case scalar_kind_t::f16_k: return index->add(label, (f16_t const*)vector);
+    case scalar_kind_t::f8_k: return index->add(label, (f8_bits_t const*)vector);
+    case scalar_kind_t::b1x8_k: return index->add(label, (b1x8_t const*)vector);
+    default: return add_result_t{}.failed("Unknown scalar kind!");
+    }
+}
+
+bool get_(index_t* index, label_t label, void* vector, scalar_kind_t kind) {
+    switch (kind) {
+    case scalar_kind_t::f32_k: return index->get(label, (f32_t*)vector);
+    case scalar_kind_t::f64_k: return index->get(label, (f64_t*)vector);
+    case scalar_kind_t::f16_k: return index->get(label, (f16_t*)vector);
+    case scalar_kind_t::f8_k: return index->get(label, (f8_bits_t*)vector);
+    case scalar_kind_t::b1x8_k: return index->get(label, (b1x8_t*)vector);
+    default: return index->empty_search_result().failed("Unknown scalar kind!");
+    }
+}
+
+search_result_t search_(index_t* index, void const* vector, scalar_kind_t kind, size_t n) {
+    switch (kind) {
+    case scalar_kind_t::f32_k: return index->search((f32_t const*)vector, n);
+    case scalar_kind_t::f64_k: return index->search((f64_t const*)vector, n);
+    case scalar_kind_t::f16_k: return index->search((f16_t const*)vector, n);
+    case scalar_kind_t::f8_k: return index->search((f8_bits_t const*)vector, n);
+    case scalar_kind_t::b1x8_k: return index->search((b1x8_t const*)vector, n);
+    default: return index->empty_search_result().failed("Unknown scalar kind!");
+    }
+}
+
+index_punned_dense_metric_t udf(metric_kind_t kind, usearch_metric_t raw_ptr) {
+    index_punned_dense_metric_t result;
+    result.kind_ = kind;
+    result.func_ = [raw_ptr](punned_vector_view_t a, punned_vector_view_t b) -> distance_t {
+        return raw_ptr((void const*)a.data(), (void const*)b.data());
+    };
+    return result;
+}
+
+extern "C" {
 
-    config_t config;
-    config.expansion_add = static_cast<std::size_t>(expansion_add);
-    config.expansion_search = static_cast<std::size_t>(expansion_search);
-    config.connectivity = static_cast<std::size_t>(connectivity);
-    config.max_elements = static_cast<std::size_t>(capacity);
-    config.max_threads_add = std::thread::hardware_concurrency();
-    config.max_threads_search = std::thread::hardware_concurrency();
+usearch_index_t usearch_init(usearch_init_options_t* options, usearch_error_t* error) {
 
-    scalar_kind_t accuracy = scalar_kind_from_name(accuracy_str, accuracy_len);
-    metric_kind_t metric_kind = metric_from_name(metric_str, metric_len);
-    index_t index = index_t::make(metric_kind, static_cast<std::size_t>(dimensions), accuracy, config);
+    assert(options && error);
+
+    index_config_t config;
+    config.connectivity = options->connectivity;
+    index_t index =        //
+        options->metric ?  //
+            index_t::make( //
+                options->dimensions, udf(to_native_metric(options->metric_kind), options->metric), config,
+                to_native_scalar(options->quantization), options->expansion_add, options->expansion_search)
+                        :  //
+            index_t::make( //
+                options->dimensions, to_native_metric(options->metric_kind), config,
+                to_native_scalar(options->quantization), options->expansion_add, options->expansion_search);
 
     index_t* result_ptr = new index_t(std::move(index));
     return result_ptr;
 }
 
-void usearch_free(index_t* index) { delete index; }
+void usearch_free(usearch_index_t index, usearch_error_t*) { delete reinterpret_cast<index_t*>(index); }
 
 void usearch_save(usearch_index_t index, char const* path, usearch_error_t* error) {
     serialization_result_t result = reinterpret_cast<index_t*>(index)->save(path);
@@ -101,17 +150,6 @@ void usearch_reserve(usearch_index_t index, size_t capacity, usearch_error_t*) {
     reinterpret_cast<index_t*>(index)->reserve(capacity);
 }
 
-add_result_t add_(index_t* index, usearch_label_t label, void const* vector, scalar_kind_t kind) {
-    switch (kind) {
-    case scalar_kind_t::f32_k: return index->add(label, (f32_t const*)vector);
-    case scalar_kind_t::f64_k: return index->add(label, (f64_t const*)vector);
-    case scalar_kind_t::f16_k: return index->add(label, (f16_t const*)vector);
-    case scalar_kind_t::f8_k: return index->add(label, (f8_bits_t const*)vector);
-    case scalar_kind_t::b1x8_k: return index->add(label, (b1x8_t const*)vector);
-    default: return add_result_t{}.failed("Unknown scalar kind!");
-    }
-}
-
 void usearch_add(                                                                                 //
     usearch_index_t index, usearch_label_t label, void const* vector, usearch_scalar_kind_t kind, //
     usearch_error_t* error) {
@@ -121,18 +159,7 @@ void usearch_add(
 }
 
 bool usearch_contains(usearch_index_t index, usearch_label_t label, usearch_error_t*) {
-    reinterpret_cast<index_t*>(index)->contains(label);
-}
-
-search_result_t search_(index_t* index, void const* vector, scalar_kind_t kind, size_t n) {
-    switch (kind) {
-    case scalar_kind_t::f32_k: return index->search((f32_t const*)vector, n);
-    case scalar_kind_t::f64_k: return index->search((f64_t const*)vector, n);
-    case scalar_kind_t::f16_k: return index->search((f16_t const*)vector, n);
-    case scalar_kind_t::f8_k: return index->search((f8_bits_t const*)vector, n);
-    case scalar_kind_t::b1x8_k: return index->search((b1x8_t const*)vector, n);
-    default: return search_result_t{}.failed("Unknown scalar kind!");
-    }
+    return reinterpret_cast<index_t*>(index)->contains(label);
 }
 
 size_t usearch_search(                                                                           //
@@ -147,21 +174,14 @@ size_t usearch_search(
     return result.dump_to(found_labels, found_distances);
 }
 
-bool get_(index_t* index, void const* vector, scalar_kind_t kind) {
-    switch (kind) {
-    case scalar_kind_t::f32_k: return index->get((f32_t const*)vector, n);
-    case scalar_kind_t::f64_k: return index->get((f64_t const*)vector, n);
-    case scalar_kind_t::f16_k: return index->get((f16_t const*)vector, n);
-    case scalar_kind_t::f8_k: return index->get((f8_bits_t const*)vector, n);
-    case scalar_kind_t::b1x8_k: return index->get((b1x8_t const*)vector, n);
-    default: return search_result_t{}.failed("Unknown scalar kind!");
-    }
-}
-
 bool usearch_get(                                 //
     usearch_index_t index, usearch_label_t label, //
     void* vector, usearch_scalar_kind_t kind, usearch_error_t*) {
-    return search_(reinterpret_cast<index_t*>(index), vector, to_native_scalar(kind));
+    return get_(reinterpret_cast<index_t*>(index), label, vector, to_native_scalar(kind));
 }
 
-void usearch_remove(usearch_index_t, usearch_label_t, usearch_error_t*) {}
+void usearch_remove(usearch_index_t, usearch_label_t, usearch_error_t* error) {
+    if (error != nullptr)
+        *error = "USearch does not support removal of elements yet.";
+}
+}

package/c/test.c

@@ -0,0 +1,182 @@
+#include <assert.h>
+#include <errno.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/stat.h>
+#include <time.h>
+
+#include "usearch.h"
+
+float* read_fvecs_file(const char* filename, size_t* num_vectors, size_t* vector_dim) {
+    struct stat st;
+    FILE* file;
+    size_t cnt;
+    float skip;
+
+    ;
+    if (stat(filename, &st) == -1) {
+        printf("Failed to read file: %s err: %d: %s\n", filename, errno, strerror(errno));
+        return NULL;
+    }
+
+    file = fopen(filename, "rb");
+    if (file == NULL) {
+        printf("Failed to open file: %s\n", filename);
+        return NULL;
+    }
+
+    // Read the number of vectors and vector dimension from the file
+    cnt = fread(vector_dim, sizeof(int), 1, file);
+    assert(cnt == 1);
+    if (st.st_size % ((*vector_dim + 1) * sizeof(float)) != 0) {
+        printf("File does not contain a whole number of vectors.\n Vector dim: %ld, file size: %ld\n", *vector_dim,
+               st.st_size);
+        fclose(file);
+        return NULL;
+    }
+
+    *num_vectors = st.st_size / ((*vector_dim + 1) * sizeof(float));
+
+    // Allocate memory for the array
+    float* data = (float*)malloc(*num_vectors * *vector_dim * sizeof(float));
+    if (data == NULL) {
+        printf("Memory allocation failed.\n");
+        fclose(file);
+        return NULL;
+    }
+
+    // Read the data from the file into the array
+    for (size_t i = 0; i < *num_vectors; i++) {
+        cnt = fread(data + i * *vector_dim, sizeof(float), *vector_dim, file);
+        assert(cnt == *vector_dim);
+        if (i == *num_vectors - 1) {
+            break;
+        }
+        cnt = fread(&skip, sizeof(float), 1, file);
+        assert(cnt == 1);
+    }
+
+    fclose(file);
+    return data;
+}
+
+// log every this many iterations in test loops
+const int LOG_GRANULARITY = 10000;
+
+void test_index(float* data, size_t num_vectors, size_t vector_dim) {
+    usearch_init_options_t opts;
+    usearch_index_t idx;
+    usearch_error_t error = NULL;
+    clock_t start;
+    opts.connectivity = 2; // 32 in faiss
+    opts.dimensions = vector_dim;
+    opts.expansion_add = 40;    // 40 in faiss
+    opts.expansion_search = 16; // 10 in faiss
+    opts.metric_kind = usearch_metric_ip_k;
+    opts.metric = NULL;
+    opts.quantization = usearch_scalar_f32_k;
+
+    // results arrays
+    int k = 10;
+    num_vectors /= 10;
+    usearch_label_t* labels = (usearch_label_t*)calloc(k, sizeof(usearch_label_t));
+    float* distances = (float*)calloc(k, sizeof(float));
+
+    fprintf(stderr, "read %ld vectors of dimension %ld\n", num_vectors, vector_dim);
+    fprintf(stderr, "initializing usearch...\n");
+    idx = usearch_init(&opts, &error);
+    if (error != NULL) {
+        fprintf(stderr, "usearch error: %s\n", error);
+        assert(false);
+    }
+
+    fprintf(stderr, "reserving capacity...\n");
+    usearch_reserve(idx, num_vectors, &error);
+    assert(!error);
+
+    fprintf(stderr, "adding vectors...\n");
+    for (size_t i = 0; i < num_vectors; i++) {
+        if (i % LOG_GRANULARITY == 0) {
+            fprintf(stderr, "added %ld vectors...\n", i);
+        }
+        usearch_label_t label = i;
+        usearch_add(idx, label, data + i * vector_dim, usearch_scalar_f32_k, &error);
+        assert(!error);
+    }
+
+    fprintf(stderr, "checking containment of vectors...\n");
+    for (size_t i = 0; i < num_vectors; i++) {
+        if (i % LOG_GRANULARITY == 0) {
+            fprintf(stderr, "checked %ld vectors...\n", i);
+        }
+        usearch_label_t label = i;
+        assert(usearch_contains(idx, label, &error));
+        assert(!error);
+    }
+
+    assert(!usearch_contains(idx, -1, &error));
+    assert(!error);
+
+    fprintf(stderr, "searching vectors...\n");
+    for (size_t i = 0; i < num_vectors; i++) {
+        if (i % LOG_GRANULARITY == 0) {
+            fprintf(stderr, "searched %ld vectors...\n", i);
+        }
+        const void *query_vector = data + i * vector_dim;
+        usearch_search(idx, query_vector, usearch_scalar_f32_k, k, labels, distances, &error);
+        assert(!error);
+    }
+
+    fprintf(stderr, "saving the index...\n");
+    start = clock();
+    usearch_save(idx, "usearch_index.bin", &error);
+    assert(!error);
+    fprintf(stderr, "saving took %.2f ms\n", ((double)(clock() - start)) / CLOCKS_PER_SEC * 1000);
+
+    fprintf(stderr, "destroying the index...\n");
+    start = clock();
+    usearch_free(idx, &error);
+    assert(!error);
+    fprintf(stderr, "destroying the index took %.2f ms\n", ((double)(clock() - start)) / CLOCKS_PER_SEC * 1000);
+
+    fprintf(stderr, "loading the index...\n");
+    start = clock();
+    idx = usearch_init(&opts, &error);
+    assert(!error);
+    assert(usearch_size(idx, &error) == 0);
+    assert(!error);
+    usearch_load(idx, "usearch_index.bin", &error);
+    assert(!error);
+    fprintf(stderr, "loading the index took %.2f ms\n", ((double)(clock() - start)) / CLOCKS_PER_SEC * 1000);
+    assert(usearch_size(idx, &error) == num_vectors);
+    assert(!error);
+    usearch_free(idx, &error);
+
+    fprintf(stderr, "viewing the index...\n");
+    start = clock();
+    idx = usearch_init(&opts, &error);
+    assert(!error);
+    assert(usearch_size(idx, &error) == 0);
+    assert(!error);
+    usearch_view(idx, "usearch_index.bin", &error);
+    assert(!error);
+    fprintf(stderr, "viewing the index took %.2f ms\n", ((double)(clock() - start)) / CLOCKS_PER_SEC * 1000);
+    assert(usearch_size(idx, &error) == num_vectors);
+    assert(!error);
+    usearch_free(idx, &error);
+
+}
+
+int main() {
+    const char* filename = "sift/sift_base.fvecs";
+    size_t num_vectors = 0, vector_dim = 0;
+    float* data = read_fvecs_file(filename, &num_vectors, &vector_dim);
+    if (data != NULL) {
+
+        test_index(data, num_vectors, vector_dim);
+
+        free(data); // Remember to free the dynamically allocated memory
+    }
+    return 0;
+}

package/c/usearch.h

@@ -1,14 +1,18 @@
 #ifndef UNUM_USEARCH_H
 #define UNUM_USEARCH_H
-
-#include <stdint.h> // `size_t`
+// in case the header is included from cpp code
+#ifdef __cplusplus
+extern "C" {
+#endif
+#include <stdbool.h> // `bool`
+#include <stdint.h>  // `size_t`
 
 typedef void* usearch_index_t;
 typedef uint32_t usearch_label_t;
 typedef float usearch_distance_t;
 typedef char const* usearch_error_t;
 
-typedef usearch_distance_t (*)(void const*, void const*) usearch_metric_t;
+typedef usearch_distance_t (*usearch_metric_t)(void const*, void const*);
 
 typedef enum usearch_metric_kind_t {
     usearch_metric_ip_k = 0,
@@ -39,13 +43,12 @@ typedef struct usearch_init_options_t {
 
     usearch_scalar_kind_t quantization;
     size_t dimensions;
-    size_t capacity;
     size_t connectivity;
     size_t expansion_add;
     size_t expansion_search;
 } usearch_init_options_t;
 
-void usearch_init(usearch_init_options_t*, usearch_index_t*, usearch_error_t*);
+usearch_index_t usearch_init(usearch_init_options_t*, usearch_error_t*);
 void usearch_free(usearch_index_t, usearch_error_t*);
 
 void usearch_save(usearch_index_t, char const* path, usearch_error_t*);
@@ -79,4 +82,7 @@ bool usearch_get(                     //
 
 void usearch_remove(usearch_index_t, usearch_label_t, usearch_error_t*);
 
+#ifdef __cplusplus
+}
+#endif
 #endif

package/conanfile.py

@@ -4,7 +4,7 @@ from conans import ConanFile
 class USearchConan(ConanFile):
 
     name = 'USearch'
-    version = '0.19.0'
+    version = '0.19.1'
     license = 'Apache 2.0'
     url = 'https://github.com/unum-cloud/usearch'
     description = 'Smaller & Faster Single-File Vector Search Engine from Unum'

package/cpp/bench.cpp

@@ -71,7 +71,7 @@ struct alignas(32) persisted_matrix_gt {
     persisted_matrix_gt(char const* path) noexcept(false) {
         if (!path || !std::strlen(path))
             throw std::invalid_argument("The file path is empty");
-#if defined(WINDOWS)
+#if defined(USEARCH_DEFINED_WINDOWS)
 
         HANDLE file_handle =
             CreateFileA(path, GENERIC_READ, FILE_SHARE_READ, nullptr, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, nullptr);
@@ -117,7 +117,7 @@ struct alignas(32) persisted_matrix_gt {
 
     ~persisted_matrix_gt() {
         if (raw_handle != nullptr)
-#if defined(WINDOWS)
+#if defined(USEARCH_DEFINED_WINDOWS)
             UnmapViewOfFile(raw_handle);
 #else
             munmap((void*)raw_handle, raw_length);
@@ -377,7 +377,7 @@ void handler(int sig) {
     size_t size;
 
     // get void*'s for all entries on the stack
-#if defined(WINDOWS)
+#if defined(USEARCH_DEFINED_WINDOWS)
     size = CaptureStackBackTrace(0, 10, array, NULL);
 #else
     size = backtrace(array, 10);
@@ -386,7 +386,7 @@ void handler(int sig) {
     // print out all the frames to stderr
     fprintf(stderr, "Error: signal %d:\n", sig);
 
-#if defined(WINDOWS)
+#if defined(USEARCH_DEFINED_WINDOWS)
     SYMBOL_INFO* symbol = (SYMBOL_INFO*)calloc(sizeof(SYMBOL_INFO) + 256 * sizeof(char), 1);
     symbol->MaxNameLen = 255;
     symbol->SizeOfStruct = sizeof(SYMBOL_INFO);

package/docs/compilation.md

@@ -173,6 +173,7 @@ go test -v
 
 ```sh
 swift build
+swift test -v
 ```
 
 ## C

package/include/usearch/index.hpp

@@ -112,7 +112,7 @@ namespace usearch {
 using f64_t = double;
 using f32_t = float;
 using byte_t = char;
-enum class b1x8_t : unsigned char {};
+enum b1x8_t : unsigned char {};
 
 enum class metric_kind_t : std::uint8_t {
     unknown_k = 0,
@@ -311,7 +311,7 @@ template <typename scalar_at = float, typename result_at = scalar_at> struct cos
             ab += result_t(a[i]) * result_t(b[i]), //
                 a2 += square<result_t>(a[i]),      //
                 b2 += square<result_t>(b[i]);
-        return (ab != 0) ? (1 - ab / (std::sqrt(a2) * std::sqrt(b2))) : 0;
+        return (ab != 0) ? (1 - ab / (std::sqrt(a2) * std::sqrt(b2))) : 1;
     }
 };
 
@@ -354,7 +354,10 @@ template <typename scalar_at = std::uint64_t, typename result_at = std::size_t>
     using view_t = span_gt<scalar_t const>;
     using result_t = result_at;
     using result_type = result_t;
-    static_assert(std::is_unsigned<scalar_t>::value, "Hamming distance requires unsigned integral words");
+    static_assert( //
+        std::is_unsigned<scalar_t>::value ||
+            (std::is_enum<scalar_t>::value && std::is_unsigned<typename std::underlying_type<scalar_t>::type>::value),
+        "Hamming distance requires unsigned integral words");
 
     inline metric_kind_t kind() const noexcept { return metric_kind_t::hamming_k; }
     inline scalar_kind_t scalar_kind() const noexcept { return common_scalar_kind<scalar_t>(); }
@@ -385,7 +388,10 @@ template <typename scalar_at = std::uint64_t, typename result_at = float> struct
     using view_t = span_gt<scalar_t const>;
     using result_t = result_at;
     using result_type = result_t;
-    static_assert(std::is_unsigned<scalar_t>::value, "Tanimoto distance requires unsigned integral words");
+    static_assert( //
+        std::is_unsigned<scalar_t>::value ||
+            (std::is_enum<scalar_t>::value && std::is_unsigned<typename std::underlying_type<scalar_t>::type>::value),
+        "Tanimoto distance requires unsigned integral words");
     static_assert(std::is_floating_point<result_t>::value, "Tanimoto distance will be a fraction");
 
     inline metric_kind_t kind() const noexcept { return metric_kind_t::tanimoto_k; }
@@ -419,7 +425,10 @@ template <typename scalar_at = std::uint64_t, typename result_at = float> struct
     using view_t = span_gt<scalar_t const>;
     using result_t = result_at;
     using result_type = result_t;
-    static_assert(std::is_unsigned<scalar_t>::value, "Sorensen-Dice distance requires unsigned integral words");
+    static_assert( //
+        std::is_unsigned<scalar_t>::value ||
+            (std::is_enum<scalar_t>::value && std::is_unsigned<typename std::underlying_type<scalar_t>::type>::value),
+        "Sorensen-Dice distance requires unsigned integral words");
     static_assert(std::is_floating_point<result_t>::value, "Sorensen-Dice distance will be a fraction");
 
     inline metric_kind_t kind() const noexcept { return metric_kind_t::sorensen_k; }
@@ -1571,6 +1580,7 @@ class index_gt {
     /**
      *  @brief  Erases all the vectors from the index.
      *          Will change `size()` to zero, but will keep the same `capacity()`.
+     *          Will keep the number of available threads/contexts the same as it was.
      */
     void clear() noexcept {
         std::size_t n = size_;
@@ -1584,6 +1594,7 @@ class index_gt {
     /**
      *  @brief  Erases all the vectors from the index, also deallocating the registry.
      *          Will change both `size()` and `capacity()` to zero.
+     *          Will deallocate all threads/contexts.
      */
     void reset() noexcept {
         clear();
@@ -1732,6 +1743,11 @@ class index_gt {
         std::size_t measurements{};
         error_t error{};
 
+        // todo: this is a hack to get a handle to a failed search_result_t without changing its member types
+        // given that search_result_t can represent a failed result (which implies no valid top_candidates_t &top_),
+        // the top_ probably needs to be a pointer.
+        inline search_result_t(index_gt const& index) noexcept
+            : index_(index), top_(index.contexts_[0].top_candidates) {}
         inline search_result_t(search_result_t&&) = default;
         inline search_result_t& operator=(search_result_t&&) = default;
 
@@ -2574,6 +2590,7 @@ class index_gt {
     void search_exact_(vector_view_t query, std::size_t count, context_t& context) const noexcept {
         top_candidates_t& top = context.top_candidates;
         top.clear();
+        top.reserve(count);
         for (std::size_t i = 0; i != size(); ++i)
             top.insert({context.measure(query, node_with_id_(i)), static_cast<id_t>(i)}, count);
     }

package/include/usearch/index_punned_dense.hpp

@@ -288,6 +288,8 @@ class index_punned_dense_gt {
     search_result_t search_around(label_t hint, f32_t const* vector, std::size_t wanted, search_config_t config) const { return search_around_(hint, vector, wanted, config, casts_.from_f32); }
     search_result_t search_around(label_t hint, f64_t const* vector, std::size_t wanted, search_config_t config) const { return search_around_(hint, vector, wanted, config, casts_.from_f64); }
 
+    search_result_t empty_search_result() const { return search_result_t{*typed_}; }
+
     bool get(label_t label, b1x8_t* vector) const { return get_(label, vector, casts_.to_b1x8); }
     bool get(label_t label, f8_bits_t* vector) const { return get_(label, vector, casts_.to_f8); }
     bool get(label_t label, f16_t* vector) const { return get_(label, vector, casts_.to_f16); }
@@ -641,10 +643,10 @@ class index_punned_dense_gt {
         case metric_kind_t::l2sq_k: return l2sq_metric_(dimensions, accuracy);
         case metric_kind_t::pearson_k: return pearson_metric_(accuracy);
         case metric_kind_t::haversine_k: return haversine_metric_(accuracy);
-        case metric_kind_t::hamming_k: return hamming_gt<uint8_t>{};
+        case metric_kind_t::hamming_k: return hamming_gt<b1x8_t>{};
         case metric_kind_t::jaccard_k: // Equivalent to Tanimoto
-        case metric_kind_t::tanimoto_k: return tanimoto_gt<uint8_t>{};
-        case metric_kind_t::sorensen_k: return sorensen_gt<uint8_t>{};
+        case metric_kind_t::tanimoto_k: return tanimoto_gt<b1x8_t>{};
+        case metric_kind_t::sorensen_k: return sorensen_gt<b1x8_t>{};
         default: return {};
         }
     }

package/include/usearch/index_punned_helpers.hpp

@@ -94,6 +94,8 @@ inline bool hardware_supports(isa_t isa) noexcept {
     default: return false;
     }
 #endif
+
+    (void)isa;
     return false;
 }