Metadata-Version: 2.4
Name: forgeNN
Version: 2.0.0
Summary: A From Scratch Neural Network Framework with Educational Purposes
Author: Enbiya Çabuk
Author-email: cabuk23@itu.edu.tr
License: MIT License
        
        Copyright (c) 2025 Enbiya Çabuk 
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/Savernish/forgeNN
Project-URL: Documentation, https://github.com/Savernish/forgeNN/blob/v2.0.0/README.md
Project-URL: Repository, https://github.com/Savernish/forgeNN/tree/v2.0.0
Project-URL: Bug Reports, https://github.com/Savernish/forgeNN/issues
Project-URL: Changelog, https://github.com/Savernish/forgeNN/blob/v2.0.0/CHANGELOG.md
Keywords: neural-networks,machine-learning,deep-learning,education,automatic-differentiation,numpy,from-scratch,ai,artificial-intelligence,pytorch,numba
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
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: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: numba>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: sphinx>=4.0.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Requires-Dist: build>=0.8.0; extra == "dev"
Provides-Extra: examples
Requires-Dist: matplotlib>=3.5.0; extra == "examples"
Requires-Dist: jupyter>=1.0.0; extra == "examples"
Provides-Extra: onnx
Requires-Dist: onnx>=1.14.0; extra == "onnx"
Provides-Extra: cuda
Requires-Dist: cupy-cuda12x>=13.0.0; (platform_system == "Windows" or platform_system == "Linux") and extra == "cuda"
Provides-Extra: all
Requires-Dist: pytest>=7.0.0; extra == "all"
Requires-Dist: pytest-cov>=4.0.0; extra == "all"
Requires-Dist: sphinx>=4.0.0; extra == "all"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "all"
Requires-Dist: black>=22.0.0; extra == "all"
Requires-Dist: flake8>=4.0.0; extra == "all"
Requires-Dist: mypy>=0.950; extra == "all"
Requires-Dist: twine>=4.0.0; extra == "all"
Requires-Dist: build>=0.8.0; extra == "all"
Requires-Dist: matplotlib>=3.5.0; extra == "all"
Requires-Dist: jupyter>=1.0.0; extra == "all"
Requires-Dist: onnx>=1.14.0; extra == "all"
Requires-Dist: cupy-cuda12x>=13.0.0; (platform_system == "Windows" or platform_system == "Linux") and extra == "all"
Dynamic: license-file

# forgeNN

## Table of Contents

- [Installation](#Installation)
- [Overview](#Overview)
- [Performance vs PyTorch](#Performance-vs-PyTorch)
- [Quick Start](#Quick-Start)
- [Complete Example](#Complete-Example)
- [Roadmap](#Roadmap)
- [Contributing](#Contributing)
- [Acknowledgments](#Acknowledgments)

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![Stars](https://img.shields.io/github/stars/Savernish/forgeNN.svg?style=social&label=Stars)](https://github.com/Savernish/forgeNN)
[![NumPy](https://img.shields.io/badge/powered_by-NumPy-blue.svg)](https://numpy.org/)
[![PyPI version](https://img.shields.io/pypi/v/forgeNN.svg)](https://pypi.org/project/forgeNN/)
[![Downloads](https://img.shields.io/pypi/dm/forgeNN.svg)](https://pypi.org/project/forgeNN/)
[![License](https://img.shields.io/pypi/l/forgeNN.svg)](https://pypi.org/project/forgeNN/)

## Installation

```bash
pip install forgeNN
```

Optional extras:

```bash
# ONNX helpers (scaffold)
pip install "forgeNN[onnx]"

# CUDA backend (scaffold; requires compatible GPU/driver)
pip install "forgeNN[cuda]"
```

## Overview

**forgeNN** is a modern neural network framework with an API built around a straightforward `Sequential` model, a fast NumPy autograd `Tensor`, and a Keras-like `compile/fit` training workflow.

This project is built and maintained by a single student developer. For background and portfolio/CV, see: https://savern.me

### Key Features

- **Fast NumPy core**: Vectorized operations with fused, stable math
- **Dynamic Computation Graphs**: Automatic differentiation with gradient tracking
- **Complete Neural Networks**: From simple neurons to complex architectures
- **Production Loss Functions**: Cross-entropy, MSE with numerical stability
 - **Scaffolded Integrations**: Runtime device API for future CUDA; ONNX export/import stubs

## Performance vs PyTorch

**forgeNN is 3.52x faster than PyTorch on small models!**

| Metric | PyTorch | forgeNN | Advantage |
|--------|---------|---------|-----------|
| Training Time (MNIST) | 64.72s | 30.84s | **2.10x faster** |
| Test Accuracy | 97.30% | 97.37% | **+0.07% better** |
| Small Models (<109k params) | Baseline | **3.52x faster** | **Massive speedup** |

📊 Comparison and detailed docs are being refreshed for v2; see examples/ for runnable demos.


## Quick Start

### Keras-like Training (compile/fit)

```python
model = fnn.Sequential([
    fnn.Input((20,)),        # optional Input layer seeds summary & shapes
    fnn.Dense(64) @ 'relu',
    fnn.Dense(32) @ 'relu',
    fnn.Dense(3)  @ 'linear'
])

# Optionally inspect architecture
model.summary()              # or model.summary((20,)) if no Input layer
opt = fnn.Adam(lr=1e-3)      # or other optimizers (adamw, sgd, etc)
compiled = fnn.compile(model,
                    optimizer=opt,
                    loss='cross_entropy',
                    metrics=['accuracy'])
compiled.fit(X, y, epochs=10, batch_size=64)
loss, metrics = compiled.evaluate(X, y)

# Tip: `mse` auto-detects 1D integer class labels for (N,C) logits and one-hot encodes internally.
# model.summary() can be called any time after construction if an Input layer or input_shape is provided.
```



## Complete Example

See `examples/` for full fledged demos

## Links

- **PyPI Package**: https://pypi.org/project/forgeNN/
- **Documentation**: v2 guides coming soon; examples in `examples/`
- **Issues**: GitHub Issues for bug reports and feature requests
- **Portfolio/CV**: https://savern.me

## Roadmap (post v2.0.0)

- CUDA backend and device runtime
  - Device abstraction for `Tensor` and layers
  - Initial CUDA kernels (Conv, GEMM, elementwise) and CPU/CUDA parity tests
  - Setup and troubleshooting guide

- ONNX: export and import (full coverage for the core API)
  - Export `Sequential` graphs with Conv/Pool/Flatten/Dense/LayerNorm/Dropout/activations
  - Import linear and branched graphs where feasible; shape inference checks
  - Round‑trip parity tests and examples

- Model save and load
  - Architecture JSON + weights (NPZ) format
  - `state_dict`/`load_state_dict` compatibility helpers
  - Versioning and minimal migration guidance

- Transformer positional encodings
  - Sinusoidal `PositionalEncoding` and learnable `PositionalEmbedding`
  - Tiny encoder demo with text classification walkthrough

- Performance and stability
  - CPU optimizations for conv/pool paths, memory reuse, and fewer allocations
  - Threading guidance (MKL/OpenBLAS), deterministic runs, and profiling notes

- Documentation
  - Practical guides for `Sequential`, `compile/fit`, model I/O, ONNX, and CUDA setup
  - Design overview of autograd and execution model

## Contributing

I am not currently accepting contributions, but I'm always open to suggestions and feedback!

## Acknowledgments

- Inspired by educational automatic differentiation tutorials (micrograd)
- Built for both learning and production use
- Optimized with modern NumPy practices
- **Available on PyPI**: `pip install forgeNN`

---
