Metadata-Version: 2.4
Name: multilayer-perceptron-from-scratch
Version: 0.1.2
Summary: A clean and educational implementation of a Multilayer Perceptron from scratch using NumPy
Author-email: Nehorai Yosef <neopydev5454@gmail.com>
License: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Requires-Dist: numpy>=1.20.0
Description-Content-Type: text/markdown

# Multilayer Perceptron (MLP) from Scratch 🧠

[![GitHub Repo](https://img.shields.io/badge/GitHub-Repository-blue?logo=github)](https://github.com/nyosef1108/multilayer-perceptron-from-scratch)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![NumPy](https://img.shields.io/badge/dependency-NumPy-blueviolet.svg)](https://numpy.org/)

**Multilayer Perceptron from Scratch** is a lightweight, educational, and high-performance implementation of a feedforward artificial neural network built entirely from scratch using NumPy.

A lightweight, educational, and high-performance implementation of a **Multilayer Perceptron** neural network, built entirely from scratch using **NumPy**.

This project implements the fundamental mathematics of deep learning—including **Backpropagation** and **Stochastic Gradient Descent (SGD)** with data shuffling—without the overhead of heavy frameworks like PyTorch or TensorFlow.

---

### ✨ Key Features

* **🎯 Pure NumPy:** Zero dependencies for the core engine (only `numpy`).

* **🔄 Stochastic Gradient Descent (SGD):** Includes automatic data shuffling every epoch for better convergence.

* **🏗️ Flexible Architecture:** Custom-define any number of hidden layers and neurons.

* **📉 Matrix-Based Backpropagation:** Efficient implementation using the four fundamental equations of backpropagation.

* **🎓 Educational Design:** Clean, commented code ideal for learning how neural networks actually work "under the hood."

---

### 📦 Installation

You can install the package directly from PyPI:

```bash
pip install multilayer-perceptron-from-scratch
```

---
### 📓 Interactive Jupyter Notebooks (.ipynb)

For a richer, visual, and hands-on experience, the repository includes ready-to-run Jupyter Notebooks featuring complex non-linear classification tasks. Each demo captures dynamic metrics like **Loss progression** and **Accuracy scores**, culminating in detailed decision boundary plots using `matplotlib`.

---

#### 🌕 DEMO 1: Moons Dataset Boundary
* **Description:** A classic, non-linear benchmarking problem. This demo uses a hidden layer of 16 neurons to smoothly separate two intertwining mathematical half-circles.
* **Key Components:** `sklearn.datasets.make_moons`, `matplotlib.pyplot` contour plotting.
* **Performance:** Reaches **100% accuracy** in less than 1000 epochs.
* **🔗 Run in Cloud:** [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/nyosef1108/multilayer-perceptron-from-scratch/blob/main/DEMO1.ipynb)

<p align="center">
  <img src="https://raw.githubusercontent.com/nyosef1108/multilayer-perceptron-from-scratch/main/assets/demo1_moons.png" alt="Moons Dataset Decision Boundary" width="600"/>
</p>

---

#### 🌀 DEMO 2: Wide-Gap 6-Arm Spiral
* **Description:** A highly complex geometric distribution designed to test the network's ability to capture sharp, twisting transitions. By leveraging a deeper architecture (`[2, 10, 10, 1]`) and a higher learning rate ($\eta = 0.2$), the model maps the intricate spiral arms perfectly.
* **Key Components:** Custom synthetic spiral generator with a wide center gap.
* **Performance:** Successfully untangles all 6 arms, achieving **99.8%+ accuracy** by epoch 2000.
* **🔗 Run in Cloud:** [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/nyosef1108/multilayer-perceptron-from-scratch/blob/main/DEMO2.ipynb)

<p align="center">
  <img src="https://raw.githubusercontent.com/nyosef1108/multilayer-perceptron-from-scratch/main/assets/demo2_spiral.png" alt="6-Arm Spiral Decision Boundary" width="550"/>
</p>

---

#### 📊 DEMO 3: Continuous Cosine vs. Interrupted Sine
* **Description:** A sophisticated phase and amplitude classification task. The network is challenged to classify a completely continuous blue Cosine wave against a red Sine wave that gets intentionally interrupted at intersection points to avoid mathematical overlapping.
* **Key Components:** Custom hybrid mathematical wave simulation, `matplotlib.lines.Line2D` advanced legends.
* **Performance:** Demonstrates exceptional decision-boundary fitting with **98.6% accuracy**.
* **🔗 Run in Cloud:** [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/nyosef1108/multilayer-perceptron-from-scratch/blob/main/DEMO3.ipynb)

<p align="center">
  <img src="https://raw.githubusercontent.com/nyosef1108/multilayer-perceptron-from-scratch/main/assets/demo3_sin_cos.png" alt="Continuous Cosine vs Interrupted Sine Boundary" width="650"/>
</p>

---

### 🚀 Quick Start (XOR Example)

The following example demonstrates how to solve the classic XOR problem using the `Network` class.

```python
import numpy as np
from multilayer_perceptron import Network

# 1. Define Architecture: [Input (2), Hidden (20), Output (1)]
net = Network([2, 20, 1])

# 2. Prepare Training Data (XOR)
# Format: List of tuples (input_vector, target_vector)
training_data = [
    (np.array([[0], [0]]), np.array([[0]])),
    (np.array([[0], [1]]), np.array([[1]])),
    (np.array([[1], [0]]), np.array([[1]])),
    (np.array([[1], [1]]), np.array([[0]]))
]

# 3. Train using SGD
# Parameters: data, epochs, learning_rate
print("Starting Training...")
net.SGD(training_data, epochs=3000, learning_rate=0.2)

# 4. Test the model
print("\nResults:")
for x, y in training_data:
    output, _, _ = net.feedforward(x)
    prediction = 1 if output >= 0.5 else 0
    print(f"Input: {x.flatten()} | Target: {int(y[0][0])} | Predicted: {prediction}")
```

---

### 📜 License

Distributed under the **MIT License**. See `LICENSE` for more information.

---

**Created with ❤️ by Nehorai Yosef**