usearch 1.1.1 → 1.2.0

package/python/usearch/index.py

@@ -6,8 +6,17 @@ from __future__ import annotations
 # into the primary `Index` class, connecting USearch with Numba.
 import os
 import math
-from typing import Optional, Union, NamedTuple, List, Iterable
 from dataclasses import dataclass
+from typing import (
+    Optional,
+    Union,
+    NamedTuple,
+    List,
+    Iterable,
+    Tuple,
+    Dict,
+    Callable,
+)
 
 import numpy as np
 from tqdm import tqdm
@@ -34,8 +43,23 @@ MetricKindBitwise = (
     MetricKind.Sorensen,
 )
 
+
+class CompiledMetric(NamedTuple):
+    pointer: int
+    kind: MetricKind
+    signature: MetricSignature
+
+
 Key = np.uint64
 
+KeyOrKeysLike = Union[Key, Iterable[Key], int, Iterable[int], np.ndarray, memoryview]
+
+VectorOrVectorsLike = Union[np.ndarray, Iterable[np.ndarray], memoryview]
+
+DTypeLike = Union[str, ScalarKind]
+
+MetricLike = Union[str, MetricKind, CompiledMetric]
+
 
 def _normalize_dtype(dtype, metric: MetricKind = MetricKind.Cos) -> ScalarKind:
     if dtype is None or dtype == "":
@@ -58,19 +82,11 @@ def _normalize_dtype(dtype, metric: MetricKind = MetricKind.Cos) -> ScalarKind:
         "float32": ScalarKind.F32,
         "float16": ScalarKind.F16,
         "int8": ScalarKind.I8,
-    }
-    if isinstance(dtype, np.dtype):
-        dtype = dtype.name
-    return _normalize[dtype]
-
-
-def _to_numpy_compatible_dtype(dtype: ScalarKind) -> ScalarKind:
-    _normalize = {
-        ScalarKind.F64: ScalarKind.F64,
-        ScalarKind.F32: ScalarKind.F32,
-        ScalarKind.F16: ScalarKind.F16,
-        ScalarKind.I8: ScalarKind.F16,
-        ScalarKind.B1: ScalarKind.B1,
+        np.float64: ScalarKind.F64,
+        np.float32: ScalarKind.F32,
+        np.float16: ScalarKind.F16,
+        np.int8: ScalarKind.I8,
+        np.uint8: ScalarKind.B1,
     }
     return _normalize[dtype]
 
@@ -80,13 +96,15 @@ def _to_numpy_dtype(dtype: ScalarKind):
         ScalarKind.F64: np.float64,
         ScalarKind.F32: np.float32,
         ScalarKind.F16: np.float16,
-        ScalarKind.I8: np.float16,
+        ScalarKind.I8: np.int8,
         ScalarKind.B1: np.uint8,
     }
+    if dtype in _normalize.values():
+        return dtype
     return _normalize[dtype]
 
 
-def _normalize_metric(metric):
+def _normalize_metric(metric) -> MetricKind:
     if metric is None:
         return MetricKind.Cos
 
@@ -111,14 +129,12 @@ def _normalize_metric(metric):
 
 
 def _search_in_compiled(
-    *,
-    compiled: Union[_CompiledIndex, _CompiledIndexes],
+    compiled_callable: Callable,
     vectors: np.ndarray,
-    k: int,
-    threads: int,
-    exact: bool,
+    *,
     log: Union[str, bool],
     batch_size: int,
+    **kwargs,
 ) -> Union[Matches, BatchMatches]:
     #
     assert isinstance(vectors, np.ndarray), "Expects a NumPy array"
@@ -150,12 +166,7 @@ def _search_in_compiled(
             disable=log is False,
         )
         for vectors in tasks:
-            tuple_ = compiled.search(
-                vectors,
-                k,
-                exact=exact,
-                threads=threads,
-            )
+            tuple_ = compiled_callable(vectors, **kwargs)
             tasks_matches.append(BatchMatches(*tuple_))
             pbar.update(vectors.shape[0])
 
@@ -165,22 +176,19 @@ def _search_in_compiled(
                 keys=np.vstack([m.keys for m in tasks_matches]),
                 distances=np.vstack([m.distances for m in tasks_matches]),
                 counts=np.concatenate([m.counts for m in tasks_matches], axis=None),
+                visited_members=sum([m.visited_members for m in tasks_matches]),
+                computed_distances=sum([m.computed_distances for m in tasks_matches]),
             )
         )
 
     else:
