Metadata-Version: 2.5
Name: pulsegrad
Version: 0.1.0
Summary: Live training telemetry and CLI for PyTorch — one-line integration for HF Trainer / TRL / vanilla PyTorch.
Project-URL: Homepage, https://github.com/manish181192/pulsegrad
Project-URL: Documentation, https://manish181192.github.io/pulsegrad/
Project-URL: Repository, https://github.com/manish181192/pulsegrad
Project-URL: Issues, https://github.com/manish181192/pulsegrad/issues
Author: Manish V.
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: debugging,gradients,machine-learning,observability,pytorch,telemetry,training
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115
Requires-Dist: msgpack>=1.1
Requires-Dist: pulsegrad-schemas<0.2,>=0.1.0
Requires-Dist: pydantic>=2.9
Requires-Dist: rich>=13.0
Requires-Dist: textual>=0.60
Requires-Dist: tomli-w>=1.0
Requires-Dist: typer>=0.13
Requires-Dist: uvicorn[standard]>=0.32
Provides-Extra: hf
Requires-Dist: peft>=0.13; extra == 'hf'
Requires-Dist: transformers>=4.45; extra == 'hf'
Description-Content-Type: text/markdown

# PulseGrad (`pug`)

**Live training telemetry and CLI for PyTorch.**

[![License: Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/manish181192/pulsegrad/blob/main/LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://github.com/manish181192/pulsegrad)
[![Docs](https://img.shields.io/badge/docs-guide-blue)](https://manish181192.github.io/pulsegrad/)

Training instability — loss spikes, dead adapters, vanishing gradients,
precision underflow — shows up first in the gradient/weight/activation stream,
not the loss curve. By the time loss visibly degrades you have often lost
minutes to hours of compute. PulseGrad instruments the optimizer step boundary
directly and turns that stream into localized, typed findings rather than raw
numbers a human has to interpret.

> **Status: early development.** The collector core (hooks, stat reducers,
> local SQLite store, CLI) is implemented. Read the
> [roadmap](https://github.com/manish181192/pulsegrad#roadmap) before depending
> on this in production.

## Install

```bash
pip install pulsegrad
```

PyTorch is a **peer dependency** — PulseGrad never installs or pins it, so your
existing CUDA/ROCm/CPU build is left exactly as it is. Bring your own `torch`.

For Hugging Face integrations (`transformers`, `peft`):

```bash
pip install "pulsegrad[hf]"
```

## Quickstart

```python
import pulsegrad as pug

pug.init()  # one line, before training starts — that's all

for batch in loader:  # a completely vanilla loop, no pulsegrad calls
    loss = model(batch).loss
    loss.backward()
    optimizer.step()
    optimizer.zero_grad()
```

Model, optimizer, steps, loss, learning rate, and end-of-run status
(completed/crashed, even on unhandled exceptions) are discovered and recorded
automatically — no per-step calls, no `close()`.

When auto-discovery cannot identify the right model — and it says so loudly
when that happens — `pulsegrad.watch(model, optimizer)` is the explicit form.
Both return the same `Session`.

Then, from a shell:

```bash
pug ls        # runs recorded so far
pug summary   # one-screen report on the latest run
```

## What the collector does

- **Zero-touch capture** — gradients read at the optimizer-step boundary
  (post-accumulation, semantically final), weights post-step, activation stats
  via sampled forward hooks. Per-module rows go to a local SQLite store behind
  a non-blocking writer thread.
- **Multi-model training** (GAN, DPO, distillation) — call `watch()` once per
  model; each gets its own run. Losses are scoped to the correct run by walking
  the loss tensor's autograd graph.
- **DDP-aware** — under `torchrun`, only rank 0 records, since post-allreduce
  gradients and weights are identical across ranks. Other ranks get an inert
  session, so the same script runs unmodified. `PULSEGRAD_ALL_RANKS=1` opts
  into per-rank runs.
- **Post-hoc CLI summary** — `pug summary` prints status, loss trajectory,
  NaN/Inf health with the first offending step and modules, top grad-norm
  modules, dead activations, and throughput.
- **Kill-switch** — `PULSEGRAD_DISABLED=1` makes the whole collector a no-op.

`import pulsegrad` resolves its public API lazily and does not import torch,
so adding it to a script costs approximately nothing until you call `init()`.

## Known limitations

- **Multi-evaluation optimizer closures aren't supported yet.** Optimizers
  whose `step(closure)` calls the closure more than once per step —
  `torch.optim.LBFGS` is the common case — desync PulseGrad's internal stats
  pairing and silently record no data for the affected steps. Training itself
  is unaffected; you just won't see anything in `pug ls` for that run. Tracked
  for a fix; everything else in this document is unaffected.

## Documentation

- [Researcher guide](https://manish181192.github.io/pulsegrad/) — `init()`/
  `watch()` usage, per-training-type guides, detector catalog.
- [Repository](https://github.com/manish181192/pulsegrad) — design docs,
  benchmarks, and roadmap.

## License

Apache-2.0. See
[LICENSE](https://github.com/manish181192/pulsegrad/blob/main/LICENSE).
