Metadata-Version: 2.4
Name: NumFrame
Version: 0.1.0
Summary: A deep learning framework built from scratch using NumPy
Home-page: https://github.com
Author: solo_Brain
Author-email: estiakabag@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.18.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# NumFrame: Deep Learning From Scratch with NumPy

NumFrame is a lightweight, dynamic, and completely modular deep learning framework written from scratch using **NumPy**. It mimics production-grade deep learning libraries like PyTorch and Keras, implementing an object-oriented, tape-free automated sequential graph loop.

This library is perfect for educational research, helping you understand how deep neural networks process hidden state mathematics, evaluate error propagation, and execute Stochastic Gradient Descent optimization under the hood.

---

## 🚀 Key Features

*   **Fully Dynamic Pipeline**: Add as many layers or non-linearities as you want on the fly using the `Sequential` container.
*   **Object-Oriented Design**: Clean division of responsibilities across modular components (`layers`, `activations`, `losses`, `optimizers`).
*   **Vectorized Backpropagation**: Efficient tensor-dot matrix calculations for rapid training performance on CPU.
*   **Coupled Softmax & Loss Stability**: Integrated categorical cross-entropy loss derivative computation prevents numerical underflow or exploding losses.

---

## 📦 Package Directory Map

```text
NumFrame/                     # Root source code package
│
├── __init__.py               # Core package export definitions
├── base.py                   # Standard Layer parent interface blueprint
├── layers.py                 # Structural blocks (Dense / Fully Connected)
├── activations.py            # Non-linear pathways (ReLU, Softmax)
├── losses.py                 # Performance criteria evaluation rules
├── optimizers.py             # Parameter update logic (Stochastic Gradient Descent)
└── model.py                  # Sequential coordination pipeline engine
```

---

## 🛠️ Quick Installation

Clone your workspace or open your repository terminal in the directory where `setup.py` lives, then run the dynamic workspace link engine via `pip`:

```bash
pip install -e .
```

*Note: The `-e` flag stands for editable mode. Any updates or structural extensions you make inside the `NumFrame/` directory will instantly go live without requiring a fresh reinstall!*

---

## 💻 Full End-to-End Walkthrough Example

Here is a full workspace pipeline showing how to import **NumFrame** to build, train, and execute a multi-layer perception classifier:

```python
import numpy as np
import NumFrame

# -------------------------------------------------------------
# 1. Prepare Your Dataset 
# -------------------------------------------------------------
# Creating dummy vector data mimicking a 10-class problem (e.g., MNIST digit pixels)
print("Initializing dummy dataset arrays...")
X_train = np.random.randn(1000, 784)  # 1000 flat image samples
Y_train = np.random.randint(0, 10, size=(1000,))  # 10 separate digit classes

# -------------------------------------------------------------
# 2. Build Your Dynamic Neural Network Architecture
# -------------------------------------------------------------
model = NumFrame.Sequential()

# Stack your layers cleanly using .add()
model.add(NumFrame.Dense(n_inputs=784, n_neurons=256))
model.add(NumFrame.ReLU())
model.add(NumFrame.Dense(n_inputs=256, n_neurons=128))
model.add(NumFrame.ReLU())
model.add(NumFrame.Dense(n_inputs=128, n_neurons=10))
model.add(NumFrame.Softmax())

# -------------------------------------------------------------
# 3. Attach Loss & Optimization Protocols
# -------------------------------------------------------------
model.set_loss(NumFrame.LossCategoricalCrossEntropy())
optimizer = NumFrame.OptimizerSGD(learning_rate=0.1)

# -------------------------------------------------------------
# 4. Train (Fit) the Network Model
# -------------------------------------------------------------
print("\nBeginning training run loop...")
model.fit(
    X=X_train, 
    y=Y_train, 
    epochs=100, 
    batch_size=64, 
    optimizer=optimizer, 
    print_every=10
)

# -------------------------------------------------------------
# 5. Evaluate and Predict
# -------------------------------------------------------------
print("\nGenerating fresh out-of-sample predictions...")
sample_images = np.random.randn(5, 784)
predictions = model.predict(sample_images)

print(f"Calculated Predicted Classes: {predictions}")
```

---

## 🧩 Architectural Design Philosophy

### The Forward Execution Chain
The model pipes dataset parameters index-by-index down a continuous list tracking the layer states. The computation flow operates explicitly as:
$$\text{Input} \rightarrow \text{Dense}_1 \rightarrow \text{ReLU}_1 \rightarrow \text{Dense}_2 \rightarrow \text{Softmax} \rightarrow \text{Loss}$$

### The Backward Derivative Loop
Gradients are passed back in total reverse using Python’s built-in step tools. Instead of managing a global computational graph tree, every layer calculates its relative changes (`dweights`, `dbiases`, `dinputs`) and steps downstream sequentially. This ensures a clean $O(N)$ execution path.

---

## 📜 License
This architecture framework is completely open-source and released under the [MIT License](LICENSE).
