epicon 0.3.0__tar.gz

epicon-0.3.0/LICENSE

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

epicon-0.3.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: epicon
+Version: 0.3.0
+Summary: Lightweight from-scratch ML library — neural nets, tree-based models, linear models, and more
+Author-email: Kebtes <kebtes@pm.me>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kebtes/epicon
+Project-URL: Repository, https://github.com/kebtes/epicon
+Project-URL: Documentation, https://github.com/kebtes/epicon#readme
+Project-URL: Changelog, https://github.com/kebtes/epicon/blob/main/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/kebtes/epicon/issues
+Keywords: machine-learning,neural-networks,decision-trees,numpy,ml-library
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Provides-Extra: numba
+Requires-Dist: numba>=0.56; extra == "numba"
+Provides-Extra: all
+Requires-Dist: epicon[numba]; extra == "all"
+Dynamic: license-file
+
+# Epicon
+
+A **lightweight, from-scratch** machine learning library built on NumPy with
+optional Numba acceleration. Provides a unified API for neural networks
+**and** traditional ML models.
+
+Designed to be minimal yet capable — like **Flask for ML**.
+
+## Quick Start
+
+```python
+import epicon
+from epicon.datasets import load_iris
+from epicon.preprocessing import train_test_split
+from epicon.metrics import accuracy_score
+
+# Load data
+X, y = load_iris(return_X_y=True)
+X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.3)
+
+# Train a model
+model = epicon.DecisionTreeClassifier(max_depth=5)
+model.fit(X_train, y_train)
+
+# Evaluate
+y_pred = model.predict(X_test)
+print(f"Accuracy: {accuracy_score(y_test, y_pred):.4f}")
+```
+
+## What's Included
+
+### Neural Networks
+- Layers: `Dense`, `Dropout`, `Conv1D`
+- Activations: `ReLU`, `LeakyReLU`, `Sigmoid`, `Softmax`, `Tanh`
+- Losses: `MSE`, `BinaryCrossEntropy`, `CategoricalCrossEntropy`
+- Optimizers: `GradientDescent`, `Momentum`, `Adam`
+- `Model` — layer-by-layer construction
+- `Sequential` — Keras-style wrapper with string activations
+
+### Traditional ML Models
+- `LinearRegression`, `Ridge`, `Lasso`, `LogisticRegression`
+- `KNeighborsClassifier`, `KNeighborsRegressor`
+- `GaussianNB`
+- `DecisionTreeClassifier`, `DecisionTreeRegressor`
+- `RandomForestClassifier`, `RandomForestRegressor`
+
+### Utilities
+- Preprocessing: `StandardScaler`, `MinMaxScaler`, `LabelEncoder`, `OneHotEncoder`, `train_test_split`
+- Datasets: `load_iris`, `load_mnist`, `make_classification`, `make_regression`
+- Metrics: `accuracy_score`, `precision_score`, `recall_score`, `f1_score`, `confusion_matrix`, `mean_squared_error`, `mean_absolute_error`, `r2_score`
+
+## Installation
+
+```bash
+# Minimal install (NumPy required)
+pip install numpy
+
+# Install Epicon from source
+pip install -e .
+
+# With Numba (optional, for faster tree/KNN)
+pip install numba
+```
+
+## Design
+
+- **Consistent API**: all models follow `fit(X, y)` / `predict(X)`.
+- **Minimal dependencies**: only NumPy is required.
+- **Optional acceleration**: Numba JIT for tree split search and KNN.
+- **Educational**: readable, fully documented source code.
+- **Tested**: 169+ unit tests with pytest.
+
+## Examples
+
+See the [examples/](examples/) directory:
+
+- `example_ml_iris.py` — Decision tree on Iris dataset
+- `example_ml_binary.py` — LogisticRegression with L2 penalty
+- `example_ml_forest.py` — RandomForestRegressor on synthetic data
+- `example_nn_sequential.py` — Sequential neural net with Adam on MNIST

epicon-0.3.0/README.md

