Interactive Demo & Examples

NeuralDBG includes interactive demos designed to showcase its capabilities as a causal inference engine for deep learning training dynamics. Unlike traditional metric trackers, these examples demonstrate how the system identifies "why" a model fails by extracting semantic events and building causal hypotheses.

The primary showcase is the vanishing gradient demo, which illustrates the transition from healthy training to failure states. This demo serves as a template for developers to understand the non-invasive integration of the NeuralDbg context manager within standard PyTorch training loops. Sources: README.md, infrastructure_planning/CODEBASE_GUIDE.md

Vanishing Gradient Demo

The vanishing gradient demo is a self-contained script that simulates a common deep learning failure. It uses a deep network architecture specifically designed to trigger vanishing gradients to show how NeuralDBG captures the root cause. Sources: infrastructure_planning/CODEBASE_GUIDE.md:65-72, demo_vanishing_gradients.py

Scenario Architecture

The demo sets up a specific environment to induce failure:

• Model: A deep network using Tanh activation functions, which are prone to saturation and vanishing gradients in deep architectures.
• Data: Small-scale synthetic data and a low learning rate to exacerbate the lack of signal propagation.
• Integration: The training loop is wrapped in the NeuralDbg context manager, which attaches hooks to observe layer-wise dynamics.

Sources: infrastructure_planning/CODEBASE_GUIDE.md:65-72, plans/reasoning_engine_analysis.md:144-150

Execution Flow

The following diagram illustrates the flow of the interactive demo from initialization to post-mortem analysis:

The demo execution flow shows how semantic events are extracted during training and processed into ranked hypotheses once the training context is exited. Sources: demo_vanishing_gradients.py, infrastructure_planning/CODEBASE_GUIDE.md:38-48

Core Demo Components

The demos rely on several key components within the NeuralDBG architecture to transform raw tensor data into meaningful explanations. Sources: README.md, infrastructure_planning/CODEBASE_GUIDE.md:38-48

Semantic Event Extraction

During the demo, PyTorch hooks fire during forward and backward passes. These hooks do not store full tensors but instead classify health states.

Sources: infrastructure_planning/CODEBASE_GUIDE.md:31-36, plans/reasoning_engine_analysis.md:12-20

Causal Reasoning Logic

Once the demo completes its training loop, the explain_failure() method is called. This initiates the reasoning engine's abductive logic.

This sequence demonstrates the post-training analysis where the engine compresses thousands of potential events into a few root causes. Sources: infrastructure_planning/CODEBASE_GUIDE.md:44-48, plans/reasoning_engine_analysis.md:12-20

Usage Example

The following code snippet demonstrates the standard pattern for using NeuralDBG in a research context, as seen in the package demos:

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

# Setup prone to failure
model = nn.Sequential(nn.Linear(10, 5), nn.Tanh(), nn.Linear(5, 1))
with NeuralDbg(model) as dbg:
    for inputs, targets in dataloader:
        outputs = model(inputs)
        loss = criterion(outputs, targets)
        loss.backward()
        optimizer.step()

# Query post-mortem
explanations = dbg.explain_failure()
for hypothesis in explanations:
    print(hypothesis)

Sources: README.md:55-75, demo_vanishing_gradients.py

Milestone and Roadmap Validation

Demos are a critical part of the project's quality assurance and validation cycle. According to the project's global rules, specific demo requirements must be met at each milestone. Sources: ROADMAP.md, plans/reasoning_engine_analysis.md:144-150

• Milestone Requirements: The project MUST have at least 2 working demos at each validation milestone (25%, 50%, 75%, 90%, 95%).
• Verification: Each demo must be runnable without errors and demonstrate different aspects of the product, such as vanishing gradients or dead neurons.
• Performance Tracking: Future demos are planned to include MLflow integration to track loss curves and gradient health automatically.

Sources: ROADMAP.md:12-25, infrastructure_planning/milestone_0_tasks.md:38-42

Interactive demos and examples serve as the primary evidence of NeuralDBG's epistemic value, proving that the system can successfully distinguish between correlation and causation in deep learning training failures. Sources: ROADMAP.md:50-55, plans/reasoning_engine_analysis.md:214-220