Metadata-Version: 2.5
Name: nansense
Version: 0.3.0
Summary: Pytorch debugger: step through the training process batch by batch, visualize gradients and activations, and run interpretability experiments
Project-URL: Homepage, https://github.com/kongaskristjan/nansense
Project-URL: Repository, https://github.com/kongaskristjan/nansense
Project-URL: Documentation, https://kongaskristjan.github.io/nansense/
Author-email: Kristjan Kongas <kongaskristjan@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: debugging,deep-learning,pytorch,training,visualization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: av>=17.1.0
Requires-Dist: captum>=0.9.0
Requires-Dist: fastapi>=0.110
Requires-Dist: matplotlib>=3.10.9
Requires-Dist: mcp>=2.0
Requires-Dist: nicegui>=3.12.1
Requires-Dist: numpy>=2
Requires-Dist: pillow>=12.2.0
Requires-Dist: plotly>=6.7.0
Requires-Dist: typing-extensions>=4.6; python_version < '3.11'
Requires-Dist: uvicorn>=0.30
Description-Content-Type: text/markdown

<h1 align="center">
  <img src="nansense/assets/logo_small.png" alt="NaNsense logo" height="36" align="middle"> NaNsense
</h1>

<p align="center"><em>Don't guess why your neural network fails to learn. Instead, have a look inside.</em></p>

https://github.com/user-attachments/assets/d7ee7ecc-4828-4655-866d-a220174c2b44

<p align="center"><em>The main NaNsense UI: click layers to see activations and gradients, measure receptive fields, collect per-channel statistics, and run deep dream mid-training.</em></p>

- 🕹️ **[Try the Playground](https://kongaskristjan.github.io/nansense/dev/playground/)** — inspect a trained network in your browser, no install
- ✨ **[Integrate with one prompt](https://kongaskristjan.github.io/nansense/dev/integrate/)** — a coding agent wires it into your training loop
- 🤖 **[Debug with a coding agent](https://kongaskristjan.github.io/nansense/dev/mcp/)** — it speaks MCP, so your agent can also debug your net
- 📚 **[Documentation](https://kongaskristjan.github.io/nansense/)** — showcase, guides and the full Python API (also as [llms.txt](https://kongaskristjan.github.io/nansense/llms.txt))

*NaNsense* is a PyTorch debugger that visualizes activations, gradients, weights, optimizer state and various statistics. You can **pause, step batch-by-batch, and time-travel to a different epoch while training**, and see exactly what every layer is doing.

Here's how *NaNsense* can help:

- **See what is actually going on**. Visualize activations and gradients, find image patches with minimal or maximal activation for a given channel, and simulate what each neuron is searching for (deep dream)
- **Spot optimization bottlenecks**. Discover insufficient receptive fields, measure neuron death, discover padding artifacts and spot gradient underflow

Unlike wandb or TensorBoard, which log external metrics (loss, accuracy) to scroll through after the run, NaNsense is about understanding the internals of the network. A logger tells you *that* the loss stopped falling; NaNsense shows you *why* — say, a layer's channels dying or fp16 gradients underflowing.

## Try it

Clone the repository and run a bundled example with [uv](https://docs.astral.sh/uv/getting-started/installation) — Python, dependencies, datasets and pretrained networks download automatically, and a browser tab opens with the UI:

```bash
# Install uv (Windows: https://docs.astral.sh/uv/getting-started/installation):
curl -LsSf https://astral.sh/uv/install.sh | sh

git clone https://github.com/kongaskristjan/nansense
cd nansense

# --group: cpu | cuda (NVIDIA) | cuda-legacy (pre-Turing NVIDIA) | rocm (AMD)
uv run --group cpu examples/standard/main.py --nansense-port 8080
```

[Getting started](https://kongaskristjan.github.io/nansense/dev/getting-started/) lists all the examples and explains the hardware groups.

## Use it in your project

```bash
pip install nansense
```

Wiring it into a training loop is a few lines of code: paste [one prompt](https://kongaskristjan.github.io/nansense/dev/integrate/) into your coding agent, or follow the [Wiring guide](https://kongaskristjan.github.io/nansense/dev/wiring/) yourself.

See [`INTERNALS.md`](INTERNALS.md) for how it works under the hood (it's long).
