# HuggingFace Accelerate

An Accelerate tracker that annotates a live Ingero eBPF trace with the
training step, so a recorded trace can be sliced per step after the run.

Accelerate has no per-step callback, but it has a tracker plugin API.
`IngeroTracker` is a `GeneralTracker` whose `.log(values, step=...)` the
agent rides: every `accelerator.log({...}, step=N)` your loop already
makes becomes one annotation. **If you train through
`transformers.Trainer`, use the `hf-trainer` integration instead.**

## What it does

`IngeroTracker` connects once to the agent's annotation socket and, on
every `accelerator.log` call, writes one NDJSON annotation scoped to the
training process PID with the `step` (and `epoch`, if you include it in
the logged values). The agent joins those labels to the eBPF event
stream; `ingero query` and `ingero explain` then slice the trace by
step.

It only fires when your loop calls `accelerator.log(..., step=N)`, which
most Accelerate loops already do for metrics. If yours does not, log on
the boundary you care about or annotate manually.

## Requirements

The agent must be running with the annotation ingest socket enabled:

    sudo ingero trace --record --annotate

If it is not, the tracker is a no-op: it logs one line and every call
returns without sending. It never crashes or slows the run.

## Use in your own loop

    from accelerate import Accelerator
    from ingero_accelerate import IngeroTracker

    acc = Accelerator(log_with=[IngeroTracker(run_id="my-run")])
    acc.init_trackers("my-project")
    ...
    acc.log({"loss": loss.item(), "epoch": epoch}, step=global_step)
    ...
    acc.end_training()

## Files

| File | Purpose |
|------|---------|
| `ingero_annotate.py` | Framework-agnostic NDJSON socket writer. Shared verbatim with the lightning / ray / hf-trainer integrations. |
| `ingero_accelerate.py` | The `IngeroTracker` GeneralTracker adapter. |
| `train_example.py` | A runnable end-to-end example. |
| `test_*.py`, `conftest.py` | pytest suite (fake socket server, no agent or accelerate needed). |

## Tests

    pip install pytest
    pytest
