usearch 0.22.3 → 1.0.0

package/python/usearch/index.py

@@ -7,13 +7,17 @@ from __future__ import annotations
 import os
 import math
 from typing import Optional, Union, NamedTuple, List, Iterable
+from dataclasses import dataclass
 
 import numpy as np
 from tqdm import tqdm
 
-from usearch.compiled import Index as _CompiledIndex, IndexMetadata, IndexStats
-from usearch.compiled import SparseIndex as _CompiledSetsIndex
+from usearch.compiled import Index as _CompiledIndex
+from usearch.compiled import Indexes as _CompiledIndexes
+from usearch.compiled import IndexStats as _CompiledIndexStats
 
+from usearch.compiled import index_dense_metadata as _index_dense_metadata
+from usearch.compiled import exact_search as _exact_search
 from usearch.compiled import MetricKind, ScalarKind, MetricSignature
 from usearch.compiled import (
     DEFAULT_CONNECTIVITY,
@@ -30,12 +34,10 @@ MetricKindBitwise = (
     MetricKind.Sorensen,
 )
 
-SparseIndex = _CompiledSetsIndex
+Key = np.uint64
 
-Label = np.uint64
 
-
-def _normalize_dtype(dtype, metric: MetricKind = MetricKind.IP) -> ScalarKind:
+def _normalize_dtype(dtype, metric: MetricKind = MetricKind.Cos) -> ScalarKind:
     if dtype is None or dtype == "":
         return ScalarKind.B1 if metric in MetricKindBitwise else ScalarKind.F32
 
@@ -49,14 +51,16 @@ def _normalize_dtype(dtype, metric: MetricKind = MetricKind.IP) -> ScalarKind:
         "f64": ScalarKind.F64,
         "f32": ScalarKind.F32,
         "f16": ScalarKind.F16,
-        "f8": ScalarKind.F8,
+        "i8": ScalarKind.I8,
         "b1": ScalarKind.B1,
         "b1x8": ScalarKind.B1,
-        np.float64: ScalarKind.F64,
-        np.float32: ScalarKind.F32,
-        np.float16: ScalarKind.F16,
-        np.int8: ScalarKind.F8,
+        "float64": ScalarKind.F64,
+        "float32": ScalarKind.F32,
+        "float16": ScalarKind.F16,
+        "int8": ScalarKind.I8,
     }
+    if isinstance(dtype, np.dtype):
+        dtype = dtype.name
     return _normalize[dtype]
 
 
@@ -65,7 +69,7 @@ def _to_numpy_compatible_dtype(dtype: ScalarKind) -> ScalarKind:
         ScalarKind.F64: ScalarKind.F64,
         ScalarKind.F32: ScalarKind.F32,
         ScalarKind.F16: ScalarKind.F16,
-        ScalarKind.F8: ScalarKind.F16,
+        ScalarKind.I8: ScalarKind.F16,
         ScalarKind.B1: ScalarKind.B1,
     }
     return _normalize[dtype]
@@ -76,7 +80,7 @@ def _to_numpy_dtype(dtype: ScalarKind):
         ScalarKind.F64: np.float64,
         ScalarKind.F32: np.float32,
         ScalarKind.F16: np.float16,
-        ScalarKind.F8: np.float16,
+        ScalarKind.I8: np.float16,
         ScalarKind.B1: np.uint8,
     }
     return _normalize[dtype]
@@ -84,15 +88,19 @@ def _to_numpy_dtype(dtype: ScalarKind):
 
 def _normalize_metric(metric):
     if metric is None:
