Semantic Event Data Structure

Relevant source files

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

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

The Semantic Event Data Structure is the foundational information unit within NeuralDBG, designed to capture high-level transitions in neural network training dynamics. Unlike traditional debuggers that store raw tensor snapshots, NeuralDBG extracts meaningful "events"—such as gradient health transitions or activation regime shifts—to enable memory-efficient causal inference and post-mortem reasoning.

These structures allow the system to treat training as a semantic trace of learning dynamics. By focusing on state changes (e.g., from HEALTHY to VANISHING) rather than raw data, the engine can identify the root causes of training failures and track the propagation of instabilities through network layers.

Sources: README.md:14-22, neuraldbg.py:53-58, infrastructure_planning/CODEBASE_GUIDE.md:12-16

Core Data Models

The system relies on several key data structures to define the state and transitions of a neural network during training.

SemanticEvent Class

The SemanticEvent dataclass is the primary container for a detected transition. It encapsulates the type of event, its location in the model, the time (step) it occurred, and the nature of the state change.

Field	Type	Description
event_type	EventType	Categorization of the event (e.g., Gradient vs Activation).
layer_name	str	The identifier of the specific layer where the event was detected.
step	int	The training step number at which the transition occurred.
from_state	Any	The health state of the component prior to the transition.
to_state	Any	The health state of the component after the transition.
confidence	float	A score (0.0 to 1.0) representing the certainty of the detection.
metadata	Dict	Supporting stats such as saturation ratios or gradient norms.

Sources: neuraldbg.py:53-67, logic_graph.md:21-28, infrastructure_planning/CODEBASE_GUIDE.md:31-31

State Enums

The data structure utilizes specific Enums to categorize the "health" of gradients and activations.

• EventType: Defines high-level categories including GRADIENT_HEALTH_TRANSITION, ACTIVATION_REGIME_SHIFT, OPTIMIZER_INSTABILITY, and DATA_ANOMALY.
• GradientHealth: Categorizes gradient norms as HEALTHY, VANISHING, EXPLODING, or SATURATED.
• ActivationHealth: Monitors activation regimes, classifying them as NORMAL, SATURATED, DEAD, or ANOMALOUS.

Sources: neuraldbg.py:28-51, infrastructure_planning/CODEBASE_GUIDE.md:28-30

Event Lifecycle and Logic Flow

Semantic events are generated through non-invasive PyTorch hooks attached to model boundaries. This lifecycle ensures that data is captured during both forward and backward passes without manual code changes to the training loop.

Detection Logic

The generation of an event is gated by specific thresholds and state comparison logic:

1. Gradient Health: A transition is detected if the gradient norm moves across thresholds (default: 1e-6 for vanishing, 1e3 for exploding).
2. Activation Health: A shift is recorded if the dead_ratio exceeds 0.9 or the saturation_ratio exceeds 0.7.
3. Confidence Scoring: For gradient transitions, confidence is calculated based on the magnitude of change (the ratio of change relative to the previous norm).

Sources: neuraldbg.py:192-230, plans/reasoning_engine_analysis.md:417-422

Relationship to Causal Inference

Semantic events serve as the "evidence" for CausalHypothesis objects. The reasoning engine analyzes the stream of events to identify temporal and structural patterns.

Coupling Detection

The engine identifies Coupled Failures by searching for events that occur within a specific temporal window (default: 5 steps). If an ACTIVATION_REGIME_SHIFT (e.g., saturation) is followed by a GRADIENT_HEALTH_TRANSITION (e.g., vanishing), the system identifies a potential causal link and boosts the confidence of the resulting hypothesis.

Sources: neuraldbg.py:352-386, plans/reasoning_engine_analysis.md:465-470

Summary of Feature Metadata

The metadata field in a SemanticEvent contains implementation-specific statistics used for deeper analysis during the reasoning phase.

Event Type	Metadata Fields
Activation Shift	prev_saturation, current_saturation, prev_dead, current_dead
Gradient Transition	prev_norm, current_norm, transition_type

Sources: neuraldbg.py:126-131, neuraldbg.py:157-161

The Semantic Event Data Structure effectively abstracts complex tensor interactions into a format suitable for abductive reasoning. By maintaining a chronological list of these events, NeuralDBG provides a traceable "autopsy" of training failures, allowing developers to identify whether an issue like vanishing gradients originated in a specific layer or was caused by activation saturation upstream.

Sources: README.md:45-51, infrastructure_planning/CODEBASE_GUIDE.md:48-55