-        tuple_ = compiled.search(
-            vectors,
-            k,
-            exact=exact,
-            threads=threads,
-        )
+        tuple_ = compiled_callable(vectors, **kwargs)
         return distil_batch(BatchMatches(*tuple_))
 
 
 def _add_to_compiled(
-    *,
     compiled,
+    *,
     keys,
     vectors,
     copy: bool,
@@ -231,13 +239,13 @@ def _add_to_compiled(
             disable=log is False,
         )
         for keys, vectors in tasks:
-            compiled.add(keys, vectors, copy=copy, threads=threads)
+            compiled.add_many(keys, vectors, copy=copy, threads=threads)
             pbar.update(len(keys))
 
         pbar.close()
 
     else:
-        compiled.add(keys, vectors, copy=copy, threads=threads)
+        compiled.add_many(keys, vectors, copy=copy, threads=threads)
 
     return keys
 
@@ -249,6 +257,9 @@ class Match:
     key: int
     distance: float
 
+    def to_tuple(self) -> tuple:
+        return self.key, self.distance
+
 
 @dataclass
 class Matches:
@@ -258,8 +269,8 @@ class Matches:
     keys: np.ndarray
     distances: np.ndarray
 
-    visited_members: int
-    computed_distances: int
+    visited_members: int = 0
+    computed_distances: int = 0
 
     def __len__(self) -> int:
         return len(self.keys)
@@ -293,8 +304,8 @@ class BatchMatches:
     distances: np.ndarray
     counts: np.ndarray
 
-    visited_members: int
-    computed_distances: int
+    visited_members: int = 0
+    computed_distances: int = 0
 
     def __len__(self) -> int:
         return len(self.counts)
@@ -313,58 +324,140 @@ class BatchMatches:
     def to_list(self) -> List[List[tuple]]:
         """Convert the result for each query to the list of tuples with information about its matches."""
         list_of_matches = [self.__getitem__(row) for row in range(self.__len__())]
-        return [match.to_list() for matches in list_of_matches for match in matches]
+        return [match.to_tuple() for matches in list_of_matches for match in matches]
 
-    def mean_recall(self, expected: np.ndarray, k: Optional[int] = None) -> float:
+    def mean_recall(self, expected: np.ndarray, count: Optional[int] = None) -> float:
         """Measures recall [0, 1] as of `Matches` that contain the corresponding
         `expected` entry anywhere among results."""
-        return self.count_matches(expected, k=k) / len(expected)
+        return self.count_matches(expected, count=count) / len(expected)
 
-    def count_matches(self, expected: np.ndarray, k: Optional[int] = None) -> int:
+    def count_matches(self, expected: np.ndarray, count: Optional[int] = None) -> int:
         """Measures recall [0, len(expected)] as of `Matches` that contain the corresponding
         `expected` entry anywhere among results.
         """
         assert len(expected) == len(self)
         recall = 0
-        if k is None:
-            k = self.keys.shape[1]
+        if count is None:
+            count = self.keys.shape[1]
 
-        if k == 1:
+        if count == 1:
             recall = np.sum(self.keys[:, 0] == expected)
         else:
             for i in range(len(self)):
-                recall += expected[i] in self.keys[i, :k]
+                recall += expected[i] in self.keys[i, :count]
         return recall
 
     def __repr__(self) -> str:
         return f"usearch.BatchMatches({np.sum(self.counts)} across {len(self)} queries)"
 
 
-class CompiledMetric(NamedTuple):
-    pointer: int
-    kind: MetricKind
-    signature: MetricSignature
+@dataclass
+class Clustering:
+    def __init__(
+        self,
+        index: Index,
+        matches: BatchMatches,
+        queries: Optional[np.ndarray] = None,
+    ) -> None:
+        if queries is None:
+            queries = index._compiled.get_keys_in_slice()
+        self.index = index
+        self.queries = queries
+        self.matches = matches
+
+    def __repr__(self) -> str:
+        return f"usearch.Clustering(for {len(self.queries)} queries)"
+
+    @property
+    def centroids_popularity(self) -> Tuple[np.ndarray, np.ndarray]:
+        return np.unique(self.matches.keys, return_counts=True)
+
+    def members_of(self, centroid: Key) -> np.ndarray:
+        return self.queries[self.matches.keys.flatten() == centroid]
+
+    def subcluster(self, centroid: Key, **clustering_kwards) -> Clustering:
+        sub_keys = self.members_of(centroid)
+        return self.index.cluster(keys=sub_keys, **clustering_kwards)
+
+    def plot_centroids_popularity(self):
+        from matplotlib import pyplot as plt
+
+        _, sizes = self.centroids_popularity
+        plt.yscale("log")
+        plt.plot(sorted(sizes), np.arange(len(sizes)))
+        plt.show()
+
+    @property
+    def network(self):
+        import networkx as nx
+
+        keys, sizes = self.centroids_popularity
+
+        g = nx.Graph()
+        for key, size in zip(keys, sizes):
+            g.add_node(key, size=size)
+
+        for i, i_key in enumerate(keys):
+            for j_key in keys[:i]:
+                d = self.index.pairwise_distance(i_key, j_key)
+                g.add_edge(i_key, j_key, distance=d)
+
+        return g
+
+
+class IndexedKeys:
+    """Smart-reference for the range of keys present in a specific `Index`"""
+
+    def __init__(self, index: Index) -> None:
+        self.index = index
+
+    def __len__(self) -> int:
+        return len(self.index)
+
+    def __getitem__(
+        self,
+        offset_offsets_or_slice: Union[int, np.ndarray, slice],
+    ) -> Union[Key, np.ndarray]:
+        if isinstance(offset_offsets_or_slice, slice):
+            start, stop, step = offset_offsets_or_slice.indices(len(self))
+            if step:
+                raise
+            return self.index._compiled.get_keys_in_slice(start, stop - start)
+
+        elif isinstance(offset_offsets_or_slice, Iterable):
+            offsets = np.array(offset_offsets_or_slice)
+            return self.index._compiled.get_keys_at_offsets(offsets)
+
+        else:
+            offset = int(offset_offsets_or_slice)
+            return self.index._compiled.get_key_at_offset(offset)
+
+    def __array__(self, dtype=None) -> np.ndarray:
+        if dtype is None:
+            dtype = Key
+        return self.index._compiled.get_keys_in_slice().astype(dtype)
 
 
 class Index:
-    """Fast JIT-compiled vector-search index for dense equi-dimensional embeddings.
+    """Fast vector-search engine for dense equi-dimensional embeddings.
 
     Vector keys must be integers.
     Vectors must have the same number of dimensions within the index.
-    Supports Inner Product, Cosine Distance, Ln measures
-    like the Euclidean metric, as well as automatic downcasting
-    and quantization.
+    Supports Inner Product, Cosine Distance, L^n measures like the Euclidean metric,
+    as well as automatic downcasting to low-precision floating-point and integral
+    representations.
     """
 
     def __init__(
         self,
         *,
         ndim: int = 0,
-        metric: Union[str, MetricKind, CompiledMetric] = MetricKind.Cos,
-        dtype: Optional[Union[str, ScalarKind]] = None,
+        metric: MetricLike = MetricKind.Cos,
+        dtype: Optional[DTypeLike] = None,
         connectivity: Optional[int] = None,
         expansion_add: Optional[int] = None,
         expansion_search: Optional[int] = None,
+        multi: bool = False,
         path: Optional[os.PathLike] = None,
         view: bool = False,
     ) -> None:
@@ -377,41 +470,43 @@ class Index:
             coordinates. Angular (Cos) and Euclidean (L2sq), obviously, apply to
             vectors with arbitrary number of dimensions.
 
-        :param metric: Distance function, defaults to MetricKind.Cos
-        :type metric: Union[MetricKind, Callable, str], optional
+        :param metric: Distance function
+        :type metric: MetricLike, defaults to MetricKind.Cos
             Kind of the distance function, or the Numba `cfunc` JIT-compiled object.
             Possible `MetricKind` values: IP, Cos, L2sq, Haversine, Pearson,
             Hamming, Tanimoto, Sorensen.
 
-        :param dtype: Scalar type for internal vector storage, defaults to None
-        :type dtype: Optional[Union[str, ScalarKind]], optional
+        :param dtype: Scalar type for internal vector storage
+        :type dtype: Optional[DTypeLike], defaults to None
             For continuous metrics can be: f16, f32, f64, or i8.
             For bitwise metrics it's implementation-defined, and can't change.
             Example: you can use the `f16` index with `f32` vectors in Euclidean space,
             which will be automatically downcasted.
 
-        :param connectivity: Connections per node in HNSW, defaults to None
-        :type connectivity: Optional[int], optional
+        :param connectivity: Connections per node in HNSW
+        :type connectivity: Optional[int], defaults to None
             Hyper-parameter for the number of Graph connections
             per layer of HNSW. The original paper calls it "M".
             Optional, but can't be changed after construction.
 
-        :param expansion_add: Traversal depth on insertions, defaults to None
-        :type expansion_add: Optional[int], optional
+        :param expansion_add: Traversal depth on insertions
+        :type expansion_add: Optional[int], defaults to None
             Hyper-parameter for the search depth when inserting new
             vectors. The original paper calls it "efConstruction".
             Can be changed afterwards, as the `.expansion_add`.
 
-        :param expansion_search: Traversal depth on queries, defaults to None
-        :type expansion_search: Optional[int], optional
+        :param expansion_search: Traversal depth on queries
+        :type expansion_search: Optional[int], defaults to None
             Hyper-parameter for the search depth when querying
             nearest neighbors. The original paper calls it "ef".
             Can be changed afterwards, as the `.expansion_search`.
 
-        :param path: Where to store the index, defaults to None
-        :type path: Optional[os.PathLike], optional
-        :param view: Are we simply viewing an immutable index, defaults to False
-        :type view: bool, optional
+        :param multi: Allow multiple vectors with the same key
+        :type multi: bool, defaults to True
+        :param path: Where to store the index
+        :type path: Optional[os.PathLike], defaults to None
+        :param view: Are we simply viewing an immutable index
+        :type view: bool, defaults to False
         """
 
         if connectivity is None:
@@ -449,6 +544,7 @@ class Index:
             connectivity=connectivity,
             expansion_add=expansion_add,
             expansion_search=expansion_search,
+            multi=multi,
             metric_kind=self._metric_kind,
             metric_pointer=self._metric_pointer,
             metric_signature=self._metric_signature,
@@ -456,6 +552,7 @@ class Index:
 
         self.path = path
         if path and os.path.exists(path):
+            path = os.fspath(path)
             if view:
                 self._compiled.view(path)
             else:
@@ -463,6 +560,7 @@ class Index:
 
     @staticmethod
     def metadata(path: os.PathLike) -> Optional[dict]:
+        path = os.fspath(path)
         if not os.path.exists(path):
             return None
         try:
@@ -472,6 +570,7 @@ class Index:
 
     @staticmethod
     def restore(path: os.PathLike, view: bool = False) -> Optional[Index]:
+        path = os.fspath(path)
         meta = Index.metadata(path)
         if not meta:
             return None
@@ -483,10 +582,13 @@ class Index:
             view=view,
         )
 
