mlkit 0.1.0__py3-none-any.whl

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/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]

mlkit/cluster.py

@@ -0,0 +1,108 @@
+"""k-means clustering with k-means++ initialisation."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from .base import BaseEstimator, ClusterMixin, check_array, check_is_fitted
+from .neighbors import pairwise_distances
+
+__all__ = ["KMeans"]
+
+
+class KMeans(BaseEstimator, ClusterMixin):
+    """Lloyd's k-means with k-means++ seeding and multiple restarts.
+
+    Args:
+        n_clusters: Number of clusters ``k``.
+        n_init: Number of independent runs; the run with the lowest inertia wins.
+        max_iter: Maximum Lloyd iterations per run.
+        tol: Stop a run when no centroid moves more than ``tol``.
+        random_state: Seed for reproducible initialisation.
+
+    Attributes:
+        cluster_centers_: Centroids of shape ``(n_clusters, n_features)``.
+        labels_: Cluster index of each training sample.
+        inertia_: Sum of squared distances of samples to their closest centroid.
+        n_iter_: Lloyd iterations used by the best run.
+    """
+
+    def __init__(
+        self,
+        n_clusters: int = 8,
+        n_init: int = 10,
+        max_iter: int = 300,
+        tol: float = 1e-6,
+        random_state: Optional[int] = None,
+    ) -> None:
+        self.n_clusters = n_clusters
+        self.n_init = n_init
+        self.max_iter = max_iter
+        self.tol = tol
+        self.random_state = random_state
+        self.cluster_centers_: np.ndarray = None  # type: ignore[assignment]
+        self.labels_: np.ndarray = None  # type: ignore[assignment]
+        self.inertia_: float = float("nan")
+        self.n_iter_: int = 0
+
+    @staticmethod
+    def _kmeans_pp(X: np.ndarray, k: int, rng: np.random.Generator) -> np.ndarray:
+        n = X.shape[0]
+        centers = np.empty((k, X.shape[1]))
+        centers[0] = X[rng.integers(n)]
+        d2 = ((X - centers[0]) ** 2).sum(axis=1)
+        for i in range(1, k):
+            total = d2.sum()
+            j = rng.integers(n) if total == 0 else rng.choice(n, p=d2 / total)
+            centers[i] = X[j]
+            d2 = np.minimum(d2, ((X - centers[i]) ** 2).sum(axis=1))
+        return centers
+
+    def _single_run(self, X: np.ndarray, rng: np.random.Generator):
+        centers = self._kmeans_pp(X, self.n_clusters, rng)
+        n_iter = 0
+        for n_iter in range(1, self.max_iter + 1):
+            labels = np.argmin(pairwise_distances(X, centers), axis=1)
+            new_centers = centers.copy()
+            for c in range(self.n_clusters):
+                members = X[labels == c]
+                if members.shape[0] > 0:  # keep an empty cluster's centroid in place
+                    new_centers[c] = members.mean(axis=0)
+            shift = np.abs(new_centers - centers).max()
+            centers = new_centers
+            if shift <= self.tol:
+                break
+        labels = np.argmin(pairwise_distances(X, centers), axis=1)
+        inertia = float(((X - centers[labels]) ** 2).sum())
+        return centers, labels, inertia, n_iter
+
+    def fit(self, X: ArrayLike, y: Optional[ArrayLike] = None) -> "KMeans":
+        """Cluster ``X`` of shape ``(n_samples, n_features)``. ``y`` is ignored."""
+        X = check_array(X)
+        if not 1 <= self.n_clusters <= X.shape[0]:
+            raise ValueError(
+                f"n_clusters must be in [1, n_samples={X.shape[0]}], got {self.n_clusters}."
+            )
+        if self.n_init < 1:
+            raise ValueError("n_init must be >= 1.")
+        rng = np.random.default_rng(self.random_state)
+        best = None
+        for _ in range(self.n_init):
+            run = self._single_run(X, rng)
+            if best is None or run[2] < best[2]:
+                best = run
+        self.cluster_centers_, self.labels_, self.inertia_, self.n_iter_ = best  # type: ignore[misc]
+        return self
+
+    def predict(self, X: ArrayLike) -> np.ndarray:
+        """Assign each sample in ``X`` to its nearest centroid."""
+        check_is_fitted(self, "cluster_centers_")
+        return np.argmin(pairwise_distances(X, self.cluster_centers_), axis=1)
+
+    def transform(self, X: ArrayLike) -> np.ndarray:
+        """Return distances to each centroid, shape ``(n_samples, n_clusters)``."""
+        check_is_fitted(self, "cluster_centers_")
+        return pairwise_distances(X, self.cluster_centers_)

mlkit/datasets.py

@@ -0,0 +1,73 @@
+"""Synthetic dataset generators for examples and tests."""
+
+from __future__ import annotations
+
+from typing import Optional, Tuple, Union
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+__all__ = ["make_blobs", "make_regression"]
+
+
+def make_blobs(
+    n_samples: int = 100,
+    n_features: int = 2,
+    centers: Union[int, ArrayLike] = 3,
+    cluster_std: float = 1.0,
+    random_state: Optional[int] = None,
+) -> Tuple[np.ndarray, np.ndarray]:
+    """Generate isotropic Gaussian blobs for clustering/classification.
+
+    Args:
+        n_samples: Total number of points, split as evenly as possible.
+        n_features: Dimensionality (ignored if ``centers`` is an array).
+        centers: Number of centres (drawn uniformly in ``[-10, 10]``) or an
+            explicit array of shape ``(n_centers, n_features)``.
+        cluster_std: Standard deviation of each blob.
+        random_state: Seed for reproducibility.
+
+    Returns:
+        ``(X, y)`` with ``X`` of shape ``(n_samples, n_features)`` and integer
+        labels ``y`` of shape ``(n_samples,)``.
+    """
+    rng = np.random.default_rng(random_state)
+    if isinstance(centers, (int, np.integer)):
+        C = rng.uniform(-10.0, 10.0, size=(int(centers), n_features))
+    else:
+        C = np.asarray(centers, dtype=float)
+        if C.ndim != 2:
+            raise ValueError("centers must be an int or a 2-D array.")
+    k = C.shape[0]
+    counts = np.full(k, n_samples // k)
+    counts[: n_samples % k] += 1
+    y = np.repeat(np.arange(k), counts)
+    X = C[y] + rng.normal(scale=cluster_std, size=(n_samples, C.shape[1]))
+    perm = rng.permutation(n_samples)
+    return X[perm], y[perm]
+
+
+def make_regression(
+    n_samples: int = 100,
+    n_features: int = 3,
+    noise: float = 0.0,
+    bias: float = 0.0,
+    random_state: Optional[int] = None,
+) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Generate a random linear regression problem ``y = X @ coef + bias + noise``.
+
+    Args:
+        n_samples: Number of samples.
+        n_features: Number of features.
+        noise: Standard deviation of Gaussian noise added to ``y``.
+        bias: Intercept of the underlying model.
+        random_state: Seed for reproducibility.
+
+    Returns:
+        ``(X, y, coef)`` where ``coef`` holds the true weights.
+    """
+    rng = np.random.default_rng(random_state)
+    X = rng.normal(size=(n_samples, n_features))
+    coef = rng.uniform(-5.0, 5.0, size=n_features)
+    y = X @ coef + bias + rng.normal(scale=noise, size=n_samples) if noise > 0 else X @ coef + bias
+    return X, y, coef

