coreLearn 0.1.0__py3-none-any.whl

coreLearn/__init__.py

@@ -0,0 +1,17 @@
+"""my_ml_library — public API."""
+
+from .knn import KNNClassifier
+from .linear_regression import LinearRegression
+from .evaluator import Evaluator, accuracy, mae, mse, rmse, precision, recall, f1_score
+from .distances import DistanceMetric, DistanceMetricFactory
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "KNNClassifier",
+    "LinearRegression",
+    "Evaluator",
+    "accuracy", "mae", "mse", "rmse",
+    "precision", "recall", "f1_score",
+    "DistanceMetric", "DistanceMetricFactory",
+]

coreLearn/base.py

@@ -0,0 +1,25 @@
+from abc import ABC, abstractmethod
+
+
+class BaseModel(ABC):
+    """
+    Abstract base class for all models.
+
+    Implements the **Template Method** design pattern: ``fit_predict`` defines
+    the skeleton (fit → predict) and subclasses fill in the concrete steps.
+    """
+
+    @abstractmethod
+    def fit(self, X, y) -> "BaseModel":
+        """Train the model on feature matrix X and label vector y."""
+        pass
+
+    @abstractmethod
+    def predict(self, X) -> list:
+        """Return predictions for feature matrix X."""
+        pass
+
+    def fit_predict(self, X_train, y_train, X_test) -> list:
+        """Template method: train on X_train/y_train, then predict X_test."""
+        self.fit(X_train, y_train)
+        return self.predict(X_test)

coreLearn/distances.py

@@ -0,0 +1,125 @@
+from abc import ABC, abstractmethod
+
+import numpy as np
+
+
+class DistanceMetric(ABC):
+    """
+    Abstract distance metric.
+
+    Subclasses only need to implement ``compute()``.
+    ``__call__`` support lets an instance be used like a function:
+    ``metric(a, b)``  →  ``metric.compute(a, b)``
+    """
+
+    @abstractmethod
+    def compute(self, a: list, b: list) -> float:
+        """Compute and return the distance between two points."""
+
+    def __call__(self, a: list, b: list) -> float:
+        """Allow the object to be called as a function."""
+        return self.compute(a, b)
+
+
+class EuclideanDistance(DistanceMetric):
+    """
+    Euclidean (L2) distance: √Σ(aᵢ − bᵢ)²
+
+    General-purpose; suitable for continuous, scaled data.
+    """
+
+    def compute(self, a: list, b: list) -> float:
+        a_arr, b_arr = np.array(a), np.array(b)
+        return float(np.sqrt(np.sum((a_arr - b_arr) ** 2)))
+
+
+class ManhattanDistance(DistanceMetric):
+    """
+    Manhattan (L1) distance: Σ|aᵢ − bᵢ|
+
+    Preferred over Euclidean for grid-like spaces or when
+    robustness to outliers is desired.
+    """
+
+    def compute(self, a: list, b: list) -> float:
+        a_arr, b_arr = np.array(a), np.array(b)
+        return float(np.sum(np.abs(a_arr - b_arr)))
+
+
+class DistanceMetricFactory:
+    """
+    **Factory Pattern** — creates ``DistanceMetric`` instances by name.
+
+    ``KNNClassifier`` does not import concrete classes (``EuclideanDistance``,
+    etc.) directly; it simply passes a name to this factory.  Benefits:
+
+    * Adding a new metric requires no changes to ``KNNClassifier``.
+    * Decouples metric classes from consumer code (loose coupling).
+
+    Usage::
+
+        metric = DistanceMetricFactory.create("euclidean")
+        dist   = metric([1, 2], [4, 6])   # → 5.0
+
+    Registering a new metric::
+
+        class ChebyshevDistance(DistanceMetric):
+            def compute(self, a, b):
+                return float(max(abs(x - y) for x, y in zip(a, b)))
+
+        DistanceMetricFactory.register("chebyshev", ChebyshevDistance)
+    """
+
+    _registry: dict[str, type[DistanceMetric]] = {
+        "euclidean": EuclideanDistance,
+        "manhattan": ManhattanDistance,
+    }
+
+    @classmethod
+    def create(cls, name: str) -> "DistanceMetric":
+        """
+        Instantiate and return a ``DistanceMetric`` for the given name.
+
+        Parameters
+        ----------
+        name : str
+            Metric name — see ``available()`` for registered options.
+
+        Raises
+        ------
+        ValueError
+            If an unknown name is provided.
+        """
+        if name not in cls._registry:
+            raise ValueError(
+                f"Unknown distance metric: '{name}'. "
+                f"Available: {cls.available()}"
+            )
+        return cls._registry[name]()
+
+    @classmethod
+    def available(cls) -> list[str]:
+        """Return a list of all registered metric names."""
+        return list(cls._registry)
+
+    @classmethod
+    def register(cls, name: str, metric_class: type[DistanceMetric]) -> None:
+        """
+        Add a new distance metric class to the registry.
+
+        Parameters
+        ----------
+        name         : str                    — Lookup key.
+        metric_class : type[DistanceMetric]   — Concrete class (not yet instantiated).
+
+        Raises
+        ------
+        TypeError
+            If ``metric_class`` is not a subclass of ``DistanceMetric``.
+        """
+        if not (isinstance(metric_class, type) and
+                issubclass(metric_class, DistanceMetric)):
+            raise TypeError(
+                f"{metric_class} must be a subclass of DistanceMetric."
+            )
+        cls._registry[name] = metric_class