+    def __len__(self) -> int:
+        return self._compiled.__len__()
+
     def add(
         self,
-        keys,
-        vectors,
+        keys: KeyOrKeysLike,
+        vectors: VectorOrVectorsLike,
         *,
         copy: bool = True,
         threads: int = 0,
@@ -507,23 +609,23 @@ class Index:
         pass `copy=False`, if you can guarantee the lifetime of the
         primary vectors store during the process of construction.
 
-        :param keys: Unique identifier(s) for passed vectors, optional
-        :type keys: np.ndarray
+        :param keys: Unique identifier(s) for passed vectors
+        :type keys: Optional[KeyOrKeysLike], can be `None`
         :param vectors: Vector or a row-major matrix
-        :type vectors: np.ndarray
-        :param copy: Should the index store a copy of vectors, defaults to True
-        :type copy: bool, optional
-        :param threads: Optimal number of cores to use, defaults to 0
-        :type threads: int, optional
-        :param log: Whether to print the progress bar, default to False
-        :type log: Union[str, bool], optional
-        :param batch_size: Number of vectors to process at once, defaults to 0
-        :type batch_size: int, optional
+        :type vectors: VectorOrVectorsLike
+        :param copy: Should the index store a copy of vectors
+        :type copy: bool, defaults to True
+        :param threads: Optimal number of cores to use
+        :type threads: int, defaults to 0
+        :param log: Whether to print the progress bar
+        :type log: Union[str, bool], defaults to False
+        :param batch_size: Number of vectors to process at once
+        :type batch_size: int, defaults to 0
         :return: Inserted key or keys
         :type: Union[int, np.ndarray]
         """
         return _add_to_compiled(
-            compiled=self._compiled,
+            self._compiled,
             keys=keys,
             vectors=vectors,
             copy=copy,
@@ -534,8 +636,9 @@ class Index:
 
     def search(
         self,
-        vectors,
-        k: int = 10,
+        vectors: VectorOrVectorsLike,
+        count: int = 10,
+        radius: float = math.inf,
         *,
         threads: int = 0,
         exact: bool = False,
@@ -546,38 +649,113 @@ class Index:
         Performs approximate nearest neighbors search for one or more queries.
 
         :param vectors: Query vector or vectors.
-        :type vectors: np.ndarray
-        :param k: Upper limit on the number of matches to find, defaults to 10
-        :type k: int, optional
-        :param threads: Optimal number of cores to use, defaults to 0
-        :type threads: int, optional
-        :param exact: Perform exhaustive linear-time exact search, defaults to False
-        :type exact: bool, optional
+        :type vectors: VectorOrVectorsLike
+        :param count: Upper count on the number of matches to find
+        :type count: int, defaults to 10
+        :param threads: Optimal number of cores to use
+        :type threads: int, defaults to 0
+        :param exact: Perform exhaustive linear-time exact search
+        :type exact: bool, defaults to False
         :param log: Whether to print the progress bar, default to False
         :type log: Union[str, bool], optional
-        :param batch_size: Number of vectors to process at once, defaults to 0
-        :type batch_size: int, optional
+        :param batch_size: Number of vectors to process at once
+        :type batch_size: int, defaults to 0
         :return: Matches for one or more queries
         :rtype: Union[Matches, BatchMatches]
         """
 
         return _search_in_compiled(
-            compiled=self._compiled,
-            vectors=vectors,
-            k=k,
-            exact=exact,
-            threads=threads,
+            self._compiled.search_many,
+            vectors,
+            # Batch scheduling:
             log=log,
             batch_size=batch_size,
+            # Search constraints:
+            count=count,
+            exact=exact,
+            threads=threads,
         )
 
+    def contains(self, keys: KeyOrKeysLike) -> Union[bool, np.ndarray]:
+        if isinstance(keys, Iterable):
+            return self._compiled.contains_many(np.array(keys, dtype=Key))
+        else:
+            return self._compiled.contains_one(int(keys))
+
+    def __contains__(self, keys: KeyOrKeysLike) -> Union[bool, np.ndarray]:
+        return self.contains(keys)
+
+    def count(self, keys: KeyOrKeysLike) -> Union[int, np.ndarray]:
+        if isinstance(keys, Iterable):
+            return self._compiled.count_many(np.array(keys, dtype=Key))
+        else:
+            return self._compiled.count_one(int(keys))
+
+    def get(
+        self,
+        keys: KeyOrKeysLike,
+        dtype: Optional[DTypeLike] = None,
+    ) -> Union[Optional[np.ndarray], Tuple[Optional[np.ndarray]]]:
+        """Looks up one or more keys from the `Index`, retrieving corresponding vectors.
+
+        Returns `None`, if one key is requested, and its not present.
+        Returns a (row) vector, if the key maps into a single vector.
+        Returns a (row-major) matrix, if the key maps into a multiple vectors.
+        If multiple keys are requested, composes many such responses into a `tuple`.
+
+        :param keys: One or more keys to lookup
+        :type keys: KeyOrKeysLike
+        :return: One or more keys lookup results
+        :rtype: Union[Optional[np.ndarray], Tuple[Optional[np.ndarray]]]
+        """
+        if not dtype:
+            dtype = self.dtype
+        else:
+            dtype = _normalize_dtype(dtype)
+
+        view_dtype = _to_numpy_dtype(dtype)
+
+        def cast(result):
+            if result is not None:
+                return result.view(view_dtype)
+            return result
+
+        is_one = not isinstance(keys, Iterable)
+        if is_one:
+            keys = [keys]
+        if not isinstance(keys, np.ndarray):
+            keys = np.array(keys, dtype=Key)
+        else:
+            keys = keys.astype(Key)
+
+        results = self._compiled.get_many(keys, dtype)
+        results = [cast(result) for result in results]
+        return results[0] if is_one else results
+
+    def __getitem__(
+        self, keys: KeyOrKeysLike
+    ) -> Union[np.ndarray, Tuple[np.ndarray, np.ndarray]]:
+        """Looks up one or more keys from the `Index`, retrieving corresponding vectors.
+
+        Returns `None`, if one key is requested, and its not present.
+        Returns a (row) vector, if the key maps into a single vector.
+        Returns a (row-major) matrix, if the key maps into a multiple vectors.
+        If multiple keys are requested, composes many such responses into a `tuple`.
+
+        :param keys: One or more keys to lookup
+        :type keys: KeyOrKeysLike
+        :return: One or more keys lookup results
+        :rtype: Union[Optional[np.ndarray], Tuple[Optional[np.ndarray]]]
+        """
+        return self.get(keys)
+
     def remove(
         self,
-        keys: Union[int, Iterable[int]],
+        keys: KeyOrKeysLike,
         *,
         compact: bool = False,
         threads: int = 0,
-    ) -> Union[bool, int]:
+    ) -> Union[int, np.ndarray]:
         """Removes one or move vectors from the index.
 
         When working with extremely large indexes, you may want to
@@ -585,57 +763,72 @@ class Index:
         In other cases, rebuilding - is the recommended approach.
 
         :param keys: Unique identifier for passed vectors, optional
-        :type keys: np.ndarray
+        :type keys: KeyOrKeysLike
         :param compact: Removes links to removed nodes (expensive), defaults to False
         :type compact: bool, optional
         :param threads: Optimal number of cores to use, defaults to 0
         :type threads: int, optional
-        :return: Number of removed entries
-        :type: Union[bool, int]
+        :return: Array of integers for the number of removed vectors per key
+        :type: Union[int, np.ndarray]
         """