mlkit/linear_model.py

@@ -0,0 +1,191 @@
+"""Linear models: ordinary least squares, ridge and logistic regression."""
+
+from __future__ import annotations
+
+from typing import Tuple
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from .base import BaseEstimator, ClassifierMixin, RegressorMixin, check_array, check_is_fitted, check_X_y
+
+__all__ = ["LinearRegression", "Ridge", "LogisticRegression"]
+
+
+def _center(X: np.ndarray, y: np.ndarray, fit_intercept: bool) -> Tuple[np.ndarray, np.ndarray, np.ndarray, float]:
+    if fit_intercept:
+        X_mean = X.mean(axis=0)
+        y_mean = float(y.mean())
+        return X - X_mean, y - y_mean, X_mean, y_mean
+    return X, y, np.zeros(X.shape[1]), 0.0
+
+
+class _LinearRegressorBase(BaseEstimator, RegressorMixin):
+    coef_: np.ndarray
+    intercept_: float
+
+    def predict(self, X: ArrayLike) -> np.ndarray:
+        """Predict targets for ``X`` of shape ``(n_samples, n_features)``."""
+        check_is_fitted(self, "coef_")
+        X = check_array(X)
+        if X.shape[1] != self.coef_.shape[0]:
+            raise ValueError(f"X has {X.shape[1]} features, expected {self.coef_.shape[0]}.")
+        return X @ self.coef_ + self.intercept_
+
+
+class LinearRegression(_LinearRegressorBase):
+    """Ordinary least squares linear regression.
+
+    Solves ``min ||y - X w - b||^2`` with :func:`numpy.linalg.lstsq`, which is
+    robust to rank-deficient ``X``.
+
+    Args:
+        fit_intercept: Whether to learn an intercept ``b``.
+
+    Attributes:
+        coef_: Weights of shape ``(n_features,)``.
+        intercept_: Bias term (``0.0`` if ``fit_intercept=False``).
+    """
+
+    def __init__(self, fit_intercept: bool = True) -> None:
+        self.fit_intercept = fit_intercept
+        self.coef_ = None  # type: ignore[assignment]
+        self.intercept_ = 0.0
+
+    def fit(self, X: ArrayLike, y: ArrayLike) -> "LinearRegression":
+        """Fit the model to ``X`` of shape ``(n_samples, n_features)`` and ``y``."""
+        X, y = check_X_y(X, y, y_numeric=True)
+        Xc, yc, X_mean, y_mean = _center(X, y, self.fit_intercept)
+        coef, *_ = np.linalg.lstsq(Xc, yc, rcond=None)
+        self.coef_ = coef
+        self.intercept_ = float(y_mean - X_mean @ coef)
+        return self
+
+
+class Ridge(_LinearRegressorBase):
+    """Linear regression with L2 regularisation (closed form).
+
+    Minimises ``||y - X w - b||^2 + alpha * ||w||^2``. The intercept is not
+    penalised.
+
+    Args:
+        alpha: Non-negative regularisation strength.
+        fit_intercept: Whether to learn an intercept ``b``.
+
+    Attributes:
+        coef_: Weights of shape ``(n_features,)``.
+        intercept_: Bias term.
+    """
+
+    def __init__(self, alpha: float = 1.0, fit_intercept: bool = True) -> None:
+        self.alpha = alpha
+        self.fit_intercept = fit_intercept
+        self.coef_ = None  # type: ignore[assignment]
+        self.intercept_ = 0.0
+
+    def fit(self, X: ArrayLike, y: ArrayLike) -> "Ridge":
+        """Fit the model to ``X`` of shape ``(n_samples, n_features)`` and ``y``."""
+        if self.alpha < 0:
+            raise ValueError("alpha must be non-negative.")
+        X, y = check_X_y(X, y, y_numeric=True)
+        Xc, yc, X_mean, y_mean = _center(X, y, self.fit_intercept)
+        n_features = X.shape[1]
+        A = Xc.T @ Xc + self.alpha * np.eye(n_features)
+        coef = np.linalg.lstsq(A, Xc.T @ yc, rcond=None)[0]
+        self.coef_ = coef
+        self.intercept_ = float(y_mean - X_mean @ coef)
+        return self
+
+
+def _softmax(z: np.ndarray) -> np.ndarray:
+    z = z - z.max(axis=1, keepdims=True)
+    e = np.exp(z)
+    return e / e.sum(axis=1, keepdims=True)
+
+
+class LogisticRegression(BaseEstimator, ClassifierMixin):
+    """Multinomial logistic regression trained by full-batch gradient descent.
+
+    Binary problems are handled as the two-class case of the softmax model.
+    Features should be on comparable scales (see
+    :class:`mlkit.preprocessing.StandardScaler`) for fast convergence.
+
+    Args:
+        learning_rate: Gradient descent step size.
+        max_iter: Maximum number of gradient steps.
+        tol: Stop when the largest absolute gradient entry falls below ``tol``.
+        alpha: L2 penalty on the weights (not the intercepts).
+        fit_intercept: Whether to learn per-class intercepts.
+
+    Attributes:
+        classes_: Sorted unique class labels, shape ``(n_classes,)``.
+        coef_: Weights of shape ``(n_classes, n_features)``.
+        intercept_: Intercepts of shape ``(n_classes,)``.
+        n_iter_: Number of gradient steps actually taken.
+    """
+
+    def __init__(
+        self,
+        learning_rate: float = 0.1,
+        max_iter: int = 1000,
+        tol: float = 1e-6,
+        alpha: float = 0.0,
+        fit_intercept: bool = True,
+    ) -> None:
+        self.learning_rate = learning_rate
+        self.max_iter = max_iter
+        self.tol = tol
+        self.alpha = alpha
+        self.fit_intercept = fit_intercept
+        self.classes_: np.ndarray = None  # type: ignore[assignment]
+        self.coef_: np.ndarray = None  # type: ignore[assignment]
+        self.intercept_: np.ndarray = None  # type: ignore[assignment]
+        self.n_iter_: int = 0
+
+    def fit(self, X: ArrayLike, y: ArrayLike) -> "LogisticRegression":
+        """Fit the model to ``X`` of shape ``(n_samples, n_features)`` and labels ``y``."""
+        X, y = check_X_y(X, y)
+        classes, y_idx = np.unique(y, return_inverse=True)
+        if classes.shape[0] < 2:
+            raise ValueError("LogisticRegression needs at least two classes in y.")
+        n_samples, n_features = X.shape
+        n_classes = classes.shape[0]
+        Y = np.eye(n_classes)[y_idx]
+
+        W = np.zeros((n_classes, n_features))
+        b = np.zeros(n_classes)
+        n_iter = 0
+        for n_iter in range(1, self.max_iter + 1):
+            P = _softmax(X @ W.T + b)
+            diff = (P - Y) / n_samples
+            grad_W = diff.T @ X + self.alpha * W
+            grad_b = diff.sum(axis=0) if self.fit_intercept else np.zeros(n_classes)
+            W -= self.learning_rate * grad_W
+            b -= self.learning_rate * grad_b
+            if max(np.abs(grad_W).max(), np.abs(grad_b).max()) < self.tol:
+                break
+
+        self.classes_ = classes
+        self.coef_ = W
+        self.intercept_ = b
+        self.n_iter_ = n_iter
+        return self
+
+    def decision_function(self, X: ArrayLike) -> np.ndarray:
+        """Return per-class linear scores of shape ``(n_samples, n_classes)``."""
+        check_is_fitted(self, "coef_")
+        X = check_array(X)
+        if X.shape[1] != self.coef_.shape[1]:
+            raise ValueError(f"X has {X.shape[1]} features, expected {self.coef_.shape[1]}.")
+        return X @ self.coef_.T + self.intercept_
+
+    def predict_proba(self, X: ArrayLike) -> np.ndarray:
+        """Return class probabilities of shape ``(n_samples, n_classes)``.
+
+        Columns follow the order of ``classes_``.
+        """
+        return _softmax(self.decision_function(X))
+
+    def predict(self, X: ArrayLike) -> np.ndarray:
+        """Return the most probable class label for each sample."""
+        return self.classes_[np.argmax(self.decision_function(X), axis=1)]

