mlkit 0.0.1__tar.gz → 0.1.0__tar.gz

mlkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nehz
+
+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.

mlkit-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: mlkit
+Version: 0.1.0
+Summary: Machine Learning Toolkit: a small, readable NumPy toolkit with a fit/predict API, classic models, preprocessing and metrics.
+Author: nehz
+License-Expression: MIT
+Keywords: machine learning,regression,classification,clustering,numpy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# mlkit
+
+**Machine Learning Toolkit**: a small, readable machine learning library built on NumPy.
+
+mlkit has the familiar `fit` / `predict` / `transform` estimator interface and a
+handful of classic algorithms, each implemented in a few dozen lines of plain
+NumPy. Use it to learn how the algorithms work, to teach them, or for small
+projects where a large ML stack is too much. NumPy is its only dependency.
+
+## Features
+
+- **Estimator API**: `fit`, `predict`, `transform`, `score`, `get_params` / `set_params`, `clone`
+- **Linear models**: `LinearRegression` (least squares), `Ridge` (L2, closed form), `LogisticRegression` (multinomial, gradient descent, optional L2)
+- **Neighbours**: `KNeighborsClassifier`, `KNeighborsRegressor` (uniform or inverse-distance weights)
+- **Clustering**: `KMeans` (k-means++ seeding, multiple restarts, reproducible via `random_state`)
+- **Preprocessing**: `StandardScaler`, `MinMaxScaler` (both with `inverse_transform`)
+- **Model selection**: `train_test_split`, `KFold`, `cross_val_score`
+- **Metrics**: accuracy, confusion matrix, precision / recall / F1 (binary and macro), MSE, MAE, R²
+- **Datasets**: `make_blobs`, `make_regression` synthetic generators
+- Input validation with clear errors, and `NotFittedError` when an estimator is used before `fit`
+- Type hints throughout (ships `py.typed`)
+
+## Installation
+
+```bash
+pip install mlkit
+```
+
+From a source checkout:
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[test]"
+.venv/bin/python -m pytest
+```
+
+Requires Python 3.9+ and NumPy 1.22+.
+
+## Quickstart
+
+```python
+from mlkit import KMeans, LinearRegression, LogisticRegression, StandardScaler, train_test_split
+from mlkit.datasets import make_blobs, make_regression
+from mlkit.metrics import accuracy_score, r2_score
+
+# Classification: scale the features, then fit a logistic regression
+X, y = make_blobs(n_samples=300, centers=3, random_state=0)
+X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.25, random_state=0)
+
+scaler = StandardScaler().fit(X_train)
+clf = LogisticRegression(learning_rate=0.5, max_iter=2000)
+clf.fit(scaler.transform(X_train), y_train)
+print("accuracy:", accuracy_score(y_test, clf.predict(scaler.transform(X_test))))
+
+# Regression
+X, y, true_coef = make_regression(n_samples=200, n_features=3, noise=0.5, random_state=1)
+reg = LinearRegression().fit(X, y)
+print("R^2:", r2_score(y, reg.predict(X)), "coef:", reg.coef_)
+
+# Clustering
+km = KMeans(n_clusters=3, random_state=0).fit(X_train)
+print("inertia:", km.inertia_, "labels:", km.labels_[:10])
+```
+
+Cross-validation:
+
+```python
+from mlkit import KFold, KNeighborsClassifier, cross_val_score
+
+scores = cross_val_score(KNeighborsClassifier(n_neighbors=5), X_train, y_train,
+                         cv=KFold(n_splits=5, shuffle=True, random_state=0))
+print(scores.mean())
+```
+
+## API overview
+
+All estimators subclass `mlkit.BaseEstimator`. Hyper-parameters are the
+constructor arguments. Learned attributes end in `_` and exist only after
+`fit`. Every `fit` returns `self`. Calling `predict` or `transform` before `fit`
+raises `mlkit.NotFittedError`.
+
+### `mlkit` (top level)
+
+| Name | Description |
+| --- | --- |
+| `BaseEstimator` | Base class with `get_params()`, `set_params(**params)`, and a readable `repr` |
+| `NotFittedError` | Raised when an estimator is used before `fit` |
+| `clone(estimator)` | New unfitted estimator with the same hyper-parameters |
+| `__version__` | `"0.1.0"` |
+
+### `mlkit.linear_model`
+
+| Class | Parameters | Methods | Fitted attributes |
+| --- | --- | --- | --- |
+| `LinearRegression` | `fit_intercept=True` | `fit(X, y)`, `predict(X)`, `score(X, y)` (R²) | `coef_`, `intercept_` |
+| `Ridge` | `alpha=1.0`, `fit_intercept=True` | `fit`, `predict`, `score` (R²) | `coef_`, `intercept_` |
+| `LogisticRegression` | `learning_rate=0.1`, `max_iter=1000`, `tol=1e-6`, `alpha=0.0`, `fit_intercept=True` | `fit`, `predict`, `predict_proba`, `decision_function`, `score` (accuracy) | `classes_`, `coef_` (n_classes × n_features), `intercept_`, `n_iter_` |
+
+### `mlkit.neighbors`
+
+| Name | Parameters | Methods / notes |
+| --- | --- | --- |
+| `KNeighborsClassifier` | `n_neighbors=5`, `weights="uniform"` \| `"distance"` | `fit`, `predict`, `predict_proba`, `kneighbors(X)`, `score` (accuracy); `classes_` |
+| `KNeighborsRegressor` | `n_neighbors=5`, `weights="uniform"` \| `"distance"` | `fit`, `predict`, `kneighbors(X)`, `score` (R²) |
+| `pairwise_distances(A, B)` | | Euclidean distance matrix of shape `(len(A), len(B))` |
+
+### `mlkit.cluster`
+
+| Class | Parameters | Methods | Fitted attributes |
+| --- | --- | --- | --- |
+| `KMeans` | `n_clusters=8`, `n_init=10`, `max_iter=300`, `tol=1e-6`, `random_state=None` | `fit(X)`, `predict(X)`, `fit_predict(X)`, `transform(X)` (distances to centroids) | `cluster_centers_`, `labels_`, `inertia_`, `n_iter_` |
+
+### `mlkit.preprocessing`
+
+| Class | Parameters | Methods | Fitted attributes |
+| --- | --- | --- | --- |
+| `StandardScaler` | `with_mean=True`, `with_std=True` | `fit`, `transform`, `fit_transform`, `inverse_transform` | `mean_`, `scale_` |
+| `MinMaxScaler` | `feature_range=(0.0, 1.0)` | `fit`, `transform`, `fit_transform`, `inverse_transform` | `data_min_`, `data_max_` |
+
+### `mlkit.model_selection`
+
+| Name | Signature |
+| --- | --- |
+| `train_test_split` | `train_test_split(*arrays, test_size=0.25, shuffle=True, random_state=None)` returns `[a_train, a_test, b_train, b_test, ...]` |
+| `KFold` | `KFold(n_splits=5, shuffle=False, random_state=None)`; `.split(X)` yields `(train_idx, test_idx)` |
+| `cross_val_score` | `cross_val_score(estimator, X, y, *, cv=5, scoring=None)` returns an array of per-fold scores (`scoring` is `metric(y_true, y_pred)`; it defaults to `estimator.score`) |
+
+### `mlkit.metrics`
+
+| Function | Notes |
+| --- | --- |
+| `accuracy_score(y_true, y_pred)` | Fraction of exact matches |
+| `confusion_matrix(y_true, y_pred, labels=None)` | `C[i, j]`: true `labels[i]` predicted as `labels[j]` |
+| `precision_score(y_true, y_pred, *, average="binary", pos_label=1)` | `average` is `"binary"` or `"macro"`. A zero denominator gives 0.0 |
+| `recall_score(...)` | Same arguments as `precision_score` |
+| `f1_score(...)` | Same arguments as `precision_score` |
+| `mean_squared_error(y_true, y_pred)` | |
+| `mean_absolute_error(y_true, y_pred)` | |
+| `r2_score(y_true, y_pred)` | Coefficient of determination |
+
+### `mlkit.datasets`
+
+| Function | Returns |
+| --- | --- |
+| `make_blobs(n_samples=100, n_features=2, centers=3, cluster_std=1.0, random_state=None)` | `(X, y)` |
+| `make_regression(n_samples=100, n_features=3, noise=0.0, bias=0.0, random_state=None)` | `(X, y, coef)` |
+
+### `mlkit.base`
+
+Contains the `ClassifierMixin`, `RegressorMixin`, `TransformerMixin` and
+`ClusterMixin` mixins for writing your own estimators, plus the validation
+helpers `check_array`, `check_X_y` and `check_is_fitted`.
+
+## Scope and limitations
+
+mlkit puts clarity ahead of speed. k-NN uses brute-force distances, and
+logistic regression uses plain full-batch gradient descent, so scale your
+features first. It is not a replacement for scikit-learn on large datasets.
+
+## License
+
+MIT

mlkit-0.1.0/README.md

@@ -0,0 +1,162 @@
+# mlkit
+
+**Machine Learning Toolkit**: a small, readable machine learning library built on NumPy.
+
+mlkit has the familiar `fit` / `predict` / `transform` estimator interface and a
+handful of classic algorithms, each implemented in a few dozen lines of plain
+NumPy. Use it to learn how the algorithms work, to teach them, or for small
+projects where a large ML stack is too much. NumPy is its only dependency.
+
+## Features
+
+- **Estimator API**: `fit`, `predict`, `transform`, `score`, `get_params` / `set_params`, `clone`
+- **Linear models**: `LinearRegression` (least squares), `Ridge` (L2, closed form), `LogisticRegression` (multinomial, gradient descent, optional L2)
+- **Neighbours**: `KNeighborsClassifier`, `KNeighborsRegressor` (uniform or inverse-distance weights)
+- **Clustering**: `KMeans` (k-means++ seeding, multiple restarts, reproducible via `random_state`)
+- **Preprocessing**: `StandardScaler`, `MinMaxScaler` (both with `inverse_transform`)
+- **Model selection**: `train_test_split`, `KFold`, `cross_val_score`
+- **Metrics**: accuracy, confusion matrix, precision / recall / F1 (binary and macro), MSE, MAE, R²
+- **Datasets**: `make_blobs`, `make_regression` synthetic generators
+- Input validation with clear errors, and `NotFittedError` when an estimator is used before `fit`
+- Type hints throughout (ships `py.typed`)
+
+## Installation
+
+```bash
+pip install mlkit
+```
+
+From a source checkout:
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[test]"
+.venv/bin/python -m pytest
+```
+
+Requires Python 3.9+ and NumPy 1.22+.
+
+## Quickstart
+
+```python
+from mlkit import KMeans, LinearRegression, LogisticRegression, StandardScaler, train_test_split
+from mlkit.datasets import make_blobs, make_regression
+from mlkit.metrics import accuracy_score, r2_score
+
+# Classification: scale the features, then fit a logistic regression
+X, y = make_blobs(n_samples=300, centers=3, random_state=0)
+X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.25, random_state=0)
+
+scaler = StandardScaler().fit(X_train)
+clf = LogisticRegression(learning_rate=0.5, max_iter=2000)
+clf.fit(scaler.transform(X_train), y_train)
+print("accuracy:", accuracy_score(y_test, clf.predict(scaler.transform(X_test))))
+
+# Regression
+X, y, true_coef = make_regression(n_samples=200, n_features=3, noise=0.5, random_state=1)
+reg = LinearRegression().fit(X, y)
+print("R^2:", r2_score(y, reg.predict(X)), "coef:", reg.coef_)
+
+# Clustering
+km = KMeans(n_clusters=3, random_state=0).fit(X_train)
+print("inertia:", km.inertia_, "labels:", km.labels_[:10])
+```
+
+Cross-validation:
+
+```python
+from mlkit import KFold, KNeighborsClassifier, cross_val_score
+
+scores = cross_val_score(KNeighborsClassifier(n_neighbors=5), X_train, y_train,
+                         cv=KFold(n_splits=5, shuffle=True, random_state=0))
+print(scores.mean())
+```
+
+## API overview
+
+All estimators subclass `mlkit.BaseEstimator`. Hyper-parameters are the
+constructor arguments. Learned attributes end in `_` and exist only after
+`fit`. Every `fit` returns `self`. Calling `predict` or `transform` before `fit`
+raises `mlkit.NotFittedError`.
+
+### `mlkit` (top level)
+
+| Name | Description |
+| --- | --- |
+| `BaseEstimator` | Base class with `get_params()`, `set_params(**params)`, and a readable `repr` |
+| `NotFittedError` | Raised when an estimator is used before `fit` |
+| `clone(estimator)` | New unfitted estimator with the same hyper-parameters |
+| `__version__` | `"0.1.0"` |
+
+### `mlkit.linear_model`
+
+| Class | Parameters | Methods | Fitted attributes |
+| --- | --- | --- | --- |
+| `LinearRegression` | `fit_intercept=True` | `fit(X, y)`, `predict(X)`, `score(X, y)` (R²) | `coef_`, `intercept_` |
+| `Ridge` | `alpha=1.0`, `fit_intercept=True` | `fit`, `predict`, `score` (R²) | `coef_`, `intercept_` |
+| `LogisticRegression` | `learning_rate=0.1`, `max_iter=1000`, `tol=1e-6`, `alpha=0.0`, `fit_intercept=True` | `fit`, `predict`, `predict_proba`, `decision_function`, `score` (accuracy) | `classes_`, `coef_` (n_classes × n_features), `intercept_`, `n_iter_` |
+
+### `mlkit.neighbors`
+
+| Name | Parameters | Methods / notes |
+| --- | --- | --- |
+| `KNeighborsClassifier` | `n_neighbors=5`, `weights="uniform"` \| `"distance"` | `fit`, `predict`, `predict_proba`, `kneighbors(X)`, `score` (accuracy); `classes_` |
+| `KNeighborsRegressor` | `n_neighbors=5`, `weights="uniform"` \| `"distance"` | `fit`, `predict`, `kneighbors(X)`, `score` (R²) |
+| `pairwise_distances(A, B)` | | Euclidean distance matrix of shape `(len(A), len(B))` |
+
+### `mlkit.cluster`
+
+| Class | Parameters | Methods | Fitted attributes |
+| --- | --- | --- | --- |
+| `KMeans` | `n_clusters=8`, `n_init=10`, `max_iter=300`, `tol=1e-6`, `random_state=None` | `fit(X)`, `predict(X)`, `fit_predict(X)`, `transform(X)` (distances to centroids) | `cluster_centers_`, `labels_`, `inertia_`, `n_iter_` |
+
+### `mlkit.preprocessing`
+
+| Class | Parameters | Methods | Fitted attributes |
+| --- | --- | --- | --- |
+| `StandardScaler` | `with_mean=True`, `with_std=True` | `fit`, `transform`, `fit_transform`, `inverse_transform` | `mean_`, `scale_` |
+| `MinMaxScaler` | `feature_range=(0.0, 1.0)` | `fit`, `transform`, `fit_transform`, `inverse_transform` | `data_min_`, `data_max_` |
+
+### `mlkit.model_selection`
+
+| Name | Signature |
+| --- | --- |
+| `train_test_split` | `train_test_split(*arrays, test_size=0.25, shuffle=True, random_state=None)` returns `[a_train, a_test, b_train, b_test, ...]` |
+| `KFold` | `KFold(n_splits=5, shuffle=False, random_state=None)`; `.split(X)` yields `(train_idx, test_idx)` |
+| `cross_val_score` | `cross_val_score(estimator, X, y, *, cv=5, scoring=None)` returns an array of per-fold scores (`scoring` is `metric(y_true, y_pred)`; it defaults to `estimator.score`) |
+
+### `mlkit.metrics`
+
+| Function | Notes |
+| --- | --- |
+| `accuracy_score(y_true, y_pred)` | Fraction of exact matches |
+| `confusion_matrix(y_true, y_pred, labels=None)` | `C[i, j]`: true `labels[i]` predicted as `labels[j]` |
+| `precision_score(y_true, y_pred, *, average="binary", pos_label=1)` | `average` is `"binary"` or `"macro"`. A zero denominator gives 0.0 |
+| `recall_score(...)` | Same arguments as `precision_score` |
+| `f1_score(...)` | Same arguments as `precision_score` |
+| `mean_squared_error(y_true, y_pred)` | |
+| `mean_absolute_error(y_true, y_pred)` | |
+| `r2_score(y_true, y_pred)` | Coefficient of determination |
+
+### `mlkit.datasets`
+
+| Function | Returns |
+| --- | --- |
+| `make_blobs(n_samples=100, n_features=2, centers=3, cluster_std=1.0, random_state=None)` | `(X, y)` |
+| `make_regression(n_samples=100, n_features=3, noise=0.0, bias=0.0, random_state=None)` | `(X, y, coef)` |
+
+### `mlkit.base`
+
+Contains the `ClassifierMixin`, `RegressorMixin`, `TransformerMixin` and
+`ClusterMixin` mixins for writing your own estimators, plus the validation
+helpers `check_array`, `check_X_y` and `check_is_fitted`.
+
+## Scope and limitations
+
+mlkit puts clarity ahead of speed. k-NN uses brute-force distances, and
+logistic regression uses plain full-batch gradient descent, so scale your
+features first. It is not a replacement for scikit-learn on large datasets.
+
+## License
+
+MIT

