Metadata-Version: 2.4
Name: pulseml
Version: 0.1.8
Summary: A live ML training debugger - GUI or CLI, any backend (NumPy, PyTorch, TensorFlow, CuPy, JAX).
Author-email: Yash Patel <codeyash09@gmail.com>
License: Proprietary
Project-URL: Homepage, https://github.com/codeyash09/PulseML
Project-URL: Issues, https://github.com/codeyash09/PulseML/issues
Keywords: machine-learning,deep-learning,debugging,pytorch,tensorflow,numpy,jax,cupy,training,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: pillow
Requires-Dist: litellm
Requires-Dist: fpdf2
Provides-Extra: torch
Requires-Dist: torch; extra == "torch"
Provides-Extra: tensorflow
Requires-Dist: tensorflow; extra == "tensorflow"
Provides-Extra: cupy
Requires-Dist: cupy-cuda12x; extra == "cupy"
Provides-Extra: jax
Requires-Dist: jax; extra == "jax"
Dynamic: license-file

# 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](https://pulsedb.netlify.app/) · [PyPI](https://pypi.org/project/pulseml/)

[![PyPI Downloads](https://static.pepy.tech/personalized-badge/pulseml?period=total\&units=NONE\&left_color=BLACK\&right_color=GREY\&left_text=downloads)](https://pepy.tech/projects/pulseml)

---

# Quickstart

Import `auto_track` immediately before your training loop.

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

```python
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:

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

Pulse turns this into an active debugging loop:

```text
                  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.

```text
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.

```text
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**.

```text
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.

```text
             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.

```text
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.

```text
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.

```text
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.

```text
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:

```text
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:

```text
sqrt(num_layers)
```

instead of:

```text
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:

```text
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

```bash
pip install pulseml
```

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

On Debian/Ubuntu:

```bash
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.

```text
                    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`](/pulse-pkg/LICENSE).

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