PulseML

The live debugger for machine learning.

Observe your training. Intercept failures. Reason about the cause. Verify the math. Fix the code.

Pulse is an agentic ML debugging system for Python training scripts. It monitors tensors, metrics, and training behavior in real time, automatically intercepts runtime errors, analyzes the relevant code, develops fixes, verifies mathematical changes, and can restart the training process with those fixes applied.

Pulse works across major ML backends and is designed to debug models while they are being developed and trained, rather than only after something has gone wrong.

Website · PyPI

---

Quickstart

Import auto_track immediately before your training loop.

Make sure your training code is wrapped in if __name__ == '__main__':.

from pulse import auto_track

if __name__ == '__main__':
    auto_track()

    for epoch in range(num_epochs):
        # Your training code
        pass

Pulse discovers variables available for monitoring and launches the debugging interface.

The recommended interface is now the CLI, which keeps training output, diagnostics, agent interaction, and error handling in the same terminal.

---

What Pulse Does

Traditional ML debugging often looks like:

TRAIN
  |
  v
CRASH
  |
  v
READ TRACEBACK
  |
  v
GUESS
  |
  v
EDIT CODE
  |
  v
RUN AGAIN

Pulse turns this into an active debugging loop:

                  TRAINING
                     |
                     v
                OBSERVATION
                     |
                     v
              ERROR / ANOMALY
                     |
                     v
               USER PROMPT
                     |
                     v
                AI ANALYSIS
                     |
                     v
              SOLUTION DEVELOPMENT
                     |
                     v
                 IMPLEMENT
                     |
                     v
              VERIFY THE FIX
                /         \
             PASS         FAIL
              |             |
              v             v
           RESTART       RETRY
              |             |
              +------<------+
                     |
                     v
             CHECK FULL SCRIPT
                     |
                     v
              CONTINUE TRAINING

Pulse isn't just a tensor viewer.

It is becoming an agentic debugging loop for ML training code.

---

Agentic Debugging

Pulse's AI analyst now operates through a multi-step debugging process designed to investigate failures rather than immediately guess at a fix.

1. Scan the Entire Script

When debugging begins, the agent first examines the full training script.

It identifies:

• The structure of the program
• The training loop
• Model components
• Relevant variables
• Dependencies between regions of code
• The location associated with the failure
• Other potentially related sections

The goal is to determine where the debugging problem actually lives before making changes.

FULL SCRIPT
     |
     v
SCAN
     |
     v
LOCATE RELEVANT REGION

---

2. Focus and Propose a Solution

Once the relevant region has been identified, the agent focuses its reasoning on that section.

It combines information from:

• Source code
• Runtime errors
• Tensor statistics
• Matrix values
• Scalar curves
• Gradients
• Activations
• Training behavior
• Previous debugging context

The agent then proposes a concrete solution before modifying the code.

CODE + RUNTIME STATE + ERROR
              |
              v
          ANALYSIS
              |
              v
        PROPOSED SOLUTION

---

3. Develop and Implement

After determining the solution, the agent develops the required code changes and implements them directly into the training script.

This separates figuring out the solution from actually modifying the program.

PROBLEM
   |
   v
SOLUTION
   |
   v
DEVELOP
   |
   v
IMPLEMENT

---

4. Verify the Solution

Pulse doesn't stop after changing the code.

The agent can check the mathematical correctness of the proposed solution using Pulse's deterministic math evaluation system.

This allows the agent to verify things such as:

• Scaling factors
• Gradient relationships
• Normalization
• Update magnitudes
• Ratios
• Numerical thresholds
• Other exact mathematical expressions

The LLM handles reasoning.

Pulse handles exact numerical evaluation.

             AGENT
               |
       +-------+-------+
       |               |
   REASONING        MATH CHECK
       |               |
       |        DETERMINISTIC
       |          EVALUATION
       |               |
       +-------+-------+
               |
               v
          VERIFIED FIX

