usearch 2.9.2 → 2.10.1

package/README.md

@@ -192,6 +192,44 @@ When compared to FAISS's `IndexFlatL2` in Google Colab, __[USearch may offer up
 - `faiss.IndexFlatL2`: __55.3 ms__.
 - `usearch.index.search`: __2.54 ms__.
 
+## User-Defined Functions
+
+While most vector search packages concentrate on just a few metrics - "Inner Product distance" and "Euclidean distance," USearch extends this list to include any user-defined metrics.
+This flexibility allows you to customize your search for various applications, from computing geospatial coordinates with the rare [Haversine][haversine] distance to creating custom metrics for composite embeddings from multiple AI models.
+
+![USearch: Vector Search Approaches](https://github.com/unum-cloud/usearch/blob/main/assets/usearch-approaches-white.png?raw=true)
+
+Unlike older approaches indexing high-dimensional spaces, like KD-Trees and Locality Sensitive Hashing, HNSW doesn't require vectors to be identical in length.
+They only have to be comparable.
+So you can apply it in [obscure][obscure] applications, like searching for similar sets or fuzzy text matching, using [GZip][gzip-similarity] as a distance function.
+
+> Read more about [JIT and UDF in USearch Python SDK](https://unum-cloud.github.io/usearch/python#user-defined-metrics-and-jit-in-python).
+
+[haversine]: https://ashvardanian.com/posts/abusing-vector-search#geo-spatial-indexing
+[obscure]: https://ashvardanian.com/posts/abusing-vector-search
+[gzip-similarity]: https://twitter.com/LukeGessler/status/1679211291292889100?s=20
+
+## Memory Efficiency, Downcasting, and Quantization
+
+Training a quantization model and dimension-reduction is a common approach to accelerate vector search.
+Those, however, are only sometimes reliable, can significantly affect the statistical properties of your data, and require regular adjustments if your distribution shifts.
+Instead, we have focused on high-precision arithmetic over low-precision downcasted vectors.
+The same index, and `add` and `search` operations will automatically down-cast or up-cast between `f64_t`, `f32_t`, `f16_t`, `i8_t`, and single-bit representations.
+You can use the following command to check, if hardware acceleration is enabled:
+
+```sh
+$ python -c 'from usearch.index import Index; print(Index(ndim=768, metric="cos", dtype="f16").hardware_acceleration)'
+> sapphire
+$ python -c 'from usearch.index import Index; print(Index(ndim=166, metric="tanimoto").hardware_acceleration)'
+> ice
+```
+
+Using smaller numeric types will save you RAM needed to store the vectors, but you can also compress the neighbors lists forming our proximity graphs.
+By default, 32-bit `uint32_t` is used to enumerate those, which is not enough if you need to address over 4 Billion entries.
+For such cases we provide a custom `uint40_t` type, that will still be 37.5% more space-efficient than the commonly used 8-byte integers, and will scale up to 1 Trillion entries.
+
+![USearch uint40_t support](https://github.com/unum-cloud/usearch/blob/main/assets/usearch-neighbor-types.png?raw=true)
+
 ## `Indexes` for Multi-Index Lookups
 
 For larger workloads targeting billions or even trillions of vectors, parallel multi-index lookups become invaluable.
@@ -264,43 +302,6 @@ pairs: dict = men.join(women, max_proposals=0, exact=False)
 
 > Read more in the post: [Combinatorial Stable Marriages for Semantic Search 💍](https://ashvardanian.com/posts/searching-stable-marriages)
 
-## User-Defined Functions
-
-While most vector search packages concentrate on just a few metrics - "Inner Product distance" and "Euclidean distance," USearch extends this list to include any user-defined metrics.
-This flexibility allows you to customize your search for various applications, from computing geospatial coordinates with the rare [Haversine][haversine] distance to creating custom metrics for composite embeddings from multiple AI models.
-
-![USearch: Vector Search Approaches](https://github.com/unum-cloud/usearch/blob/main/assets/usearch-approaches-white.png?raw=true)
-
-Unlike older approaches indexing high-dimensional spaces, like KD-Trees and Locality Sensitive Hashing, HNSW doesn't require vectors to be identical in length.
-They only have to be comparable.
-So you can apply it in [obscure][obscure] applications, like searching for similar sets or fuzzy text matching, using [GZip][gzip-similarity] as a distance function.
-
-> Read more about [JIT and UDF in USearch Python SDK](https://unum-cloud.github.io/usearch/python#user-defined-metrics-and-jit-in-python).
-
-[haversine]: https://ashvardanian.com/posts/abusing-vector-search#geo-spatial-indexing
-[obscure]: https://ashvardanian.com/posts/abusing-vector-search
-[gzip-similarity]: https://twitter.com/LukeGessler/status/1679211291292889100?s=20
-
-## Memory Efficiency, Downcasting, and Quantization
-
-Training a quantization model and dimension-reduction is a common approach to accelerate vector search.
-Those, however, are only sometimes reliable, can significantly affect the statistical properties of your data, and require regular adjustments if your distribution shifts.
-Instead, we have focused on high-precision arithmetic over low-precision downcasted vectors.
-The same index, and `add` and `search` operations will automatically down-cast or up-cast between `f64_t`, `f32_t`, `f16_t`, `i8_t`, and single-bit representations.
-You can use the following command to check, if hardware acceleration is enabled:
-
-```sh
-$ python -c 'from usearch.index import Index; print(Index(ndim=768, metric="cos", dtype="f16").hardware_acceleration)'
-> avx512+f16
-$ python -c 'from usearch.index import Index; print(Index(ndim=166, metric="tanimoto").hardware_acceleration)'
-> avx512+popcnt
-```
-
-Using smaller numeric types will save you RAM needed to store the vectors, but you can also compress the neighbors lists forming our proximity graphs.
-By default, 32-bit `uint32_t` is used to enumerate those, which is not enough if you need to address over 4 Billion entries.
-For such cases we provide a custom `uint40_t` type, that will still be 37.5% more space-efficient than the commonly used 8-byte integers, and will scale up to 1 Trillion entries.
-
-![USearch uint40_t support](https://github.com/unum-cloud/usearch/blob/main/assets/usearch-neighbor-types.png?raw=true)
 
 ## Functionality
 
@@ -431,7 +432,7 @@ doi = {10.5281/zenodo.7949416},
 author = {Vardanian, Ash},
 title = {{USearch by Unum Cloud}},
 url = {https://github.com/unum-cloud/usearch},
-version = {2.9.2},
+version = {2.10.1},
 year = {2023},
 month = oct,
 }

package/javascript/{types → dist/cjs}/usearch.d.ts

@@ -1,4 +1,87 @@
-export class Index {
+type Vector = Float32Array | Float64Array | Int8Array;
+type Matrix = Vector[];
+type VectorOrMatrix = Vector | Matrix;
+/**
+ * Enumeration representing the various metric kinds used to measure the distance between vectors in the index.
+ * @enum {string}
+ * @readonly
+ */
+export declare enum MetricKind {
+    Unknown = "unknown",
+    Cos = "cos",
+    IP = "ip",
+    L2sq = "l2sq",
+    Haversine = "haversine",
+    Divergence = "divergence",
+    Pearson = "pearson",
+    Jaccard = "jaccard",
+    Hamming = "hamming",
+    Tanimoto = "tanimoto",
+    Sorensen = "sorensen"
+}
+/**
+ * Enumeration representing the various scalar kinds used to define the type of scalar values in vectors.
+ * @enum {string}
+ * @readonly
+ */
+export declare enum ScalarKind {
+    Unknown = "unknown",
+    F32 = "f32",
+    F64 = "f64",
+    F16 = "f16",
+    I8 = "i8",
+    B1 = "b1"
+}
+/**
+ * Represents a set of search results.
+ */
+export declare class Matches {
+    keys: BigUint64Array;
+    distances: Float32Array;
+    /**
+     * Constructs a Matches object.
+     *
+     * @param {BigUint64Array} keys - The keys of the nearest neighbors found.
+     * @param {Float32Array} distances - The distances of the nearest neighbors found.
+     */
+    constructor(keys: BigUint64Array, distances: Float32Array);
+}
+/**
+ * Represents a set of batched search results.
+ */
+export declare class BatchMatches {
+    keys: BigUint64Array;
+    distances: Float32Array;
+    counts: BigUint64Array;
+    k: number;
+    /**
+     * Constructs a BatchMatches object.
+     *
+     * @param {BigUint64Array} keys - The keys of the nearest neighbors found in the batch.
+     * @param {Float32Array} distances - The distances of the nearest neighbors found in the batch.
+     * @param {BigUint64Array} counts - The number of neighbors found for each query in the batch.
+     * @param {number} k - The limit for search results per query in the batch.
+     */
+    constructor(keys: BigUint64Array, distances: Float32Array, counts: BigUint64Array, k: number);
+    /**
+     * Retrieves a Matches object at the specified index in the batch.
+     *
+     * @param {number} i - The index at which to retrieve the Matches object.
+     * @returns {Matches} - A Matches object representing the search results at the specified index in the batch.
+     */
+    get(i: number): Matches;
+}
+export interface IndexCongif {
+    dimensions: number;
+    metric: MetricKind;
+    quantization: ScalarKind;
+    connectivity: number;
+    expansion_add: number;
+    expansion_search: number;
+    multi: boolean;
+}
+export declare class Index {
+    #private;
     /**
      * Constructs a new index.
      *
@@ -11,16 +94,7 @@ export class Index {
      * @param {boolean} [multi=false] - Optional, default is false.
      * @throws Will throw an error if any of the parameters are of incorrect type or invalid value.
      */
-    constructor(dimensionsOrConfigs: number | {
-        dimensions: number;
-        metric: MetricKind;
-        quantization: ScalarKind;
-        connectivity: number;
-        expansion_add: number;
-        expansion_search: number;
-        multi: boolean;
-    }, metric?: MetricKind, quantization?: ScalarKind, connectivity?: number, expansion_add?: number, expansion_search?: number, multi?: boolean);
-    _compiledIndex: any;
+    constructor(dimensionsOrConfigs: number | bigint | IndexCongif, metric?: MetricKind, quantization?: ScalarKind, connectivity?: number, expansion_add?: number, expansion_search?: number, multi?: boolean);
     /**
      * Add vectors to the index.
      *
@@ -43,7 +117,7 @@ export class Index {
      * @throws Will throw an error if the length of keys doesn't match the number of vectors
      *         or if it's not a single key.
      */
-    add(keys: bigint | bigint[] | BigUint64Array, vectors: Float32Array | Float64Array | Int8Array): void;
+    add(keys: bigint | bigint[] | BigUint64Array, vectors: Vector): void;
     /**
      * Perform a k-nearest neighbor search on the index.
      *
@@ -59,13 +133,13 @@ export class Index {
      * query vector. If there are not enough results for a query, the result array is
      * padded with -1s.
      *
-     * @param {Float32Array|Float64Array|Int8Array|Array<Array<number>>} vectors - Input matrix representing query vectors, can be a TypedArray or an array of arrays.
+     * @param {Float32Array|Float64Array|Int8Array|Array<Array<number>>} vectors - Input matrix representing query vectors, can be a TypedArray or an array of TypedArray.
      * @param {number} k - The number of nearest neighbors to search for each query vector.
      * @return {Matches|BatchMatches} - Search results for one or more queries, containing keys, distances, and counts of the matches found.
      * @throws Will throw an error if `k` is not a positive integer or if the size of the vectors is not a multiple of dimensions.
-     * @throws Will throw an error if `vectors` is not a valid input type (TypedArray or an array of arrays) or if its flattened size is not a multiple of dimensions.
+     * @throws Will throw an error if `vectors` is not a valid input type (TypedArray or an array of TypedArray) or if its flattened size is not a multiple of dimensions.
      */
-    search(vectors: Float32Array | Float64Array | Int8Array | Array<Array<number>>, k: number): Matches | BatchMatches;
+    search(vectors: VectorOrMatrix, k: number): Matches | BatchMatches;
     /**
      * Verifies the presence of one or more keys in the index.
      *
@@ -135,103 +209,4 @@ export class Index {
      */
     view(path: string): void;
 }
-/**
- * *
- */
-export type MetricKind = string;
-export namespace MetricKind {
-    let Unknown: string;
-    let Cos: string;
-    let IP: string;
-    let L2sq: string;
-    let Haversine: string;
-    let Divergence: string;
-    let Pearson: string;
-    let Jaccard: string;
-    let Hamming: string;
-    let Tanimoto: string;
-    let Sorensen: string;
-}
-/**
- * *
- */
-export type ScalarKind = string;
-export namespace ScalarKind {
-    let Unknown_1: string;
-    export { Unknown_1 as Unknown };
-    export let F32: string;
-    export let F64: string;
-    export let F16: string;
-    export let I8: string;
-    export let B1: string;
-}
-/**
- * Represents a set of search results.
- */
-export class Matches {
-    /**
-     * Constructs a Matches object.
-     *
-     * @param {BigUint64Array} keys - The keys of the nearest neighbors found.
-     * @param {Float32Array} distances - The distances of the nearest neighbors found.
-     */
-    constructor(keys: BigUint64Array, distances: Float32Array);
-    keys: BigUint64Array;
-    distances: Float32Array;
-}
-/**
- * Represents a set of batched search results.
- */
-export class BatchMatches {
-    /**
-     * Constructs a BatchMatches object.
-     *
-     * @param {BigUint64Array} keys - The keys of the nearest neighbors found in the batch.
-     * @param {Float32Array} distances - The distances of the nearest neighbors found in the batch.
-     * @param {BigUint64Array} counts - The number of neighbors found for each query in the batch.
-     * @param {bigint} k - The limit for search results per query in the batch.
-     */
-    constructor(keys: BigUint64Array, distances: Float32Array, counts: BigUint64Array, k: bigint);
-    keys: BigUint64Array;
-    distances: Float32Array;
-    counts: BigUint64Array;
-    k: bigint;
-    /**
-     * Retrieves a Matches object at the specified index in the batch.
-     *
-     * @param {number} i - The index at which to retrieve the Matches object.
-     * @returns {Matches} - A Matches object representing the search results at the specified index in the batch.
-     */
-    get(i: number): Matches;
-}
-/**
- * Performs an exact search on the given dataset to find the best matching vectors for each query.
- *
- * @param {Float32Array|Float64Array|Int8Array|Array<Array<number>>} dataset - The dataset containing vectors to be searched. It can be a TypedArray or an array of arrays.
- * @param {Float32Array|Float64Array|Int8Array|Array<Array<number>>} queries - The queries containing vectors to search for in the dataset. It can be a TypedArray or an array of arrays.
- * @param {number} dimensions - The dimensionality of the vectors in both the dataset and the queries. It defines the number of elements in each vector.
- * @param {number} count - The number of nearest neighbors to return for each query. If the dataset contains fewer vectors than the specified count, the result will contain only the available vectors.
- * @param {MetricKind} metric - The distance metric to be used for the search.
- * @return {Matches|BatchMatches} - Returns a `Matches` or `BatchMatches` object containing the results of the search.
- * @throws Will throw an error if `dimensions` and `count` are not positive integers.
- * @throws Will throw an error if `metric` is not a valid MetricKind.
- * @throws Will throw an error if `dataset` and `queries` are not valid input types (TypedArray or an array of arrays).
- * @throws Will throw an error if the sizes of the flattened `dataset` and `queries` are not multiples of `dimensions`.
- * @throws Will throw an error if `count` is greater than the number of vectors in the `dataset`.
- *
- * @example
- * const dataset = [[1.0, 2.0], [3.0, 4.0]]; // Two vectors: [1.0, 2.0] and [3.0, 4.0]
- * const queries = [[1.5, 2.5]]; // One vector: [1.5, 2.5]
- * const dimensions = 2; // The number of elements in each vector.
- * const count = 1; // The number of nearest neighbors to return for each query.
- * const metric = MetricKind.IP; // Using the Inner Product distance metric.
- *
- * const result = exactSearch(dataset, queries, dimensions, count, metric);
- * // result might be:
- * // {
- * //    keys: BigUint64Array [ 1n ],
- * //    distances: Float32Array [ some_value ],
- * // }
- */
-export function exactSearch(dataset: Float32Array | Float64Array | Int8Array | Array<Array<number>>, queries: Float32Array | Float64Array | Int8Array | Array<Array<number>>, dimensions: number, count: number, metric: MetricKind): Matches | BatchMatches;
-//# sourceMappingURL=usearch.d.ts.map
+export {};