Metadata-Version: 2.5
Name: nn-htop
Version: 0.1.1
Summary: htop for Neural Networks: A terminal UI monitoring PyTorch layers, activations, and gradients in real-time.
Author-email: marviecephas <marviecephas@gmail.com>
License: MIT
Keywords: deep-learning,mlops,monitoring,pytorch,terminal,tui
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: rich>=13.0.0
Requires-Dist: textual>=0.50.0
Requires-Dist: torch>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

![nn-htop](demo.gif)

# nn-htop

A terminal-based monitor for PyTorch neural network layer activations and gradient norms (htop for PyTorch neural networks).

## Installation

```bash
pip install nn-htop
```

## Quickstart

Run the built-in demonstration harness (a 3-layer MLP training on synthetic tensor batches):

```bash
nn-htop
```

## Integration

Attach `Monitor` to any `torch.nn.Module` using context-managed hook lifecycle and launch the non-blocking Textual interface:

```python
import torch
import torch.nn as nn
from nn_htop import Monitor, launch_tui

model = nn.Sequential(
    nn.Linear(128, 64),
    nn.ReLU(),
    nn.Linear(64, 10),
)

with Monitor(model) as monitor:
    # Launches Textual TUI; non-blocking telemetry reads at 5 FPS
    launch_tui(monitor)
```

### Manual Training Loop Integration

If integrating into an existing custom training workflow:

```python
import threading
from nn_htop import Monitor, launch_tui

model = MyCustomModel()

with Monitor(model) as monitor:
    # Monitor registers full backward hooks and forward hooks on all leaf layers.
    # Metrics (mean activation, L2 gradient norm) are stored in a thread-safe state dictionary.
    launch_tui(monitor, train_fn=my_training_loop)
```

## Architecture

- **Hook Instrumentation**: Attaches `register_forward_hook` (mean activation tracking) and `register_full_backward_hook` (L2 gradient norm) to leaf modules. Automatically overrides `inplace=True` during monitoring to prevent autograd graph conflicts.
- **Memory Safety**: Tensors are detached and reduced to Python floats immediately inside hook callbacks to eliminate computational graph retention.
- **Decoupled Telemetry**: PyTorch training threads write strictly to atomic state dictionaries; the UI polls via `set_interval(0.2)` at 5 FPS to guarantee zero impact on training throughput.
