wknn_1 0.1.0__tar.gz

wknn_1-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# uv / venv
+.venv/
+uv.lock.bak
+
+# Test / cache
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Saved models produced by examples/tests
+*.npz
+*.pkl
+*.pickle
+model.json
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

wknn_1-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

wknn_1-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrey Ferubko, Oleg Kazakov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wknn_1-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: wknn_1
+Version: 0.1.0
+Summary: scikit-learn compatible weighted k-Nearest-Neighbours regressor
+Project-URL: Homepage, https://example.com/your-username/wknn_1
+Project-URL: Repository, https://example.com/your-username/wknn_1
+Author-email: Your Name <you@example.com>
+License: MIT
+License-File: LICENSE
+Keywords: knn,machine-learning,regression,scikit-learn,weighted-knn
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: <3.15,>=3.8
+Requires-Dist: numpy>=1.21
+Requires-Dist: scikit-learn>=1.0
+Description-Content-Type: text/markdown
+
+# wknn_1
+
+A scikit-learn compatible **weighted k-Nearest-Neighbours regressor**.
+
+> This README documents how to run, develop and deploy the library, with usage
+> examples. A richer version with links to the underlying scientific papers
+> will follow.
+
+## Features
+
+- Drop-in scikit-learn estimator (`BaseEstimator` + `RegressorMixin`): works
+  with `Pipeline`, `clone`, `GridSearchCV`, `get_params`/`set_params`, `score`.
+- Flexible `weights` parameter:
+  - **named** standard functions: `linear` (default), `inverse`/`distance`,
+    `exponential`, `gaussian`, `uniform`;
+  - a **custom callable**;
+  - a **`MixedWeightFunction`** with a *different formula per predictor
+    dimension* (e.g. linear decrease on dim 0, exponential growth on dim 1);
+  - a **per-rank weight vector** (list or ndarray, coerced to numpy).
+- Standard weight functions standardize their inputs internally (centering /
+  scaling / normalization), so they are robust to non-standardized data.
+- Predictors and responses must be `numpy.ndarray`; anything else raises an
+  informative `InvalidInputError`.
+- Save / load trained weights in **npz**, **pickle** and **json** to move a
+  trained model between machines.
+- `refit` for retraining and `delete` for tearing the model down (state +
+  on-disk files + metadata) — handy after training on the wrong data.
+- Fully typed (`py.typed` ships with the package). Python 3.8 – 3.14.
+
+## Install & run (uv)
+
+```bash
+# from the project root, in the uv-managed virtual environment
+uv sync                       # create .venv and install deps + dev tools
+uv run python -c "import wknn_1; print(wknn_1.__version__)"
+```
+
+## Quick start
+
+```python
+import numpy as np
+from wknn_1 import WKNNRegressor
+
+X = np.random.default_rng(0).normal(size=(200, 3))
+y = X @ np.array([2.0, -1.5, 0.5])
+
+model = WKNNRegressor(n_neighbors=8, weights="linear").fit(X[:160], y[:160])
+preds = model.predict(X[160:])
+print(model.score(X[160:], y[160:]))
+```
+
+### Per-dimension (mixed) weighting
+
+```python
+import numpy as np
+from wknn_1 import WKNNRegressor, MixedWeightFunction
+
+mixed = MixedWeightFunction(
+    [lambda d: np.clip(1.0 - d, 0.0, None),  # linear decrease on dim 0
+     lambda d: np.exp(d)],                   # exponential growth on dim 1
+    aggregate="product",
+)
+model = WKNNRegressor(n_neighbors=6, weights=mixed).fit(X2d, y)
+```
+
+### Per-rank weight vector
+
+```python
+# the i-th nearest neighbour always gets weight vec[i]
+model = WKNNRegressor(n_neighbors=4, weights=[1.0, 0.5, 0.25, 0.1]).fit(X, y)
+```
+
+### Custom callable
+
+```python
+def gaussian_kernel(deltas):           # deltas: (..., k, n_features)
+    dist = np.sqrt((deltas ** 2).sum(axis=-1))
+    return np.exp(-(dist ** 2))         # -> (..., k)
+
+model = WKNNRegressor(weights=gaussian_kernel).fit(X, y)
+```
+
+### Save, transfer, load, retrain, delete
+
+```python
+model.save_weights("model.npz")               # or .pkl / .json
+restored = WKNNRegressor().load_weights("model.npz")
+
+model.refit(X_new, y_new)                      # retrain from scratch
+model.delete()                                 # wipe state + files + metadata
+```
+
+> Custom callable weight functions cannot be stored in `npz`/`json`; use
+> `pickle`, or re-supply the callable via `set_params(weights=...)` after load.
+
+### Extending the standard functions
+
+```python
+from wknn_1 import register_weight_function, StandardWeightFunction
+
+register_weight_function(
+    "epanechnikov",
+    lambda: StandardWeightFunction("linear", normalize=True),
+)
+WKNNRegressor(weights="epanechnikov")
+```
+
+## Development
+
+```bash
+uv run ruff check .          # lint
+uv run ruff format .         # format
+uv run pytest                # tests
+```
+
+## Deploy
+
+```bash
+uv build                     # builds sdist + wheel into dist/
+# uv publish                 # later: upload to PyPI after testing
+```
+
+## Project layout
+
+```
+src/wknn_1/
+  estimator.py        WKNNRegressor (composes the mixins below)
+  validation.py       numpy-only input checks
+  preprocessing.py    standardization helpers
+  persistence.py      npz / pickle / json save & load
+  weights/            base, standard, mixed/fixed/rank, registry
+  mixins/             validation / preprocessing / prediction / persistence
+tests/                pytest suite
+```