coreLearn/evaluator.py

@@ -0,0 +1,143 @@
+import numpy as np
+
+
+# ---------------------------------------------------------------------------
+# Regression metrics
+# ---------------------------------------------------------------------------
+
+def mae(y_true: np.ndarray, y_pred: np.ndarray) -> float:
+    """Mean Absolute Error."""
+    yt: np.ndarray = np.array(list(y_true), dtype=float)
+    yp: np.ndarray = np.array(list(y_pred), dtype=float)
+    if len(yt) == 0:
+        raise ValueError("y_true must not be empty.")
+    if len(yt) != len(yp):
+        raise ValueError(f"y_true and y_pred must have the same length: {len(yt)} != {len(yp)}")
+    return float(np.mean(np.abs(yt - yp)))
+
+
+def mse(y_true: np.ndarray, y_pred: np.ndarray) -> float:
+    """Mean Squared Error."""
+    yt: np.ndarray = np.array(list(y_true), dtype=float)
+    yp: np.ndarray = np.array(list(y_pred), dtype=float)
+    if len(yt) == 0:
+        raise ValueError("y_true must not be empty.")
+    if len(yt) != len(yp):
+        raise ValueError(f"y_true and y_pred must have the same length: {len(yt)} != {len(yp)}")
+    return float(np.mean((yt - yp) ** 2))
+
+
+def rmse(y_true: np.ndarray, y_pred: np.ndarray) -> float:
+    """Root Mean Squared Error."""
+    return float(np.sqrt(mse(y_true, y_pred)))
+
+
+# ---------------------------------------------------------------------------
+# Classification metrics
+# ---------------------------------------------------------------------------
+
+def accuracy(y_true: np.ndarray, y_pred: np.ndarray) -> float:
+    """Fraction of correctly predicted labels."""
+    yt: list = list(y_true)
+    yp: list = list(y_pred)
+    if len(yt) == 0:
+        raise ValueError("y_true must not be empty.")
+    if len(yt) != len(yp):
+        raise ValueError(f"y_true and y_pred must have the same length: {len(yt)} != {len(yp)}")
+    return sum(t == p for t, p in zip(yt, yp)) / len(yt)
+
+
+def precision(y_true: np.ndarray, y_pred: np.ndarray) -> float:
+    """Macro-averaged precision across all classes."""
+    yt: np.ndarray = np.array(y_true)
+    yp: np.ndarray = np.array(y_pred)
+    classes: np.ndarray = np.unique(yt)
+    scores: list[float] = []
+    for c in classes:
+        tp: int = int(np.sum((yp == c) & (yt == c)))
+        fp: int = int(np.sum((yp == c) & (yt != c)))
+        scores.append(tp / (tp + fp) if (tp + fp) > 0 else 0.0)
+    return float(np.mean(scores))
+
+
+def recall(y_true: np.ndarray, y_pred: np.ndarray) -> float:
+    """Macro-averaged recall across all classes."""
+    yt: np.ndarray = np.array(y_true)
+    yp: np.ndarray = np.array(y_pred)
+    classes: np.ndarray = np.unique(yt)
+    scores: list[float] = []
+    for c in classes:
+        tp: int = int(np.sum((yp == c) & (yt == c)))
+        fn: int = int(np.sum((yp != c) & (yt == c)))
+        scores.append(tp / (tp + fn) if (tp + fn) > 0 else 0.0)
+    return float(np.mean(scores))
+
+
+def f1_score(y_true: np.ndarray, y_pred: np.ndarray) -> float:
+    """Macro-averaged F1 score."""
+    yt: np.ndarray = np.array(y_true)
+    yp: np.ndarray = np.array(y_pred)
+    classes: np.ndarray = np.unique(yt)
+    scores: list[float] = []
+    for c in classes:
+        tp: int = int(np.sum((yp == c) & (yt == c)))
+        fp: int = int(np.sum((yp == c) & (yt != c)))
+        fn: int = int(np.sum((yp != c) & (yt == c)))
+        p: float = tp / (tp + fp) if (tp + fp) > 0 else 0.0
+        r: float = tp / (tp + fn) if (tp + fn) > 0 else 0.0
+        scores.append(2 * p * r / (p + r) if (p + r) > 0 else 0.0)
+    return float(np.mean(scores))
+
+
+# ---------------------------------------------------------------------------
+# Evaluator
+# ---------------------------------------------------------------------------
+
+class Evaluator:
+    """
+    Runs registered metrics by kind: regression or classification.
+
+    Built-in metrics are pre-registered per kind. New metrics can be added
+    at runtime via register() without modifying this class (Open/Closed Principle).
+    """
+
+    _regression_metrics: dict[str, callable] = {
+        "mae":  mae,
+        "mse":  mse,
+        "rmse": rmse,
+    }
+
+    _classification_metrics: dict[str, callable] = {
+        "accuracy":  accuracy,
+        "precision": precision,
+        "recall":    recall,
+        "f1":        f1_score,
+    }
+
+    @classmethod
+    def register(cls, name: str, fn: callable, kind: str = "regression") -> None:
+        """
+        Register a new metric function.
+
+        Parameters
+        ----------
+        name : metric name used as dict key
+        fn   : callable with signature (y_true, y_pred) -> float
+        kind : 'regression' (default) or 'classification'
+        """
+        if kind == "regression":
+            cls._regression_metrics[name] = fn
+        elif kind == "classification":
+            cls._classification_metrics[name] = fn
+        else:
+            raise ValueError(f"Unknown kind '{kind}'. Use 'regression' or 'classification'.")
+
+    @classmethod
+    def evaluate_regression(cls, y_true: np.ndarray, y_pred: np.ndarray) -> dict[str, float]:
+        """Run all registered regression metrics (mae, mse, rmse, ...)."""
+        return {name: fn(y_true, y_pred) for name, fn in cls._regression_metrics.items()}
+
+    @classmethod
+    def evaluate_classification(cls, y_true: np.ndarray, y_pred: np.ndarray) -> dict[str, float]:
+        """Run all registered classification metrics (accuracy, precision, recall, f1, ...)."""
+        return {name: fn(y_true, y_pred) for name, fn in cls._classification_metrics.items()}