-        return MetricKind.IP
+        return MetricKind.Cos
 
     if isinstance(metric, str):
         _normalize = {
             "cos": MetricKind.Cos,
+            "cosine": MetricKind.Cos,
             "ip": MetricKind.IP,
+            "dot": MetricKind.IP,
+            "inner_product": MetricKind.IP,
+            "l2sq": MetricKind.L2sq,
             "l2_sq": MetricKind.L2sq,
             "haversine": MetricKind.Haversine,
-            "perason": MetricKind.Pearson,
+            "pearson": MetricKind.Pearson,
             "hamming": MetricKind.Hamming,
             "tanimoto": MetricKind.Tanimoto,
             "sorensen": MetricKind.Sorensen,
@@ -102,59 +110,234 @@ def _normalize_metric(metric):
     return metric
 
 
-class Matches(NamedTuple):
-    labels: np.ndarray
+def _search_in_compiled(
+    *,
+    compiled: Union[_CompiledIndex, _CompiledIndexes],
+    vectors: np.ndarray,
+    k: int,
+    threads: int,
+    exact: bool,
+    log: Union[str, bool],
+    batch_size: int,
+) -> Union[Matches, BatchMatches]:
+    #
+    assert isinstance(vectors, np.ndarray), "Expects a NumPy array"
+    assert vectors.ndim == 1 or vectors.ndim == 2, "Expects a matrix or vector"
+    if vectors.ndim == 1:
+        vectors = vectors.reshape(1, len(vectors))
+    count_vectors = vectors.shape[0]
+
+    def distil_batch(
+        batch_matches: BatchMatches,
+    ) -> Union[BatchMatches, Matches]:
+        return batch_matches[0] if count_vectors == 1 else batch_matches
+
+    if log and batch_size == 0:
+        batch_size = int(math.ceil(count_vectors / 100))
+
+    if batch_size:
+        tasks = [
+            vectors[start_row : start_row + batch_size, :]
+            for start_row in range(0, count_vectors, batch_size)
+        ]
+        tasks_matches = []
+        name = log if isinstance(log, str) else "Search"
+        pbar = tqdm(
+            tasks,
+            desc=name,
+            total=count_vectors,
+            unit="vector",
+            disable=log is False,
+        )
+        for vectors in tasks:
+            tuple_ = compiled.search(
+                vectors,
+                k,
+                exact=exact,
+                threads=threads,
+            )
+            tasks_matches.append(BatchMatches(*tuple_))
+            pbar.update(vectors.shape[0])
+
+        pbar.close()
+        return distil_batch(
+            BatchMatches(
+                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),
+            )
+        )
+
+    else:
+        tuple_ = compiled.search(
+            vectors,
+            k,
+            exact=exact,
+            threads=threads,
+        )
+        return distil_batch(BatchMatches(*tuple_))
+
+
+def _add_to_compiled(
+    *,
+    compiled,
+    keys,
+    vectors,
+    copy: bool,
+    threads: int,
+    log: Union[str, bool],
+    batch_size: int,
+) -> Union[int, np.ndarray]:
+    assert isinstance(vectors, np.ndarray), "Expects a NumPy array"
+    assert vectors.ndim == 1 or vectors.ndim == 2, "Expects a matrix or vector"
+    if vectors.ndim == 1:
+        vectors = vectors.reshape(1, len(vectors))
+
+    # Validate or generate the keys
+    count_vectors = vectors.shape[0]
+    generate_labels = keys is None
+    if generate_labels:
+        start_id = len(compiled)
+        keys = np.arange(start_id, start_id + count_vectors, dtype=Key)
+    else:
+        if not isinstance(keys, Iterable):
+            assert count_vectors == 1, "Each vector must have a key"
+            keys = [keys]
+        keys = np.array(keys).astype(Key)
+
+    assert len(keys) == count_vectors
+
+    # If logging is requested, and batch size is undefined, set it to grow 1% at a time:
+    if log and batch_size == 0:
+        batch_size = int(math.ceil(count_vectors / 100))
+
+    # Split into batches and log progress, if needed
+    if batch_size:
+        keys = [
+            keys[start_row : start_row + batch_size]
+            for start_row in range(0, count_vectors, batch_size)
+        ]
+        vectors = [
+            vectors[start_row : start_row + batch_size, :]
+            for start_row in range(0, count_vectors, batch_size)
+        ]
+        tasks = zip(keys, vectors)
+        name = log if isinstance(log, str) else "Add"
+        pbar = tqdm(
+            tasks,
+            desc=name,
+            total=count_vectors,
+            unit="vector",
+            disable=log is False,
+        )
+        for keys, vectors in tasks:
+            compiled.add(keys, vectors, copy=copy, threads=threads)
+            pbar.update(len(keys))
+
+        pbar.close()
+
+    else:
+        compiled.add(keys, vectors, copy=copy, threads=threads)
+
+    return keys
+
+
+@dataclass
+class Match:
+    """This class contains information about retrieved vector."""
+
+    key: int
+    distance: float
+
+
+@dataclass
+class Matches:
+    """This class contains information about multiple retrieved vectors for single query,
+    i.e it is a set of `Match` instances."""
+
+    keys: np.ndarray
     distances: np.ndarray