wknn_1-0.1.0/README.md

@@ -0,0 +1,134 @@
+# wknn_1
+
+A scikit-learn compatible **weighted k-Nearest-Neighbours regressor**.
+
+> This README documents how to run, develop and deploy the library, with usage
+> examples. A richer version with links to the underlying scientific papers
+> will follow.
+
+## Features
+
+- Drop-in scikit-learn estimator (`BaseEstimator` + `RegressorMixin`): works
+  with `Pipeline`, `clone`, `GridSearchCV`, `get_params`/`set_params`, `score`.
+- Flexible `weights` parameter:
+  - **named** standard functions: `linear` (default), `inverse`/`distance`,
+    `exponential`, `gaussian`, `uniform`;
+  - a **custom callable**;
+  - a **`MixedWeightFunction`** with a *different formula per predictor
+    dimension* (e.g. linear decrease on dim 0, exponential growth on dim 1);
+  - a **per-rank weight vector** (list or ndarray, coerced to numpy).
+- Standard weight functions standardize their inputs internally (centering /
+  scaling / normalization), so they are robust to non-standardized data.
+- Predictors and responses must be `numpy.ndarray`; anything else raises an
+  informative `InvalidInputError`.
+- Save / load trained weights in **npz**, **pickle** and **json** to move a
+  trained model between machines.
+- `refit` for retraining and `delete` for tearing the model down (state +
+  on-disk files + metadata) — handy after training on the wrong data.
+- Fully typed (`py.typed` ships with the package). Python 3.8 – 3.14.
+
+## Install & run (uv)
+
+```bash
+# from the project root, in the uv-managed virtual environment
+uv sync                       # create .venv and install deps + dev tools
+uv run python -c "import wknn_1; print(wknn_1.__version__)"
+```
+
+## Quick start
+
+```python
+import numpy as np
+from wknn_1 import WKNNRegressor
+
+X = np.random.default_rng(0).normal(size=(200, 3))
+y = X @ np.array([2.0, -1.5, 0.5])
+
+model = WKNNRegressor(n_neighbors=8, weights="linear").fit(X[:160], y[:160])
+preds = model.predict(X[160:])
+print(model.score(X[160:], y[160:]))
+```
+
+### Per-dimension (mixed) weighting
+
+```python
+import numpy as np
+from wknn_1 import WKNNRegressor, MixedWeightFunction
+
+mixed = MixedWeightFunction(
+    [lambda d: np.clip(1.0 - d, 0.0, None),  # linear decrease on dim 0
+     lambda d: np.exp(d)],                   # exponential growth on dim 1
+    aggregate="product",
+)
+model = WKNNRegressor(n_neighbors=6, weights=mixed).fit(X2d, y)
+```
+
+### Per-rank weight vector
+
+```python
+# the i-th nearest neighbour always gets weight vec[i]
+model = WKNNRegressor(n_neighbors=4, weights=[1.0, 0.5, 0.25, 0.1]).fit(X, y)
+```
+
+### Custom callable
+
+```python
+def gaussian_kernel(deltas):           # deltas: (..., k, n_features)
+    dist = np.sqrt((deltas ** 2).sum(axis=-1))
+    return np.exp(-(dist ** 2))         # -> (..., k)
+
+model = WKNNRegressor(weights=gaussian_kernel).fit(X, y)
+```
+
+### Save, transfer, load, retrain, delete
+
+```python
+model.save_weights("model.npz")               # or .pkl / .json
+restored = WKNNRegressor().load_weights("model.npz")
+
+model.refit(X_new, y_new)                      # retrain from scratch
+model.delete()                                 # wipe state + files + metadata
+```
+
+> Custom callable weight functions cannot be stored in `npz`/`json`; use
+> `pickle`, or re-supply the callable via `set_params(weights=...)` after load.
+
+### Extending the standard functions
+
+```python
+from wknn_1 import register_weight_function, StandardWeightFunction
+
+register_weight_function(
+    "epanechnikov",
+    lambda: StandardWeightFunction("linear", normalize=True),
+)
+WKNNRegressor(weights="epanechnikov")
+```
+
+## Development
+
+```bash
+uv run ruff check .          # lint
+uv run ruff format .         # format
+uv run pytest                # tests
+```
+
+## Deploy
+
+```bash
+uv build                     # builds sdist + wheel into dist/
+# uv publish                 # later: upload to PyPI after testing
+```
+
+## Project layout
+
+```
+src/wknn_1/
+  estimator.py        WKNNRegressor (composes the mixins below)
+  validation.py       numpy-only input checks
+  preprocessing.py    standardization helpers
+  persistence.py      npz / pickle / json save & load
+  weights/            base, standard, mixed/fixed/rank, registry
+  mixins/             validation / preprocessing / prediction / persistence
+tests/                pytest suite
+```

