ZeroProp: Raw NumPy Neural Network Engine

ZeroProp is a custom-built, zero-dependency (excluding NumPy) neural network engine. It is designed to demonstrate a deep, foundational understanding of backpropagation, matrix calculus, and gradient descent without relying on abstractions from libraries like PyTorch or TensorFlow.

Architecture & Data Flow

Here is how the Real-Time Training system works via WebSockets:

sequenceDiagram
    participant Client as Frontend Dashboard
    participant API as FastAPI (Server)
    participant Engine as NumPy NN Engine

    Client->>API: 1. Connect WebSocket (/ws/train)
    Client->>API: 2. Send Start Command {"epochs": 2000, "lr": 1.0}
    
    loop Every Epoch
        API->>Engine: Forward Pass (X -> Y_pred)
        API->>Engine: Backward Pass (Update W, b)
        Engine-->>API: Yield Loss & Accuracy Metrics
        API-->>Client: 3. Stream JSON {epoch, loss, acc}
    end
    
    API-->>Client: 4. Send Status: Completed
    Client->>API: 5. Fetch Final Decision Boundary Points (/predict)

Loading

Features

• Pure Math Engine: Fully connected layers (Dense), Activations (ReLU), and combined loss functions ( SoftmaxCrossEntropy) built entirely from scratch.
• FastAPI Backend: The engine is wrapped in a modern FastAPI application.
• Real-Time Training (WebSockets): Features a WebSocket endpoint (ws://.../ws/train) that streams the epoch, loss, and accuracy in real-time to connected clients.
• Non-Linear Dataset: Generates a 3-class spiral dataset to prove the network's capability to learn non-linear decision boundaries.

Tech Stack

• Python 3.10+
• NumPy (Matrix operations)
• FastAPI & Uvicorn (REST & WebSocket serving)

Getting Started

1. Installation

Create a virtual environment and install the required dependencies:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Environment Variables & CORS

By default, the API allows all CORS origins (*). For security or integration with the frontend, you can restrict this by setting the CORS_ORIGINS environment variable (comma-separated).

# Example (Linux/macOS)
export CORS_ORIGINS="http://localhost:5173,http://127.0.0.1:5173"

# Example (Windows PowerShell)
$env:CORS_ORIGINS="http://localhost:5173,http://127.0.0.1:5173"

3. Running the API

Start the FastAPI server:

uvicorn main:app --reload

The server will start at http://127.0.0.1:8000.

4. API Endpoints

• GET /dataset: Returns the generated X (coordinates) and y (labels) arrays for the spiral dataset.
• POST /predict: Accepts a grid of points and returns the network's class predictions (useful for drawing decision boundaries on a frontend).
• WS /ws/train: WebSocket connection. Send {"epochs": 2000, "learning_rate": 1.0} to trigger the backpropagation loop and receive real-time metric streams.

Why this exists?

This project serves as a proof of work for machine learning engineering. Understanding how to call loss.backward() in PyTorch is standard; understanding the exact matrix operations required to propagate gradients backwards through a computational graph demonstrates true mastery of the underlying mechanics.

Check out the Detailed Math Breakdown (docs/math.md) to see the exact matrix calculus utilized under the hood!