-    counts: Union[np.ndarray, int]
 
-    @property
-    def is_multiple(self) -> bool:
-        return isinstance(self.counts, np.ndarray)
+    visited_members: int
+    computed_distances: int
 
-    @property
-    def batch_size(self) -> int:
-        return len(self.counts) if isinstance(self.counts, np.ndarray) else 1
+    def __len__(self) -> int:
+        return len(self.keys)
 
-    @property
-    def total_matches(self) -> int:
-        return np.sum(self.counts)
+    def __getitem__(self, index: int) -> Match:
+        if isinstance(index, int) and index < len(self):
+            return Match(
+                key=self.keys[index],
+                distance=self.distances[index],
+            )
+        else:
+            raise IndexError(f"`index` must be an integer under {len(self)}")
+
+    def to_list(self) -> List[tuple]:
+        """
+        Convert matches to the list of tuples which contain matches' indices and distances to them.
+        """
+
+        return [(int(l), float(d)) for l, d in zip(self.keys, self.distances)]
+
+    def __repr__(self) -> str:
+        return f"usearch.Matches({len(self)})"
 
-    def to_list(self, row: Optional[int] = None) -> Union[List[dict], List[List[dict]]]:
-        if not self.is_multiple:
-            assert row is None, "Exporting a single sequence is only for batch requests"
-            labels = self.labels
-            distances = self.distances
 
-        elif row is None:
-            return [self.to_list(i) for i in range(self.batch_size)]
+@dataclass
+class BatchMatches:
+    """This class contains information about multiple retrieved vectors for multiple queries,
+    i.e it is a set of `Matches` instances."""
 
+    keys: np.ndarray
+    distances: np.ndarray
+    counts: np.ndarray
+
+    visited_members: int
+    computed_distances: int
+
+    def __len__(self) -> int:
+        return len(self.counts)
+
+    def __getitem__(self, index: int) -> Matches:
+        if isinstance(index, int) and index < len(self):
+            return Matches(
+                keys=self.keys[index, : self.counts[index]],
+                distances=self.distances[index, : self.counts[index]],
+                visited_members=self.visited_members // len(self),
+                computed_distances=self.computed_distances // len(self),
+            )
         else:
-            count = self.counts[row]
-            labels = self.labels[row, :count]
-            distances = self.distances[row, :count]
+            raise IndexError(f"`index` must be an integer under {len(self)}")
 
-        return [
-            {"label": int(label), "distance": float(distance)}
-            for label, distance in zip(labels, distances)
-        ]
+    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]
 
-    def recall_first(self, expected: np.ndarray) -> float:
-        best_matches = self.labels if not self.is_multiple else self.labels[:, 0]
-        return np.sum(best_matches == expected) / len(expected)
+    def mean_recall(self, expected: np.ndarray, k: 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)
 