If the solution is unsuccessful, the agent can return to the implementation stage and retry with a revised solution.

IMPLEMENT
    |
    v
VERIFY
  /   \
PASS   FAIL
 |      |
 v      v
DONE   RETRY
        |
        +----> DEVELOP

---

5. Check the Overall Script

After a successful fix, Pulse checks the rest of the script for additional errors.

If another problem is found, Pulse doesn't silently continue modifying the program.

Instead, it prompts the user and asks whether they want to debug the newly discovered issue.

This allows debugging to continue through multiple independent failures while keeping the user in control.

FIX SUCCESSFUL
      |
      v
SCAN SCRIPT AGAIN
      |
   +--+--+
   |     |
 CLEAN  ERROR
   |     |
   v     v
TRAIN   PROMPT USER
         |
         v
      DEBUG?

---

Automatic Error Interception

Pulse can now intercept errors thrown by Python itself, not just errors that Pulse specifically detects.

For example, if the training script encounters a normal Python exception, Pulse can capture the failure and present the user with the option to send it through the debugging agent.

YOUR TRAINING SCRIPT
        |
        v
   PYTHON ERROR
        |
        v
     PULSE
        |
        v
"Would you like the agent
 to debug this error?"

This means Pulse can operate as a layer around the training process rather than requiring every possible failure mode to be manually implemented into the debugger.

The user remains in control of whether an error should be handed to the agent.

---

Automatic Training Restart

One of Pulse's newest capabilities is the ability to restart the training script after code has been modified.

When restarting, Pulse preserves important runtime state such as:

• The model
• The AI API key
• Relevant debugging state

That state is passed into the restarted process so that the changes made by the agent can immediately be tested.

TRAINING
   |
   v
ERROR
   |
   v
DEBUG
   |
   v
IMPLEMENT FIX
   |
   v
RESTART TRAINING
   |
   +---- Model preserved
   |
   +---- API key preserved
   |
   +---- Debugging context preserved
   |
   v
TEST THE FIX

This turns code modification into an iterative test-and-repair loop instead of requiring the user to manually stop, edit, restart, and reconnect everything.

---

Live Tensor Debugging

Pulse can monitor tensors and variables directly inside your training loop.

Features include:

• Live matrix visualization
• Tensor shapes and statistics
• Heatmaps
• Gradient monitoring
• Activation monitoring
• Real-time scalar tracking
• Loss and metric curves
• Runtime diagnostics

Pulse is designed to make the internal state of a model visible while it is actually training.

---

Smart Scalars

Pulse automatically recognizes scalar values such as:

• Loss
• Accuracy
• Learning rate
• Gradient norms
• Other numerical training metrics

Instead of rendering scalars as matrices, Pulse displays them as live step charts.

Loss-like variables can also be automatically detected and pre-selected during setup.

---

CLI-First Debugging

Pulse's CLI is now the primary interface.

The GUI is being deprecated in favor of the CLI because debugging is more effective when the user can keep everything in one environment.

Instead of switching between a training process, graphical dashboard, and terminal, Pulse keeps the debugging workflow directly alongside the training output.

The CLI is designed for:

• Local development
• Google Colab
• SSH
• Remote GPUs
• Headless servers

It provides:

• Live tensor statistics
• ASCII scalar charts
• Matrix tracking
• Training pause/resume
• Adding variables while training
• AI analysis directly from the terminal
• Automatic error interception
• Agentic debugging
• Training restarts
• Optional labeled PDF snapshots

Why CLI?

ML debugging is inherently iterative.

You often need to:

TRAIN
  ↓
SEE ERROR
  ↓
READ DIAGNOSTICS
  ↓
ASK AGENT
  ↓
MODIFY CODE
  ↓
RESTART
  ↓
OBSERVE RESULT

Keeping that workflow in the terminal removes the need to constantly move between separate interfaces.

---

GUI Status

The Pulse GUI is deprecated.

The project is moving toward a CLI-first workflow because the CLI provides a more direct environment for:

• Training output
• Runtime errors
• Agent interaction
• Code debugging
• Restarts
• Tensor diagnostics

The GUI may remain available for compatibility, but new development is focused primarily on the CLI and agentic debugging system.

---

Deterministic Math Verification

LLMs should reason about math. They shouldn't be the calculator.

During ML debugging, an agent may need to calculate:

• Update magnitudes
• Ratios
• Scaling factors
• Normalization values
• Gradient relationships
• Numerical thresholds
• Other exact mathematical expressions

Rather than relying on the LLM to perform these calculations itself, Pulse provides a deterministic mathematical evaluation layer.

The agent can delegate an expression to the evaluator and use the exact result in its reasoning.

The evaluator uses a restricted namespace containing mathematical operations and the Python math module while disabling builtins.

This gives the agent a reliable computational primitive for checking numerical claims instead of estimating them.

---

Universal Backend Support

Pulse is designed to work across major ML frameworks.

Backend	Support
NumPy	Yes
PyTorch	Yes
TensorFlow	Yes
CuPy	Yes
JAX	Yes

A shared backend abstraction allows Pulse to inspect and monitor tensors across different frameworks without requiring major changes to the user's training code.

---

Performance

Instrumentation should not become the bottleneck.

Pulse is designed to minimize debugging overhead through:

• Matrix caching
• Host-side NumPy conversion
• Reusable Matplotlib figures
• set_data() updates instead of rebuilding plots
• Render sizes matched to actual thumbnails
• Selective tracking of monitored variables

The objective is simple:

More visibility. Less overhead.

---

Real Debugging Examples

Vocabulary Expansion Causing Training Instability

A custom LLM experienced training instability after a 2.5× vocabulary increase.

Pulse's diagnostics exposed a normalization problem where residual growth was divided by:

sqrt(num_layers)

instead of:

num_layers

This caused activation growth that eventually destabilized training and halted learning.

---

Custom Attention Producing NaN Loss

Another debugging session involved a custom attention implementation producing NaN loss.

Pulse helped trace the failure to a missing infinity check before a division operation.

---

AI Providers

Pulse supports multiple AI providers through environment variables:

ANTHROPIC_API_KEY
OPENAI_API_KEY
GEMINI_API_KEY
DEEPSEEK_API_KEY

If no key is configured, Pulse can prompt for one when the AI analyst is first used.

API keys can also be preserved across Pulse-managed training restarts so the debugging workflow can continue without requiring the user to reconnect the agent.

---

Install

pip install pulseml

tkinter is required for legacy GUI mode and ships with most Python installations.

On Debian/Ubuntu:

sudo apt install python3-tk

For CLI-mode PDF snapshots, fpdf2 is installed automatically with the base package.

---

The Goal

Pulse is being built toward a different kind of ML debugging workflow.

                    TRAINING
                       |
                       v
                  OBSERVATION
                       |
                       v
                ERROR / ANOMALY
                       |
                       v
                SCAN FULL SCRIPT
                       |
                       v
                 FOCUS REGION
                       |
                       v
                PROPOSE SOLUTION
                       |
                       v
                     DEVELOP
                       |
                       v
                   IMPLEMENT
                       |
                       v
                VERIFY THE MATH
                       |
                 +-----+-----+
                 |           |
               PASS         FAIL
                 |           |
                 v           v
              RESTART      RETRY
                 |           |
                 +-----+-----+
                       |
                       v
                 CHECK SCRIPT
                       |
                 +-----+-----+
                 |           |
               CLEAN        ERROR
                 |           |
                 v           v
              TRAIN       ASK USER

The goal isn't simply to tell you that your model is broken.

Pulse should help you find where the problem is, understand why it happens, develop the solution, verify the mathematics, implement the fix, restart the training process, and continue debugging until the script is working.

---

License

Proprietary. See LICENSE.

Use of this software is governed by the terms in that file. Copying, redistribution, and reverse engineering are not permitted.