mlkit/metrics.py

@@ -0,0 +1,139 @@
+"""Evaluation metrics for regression and classification."""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Sequence, Tuple
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+__all__ = [
+    "accuracy_score",
+    "confusion_matrix",
+    "precision_score",
+    "recall_score",
+    "f1_score",
+    "mean_squared_error",
+    "mean_absolute_error",
+    "r2_score",
+]
+
+_AVERAGES = ("binary", "macro")
+
+
+def _check_pair(y_true: ArrayLike, y_pred: ArrayLike, numeric: bool = False) -> Tuple[np.ndarray, np.ndarray]:
+    dtype = float if numeric else None
+    t = np.asarray(y_true, dtype=dtype)
+    p = np.asarray(y_pred, dtype=dtype)
+    if t.ndim != 1 or p.ndim != 1:
+        raise ValueError("y_true and y_pred must be 1-D.")
+    if t.shape[0] != p.shape[0]:
+        raise ValueError(f"Inconsistent lengths: {t.shape[0]} != {p.shape[0]}.")
+    if t.shape[0] == 0:
+        raise ValueError("Empty input.")
+    return t, p
+
+
+# --------------------------------------------------------------------------- #
+# Regression
+# --------------------------------------------------------------------------- #
+
+
+def mean_squared_error(y_true: ArrayLike, y_pred: ArrayLike) -> float:
+    """Mean of squared residuals."""
+    t, p = _check_pair(y_true, y_pred, numeric=True)
+    return float(np.mean((t - p) ** 2))
+
+
+def mean_absolute_error(y_true: ArrayLike, y_pred: ArrayLike) -> float:
+    """Mean of absolute residuals."""
+    t, p = _check_pair(y_true, y_pred, numeric=True)
+    return float(np.mean(np.abs(t - p)))
+
+
+def r2_score(y_true: ArrayLike, y_pred: ArrayLike) -> float:
+    """Coefficient of determination ``1 - SS_res / SS_tot``.
+
+    Returns 1.0 for a perfect fit of constant ``y_true`` and 0.0 for an
+    imperfect one (where ``SS_tot`` is zero).
+    """
+    t, p = _check_pair(y_true, y_pred, numeric=True)
+    ss_res = float(np.sum((t - p) ** 2))
+    ss_tot = float(np.sum((t - t.mean()) ** 2))
+    if ss_tot == 0.0:
+        return 1.0 if ss_res == 0.0 else 0.0
+    return 1.0 - ss_res / ss_tot
+
+
+# --------------------------------------------------------------------------- #
+# Classification
+# --------------------------------------------------------------------------- #
+
+
+def accuracy_score(y_true: ArrayLike, y_pred: ArrayLike) -> float:
+    """Fraction of exactly matching labels."""
+    t, p = _check_pair(y_true, y_pred)
+    return float(np.mean(t == p))
+
+
+def confusion_matrix(y_true: ArrayLike, y_pred: ArrayLike, labels: Optional[Sequence[Any]] = None) -> np.ndarray:
+    """Count matrix ``C`` where ``C[i, j]`` is the number of samples of true
+    class ``labels[i]`` predicted as ``labels[j]``.
+
+    Args:
+        y_true: True labels.
+        y_pred: Predicted labels.
+        labels: Label order; defaults to the sorted union of both inputs.
+            Samples whose labels are not listed are ignored.
+    """
+    t, p = _check_pair(y_true, y_pred)
+    lab = np.unique(np.concatenate([t, p])) if labels is None else np.asarray(labels)
+    index = {v: i for i, v in enumerate(lab.tolist())}
+    cm = np.zeros((len(lab), len(lab)), dtype=int)
+    for a, b in zip(t.tolist(), p.tolist()):
+        if a in index and b in index:
+            cm[index[a], index[b]] += 1
+    return cm
+
+
+def _per_class_counts(t: np.ndarray, p: np.ndarray, average: str, pos_label: Any):
+    if average not in _AVERAGES:
+        raise ValueError(f"average must be one of {_AVERAGES}, got {average!r}.")
+    labels = [pos_label] if average == "binary" else np.unique(np.concatenate([t, p])).tolist()
+    tp = np.array([np.sum((p == c) & (t == c)) for c in labels], dtype=float)
+    fp = np.array([np.sum((p == c) & (t != c)) for c in labels], dtype=float)
+    fn = np.array([np.sum((p != c) & (t == c)) for c in labels], dtype=float)
+    return tp, fp, fn
+
+
+def _safe_div(num: np.ndarray, den: np.ndarray) -> np.ndarray:
+    return np.divide(num, den, out=np.zeros_like(num), where=den != 0)
+
+
+def precision_score(y_true: ArrayLike, y_pred: ArrayLike, *, average: str = "binary", pos_label: Any = 1) -> float:
+    """Precision ``tp / (tp + fp)``.
+
+    Args:
+        average: ``"binary"`` scores only ``pos_label``; ``"macro"`` averages
+            the per-class scores over all labels present.
+        pos_label: Positive class used when ``average="binary"``.
+
+    Undefined ratios (zero denominator) count as 0.0.
+    """
+    t, p = _check_pair(y_true, y_pred)
+    tp, fp, _ = _per_class_counts(t, p, average, pos_label)
+    return float(np.mean(_safe_div(tp, tp + fp)))
+
+
+def recall_score(y_true: ArrayLike, y_pred: ArrayLike, *, average: str = "binary", pos_label: Any = 1) -> float:
+    """Recall ``tp / (tp + fn)``. See :func:`precision_score` for arguments."""
+    t, p = _check_pair(y_true, y_pred)
+    tp, _, fn = _per_class_counts(t, p, average, pos_label)
+    return float(np.mean(_safe_div(tp, tp + fn)))
+
+
+def f1_score(y_true: ArrayLike, y_pred: ArrayLike, *, average: str = "binary", pos_label: Any = 1) -> float:
+    """F1 ``2 tp / (2 tp + fp + fn)``. See :func:`precision_score` for arguments."""
+    t, p = _check_pair(y_true, y_pred)
+    tp, fp, fn = _per_class_counts(t, p, average, pos_label)
+    return float(np.mean(_safe_div(2 * tp, 2 * tp + fp + fn)))

