usearch 0.13.0 → 0.15.0

package/javascript/usearch.js

@@ -1,3 +1,118 @@
-const usearch = require('bindings')('usearch');
+const usearch_native = require('bindings')('usearch');
 
-module.exports = usearch;
+class Index {
+    /**
+     * Creates an instance of Index.
+     * @date 6/7/2023 - 7:32:29 AM
+     *
+     * @constructor
+     * @param {...{}} args
+     */
+    constructor(...args) {
+        this.native = new usearch_native.Index(...args)
+    }
+
+    /**
+     * Description placeholder
+     * @date 6/7/2023 - 7:32:28 AM
+     *
+     * @param {...{}} args
+     * @returns {*}
+     */
+    dimensions(...args) {
+        return this.native.dimensions(...args)
+    }
+
+    /**
+     * Description placeholder
+     * @date 6/7/2023 - 7:32:28 AM
+     *
+     * @param {...{}} args
+     * @returns {*}
+     */
+    size(...args) {
+        return this.native.size(...args)
+    }
+
+    /**
+     * Description placeholder
+     * @date 6/7/2023 - 7:32:28 AM
+     *
+     * @param {...{}} args
+     * @returns {*}
+     */
+    capacity(...args) {
+        return this.native.capacity(...args)
+    }
+
+    /**
+     * Description placeholder
+     * @date 6/7/2023 - 7:32:28 AM
+     *
+     * @param {...{}} args
+     * @returns {*}
+     */
+    connectivity(...args) {
+        return this.native.connectivity(...args)
+    }
+
+    /**
+     * Description placeholder
+     * @date 6/7/2023 - 7:32:28 AM
+     *
+     * @param {...{}} args
+     * @returns {*}
+     */
+    save(...args) {
+        return this.native.save(...args)
+    }
+
+    /**
+     * Description placeholder
+     * @date 6/7/2023 - 7:32:27 AM
+     *
+     * @param {...{}} args
+     * @returns {*}
+     */
+    load(...args) {
+        return this.native.load(...args)
+    }
+
+    /**
+     * Description placeholder
+     * @date 6/7/2023 - 7:32:27 AM
+     *
+     * @param {...{}} args
+     * @returns {*}
+     */
+    view(...args) {
+        return this.native.view(...args)
+    }
+
+    /**
+     * Description placeholder
+     * @date 6/7/2023 - 7:32:27 AM
+     *
+     * @param {...{}} args
+     * @returns {*}
+     */
+    add(...args) {
+        return this.native.add(...args)
+    }
+
+    /**
+     * Description placeholder
+     * @date 6/7/2023 - 7:32:27 AM
+     *
+     * @param {...{}} args
+     * @returns {*}
+     */
+    search(...args) {
+        return this.native.search(...args)
+    }
+}
+
+
+module.exports = {
+    Index: Index
+};

package/objc/USearchObjective.mm

@@ -2,17 +2,73 @@
 
 #pragma clang diagnostic push
 #pragma clang diagnostic ignored "-Wdocumentation"
-#import "punned.hpp"
+#import <usearch/index_punned_dense.hpp>
 #pragma clang diagnostic pop
 
 using namespace unum::usearch;
 using namespace unum;
 
 using distance_t = punned_distance_t;
-using punned_t = punned_gt<UInt32>;
+using punned_t = index_punned_dense_gt<UInt32>;
+using add_result_t = punned_t::add_result_t;
+using search_result_t = punned_t::search_result_t;
+using serialization_result_t = punned_t::serialization_result_t;
 using shared_index_t = std::shared_ptr<punned_t>;
 
