Post-Mortem Reasoner

Relevant source files

The following files were used as context for generating this wiki page:

• neuraldbg.py
• plans/reasoning_engine_analysis.md
• README.md
• infrastructure_planning/CODEBASE_GUIDE.md
• ROADMAP.md

The Post-Mortem Reasoner is the core diagnostic component of NeuralDBG, designed to provide structured, causal explanations for deep learning training failures. Unlike traditional monitoring tools that focus on raw metric tracking, the Reasoner treats training dynamics as a semantic trace, extracting meaningful events to generate ranked causal hypotheses about why a model failed. Sources: README.md, infrastructure_planning/CODEBASE_GUIDE.md

The Reasoner operates after a training session has concluded or failed, utilizing an Event-Driven Abductive Reasoning Model. It transforms low-level tensor statistics into high-level semantic descriptions, allowing researchers to identify root causes like vanishing gradients or activation saturation without manual inspection of raw data dumps. Sources: plans/reasoning_engine_analysis.md:8-12, README.md

Reasoning Architecture

The Post-Mortem Reasoner follows a specific pipeline to convert raw training data into actionable insights. This process is memory-efficient because it operates at module boundaries and does not require full tensor storage. Sources: plans/reasoning_engine_analysis.md:8-15, infrastructure_planning/CODEBASE_GUIDE.md

Logic Flow

The diagnosis follows a linear progression from data collection to hypothesis ranking:

Sources: plans/reasoning_engine_analysis.md:12-14

Core Components

The reasoning engine is composed of several specialized sub-modules:

Component	Functionality
Event Extractor	Converts PyTorch tensor stats (from forward/backward hooks) into semantic events.
State Classifier	Categorizes gradient/activation health based on specific thresholds (e.g., vanishing if < 1e-6).
Causal Compressor	Identifies the first occurrence and propagation patterns of failures to find root causes.
Hypothesis Generator	Uses rule-based abductive reasoning to link events and assign confidence scores.

Sources: plans/reasoning_engine_analysis.md:16-25, README.md, infrastructure_planning/CODEBASE_GUIDE.md

Semantic Event Processing

The Reasoner identifies "Semantic Events," which are high-level transitions in learning dynamics. These events serve as the building blocks for causal chains. Sources: README.md, infrastructure_planning/CODEBASE_GUIDE.md

Event Classification

The engine classifies health states for both gradients and activations:

• Gradient Health: Categories include HEALTHY, VANISHING, EXPLODING, and SATURATED.
• Activation Health: Categories include NORMAL, SATURATED, DEAD, and ANOMALOUS.

Sources: infrastructure_planning/CODEBASE_GUIDE.md, plans/reasoning_engine_analysis.md:210-215

Causal Chain Construction

Events are linked temporally and structurally. The Reasoner looks for "Coupled Failures"—events that occur in close temporal proximity (currently defined as within 5 steps) or propagate through network layers. Sources: plans/reasoning_engine_analysis.md:23-25, 415-418, README.md

Sources: plans/reasoning_engine_analysis.md:16-25, infrastructure_planning/CODEBASE_GUIDE.md

Diagnostic Capabilities

The Post-Mortem Reasoner is specifically tuned to detect and explain several failure modes common in deep learning. Sources: README.md, ROADMAP.md

Failure Mode Explanations

• Vanishing Gradients: Detects when gradients in early layers become too small to facilitate learning, often due to activation mismatches or extreme learning rates.
• Dead Neurons: Identifies layers (particularly ReLU-based) where activations become permanently zero.
• Activation Shifts: Monitors when neurons move from normal regimes to saturated or dead states.
• Instability Propagation: Tracks how an initial failure in one layer (the root cause) spreads to adjacent layers over subsequent steps.

Sources: README.md, infrastructure_planning/CODEBASE_GUIDE.md, plans/reasoning_engine_analysis.md:65-70

Causal Hypothesis Structure

Each hypothesis generated by the engine contains:

1. Failure Type: The nature of the instability (e.g., vanishing_gradients).
2. Origin: The specific layer and training step where the issue first appeared.
3. Confidence Score: A value (0.0 to 1.0) indicating the engine's certainty in the cause.
4. Causal Metadata: Information on propagation patterns and coupled events.

Sources: README.md, infrastructure_planning/CODEBASE_GUIDE.md

Implementation Methods

The following key methods within the NeuralDbg core engine manage the reasoning process:

• explain_failure(): The main entry point that triggers the reasoning logic and returns a list of hypotheses.
• get_root_causes(): Analyzes the event log to find the earliest layer and step associated with a failure chain.
• detect_coupled_failures(): Uses temporal proximity to find related events across different layers or parameters.
• export_mermaid_causal_graph(): Generates a visual representation of the causal chain for human review.

Sources: infrastructure_planning/CODEBASE_GUIDE.md, ROADMAP.md

Limitations and Roadmap

The current iteration of the Post-Mortem Reasoner primarily uses rule-based abductive reasoning with hardcoded thresholds. Sources: plans/reasoning_engine_analysis.md:27-32

Identified Gaps

• Lack of Predictive Power: The engine is purely reactive (post-mortem).
• Simple Heuristics: It relies on static thresholds rather than learned patterns.
• Limited Architecture Awareness: It does not yet differentiate between layer types (e.g., skip connections or normalization layers).

Sources: plans/reasoning_engine_analysis.md:34-45

Future Enhancements

Planned improvements include moving toward Pearl’s Ladder of Causation, incorporating counterfactual reasoning, and adding architecture-specific monitoring for Residual connections and Batch Normalization. Sources: plans/reasoning_engine_analysis.md:55-62, 430-440, ROADMAP.md

The Post-Mortem Reasoner provides a structured bridge between raw numerical instabilities and high-level architectural understanding, significantly reducing the time required to debug complex training failures in deep neural networks. Sources: README.md, infrastructure_planning/CODEBASE_GUIDE.md