mlkit/model_selection.py

@@ -0,0 +1,117 @@
+"""Data splitting and cross-validation."""
+
+from __future__ import annotations
+
+from typing import Callable, Iterator, List, Optional, Tuple, Union
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from .base import BaseEstimator, clone
+
+__all__ = ["train_test_split", "KFold", "cross_val_score"]
+
+
+def train_test_split(
+    *arrays: ArrayLike,
+    test_size: Union[float, int] = 0.25,
+    shuffle: bool = True,
+    random_state: Optional[int] = None,
+) -> List[np.ndarray]:
+    """Split arrays into random train and test subsets.
+
+    Args:
+        *arrays: One or more arrays with the same first dimension.
+        test_size: Fraction in ``(0, 1)`` or absolute number of test samples.
+        shuffle: Shuffle before splitting.
+        random_state: Seed for reproducible shuffling.
+
+    Returns:
+        ``[a_train, a_test, b_train, b_test, ...]`` for each input array.
+
+    Example:
+        >>> X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)
+    """
+    if not arrays:
+        raise ValueError("At least one array is required.")
+    arrs = [np.asarray(a) for a in arrays]
+    n = arrs[0].shape[0]
+    if any(a.shape[0] != n for a in arrs):
+        raise ValueError("All arrays must have the same number of samples.")
+
+    if isinstance(test_size, float):
+        if not 0.0 < test_size < 1.0:
+            raise ValueError("A float test_size must be in (0, 1).")
+        n_test = int(np.ceil(test_size * n))
+    else:
+        n_test = int(test_size)
+    if not 0 < n_test < n:
+        raise ValueError(f"test_size={test_size} leaves an empty train or test set for n={n}.")
+
+    idx = np.random.default_rng(random_state).permutation(n) if shuffle else np.arange(n)
+    test_idx, train_idx = idx[:n_test], idx[n_test:]
+    out: List[np.ndarray] = []
+    for a in arrs:
+        out.extend([a[train_idx], a[test_idx]])
+    return out
+
+
+class KFold:
+    """K-fold cross-validation splitter.
+
+    Args:
+        n_splits: Number of folds (>= 2).
+        shuffle: Shuffle sample indices before folding.
+        random_state: Seed used when ``shuffle=True``.
+    """
+
+    def __init__(self, n_splits: int = 5, shuffle: bool = False, random_state: Optional[int] = None) -> None:
+        if n_splits < 2:
+            raise ValueError("n_splits must be >= 2.")
+        self.n_splits = n_splits
+        self.shuffle = shuffle
+        self.random_state = random_state
+
+    def split(self, X: ArrayLike) -> Iterator[Tuple[np.ndarray, np.ndarray]]:
+        """Yield ``(train_indices, test_indices)`` for each fold."""
+        n = np.asarray(X).shape[0]
+        if self.n_splits > n:
+            raise ValueError(f"Cannot make {self.n_splits} folds from {n} samples.")
+        idx = np.random.default_rng(self.random_state).permutation(n) if self.shuffle else np.arange(n)
+        for test_idx in np.array_split(idx, self.n_splits):
+            yield np.setdiff1d(idx, test_idx, assume_unique=True), test_idx
+
+
+def cross_val_score(
+    estimator: BaseEstimator,
+    X: ArrayLike,
+    y: ArrayLike,
+    *,
+    cv: Union[int, KFold] = 5,
+    scoring: Optional[Callable[[np.ndarray, np.ndarray], float]] = None,
+) -> np.ndarray:
+    """Evaluate ``estimator`` with K-fold cross-validation.
+
+    A fresh :func:`~mlkit.base.clone` of ``estimator`` is fitted on each fold.
+
+    Args:
+        estimator: An unfitted estimator with ``fit``/``predict``.
+        X: Features, shape ``(n_samples, n_features)``.
+        y: Targets, shape ``(n_samples,)``.
+        cv: Number of folds or a :class:`KFold` instance.
+        scoring: ``metric(y_true, y_pred) -> float``; defaults to the
+            estimator's own ``score`` method.
+
+    Returns:
+        Array of per-fold scores, shape ``(n_splits,)``.
+    """
+    X_arr, y_arr = np.asarray(X), np.asarray(y)
+    splitter = KFold(n_splits=cv) if isinstance(cv, int) else cv
+    scores = []
+    for train_idx, test_idx in splitter.split(X_arr):
+        model = clone(estimator).fit(X_arr[train_idx], y_arr[train_idx])  # type: ignore[attr-defined]
+        if scoring is None:
+            scores.append(model.score(X_arr[test_idx], y_arr[test_idx]))
+        else:
+            scores.append(scoring(y_arr[test_idx], model.predict(X_arr[test_idx])))
+    return np.asarray(scores, dtype=float)