-        return self._compiled.remove(keys, compact=compact, threads=threads)
-
-    def rename(self, label_from: int, label_to: int) -> bool:
-        """Relabel existing entry"""
-        return self._compiled.rename(label_from, label_to)
-
-    @property
-    def specs(self) -> dict:
-        return {
-            "Class": "usearch.Index",
-            "Connectivity": self.connectivity,
-            "Size": self.size,
-            "Dimensions": self.ndim,
-            "Expansion@Add": self.expansion_add,
-            "Expansion@Search": self.expansion_search,
-            "OpenMP": USES_OPENMP,
-            "SimSIMD": USES_SIMSIMD,
-            "NativeF16": USES_NATIVE_F16,
-            "JIT": self.jit,
-            "DType": self.dtype,
-            "Path": self.path,
-        }
+        if not isinstance(keys, Iterable):
+            return self._compiled.remove_one(keys, compact=compact, threads=threads)
+        else:
+            keys = np.array(keys, dtype=Key)
+            return self._compiled.remove_many(keys, compact=compact, threads=threads)
 
-    def __len__(self) -> int:
-        return self._compiled.__len__()
+    def __delitem__(self, keys: KeyOrKeysLike) -> Union[int, np.ndarray]:
+        raise self.remove(keys)
 
-    def __delitem__(self, key: int) -> bool:
-        raise self.remove(key)
+    def rename(
+        self,
+        from_: KeyOrKeysLike,
+        to: KeyOrKeysLike,
+    ) -> Union[int, np.ndarray]:
+        """Rename existing member vector or vectors.
+
+        May be used in iterative clustering procedures, where one would iteratively
+        relabel every vector with the name of the cluster an entry belongs to, until
+        the system converges.
+
+        :param from_: One or more keys to be renamed
+        :type from_: KeyOrKeysLike
+        :param to: New name or names (of identical length as `from_`)
+        :type to: KeyOrKeysLike
+        :return: Number of vectors that were found and renamed
+        :rtype: int
+        """
+        if isinstance(from_, Iterable):
+            from_ = np.array(from_, dtype=Key)
+            if isinstance(to, Iterable):
+                to = np.array(to, dtype=Key)
+                return self._compiled.rename_many_to_many(from_, to)
 
