usearch 0.22.3 → 1.1.0

package/javascript/usearch.d.ts

@@ -0,0 +1,102 @@
+
+/** Search result object. */
+export interface Matches {
+    /** The keys of the nearest neighbors found, size n*k. */
+    keys: BigUint64Array,
+    /** The distances of the nearest neighbors found, size n*k. */
+    distances: Float32Array,
+    /** The distances of the nearest neighbors found, size n*k. */
+    count: bigint
+}
+
+/** K-Approximate Nearest Neighbors search index. */
+export class Index {
+
+    /**
+     * Constructs a new index.
+     * 
+     * @param {bigint} dimensions
+     * @param {string} metric
+     * @param {string} quantization
+     * @param {bigint} capacity
+     * @param {bigint} connectivity
+     * @param {bigint} expansion_add
+     * @param {bigint} expansion_search
+     */
+    constructor(...args);
+
+    /**
+     * Returns the dimensionality of vectors.
+     * @return {bigint} The dimensionality of vectors.
+     */
+    dimensions(): bigint;
+
+    /**
+     * Returns the bigint of vectors currently indexed.
+     * @return {bigint} The bigint of vectors currently indexed.
+     */
+    size(): bigint;
+
+    /**
+     * Returns index capacity.
+     * @return {bigints} The capacity of index.
+     */
+    capacity(): bigint;
+
+    /**
+     * Returns connectivity.
+     * @return {bigint} The connectivity of index.
+     */
+    connectivity(): bigint;
+
+    /** 
+     * Write index to a file.
+     * @param {string} path File path to write.
+     */
+    save(path: string): void;
+
+    /** 
+     * Load index from a file.
+     * @param {string} path File path to read.
+     */
+    load(path: string): void;
+
+    /** 
+     * View index from a file, without loading into RAM.
+     * @param {string} path File path to read.
+     */
+    load(path: string): void;
+
+    /** 
+     * Add n vectors of dimension d to the index.
+     * 
+     * @param {bigint | bigint[]} keys Input identifiers for every vector.
+     * @param {Float32Array | Float32Array[]} mat Input matrix, matrix of size n * d.
+     */
+    add(keys: bigint | bigint[], mat: Float32Array | Float32Array[]): void;
+
+    /** 
+     * Query n vectors of dimension d to the index. Return at most k vectors for each. 
+     * If there are not enough results for a query, the result array is padded with -1s.
+     *
+     * @param {Float32Array} mat Input vectors to search, matrix of size n * d.
+     * @param {bigint} k The bigint of nearest neighbors to search for.
+     * @return {Matches} Output of the search result.
+     */
+    search(mat: Float32Array, k: bigint): Matches;
+
+    /** 
+     * Check if an entry is contained in the index.
+     * 
+     * @param {bigint} key Identifier to look up.
+     */
+    contains(key: bigint): boolean;
+
+    /** 
+     * Remove a vector from the index.
+     * 
+     * @param {bigint} key Input identifier for every vector to be removed.
+     */
+    remove(key: bigint): boolean;
+
+}

package/javascript/usearch.js

@@ -1,118 +1,2 @@
-const usearch_native = require('bindings')('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
-};
+const usearch = require('bindings')('usearch');
+module.exports = usearch;

package/objc/USearchObjective.mm

@@ -2,21 +2,19 @@
 
 #pragma clang diagnostic push
 #pragma clang diagnostic ignored "-Wdocumentation"
-#import <usearch/index_punned_dense.hpp>
+#import <usearch/index_dense.hpp>
 #pragma clang diagnostic pop
 
 using namespace unum::usearch;
 using namespace unum;
 