-@interface Index ()
+metric_kind_t to_native_metric(USearchMetric m) {
+    switch (m) {
+        case USearchMetricIP:
+            return metric_kind_t::ip_k;
+
+        case USearchMetricCos:
+            return metric_kind_t::cos_k;
+
+        case USearchMetricL2sq:
+            return metric_kind_t::l2sq_k;
+
+        case USearchMetricHamming:
+            return metric_kind_t::hamming_k;
+
+        case USearchMetricHaversine:
+            return metric_kind_t::haversine_k;
+
+        case USearchMetricJaccard:
+            return metric_kind_t::jaccard_k;
+
+        case USearchMetricPearson:
+            return metric_kind_t::pearson_k;
+
+        case USearchMetricSorensen:
+            return metric_kind_t::sorensen_k;
+
+        case USearchMetricTanimoto:
+            return metric_kind_t::tanimoto_k;
+
+        default:
+            return metric_kind_t::unknown_k;
+    }
+}
+
+scalar_kind_t to_native_scalar(USearchScalar m) {
+    switch (m) {
+        case USearchScalarF8:
+            return scalar_kind_t::f8_k;
+
+        case USearchScalarF16:
+            return scalar_kind_t::f16_k;
+
+        case USearchScalarF32:
+            return scalar_kind_t::f32_k;
+
+        case USearchScalarF64:
+            return scalar_kind_t::f64_k;
+
+        default:
+            return scalar_kind_t::unknown_k;
+    }
+}
+
+@interface USearchIndex ()
 
 @property (readonly) shared_index_t native;
 
@@ -20,7 +76,7 @@ using shared_index_t = std::shared_ptr<punned_t>;
 
 @end
 
-@implementation Index
+@implementation USearchIndex
 
 - (instancetype)initWithIndex:(shared_index_t)native {
     self = [super init];
@@ -48,79 +104,101 @@ using shared_index_t = std::shared_ptr<punned_t>;
     return static_cast<UInt32>(_native->capacity());
 }
 
