NeuralDBG

Training failed? NeuralDBG tells you why. It hooks into your PyTorch training loop, detects what went wrong (vanishing gradients, exploding gradients, data anomalies), and pinpoints the exact layer and step — so you fix it in seconds, not hours.

Overview

NeuralDBG treats training as a semantic trace of learning dynamics rather than a black box. It extracts meaningful events and provides causal hypotheses about training failures, enabling researchers to:

• Identify gradient health transitions (stable -> vanishing/saturated)
• Detect activation regime shifts (normal -> saturated/dead)
• Detect optimizer instability (loss plateaus, spikes, divergence)
• Catch data anomalies (NaN, Inf, distribution shifts)
• Track propagation of instabilities through network layers
• Generate ranked causal explanations for training failures

Unlike traditional monitoring tools (TensorBoard, Weights & Biases), NeuralDBG focuses on causal inference rather than metric tracking.

Neural Suite

Request early access: open an issue with label suite-access.

Try it in 60 seconds (Colab)

Or locally: python examples/quickstart_interactive.py

Public benchmark

Reproducible causal accuracy on synthetic failures (details):

python -m benchmark_public.run

Latest results: benchmark_public/results.json

Why NeuralDBG?

"TensorBoard tells you when it failed. NeuralDBG tells you why."

Key Features

• Semantic Event Extraction: Detects meaningful transitions in training dynamics
• Causal Compression: Identifies first occurrences and propagation patterns
• Post-Mortem Reasoning: Provides ranked hypotheses about failure causes
• Optimizer Instability Detection: Tracks loss plateaus, spikes, and divergence
• Data Anomaly Detection: Catches NaN, Inf, and distribution shifts in inputs
• Event Collapsing: Merges sequential events into summary traces
• Compiler-Aware: Operates at module boundaries to survive torch.compile
• Non-Invasive: Wraps existing PyTorch training loops without code changes
• Minimal API: Focused on explanations, not raw data dumps
• Diagnostic package export: JSON export for the Neural Suite visualizer (private beta)

Quick Start

Installation

pip install neuraldbg

Basic Usage

import torch
import torch.nn as nn
from neuraldbg import NeuralDbg

# Your existing model and training setup
model = nn.Sequential(nn.Linear(10, 5), nn.ReLU(), nn.Linear(5, 1))
optimizer = torch.optim.SGD(model.parameters(), lr=0.01)
criterion = nn.MSELoss()

# Wrap your training loop
with NeuralDbg(model) as dbg:
    for step, (inputs, targets) in enumerate(dataloader):
        optimizer.zero_grad()

        outputs = model(inputs)
        loss = criterion(outputs, targets)
        loss.backward()
        dbg.record_loss(loss.item())
        optimizer.step()

# After training failure, query for explanations
explanations = dbg.explain_failure()
print(explanations[0])  # "Gradient vanishing originated in layer 'linear1' at step 234..."

Inference API

# Get ranked causal hypotheses for the failure
hypotheses = dbg.get_causal_hypotheses()

# Query specific causal chains
chain = dbg.trace_causal_chain('vanishing_gradients')

# Check for coupled failures
couplings = dbg.detect_coupled_failures()

# Export diagnostic package (JSON) for Neural Suite visualizer
dbg.export_aquarium_package('debug_session.json')

Optimizer Instability Detection

with NeuralDbg(model) as dbg:
    for step in range(num_steps):
        dbg.step = step
        output = model(inputs)
        loss = criterion(output, targets)
        loss.backward()
        dbg.record_loss(loss.item())
        optimizer.step()

# Detect loss plateaus, spikes, or divergence
hypotheses = dbg.explain_failure("optimizer_instability")
for h in hypotheses:
    print(h.description)

Data Anomaly Detection

Data anomalies (NaN, Inf, distribution shifts) are detected automatically from layer inputs during the forward pass:

with NeuralDbg(model) as dbg:
    # ... training loop ...
    pass

hypotheses = dbg.explain_failure("data_anomaly")
for h in hypotheses:
    print(h.description)  # "NaN values detected in input to layer 'linear1'..."

Supported Architectures

NeuralDBG has been validated across 9 architectures:

Supported Failure Types

Architecture

Core Components

• Semantic Event Extractor: Detects meaningful transitions in learning dynamics
• Causal Compressor: Identifies patterns and propagation in training failures
• Post-Mortem Reasoner: Generates ranked hypotheses about failure causes
• Compiler-Aware Monitor: Operates at safe boundaries for optimization compatibility

Event Types

Editions

The Core edition works standalone with basic heuristic fallbacks. Install the Engine for advanced causal reasoning.

Target Users

• ML Researchers seeking causal explanations for training failures
• PhD Students analyzing learning dynamics in novel architectures
• Research Engineers understanding optimization instabilities

Limitations

• PyTorch only
• Focus on semantic events, not tensor inspection

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

Developer Setup

make bootstrap
source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate     # Windows

License

MIT License - see LICENSE.md for details.

Documentation

• Landing page — branding and suite overview
• PyTorch support matrix
• CHANGELOG.md - Version history and notable changes
• logic_graph.md - System architecture and data flow
• docs/PHASE2_DOGFOODING.md - Detailed dogfooding scenarios

Citation

If you use NeuralDBG in your research, please cite:

@misc{neuraldbg2026,
  title={NeuralDBG: A Causal Inference Engine for Deep Learning Training Dynamics},
  author={SENOUVO Jacques-Charles Gad},
  year={2026},
  url={https://github.com/LambdaSection/NeuralDBG}
}