@@ -0,0 +1,80 @@
+# Epicon
+
+A **lightweight, from-scratch** machine learning library built on NumPy with
+optional Numba acceleration. Provides a unified API for neural networks
+**and** traditional ML models.
+
+Designed to be minimal yet capable — like **Flask for ML**.
+
+## Quick Start
+
+```python
+import epicon
+from epicon.datasets import load_iris
+from epicon.preprocessing import train_test_split
+from epicon.metrics import accuracy_score
+
+# Load data
+X, y = load_iris(return_X_y=True)
+X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.3)
+
+# Train a model
+model = epicon.DecisionTreeClassifier(max_depth=5)
+model.fit(X_train, y_train)
+
+# Evaluate
+y_pred = model.predict(X_test)
+print(f"Accuracy: {accuracy_score(y_test, y_pred):.4f}")
+```
+
+## What's Included
+
+### Neural Networks
+- Layers: `Dense`, `Dropout`, `Conv1D`
+- Activations: `ReLU`, `LeakyReLU`, `Sigmoid`, `Softmax`, `Tanh`
+- Losses: `MSE`, `BinaryCrossEntropy`, `CategoricalCrossEntropy`
+- Optimizers: `GradientDescent`, `Momentum`, `Adam`
+- `Model` — layer-by-layer construction
+- `Sequential` — Keras-style wrapper with string activations
+
+### Traditional ML Models
+- `LinearRegression`, `Ridge`, `Lasso`, `LogisticRegression`
+- `KNeighborsClassifier`, `KNeighborsRegressor`
+- `GaussianNB`
+- `DecisionTreeClassifier`, `DecisionTreeRegressor`
+- `RandomForestClassifier`, `RandomForestRegressor`
+
+### Utilities
+- Preprocessing: `StandardScaler`, `MinMaxScaler`, `LabelEncoder`, `OneHotEncoder`, `train_test_split`
+- Datasets: `load_iris`, `load_mnist`, `make_classification`, `make_regression`
+- Metrics: `accuracy_score`, `precision_score`, `recall_score`, `f1_score`, `confusion_matrix`, `mean_squared_error`, `mean_absolute_error`, `r2_score`
+
+## Installation
+
+```bash
+# Minimal install (NumPy required)
+pip install numpy
+
+# Install Epicon from source
+pip install -e .
+
+# With Numba (optional, for faster tree/KNN)
+pip install numba
+```
+
+## Design
+
+- **Consistent API**: all models follow `fit(X, y)` / `predict(X)`.
+- **Minimal dependencies**: only NumPy is required.
+- **Optional acceleration**: Numba JIT for tree split search and KNN.
+- **Educational**: readable, fully documented source code.
+- **Tested**: 169+ unit tests with pytest.
+
+## Examples
+
+See the [examples/](examples/) directory:
+
+- `example_ml_iris.py` — Decision tree on Iris dataset
+- `example_ml_binary.py` — LogisticRegression with L2 penalty
+- `example_ml_forest.py` — RandomForestRegressor on synthetic data
+- `example_nn_sequential.py` — Sequential neural net with Adam on MNIST

epicon-0.3.0/epicon/__init__.py

@@ -0,0 +1,78 @@
+"""
+============================================================
+Epicon
+============================================================
+
+A lightweight, from-scratch machine learning library built on
+NumPy with optional Numba acceleration. Provides a unified API
+for neural networks and traditional ML models, designed to be
+a minimal yet capable alternative to PyTorch/TensorFlow for
+everyday ML tasks.
+
+Key Design Principles:
+    - Simple, consistent API (fit/predict) across all models
+    - Minimal dependencies (NumPy required, Numba optional)
+    - Educational transparency — readable, documented source
+    - Fast execution via vectorized NumPy and optional Numba JIT
+
+Quick Start:
+    >>> import epicon
+    >>> from epicon.datasets import load_iris
+    >>> X, y = load_iris(return_X_y=True)
+    >>> model = epicon.LogisticRegression()
+    >>> model.fit(X, y)
+    >>> model.predict(X[:5])
+"""
+
+# ---------------------------------------------------------------------------
+# Neural Network Components
+# ---------------------------------------------------------------------------
+from epicon.activations import Activation, LeakyReLU, ReLU, Sigmoid, Softmax, Tanh
+
+# ---------------------------------------------------------------------------
+# Datasets
+# ---------------------------------------------------------------------------
+from epicon.datasets import load_iris, load_mnist, make_classification, make_regression
+from epicon.ensemble import RandomForestClassifier, RandomForestRegressor
+from epicon.layers import Conv1D, Dense, Dropout, Layer
+
+# ---------------------------------------------------------------------------
+# Traditional ML Models
+# ---------------------------------------------------------------------------
+from epicon.linear_model import Lasso, LinearRegression, LogisticRegression, Ridge
+from epicon.losses import MSE, BinaryCrossEntropy, CategoricalCrossEntropy, Loss
+
+# ---------------------------------------------------------------------------
+# Metrics
+# ---------------------------------------------------------------------------
+from epicon.metrics import (
+    accuracy_score,
+    confusion_matrix,
+    f1_score,
+    mean_absolute_error,
+    mean_squared_error,
+    precision_score,
+    r2_score,
+    recall_score,
+)
+from epicon.models import Model, Sequential
+from epicon.naive_bayes import GaussianNB
+from epicon.neighbors import KNeighborsClassifier, KNeighborsRegressor
+from epicon.optimizers import Adam, GradientDescent, Momentum, Optimizer
+
+# ---------------------------------------------------------------------------
+# Preprocessing & Utilities
+# ---------------------------------------------------------------------------
+from epicon.preprocessing import (
+    LabelEncoder,
+    MinMaxScaler,
+    OneHotEncoder,
+    StandardScaler,
+    train_test_split,
+)
+from epicon.tree import DecisionTreeClassifier, DecisionTreeRegressor
+
+# ---------------------------------------------------------------------------
+# Version
+# ---------------------------------------------------------------------------
+__version__ = "0.3.0"