-    def __contains__(self, key: int) -> bool:
-        return self._compiled.__contains__(key)
+            else:
+                return self._compiled.rename_many_to_one(from_, int(to))
 
-    def __getitem__(self, key: int) -> np.ndarray:
-        dtype = self.dtype
-        get_dtype = _to_numpy_compatible_dtype(dtype)
-        vector = self._compiled.__getitem__(key, get_dtype)
-        view_dtype = _to_numpy_dtype(dtype)
-        return None if vector is None else vector.view(view_dtype)
+        else:
+            return self._compiled.rename_one_to_one(int(from_), int(to))
 
     @property
     def jit(self) -> bool:
+        """
+        :return: True, if the provided `metric` was JIT-ed
+        :rtype: bool
+        """
         return self._metric_jit is not None
 
+    @property
+    def hardware_acceleration(self) -> str:
+        """Describes the kind of hardware-acceleration support used in
+        that exact instance of the `Index`, for that metric kind, and
+        the given number of dimensions.
+
+        :return: "auto", if nothing is available, ISA subset name otherwise
+        :rtype: str
+        """
+        return self._compiled.hardware_acceleration
+
     @property
     def size(self) -> int:
         return self._compiled.size
@@ -649,7 +842,7 @@ class Index:
         return self._metric_jit if self._metric_jit else self._metric_kind
 
     @metric.setter