-- (UInt32)expansion_add {
-    return static_cast<UInt32>(_native->config().expansion_add);
-}
-
-- (UInt32)expansion_search {
-    return static_cast<UInt32>(_native->config().expansion_search);
+- (UInt32)expansionAdd {
+    return static_cast<UInt32>(_native->expansion_add());
 }
 
-+ (instancetype)indexIP:(UInt32)dimensions connectivity:(UInt32)connectivity {
-    std::size_t dims = static_cast<std::size_t>(dimensions);
-    index_config_t config;
-
-    config.connectivity = static_cast<std::size_t>(connectivity);
-    shared_index_t ptr = std::make_shared<punned_t>(punned_t::ip(dims, accuracy_t::f32_k, config));
-    return [[Index alloc] initWithIndex:ptr];
+- (UInt32)expansionSearch {
+    return static_cast<UInt32>(_native->expansion_search());
 }
 
-+ (instancetype)indexL2sq:(UInt32)dimensions connectivity:(UInt32)connectivity {
++ (instancetype)make:(USearchMetric)metric dimensions:(UInt32)dimensions connectivity:(UInt32)connectivity quantization:(USearchScalar)quantization {
     std::size_t dims = static_cast<std::size_t>(dimensions);
     index_config_t config;
 
     config.connectivity = static_cast<std::size_t>(connectivity);
-    shared_index_t ptr = std::make_shared<punned_t>(punned_t::l2sq(dims, accuracy_t::f32_k, config));
-    return [[Index alloc] initWithIndex:ptr];
-}
-
-+ (instancetype)indexHaversine:(UInt32)connectivity {
-    index_config_t config;
-
-    config.connectivity = static_cast<std::size_t>(connectivity);
-    shared_index_t ptr = std::make_shared<punned_t>(punned_t::haversine(accuracy_t::f32_k, config));
-    return [[Index alloc] initWithIndex:ptr];
+    shared_index_t ptr = std::make_shared<punned_t>(punned_t::make(dims, to_native_metric(metric), config, to_native_scalar(quantization)));
+    return [[USearchIndex alloc] initWithIndex:ptr];
 }
 
 - (void)addSingle:(UInt32)label
            vector:(Float32 const *_Nonnull)vector {
-    _native->add(label, vector);
+    add_result_t result = _native->add(label, vector);
+
+    if (!result) {
+        @throw [NSException exceptionWithName:@"Can't add to index"
+                                       reason:[NSString stringWithUTF8String:result.error.what()]
+                                     userInfo:nil];
+    }
 }
 
 - (UInt32)searchSingle:(Float32 const *_Nonnull)vector
                  count:(UInt32)wanted
                 labels:(UInt32 *_Nullable)labels
              distances:(Float32 *_Nullable)distances {
-    std::size_t found = _native->search(vector, static_cast<std::size_t>(wanted)).dump_to(labels, distances);
+    search_result_t result = _native->search(vector, static_cast<std::size_t>(wanted));
+
+    if (!result) {
+        @throw [NSException exceptionWithName:@"Can't find in index"
+                                       reason:[NSString stringWithUTF8String:result.error.what()]
+                                     userInfo:nil];
+    }
 
+    std::size_t found = result.dump_to(labels, distances);
     return static_cast<UInt32>(found);
 }
 
-- (void)addPrecise:(UInt32)label
-            vector:(Float64 const *_Nonnull)vector {
-    _native->add(label, (f64_t const *)vector);
+- (void)addDouble:(UInt32)label
+           vector:(Float64 const *_Nonnull)vector {
+    add_result_t result = _native->add(label, (f64_t const *)vector);
+
+    if (!result) {
+        @throw [NSException exceptionWithName:@"Can't add to index"
+                                       reason:[NSString stringWithUTF8String:result.error.what()]
+                                     userInfo:nil];
+    }
 }
 
-- (UInt32)searchPrecise:(Float64 const *_Nonnull)vector
-                  count:(UInt32)wanted
-                 labels:(UInt32 *_Nullable)labels
-              distances:(Float32 *_Nullable)distances {
-    std::size_t found = _native->search((f64_t const *)vector, static_cast<std::size_t>(wanted)).dump_to(labels, distances);
+- (UInt32)searchDouble:(Float64 const *_Nonnull)vector
+                 count:(UInt32)wanted
+                labels:(UInt32 *_Nullable)labels
+             distances:(Float32 *_Nullable)distances {
+    search_result_t result = _native->search((f64_t const *)vector, static_cast<std::size_t>(wanted));
+
+    if (!result) {
+        @throw [NSException exceptionWithName:@"Can't find in index"
+                                       reason:[NSString stringWithUTF8String:result.error.what()]
+                                     userInfo:nil];
+    }
 
+    std::size_t found = result.dump_to(labels, distances);
     return static_cast<UInt32>(found);
 }
 
-- (void)addImprecise:(UInt32)label
-              vector:(void const *_Nonnull)vector {
-    _native->add(label, (f16_bits_t const *)vector);
+- (void)addHalf:(UInt32)label
+         vector:(void const *_Nonnull)vector {
+    add_result_t result = _native->add(label, (f16_t const *)vector);
+
+    if (!result) {
+        @throw [NSException exceptionWithName:@"Can't add to index"
+                                       reason:[NSString stringWithUTF8String:result.error.what()]
+                                     userInfo:nil];
+    }
 }
 
-- (UInt32)searchImprecise:(void const *_Nonnull)vector
-                    count:(UInt32)wanted
-                   labels:(UInt32 *_Nullable)labels
-                distances:(Float32 *_Nullable)distances {
-    std::size_t found = _native->search((f16_bits_t const *)vector, static_cast<std::size_t>(wanted)).dump_to(labels, distances);
+- (UInt32)searchHalf:(void const *_Nonnull)vector
+               count:(UInt32)wanted
+              labels:(UInt32 *_Nullable)labels
+           distances:(Float32 *_Nullable)distances {
+    search_result_t result = _native->search((f16_t const *)vector, static_cast<std::size_t>(wanted));
 
+    if (!result) {
+        @throw [NSException exceptionWithName:@"Can't find in index"
+                                       reason:[NSString stringWithUTF8String:result.error.what()]
+                                     userInfo:nil];
+    }
+
+    std::size_t found = result.dump_to(labels, distances);
     return static_cast<UInt32>(found);
 }
 
@@ -137,7 +215,13 @@ using shared_index_t = std::shared_ptr<punned_t>;
                                      userInfo:nil];
     }
 
-    _native->save(path_c);
+    serialization_result_t result = _native->save(path_c);
+
+    if (!result) {
+        @throw [NSException exceptionWithName:@"Can't save to disk"
+                                       reason:[NSString stringWithUTF8String:result.error.what()]
+                                     userInfo:nil];
+    }
 }
 
 - (void)load:(NSString *)path {
@@ -149,7 +233,13 @@ using shared_index_t = std::shared_ptr<punned_t>;
                                      userInfo:nil];
     }
 
-    _native->load(path_c);
+    serialization_result_t result = _native->load(path_c);
+
+    if (!result) {
+        @throw [NSException exceptionWithName:@"Can't load from disk"
+                                       reason:[NSString stringWithUTF8String:result.error.what()]
+                                     userInfo:nil];
+    }
 }
 
 - (void)view:(NSString *)path {
@@ -161,7 +251,13 @@ using shared_index_t = std::shared_ptr<punned_t>;
                                      userInfo:nil];
     }
 
-    _native->view(path_c);
+    serialization_result_t result = _native->view(path_c);
+
+    if (!result) {
+        @throw [NSException exceptionWithName:@"Can't view from disk"
+                                       reason:[NSString stringWithUTF8String:result.error.what()]
+                                     userInfo:nil];
+    }
 }
 
 @end