-    def recall(self, expected: np.ndarray) -> float:
-        assert len(expected) == self.batch_size
+    def count_matches(self, expected: np.ndarray, k: 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
-        for i in range(self.batch_size):
-            recall += expected[i] in self.labels[i]
-        return recall / len(expected)
+        if k is None:
+            k = self.keys.shape[1]
+
+        if k == 1:
+            recall = np.sum(self.keys[:, 0] == expected)
+        else:
+            for i in range(len(self)):
+                recall += expected[i] in self.keys[i, :k]
+        return recall
 
     def __repr__(self) -> str:
-        return (
-            f"usearch.Matches({self.total_matches})"
-            if self.is_multiple
-            else f"usearch.Matches({self.total_matches} across {self.batch_size} queries)"
-        )
+        return f"usearch.BatchMatches({np.sum(self.counts)} across {len(self)} queries)"
 
 
 class CompiledMetric(NamedTuple):
@@ -166,7 +349,7 @@ class CompiledMetric(NamedTuple):
 class Index:
     """Fast JIT-compiled vector-search index for dense equi-dimensional embeddings.
 
-    Vector labels must be integers.
+    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
@@ -175,13 +358,13 @@ class Index:
 
     def __init__(
         self,
+        *,
         ndim: int = 0,
-        metric: Union[str, MetricKind, CompiledMetric] = MetricKind.IP,
+        metric: Union[str, MetricKind, CompiledMetric] = MetricKind.Cos,
         dtype: Optional[Union[str, ScalarKind]] = None,
-        connectivity: int = DEFAULT_CONNECTIVITY,
-        expansion_add: int = DEFAULT_EXPANSION_ADD,
-        expansion_search: int = DEFAULT_EXPANSION_SEARCH,
-        tune: bool = False,
+        connectivity: Optional[int] = None,
+        expansion_add: Optional[int] = None,
+        expansion_search: Optional[int] = None,
         path: Optional[os.PathLike] = None,
         view: bool = False,
     ) -> None:
@@ -189,21 +372,20 @@ class Index:
 
         :param ndim: Number of vector dimensions
         :type ndim: int
-            Required for some metrics, optional for others.
+            Required for some metrics, pre-set for others.
             Haversine, for example, only applies to 2-dimensional latitude/longitude
             coordinates. Angular (Cos) and Euclidean (L2sq), obviously, apply to
             vectors with arbitrary number of dimensions.
 
-        :param metric: Distance function, defaults to MetricKind.IP
+        :param metric: Distance function, defaults to MetricKind.Cos
         :type metric: Union[MetricKind, Callable, str], optional
             Kind of the distance function, or the Numba `cfunc` JIT-compiled object.
             Possible `MetricKind` values: IP, Cos, L2sq, Haversine, Pearson,
             Hamming, Tanimoto, Sorensen.
-            Not every kind is JIT-able. For Jaccard distance, use `SparseIndex`.
 
         :param dtype: Scalar type for internal vector storage, defaults to None
         :type dtype: Optional[Union[str, ScalarKind]], optional
-            For continuous metrics can be: f16, f32, f64, or f8.
+            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.
@@ -226,15 +408,23 @@ class Index:
             nearest neighbors. The original paper calls it "ef".
             Can be changed afterwards, as the `.expansion_search`.
 
-        :param tune: Automatically adjusts hyper-parameters, defaults to False
-        :type tune: bool, optional
-
         :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
         """
 
+        if connectivity is None:
+            connectivity = DEFAULT_CONNECTIVITY
+        if expansion_add is None:
+            expansion_add = DEFAULT_EXPANSION_ADD
+        if expansion_search is None:
+            expansion_search = DEFAULT_EXPANSION_SEARCH
+
+        assert isinstance(connectivity, int), "Expects integer `connectivity`"
+        assert isinstance(expansion_add, int), "Expects integer `expansion_add`"
+        assert isinstance(expansion_search, int), "Expects integer `expansion_search`"
+
         metric = _normalize_metric(metric)
         if isinstance(metric, MetricKind):
             self._metric_kind = metric
@@ -256,13 +446,12 @@ class Index:
         self._compiled = _CompiledIndex(
             ndim=ndim,
             dtype=dtype,
-            metric=self._metric_kind,
-            metric_pointer=self._metric_pointer,
-            metric_signature=self._metric_signature,
             connectivity=connectivity,
             expansion_add=expansion_add,
             expansion_search=expansion_search,
-            tune=tune,
+            metric_kind=self._metric_kind,
+            metric_pointer=self._metric_pointer,
+            metric_signature=self._metric_signature,
         )
 
         self.path = path
@@ -273,31 +462,30 @@ class Index:
                 self._compiled.load(path)
 
     @staticmethod
-    def metadata(path: os.PathLike) -> IndexMetadata:
-        return IndexMetadata(path)
+    def metadata(path: os.PathLike) -> Optional[dict]:
+        if not os.path.exists(path):
+            return None
+        try:
+            return _index_dense_metadata(path)
+        except Exception:
+            return None
 
     @staticmethod
-    def restore(path: os.PathLike, view: bool = False) -> Index:
+    def restore(path: os.PathLike, view: bool = False) -> Optional[Index]:
         meta = Index.metadata(path)
-        bits_per_scalar = {
-            ScalarKind.F8: 8,
-            ScalarKind.F16: 16,
-            ScalarKind.F32: 32,
-            ScalarKind.F64: 64,
-            ScalarKind.B1: 1,
-        }[meta.scalar_kind]
-        ndim = meta.bytes_for_vectors * 8 // meta.size // bits_per_scalar
+        if not meta:
+            return None
         return Index(
-            ndim=ndim,
-            connectivity=meta.connectivity,
-            metric=meta.metric,
+            ndim=meta["dimensions"],
+            dtype=meta["kind_scalar"],
+            metric=meta["kind_metric"],
             path=path,
             view=view,
         )
 
     def add(
         self,
-        labels,
+        keys,
         vectors,
         *,
         copy: bool = True,
@@ -307,22 +495,22 @@ class Index:
     ) -> Union[int, np.ndarray]:
         """Inserts one or move vectors into the index.
 
-        For maximal performance the `labels` and `vectors`
+        For maximal performance the `keys` and `vectors`
         should conform to the Python's "buffer protocol" spec.
 
         To index a single entry:
-            labels: int, vectors: np.ndarray.
+            keys: int, vectors: np.ndarray.
         To index many entries:
-            labels: np.ndarray, vectors: np.ndarray.
+            keys: np.ndarray, vectors: np.ndarray.
 
         When working with extremely large indexes, you may want to
         pass `copy=False`, if you can guarantee the lifetime of the
         primary vectors store during the process of construction.
 
-        :param labels: Unique identifier(s) for passed vectors, optional
-        :type labels: Buffer
+        :param keys: Unique identifier(s) for passed vectors, optional
+        :type keys: np.ndarray
         :param vectors: Vector or a row-major matrix
-        :type vectors: Buffer
+        :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
@@ -331,66 +519,18 @@ class Index:
         :type log: Union[str, bool], optional
         :param batch_size: Number of vectors to process at once, defaults to 0
         :type batch_size: int, optional
-        :return: Inserted label or labels
+        :return: Inserted key or keys
         :type: Union[int, np.ndarray]
         """
-        assert isinstance(vectors, np.ndarray), "Expects a NumPy array"
-        assert vectors.ndim == 1 or vectors.ndim == 2, "Expects a matrix or vector"
-        count_vectors = vectors.shape[0] if vectors.ndim == 2 else 1
-        is_multiple = count_vectors > 1
-        if not is_multiple:
-            vectors = vectors.flatten()
-
-        # Validate of generate teh labels
-        generate_labels = labels is None
-        if generate_labels:
-            start_id = len(self._compiled)
-            if is_multiple:
-                labels = np.arange(start_id, start_id + count_vectors, dtype=Label)
-            else:
-                labels = start_id
-        else:
-            if isinstance(labels, np.ndarray):
-                if not is_multiple:
-                    labels = int(labels[0])
-                else:
-                    labels = labels.astype(Label)
-        count_labels = len(labels) if isinstance(labels, Iterable) else 1
-        assert count_labels == count_vectors
-
-        # If logging is requested, and batch size is undefined, set it to grow 1% at a time:
-        if log and batch_size == 0:
-            batch_size = int(math.ceil(count_vectors / 100))
-
-        # Split into batches and log progress, if needed
-        if batch_size:
-            labels = [
-                labels[start_row : start_row + batch_size]
-                for start_row in range(0, count_vectors, batch_size)
-            ]
-            vectors = [
-                vectors[start_row : start_row + batch_size, :]
-                for start_row in range(0, count_vectors, batch_size)
-            ]
-            tasks = zip(labels, vectors)
-            name = log if isinstance(log, str) else "Add"
-            pbar = tqdm(
-                tasks,
-                desc=name,
-                total=count_vectors,
-                unit="Vector",
-                disable=log is False,
-            )
-            for labels, vectors in tasks:
-                self._compiled.add(labels, vectors, copy=copy, threads=threads)
-                pbar.update(len(labels))
-
-            pbar.close()
-
-        else:
-            self._compiled.add(labels, vectors, copy=copy, threads=threads)
-
-        return labels
+        return _add_to_compiled(
+            compiled=self._compiled,
+            keys=keys,
+            vectors=vectors,
+            copy=copy,
+            threads=threads,
+            log=log,
+            batch_size=batch_size,
+        )
 
     def search(
         self,
@@ -401,12 +541,12 @@ class Index:
         exact: bool = False,
         log: Union[str, bool] = False,
         batch_size: int = 0,
-    ) -> Matches:
+    ) -> Union[Matches, BatchMatches]:
         """
         Performs approximate nearest neighbors search for one or more queries.
 
         :param vectors: Query vector or vectors.
-        :type vectors: Buffer
+        :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
@@ -417,60 +557,23 @@ class Index:
         :type log: Union[str, bool], optional
         :param batch_size: Number of vectors to process at once, defaults to 0
         :type batch_size: int, optional
-        :return: Approximate matches for one or more queries
-        :rtype: Matches
+        :return: Matches for one or more queries
+        :rtype: Union[Matches, BatchMatches]
         """
 
-        assert isinstance(vectors, np.ndarray), "Expects a NumPy array"
-        assert vectors.ndim == 1 or vectors.ndim == 2, "Expects a matrix or vector"
-        count_vectors = vectors.shape[0] if vectors.ndim == 2 else 1
-
-        if log and batch_size == 0:
-            batch_size = int(math.ceil(count_vectors / 100))
-
-        if batch_size:
-            tasks = [
-                vectors[start_row : start_row + batch_size, :]
-                for start_row in range(0, count_vectors, batch_size)
-            ]
-            tasks_matches = []
-            name = log if isinstance(log, str) else "Search"
-            pbar = tqdm(
-                tasks,
-                desc=name,
-                total=count_vectors,
-                unit="Vector",
-                disable=log is False,
-            )
-            for vectors in tasks:
-                tuple_ = self._compiled.search(
-                    vectors,
-                    k,
-                    exact=exact,
-                    threads=threads,
-                )
-                tasks_matches.append(Matches(*tuple_))
-                pbar.update(vectors.shape[0])
-
-            pbar.close()
-            return Matches(
-                labels=np.vstack([m.labels 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),
-            )
-
-        else:
-            tuple_ = self._compiled.search(
-                vectors,
-                k,
-                exact=exact,
-                threads=threads,
-            )
-            return Matches(*tuple_)
+        return _search_in_compiled(
+            compiled=self._compiled,
+            vectors=vectors,
+            k=k,
+            exact=exact,
+            threads=threads,
+            log=log,
+            batch_size=batch_size,
+        )
 
     def remove(
         self,
-        labels: Union[int, Iterable[int]],
+        keys: Union[int, Iterable[int]],
         *,
         compact: bool = False,
         threads: int = 0,
@@ -481,8 +584,8 @@ class Index:
         mark some entries deleted, instead of rebuilding a filtered index.
         In other cases, rebuilding - is the recommended approach.
 
-        :param labels: Unique identifier for passed vectors, optional
-        :type labels: Buffer
+        :param keys: Unique identifier for passed vectors, optional
+        :type keys: np.ndarray
         :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
@@ -490,7 +593,7 @@ class Index:
         :return: Number of removed entries
         :type: Union[bool, int]
         """
-        return self._compiled.remove(labels, compact=compact, threads=threads)
+        return self._compiled.remove(keys, compact=compact, threads=threads)
 
     def rename(self, label_from: int, label_to: int) -> bool:
         """Relabel existing entry"""
@@ -516,16 +619,16 @@ class Index:
     def __len__(self) -> int:
         return self._compiled.__len__()
 
-    def __delitem__(self, label: int) -> bool:
-        raise self.remove(label)
+    def __delitem__(self, key: int) -> bool:
+        raise self.remove(key)
 
-    def __contains__(self, label: int) -> bool:
-        return self._compiled.__contains__(label)
+    def __contains__(self, key: int) -> bool:
+        return self._compiled.__contains__(key)
 
-    def __getitem__(self, label: int) -> np.ndarray:
+    def __getitem__(self, key: int) -> np.ndarray:
         dtype = self.dtype
         get_dtype = _to_numpy_compatible_dtype(dtype)
-        vector = self._compiled.__getitem__(label, get_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)
 
@@ -545,6 +648,28 @@ class Index:
     def metric(self) -> Union[MetricKind, CompiledMetric]:
         return self._metric_jit if self._metric_jit else self._metric_kind
 
+    @metric.setter
+    def metric(self, metric: Union[str, MetricKind, CompiledMetric]):
+        metric = _normalize_metric(metric)
+        if isinstance(metric, MetricKind):
+            metric_kind = metric
+            metric_pointer = 0
+            metric_signature = MetricSignature.ArrayArraySize
+        elif isinstance(metric, CompiledMetric):
+            metric_kind = metric.kind
+            metric_pointer = metric.pointer
+            metric_signature = metric.signature
+        else:
+            raise ValueError(
+                "The `metric` must be a `CompiledMetric` or a `MetricKind`"
+            )
+
+        return self._compiled.change_metric(
+            metric_kind=metric_kind,
+            metric_pointer=metric_pointer,
+            metric_signature=metric_signature,
+        )
+
     @property
     def dtype(self) -> ScalarKind:
         return self._compiled.dtype
@@ -581,25 +706,27 @@ class Index:
         path = path if path else self.path
         if path is None:
             raise Exception("Define `path` argument")
-        self._compiled.save(path)
+        self._compiled.save(os.fspath(path))
 
     def load(self, path: Optional[os.PathLike] = None):
         path = path if path else self.path
         if path is None:
             raise Exception("Define `path` argument")
-        self._compiled.load(path)
+        self._compiled.load(os.fspath(path))
 
     def view(self, path: Optional[os.PathLike] = None):
         path = path if path else self.path
         if path is None:
             raise Exception("Define `path` argument")
-        self._compiled.view(path)
+        self._compiled.view(os.fspath(path))
 
     def clear(self):
+        """Erases all the vectors from the index, preserving the space for future insertions."""
         self._compiled.clear()
 
-    def close(self):
-        self._compiled.close()
+    def reset(self):
+        """Erases all members from index, closing files, and returning RAM to OS."""
+        self._compiled.reset()
 
     def copy(self) -> Index:
         result = Index(
@@ -626,7 +753,7 @@ class Index:
         :type max_proposals: int, optional
         :param exact: Controls if underlying `search` should be exact, defaults to False
         :type exact: bool, optional
-        :return: Mapping from labels of `self` to labels of `other`
+        :return: Mapping from keys of `self` to keys of `other`
         :rtype: dict
         """
         return self._compiled.join(
@@ -635,49 +762,71 @@ class Index:
             exact=exact,
         )
 
-    def get_labels(self, offset: int = 0, limit: int = 0) -> np.ndarray:
+    def get_keys(self, offset: int = 0, limit: int = 0) -> np.ndarray:
         if limit == 0:
             limit = 2**63 - 1
-        return self._compiled.get_labels(offset, limit)
+        return self._compiled.get_keys(offset, limit)
 
     @property
-    def labels(self) -> np.ndarray:
-        """Retrieves the labels of all vectors present in `self`
+    def keys(self) -> np.ndarray:
+        """Retrieves the keys of all vectors present in `self`
 
-        :return: Array of labels
+        :return: Array of keys
         :rtype: np.ndarray
         """
-        return self._compiled.labels
+        return self._compiled.keys
 
     def get_vectors(
         self,
-        labels: np.ndarray,
+        keys: np.ndarray,
         dtype: ScalarKind = ScalarKind.F32,
     ) -> np.ndarray:
-        """Retrieves vectors associated with given `labels`
+        """Retrieves vectors associated with given `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 labels])
+        vectors = np.vstack([self._compiled.__getitem__(l, get_dtype) for l in keys])
         view_dtype = _to_numpy_dtype(dtype)
         return vectors.view(view_dtype)
 
     @property
     def vectors(self) -> np.ndarray:
-        return self.get_vectors(self.labels, self.dtype)
+        return self.get_vectors(self.keys, self.dtype)
 
     @property
     def max_level(self) -> int:
         return self._compiled.max_level
 
     @property
-    def levels_stats(self) -> IndexStats:
+    def levels_stats(self) -> _CompiledIndexStats:
+        """Get the accumulated statistics for the entire multi-level graph.
+
+        :return: Statistics for the entire multi-level graph.
+        :rtype: _CompiledIndexStats
+
+        Statistics:
+            - ``nodes`` (int): The number of nodes in that level.
+            - ``edges`` (int): The number of edges in that level.
+            - ``max_edges`` (int): The maximum possible number of edges in that level.
+            - ``allocated_bytes`` (int): The amount of allocated memory for that level.
+        """
         return self._compiled.levels_stats
 
-    def level_stats(self, level: int) -> IndexStats:
+    def level_stats(self, level: int) -> _CompiledIndexStats:
+        """Get statistics for one level of the index - one graph.
+
+        :return: Statistics for one level of the index - one graph.
+        :rtype: _CompiledIndexStats
+
+        Statistics:
+            - ``nodes`` (int): The number of nodes in that level.
+            - ``edges`` (int): The number of edges in that level.
+            - ``max_edges`` (int): The maximum possible number of edges in that level.
+            - ``allocated_bytes`` (int): The amount of allocated memory for that level.
+        """
         return self._compiled.level_stats(level)
 
     def __repr__(self) -> str:
@@ -711,3 +860,146 @@ class Index:
                 *level_stats,
             ]
         )
+
+
+class Indexes:
+    def __init__(
+        self,
+        indexes: Iterable[Index] = [],
+        paths: Iterable[os.PathLike] = [],
+        view: bool = False,
+        threads: int = 0,
+    ) -> None:
+        self._compiled = _CompiledIndexes()
+        for index in indexes:
+            self._compiled.add(index._compiled)
+        self._compiled.add_paths(paths, view=view, threads=threads)
+
+    def add(self, index: Index):
+        self._compiled.add(index._compiled)
+
+    def __len__(self) -> int:
+        return self._compiled.__len__()
+
+    def search(
+        self,
+        vectors,
+        k: int = 10,
+        *,
+        threads: int = 0,
+        exact: bool = False,
+    ):
+        return _search_in_compiled(
+            compiled=self._compiled,
+            vectors=vectors,
+            k=k,
+            exact=exact,
+            threads=threads,
+            log=False,
+            batch_size=None,
+        )
+
+
+def search(
+    dataset: np.ndarray,
+    query: np.ndarray,
+    k: int = 10,
+    metric: Union[str, MetricKind, CompiledMetric] = MetricKind.Cos,
+    *,
+    exact: bool = False,
+    threads: int = 0,
+    log: Union[str, bool] = False,
+    batch_size: int = 0,
+) -> Union[Matches, BatchMatches]:
+    """Shortcut for search, that can avoid index construction. Particularly useful for
+    tiny datasets, where brute-force exact search works fast enough.
+
+    :param dataset: Row-major matrix.
+    :type dataset: np.ndarray
+    :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 metric: Distance function, defaults to MetricKind.Cos
+    :type metric: Union[MetricKind, Callable, str], optional
+        Kind of the distance function, or the Numba `cfunc` JIT-compiled object.
+        Possible `MetricKind` values: IP, Cos, L2sq, Haversine, Pearson,
+        Hamming, Tanimoto, Sorensen.
+
+    :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
+    :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
+
+    :return: Matches for one or more queries
+    :rtype: Union[Matches, BatchMatches]
+    """
+    assert dataset.ndim == 2, "Dataset must be a matrix, with a vector in each row"
+
+    if not exact:
+        index = Index(
+            dataset.shape[1],
+            metric=metric,
+            dtype=dataset.dtype,
+        )
+        index.add(
+            None,
+            dataset,
+            threads=threads,
+            log=log,
+            batch_size=batch_size,
+        )
+        return index.search(
+            query,
+            k,
+            threads=threads,
+            log=log,
+            batch_size=batch_size,
+        )
+
+    metric = _normalize_metric(metric)
+    if isinstance(metric, MetricKind):
+        metric_kind = metric
+        metric_pointer = 0
+        metric_signature = MetricSignature.ArrayArraySize
+    elif isinstance(metric, CompiledMetric):
+        metric_kind = metric.kind
+        metric_pointer = metric.pointer
+        metric_signature = metric.signature
+    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)
+
+            return _exact_search(dataset, query, k, **kwargs)
+
+    return _search_in_compiled(
+        compiled=WrappedDataset(),
+        vectors=query,
+        k=k,
+        threads=threads,
+        exact=True,
+        log=log,
+        batch_size=batch_size,
+    )