-    def metric(self, metric: Union[str, MetricKind, CompiledMetric]):
+    def metric(self, metric: MetricLike):
         metric = _normalize_metric(metric)
         if isinstance(metric, MetricKind):
             metric_kind = metric
@@ -728,6 +921,9 @@ class Index:
         """Erases all members from index, closing files, and returning RAM to OS."""
         self._compiled.reset()
 
+    def __del__(self):
+        self.reset()
+
     def copy(self) -> Index:
         result = Index(
             ndim=self.ndim,
@@ -741,7 +937,12 @@ class Index:
         result._compiled = self._compiled.copy()
         return result
 
-    def join(self, other: Index, max_proposals: int = 0, exact: bool = False) -> dict:
+    def join(
+        self,
+        other: Index,
+        max_proposals: int = 0,
+        exact: bool = False,
+    ) -> Dict[Key, Key]:
         """Performs "Semantic Join" or pairwise matching between `self` & `other` index.
         Is different from `search`, as no collisions are allowed in resulting pairs.
         Uses the concept of "Stable Marriages" from Combinatorics, famous for the 2012
@@ -754,7 +955,7 @@ class Index:
         :param exact: Controls if underlying `search` should be exact, defaults to False
         :type exact: bool, optional
         :return: Mapping from keys of `self` to keys of `other`
-        :rtype: dict
+        :rtype: Dict[Key, Key]
         """
         return self._compiled.join(
             other=other._compiled,
@@ -762,44 +963,91 @@ class Index:
             exact=exact,
         )
 
-    def get_keys(self, offset: int = 0, limit: int = 0) -> np.ndarray:
-        if limit == 0:
-            limit = 2**63 - 1
-        return self._compiled.get_keys(offset, limit)
+    def cluster(
+        self,
+        *,
+        vectors: Optional[np.ndarray] = None,
+        keys: Optional[np.ndarray] = None,
+        min_count: Optional[int] = None,
+        max_count: Optional[int] = None,
+        threads: int = 0,
+        log: Union[str, bool] = False,
+        batch_size: int = 0,
+    ) -> Clustering:
+        """
+        Clusters already indexed or provided `vectors`, mapping them to various centroids.
 
-    @property
-    def keys(self) -> np.ndarray:
-        """Retrieves the keys of all vectors present in `self`
+        :param vectors: .
+        :type vectors: Optional[VectorOrVectorsLike]
+        :param count: Upper bound on the number of clusters to produce
+        :type count: Optional[int], defaults to None
 
-        :return: Array of keys
-        :rtype: np.ndarray
+        :param threads: Optimal number of cores to use,
+        :type threads: int, defaults to 0
+        :param log: Whether to print the progress bar
+        :type log: Union[str, bool], defaults to False
+        :param batch_size: Number of vectors to process at once, defaults to 0
+        :type batch_size: int, defaults to 0
+        :return: Matches for one or more queries
+        :rtype: Union[Matches, BatchMatches]
         """
-        return self._compiled.keys
+        if min_count is None:
+            min_count = 0
+        if max_count is None:
+            max_count = 0
+
+        if vectors is not None:
+            assert keys is None, "You can either cluster vectors or member keys"
+            results = self._compiled.cluster_vectors(
+                vectors,
+                min_count=min_count,
+                max_count=max_count,
+                threads=threads,
+            )
+        else:
+            if keys is None:
+                keys = self._compiled.get_keys_in_slice()
+            if not isinstance(keys, np.ndarray):
+                keys = np.array(keys)
+            keys = keys.astype(Key)
+            results = self._compiled.cluster_keys(
+                keys,
+                min_count=min_count,
+                max_count=max_count,
+                threads=threads,
+            )
 
-    def get_vectors(
-        self,
-        keys: np.ndarray,
-        dtype: ScalarKind = ScalarKind.F32,
-    ) -> np.ndarray:
-        """Retrieves vectors associated with given `keys`
+        batch_matches = BatchMatches(*results)
+        return Clustering(self, batch_matches, keys)
 
-        :return: Matrix of vectors (row-major)
-        :rtype: np.ndarray
-        """
-        dtype = _normalize_dtype(dtype, self._metric_kind)
-        get_dtype = _to_numpy_compatible_dtype(dtype)
-        vectors = np.vstack([self._compiled.__getitem__(l, get_dtype) for l in keys])
-        view_dtype = _to_numpy_dtype(dtype)
-        return vectors.view(view_dtype)
+    def pairwise_distance(
+        self, left: KeyOrKeysLike, right: KeyOrKeysLike
+    ) -> Union[np.ndarray, float]:
+        assert isinstance(left, Iterable) == isinstance(right, Iterable)
+
+        if not isinstance(left, Iterable):
+            return self._compiled.pairwise_distance(int(left), int(right))
+        else:
+            left = np.array(left).astype(Key)
+            right = np.array(right).astype(Key)
+            return self._compiled.pairwise_distances(left, right)
+
+    @property
+    def keys(self) -> IndexedKeys:
+        return IndexedKeys(self)
 
     @property
     def vectors(self) -> np.ndarray:
-        return self.get_vectors(self.keys, self.dtype)
+        return self.get(self.keys, vstack=True)
 
     @property
     def max_level(self) -> int:
         return self._compiled.max_level
 
+    @property
+    def nlevels(self) -> int:
+        return self._compiled.max_level + 1
+
     @property
     def levels_stats(self) -> _CompiledIndexStats:
         """Get the accumulated statistics for the entire multi-level graph.
@@ -829,37 +1077,63 @@ class Index:
         """
         return self._compiled.level_stats(level)
 
+    @property
+    def specs(self) -> Dict[str, Union[str, int, bool]]:
+        return {
+            "Class": "usearch.Index",
+            "Connectivity": self.connectivity,
+            "Size": self.size,
+            "Dimensions": self.ndim,
+            "Expansion@Add": self.expansion_add,
+            "Expansion@Search": self.expansion_search,
+            "OpenMP": USES_OPENMP,
+            "SimSIMD": USES_SIMSIMD,
+            "NativeF16": USES_NATIVE_F16,
+            "JIT": self.jit,
+            "DType": self.dtype,
+            "Path": self.path,
+        }
+
     def __repr__(self) -> str:
-        f = "usearch.Index({} x {}, {}, expansion: {} & {}, {} vectors in {} levels)"
+        f = "usearch.Index({} x {}, {}, connectivity: {}, expansion: {} & {}, {} vectors in {} levels)"
         return f.format(
             self.dtype,
             self.ndim,
             self.metric,
+            self.connectivity,
             self.expansion_add,
             self.expansion_search,
             len(self),
-            self.max_level + 1,
+            self.nlevels,
         )
 
-    def _repr_pretty_(self) -> str:
+    def _repr_pretty_(self, printer, cycle) -> str:
         level_stats = [
-            f"--- {i}. {self.level_stats(i).nodes} nodes" for i in range(self.max_level)
+            f"--- {i}. {self.level_stats(i).nodes:,} nodes" for i in range(self.nlevels)
         ]
-        return "\n".join(
+        lines = "\n".join(
             [
                 "usearch.Index",
-                "- config" f"-- data type: {self.dtype}",
+                "- config",
+                f"-- data type: {self.dtype}",
                 f"-- dimensions: {self.ndim}",
                 f"-- metric: {self.metric}",
+                f"-- connectivity: {self.connectivity}",
                 f"-- expansion on addition:{self.expansion_add} candidates",
                 f"-- expansion on search: {self.expansion_search} candidates",
+                "- binary",
+                f"-- uses OpenMP: {USES_OPENMP}",
+                f"-- uses SimSIMD: {USES_SIMSIMD}",
+                f"-- supports half-precision: {USES_NATIVE_F16}",
+                f"-- uses hardware acceletion: {self.hardware_acceleration}",
                 "- state",
-                f"-- size: {self.size} vectors",
-                f"-- memory usage: {self.memory_usage} bytes",
+                f"-- size: {self.size:,} vectors",
+                f"-- memory usage: {self.memory_usage:,} bytes",
                 f"-- max level: {self.max_level}",
                 *level_stats,
             ]
         )
+        printer.text(lines)
 
 
 class Indexes:
@@ -872,11 +1146,14 @@ class Indexes:
     ) -> None:
         self._compiled = _CompiledIndexes()
         for index in indexes:
-            self._compiled.add(index._compiled)
-        self._compiled.add_paths(paths, view=view, threads=threads)
+            self._compiled.merge(index._compiled)
+        self._compiled.merge_paths(paths, view=view, threads=threads)
+
+    def merge(self, index: Index):
+        self._compiled.merge(index._compiled)
 
-    def add(self, index: Index):
-        self._compiled.add(index._compiled)
+    def merge_path(self, path: os.PathLike):
+        self._compiled.merge_path(os.fspath(path))
 
     def __len__(self) -> int:
         return self._compiled.__len__()
@@ -884,27 +1161,29 @@ class Indexes:
     def search(
         self,
         vectors,
-        k: int = 10,
+        count: int = 10,
         *,
         threads: int = 0,
         exact: bool = False,
     ):
         return _search_in_compiled(
-            compiled=self._compiled,
-            vectors=vectors,
-            k=k,
-            exact=exact,
-            threads=threads,
+            self._compiled.search_many,
+            vectors,
+            # Batch scheduling:
             log=False,
             batch_size=None,
+            # Search constraints:
+            count=count,
+            exact=exact,
+            threads=threads,
         )
 
 
 def search(
     dataset: np.ndarray,
     query: np.ndarray,
-    k: int = 10,
-    metric: Union[str, MetricKind, CompiledMetric] = MetricKind.Cos,
+    count: int = 10,
+    metric: MetricLike = MetricKind.Cos,
     *,
     exact: bool = False,
     threads: int = 0,
@@ -919,11 +1198,11 @@ def search(
     :param query: Query vector or vectors (also row-major), to find in `dataset`.
     :type query: np.ndarray
 
-    :param k: Upper limit on the number of matches to find, defaults to 10
-    :type k: int, optional
+    :param count: Upper count on the number of matches to find, defaults to 10
+    :type count: int, optional
 
-    :param metric: Distance function, defaults to MetricKind.Cos
-    :type metric: Union[MetricKind, Callable, str], optional
+    :param metric: Distance function
+    :type metric: MetricLike, defaults to MetricKind.Cos
         Kind of the distance function, or the Numba `cfunc` JIT-compiled object.
         Possible `MetricKind` values: IP, Cos, L2sq, Haversine, Pearson,
         Hamming, Tanimoto, Sorensen.
@@ -957,7 +1236,7 @@ def search(
         )
         return index.search(
             query,
-            k,
+            count,
             threads=threads,
             log=log,
             batch_size=batch_size,
@@ -975,31 +1254,27 @@ def search(
     else:
         raise ValueError("The `metric` must be a `CompiledMetric` or a `MetricKind`")
 
-    class WrappedDataset:
-        def __init__(self) -> None:
-            pass
-
-        def search(self, query, k, **kwargs):
-            kwargs.pop("exact")
-            kwargs.update(
-                dict(
-                    metric_kind=metric_kind,
-                    metric_pointer=metric_pointer,
-                    metric_signature=metric_signature,
-                )
-            )
-            assert dataset.shape[1] == query.shape[1], "Number of dimensions differs"
-            if dataset.dtype != query.dtype:
-                query = query.astype(dataset.dtype)
+    def search_batch(query, **kwargs):
+        assert dataset.shape[1] == query.shape[1], "Number of dimensions differs"
+        if dataset.dtype != query.dtype:
+            query = query.astype(dataset.dtype)
 
-            return _exact_search(dataset, query, k, **kwargs)
+        return _exact_search(
+            dataset,
+            query,
+            metric_kind=metric_kind,
+            metric_pointer=metric_pointer,
+            metric_signature=metric_signature,
+            **kwargs,
+        )
 
     return _search_in_compiled(
-        compiled=WrappedDataset(),
-        vectors=query,
-        k=k,
-        threads=threads,
-        exact=True,
+        search_batch,
+        query,
+        # Batch scheduling:
         log=log,
         batch_size=batch_size,
+        # Search constraints:
+        count=count,
+        threads=threads,
     )