coreLearn/knn.py

@@ -0,0 +1,210 @@
+from concurrent.futures import ProcessPoolExecutor
+
+import numpy as np
+
+from .base import BaseModel
+from .distances import DistanceMetricFactory
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _majority_vote(labels: list):
+    """Return the most frequent label in the list."""
+    counts: dict = {}
+    for label in labels:
+        counts[label] = counts.get(label, 0) + 1
+    return max(counts, key=lambda k: counts[k])
+
+
+def _predict_worker(args: tuple):
+    """
+    Module-level worker for ProcessPoolExecutor.
+
+    Must be defined at module level (not nested) so that Python's
+    multiprocessing can pickle it and send it to worker processes.
+
+    Each worker process receives its own copy of the KD-Tree and metric
+    via pickle — no shared memory, no data race.
+    """
+    tree, sample, k, metric = args
+    neighbours = tree.nearest_k(sample, k, metric)
+    return _majority_vote(neighbours)
+
+
+# ---------------------------------------------------------------------------
+# KD-Tree
+# ---------------------------------------------------------------------------
+
+class KDNode:
+    """A single node in a KD-Tree."""
+
+    def __init__(self, point: list, label, left=None, right=None):
+        self.point = point
+        self.label = label
+        self.left = left
+        self.right = right
+
+
+class KDTree:
+    """
+    Binary space-partitioning tree for fast nearest-neighbour lookups.
+
+    Both ``_build`` and ``_search`` are **recursive**, satisfying the
+    Recursion learning outcome.
+    """
+
+    def __init__(self, points: list, labels: list):
+        data = list(zip(points, labels))
+        self.root = self._build(data, depth=0)
+
+    # -- recursive build --
+
+    def _build(self, data: list, depth: int):
+        """Split data along alternating axes and return the root KDNode."""
+        if not data:
+            return None
+        k = len(data[0][0])
+        axis = depth % k
+        data.sort(key=lambda item: item[0][axis])
+        mid = len(data) // 2
+        return KDNode(
+            point=data[mid][0],
+            label=data[mid][1],
+            left=self._build(data[:mid], depth + 1),
+            right=self._build(data[mid + 1:], depth + 1),
+        )
+
+    # -- public query --
+
+    def nearest_k(self, target: list, k: int, metric) -> list:
+        """Return labels of the k nearest neighbours to *target*."""
+        best: list = []
+        self._search(self.root, target, k, metric, depth=0, best=best)
+        best.sort(key=lambda x: x[0])
+        return [label for _, label in best[:k]]
+
+    # -- recursive search --
+
+    def _search(self, node, target: list, k: int,
+                metric, depth: int, best: list) -> None:
+        """Recursively prune branches using the splitting-plane distance."""
+        if node is None:
+            return
+        dist = metric(target, node.point)
+
+        if len(best) < k:
+            best.append((dist, node.label))
+        elif dist < best[-1][0]:
+            best[-1] = (dist, node.label)
+        best.sort(key=lambda x: x[0])
+
+        axis = depth % len(target)
+        diff = target[axis] - node.point[axis]
+        near, far = (node.left, node.right) if diff <= 0 else (node.right, node.left)
+
+        self._search(near, target, k, metric, depth + 1, best)
+        if len(best) < k or abs(diff) < best[-1][0]:
+            self._search(far, target, k, metric, depth + 1, best)
+
+
+# ---------------------------------------------------------------------------
+# KNN Classifier
+# ---------------------------------------------------------------------------
+
+class KNNClassifier(BaseModel):
+    """
+    K-Nearest Neighbours classifier.
+
+    Uses a KD-Tree for efficient lookups (**Recursion**) and
+    ``ProcessPoolExecutor`` for **parallel** prediction across test samples
+    (**Concurrency**). Unlike threading, each worker runs in a separate
+    process with its own GIL — enabling true CPU-bound parallelism.
+
+    Parameters
+    ----------
+    k        : number of neighbours
+    distance : 'euclidean' (default) or 'manhattan'
+    n_jobs   : number of parallel worker processes during predict
+               (1 = no multiprocessing, sequential)
+    """
+
+    def __init__(self, k: int = 5, distance: str = "euclidean", n_jobs: int = 1):
+        if not isinstance(k, int) or k < 1:
+            raise ValueError(f"k must be a positive integer, got: {k!r}.")
+        if not isinstance(n_jobs, int) or n_jobs < 1:
+            raise ValueError(f"n_jobs must be a positive integer, got: {n_jobs!r}.")
+        self.k = k
+        self.n_jobs = n_jobs
+        self._metric = DistanceMetricFactory.create(distance) 
+        self._tree: KDTree | None = None
+        self._n_train: int = 0
+        self._n_features: int = 0
+
+    def fit(self, X, y) -> "KNNClassifier":
+        """Build the internal KD-Tree from training data."""
+        X = np.array(X, dtype=float)
+        y = list(y)
+
+        if X.ndim != 2:
+            raise ValueError(
+                f"X must be 2-D (n_samples, n_features), got shape {X.shape}."
+            )
+        if len(X) == 0:
+            raise ValueError("Training data X must not be empty.")
+        if len(y) == 0:
+            raise ValueError("Label vector y must not be empty.")
+        if len(X) != len(y):
+            raise ValueError(
+                f"X and y must have the same number of samples: {len(X)} != {len(y)}."
+            )
+        if self.k > len(X):
+            raise ValueError(
+                f"k ({self.k}) cannot be greater than the number of "
+                f"training samples ({len(X)})."
+            )
+
+        self._n_train = len(X)
+        self._n_features = X.shape[1]
+        self._tree = KDTree(X.tolist(), y)
+        return self
+
+    def _predict_one(self, x: list):
+        """Classify a single sample by majority vote among k neighbours."""
+        neighbours = self._tree.nearest_k(x, self.k, self._metric)
+        return _majority_vote(neighbours)
+
+    def predict(self, X) -> list:
+        """
+        Predict class labels for all samples in X.
+
+        n_jobs=1 : sequential prediction (no process overhead).
+        n_jobs>1 : samples are distributed across ``n_jobs`` worker processes
+                   via ``ProcessPoolExecutor``. Each process receives a
+                   pickled copy of the KD-Tree and metric — no shared memory,
+                   no data race, true CPU-level parallelism.
+        """
+        if self._tree is None:
+            raise RuntimeError("Call fit() before predict().")
+        raw = list(X) if not isinstance(X, np.ndarray) else X
+        if len(raw) == 0:
+            return []
+        X = np.array(X, dtype=float)
+        if X.ndim != 2:
+            raise ValueError(
+                f"X must be 2-D (n_samples, n_features), got shape {X.shape}."
+            )
+        if X.shape[1] != self._n_features:
+            raise ValueError(
+                f"Feature count mismatch: model was trained with {self._n_features} "
+                f"features, but X has {X.shape[1]}."
+            )
+        samples: list = X.tolist()
+
+        if self.n_jobs == 1:
+            return [self._predict_one(x) for x in samples]
+
+        args = [(self._tree, x, self.k, self._metric) for x in samples]
+        with ProcessPoolExecutor(max_workers=self.n_jobs) as executor:
+            return list(executor.map(_predict_worker, args))