Metadata-Version: 2.4
Name: vanillanets
Version: 1.0.0
Summary: A transparent, NumPy-only neural network library for learning and experimentation.
Home-page: https://github.com/UmarBalak/vanillanets
Author: Umar Balak
Author-email: Umar Balak <umarbalak35@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/UmarBalak/vanillanets
Project-URL: Documentation, https://github.com/UmarBalak/vanillanets#readme
Project-URL: Repository, https://github.com/UmarBalak/vanillanets
Project-URL: Bug Tracker, https://github.com/UmarBalak/vanillanets/issues
Keywords: neural-network,deep-learning,machine-learning,numpy,education,from-scratch
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.3.3
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# VanillaNets v1.0.0

[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/downloads/)
[![NumPy](https://img.shields.io/badge/dependency-numpy%202.3.3%2B-green)](https://numpy.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Status: Production Ready ✓](https://img.shields.io/badge/status-production%20ready-success)]()

**A transparent, NumPy-only neural network library designed for learning and experimentation.**

VanillaNets is a from-scratch implementation of core neural network components using only Python and NumPy. Every component is written explicitly with clarity prioritized over convenience, making the entire system transparent, easy to inspect, and perfect for understanding how neural networks operate under the hood.

Whether you're a student learning fundamentals, a researcher prototyping new ideas, or an educator building curriculum, VanillaNets provides a crystal-clear window into neural network mechanics without framework abstractions.

---

## Features

### Core Architecture
* **Dense Layers** - Fully connected layers with efficient forward and backward passes
* **Advanced Weight Initialization** - He, Xavier (Glorot), normal and uniform distributions for optimized training
* **Flexible Bias Initialization** - Zeros or small positive constants to reduce dead units

### Activation Functions (with derivatives)
* Linear, ReLU & LeakyReLU
* Tanh & Sigmoid
* Softmax (with fused Softmax+CrossEntropy backward pass optimization)

### Loss Functions
* Binary Cross-Entropy (for binary classification)
* Categorical Cross-Entropy (for multiclass classification)
* Sparse Categorical Cross-Entropy (for integer-encoded labels)
* Mean Squared Error (for regression)

### Optimizers
* **SGD** - Stochastic Gradient Descent with momentum and learning rate decay
* **Adam** - Adaptive Moment Estimation with adaptive learning rates per parameter

### Metrics & Evaluation
* **Classification:** Accuracy, Precision, Recall, F1 Score, Confusion Matrix
* **Regression:** R² Score, Mean Absolute Error (MAE), Root Mean Squared Error (RMSE)

### Model API
* Sequential model building (`model.add()`)
* Flexible metrics interface (single metric or multiple metrics as dict/list)
* Training with `fit()` and optional validation data
* Inference with `predict()`
* Batch evaluation with `evaluate()`

### Performance Optimizations
* Fused Softmax + Categorical Cross-Entropy backward pass (faster training)
* Efficient NumPy vectorization throughout
* Memory-conscious layer implementations

---

## Installation

### From PyPI (Recommended)

Install directly from PyPI:

```bash
pip install vanillanets
```

### From Source

Clone the repository and install in development mode:

```bash
git clone https://github.com/UmarBalak/vanillanets.git
cd vanillanets
pip install -e .
```

Or install with development dependencies:

```bash
pip install -e ".[dev]"
```

### Requirements

- **Python:** 3.8 or higher
- **NumPy:** 2.3.3+ (for efficient numerical computation)

### Verify Installation

```python
import vanillanets
print(f"VanillaNets {vanillanets.__version__} installed successfully!")

# Import core components
from vanillanets import Model, DenseLayer
from vanillanets.activations import ReLU, Sigmoid
from vanillanets.losses import BinaryCrossEntropy
from vanillanets.optimizers import Optimizer_Adam
from vanillanets.metrics import Accuracy

print("✓ All modules imported successfully!")
```

---

## Quick Start

### Example 1: Binary Classification

```python
from vanillanets import Model, DenseLayer, Optimizer_Adam
from vanillanets.activations import ReLU, Sigmoid
from vanillanets.losses import BinaryCrossEntropy
from vanillanets.metrics import Accuracy

# Build model
model = Model()
model.add(DenseLayer(30, 64))
model.add(ReLU())
model.add(DenseLayer(64, 1))
model.add(Sigmoid())

# Compile with loss, optimizer, and metrics
model.set(
    loss=BinaryCrossEntropy(),
    optimizer=Optimizer_Adam(learning_rate=0.01),
    metrics={'accuracy': Accuracy()}
)
model.finalize()

# Train the model
model.fit(X_train, y_train, epochs=100, print_every=10, 
          validation_data=(X_val, y_val))

# Evaluate on test set
loss, metrics = model.evaluate(X_test, y_test)
print(f"Test Loss: {loss:.4f}, Accuracy: {metrics['accuracy']:.4f}")

# Make predictions
predictions = model.predict(X_new)
```

### Example 2: Multiclass Classification

```python
from vanillanets import Model, DenseLayer, Optimizer_Adam
from vanillanets.activations import ReLU, Softmax
from vanillanets.losses import CategoricalCrossEntropy
from vanillanets.metrics import Accuracy

# Build model
model = Model()
model.add(DenseLayer(784, 128))
model.add(ReLU())
model.add(DenseLayer(128, 64))
model.add(ReLU())
model.add(DenseLayer(64, 10))
model.add(Softmax())

# Compile
model.set(
    loss=CategoricalCrossEntropy(),
    optimizer=Optimizer_Adam(learning_rate=0.05),
    metrics={'accuracy': Accuracy()}
)
model.finalize()

# Train
model.fit(X_train, y_train, epochs=50, print_every=5)
```

### Example 3: Regression

```python
from vanillanets import Model, DenseLayer, Optimizer_Adam
from vanillanets.activations import Linear, ReLU
from vanillanets.losses import MeanSquaredError
from vanillanets.metrics import RMSE, MAE

# Build model
model = Model()
model.add(DenseLayer(8, 64))
model.add(ReLU())
model.add(DenseLayer(64, 1))
model.add(Linear())

# Compile with multiple metrics
model.set(
    loss=MeanSquaredError(),
    optimizer=Optimizer_Adam(learning_rate=0.01),
    metrics={'rmse': RMSE(), 'mae': MAE()}
)
model.finalize()

# Train and evaluate
model.fit(X_train, y_train, epochs=100, validation_data=(X_val, y_val))
loss, metrics = model.evaluate(X_test, y_test)
print(f"Test RMSE: {metrics['rmse']:.4f}, MAE: {metrics['mae']:.4f}")
```

---

## Examples

Full working examples included:
* `binary_classification.py` - Breast cancer classification
* `multiclass_classification.py` - Handwritten digit recognition
* `regression.py` - California housing price prediction

Run any example:
```bash
python binary_classification.py
python multiclass_classification.py
python regression.py
```

---

## Testing

Run the comprehensive test suite (requires pytest):

```bash
pip install pytest
pytest tests/ -v
```

Or run tests with coverage:

```bash
pip install pytest pytest-cov
pytest tests/ -v --cov=vanillanets
```

### Test Coverage

Comprehensive unit and integration tests cover:
- ✓ All activation functions (Linear, Sigmoid, ReLU, LeakyReLU, Tanh, Softmax) and their derivatives
- ✓ All loss functions (BCE, CCE, SparseCCE, MSE) with gradient validation
- ✓ Dense layer forward/backward passes
- ✓ Optimizer updates (SGD momentum, Adam adaptive rates)
- ✓ Fused Softmax+CrossEntropy optimization
- ✓ All metrics (classification & regression)
- ✓ Model training, evaluation, and prediction workflows
- ✓ Edge cases and numerical stability

---

## Design Philosophy

VanillaNets is built on the principle that **understanding requires transparency**:

- **No magic** ✓ Every computation is explicit; no hidden state or black-box frameworks
- **Learn by reading** ✓ Source code is the primary documentation
- **Experimentation-friendly** ✓ Modify any component without framework constraints
- **Pure NumPy** ✓ No external dependencies beyond NumPy for core functionality
- **Production-ready** ✓ Full test coverage, efficient implementations, stable API

## Use Cases

- **Education:** Perfect for coursework on neural networks and deep learning
- **Research Prototyping:** Experiment with new loss functions, activations, or optimization strategies
- **Interview Prep:** Implement solutions from scratch during ML engineering interviews
- **Curriculum Development:** Build course materials with fully transparent implementations
- **Algorithmic Learning:** Understand backpropagation, gradient descent, and optimizer mechanics

---

## Project Status

### v1.0.0 - Production Ready

**Fully Implemented & Tested:**
- ✓ Dense layer implementation with He, Xavier, normal, and uniform weight initialization
- ✓ All activation functions with proper gradient computation (Linear, ReLU, LeakyReLU, Tanh, Sigmoid, Softmax)
- ✓ All loss functions with backward passes (BCE, CCE, SparseCCE, MSE)
- ✓ SGD optimizer with momentum and learning rate decay
- ✓ Adam optimizer with adaptive learning rates
- ✓ Comprehensive metrics suite (Accuracy, Precision, Recall, F1, Confusion Matrix, R², MAE, RMSE)
- ✓ Full Model API (add, set, finalize, predict, evaluate, fit)
- ✓ Fused Softmax+CrossEntropy optimization for faster training
- ✓ Extensive test coverage (50+ test cases)
- ✓ Complete example applications (binary classification, multiclass classification, regression)
- ✓ Validation data support during training

### Future Enhancements (Post-v1.0)
- Convolutional (Conv2D) layers with pooling
- Recurrent layers (LSTM, GRU)
- Batch normalization and layer normalization
- Dropout regularization
- Custom layer support through base class
- Learning rate scheduling
- Distributed training utilities (multi-GPU)
- Quantization and pruning support

---

## License

MIT License - See [LICENSE](LICENSE) for full details.

You are free to use, modify, and distribute this software for any purpose (commercial or personal) with proper attribution.

---

## Acknowledgments

VanillaNets was built with a singular mission: to demystify neural networks for learners everywhere. This library stands on the shoulders of foundational work in deep learning by pioneers like Yann LeCun, Geoffrey Hinton, Yoshua Bengio, and the broader machine learning community.

Special thanks to:
- The NumPy team for creating an incredible numerical computing foundation
- All educators who emphasize understanding over black-box frameworks
- Contributors and users who provide feedback and improvements

## Citation

If you use VanillaNets in your research or teaching, please cite:

```bibtex
@software{vanillanets2026,
  title={VanillaNets: A Transparent Neural Network Library},
  author={Umar Balak},
  year={2026},
  url={https://github.com/UmarBalak/vanillanets}
}
```

---

## Resources & References

### Recommended Reading
- **Neural Networks from Scratch in Python**, co-authored by Harrison Kinsley and Daniel Kukieła
- **Deep Learning** by Goodfellow, I., Bengio, Y., & Courville, A.
- **Hands-On Machine Learning with Scikit-Learn, Keras, and TensorFlow, 3rd Edition** by Aurélien Géron


### Related Projects
- [NumPy](https://numpy.org/) - Our computational foundation
- [3blue1brown Neural Network Series](https://www.youtube.com/watch?v=aircAruvnKk) - Visual learning guide

---

**Built with ❤️ for learners by learners.**