mlkit/neighbors.py

@@ -0,0 +1,132 @@
+"""k-nearest-neighbour classification and regression (brute-force Euclidean)."""
+
+from __future__ import annotations
+
+from typing import Tuple
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from .base import BaseEstimator, ClassifierMixin, RegressorMixin, check_array, check_is_fitted, check_X_y
+
+__all__ = ["KNeighborsClassifier", "KNeighborsRegressor", "pairwise_distances"]
+
+_WEIGHTS = ("uniform", "distance")
+
+
+def pairwise_distances(A: ArrayLike, B: ArrayLike) -> np.ndarray:
+    """Euclidean distances between rows of ``A`` and rows of ``B``.
+
+    Args:
+        A: Array of shape ``(n_a, n_features)``.
+        B: Array of shape ``(n_b, n_features)``.
+
+    Returns:
+        Array of shape ``(n_a, n_b)``.
+    """
+    A = check_array(A)
+    B = check_array(B)
+    if A.shape[1] != B.shape[1]:
+        raise ValueError(f"Feature mismatch: {A.shape[1]} != {B.shape[1]}.")
+    sq = (A * A).sum(axis=1)[:, None] - 2.0 * A @ B.T + (B * B).sum(axis=1)[None, :]
+    return np.sqrt(np.maximum(sq, 0.0))
+
+
+class _KNeighborsBase(BaseEstimator):
+    def __init__(self, n_neighbors: int = 5, weights: str = "uniform") -> None:
+        self.n_neighbors = n_neighbors
+        self.weights = weights
+        self._fit_X: np.ndarray = None  # type: ignore[assignment]
+        self._fit_y: np.ndarray = None  # type: ignore[assignment]
+
+    def _validate_params(self, n_samples: int) -> None:
+        if self.weights not in _WEIGHTS:
+            raise ValueError(f"weights must be one of {_WEIGHTS}, got {self.weights!r}.")
+        if not 1 <= self.n_neighbors <= n_samples:
+            raise ValueError(
+                f"n_neighbors must be in [1, n_samples={n_samples}], got {self.n_neighbors}."
+            )
+
+    def kneighbors(self, X: ArrayLike) -> Tuple[np.ndarray, np.ndarray]:
+        """Find the ``n_neighbors`` nearest training samples for each row of ``X``.
+
+        Returns:
+            ``(distances, indices)``, each of shape ``(n_samples, n_neighbors)``,
+            sorted by increasing distance.
+        """
+        check_is_fitted(self, "_fit_X")
+        D = pairwise_distances(X, self._fit_X)
+        idx = np.argsort(D, axis=1, kind="stable")[:, : self.n_neighbors]
+        return np.take_along_axis(D, idx, axis=1), idx
+
+    def _neighbor_weights(self, dist: np.ndarray) -> np.ndarray:
+        if self.weights == "uniform":
+            return np.ones_like(dist)
+        # Exact matches dominate: give them weight 1 and everything else 0.
+        with np.errstate(divide="ignore"):
+            w = 1.0 / dist
+        exact = np.isinf(w)
+        rows = exact.any(axis=1)
+        w[rows] = exact[rows].astype(float)
+        return w
+
+
+class KNeighborsClassifier(_KNeighborsBase, ClassifierMixin):
+    """Classifier voting among the ``k`` nearest training samples.
+
+    Args:
+        n_neighbors: Number of neighbours ``k``.
+        weights: ``"uniform"`` (each neighbour counts equally) or
+            ``"distance"`` (votes weighted by inverse distance).
+
+    Attributes:
+        classes_: Sorted unique class labels.
+    """
+
+    def __init__(self, n_neighbors: int = 5, weights: str = "uniform") -> None:
+        super().__init__(n_neighbors=n_neighbors, weights=weights)
+        self.classes_: np.ndarray = None  # type: ignore[assignment]
+
+    def fit(self, X: ArrayLike, y: ArrayLike) -> "KNeighborsClassifier":
+        """Store the training data ``X`` and labels ``y``."""
+        X, y = check_X_y(X, y)
+        self._validate_params(X.shape[0])
+        self.classes_, self._fit_y = np.unique(y, return_inverse=True)
+        self._fit_X = X
+        return self
+
+    def predict_proba(self, X: ArrayLike) -> np.ndarray:
+        """Return vote shares of shape ``(n_samples, n_classes)`` (columns follow ``classes_``)."""
+        dist, idx = self.kneighbors(X)
+        w = self._neighbor_weights(dist)
+        labels = self._fit_y[idx]
+        proba = np.zeros((idx.shape[0], self.classes_.shape[0]))
+        for c in range(self.classes_.shape[0]):
+            proba[:, c] = (w * (labels == c)).sum(axis=1)
+        return proba / proba.sum(axis=1, keepdims=True)
+
+    def predict(self, X: ArrayLike) -> np.ndarray:
+        """Return the majority-vote label for each sample (ties go to the smaller class)."""
+        return self.classes_[np.argmax(self.predict_proba(X), axis=1)]
+
+
+class KNeighborsRegressor(_KNeighborsBase, RegressorMixin):
+    """Regressor averaging the targets of the ``k`` nearest training samples.
+
+    Args:
+        n_neighbors: Number of neighbours ``k``.
+        weights: ``"uniform"`` or ``"distance"`` (inverse-distance weighted mean).
+    """
+
+    def fit(self, X: ArrayLike, y: ArrayLike) -> "KNeighborsRegressor":
+        """Store the training data ``X`` and numeric targets ``y``."""
+        X, y = check_X_y(X, y, y_numeric=True)
+        self._validate_params(X.shape[0])
+        self._fit_X, self._fit_y = X, y
+        return self
+
+    def predict(self, X: ArrayLike) -> np.ndarray:
+        """Return the (weighted) mean neighbour target for each sample."""
+        dist, idx = self.kneighbors(X)
+        w = self._neighbor_weights(dist)
+        return (w * self._fit_y[idx]).sum(axis=1) / w.sum(axis=1)