package/objc/include/USearchObjective.h

@@ -4,19 +4,36 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-typedef NS_ENUM(NSUInteger, Quantization) {
-    kSinglePrecision,
-    kHalfPrecision,
-    kDoublePrecision
+typedef NS_ENUM(NSUInteger, USearchScalar) {
+    USearchScalarF32,
+    USearchScalarF16,
+    USearchScalarF64,
+    USearchScalarF8,
+    USearchScalarB1
 };
 
+typedef NS_ENUM(NSUInteger, USearchMetric) {
+    USearchMetricUnknown,
+    USearchMetricIP,
+    USearchMetricCos,
+    USearchMetricL2sq,
+    USearchMetricPearson,
+    USearchMetricHaversine,
+    USearchMetricJaccard,
+    USearchMetricHamming,
+    USearchMetricTanimoto,
+    USearchMetricSorensen
+};
+
+typedef UInt32 USearchLabel;
+
 API_AVAILABLE(ios(13.0), macos(10.15), tvos(13.0), watchos(6.0))
-@interface Index : NSObject
+@interface USearchIndex : NSObject
 
 @property (readonly) UInt32 dimensions;
 @property (readonly) UInt32 connectivity;
-@property (readonly) UInt32 expansion_add;
-@property (readonly) UInt32 expansion_search;
+@property (readonly) UInt32 expansionAdd;
+@property (readonly) UInt32 expansionSearch;
 
 @property (readonly) UInt32 length;
 @property (readonly) UInt32 capacity;
@@ -24,37 +41,96 @@ API_AVAILABLE(ios(13.0), macos(10.15), tvos(13.0), watchos(6.0))
 
 - (instancetype)init NS_UNAVAILABLE;
 
-+ (instancetype)indexIP:(UInt32)dimensions connectivity:(UInt32)connectivity NS_SWIFT_NAME(indexIP(dimensions:connectivity:));
-+ (instancetype)indexL2sq:(UInt32)dimensions connectivity:(UInt32)connectivity NS_SWIFT_NAME(l2sq(dimensions:connectivity:));
-+ (instancetype)indexHaversine:(UInt32)connectivity NS_SWIFT_NAME(indexHaversine(connectivity:));
-
-- (void)addSingle:(UInt32)label
+/**
+ * @brief Initializes a new index.
+ * @param metric The distance function to compare the dis-similarity of vectors.
+ * @param dimensions The number of dimensions planned for this index.
+ * @param connectivity Number of connections per node in the proximity graph.
+ * Higher connectivity improves accuracy, increases memory usage, and reduces construction speed.
+ * @param quantization Accuracy of internal vector representations. Lower accuracy means higher speed.
+ */
++ (instancetype)make:(USearchMetric)metric dimensions:(UInt32)dimensions connectivity:(UInt32)connectivity quantization:(USearchScalar)quantization NS_SWIFT_NAME(make(metric:dimensions:connectivity:quantization:));
+
+/**
+ * @brief Adds a labeled vector to the index.
+ * @param vector Single-precision vector.
+ */
+- (void)addSingle:(USearchLabel)label
            vector:(Float32 const *_Nonnull)vector NS_SWIFT_NAME(addSingle(label:vector:));
 
+/**
+ * @brief Approximate nearest neighbors search.
+ * @param vector Single-precision query vector.
+ * @param count Upper limit on the number of matches to retrieve.
+ * @param labels Optional output buffer for labels of approximate neighbors.
+ * @param distances Optional output buffer for (increasing) distances to approximate neighbors.
+ * @return Number of matches exported to `labels` and `distances`.
+ */
 - (UInt32)searchSingle:(Float32 const *_Nonnull)vector
                  count:(UInt32)count
-                labels:(UInt32 *_Nullable)labels
+                labels:(USearchLabel *_Nullable)labels
              distances:(Float32 *_Nullable)distances NS_SWIFT_NAME(searchSingle(vector:count:labels:distances:));
 
-- (void)addPrecise:(UInt32)label
-            vector:(Float64 const *_Nonnull)vector NS_SWIFT_NAME(addPrecise(label:vector:));
-
-- (UInt32)searchPrecise:(Float64 const *_Nonnull)vector
-                  count:(UInt32)count
-                 labels:(UInt32 *_Nullable)labels
-              distances:(Float32 *_Nullable)distances NS_SWIFT_NAME(searchPrecise(vector:count:labels:distances:));
-
-- (void)addImprecise:(UInt32)label
-              vector:(void const *_Nonnull)vector NS_SWIFT_NAME(addImprecise(label:vector:));
-
-- (UInt32)searchImprecise:(void const *_Nonnull)vector
-                    count:(UInt32)count
-                   labels:(UInt32 *_Nullable)labels
-                distances:(Float32 *_Nullable)distances NS_SWIFT_NAME(searchImprecise(vector:count:labels:distances:));
-
-- (void)save:(NSString *)path NS_SWIFT_NAME(dump(path:));
+/**
+ * @brief Adds a labeled vector to the index.
+ * @param vector Double-precision vector.
+ */
+- (void)addDouble:(UInt32)label
+           vector:(Float64 const *_Nonnull)vector NS_SWIFT_NAME(addDouble(label:vector:));
+
+/**
+ * @brief Approximate nearest neighbors search.
+ * @param vector Double-precision query vector.
+ * @param count Upper limit on the number of matches to retrieve.
+ * @param labels Optional output buffer for labels of approximate neighbors.
+ * @param distances Optional output buffer for (increasing) distances to approximate neighbors.
+ * @return Number of matches exported to `labels` and `distances`.
+ */
+- (UInt32)searchDouble:(Float64 const *_Nonnull)vector
+                 count:(UInt32)count
+                labels:(USearchLabel *_Nullable)labels
+             distances:(Float32 *_Nullable)distances NS_SWIFT_NAME(searchDouble(vector:count:labels:distances:));
+
+/**
+ * @brief Adds a labeled vector to the index.
+ * @param vector Half-precision vector.
+ */
+- (void)addHalf:(UInt32)label
+         vector:(void const *_Nonnull)vector NS_SWIFT_NAME(addHalf(label:vector:));
+
+/**
+ * @brief Approximate nearest neighbors search.
+ * @param vector Half-precision query vector.
+ * @param count Upper limit on the number of matches to retrieve.
+ * @param labels Optional output buffer for labels of approximate neighbors.
+ * @param distances Optional output buffer for (increasing) distances to approximate neighbors.
+ * @return Number of matches exported to `labels` and `distances`.
+ */
+- (UInt32)searchHalf:(void const *_Nonnull)vector
+               count:(UInt32)count
+              labels:(USearchLabel *_Nullable)labels
+           distances:(Float32 *_Nullable)distances NS_SWIFT_NAME(searchHalf(vector:count:labels:distances:));
+
+/**
+ * @brief Saves pre-constructed index to disk.
+ */
+- (void)save:(NSString *)path NS_SWIFT_NAME(save(path:));
+
+/**
+ * @brief Loads a pre-constructed index from index.
+ */
 - (void)load:(NSString *)path NS_SWIFT_NAME(load(path:));
+
+/**
+ * @brief Views a pre-constructed index from disk without loading it into RAM.
+ *        Allows working with larger-than memory indexes and saving scarce
+ *        memory on device in read-only workloads.
+ */
 - (void)view:(NSString *)path NS_SWIFT_NAME(view(path:));
+
+/**
+ * @brief Removes all the data from index, while preserving the settings.
+ */
 - (void)clear NS_SWIFT_NAME(clear());
 
 @end

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "usearch",
-    "version": "0.13.0",
+    "version": "0.15.0",
     "description": "Smaller & Faster Single-File Vector Search Engine from Unum",
     "author": "Ashot Vardanian",
     "license": "Apache 2.0",
@@ -24,6 +24,6 @@
         "@semantic-release/exec": "^6.0.3",
         "@semantic-release/git": "^10.0.1",
         "conventional-changelog-eslint": "^3.0.9",
-        "semantic-release": "^21.0.3"
+        "semantic-release": "^21.0.5"
     }
 }