Coupled Failures Detection
Relevant source files
The following files were used as context for generating this wiki page:
Coupled Failures Detection is a core analytical capability of the NeuralDBG reasoning engine designed to identify temporal and structural links between different training anomalies. Within the framework of NeuralDBG, failures are not treated as isolated incidents but as interconnected "Semantic Events" that propagate through the network's layers or across training steps.
The primary purpose of this system is to perform Causal Compression, reducing thousands of raw tensor observations into a small set of root causes by detecting propagation patterns and coupled dependencies. This allows the engine to distinguish between a primary failure (e.g., vanishing gradients in an early layer) and its downstream consequences (e.g., optimizer instability in later layers).
Sources: README.md, infrastructure_planning/CODEBASE_GUIDE.md, plans/reasoning_engine_analysis.md:12-25
Architecture and Logic
The detection of coupled failures follows an Event-Driven Abductive Reasoning Model. The system identifies relationships by analyzing the metadata of SemanticEvent objects, focusing on their layer identifiers, training steps, and confidence scores.
Temporal Proximity Logic
The current implementation of pattern detection relies on simple temporal proximity. Events are considered "coupled" if they occur within a specific window of each other.
- Proximity Threshold: 5 training steps.
- Logic: If
abs(event1.step - event2.step) <= 5, the system flags a potential coupling.
This logic is summarized in the following data flow:
The diagram shows how raw metrics are transformed into semantic events before being analyzed for temporal coupling to generate causal hypotheses.
Sources: plans/reasoning_engine_analysis.md:12-25, 458-463
Key Data Structures
The detection mechanism relies on the relationship between specific classes:
| Structure | Role in Coupled Detection |
|---|---|
SemanticEvent | Contains step_range, layer_id, and causal_metadata. |
NeuralDbg | The core engine class containing the detect_coupled_failures() method. |
CausalHypothesis | Represents the outcome of coupling analysis, including the causal chain and evidence. |
Sources: neuraldbg.py, infrastructure_planning/CODEBASE_GUIDE.md, README.md
Implementation Mechanisms
Coupled Failures Detection operates within the NeuralDbg class, which serves as the "Hub" for all reasoning logic. It utilizes PyTorch hooks attached to module boundaries to observe the propagation of instabilities without storing full tensors.
Detection Methods
The engine provides high-level API methods to query these relationships:
detect_coupled_failures(): Identifies temporal and structural links between detected events.trace_causal_chain(failure_type): Queries specific chains where one event triggered another.get_root_causes(): Identifies the specific layer and step where a coupled failure originated.
Causal Chain Visualization
NeuralDBG can export the detected couplings into a visual format using Mermaid diagrams to help developers understand the propagation.
This diagram illustrates a typical causal chain detected by the engine, showing how an initial vanishing gradient in Layer 1 can be coupled with neuron death in Layer 2, eventually leading to instability in Layer 3.
Sources: README.md, infrastructure_planning/CODEBASE_GUIDE.md, plans/reasoning_engine_analysis.md:12-25
Known Limitations and Future Roadmap
The current system primarily detects correlation rather than true causation, as it relies heavily on temporal proximity rather than structural intervention.
| Limitation | Description | Proposed Solution |
|---|---|---|
| Simple Heuristics | Threshold-based (e.g., 5-step window) rather than learned. | Implement Statistical Process Control (SPC). |
| No Counterfactuals | Cannot suggest "what if" scenarios. | Move toward Pearl's Ladder Level 3 reasoning. |
| First-Order Only | Often misses complex, high-order causal loops. | Implement Structural Causal Models (SCM). |
Moving Toward Structural Causal Models (SCM)
Plans involve moving from simple temporal precedence to a more robust CausalReasoningEngine. This will involve:
- Temporal Precedence: Verifying if Event A always precedes Event B.
- Causal Graph Learning: Building a Directed Acyclic Graph (DAG) of known ML failure modes (e.g., High Learning Rate $\rightarrow$ Exploding Gradients).
- Confidence Calibration: Calculating the probability of a coupling based on architectural awareness (e.g., understanding skip connections in ResNets).
Sources: plans/reasoning_engine_analysis.md:38-51, 465-515
Conclusion
Coupled Failures Detection distinguishes NeuralDBG from traditional metric-tracking tools by providing a semantic understanding of training failures. By linking events across time and layers, it enables the generation of ranked causal hypotheses that point to root causes rather than symptoms. While currently based on temporal proximity heuristics, the architecture is designed to evolve toward complex causal inference models.
Sources: README.md, plans/reasoning_engine_analysis.md:12-25