wknn_1-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "wknn_1"
+version = "0.1.0"
+description = "scikit-learn compatible weighted k-Nearest-Neighbours regressor"
+readme = "README.md"
+requires-python = ">=3.8,<3.15"
+license = { text = "MIT" }
+authors = [{ name = "Your Name", email = "you@example.com" }]
+keywords = ["knn", "weighted-knn", "regression", "scikit-learn", "machine-learning"]
+classifiers = [
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "numpy>=1.21",
+    "scikit-learn>=1.0",
+]
+
+[project.urls]
+Homepage = "https://example.com/your-username/wknn_1"
+Repository = "https://example.com/your-username/wknn_1"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.6",
+    "pytest>=7.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/wknn_1"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py38"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "C4",  # comprehensions
+    "SIM", # simplify
+]
+ignore = [
+    "UP006", "UP007", "UP035",  # keep typing.X aliases for 3.8 compatibility
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["B018"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

wknn_1-0.1.0/requirements-dev.txt

@@ -0,0 +1,5 @@
+# Development tooling for wknn_1 (fallback for `uv sync --group dev`).
+# Install on top of requirements.txt:
+#     pip install -r requirements.txt -r requirements-dev.txt
+ruff>=0.6
+pytest>=7.0

wknn_1-0.1.0/requirements.txt

@@ -0,0 +1,13 @@
+iniconfig==2.3.0
+joblib==1.5.3
+narwhals==2.22.0
+numpy==2.4.6
+packaging==26.2
+pluggy==1.6.0
+pygments==2.20.0
+pytest==9.0.3
+ruff==0.15.16
+scikit-learn==1.9.0
+scipy==1.17.1
+threadpoolctl==3.6.0
+-e file:///home/anmr/%D0%A0%D0%B0%D0%B1%D0%BE%D1%87%D0%B8%D0%B9%20%D1%81%D1%82%D0%BE%D0%BB/%D0%BC%D0%BE%D0%B8%20%D0%BB%D0%B0%D0%BF%D0%BE%D0%BD%D1%8C%D0%BA%D0%B8/wknn_1

wknn_1-0.1.0/src/wknn_1/__init__.py

@@ -0,0 +1,46 @@
+"""wknn_1: a scikit-learn compatible weighted k-Nearest-Neighbours regressor.
+
+The public surface is intentionally small. The estimator lives in
+:mod:`wknn_1.estimator`; the weighting machinery lives in :mod:`wknn_1.weights`.
+"""
+
+from __future__ import annotations
+
+from .estimator import WKNNRegressor
+from .exceptions import (
+    InvalidInputError,
+    NotFittedError,
+    PersistenceError,
+    WeightFunctionError,
+    WKNNError,
+)
+from .weights import (
+    BaseWeightFunction,
+    FixedFeatureWeightFunction,
+    MixedWeightFunction,
+    RankWeightFunction,
+    StandardWeightFunction,
+    get_weight_function,
+    list_weight_functions,
+    register_weight_function,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "WKNNRegressor",
+    "BaseWeightFunction",
+    "StandardWeightFunction",
+    "MixedWeightFunction",
+    "FixedFeatureWeightFunction",
+    "RankWeightFunction",
+    "get_weight_function",
+    "register_weight_function",
+    "list_weight_functions",
+    "WKNNError",
+    "InvalidInputError",
+    "NotFittedError",
+    "WeightFunctionError",
+    "PersistenceError",
+    "__version__",
+]

wknn_1-0.1.0/src/wknn_1/_types.py

@@ -0,0 +1,34 @@
+"""Type aliases shared across the package.
+
+We rely on ``from __future__ import annotations`` everywhere so that modern
+typing syntax stays valid as plain strings on Python 3.8. The runtime aliases
+defined here only use constructs available since numpy 1.21.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Sequence, Union
+
+import numpy as np
+import numpy.typing as npt
+
+#: A floating point numpy array (the canonical internal representation).
+FloatArray = npt.NDArray[np.floating]
+
+#: A callable that maps per-dimension distances of one feature column,
+#: shape ``(..., k)``, to per-dimension weights of the same shape.
+DimWeightCallable = Callable[[np.ndarray], np.ndarray]
+
+#: A callable that maps a full deltas tensor, shape ``(..., k, n_features)``,
+#: to neighbour weights of shape ``(..., k)``.
+WeightCallable = Callable[[np.ndarray], np.ndarray]
+
+#: Anything that can be coerced into a 1-D numpy vector.
+VectorLike = Union[np.ndarray, Sequence[float]]
+
+#: Everything the ``weights`` estimator parameter is allowed to be: a name,
+#: a weight-function instance / callable, or a per-rank vector.
+WeightSpec = Union[str, WeightCallable, VectorLike]
+
+#: Supported persistence formats.
+SaveFormat = str  # one of {"npz", "pickle", "json"}

wknn_1-0.1.0/src/wknn_1/estimator.py

@@ -0,0 +1,138 @@
+"""The public estimator: :class:`WKNNRegressor`.
+
+It is assembled from small, single-responsibility mixins plus scikit-learn's
+:class:`~sklearn.base.BaseEstimator` and
+:class:`~sklearn.base.RegressorMixin`. Only this class defines ``__init__``, so
+``get_params`` / ``set_params`` / ``clone`` behave exactly as scikit-learn
+expects.
+
+Method resolution order (left to right): our mixins first, then the
+scikit-learn mixins, with ``BaseEstimator`` last.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from sklearn.base import BaseEstimator, RegressorMixin
+
+from ._types import FloatArray, WeightSpec
+from .exceptions import InvalidInputError, NotFittedError
+from .mixins import (
+    InputValidationMixin,
+    PersistenceMixin,
+    PredictionMixin,
+    PreprocessingMixin,
+)
+
+
+class WKNNRegressor(
+    InputValidationMixin,
+    PreprocessingMixin,
+    PredictionMixin,
+    PersistenceMixin,
+    RegressorMixin,
+    BaseEstimator,
+):
+    """Weighted k-Nearest-Neighbours regressor (1-D targets).
+
+    Parameters
+    ----------
+    n_neighbors:
+        Number of neighbours used for each prediction.
+    weights:
+        How neighbours are weighted. One of:
+
+        * a name, e.g. ``"linear"``, ``"inverse"``, ``"gaussian"``
+          (see :func:`wknn_1.list_weight_functions`);
+        * a :class:`~wknn_1.weights.BaseWeightFunction` instance, including
+          :class:`~wknn_1.weights.MixedWeightFunction` for per-dimension
+          formulas;
+        * any callable mapping deltas ``(..., k, n_features)`` to weights
+          ``(..., k)``;
+        * a length-``n_neighbors`` vector (list or ndarray) of per-rank
+          weights.
+    metric, p:
+        Passed straight to :class:`sklearn.neighbors.NearestNeighbors`.
+    standardize:
+        Standardize predictors (zero mean, unit variance) before neighbour
+        search. Strongly recommended; defaults to ``True``.
+    """
+
+    def __init__(
+        self,
+        n_neighbors: int = 5,
+        *,
+        weights: WeightSpec = "linear",
+        metric: str = "minkowski",
+        p: int = 2,
+        standardize: bool = True,
+    ) -> None:
+        self.n_neighbors = n_neighbors
+        self.weights = weights
+        self.metric = metric
+        self.p = p
+        self.standardize = standardize
+
+    # -- fitting ----------------------------------------------------------
+    def fit(self, X: np.ndarray, y: np.ndarray) -> "WKNNRegressor":
+        """Fit the model on numpy predictors *X* and 1-D responses *y*."""
+        X_arr, y_arr = self._validate_fit_input(X, y)
+        self._check_n_neighbors(X_arr.shape[0])
+        self.n_features_in_ = X_arr.shape[1]
+        self.Xt_ = self._fit_scaler(X_arr)
+        self.y_ = y_arr
+        self._build_index(self.Xt_)
+        # Resolve once so an invalid spec fails at fit time, not predict time.
+        self._resolve_weights()
+        self._deleted = False
+        return self
+
+    def refit(self, X: np.ndarray, y: np.ndarray) -> "WKNNRegressor":
+        """Retrain from scratch on fresh data, discarding previous state.
+
+        Equivalent to clearing the model and calling :meth:`fit` again; kept as
+        an explicit method so retraining reads clearly at call sites.
+        """
+        self._reset_fitted()
+        return self.fit(X, y)
+
+    # -- prediction -------------------------------------------------------
+    def predict(self, X: np.ndarray) -> FloatArray:
+        """Predict 1-D targets for numpy predictors *X*."""
+        self._check_is_fitted()
+        X_arr = self._validate_predict_input(X)
+        self._check_feature_count(X_arr.shape[1])
+        Xt = self._apply_scaler(X_arr)
+        return self._weighted_predict(Xt)
+
+    # -- guards -----------------------------------------------------------
+    def _check_is_fitted(self) -> None:
+        if not self._is_fitted():
+            raise NotFittedError(
+                "This WKNNRegressor is not fitted yet. Call fit (or load_weights) first."
+            )
+
+    def _check_n_neighbors(self, n_samples: int) -> None:
+        if not isinstance(self.n_neighbors, int) or self.n_neighbors < 1:
+            raise InvalidInputError("n_neighbors must be a positive integer.")
+        if self.n_neighbors > n_samples:
+            raise InvalidInputError(
+                f"n_neighbors={self.n_neighbors} exceeds the number of training "
+                f"samples ({n_samples})."
+            )
+
+    def _check_feature_count(self, n_features: int) -> None:
+        if n_features != self.n_features_in_:
+            raise InvalidInputError(
+                f"X has {n_features} features, but the model was fitted with {self.n_features_in_}."
+            )
+
+    def _reset_fitted(self) -> None:
+        for attr in ("Xt_", "y_", "scaler_", "n_features_in_", "_nn_"):
+            if hasattr(self, attr):
+                delattr(self, attr)
+        self._deleted = False
+
+    # -- scikit-learn tags ------------------------------------------------
+    def _more_tags(self) -> dict:  # pragma: no cover - metadata only
+        return {"requires_y": True, "X_types": ["2darray"]}

wknn_1-0.1.0/src/wknn_1/exceptions.py

@@ -0,0 +1,31 @@
+"""Exception types raised across the library.
+
+Everything derives from :class:`WKNNError` so callers can catch the whole
+family with a single ``except``.
+"""
+
+from __future__ import annotations
+
+
+class WKNNError(Exception):
+    """Base class for every error raised by :mod:`wknn_1`."""
+
+
+class InvalidInputError(WKNNError, TypeError):
+    """Raised when predictors/responses are not the expected numpy objects.
+
+    Subclasses :class:`TypeError` as well so existing ``except TypeError``
+    handlers keep working.
+    """
+
+
+class NotFittedError(WKNNError):
+    """Raised when prediction/persistence is attempted before ``fit``."""
+
+
+class WeightFunctionError(WKNNError):
+    """Raised when a weight specification is invalid or returns a bad shape."""
+
+
+class PersistenceError(WKNNError):
+    """Raised when saving/loading model weights fails."""