epicon-0.3.0/epicon/_jit.py

@@ -0,0 +1,250 @@
+"""
+---------------------------------------------------------
+NUMBA JIT COMPILED KERNELS FOR PERFORMANCE-CRITICAL LOOPS
+---------------------------------------------------------
+
+Optional Numba acceleration for tree-based models, KNN,
+and other algorithms with non-vectorizable loops.
+If Numba is not installed, pure Python fallbacks are used.
+"""
+
+import numpy as np
+
+try:
+    import numba as nb
+
+    HAS_NUMBA = True
+except ImportError:
+    HAS_NUMBA = False
+    nb = None
+
+
+def _jit_if_available(func=None, *, nopython=True, parallel=False, **kwargs):
+    """
+    Decorator that applies Numba JIT only if Numba is installed.
+    Can be used with or without arguments.
+
+    Usage:
+        @_jit_if_available
+        def my_func(x): ...
+
+        @_jit_if_available(nopython=True, parallel=True)
+        def my_func(x): ...
+    """
+
+    def decorator(f):
+        if HAS_NUMBA:
+            return nb.jit(f, nopython=nopython, parallel=parallel, **kwargs)
+        return f
+
+    if func is not None:
+        return decorator(func)
+    return decorator
+
+
+# ---------------------------------------------------------------------------
+# Tree split helpers
+# ---------------------------------------------------------------------------
+
+
+@_jit_if_available
+def _gini_impurity(left_counts, right_counts, total_left, total_right, total_samples):
+    """
+    Compute weighted Gini impurity for a binary split.
+
+    Args:
+        left_counts (np.ndarray): Class counts in left child.
+        right_counts (np.ndarray): Class counts in right child.
+        total_left (int): Total samples in left child.
+        total_right (int): Total samples in right child.
+        total_samples (int): Total samples in parent.
+
+    Returns:
+        float: Weighted Gini impurity of the split.
+    """
+    if total_left == 0 or total_right == 0:
+        return 0.0
+
+    left_gini = 1.0 - np.sum((left_counts / total_left) ** 2)
+    right_gini = 1.0 - np.sum((right_counts / total_right) ** 2)
+
+    return (total_left / total_samples) * left_gini + (total_right / total_samples) * right_gini
+
+
+@_jit_if_available
+def _entropy_impurity(left_counts, right_counts, total_left, total_right, total_samples):
+    """
+    Compute weighted entropy for a binary split.
+
+    Args:
+        left_counts (np.ndarray): Class counts in left child.
+        right_counts (np.ndarray): Class counts in right child.
+        total_left (int): Total samples in left child.
+        total_right (int): Total samples in right child.
+        total_samples (int): Total samples in parent.
+
+    Returns:
+        float: Weighted entropy of the split.
+    """
+    if total_left == 0 or total_right == 0:
+        return 0.0
+
+    def _entropy(counts, total):
+        if total == 0:
+            return 0.0
+        probs = counts / total
+        probs = probs[probs > 0]
+        return -np.sum(probs * np.log2(probs))
+
+    left_ent = _entropy(left_counts, total_left)
+    right_ent = _entropy(right_counts, total_right)
+
+    return (total_left / total_samples) * left_ent + (total_right / total_samples) * right_ent
+
+
+@_jit_if_available
+def _mse_split(left_y, right_y):
+    """
+    Compute weighted MSE for a binary split.
+
+    Args:
+        left_y (np.ndarray): Target values in left child.
+        right_y (np.ndarray): Target values in right child.
+
+    Returns:
+        float: Weighted MSE of the split.
+    """
+    total = len(left_y) + len(right_y)
+    if total == 0:
+        return 0.0
+
+    left_mse = np.var(left_y) * len(left_y) if len(left_y) > 0 else 0.0
+    right_mse = np.var(right_y) * len(right_y) if len(right_y) > 0 else 0.0
+
+    return (left_mse + right_mse) / total
+
+
+@_jit_if_available
+def _best_split_numeric(X_column, y, num_classes, criterion, min_samples_split, min_samples_leaf):
+    """
+    Find the best threshold for a numeric feature.
+
+    Args:
+        X_column (np.ndarray): Feature values (sorted).
+        y (np.ndarray): Target values.
+        num_classes (int): Number of classes (1 for regression).
+        criterion (str): 'gini', 'entropy', or 'mse'.
+        min_samples_split (int): Minimum samples to split.
+        min_samples_leaf (int): Minimum samples per leaf.
+
+    Returns:
+        tuple: (best_threshold, best_impurity) or (None, inf).
+    """
+    n = len(X_column)
+    best_threshold = None
+    best_score = np.inf
+
+    if n < min_samples_split:
+        return None, np.inf
+
+    # Unique thresholds at midpoints between sorted values
+    unique_vals = np.unique(X_column)
+    if len(unique_vals) == 1:
+        return None, np.inf
+
+    thresholds = (unique_vals[:-1] + unique_vals[1:]) / 2.0
+
+    for threshold in thresholds:
+        left_mask = X_column <= threshold
+        right_mask = ~left_mask
+
+        left_count = np.sum(left_mask)
+        right_count = np.sum(right_mask)
+
+        if left_count < min_samples_leaf or right_count < min_samples_leaf:
+            continue
+
+        if criterion == "mse":
+            score = _mse_split(y[left_mask], y[right_mask])
+        elif criterion in ("gini", "entropy"):
+            left_y = y[left_mask].astype(np.int64)
+            right_y = y[right_mask].astype(np.int64)
+
+            left_counts = np.zeros(num_classes, dtype=np.float64)
+            right_counts = np.zeros(num_classes, dtype=np.float64)
+
+            for c in range(num_classes):
+                left_counts[c] = np.sum(left_y == c)
+                right_counts[c] = np.sum(right_y == c)
+
+            if criterion == "gini":
+                score = _gini_impurity(left_counts, right_counts, left_count, right_count, n)
+            else:
+                score = _entropy_impurity(left_counts, right_counts, left_count, right_count, n)
+        else:
+            raise ValueError(f"Unknown criterion: {criterion}")
+
+        if score < best_score:
+            best_score = score
+            best_threshold = threshold
+
+    return best_threshold, best_score
+
+
+# ---------------------------------------------------------------------------
+# KNN distance helpers
+# ---------------------------------------------------------------------------
+
+
+@_jit_if_available
+def _euclidean_distance(x1, x2):
+    """
+    Compute Euclidean distance between two vectors.
+    """
+    diff = x1 - x2
+    return np.sqrt(np.dot(diff, diff))
+
+
+@_jit_if_available
+def _manhattan_distance(x1, x2):
+    """
+    Compute Manhattan distance between two vectors.
+    """
+    return np.sum(np.abs(x1 - x2))
+
+
+@_jit_if_available
+def _knn_predict_single(x_test, X_train, y_train, k, metric="euclidean"):
+    """
+    Predict label for a single test point using KNN.
+
+    Args:
+        x_test (np.ndarray): Single test sample.
+        X_train (np.ndarray): Training data.
+        y_train (np.ndarray): Training labels.
+        k (int): Number of neighbors.
+        metric (str): 'euclidean' or 'manhattan'.
+
+    Returns:
+        float: Predicted label (for classification, returns the majority class).
+    """
+    n_train = X_train.shape[0]
+    distances = np.zeros(n_train)
+
+    for i in range(n_train):
+        if metric == "euclidean":
+            distances[i] = _euclidean_distance(x_test, X_train[i])
+        else:
+            distances[i] = _manhattan_distance(x_test, X_train[i])
+
+    # Get indices of k smallest distances
+    indices = np.argsort(distances)[:k]
+    k_nearest = y_train[indices]
+
+    # For regression, return mean; for classification, return mode
+    if np.issubdtype(y_train.dtype, np.floating) or len(np.unique(y_train)) > 20:
+        return np.mean(k_nearest)
+    else:
+        # Return mode (most common)
+        counts = np.bincount(k_nearest.astype(np.int64))
+        return np.argmax(counts)