-using metric_t = index_punned_dense_metric_t;
-using distance_t = punned_distance_t;
-using index_t = punned_small_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;
-using label_t = typename index_t::label_t;
-using id_t = typename index_t::id_t;
-using shared_index_t = std::shared_ptr<index_t>;
+using distance_t = distance_punned_t;
+using add_result_t = typename index_dense_t::add_result_t;
+using labeling_result_t = typename index_dense_t::labeling_result_t;
+using search_result_t = typename index_dense_t::search_result_t;
+using shared_index_dense_t = std::shared_ptr<index_dense_t>;
+
+static_assert(std::is_same<USearchKey, index_dense_t::key_t>::value, "Type mismatch between Objective-C and C++");
 
 metric_kind_t to_native_metric(USearchMetric m) {
     switch (m) {
@@ -54,8 +52,8 @@ metric_kind_t to_native_metric(USearchMetric m) {
 
 scalar_kind_t to_native_scalar(USearchScalar m) {
     switch (m) {
-        case USearchScalarF8:
-            return scalar_kind_t::f8_k;
+        case USearchScalarI8:
+            return scalar_kind_t::i8_k;
 
         case USearchScalarF16:
             return scalar_kind_t::f16_k;
@@ -73,15 +71,15 @@ scalar_kind_t to_native_scalar(USearchScalar m) {
 
 @interface USearchIndex ()
 
-@property (readonly) shared_index_t native;
+@property (readonly) shared_index_dense_t native;
 
-- (instancetype)initWithIndex:(shared_index_t)native;
+- (instancetype)initWithIndex:(shared_index_dense_t)native;
 
 @end
 
 @implementation USearchIndex
 
-- (instancetype)initWithIndex:(shared_index_t)native {
+- (instancetype)initWithIndex:(shared_index_dense_t)native {
     self = [super init];
     _native = native;
     return self;
@@ -115,18 +113,18 @@ scalar_kind_t to_native_scalar(USearchScalar m) {
     return static_cast<UInt32>(_native->expansion_search());
 }
 
-+ (instancetype)make:(USearchMetric)metric dimensions:(UInt32)dimensions connectivity:(UInt32)connectivity quantization:(USearchScalar)quantization {
++ (instancetype)make:(USearchMetric)metricKind 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<index_t>(index_t::make(dims, to_native_metric(metric), config, to_native_scalar(quantization)));
+    index_config_t config(static_cast<std::size_t>(connectivity));
+    metric_punned_t metric(dims, to_native_metric(metricKind), to_native_scalar(quantization));
+    shared_index_dense_t ptr = std::make_shared<index_dense_t>(index_dense_t::make(metric, config));
     return [[USearchIndex alloc] initWithIndex:ptr];
 }
 
-- (void)addSingle:(USearchLabel)label
+- (void)addSingle:(USearchKey)key
            vector:(Float32 const *_Nonnull)vector {
-    add_result_t result = _native->add(label, vector);
+    add_result_t result = _native->add(key, vector);
 
     if (!result) {
         @throw [NSException exceptionWithName:@"Can't add to index"
@@ -137,7 +135,7 @@ scalar_kind_t to_native_scalar(USearchScalar m) {
 
 - (UInt32)searchSingle:(Float32 const *_Nonnull)vector
                  count:(UInt32)wanted
-                labels:(USearchLabel *_Nullable)labels
+                  keys:(USearchKey *_Nullable)keys
              distances:(Float32 *_Nullable)distances {
     search_result_t result = _native->search(vector, static_cast<std::size_t>(wanted));
 
@@ -147,13 +145,13 @@ scalar_kind_t to_native_scalar(USearchScalar m) {
                                      userInfo:nil];
     }
 
-    std::size_t found = result.dump_to(labels, distances);
+    std::size_t found = result.dump_to(keys, distances);
     return static_cast<UInt32>(found);
 }
 
-- (void)addDouble:(USearchLabel)label
+- (void)addDouble:(USearchKey)key
            vector:(Float64 const *_Nonnull)vector {
-    add_result_t result = _native->add(label, (f64_t const *)vector);
+    add_result_t result = _native->add(key, (f64_t const *)vector);
 
     if (!result) {
         @throw [NSException exceptionWithName:@"Can't add to index"
@@ -164,7 +162,7 @@ scalar_kind_t to_native_scalar(USearchScalar m) {
 
 - (UInt32)searchDouble:(Float64 const *_Nonnull)vector
                  count:(UInt32)wanted
-                labels:(USearchLabel *_Nullable)labels
+                  keys:(USearchKey *_Nullable)keys
              distances:(Float32 *_Nullable)distances {
     search_result_t result = _native->search((f64_t const *)vector, static_cast<std::size_t>(wanted));
 
@@ -174,13 +172,13 @@ scalar_kind_t to_native_scalar(USearchScalar m) {
                                      userInfo:nil];
     }
 
-    std::size_t found = result.dump_to(labels, distances);
+    std::size_t found = result.dump_to(keys, distances);
     return static_cast<UInt32>(found);
 }
 
-- (void)addHalf:(USearchLabel)label
+- (void)addHalf:(USearchKey)key
          vector:(void const *_Nonnull)vector {
-    add_result_t result = _native->add(label, (f16_t const *)vector);
+    add_result_t result = _native->add(key, (f16_t const *)vector);
 
     if (!result) {
         @throw [NSException exceptionWithName:@"Can't add to index"
@@ -191,7 +189,7 @@ scalar_kind_t to_native_scalar(USearchScalar m) {
 
 - (UInt32)searchHalf:(void const *_Nonnull)vector
                count:(UInt32)wanted
-              labels:(USearchLabel *_Nullable)labels
+                keys:(USearchKey *_Nullable)keys
            distances:(Float32 *_Nullable)distances {
     search_result_t result = _native->search((f16_t const *)vector, static_cast<std::size_t>(wanted));
 
@@ -201,7 +199,7 @@ scalar_kind_t to_native_scalar(USearchScalar m) {
                                      userInfo:nil];
     }
 
-    std::size_t found = result.dump_to(labels, distances);
+    std::size_t found = result.dump_to(keys, distances);
     return static_cast<UInt32>(found);
 }
 
@@ -213,6 +211,34 @@ scalar_kind_t to_native_scalar(USearchScalar m) {
     _native->reserve(static_cast<std::size_t>(count));
 }
 
+- (Boolean)contains:(USearchKey)key {
+    return _native->contains(key);
+}
+
+- (UInt32)count:(USearchKey)key {
+    return _native->count(key);
+}
+
+- (void)remove:(USearchKey)key {
+    labeling_result_t result = _native->remove(key);
+
+    if (!result) {
+        @throw [NSException exceptionWithName:@"Can't remove an entry"
+                                       reason:[NSString stringWithUTF8String:result.error.what()]
+                                     userInfo:nil];
+    }
+}
+
+- (void)rename:(USearchKey)key to:(USearchKey)to {
+    labeling_result_t result = _native->rename(key, to);
+
+    if (!result) {
+        @throw [NSException exceptionWithName:@"Can't rename the entry"
+                                       reason:[NSString stringWithUTF8String:result.error.what()]
+                                     userInfo:nil];
+    }
+}
+
 - (void)save:(NSString *)path {
     char const *path_c = [path UTF8String];
 

package/objc/include/USearchObjective.h

@@ -8,7 +8,7 @@ typedef NS_ENUM(NSUInteger, USearchScalar) {
     USearchScalarF32,
     USearchScalarF16,
     USearchScalarF64,
-    USearchScalarF8,
+    USearchScalarI8,
     USearchScalarB1
 };
 
@@ -25,7 +25,7 @@ typedef NS_ENUM(NSUInteger, USearchMetric) {
     USearchMetricSorensen
 };
 
-typedef UInt64 USearchLabel;
+typedef UInt64 USearchKey;
 
 API_AVAILABLE(ios(13.0), macos(10.15), tvos(13.0), watchos(6.0))
 @interface USearchIndex : NSObject
@@ -46,8 +46,8 @@ API_AVAILABLE(ios(13.0), macos(10.15), tvos(13.0), watchos(6.0))
  * @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.
+ * Higher connectivity improves quantization, increases memory usage, and reduces construction speed.
+ * @param quantization Quantization of internal vector representations. Lower quantization means higher speed.
  */
 + (instancetype)make:(USearchMetric)metric dimensions:(UInt32)dimensions connectivity:(UInt32)connectivity quantization:(USearchScalar)quantization NS_SWIFT_NAME(make(metric:dimensions:connectivity:quantization:));
 
@@ -60,61 +60,71 @@ API_AVAILABLE(ios(13.0), macos(10.15), tvos(13.0), watchos(6.0))
  * @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:));
+- (void)addSingle:(USearchKey)key
+           vector:(Float32 const *_Nonnull)vector NS_SWIFT_NAME(addSingle(key: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 keys Optional output buffer for keys of approximate neighbors.
  * @param distances Optional output buffer for (increasing) distances to approximate neighbors.
- * @return Number of matches exported to `labels` and `distances`.
+ * @return Number of matches exported to `keys` and `distances`.
  */
 - (UInt32)searchSingle:(Float32 const *_Nonnull)vector
                  count:(UInt32)count
-                labels:(USearchLabel *_Nullable)labels
-             distances:(Float32 *_Nullable)distances NS_SWIFT_NAME(searchSingle(vector:count:labels:distances:));
+                  keys:(USearchKey *_Nullable)keys
+             distances:(Float32 *_Nullable)distances NS_SWIFT_NAME(searchSingle(vector:count:keys:distances:));
 
 /**
  * @brief Adds a labeled vector to the index.
  * @param vector Double-precision vector.
  */
-- (void)addDouble:(USearchLabel)label
-           vector:(Float64 const *_Nonnull)vector NS_SWIFT_NAME(addDouble(label:vector:));
+- (void)addDouble:(USearchKey)key
+           vector:(Float64 const *_Nonnull)vector NS_SWIFT_NAME(addDouble(key: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 keys Optional output buffer for keys of approximate neighbors.
  * @param distances Optional output buffer for (increasing) distances to approximate neighbors.
- * @return Number of matches exported to `labels` and `distances`.
+ * @return Number of matches exported to `keys` 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:));
+                  keys:(USearchKey *_Nullable)keys
+             distances:(Float32 *_Nullable)distances NS_SWIFT_NAME(searchDouble(vector:count:keys:distances:));
 
 /**
  * @brief Adds a labeled vector to the index.
  * @param vector Half-precision vector.
  */
-- (void)addHalf:(USearchLabel)label
-         vector:(void const *_Nonnull)vector NS_SWIFT_NAME(addHalf(label:vector:));
+- (void)addHalf:(USearchKey)key
+         vector:(void const *_Nonnull)vector NS_SWIFT_NAME(addHalf(key: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 keys Optional output buffer for keys of approximate neighbors.
  * @param distances Optional output buffer for (increasing) distances to approximate neighbors.
- * @return Number of matches exported to `labels` and `distances`.
+ * @return Number of matches exported to `keys` 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:));
+                keys:(USearchKey *_Nullable)keys
+           distances:(Float32 *_Nullable)distances NS_SWIFT_NAME(searchHalf(vector:count:keys:distances:));
+
+
+- (Boolean)contains:(USearchKey)key NS_SWIFT_NAME(contains(key:));
+
+- (UInt32)count:(USearchKey)key NS_SWIFT_NAME(count(key:));
+
+- (void)remove:(USearchKey)key NS_SWIFT_NAME(remove(key:));
+
+- (void)rename:(USearchKey)key to:(USearchKey)key NS_SWIFT_NAME(rename(from:to:));
+
 
 /**
  * @brief Saves pre-constructed index to disk.

package/package.json

@@ -1,8 +1,8 @@
 {
     "name": "usearch",
-    "version": "0.22.3",
+    "version": "1.1.0",
     "description": "Smaller & Faster Single-File Vector Search Engine from Unum",
-    "author": "Ashot Vardanian",
+    "author": "Ash Vardanian",
     "license": "Apache 2.0",
     "main": "javascript/usearch.js",
     "repository": {
@@ -14,6 +14,7 @@
         "node": "~10 >=10.20 || >=12.17"
     },
     "dependencies": {
+        "@types/node": "^20.4.5",
         "bindings": "~1.2.1",
         "node-addon-api": "^3.0.0"
     },
@@ -24,6 +25,7 @@
         "@semantic-release/exec": "^6.0.3",
         "@semantic-release/git": "^10.0.1",
         "conventional-changelog-eslint": "^3.0.9",
-        "semantic-release": "^21.0.7"
+        "semantic-release": "^21.0.7",
+        "typescript": "^5.1.6"
     }
 }

package/python/README.md

@@ -15,7 +15,7 @@ from usearch.index import Index
 index = Index(
     ndim=3, # Define the number of dimensions in input vectors
     metric='cos', # Choose 'l2sq', 'haversine' or other metric, default = 'ip'
-    dtype='f32', # Quantize to 'f16' or 'f8' if needed, default = 'f32'
+    dtype='f32', # Quantize to 'f16' or 'i8' if needed, default = 'f32'
     connectivity=16, # How frequent should the connections in the graph be, optional
     expansion_add=128, # Control the recall of indexing, optional
     expansion_search=64, # Control the quality of search, optional
@@ -23,12 +23,12 @@ index = Index(
 
 vector = np.array([0.2, 0.6, 0.4])
 index.add(42, vector)
-matches, distances, count = index.search(vector, 10)
+matches: Matches = index.search(vector, 10)
 
 assert len(index) == 1
-assert count == 1
-assert matches[0] == 42
-assert distances[0] <= 0.001
+assert len(matches) == 1
+assert matches[0].key == 42
+assert matches[0].distance <= 0.001
 assert np.allclose(index[42], vector)
 ```
 
@@ -57,14 +57,18 @@ The difference would be in the shape of the tensors.
 
 ```py
 n = 100
-labels = np.arange(n)
+keys = np.arange(n)
 vectors = np.random.uniform(0, 0.3, (n, index.ndim)).astype(np.float32)
 
-index.add(labels, vectors, threads=..., copy=...)
-matches, distances, counts = index.search(vectors, 10, threads=...)
+index.add(keys, vectors, threads=..., copy=...)
+matches: BatchMatches = index.search(vectors, 10, threads=...)
 
-assert matches.shape[0] == vectors.shape[0]
-assert counts[0] <= 10
+first_query_matches: Matches = matches[0]
+assert matches[0].key == 0
+assert matches[0].distance <= 0.001
+
+assert len(matches) == vectors.shape[0]
+assert len(matches[0]) <= 10
 ```
 
 You can also override the default `threads` and `copy` arguments in bulk workloads.
@@ -257,17 +261,22 @@ from usearch.io import load_matrix, save_matrix
 
 vectors = load_matrix('deep1B.fbin')
 index = Index(ndim=vectors.shape[1])
-index.add(labels, vectors)
+index.add(keys, vectors)
 ```
 
 One may often want to evaluate the quality of the constructed index before running in production.
 The trivial way is to measure `recall@1` on the entries already present in the index.
 
 ```py
-from usearch.eval import recall_members
+from usearch.eval import self_recall
+
+stats: SearchStats = self_recall(index, exact=True)
+assert stats.visited_members == 0, "Exact search won't attend index nodes"
+assert stats.computed_distances == len(index), "And will compute the distance to every node"
 
-assert recall_members(index, exact=True) == 1
-print(recall_members(index, exact=False))
+stats: SearchStats = self_recall(index, exact=False)
+assert stats.visited_members > 0
+assert stats.computed_distances <= len(index)
 ```
 
 In case you have some ground-truth data for more than one entry, you compare search results against expected values: