deskit 1.1.0__tar.gz → 1.2.0__tar.gz

{deskit-1.1.0/src/deskit.egg-info → deskit-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deskit
-Version: 1.1.0
+Version: 1.2.0
 Summary: A Python library for Dynamic Ensemble Selection
 Author: Tikhon Vodyanov
 License-Expression: MIT

{deskit-1.1.0 → deskit-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deskit"
-version = "1.1.0"
+version = "1.2.0"
 description = "A Python library for Dynamic Ensemble Selection"
 readme = "README.md"
 license = "MIT"

{deskit-1.1.0 → deskit-1.2.0}/src/deskit/_config.py

@@ -88,7 +88,7 @@ def resolve_metric(metric):
 # Neighbor finder construction
 # ---------------------------------------------------------------------------
 
-def make_finder(preset, k, finder=None, **kwargs):
+def make_finder(preset, k, finder=None, distance_metric='euclidean', **kwargs):
     """
     Create a NeighborFinder from a preset name or custom finder string.
 
@@ -100,6 +100,17 @@ def make_finder(preset, k, finder=None, **kwargs):
         Number of neighbors.
     finder : str, optional
         Required when preset='custom'. One of 'knn', 'faiss', 'annoy', 'hnsw'.
+    distance_metric : str
+        Distance function to use. Default: 'euclidean'. See
+        neighbors.list_distance_metrics() for all options and per-backend
+        availability.
+
+        Quick guide:
+          'euclidean'  — Best default for most tabular data.
+          'manhattan'  — More robust to outliers; good for moderate-to-high dims.
+          'chebyshev'  — Max abs diff; use preset='exact' (KNN only).
+          'minkowski'  — L1/L2 generalisation; use preset='exact' (KNN only).
+          'cosine'     — Direction-based; ideal for embeddings (NLP, vision).
     **kwargs
         Forwarded to the finder constructor (e.g. index_type, n_probes).
     """
@@ -107,7 +118,7 @@ def make_finder(preset, k, finder=None, **kwargs):
         if finder is None:
             raise ValueError("Must specify 'finder' when using preset='custom'.")
         finder_type = finder.lower()
-        finder_kwargs = {'k': k, **kwargs}
+        finder_kwargs = {'k': k, 'distance_metric': distance_metric, **kwargs}
     else:
         if preset not in SPEED_PRESETS:
             raise ValueError(
@@ -117,7 +128,7 @@ def make_finder(preset, k, finder=None, **kwargs):
             )
         config = SPEED_PRESETS[preset]
         finder_type = config['finder']
-        finder_kwargs = {**config['kwargs'], 'k': k, **kwargs}
+        finder_kwargs = {**config['kwargs'], 'k': k, 'distance_metric': distance_metric, **kwargs}
 
     if finder_type == 'knn':
         from deskit.neighbors import KNNNeighborFinder

{deskit-1.1.0 → deskit-1.2.0}/src/deskit/des/dewsi.py

@@ -35,12 +35,15 @@ class DEWSI(KNNBase):
         (min-metrics) and 1.0 for classification (max-metrics) at predict time.
     preset : str
         Neighbor search preset. Default: 'balanced'. See list_presets().
+    distance_metric : str
+        Distance function to use for neighbor search. Default: 'euclidean'. See
+        neighbors.list_distance_metrics() for all options and per-backend availability.
     """
 
     def __init__(self, task, metric='mae', mode='min', k=10,
-                 threshold=0.5, temperature=None, preset='balanced', **kwargs):
+                 threshold=0.5, temperature=None, preset='balanced', distance_metric='euclidian', **kwargs):
         metric_name, metric_fn = resolve_metric(metric)
-        finder = make_finder(preset, k, **kwargs)
+        finder = make_finder(preset, k, distance_metric=distance_metric, **kwargs)
         super().__init__(metric=metric_fn, mode=mode, neighbor_finder=finder, task=task)
         self.task = task
         self.threshold = threshold

{deskit-1.1.0 → deskit-1.2.0}/src/deskit/des/dewsiv.py

@@ -37,12 +37,15 @@ class DEWSIV(KNNBase):
         Defaults to 0.5 for min-metrics, 1.0 otherwise.
     preset : str
         Neighbour search preset. Default: 'balanced'. See list_presets().
+    distance_metric : str
+        Distance function to use for neighbor search. Default: 'euclidean'. See
+        neighbors.list_distance_metrics() for all options and per-backend availability.
     """
 
     def __init__(self, task, metric='mae', mode='min', k=10,
-                 threshold=0.5, temperature=None, preset='balanced', **kwargs):
+                 threshold=0.5, temperature=None, preset='balanced', distance_metric='euclidian', **kwargs):
         metric_name, metric_fn = resolve_metric(metric)
-        finder = make_finder(preset, k, **kwargs)
+        finder = make_finder(preset, k, distance_metric=distance_metric, **kwargs)
 
         self._use_signed  = metric_name in _SIGNED_METRICS
         self._metric_name = metric_name

{deskit-1.1.0 → deskit-1.2.0}/src/deskit/des/dewst.py

@@ -40,11 +40,14 @@ class DEWST(KNNBase):
         the sample falls back to DEWS-I scoring for that model. Default: 0.7.
     preset : str
         Neighbour search preset. Default: 'balanced'. See list_presets().
+    distance_metric : str
+        Distance function to use for neighbor search. Default: 'euclidean'. See
+        neighbors.list_distance_metrics() for all options and per-backend availability.
     """
 
     def __init__(self, task, metric='mae', mode='min', k=10,
                  threshold=0.5, temperature=None, r2_threshold=0.7,
-                 preset='balanced', **kwargs):
+                 preset='balanced', distance_metric='euclidean', **kwargs):
         metric_name, metric_fn = resolve_metric(metric)
         finder = make_finder(preset, k, **kwargs)
 

{deskit-1.1.0 → deskit-1.2.0}/src/deskit/des/dewsu.py

@@ -31,10 +31,13 @@ class DEWSU(KNNBase):
         (min-metrics) and 1.0 for classification (max-metrics) at predict time.
     preset : str
         Neighbor search preset. Default: 'balanced'. See list_presets().
+    distance_metric : str
+        Distance function to use for neighbor search. Default: 'euclidean'. See
+        neighbors.list_distance_metrics() for all options and per-backend availability.
     """
 
     def __init__(self, task, metric='mae', mode='min', k=10,
-                 threshold=0.5, temperature=None, preset='balanced', **kwargs):
+                 threshold=0.5, temperature=None, preset='balanced', distance_metric='euclidean', **kwargs):
         metric_name, metric_fn = resolve_metric(metric)
         finder = make_finder(preset, k, **kwargs)
         super().__init__(metric=metric_fn, mode=mode, neighbor_finder=finder, task=task)

{deskit-1.1.0 → deskit-1.2.0}/src/deskit/des/dewsv.py

@@ -37,12 +37,15 @@ class DEWSV(KNNBase):
         Defaults to 0.5 for min-metrics, 1.0 otherwise.
     preset : str
         Neighbour search preset. Default: 'balanced'. See list_presets().
+    distance_metric : str
+        Distance function to use for neighbor search. Default: 'euclidean'. See
+        neighbors.list_distance_metrics() for all options and per-backend availability. 
     """
 
     def __init__(self, task, metric='mae', mode='min', k=10,
-                 threshold=0.5, temperature=None, preset='balanced', **kwargs):
+                 threshold=0.5, temperature=None, preset='balanced', distance_metric='euclidean', **kwargs):
         metric_name, metric_fn = resolve_metric(metric)
-        finder = make_finder(preset, k, **kwargs)
+        finder = make_finder(preset, k, distance_metric=distance_metric, **kwargs)
 
         self._use_signed = metric_name in _SIGNED_METRICS
         self._metric_name = metric_name

{deskit-1.1.0 → deskit-1.2.0}/src/deskit/des/knorae.py

@@ -26,10 +26,13 @@ class KNORAE(KNNBase):
         Regression: use 1.0.
     preset : str
         Neighbor search preset. Default: 'balanced'. See list_presets().
+    distance_metric : str
+        Distance function to use for neighbor search. Default: 'euclidean'. See
+        neighbors.list_distance_metrics() for all options and per-backend availability.
     """
 
     def __init__(self, task, metric='mae', mode='min', k=10,
-                 threshold=0.5, preset='balanced', **kwargs):
+                 threshold=0.5, preset='balanced', distance_metric='euclidean', **kwargs):
         metric_name, metric_fn = resolve_metric(metric)
         finder = make_finder(preset, k, **kwargs)
         super().__init__(metric=metric_fn, mode=mode, neighbor_finder=finder, task=task)

{deskit-1.1.0 → deskit-1.2.0}/src/deskit/des/knoraiu.py

@@ -27,10 +27,13 @@ class KNORAIU(KNNBase):
         Regression: use 1.0.
     preset : str
         Neighbor search preset. Default: 'balanced'. See list_presets().
+    distance_metric : str
+        Distance function to use for neighbor search. Default: 'euclidean'. See
+        neighbors.list_distance_metrics() for all options and per-backend availability.
     """
 
     def __init__(self, task, metric='mae', mode='min', k=10,
-                 threshold=0.5, preset='balanced', **kwargs):
+                 threshold=0.5, preset='balanced', distance_metric='euclidean', **kwargs):
         metric_name, metric_fn = resolve_metric(metric)
         finder = make_finder(preset, k, **kwargs)
         super().__init__(metric=metric_fn, mode=mode, neighbor_finder=finder, task=task)

{deskit-1.1.0 → deskit-1.2.0}/src/deskit/des/knorau.py

@@ -27,10 +27,13 @@ class KNORAU(KNNBase):
         Regression: use 1.0.
     preset : str
         Neighbor search preset. Default: 'balanced'. See list_presets().
+    distance_metric : str
+        Distance function to use for neighbor search. Default: 'euclidean'. See
+        neighbors.list_distance_metrics() for all options and per-backend availability.
     """
 
     def __init__(self, task, metric='mae', mode='min', k=10,
-                 threshold=0.5, preset='balanced', **kwargs):
+                 threshold=0.5, preset='balanced', distance_metric='euclidean', **kwargs):
         metric_name, metric_fn = resolve_metric(metric)
         finder = make_finder(preset, k, **kwargs)
         super().__init__(metric=metric_fn, mode=mode, neighbor_finder=finder, task=task)

{deskit-1.1.0 → deskit-1.2.0}/src/deskit/des/lwsei.py

@@ -19,9 +19,12 @@ class LWSEI(PredictBase):
         Neighbourhood size. Default: 10.
     preset : str
         Neighbour search preset. Default: 'balanced'. See list_presets().
+    distance_metric : str
+        Distance function to use for neighbor search. Default: 'euclidean'. See
+        neighbors.list_distance_metrics() for all options and per-backend availability.
     """
 
-    def __init__(self, task, k=10, preset='balanced', **kwargs):
+    def __init__(self, task, k=10, preset='balanced', distance_metric='euclidean', **kwargs):
         self.task    = task
         self.k       = k
         self._finder = make_finder(preset, k, **kwargs)

{deskit-1.1.0 → deskit-1.2.0}/src/deskit/des/lwseu.py

@@ -19,9 +19,12 @@ class LWSEU(PredictBase):
         Neighbourhood size. Default: 10.
     preset : str
         Neighbour search preset. Default: 'balanced'. See list_presets().
+    distance_metric : str
+        Distance function to use for neighbor search. Default: 'euclidean'. See
+        neighbors.list_distance_metrics() for all options and per-backend availability.
     """
 
-    def __init__(self, task, k=10, preset='balanced', **kwargs):
+    def __init__(self, task, k=10, preset='balanced', distance_metric='euclidean', **kwargs):
         self.task    = task
         self.k       = k
         self._finder = make_finder(preset, k, **kwargs)

{deskit-1.1.0 → deskit-1.2.0}/src/deskit/des/ola.py

@@ -22,13 +22,16 @@ class OLA(KNNBase):
         Neighborhood size. Default: 10.
     preset : str
         Neighbor search preset. Default: 'balanced'. See list_presets().
+    distance_metric : str
+        Distance function to use for neighbor search. Default: 'euclidean'. See
+        neighbors.list_distance_metrics() for all options and per-backend availability.
     """
 
     def __init__(self, task, metric='mae', mode='min', k=10,
-                 preset='balanced', threshold=None, **kwargs):
+                 preset='balanced', threshold=None, distance_metric='euclidean', **kwargs):
         metric_name, metric_fn = resolve_metric(metric)
         finder = make_finder(preset, k, **kwargs)
-        super().__init__(metric=metric_fn, mode=mode, neighbor_finder=finder, , task=task)
+        super().__init__(metric=metric_fn, mode=mode, neighbor_finder=finder, task=task)
         self.task = task
         self._metric_name = metric_name
 

{deskit-1.1.0 → deskit-1.2.0}/src/deskit/neighbors.py

@@ -5,6 +5,82 @@ import warnings
 _FAISS_MIN_SAMPLES_PER_CELL = 40
 
 
+# ---------------------------------------------------------------------------
+# Distance metric registry
+# ---------------------------------------------------------------------------
+
+# Metrics supported by each backend.
+# 'euclidean' is the universal default and always available.
+#
+# Choosing a distance metric:
+#   euclidean  – The standard L2 norm. Best default for most tabular data.
+#   manhattan  – L1 norm (sum of absolute differences). More robust to outliers
+#                and tends to work better in moderately high-dimensional spaces
+#                because it doesn't square large differences.
+#   chebyshev  – L∞ norm (maximum absolute difference across features). Useful
+#                when a single feature dominating the distance is acceptable;
+#                common in game-grid / chess-style distance problems.
+#   minkowski  – Generalisation of L1/L2 (controlled by p). p=1 → manhattan,
+#                p=2 → euclidean. Use when you want to tune between them.
+#   cosine     – Angle between vectors, ignoring magnitude. Excellent for
+#                embeddings (text, image, audio) where direction matters more
+#                than raw scale.
+
+# Metrics that every backend supports natively.
+_UNIVERSAL_METRICS = {'euclidean', 'manhattan', 'chebyshev', 'minkowski', 'cosine'}
+
+# Per-backend metric availability.
+# KNN (sklearn) supports all scipy metrics — this is the complete curated list.
+_KNN_METRICS = _UNIVERSAL_METRICS | {'correlation', 'hamming', 'canberra', 'braycurtis'}
+
+# FAISS only has built-in L2 and inner-product (cosine via normalization).
+# All others fall back to a manual compute-then-search path.
+_FAISS_NATIVE_METRICS = {'euclidean', 'cosine'}
+_FAISS_METRICS = _UNIVERSAL_METRICS  # remainder handled via sklearn fallback
+
+# Annoy metric names (library-specific).
+_ANNOY_METRIC_MAP = {
+    'euclidean': 'euclidean',
+    'manhattan': 'manhattan',
+    'cosine':    'angular',
+    'hamming':   'hamming',
+    # chebyshev and minkowski are not natively supported; we warn the user.
+}
+_ANNOY_METRICS = set(_ANNOY_METRIC_MAP)
+
+# HNSW (hnswlib) space names.
+_HNSW_METRIC_MAP = {
+    'euclidean': 'l2',
+    'cosine':    'cosine',
+    # Others not natively supported in hnswlib; we warn and fall back to l2.
+}
+_HNSW_METRICS = _UNIVERSAL_METRICS  # partial — see fit() for fallback note
+
+# All metrics callable from the public API.
+ALL_METRICS = _KNN_METRICS
+
+
+def list_distance_metrics():
+    """Print all available distance metrics with per-backend availability."""
+    print("\nAvailable Distance Metrics:")
+    print("=" * 70)
+    rows = [
+        ("euclidean",  "Default. L2 norm. Best for most tabular data.",                       "all"),
+        ("manhattan",  "L1 norm. More robust to outliers; good for high-dim data.",            "all"),
+        ("chebyshev",  "L∞ norm. Max absolute diff across features.",                         "KNN only (exact preset)"),
+        ("minkowski",  "Generalises L1/L2 via p-param. Set minkowski_p=<float>.",             "KNN only (exact preset)"),
+        ("cosine",     "Angle between vectors. Ideal for embeddings (NLP, vision).",           "all"),
+        ("correlation","Pearson correlation distance. Good for time series.",                  "KNN only (exact preset)"),
+        ("hamming",    "Fraction of differing components. For binary/categorical data.",       "KNN, Annoy"),
+        ("canberra",   "Weighted L1. Sensitive to small values near zero.",                    "KNN only (exact preset)"),
+        ("braycurtis", "Normalised L1 bounded to [0,1]. Ecological data.",                    "KNN only (exact preset)"),
+    ]
+    for name, desc, backends in rows:
+        print(f"\n  {name:<14}  {desc}")
+        print(f"  {'':14}  Backends: {backends}")
+    print("\n" + "=" * 70)
+
+
 class NeighborFinder:
     """Base class for neighbor search backends."""
 
@@ -16,12 +92,37 @@ class NeighborFinder:
 
 
 class KNNNeighborFinder(NeighborFinder):
-    """Exact nearest neighbors via sklearn NearestNeighbors."""
-
-    def __init__(self, k=10, **kwargs):
+    """
+    Exact nearest neighbors via sklearn NearestNeighbors.
+
+    Supports all distance metrics in deskit (euclidean, manhattan, chebyshev,
+    minkowski, cosine, correlation, hamming, canberra, braycurtis).
+    """
+
+    def __init__(self, k=10, distance_metric='euclidean', minkowski_p=2, **kwargs):
+        """
+        Parameters
+        ----------
+        k : int
+            Number of neighbors.
+        distance_metric : str
+            Distance function to use. One of the metrics returned by
+            list_distance_metrics(). Default: 'euclidean'.
+        minkowski_p : float
+            The p-parameter for the Minkowski metric (p=1 → manhattan,
+            p=2 → euclidean). Ignored for all other metrics.
+        """
         if k <= 0:
             raise ValueError(f"k must be positive, got k={k}")
+        metric = distance_metric.lower()
+        if metric not in _KNN_METRICS:
+            raise ValueError(
+                f"distance_metric='{distance_metric}' is not supported by KNNNeighborFinder. "
+                f"Available: {sorted(_KNN_METRICS)}."
+            )
         self.n_neighbors = k
+        self.distance_metric = metric
+        self.minkowski_p = minkowski_p
         self.kwargs = kwargs
         self.model = None
 
@@ -33,7 +134,15 @@ class KNNNeighborFinder(NeighborFinder):
                 f"Cannot find {self.n_neighbors} neighbors in a dataset with only "
                 f"{X.shape[0]} samples. Reduce k to at most {X.shape[0]}."
             )
-        self.model = NearestNeighbors(n_neighbors=self.n_neighbors, **self.kwargs)
+        metric_kwargs = {}
+        if self.distance_metric == 'minkowski':
+            metric_kwargs['p'] = self.minkowski_p
+        self.model = NearestNeighbors(
+            n_neighbors=self.n_neighbors,
+            metric=self.distance_metric,
+            metric_params=metric_kwargs if metric_kwargs else None,
+            **self.kwargs,
+        )
         self.model.fit(X)
         return self
 
@@ -48,12 +157,34 @@ class KNNNeighborFinder(NeighborFinder):
 
 
 class FaissNeighborFinder(NeighborFinder):
-    """Approximate nearest neighbors via FAISS (flat, IVF, or HNSW index)."""
+    """
+    Approximate nearest neighbors via FAISS (flat, IVF, or HNSW index).
+
+    Natively supports 'euclidean' and 'cosine'. All other metrics in
+    _UNIVERSAL_METRICS fall back to a sklearn-based exact search with a
+    warning, so you can still use them without switching presets.
+    """
 
     def __init__(self, k=10, index_type='flat', n_cells=None, n_probes=50,
-                 hnsw_M=32, hnsw_efConstruction=400, hnsw_efSearch=200):
+                 hnsw_M=32, hnsw_efConstruction=400, hnsw_efSearch=200,
+                 distance_metric='euclidean'):
+        """
+        Parameters
+        ----------
+        distance_metric : str
+            'euclidean' (default) or 'cosine'. Other metrics fall back to
+            exact sklearn search with a warning — use preset='exact' to avoid
+            the overhead.
+        """
         if k <= 0:
             raise ValueError(f"k must be positive, got k={k}")
+        metric = distance_metric.lower()
+        if metric not in _FAISS_METRICS:
+            raise ValueError(
+                f"distance_metric='{distance_metric}' is not supported by FaissNeighborFinder. "
+                f"Available: {sorted(_FAISS_METRICS)}. "
+                f"For other metrics use preset='exact' (KNNNeighborFinder)."
+            )
         self.n_neighbors = k
         self.index_type = index_type.lower()
         self.n_cells = n_cells
@@ -61,7 +192,9 @@ class FaissNeighborFinder(NeighborFinder):
         self.hnsw_M = hnsw_M
         self.hnsw_efConstruction = hnsw_efConstruction
         self.hnsw_efSearch = hnsw_efSearch
+        self.distance_metric = metric
         self.index_ = None
+        self._fallback_finder = None   # used for non-native metrics
         self._check_availability()
 
     def _check_availability(self):
@@ -71,6 +204,13 @@ class FaissNeighborFinder(NeighborFinder):
         except ImportError:
             raise ImportError("FAISS not found. Install with: pip install faiss-cpu")
 
+    @staticmethod
+    def _l2_normalize(X):
+        """Row-wise L2 normalisation in-place (for cosine similarity)."""
+        norms = np.linalg.norm(X, axis=1, keepdims=True)
+        norms = np.where(norms == 0, 1.0, norms)
+        return X / norms.astype(np.float32)
+
     def fit(self, X):
         X = np.atleast_2d(X).astype(np.float32)
         n_samples, dim = X.shape
@@ -81,6 +221,24 @@ class FaissNeighborFinder(NeighborFinder):
                 f"{n_samples} samples. Reduce k to at most {n_samples}."
             )
 
+        # Non-native metrics: delegate entirely to KNNNeighborFinder.
+        if self.distance_metric not in _FAISS_NATIVE_METRICS:
+            warnings.warn(
+                f"distance_metric='{self.distance_metric}' is not natively supported by "
+                f"FAISS. Falling back to exact sklearn KNN for this metric. "
+                f"Use preset='exact' to avoid this overhead.",
+                UserWarning,
+            )
+            self._fallback_finder = KNNNeighborFinder(
+                k=self.n_neighbors, distance_metric=self.distance_metric
+            )
+            self._fallback_finder.fit(X)
+            return self
+
+        # Cosine similarity: normalise all vectors, then use inner-product index.
+        if self.distance_metric == 'cosine':
+            X = self._l2_normalize(X)
+
         if self.index_type == 'flat':
             if dim <= 2:
                 warnings.warn(
@@ -88,14 +246,16 @@ class FaissNeighborFinder(NeighborFinder):
                     f"Consider KNNNeighborFinder for low-dimensional data.",
                     UserWarning
                 )
-            self.index_ = self.faiss.IndexFlatL2(dim)
+            if self.distance_metric == 'cosine':
+                self.index_ = self.faiss.IndexFlatIP(dim)   # inner product on normalised vecs
+            else:
+                self.index_ = self.faiss.IndexFlatL2(dim)
             self.index_.add(X)
 
         elif self.index_type == 'ivf':
             if self.n_cells is None:
                 self.n_cells = min(int(np.sqrt(n_samples)), 4096)
 
-            # Reduce n_cells if dataset is too small
             min_required = self.n_cells * _FAISS_MIN_SAMPLES_PER_CELL
             if n_samples < min_required:
                 safe_cells = max(1, n_samples // _FAISS_MIN_SAMPLES_PER_CELL)
@@ -121,8 +281,14 @@ class FaissNeighborFinder(NeighborFinder):
                     UserWarning
                 )
 
-            quantizer = self.faiss.IndexFlatL2(dim)
-            self.index_ = self.faiss.IndexIVFFlat(quantizer, dim, self.n_cells)
+            if self.distance_metric == 'cosine':
+                quantizer = self.faiss.IndexFlatIP(dim)
+                self.index_ = self.faiss.IndexIVFFlat(
+                    quantizer, dim, self.n_cells, self.faiss.METRIC_INNER_PRODUCT
+                )
+            else:
+                quantizer = self.faiss.IndexFlatL2(dim)
+                self.index_ = self.faiss.IndexIVFFlat(quantizer, dim, self.n_cells)
             self.index_.train(X)
             self.index_.add(X)
             self.index_.nprobe = effective_probes
@@ -151,21 +317,53 @@ class FaissNeighborFinder(NeighborFinder):
         X = np.atleast_2d(X).astype(np.float32)
         if X.shape[0] == 0:
             return np.empty((0, k), dtype=np.float32), np.empty((0, k), dtype=np.int64)
-        distances, indices = self.index_.search(X, k)
-        # FAISS returns squared L2; clamp to 0 before sqrt
-        return np.sqrt(np.maximum(distances, 0)), indices
 
+        # Non-native metric fallback.
+        if self._fallback_finder is not None:
+            return self._fallback_finder.kneighbors(X, k=k)
+
+        if self.distance_metric == 'cosine':
+            X = self._l2_normalize(X)
+            scores, indices = self.index_.search(X, k)
+            # Inner product on normalised vectors: similarity ∈ [-1, 1].
+            # Convert to a proper distance (0 = identical, 2 = opposite).
+            distances = 1.0 - scores
+        else:
+            distances, indices = self.index_.search(X, k)
+            # FAISS returns squared L2; clamp to 0 before sqrt.
+            distances = np.sqrt(np.maximum(distances, 0))
+
+        return distances.astype(np.float32), indices
 
-class AnnoyNeighborFinder(NeighborFinder):
-    """Approximate nearest neighbors via Annoy."""
 
-    def __init__(self, k=10, n_trees=100, metric='euclidean', search_k=-1):
+class AnnoyNeighborFinder(NeighborFinder):
+    """
+    Approximate nearest neighbors via Annoy.
+
+    Supports: euclidean, manhattan, cosine, hamming.
+    chebyshev and minkowski are not available in Annoy — use preset='exact' for those.
+    """
+
+    def __init__(self, k=10, n_trees=100, distance_metric='euclidean', search_k=-1):
+        """
+        Parameters
+        ----------
+        distance_metric : str
+            One of 'euclidean', 'manhattan', 'cosine', 'hamming'. Default: 'euclidean'.
+        """
         if k <= 0:
             raise ValueError(f"k must be positive, got k={k}")
+        metric = distance_metric.lower()
+        if metric not in _ANNOY_METRICS:
+            raise ValueError(
+                f"distance_metric='{distance_metric}' is not supported by AnnoyNeighborFinder. "
+                f"Available: {sorted(_ANNOY_METRICS)}. "
+                f"For chebyshev or minkowski use preset='exact' (KNNNeighborFinder)."
+            )
         self.k = k
         self.n_trees = n_trees
-        self.metric = metric
-        # Annoy's recommended default; the previous value (n_trees * k * 50)
+        self.distance_metric = metric
+        # Annoy's recommended default
         self.search_k = n_trees * k if search_k == -1 else search_k
         self.index_ = None
         self.n_samples_ = None
@@ -195,12 +393,7 @@ class AnnoyNeighborFinder(NeighborFinder):
                 UserWarning
             )
 
-        metric_map = {
-            'euclidean': 'euclidean', 'l2': 'euclidean',
-            'angular': 'angular',     'cosine': 'angular',
-            'manhattan': 'manhattan', 'hamming': 'hamming', 'dot': 'dot',
-        }
-        self.index_ = self.AnnoyIndex(dim, metric_map.get(self.metric.lower(), 'euclidean'))
+        self.index_ = self.AnnoyIndex(dim, _ANNOY_METRIC_MAP[self.distance_metric])
         for i, vec in enumerate(X):
             self.index_.add_item(i, vec.tolist())
         self.index_.build(self.n_trees)
@@ -244,14 +437,33 @@ class AnnoyNeighborFinder(NeighborFinder):
 
 
 class HNSWNeighborFinder(NeighborFinder):
-    """Approximate nearest neighbors via HNSW (hnswlib or nmslib backend)."""
-
-    def __init__(self, k=10, space='l2', M=32, ef_construction=400,
-                 ef_search=200, backend='hnswlib'):
+    """
+    Approximate nearest neighbors via HNSW (hnswlib or nmslib backend).
+
+    Natively supports 'euclidean' and 'cosine'. Manhattan, chebyshev, and
+    minkowski are not available in hnswlib/nmslib — use preset='exact' for those.
+    """
+
+    def __init__(self, k=10, M=32, ef_construction=400,
+                 ef_search=200, backend='hnswlib', distance_metric='euclidean'):
+        """
+        Parameters
+        ----------
+        distance_metric : str
+            'euclidean' (default) or 'cosine'. Other metrics are not supported
+            natively and will raise an error — use preset='exact' instead.
+        """
         if k <= 0:
             raise ValueError(f"k must be positive, got k={k}")
+        metric = distance_metric.lower()
+        if metric not in _HNSW_METRIC_MAP:
+            raise ValueError(
+                f"distance_metric='{distance_metric}' is not natively supported by "
+                f"HNSWNeighborFinder. Available: {sorted(_HNSW_METRIC_MAP)}. "
+                f"For other metrics use preset='exact' (KNNNeighborFinder)."
+            )
         self.n_neighbors = k
-        self.space = space
+        self.distance_metric = metric
         self.M = M
         self.ef_construction = ef_construction
         self.ef_search = ef_search
@@ -292,7 +504,8 @@ class HNSWNeighborFinder(NeighborFinder):
             )
 
         if self.backend == 'hnswlib':
-            self.index_ = self.hnswlib.Index(space=self.space, dim=dim)
+            space = _HNSW_METRIC_MAP[self.distance_metric]
+            self.index_ = self.hnswlib.Index(space=space, dim=dim)
             self.index_.init_index(
                 max_elements=n_samples, M=self.M, ef_construction=self.ef_construction
             )
@@ -300,10 +513,13 @@ class HNSWNeighborFinder(NeighborFinder):
             self.index_.add_items(X, np.arange(n_samples))
 
         else:  # nmslib
-            space_map = {'l2': 'l2', 'cosine': 'cosinesimil', 'ip': 'negdotprod'}
+            nmslib_space_map = {
+                'euclidean': 'l2',
+                'cosine':    'cosinesimil',
+            }
             self.index_ = self.nmslib.init(
                 method='hnsw',
-                space=space_map.get(self.space, 'l2'),
+                space=nmslib_space_map.get(self.distance_metric, 'l2'),
                 data_type=self.nmslib.DataType.DENSE_VECTOR
             )
             self.index_.addDataPointBatch(X)

{deskit-1.1.0 → deskit-1.2.0/src/deskit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deskit
-Version: 1.1.0
+Version: 1.2.0
 Summary: A Python library for Dynamic Ensemble Selection
 Author: Tikhon Vodyanov
 License-Expression: MIT