gpupulse 0.3.1

Local-first experiment journal for the GPUPulse Mac and iPhone apps

GPUPulse Python SDK

GPUPulse is a local-first experiment journal for the GPUPulse Mac, iPhone and Android apps. Training writes only to an append-only file; it never waits for the Mac, a network request or a hosted tracking server.

Five-minute start

1. Install

python -m pip install gpupulse

During local development, install this checkout instead:

python -m pip install -e ./python

2. Add three calls

import gpupulse

run = gpupulse.init(
    project="lnet",
    name="fair-boundary",
    group="ablation-july",
    tags=["b200", "baseline"],
    notes="First run with the new sampler",
    config={"batch_size": 64, "learning_rate": 1e-4},
)

for step in range(100):
    loss, accuracy = train(step)
    gpupulse.log(
        {"loss": loss, "accuracy": accuracy},
        step=step,
        progress=(step + 1) / 100,
    )

gpupulse.finish()

The Mac collector discovers new events over the existing SSH connection. Progress, ETA, live metrics and completion alerts then appear in GPUPulse.

3. Confirm the agent

gpupulse status
gpupulse runs --limit 10

The default journal is ~/.gpupulse/journal/events.jsonl. Override it with GPUPULSE_JOURNAL.

Context manager

from gpupulse import Run

with Run(project="lnet", name="fair-boundary", tags=["nightly"]) as run:
    run.config({"batch_size": 64})
    for step in range(100):
        run.log({"loss": 1 / (step + 1)}, step=step, progress=(step + 1) / 100)

Exceptions and SIGTERM are recorded as failures. A normal context exit records success.

Decorator

import gpupulse

@gpupulse.track(project="research", tags=["quick-check"], inject_run=True)
def train_model(dataset, run=None):
    run.config({"dataset": dataset.name})
    ...

Both synchronous and async functions are supported. The original exception is always re-raised after it is journaled.

PyTorch Lightning

from gpupulse import GPUPulseLightningCallback

trainer = Trainer(callbacks=[
    GPUPulseLightningCallback(
        project="vision",
        name="resnet50",
        group="imagenet-sweep",
        tags=["lightning", "b200"],
    )
])

The callback reads callback_metrics, global_step and estimated_stepping_batches. GPUPulse does not import or install Lightning itself.

Hugging Face Trainer

from gpupulse import GPUPulseTrainerCallback

trainer = Trainer(
    ...,
    callbacks=[GPUPulseTrainerCallback(
        project="llm",
        name="lora-7b",
        tags=["transformers", "lora"],
    )],
)

on_log values become GPUPulse metrics and global_step / max_steps becomes progress.

Journal operations

gpupulse status --json
gpupulse runs --project lnet --limit 20 --json
gpupulse export --since 0 --format jsonl
gpupulse prune --keep-days 30

Set retention_days=30 on Run, or set GPUPULSE_RETENTION_DAYS=30, to prune at most once per day. Pruning changes the cursor generation so a Mac holding an older cursor safely re-reads retained events instead of skipping them.

Privacy and performance

• No network dependency is added to training.
• Metric calls use a bounded background queue and never wait for disk.
• Config keys containing passwords, secrets, tokens, API keys or credentials are recursively redacted.
• Use config_allowlist=[...] when only explicitly approved config keys should be stored.
• SSH credentials, full commands and working directories are never written by this SDK.