mlkit/preprocessing.py

@@ -0,0 +1,111 @@
+"""Feature scaling transformers."""
+
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from .base import BaseEstimator, TransformerMixin, check_array, check_is_fitted
+
+__all__ = ["StandardScaler", "MinMaxScaler"]
+
+
+def _check_n_features(X: np.ndarray, expected: int) -> None:
+    if X.shape[1] != expected:
+        raise ValueError(f"X has {X.shape[1]} features, expected {expected}.")
+
+
+class StandardScaler(BaseEstimator, TransformerMixin):
+    """Standardise features to zero mean and unit variance.
+
+    Constant features (zero variance) are left centred but not scaled.
+
+    Args:
+        with_mean: Subtract the per-feature mean.
+        with_std: Divide by the per-feature (population) standard deviation.
+
+    Attributes:
+        mean_: Per-feature means, shape ``(n_features,)``.
+        scale_: Per-feature divisors, shape ``(n_features,)``.
+    """
+
+    def __init__(self, with_mean: bool = True, with_std: bool = True) -> None:
+        self.with_mean = with_mean
+        self.with_std = with_std
+        self.mean_: np.ndarray = None  # type: ignore[assignment]
+        self.scale_: np.ndarray = None  # type: ignore[assignment]
+
+    def fit(self, X: ArrayLike, y: Optional[ArrayLike] = None) -> "StandardScaler":
+        """Compute the mean and standard deviation of each column of ``X``."""
+        X = check_array(X)
+        self.mean_ = X.mean(axis=0) if self.with_mean else np.zeros(X.shape[1])
+        if self.with_std:
+            std = X.std(axis=0)
+            self.scale_ = np.where(std == 0.0, 1.0, std)
+        else:
+            self.scale_ = np.ones(X.shape[1])
+        return self
+
+    def transform(self, X: ArrayLike) -> np.ndarray:
+        """Return ``(X - mean_) / scale_``."""
+        check_is_fitted(self, "mean_")
+        X = check_array(X)
+        _check_n_features(X, self.mean_.shape[0])
+        return (X - self.mean_) / self.scale_
+
+    def inverse_transform(self, X: ArrayLike) -> np.ndarray:
+        """Undo :meth:`transform`."""
+        check_is_fitted(self, "mean_")
+        X = check_array(X)
+        _check_n_features(X, self.mean_.shape[0])
+        return X * self.scale_ + self.mean_
+
+
+class MinMaxScaler(BaseEstimator, TransformerMixin):
+    """Rescale each feature linearly into ``feature_range``.
+
+    Constant features are mapped to the lower bound of the range.
+
+    Args:
+        feature_range: Target ``(min, max)`` interval.
+
+    Attributes:
+        data_min_: Per-feature minimum seen in ``fit``.
+        data_max_: Per-feature maximum seen in ``fit``.
+    """
+
+    def __init__(self, feature_range: Tuple[float, float] = (0.0, 1.0)) -> None:
+        self.feature_range = feature_range
+        self.data_min_: np.ndarray = None  # type: ignore[assignment]
+        self.data_max_: np.ndarray = None  # type: ignore[assignment]
+
+    def fit(self, X: ArrayLike, y: Optional[ArrayLike] = None) -> "MinMaxScaler":
+        """Record the per-feature minimum and maximum of ``X``."""
+        lo, hi = self.feature_range
+        if not lo < hi:
+            raise ValueError(f"feature_range min must be < max, got {self.feature_range}.")
+        X = check_array(X)
+        self.data_min_ = X.min(axis=0)
+        self.data_max_ = X.max(axis=0)
+        return self
+
+    def _scale(self) -> np.ndarray:
+        rng = self.data_max_ - self.data_min_
+        lo, hi = self.feature_range
+        return (hi - lo) / np.where(rng == 0.0, 1.0, rng)
+
+    def transform(self, X: ArrayLike) -> np.ndarray:
+        """Map ``X`` into ``feature_range`` (values outside the fitted range are not clipped)."""
+        check_is_fitted(self, "data_min_")
+        X = check_array(X)
+        _check_n_features(X, self.data_min_.shape[0])
+        return (X - self.data_min_) * self._scale() + self.feature_range[0]
+
+    def inverse_transform(self, X: ArrayLike) -> np.ndarray:
+        """Undo :meth:`transform`."""
+        check_is_fitted(self, "data_min_")
+        X = check_array(X)
+        _check_n_features(X, self.data_min_.shape[0])
+        return (X - self.feature_range[0]) / self._scale() + self.data_min_

