usearch 0.15.0 → 0.16.0

package/Cargo.toml

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

package/c/lib.cpp

@@ -7,9 +7,13 @@ extern "C" {
 using namespace unum::usearch;
 using namespace unum;
 
-using label_t = int;
-using distance_t = float;
-using punned_index_t = index_punned_dense_gt<label_t>;
+using label_t = usearch_label_t;
+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 span_t = span_gt<float>;
 
 metric_kind_t to_native_metric(usearch_metric_kind_t kind) {
@@ -40,125 +44,124 @@ scalar_kind_t to_native_scalar(usearch_scalar_kind_t kind) {
 
 void usearch_init(usearch_init_options_t* options, usearch_index_t* index, usearch_error_t* error) {
 
-    try {
-        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();
-
-        // TODO: Implement safe buffers for error messages, either here on in
-        // the C++ type-punned implementation.
-        // static constexpr std::size_t error_limit_k = 128;
-        // struct safe_punned_index_t {
-        //     punned_index_t punned_index;
-        //     char error_buffers[1];
-        // };
-        // std::size_t bytes_for_error_messages = error_limit_k * config.max_threads();
-        // std::size_t bytes_to_alloc = sizeof(punned_index_t) + bytes_for_error_messages;
-        // safe_punned_index_t* result = (safe_punned_index_t*)std::malloc(bytes_to_alloc);
-
-        scalar_kind_t accuracy = scalar_kind_from_name(accuracy_str, accuracy_len);
-        metric_kind_t metric_kind = metric_from_name(metric_str, metric_len);
-        punned_index_t index = make_punned<punned_index_t>( //
-            metric_kind, static_cast<std::size_t>(dimensions), accuracy, config);
-
-        punned_index_t* result_ptr = new punned_index_t(std::move(index));
-        return result_ptr;
-    } catch (std::exception const&) {
-    }
-    return NULL;
-}
-
-void usearch_free(punned_index_t* index) { delete index; }
-
-char const* usearch_save(punned_index_t* index, char const* path) {
-    try {
-        index->save(path);
-        return NULL;
-    } catch (std::exception& e) {
-        // q:: added these to make sure I do not pass a potentially dangling e.what()
-        // though I realize allocation below may fail and I am not checking for it.
-        // what can I do there? Golang side tries to free whatever string is passed from
-        // so passing a compile time constant "double fault" string is not an option
-        char* res = new char[strlen(e.what()) + 1];
-        strcpy(res, e.what());
-        return res;
-    }
+    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();
+
+    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);
+
+    index_t* result_ptr = new index_t(std::move(index));
+    return result_ptr;
 }
 
-char const* usearch_load(punned_index_t* index, char const* path) {
-    try {
-        index->load(path);
-        return NULL;
-    } catch (std::exception& e) {
-        char* res = new char[strlen(e.what()) + 1];
-        strcpy(res, e.what());
-        return res;
-    }
+void usearch_free(index_t* index) { delete 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);
+    if (!result)
+        *error = result.error.what();
+}
+
+void usearch_load(usearch_index_t index, char const* path, usearch_error_t* error) {
+    serialization_result_t result = reinterpret_cast<index_t*>(index)->load(path);
+    if (!result)
+        *error = result.error.what();
+}
+
+void usearch_view(usearch_index_t index, char const* path, usearch_error_t* error) {
+    serialization_result_t result = reinterpret_cast<index_t*>(index)->view(path);
+    if (!result)
+        *error = result.error.what();
+}
+
+size_t usearch_size(usearch_index_t index, usearch_error_t*) { //
+    return reinterpret_cast<index_t*>(index)->size();
+}
+
+size_t usearch_capacity(usearch_index_t index, usearch_error_t*) {
+    return reinterpret_cast<index_t*>(index)->capacity();
+}
+
+size_t usearch_dimensions(usearch_index_t index, usearch_error_t*) {
+    return reinterpret_cast<index_t*>(index)->dimensions();
 }
 
-char const* usearch_view(punned_index_t* index, char const* path) {
-    try {
-        index->view(path);
-        return NULL;
-    } catch (std::exception& e) {
-        char* res = new char[strlen(e.what()) + 1];
-        strcpy(res, e.what());
-        return res;
+size_t usearch_connectivity(usearch_index_t index, usearch_error_t*) {
+    return reinterpret_cast<index_t*>(index)->connectivity();
+}
+
+void usearch_reserve(usearch_index_t index, size_t capacity, usearch_error_t*) {
+    // TODO: Consider returning the new capacity.
+    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!");
     }
 }
 
-int usearch_size(punned_index_t* index) { return index->size(); }
-int usearch_connectivity(punned_index_t* index) { return index->connectivity(); }
-int usearch_dimensions(punned_index_t* index) { return index->dimensions(); }
-int usearch_capacity(punned_index_t* index) { return index->capacity(); }
+void usearch_add(                                                                                 //
+    usearch_index_t index, usearch_label_t label, void const* vector, usearch_scalar_kind_t kind, //
+    usearch_error_t* error) {
+    add_result_t result = add_(reinterpret_cast<index_t*>(index), label, vector, to_native_scalar(kind));
+    if (!result)
+        *error = result.error.what();
+}
+
+bool usearch_contains(usearch_index_t index, usearch_label_t label, usearch_error_t*) {
+    reinterpret_cast<index_t*>(index)->contains(label);
+}
 
-char const* usearch_reserve(punned_index_t* index, int capacity) {
-    try {
-        index->reserve(capacity);
-        return NULL;
-    } catch (std::exception& e) {
-        char* res = new char[strlen(e.what()) + 1];
-        strcpy(res, e.what());
-        return res;
+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!");
     }
 }
 
-char const* usearch_add(punned_index_t* index, int label, float* vector) {
-    // q:: I followed the java example to have try catches everywhere
-    // but they are kind of useless as most errors are outside of cpp so
-    // those translate into segfaults and are not caught by the runtime
-    try {
-        index->add(label, vector);
-    } catch (std::exception& e) {
-        char* res = new char[strlen(e.what()) + 1];
-        strcpy(res, e.what());
-        return res;
+size_t usearch_search(                                                                           //
+    usearch_index_t index, void const* vector, usearch_scalar_kind_t kind, size_t results_limit, //
+    usearch_label_t* found_labels, usearch_distance_t* found_distances, usearch_error_t* error) {
+    search_result_t result = search_(reinterpret_cast<index_t*>(index), vector, to_native_scalar(kind), results_limit);
+    if (!result) {
+        *error = result.error.what();
+        return 0;
     }
-    return NULL;
-}
-
-SearchResults usearch_search(punned_index_t* index, float* query, int query_len, int limit) {
-    // todo:: this could be allocated as golang slice
-    // to avoid a copy. not sure how it interacts with gc
-    // that is why doing this now
-    label_t* matches_data = new label_t[limit];
-
-    // todo:: pass the distances to outside world
-    distance_t* dist_data = new distance_t[limit];
-    SearchResults res{0};
-    try {
-        span_t vector_span = span_t{query, static_cast<std::size_t>(query_len)};
-        res.Len = index->search(vector_span, static_cast<std::size_t>(limit)).dump_to(matches_data, dist_data);
-    } catch (std::exception& e) {
-        res.Error = new char[strlen(e.what()) + 1];
-        strcpy(res.Error, e.what());
-        // res.Error = res;
+
+    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!");
     }
-    res.Labels = matches_data;
-    res.Distances = dist_data;
-    return res;
 }
+
+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));
+}
+
+void usearch_remove(usearch_index_t, usearch_label_t, usearch_error_t*) {}

package/c/usearch.h

@@ -5,9 +5,10 @@
 
 typedef void* usearch_index_t;
 typedef uint32_t usearch_label_t;
+typedef float usearch_distance_t;
 typedef char const* usearch_error_t;
 
-typedef float (*)(void const*, void const*) usearch_metric_t;
+typedef usearch_distance_t (*)(void const*, void const*) usearch_metric_t;
 
 typedef enum usearch_metric_kind_t {
     usearch_metric_ip_k = 0,
@@ -57,18 +58,25 @@ size_t usearch_dimensions(usearch_index_t, usearch_error_t*);
 size_t usearch_connectivity(usearch_index_t, usearch_error_t*);
 
 void usearch_reserve(usearch_index_t, size_t capacity, usearch_error_t*);
-void usearch_add(usearch_index_t, usearch_label_t, float const* vector, usearch_error_t*);
+
+void usearch_add(                                                                            //
+    usearch_index_t, usearch_label_t, void const* vector, usearch_scalar_kind_t vector_kind, //
+    usearch_error_t*);
+
+bool usearch_contains(usearch_index_t, usearch_label_t, usearch_error_t*);
 
 /**
  *  @brief      Performs k-Approximate Nearest Neighbors Search.
  *  @return     Number of found matches.
  */
-size_t usearch_search(                                                //
-    usearch_index_t, float const* query_vector, size_t results_limit, //
-    usearch_label_t* found_labels, float* found_distances, usearch_error_t*);
+size_t usearch_search(                                                                                 //
+    usearch_index_t, void const* query_vector, usearch_scalar_kind_t query_kind, size_t results_limit, //
+    usearch_label_t* found_labels, usearch_distance_t* found_distances, usearch_error_t*);
+
+bool usearch_get(                     //
+    usearch_index_t, usearch_label_t, //
+    void* vector, usearch_scalar_kind_t vector_kind, usearch_error_t*);
 
-bool usearch_contains(usearch_index_t, usearch_label_t, usearch_error_t*);
-void usearch_get(usearch_index_t, usearch_label_t, float* vector, usearch_error_t*);
 void usearch_remove(usearch_index_t, usearch_label_t, usearch_error_t*);
 
 #endif

package/conanfile.py

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

package/cpp/test.cpp

@@ -90,7 +90,7 @@ template <typename scalar_at, typename index_at> void test3d_punned(index_at&& i
 
     // Reconstruct
     scalar_t vec_reconstructed[3] = {0, 0, 0};
-    index.reconstruct(42, span_t{&vec_reconstructed[0], 3ul});
+    index.get(42, span_t{&vec_reconstructed[0], 3ul});
     expect(vec_reconstructed[0] == vec[0]);
     expect(vec_reconstructed[1] == vec[1]);
     expect(vec_reconstructed[2] == vec[2]);

package/include/usearch/index_punned_dense.hpp

@@ -239,11 +239,11 @@ 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); }
 
-    void reconstruct(label_t label, b1x8_t* vector) const { return reconstruct_(label, vector, casts_.to_b1x8); }
-    void reconstruct(label_t label, f8_bits_t* vector) const { return reconstruct_(label, vector, casts_.to_f8); }
-    void reconstruct(label_t label, f16_t* vector) const { return reconstruct_(label, vector, casts_.to_f16); }
-    void reconstruct(label_t label, f32_t* vector) const { return reconstruct_(label, vector, casts_.to_f32); }
-    void reconstruct(label_t label, f64_t* vector) const { return reconstruct_(label, vector, casts_.to_f64); }
+    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); }
+    bool get(label_t label, f32_t* vector) const { return get_(label, vector, casts_.to_f32); }
+    bool get(label_t label, f64_t* vector) const { return get_(label, vector, casts_.to_f64); }
     // clang-format on
 
     static index_punned_dense_gt make(                       //
@@ -368,14 +368,22 @@ class index_punned_dense_gt {
         return lookup_table_.at(label);
     }
 
-    template <typename scalar_at> void reconstruct_(label_t label, scalar_at* reconstructed, cast_t const& cast) const {
-        id_t id = lookup_id_(label);
+    template <typename scalar_at> bool get_(label_t label, scalar_at* reconstructed, cast_t const& cast) const {
+        id_t id;
+        {
+            shared_lock_t lock(lookup_table_mutex_);
+            auto it = lookup_table_.find(label);
+            if (it == lookup_table_.end())
+                return false;
+            id = it->second;
+        }
         member_citerator_t iterator = typed_->cbegin() + id;
         member_cref_t member = *iterator;
         byte_t const* casted_vector = reinterpret_cast<byte_t const*>(member.vector.data());
         bool casted = cast(casted_vector, casted_vector_bytes_, (byte_t*)reconstructed);
         if (!casted)
             std::memcpy(reconstructed, casted_vector, casted_vector_bytes_);
+        return true;
     }
 
     template <typename scalar_at> add_result_t add_(label_t label, scalar_at const* vector, cast_t const& cast) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "usearch",
-    "version": "0.15.0",
+    "version": "0.16.0",
     "description": "Smaller & Faster Single-File Vector Search Engine from Unum",
     "author": "Ashot Vardanian",
     "license": "Apache 2.0",

package/python/lib.cpp

@@ -392,14 +392,15 @@ template <typename index_at> void view_index(index_at& index, std::string const&
 // clang-format on
 
 template <typename internal_at, typename external_at = internal_at, typename index_at = void>
-py::array_t<external_at> get_typed_member(index_at const& index, label_t label) {
+py::object get_typed_member(index_at const& index, label_t label) {
     py::array_t<external_at> result_py(static_cast<Py_ssize_t>(index.scalar_words()));
     auto result_py1d = result_py.template mutable_unchecked<1>();
-    index.reconstruct(label, (internal_at*)&result_py1d(0));
-    return result_py;
+    if (!index.get(label, (internal_at*)&result_py1d(0)))
+        return py::none();
+    return py::object(result_py);
 }
 
-template <typename index_at> py::array get_member(index_at const& index, label_t label, scalar_kind_t scalar_kind) {
+template <typename index_at> py::object get_member(index_at const& index, label_t label, scalar_kind_t scalar_kind) {
     if (scalar_kind == scalar_kind_t::f32_k)
         return get_typed_member<f32_t>(index, label);
     else if (scalar_kind == scalar_kind_t::f64_k)

package/python/scripts/test.py

@@ -79,13 +79,15 @@ def test_index(
     assert index.ndim == ndim
     assert index.connectivity == connectivity
 
-    limit = 0.7 if numpy_type != np.byte else 70
-    vector = np.random.uniform(0, limit, (index.ndim)).astype(numpy_type)
+    vector = random_vectors(count=1, ndim=ndim, dtype=numpy_type).flatten()
 
     index.add(42, vector)
 
     assert 42 in index
     assert 42 in index.labels
+    assert 43 not in index
+    assert index[42] is not None
+    assert index[43] is None
     if numpy_type != np.byte:
         assert np.allclose(index[42], vector, atol=0.1)
 

package/setup.py

@@ -89,8 +89,8 @@ setup(
     ext_modules=ext_modules,
     install_requires=[
         'numpy',
-        'ucall',
         'pandas',
+        'ucall; python_version >= "3.9"',
     ],
     extras_require={
         'jit': ['numba', 'cppyy'],