Metadata-Version: 2.1
Name: neural_net_checklist
Version: 1.0.0
Summary: A ready-to-use implementation of Andrei Karpathhy's "recipe for training neural networks"
Author-Email: Andreas Kirsch <blackhc@gmail.com>
License: MIT
Requires-Python: >=3.10
Requires-Dist: torch>=2.4.0
Requires-Dist: pytest>=8.3.2
Requires-Dist: numpy>=2.0.1
Requires-Dist: tqdm>=4.66.5
Requires-Dist: pillow>=10.4.0
Requires-Dist: torchvision>=0.19.0
Description-Content-Type: text/markdown

# neural_net_checklist: A Codified Recipe for Training Neural Networks

This repository implements a set of diagnostic assertions based on Andrei Karpathy's blog post ["A Recipe for Training Neural Networks"](https://karpathy.github.io/2019/04/25/recipe/). Instead of a manual checklist, we provide programmatic checks to diagnose and debug neural networks efficiently.

## Why This Exists

Training neural networks can be tricky. This toolkit saves you time by automating common diagnostic steps, allowing you to focus on the interesting parts of your model development.

## What's Included

We've implemented the following checks:

1. **Verify loss @ init** (for balanced classification tasks)
   ```python
   assert_balanced_classification_cross_entropy_loss_at_init
   ```

2. **Init well** (for balanced classification tasks)
   ```python
   assert_balanced_classification_cross_entropy_loss_at_init
   ```

3. **Non-zero gradients**
   ```python
   assert_non_zero_gradients
   ```

4. **Batch independence**
   - Forward pass (memory-efficient, but note: batchnorm breaks this naturally)
     ```python
     assert_batch_independence_forward
     ```
   - Backward pass (uses more memory, checks gradients)
     ```python
     assert_batch_independence_backward
     ```

5. **Overfit one batch**
   ```python
   assert_overfit_one_batch
   ```

6. **Visualize just before the net**
   ```python
   patch_module_raise_inputs
   ```

## Quick Start

To run all assertions:

- For classification tasks (e.g., computer vision):
  ```python
  assert_all_for_classification_cross_entropy_loss
  ```

- For causal language models:
  ```python
  assert_all_for_llm_cross_entropy_loss
  ```

## Installation

```bash
pip install neural_net_checklist
```

## Usage Example

```python
import neural_net_checklist.torch_diagnostics as torch_diagnostics

# Assume you have a model and a DataLoader
model = YourModel()
train_loader = YourDataLoader()

# Run all checks
torch_diagnostics.assert_all_for_classification_cross_entropy_loss(model, train_loader)
```

## Contributing

Contributions are welcome! If you have ideas for additional checks or improvements, please open an issue or submit a pull request.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Happy debugging! Remember, neural nets can be finicky, but with the right tools, we can tame them. 🧠🔧
