Metadata-Version: 2.4
Name: neuroforge-dl
Version: 0.2.0
Summary: A full-featured deep learning framework and production AI platform built from first principles in Python & NumPy.
Author-email: NeuroForge Contributors <neuroforge@example.com>
License: MIT
Project-URL: Homepage, https://github.com/username/neuroforge
Project-URL: Documentation, https://github.com/username/neuroforge#readme
Project-URL: Repository, https://github.com/username/neuroforge.git
Project-URL: Issues, https://github.com/username/neuroforge/issues
Keywords: deep-learning,autograd,neural-networks,transformers,gpt,vision-transformer,resnet,unet,bert,vae,fastapi-serving
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn[standard]>=0.28.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: mkdocs>=1.5.0; extra == "dev"
Requires-Dist: mkdocs-material>=9.5.0; extra == "dev"
Dynamic: license-file

# NeuroForge 🧠⚡

> A full-featured deep learning framework and production AI platform — built entirely from first principles in Python/NumPy.

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)
[![Tests](https://img.shields.io/badge/tests-36%20passed-brightgreen.svg)](#testing)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

---

## What is NeuroForge?

NeuroForge is a **complete, production-ready deep learning stack** implemented from scratch — no PyTorch, no TensorFlow, no Keras. Every component, from the tensor engine to the FastAPI model-serving layer, is hand-crafted:

| Layer | What's included |
|---|---|
| 🔢 **Tensor Engine** | NumPy-backed N-D arrays, dynamic autograd computation graph, full reverse-mode AD |
| 🧱 **Neural Modules** | Linear, Conv1D, Conv2D, ConvTranspose2D, MaxPool, AvgPool, RNN, LSTM, GRU, Attention, Transformer, Embedding, LayerNorm, BatchNorm, Dropout |
| 🏗️ **Model Zoo** | MLP, ConvNet, ResNet (ResNet18/34), U-Net, BERT, VAE, GPT, VisionTransformer, VisionLanguageModel |
| 📉 **Losses** | CrossEntropy, BCE, BCEWithLogits, MSE, VAE Loss (BCE + KL) |
| ⚙️ **Optimizers & Schedulers** | SGD (+ momentum), Adam, AdamW, StepLR, CosineAnnealingLR, WarmupCosineScheduler, WarmupLinearScheduler, ExponentialLR |
| 🛠️ **Training & Utilities** | Trainer, Gradient Clipping (norm & value), Numerical Gradient Checker, Weight Initialization (Xavier, Kaiming, Orthogonal), Callbacks |
| 📊 **Experiments & Visuals** | ExperimentTracker, Plot Training History, Gradient Norm Inspection |
| 📦 **Registry & Serving** | ModelRegistry (versioned save/load) + FastAPI REST server (`/health`, `/models`, `/predict`, `/generate`, `/metrics`) |

---

## Architecture

```
┌───────────────────────────────────────────────────────────────────┐
│                          NeuroForge Stack                          │
├───────────────────────────────────────────────────────────────────┤
│  neuroforge.core      │  Tensor + Autograd Engine                  │
│  neuroforge.nn        │  Module, Parameter, 16 Layer Types        │
│  neuroforge.models    │  MLP, ConvNet, ResNet, UNet, BERT, VAE...  │
│  neuroforge.losses    │  CrossEntropy, BCE, MSE, VAE Loss          │
│  neuroforge.optim     │  SGD, Adam, AdamW, Warmup Schedulers       │
│  neuroforge.data      │  TensorDataset, DataLoader                 │
│  neuroforge.training  │  Trainer, Callbacks, Metrics               │
│  neuroforge.utils     │  Init, Grad Clipping, Grad Check, Plots    │
│  neuroforge.experiments│  ExperimentTracker                        │
│  neuroforge.registry  │  ModelRegistry (versioned persistence)     │
│  neuroforge.inference │  InferenceEngine                           │
│  neuroforge.serving   │  FastAPI production REST server            │
└───────────────────────────────────────────────────────────────────┘
```

---

## Quick Start

### Installation

```bash
cd NeuroForge
pip install -e .
```

### Train a ConvNet in 5 lines

```python
import numpy as np
from neuroforge import ConvNet, CrossEntropyLoss, Adam, TensorDataset, DataLoader, Trainer

X = np.random.randn(200, 1, 28, 28).astype("float32")
y = np.random.randint(0, 10, size=(200,)).astype("int64")

model    = ConvNet(in_channels=1, num_classes=10, channels=[16, 32])
trainer  = Trainer(model, CrossEntropyLoss(), Adam(model.parameters(), lr=0.005))
history  = trainer.fit(DataLoader(TensorDataset(X, y), batch_size=32), epochs=5)
```

### Advanced Models: ResNet18, U-Net, BERT & VAE

```python
import neuroforge as nf

# ResNet-18
resnet = nf.ResNet18(in_channels=3, num_classes=10)
nf.apply_init(resnet, init_fn=nf.kaiming_normal_)

# U-Net Image Segmentation
unet = nf.UNet(in_channels=1, out_channels=1, features=[32, 64])

# BERT Masked Language Model
bert = nf.BERT(vocab_size=1000, d_model=128, nhead=4, num_layers=4)

# VAE with Reparameterization
vae = nf.VAE(input_dim=784, hidden_dim=256, latent_dim=32)
```

---

## Examples

```bash
python examples/01_mnist_cnn.py            # ConvNet image classification
python examples/02_text_gpt.py             # GPT language model + text generation
python examples/03_multimodal_demo.py      # Vision-Language multimodal model
python examples/04_advanced_models_demo.py # ResNet, U-Net, BERT, VAE, Grad Clipping & Warmup
```

---

## CLI Training & Serving

```bash
# CLI Training
python scripts/train.py --config configs/default_train.yaml

# REST Serving
python scripts/serve.py --host 0.0.0.0 --port 8000
```

---

## Testing

```bash
python -m pytest tests/ -v
```

```
36 passed in 1.45s  ✅
```

| Test Suite | Tests | Status |
|---|---|---|
| `tests/unit/test_tensor.py` | 5 | ✅ |
| `tests/unit/test_autograd.py` | 3 | ✅ |
| `tests/unit/test_layers.py` | 5 | ✅ |
| `tests/unit/test_advanced_layers.py` | 2 | ✅ |
| `tests/unit/test_models.py` | 5 | ✅ |
| `tests/unit/test_advanced_models.py` | 4 | ✅ |
| `tests/unit/test_optimizers.py` | 3 | ✅ |
| `tests/unit/test_utils_and_schedulers.py` | 4 | ✅ |
| `tests/unit/test_serving.py` | 4 | ✅ |
| `tests/integration/test_pipeline.py` | 1 | ✅ |

---

## License

MIT License. See [LICENSE](LICENSE).