mlkit-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+mlkit/__init__.py,sha256=PIitq7wzOvuCtYaW5QRLeynAylx95OmtPvPYsSutM9k,946
+mlkit/base.py,sha256=RBQfQ9eN1gF4i5ulqfUq5HroRaXliJasnAQFWBHo7oY,5440
+mlkit/cluster.py,sha256=0a3fmSAL7BdxmDoDyk7SSdAnSS8g7n-rISbZAntrgCU,4311
+mlkit/datasets.py,sha256=iUktHqbv5RxaSTzMxYd1m29QHJsGiZF5Vd08FsdOZ20,2560
+mlkit/linear_model.py,sha256=ws3qNCKif56Qm3otu-WP0zcoDrqjw-kGll7RrHKtEII,7142
+mlkit/metrics.py,sha256=Goj7d7PjDbmVLkZJB4E8zN-lFUTZphNfcdqmMVr4MBk,5191
+mlkit/model_selection.py,sha256=0XQ_XctTHMfLH7z_Uy13WyvMZwbA4NXy7m7lYk5IOlI,4243
+mlkit/neighbors.py,sha256=U9SOTHZSrT184mFOOS1ldPR6AUaHScbHCWhZ6El5fFk,5155
+mlkit/preprocessing.py,sha256=J_K3VgSfIwhIj_4tHYxuFSBPa2LlZqODn1z3KFq3XWM,4114
+mlkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mlkit-0.1.0.dist-info/licenses/LICENSE,sha256=pAfYREEW9GAy7cnK20OXjDn7ofJahYny9GCuIZQTDAA,1061
+mlkit-0.1.0.dist-info/METADATA,sha256=yAhR-NbYVhkl539eXSuCS4cNIQoBT86b-hzgEK_OjvI,8318
+mlkit-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+mlkit-0.1.0.dist-info/top_level.txt,sha256=bMLuHaaaZpWUcZAZQPEDE7tlGs8ZYUJ9zAsfZNhuoAs,6
+mlkit-0.1.0.dist-info/RECORD,,

mlkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mlkit-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+mlkit