phitodeep 0.1.3__tar.gz

phitodeep-0.1.3/LICENSE

@@ -0,0 +1,16 @@
+Apache Software License 2.0
+
+Copyright (c) 2026, Ralph Dugue
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+

phitodeep-0.1.3/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: phitodeep
+Version: 0.1.3
+Summary: Deep learning framework built from scratch with numpy!
+License: Apache-2.0
+License-File: LICENSE
+Author: Ralph Dugue
+Requires-Python: >=3.12,<4.0
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: numpy (>=2.4.4,<3.0.0)
+Description-Content-Type: text/markdown
+
+# phitodeep
+
+Deep learning framework built from scratch with numpy!
+
+## Installation
+
+```bash
+$ pip install phitodeep
+```
+
+## Usage
+MNIST quickstart:
+```python
+import numpy as np
+from datasets import load_dataset
+
+import phitodeep.loss as loss
+import phitodeep.model as m
+
+train_dataset = load_dataset("ylecun/mnist", split="train")
+test_dataset = load_dataset("ylecun/mnist", split="test")
+
+X_train = train_dataset["image"]
+y_train = train_dataset["label"]
+X_test = test_dataset["image"]
+y_test = test_dataset["label"]
+
+X_train = np.array(X_train).astype(np.float32) / 255.0
+y_train = np.array(y_train)
+X_test = np.array(X_test).astype(np.float32) / 255.0
+y_test = np.array(y_test)
+print(X_train.shape, y_train.shape)
+
+model = (
+    m.SequentialBuilder()
+    .flatten()
+    .dense(784, 128)
+    .relu()
+    .dense(128, 10)
+    .softmax()
+    .optimizer("adam")
+    .loss(loss.CategoricalCrossEntropy())
+    .alpha(0.001)
+    .epochs(300)
+    .batch(32)
+    .build()
+)
+
+model.summary()
+
+model.train(X_train, y_train, X_test, y_test)
+
+```
+
+## Contributing
+
+Interested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.
+
+## License
+
+`phitodeep` was created by Ralph Dugue. It is licensed under the terms of the Apache License 2.0 license.
+
+## Credits
+
+`phitodeep` was created with [`cookiecutter`](https://cookiecutter.readthedocs.io/en/latest/) and the `py-pkgs-cookiecutter` [template](https://github.com/py-pkgs/py-pkgs-cookiecutter).
+

phitodeep-0.1.3/README.md

@@ -0,0 +1,65 @@
+# phitodeep
+
+Deep learning framework built from scratch with numpy!
+
+## Installation
+
+```bash
+$ pip install phitodeep
+```
+
+## Usage
+MNIST quickstart:
+```python
+import numpy as np
+from datasets import load_dataset
+
+import phitodeep.loss as loss
+import phitodeep.model as m
+
+train_dataset = load_dataset("ylecun/mnist", split="train")
+test_dataset = load_dataset("ylecun/mnist", split="test")
+
+X_train = train_dataset["image"]
+y_train = train_dataset["label"]
+X_test = test_dataset["image"]
+y_test = test_dataset["label"]
+
+X_train = np.array(X_train).astype(np.float32) / 255.0
+y_train = np.array(y_train)
+X_test = np.array(X_test).astype(np.float32) / 255.0
+y_test = np.array(y_test)
+print(X_train.shape, y_train.shape)
+
+model = (
+    m.SequentialBuilder()
+    .flatten()
+    .dense(784, 128)
+    .relu()
+    .dense(128, 10)
+    .softmax()
+    .optimizer("adam")
+    .loss(loss.CategoricalCrossEntropy())
+    .alpha(0.001)
+    .epochs(300)
+    .batch(32)
+    .build()
+)
+
+model.summary()
+
+model.train(X_train, y_train, X_test, y_test)
+
+```
+
+## Contributing
+
+Interested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.
+
+## License
+
+`phitodeep` was created by Ralph Dugue. It is licensed under the terms of the Apache License 2.0 license.
+
+## Credits
+
+`phitodeep` was created with [`cookiecutter`](https://cookiecutter.readthedocs.io/en/latest/) and the `py-pkgs-cookiecutter` [template](https://github.com/py-pkgs/py-pkgs-cookiecutter).

phitodeep-0.1.3/pyproject.toml

@@ -0,0 +1,27 @@
+[tool.poetry]
+name = "phitodeep"
+version = "0.1.3"
+description = "Deep learning framework built from scratch with numpy!"
+authors = ["Ralph Dugue"]
+license = "Apache License 2.0"
+readme = "README.md"
+packages = [{include = "phitodeep", from = "src"}]
+
+[tool.poetry.dependencies]
+python = "^3.12"
+numpy = "^2.4.4"
+
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[dependency-groups]
+dev = [
+    "ipykernel (>=7.2.0,<8.0.0)",
+    "myst-nb (>=1.4.0,<2.0.0)",
+    "sphinx-autoapi (>=3.8.0,<4.0.0)",
+    "sphinx-rtd-theme (>=3.1.0,<4.0.0)",
+    "pillow (>=12.2.0,<13.0.0)",
+    "datasets (>=4.8.4,<5.0.0)"
+]

phitodeep-0.1.3/src/phitodeep/layers/activation.py

@@ -0,0 +1,106 @@
+import numpy as np
+
+from .base import Layer
+
+
+class ReLu(Layer):
+    def __init__(self) -> None:
+        super().__init__("relu")
+
+    def forward(self, X):
+        self.cache["X"] = X
+        return np.maximum(0, X)
+
+    def backward(self, dL_dZ):
+        """
+        Backpropagate through ReLU activation.
+        ReLU derivative: 1 if X > 0, else 0
+        """
+        X = self.cache["X"]
+        dL_dX = dL_dZ * (X > 0).astype(float)
+        return dL_dX
+
+
+class Sigmoid(Layer):
+    def __init__(self) -> None:
+        super().__init__("sigmoid")
+
+    def forward(self, X):
+        self.cache["X"] = X
+        self.cache["Z"] = 1 / (1 + np.exp(-X))
+        return self.cache["Z"]
+
+    def backward(self, dL_dZ):
+        """
+        Backpropagate through Sigmoid activation.
+        Sigmoid derivative: sigmoid(Z) * (1 - sigmoid(Z))
+        """
+        Z = self.cache["Z"]
+        dL_dX = dL_dZ * Z * (1 - Z)
+        return dL_dX
+
+
+class Tanh(Layer):
+    def __init__(self) -> None:
+        super().__init__("tanh")
+
+    def forward(self, X):
+        self.cache["X"] = X
+        e_x = np.exp(X)
+        e_neg_x = np.exp(-X)
+        self.cache["Z"] = (e_x - e_neg_x) / (e_x + e_neg_x)
+        return self.cache["Z"]
+
+    def backward(self, dL_dZ):
+        """
+        Backpropagate through Tanh activation.
+        Tanh derivative: 1 - tanh(Z)^2
+        """
+        Z = self.cache["Z"]
+        dL_dX = dL_dZ * (1 - Z**2)
+        return dL_dX
+
+
+class Softmax(Layer):
+    def __init__(self) -> None:
+        super().__init__("softmax")
+
+    def forward(self, X):
+        self.cache["X"] = X
+        axis = None if X.ndim < 2 else 1
+        max_a = np.max(X, axis=axis, keepdims=True)
+
+        dividend = np.exp(X - max_a)
+        divisor = np.sum(np.exp(X - max_a), axis=axis, keepdims=True)
+
+        self.cache["Z"] = dividend / divisor
+        return self.cache["Z"]
+
+    def backward(self, dL_dZ):
+        """
+        Backpropagate through Softmax activation.
+        When paired with CategoricalCrossEntropy, the combined gradient
+        (y_pred - one_hot(y_true)) / N is computed entirely in the loss,
+        so this layer is a straight pass-through.
+        """
+        return dL_dZ
+
+
+class ELU(Layer):
+    def __init__(self, alpha=1.0) -> None:
+        super().__init__("elu")
+        self.alpha_activation = alpha
+
+    def forward(self, X):
+        self.cache["X"] = X
+        self.cache["Z"] = np.where(X > 0, X, self.alpha_activation * (np.exp(X) - 1))
+        return self.cache["Z"]
+
+    def backward(self, dL_dZ):
+        """
+        Backpropagate through ELU activation.
+        ELU derivative: 1 if X > 0, else alpha * exp(X)
+        """
+        X = self.cache["X"]
+        dL_dX = dL_dZ * np.where(X > 0, 1.0, self.alpha_activation * np.exp(X))
+        return dL_dX

phitodeep-0.1.3/src/phitodeep/layers/base.py

@@ -0,0 +1,85 @@
+import numpy as np
+
+
+class Layer:
+    def __init__(self, name) -> None:
+        self.name = name
+        self.cache = {}
+        self.grads = {}
+
+    def forward(self, X):
+        raise NotImplementedError(f"Block '{self.name}' must implement forward method")
+
+    def backward(self, dL_dZ):
+        """
+        Backward pass through the block.
+
+        Args:
+            dL_dZ: gradient of loss w.r.t. output of this block
+
+        Returns:
+            dL_dX: gradient of loss w.r.t. input (to pass to previous layer)
+        """
+        raise NotImplementedError(f"Block '{self.name}' must implement backward method")
+
+
+class Flatten(Layer):
+    def __init__(self):
+        super().__init__("flatten")
+
+    def forward(self, X):
+        """
+        X: (batch_size, ...) -> (batch_size, ...)
+        """
+        self.cache["X"] = X
+        return X.reshape(X.shape[0], -1)
+
+    def backward(self, dL_dZ):
+        """
+        dL_dZ: (batch_size, ...) -> (batch_size, ...)
+        """
+        X = self.cache["X"]
+        return dL_dZ.reshape(X.shape)
+
+
+class Dense(Layer):
+    def __init__(self, input_size, output_size):
+        super().__init__("dense")
+        self.grads = {}
+        self.input_size = input_size
+        self.output_size = output_size
+        # Initialize weights and biases
+        self.W = np.random.randn(input_size, output_size) * np.sqrt(2.0 / input_size)
+        self.b = np.zeros(output_size)
+
+    def forward(self, X):
+        """
+        X: (batch_size, input_size) -> (batch_size, output_size)
+        """
+        self.cache["X"] = X
+        Z = np.dot(X, self.W) + self.b
+        return Z
+
+    def backward(self, dL_dZ):
+        """
+        Backpropagate through Dense layer.
+
+        Args:
+            dL_dZ: (batch_size, output_size) - gradient of loss w.r.t. output
+
+        Returns:
+            dL_dX: (batch_size, input_size) - gradient to pass to previous layer
+        """
+        X = self.cache["X"]
+        m = X.shape[0]  # batch size
+
+        # Gradient w.r.t. weights: (1/m) * X^T @ dL_dZ
+        self.grads["W"] = np.dot(X.T, dL_dZ) / m
+
+        # Gradient w.r.t. bias: (1/m) * sum(dL_dZ)
+        self.grads["b"] = np.sum(dL_dZ, axis=0) / m
+
+        # Gradient w.r.t. input: dL_dZ @ W^T
+        dL_dX = np.dot(dL_dZ, self.W.T)
+
+        return dL_dX

phitodeep-0.1.3/src/phitodeep/loss.py

@@ -0,0 +1,56 @@
+import numpy as np
+
+
+class LossBase:
+    def __init__(self, name) -> None:
+        self.name = name
+
+    def loss_func(self, y_pred, y_true):
+        raise NotImplementedError(f"{self.name} must implement the loss_func method.")
+
+    def loss_gradient(self, y_pred, y_true):
+        raise NotImplementedError(
+            f"{self.name} must implement the loss_gradient method."
+        )
+
+
+class MeanSquaredError(LossBase):
+    def __init__(self) -> None:
+        super().__init__("MeanSquaredError")
+
+    def loss_func(self, y_pred, y_true):
+        return np.mean((y_pred - y_true) ** 2)
+
+    def loss_gradient(self, y_pred, y_true):
+        m = len(y_true)
+        return 2 * (y_pred - y_true) / m
+
+
+class CategoricalCrossEntropy(LossBase):
+    def __init__(self) -> None:
+        super().__init__("CategoricalCrossEntropy")
+
+    def loss_func(self, y_pred, y_true):
+        N = len(y_true)
+        correct = y_pred[np.arange(N), y_true]
+        return -np.mean(np.log(correct + 1e-8))
+
+    def loss_gradient(self, y_pred, y_true):
+        # Fused Softmax + CCE gradient: (y_pred - one_hot(y_true)) / N
+        N = len(y_true)
+        grad = y_pred.copy()
+        grad[np.arange(N), y_true] -= 1.0
+        return grad / N
+
+
+class BinaryCrossEntropy(LossBase):
+    def __init__(self) -> None:
+        super().__init__("BinaryCrossEntropy")
+
+    def loss_func(self, y_pred, y_true):
+        return -np.mean(
+            y_true * np.log(y_pred + 1e-8) + (1 - y_true) * np.log(1 - y_pred + 1e-8)
+        )
+
+    def loss_gradient(self, y_pred, y_true):
+        return (y_pred - y_true) / (y_pred * (1 - y_pred) + 1e-8)

phitodeep-0.1.3/src/phitodeep/model.py

@@ -0,0 +1,213 @@
+from . import loss as ls
+from . import optimization
+from .layers import activation as a
+from .layers import base as b
+
+
+class Sequential:
+    def __init__(
+        self,
+        *layers,
+        alpha=0.01,
+        optimizer="adam",
+        batch_size=1,
+        epochs=1000,
+        loss_class=ls.MeanSquaredError(),
+    ) -> None:
+        """
+        Initialize with variable number of layers.
+
+        Usage:
+            model = Sequential(
+                b.Dense(256, 128),
+                a.ReLu(),
+                b.Dense(128, 1),
+                a.Sigmoid()
+            )
+        """
+        self.layers = list(layers)
+        self.alpha = alpha
+        self.optimizer = optimizer
+        self.batch_size = batch_size
+        self.epochs = epochs
+        self.loss_class = loss_class
+
+    def add(self, layer) -> None:
+        """Add a layer to the network."""
+        self.layers.append(layer)
+
+    def setoptimizer(self, name):
+        self.optimizer = name
+
+    def setbatchsize(self, num):
+        self.batch_size = num
+
+    def setloss(self, loss_class):
+        self.loss_class = loss_class
+
+    def train(self, X, y, X_test, y_test):
+        match self.optimizer:
+            case "sgd":
+                optimizer = optimization.SGD(alpha=self.alpha)
+            case "adam":
+                optimizer = optimization.Adam(alpha=self.alpha)
+            case _:
+                raise ValueError(f"{self.optimizer} is not a valid optimizer.")
+
+        losses = optimization.train_loop(
+            model=self,
+            X=X,
+            y=y,
+            X_test=X_test,
+            y_test=y_test,
+            optimizer=optimizer,
+            loss_class=self.loss_class,
+            batch_size=self.batch_size,
+            epochs=self.epochs,
+        )
+
+        print("Training complete.")
+        print("-" * 60)
+        print(f"Starting Training Loss: {losses[0][0]:.4f} | Starting Test Loss: {losses[0][1]:.4f}")
+        print(f"Final Training Loss: {losses[-1][0]:.4f} | Final Test Loss: {losses[-1][1]:.4f}")
+        print(f"Training Loss Improvement: {losses[0][0] - losses[-1][0]:.4f} | Test Loss Improvement: {losses[0][1] - losses[-1][1]:.4f}")
+        print("-" * 60)
+        return losses
+
+    def predict(self, X):
+        """
+        Forward pass through all layers.
+
+        Args:
+            X: input array
+
+        Returns:
+            output after passing through all layers
+        """
+        output = X
+        for layer in self.layers:
+            output = layer.forward(output)
+        return output
+
+    def backward(self, gradient):
+        """
+        Backward pass through all layers.
+
+        Args:
+            gradient: dL/dY from loss function (shape: batch_size x output_size)
+
+        Propagates gradient backwards through all layers in reverse order.
+        Each layer computes its parameter gradients, updates parameters,
+        and returns the gradient for the previous layer.
+        """
+        # Start with gradient from loss and propagate backwards
+        current_gradient = gradient
+
+        # Iterate through layers in reverse order
+        for layer in reversed(self.layers):
+            # Pass gradient through layer and get gradient for previous layer
+            current_gradient = layer.backward(current_gradient)
+
+    def __call__(self, X):
+        """Allow model(X) syntax."""
+        return self.predict(X)
+
+    def summary(self):
+        """Print model architecture."""
+        print("Model Summary:")
+        print("-" * 60)
+        print(
+            f"Optimizer: {self.optimizer} | Learning Rate: {self.alpha} | Batch Size: {self.batch_size} \nEpochs: {self.epochs} | Loss: {self.loss_class.name}"
+        )
+        print("-" * 60)
+        for i, layer in enumerate(self.layers):
+            if isinstance(layer, b.Dense):
+                print(
+                    f"Layer {i}: {layer.name.upper():<10} | Input: {layer.input_size:<5} Output: {layer.output_size:<5}"
+                )
+            else:
+                print(f"Layer {i}: {layer.name.upper():<10}")
+        print("-" * 60)
+
+
+class SequentialBuilder:
+    """Fluent API for building Sequential models."""
+
+    def __init__(self):
+        self.layers = []
+        self.alpha_value = 1
+        self.optimizer_name = "sgd"
+        self.batch_size = 1
+        self.epochs_value = 1000
+        self.loss_class = ls.MeanSquaredError()
+
+    def flatten(self):
+        """Add a Flatten layer."""
+        self.layers.append(b.Flatten())
+        return self
+
+    def dense(self, input_size, output_size):
+        """Add a Dense layer."""
+        self.layers.append(b.Dense(input_size, output_size))
+        return self
+
+    def relu(self):
+        """Add a ReLU activation."""
+        self.layers.append(a.ReLu())
+        return self
+
+    def sigmoid(self):
+        """Add a Sigmoid activation."""
+        self.layers.append(a.Sigmoid())
+        return self
+
+    def tanh(self):
+        """Add a Tanh activation."""
+        self.layers.append(a.Tanh())
+        return self
+
+    def softmax(self):
+        """Add a Softmax activation."""
+        self.layers.append(a.Softmax())
+        return self
+
+    def elu(self, alpha_activation=1.0):
+        """Add an ELU activation."""
+        self.layers.append(a.ELU(alpha_activation))
+        return self
+
+    def optimizer(self, name):
+        """Set the optimizer."""
+        self.optimizer_name = name
+        return self
+
+    def batch(self, num):
+        """Set the batch size."""
+        self.batch_size = num
+        return self
+
+    def alpha(self, num):
+        """Set the learning rate."""
+        self.alpha_value = num
+        return self
+
+    def epochs(self, num):
+        """Set the number of epochs."""
+        self.epochs_value = num
+        return self
+
+    def loss(self, loss_class):
+        """Set the loss function."""
+        self.loss_class = loss_class
+        return self
+
+    def build(self):
+        """Build and return the Sequential model."""
+        return Sequential(
+            *self.layers,
+            alpha=self.alpha_value,
+            optimizer=self.optimizer_name,
+            batch_size=self.batch_size,
+            epochs=self.epochs_value,
+            loss_class=self.loss_class,
+        )

phitodeep-0.1.3/src/phitodeep/optimization.py

@@ -0,0 +1,84 @@
+import numpy as np
+
+
+class Optimizer:
+    def step(self, layers):
+        raise NotImplementedError
+
+
+class SGD(Optimizer):
+    def __init__(self, alpha=0.01):
+        self.alpha = alpha
+
+    def step(self, layers):
+        for layer in layers:
+            if layer.grads:
+                layer.W -= self.alpha * layer.grads["W"]
+                layer.b -= self.alpha * layer.grads["b"]
+
+
+class Adam(Optimizer):
+    def __init__(self, alpha=0.01, beta1=0.9, beta2=0.999, epsilon=1e-8):
+        self.alpha = alpha
+        self.beta1 = beta1
+        self.beta2 = beta2
+        self.epsilon = epsilon
+        self.t = 0
+        self.m = {}
+        self.v = {}
+
+    def step(self, layers):
+        self.t += 1
+        for layer in layers:
+            if layer.grads:
+                for param_name, g in layer.grads.items():
+                    key = (id(layer), param_name)
+
+                    if key not in self.m:
+                        self.m[key] = np.zeros_like(g)
+                        self.v[key] = np.zeros_like(g)
+
+                    self.m[key] = self.beta1 * self.m[key] + (1 - self.beta1) * g
+                    self.v[key] = self.beta2 * self.v[key] + (1 - self.beta2) * g**2
+
+                    m_hat = self.m[key] / (1 - self.beta1**self.t)
+                    v_hat = self.v[key] / (1 - self.beta2**self.t)
+
+                    param = getattr(layer, param_name)
+                    param -= self.alpha * m_hat / (np.sqrt(v_hat) + self.epsilon)
+
+
+def train_loop(
+    model, X, y, X_test, y_test, loss_class, optimizer, epochs=1000, batch_size=1
+):
+    losses = []
+
+    for epoch in range(epochs):
+        for _ in range(len(X) // batch_size):
+            indices = np.random.randint(0, len(X), batch_size)
+            X_batch = X[indices]
+            y_batch = y[indices]
+
+            # Forward pass
+            y_pred = model.predict(X_batch)
+            loss = loss_class.loss_func(y_pred, y_batch)
+
+            # Compute gradient of loss w.r.t. predictions (dy)
+            dy = loss_class.loss_gradient(y_pred, y_batch)
+
+            # Backward pass with gradient of loss
+            model.backward(dy)
+            optimizer.step(model.layers)
+
+        y_pred = model.predict(X)
+        loss = loss_class.loss_func(y_pred, y)
+
+        y_pred_test = model.predict(X_test)
+        loss_test = loss_class.loss_func(y_pred_test, y_test)
+
+        losses.append((loss, loss_test))
+
+        if epoch % 10 == 0:
+            print(f"Epoch {epoch}, Loss: {loss:.4f}, Test Loss: {loss_test:.4f}")
+
+    return losses