mlkit-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mlkit"
+version = "0.1.0"
+description = "Machine Learning Toolkit: a small, readable NumPy toolkit with a fit/predict API, classic models, preprocessing and metrics."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "nehz" }]
+keywords = ["machine learning", "regression", "classification", "clustering", "numpy"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "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",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = ["numpy>=1.22"]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+mlkit = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

{mlkit-0.0.1 → mlkit-0.1.0}/setup.cfg

@@ -1,4 +1,4 @@
-[egg_info]
-tag_build = 
-tag_date = 0
-
+[egg_info]
+tag_build = 
+tag_date = 0
+

mlkit-0.1.0/src/mlkit/__init__.py

@@ -0,0 +1,35 @@
+"""mlkit - Machine Learning Toolkit.
+
+A small, readable NumPy toolkit with a scikit-learn style ``fit``/``predict``
+interface, classic models, preprocessing, model selection and metrics.
+"""
+
+from . import datasets, metrics
+from .base import BaseEstimator, NotFittedError, clone
+from .cluster import KMeans
+from .linear_model import LinearRegression, LogisticRegression, Ridge
+from .model_selection import KFold, cross_val_score, train_test_split
+from .neighbors import KNeighborsClassifier, KNeighborsRegressor
+from .preprocessing import MinMaxScaler, StandardScaler
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BaseEstimator",
+    "NotFittedError",
+    "clone",
+    "LinearRegression",
+    "Ridge",
+    "LogisticRegression",
+    "KNeighborsClassifier",
+    "KNeighborsRegressor",
+    "KMeans",
+    "StandardScaler",
+    "MinMaxScaler",
+    "train_test_split",
+    "KFold",
+    "cross_val_score",
+    "datasets",
+    "metrics",
+    "__version__",
+]