epicon-0.3.0/epicon/activations/__init__.py

@@ -0,0 +1,8 @@
+from epicon.activations.base import Activation
+from epicon.activations.leaky_relu import LeakyReLU
+from epicon.activations.relu import ReLU
+from epicon.activations.sigmoid import Sigmoid
+from epicon.activations.softmax import Softmax
+from epicon.activations.tanh import Tanh
+
+__all__ = ["Activation", "ReLU", "Softmax", "Sigmoid", "LeakyReLU", "Tanh"]

epicon-0.3.0/epicon/activations/base.py

@@ -0,0 +1,21 @@
+from epicon.layers.base import Layer
+
+
+class Activation(Layer):
+    """
+    -----------------------------------
+    BASE CLASS FOR ACTIVATION FUNCTIONS
+    -----------------------------------
+    """
+
+    def __init__(self):
+        super().__init__()
+
+    def forward(self, inputs):
+        raise NotImplementedError
+
+    def backward(self, dvalues):
+        raise NotImplementedError
+
+    def get_params(self):
+        return super().get_params()

epicon-0.3.0/epicon/activations/leaky_relu.py

@@ -0,0 +1,65 @@
+from typing import override
+
+import numpy as np
+
+from epicon.activations.base import Activation
+
+
+class LeakyReLU(Activation):
+    """
+    -----------------------------------------------
+              LEAKY RELU ACTIVATION FUNCTION
+    f(x) = x if x > 0, otherwise f(x) = α * x
+    This prevents neurons from "dying" by allowing a small,
+    non-zero gradient when the unit is not active.
+    -----------------------------------------------
+    """
+
+    def __init__(self, alpha=0.01):
+        """
+        Initialize the LeakyReLU with a given alpha.
+
+        Parameters:
+            alpha (float): the small constant multiplier for negative inputs. Default is 0.01.
+        """
+        self.alpha = alpha
+
+    def forward(self, inputs):
+        """
+        The forward pass applies the LeakyReLU function.
+
+        Parameters:
+            inputs (ndarray): input data to the layer
+
+        Returns:
+            output (ndarray): transformed output of the layer
+        """
+        self.inputs = inputs
+        # For each element, if positive keep it; if negative, multiply by alpha
+        self.output = np.where(inputs > 0, inputs, self.alpha * inputs)
+        return self.output
+
+    def backward(self, dvalues):
+        """
+        The backward pass computes the gradient of the loss with respect to the inputs.
+
+        Parameters:
+            dvalues (ndarray): the gradient from the next layer
+
+        Returns:
+            dinputs (ndarray): the gradient with respect to the inputs of this layer
+        """
+        # Initialize gradient as a copy of dvalues
+        self.dinputs = np.copy(dvalues)
+        # For inputs <= 0, multiply the gradient by alpha
+        self.dinputs[self.inputs <= 0] *= self.alpha
+        return self.dinputs
+
+    @override
+    def get_params(self):
+        return {"type": "LeakyReLU", "attrs": {"alpha": self.alpha}}
+
+    @override
+    def set_params(self, params: dict):
+        for key, val in params.items():
+            setattr(self, key, val)

epicon-0.3.0/epicon/activations/relu.py

@@ -0,0 +1,37 @@
+from typing import override
+
+import numpy as np
+
+from epicon.activations.base import Activation
+
+
+class ReLU(Activation):
+    """
+    -----------------------------------------------
+    RECTIFIED LINEAR UNIT (ReLU) ACTIVATION FUNCTION
+    f(x) = max(0, x)
+    -----------------------------------------------
+    """
+
+    def forward(self, inputs):
+        """
+        The `forward` function takes an input array, applies a ReLU activation function element-wise,
+        and returns the resulting output array.
+        """
+        self.inputs = inputs
+        self.output = np.maximum(0, inputs)
+        return self.output
+
+    def backward(self, dvalues):
+        """
+        The `backward` function calculates the derivative of the inputs with respect to the given values
+        and sets the derivative to zero for inputs less than or equal to zero.
+        """
+
+        self.dinputs = dvalues.copy()
+        self.dinputs[self.inputs <= 0] = 0
+        return self.dinputs
+
+    @override
+    def get_params(self):
+        return {"type": "ReLU", "attrs": {}}