mlkit-0.1.0/src/mlkit/base.py

@@ -0,0 +1,165 @@
+"""Core estimator interface, mixins and input validation helpers."""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, Optional, Tuple
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+__all__ = [
+    "BaseEstimator",
+    "ClassifierMixin",
+    "RegressorMixin",
+    "TransformerMixin",
+    "ClusterMixin",
+    "NotFittedError",
+    "check_array",
+    "check_X_y",
+    "check_is_fitted",
+    "clone",
+]
+
+
+class NotFittedError(RuntimeError):
+    """Raised when ``predict``/``transform`` is called before ``fit``."""
+
+
+def check_array(X: ArrayLike, *, ensure_2d: bool = True) -> np.ndarray:
+    """Convert ``X`` to a finite float array.
+
+    Args:
+        X: Array-like input.
+        ensure_2d: If True, a 2-D array of shape ``(n_samples, n_features)``
+            is required.
+
+    Returns:
+        A ``float64`` NumPy array.
+
+    Raises:
+        ValueError: If ``X`` is empty, has the wrong number of dimensions or
+            contains NaN/inf values.
+    """
+    arr = np.asarray(X, dtype=float)
+    if ensure_2d and arr.ndim != 2:
+        raise ValueError(f"Expected a 2-D array, got an array with ndim={arr.ndim}.")
+    if arr.size == 0:
+        raise ValueError("Input array is empty.")
+    if not np.all(np.isfinite(arr)):
+        raise ValueError("Input contains NaN or infinity.")
+    return arr
+
+
+def check_X_y(X: ArrayLike, y: ArrayLike, *, y_numeric: bool = False) -> Tuple[np.ndarray, np.ndarray]:
+    """Validate a feature matrix and a 1-D target vector of matching length.
+
+    Args:
+        X: Array-like of shape ``(n_samples, n_features)``.
+        y: Array-like of shape ``(n_samples,)``.
+        y_numeric: If True, ``y`` is converted to ``float64``.
+
+    Returns:
+        The validated ``(X, y)`` pair.
+    """
+    X_arr = check_array(X)
+    y_arr = np.asarray(y, dtype=float if y_numeric else None)
+    if y_arr.ndim != 1:
+        raise ValueError(f"y must be 1-D, got ndim={y_arr.ndim}.")
+    if y_arr.shape[0] != X_arr.shape[0]:
+        raise ValueError(
+            f"X and y have inconsistent lengths: {X_arr.shape[0]} != {y_arr.shape[0]}."
+        )
+    if y_numeric and not np.all(np.isfinite(y_arr)):
+        raise ValueError("y contains NaN or infinity.")
+    return X_arr, y_arr
+
+
+def check_is_fitted(estimator: "BaseEstimator", attribute: str) -> None:
+    """Raise :class:`NotFittedError` if ``estimator`` lacks ``attribute``."""
+    if getattr(estimator, attribute, None) is None:
+        raise NotFittedError(
+            f"This {type(estimator).__name__} instance is not fitted yet. "
+            "Call 'fit' with appropriate arguments first."
+        )
+
+
+class BaseEstimator:
+    """Base class for all estimators.
+
+    Hyper-parameters are the keyword arguments of ``__init__``; they are stored
+    unchanged as attributes. Learned state uses a trailing underscore
+    (e.g. ``coef_``) and only exists after ``fit``.
+    """
+
+    @classmethod
+    def _param_names(cls) -> list:
+        sig = inspect.signature(cls.__init__)
+        return [
+            name
+            for name, p in sig.parameters.items()
+            if name != "self" and p.kind not in (p.VAR_POSITIONAL, p.VAR_KEYWORD)
+        ]
+
+    def get_params(self) -> dict:
+        """Return the estimator's hyper-parameters as a dict."""
+        return {name: getattr(self, name) for name in self._param_names()}
+
+    def set_params(self, **params: Any) -> "BaseEstimator":
+        """Set hyper-parameters and return ``self``.
+
+        Raises:
+            ValueError: If an unknown parameter name is given.
+        """
+        valid = set(self._param_names())
+        for key, value in params.items():
+            if key not in valid:
+                raise ValueError(f"Invalid parameter {key!r} for {type(self).__name__}.")
+            setattr(self, key, value)
+        return self
+
+    def __repr__(self) -> str:
+        args = ", ".join(f"{k}={v!r}" for k, v in self.get_params().items())
+        return f"{type(self).__name__}({args})"
+
+
+def clone(estimator: BaseEstimator) -> BaseEstimator:
+    """Return a new, unfitted estimator with the same hyper-parameters."""
+    return type(estimator)(**estimator.get_params())
+
+
+class ClassifierMixin:
+    """Adds :meth:`score` returning mean accuracy."""
+
+    def score(self, X: ArrayLike, y: ArrayLike) -> float:
+        """Return the accuracy of ``self.predict(X)`` against ``y``."""
+        from .metrics import accuracy_score
+
+        return accuracy_score(y, self.predict(X))  # type: ignore[attr-defined]
+
+
+class RegressorMixin:
+    """Adds :meth:`score` returning the coefficient of determination R^2."""
+
+    def score(self, X: ArrayLike, y: ArrayLike) -> float:
+        """Return the R^2 of ``self.predict(X)`` against ``y``."""
+        from .metrics import r2_score
+
+        return r2_score(y, self.predict(X))  # type: ignore[attr-defined]
+
+
+class TransformerMixin:
+    """Adds :meth:`fit_transform`."""
+
+    def fit_transform(self, X: ArrayLike, y: Optional[ArrayLike] = None) -> np.ndarray:
+        """Fit to ``X`` and return the transformed data."""
+        return self.fit(X, y).transform(X)  # type: ignore[attr-defined]
+
+
+class ClusterMixin:
+    """Adds :meth:`fit_predict`."""
+
+    def fit_predict(self, X: ArrayLike, y: Optional[ArrayLike] = None) -> np.ndarray:
+        """Fit to ``X`` and return the cluster label of each sample."""
+        self.fit(X)  # type: ignore[attr-defined]
+        return self.labels_  # type: ignore[attr-defined]