Metadata-Version: 2.4
Name: launchhelm
Version: 0.1.1
Summary: LaunchHelm client and cooperative workload runtime
Project-URL: Homepage, https://launchhelm.com
Project-URL: Documentation, https://launchhelm.com/docs/
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: cooperative,launchhelm,runtime,telemetry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx<1,>=0.28.1
Requires-Dist: jsonschema<5,>=4.25.1
Requires-Dist: referencing<1,>=0.36.2
Provides-Extra: hf
Requires-Dist: accelerate>=1.1; extra == 'hf'
Requires-Dist: torch>=2.5; extra == 'hf'
Requires-Dist: transformers>=4.46; extra == 'hf'
Provides-Extra: lightning
Requires-Dist: lightning>=2.4; extra == 'lightning'
Requires-Dist: torch>=2.5; extra == 'lightning'
Provides-Extra: system
Requires-Dist: nvidia-ml-py>=12.560; extra == 'system'
Requires-Dist: psutil>=6.1; extra == 'system'
Provides-Extra: torch
Requires-Dist: torch>=2.5; extra == 'torch'
Description-Content-Type: text/markdown

# LaunchHelm

Training telemetry and live control for Python and PyTorch — the SDK for
[LaunchHelm](https://launchhelm.com). The SDK runs inside your training
process; Mission Control, the dashboard, charts the run and applies your
controls.

Requires Python 3.11 or later on macOS, Linux, or Windows.

## Install

```bash
pip install launchhelm
```

| Extra | For |
| --- | --- |
| `launchhelm[torch]` | PyTorch adapter: watched trainer, live controls, DDP, checkpoints |
| `launchhelm[system]` | host metrics (psutil) and per-GPU stats (NVML) |
| `launchhelm[hf]` | `transformers.Trainer` callback (`launchhelm.torch.hf`) |
| `launchhelm[lightning]` | PyTorch Lightning callback (`launchhelm.torch.lightning`) |

## Quickstart

In Mission Control, open the organization's **Projects** page and choose
**New project** — it creates the project and a project key in one step.
The key is shown once. Save it before you leave:

```bash
export LAUNCHHELM_API_KEY=lh_...        # shown once — never commit it
export LAUNCHHELM_ORGANIZATION=...      # organization UUID
export LAUNCHHELM_PROJECT=...           # project UUID
# export LAUNCHHELM_URL=https://launchhelm.com   # optional; this is the default
```

A `.env` file in the working directory or a parent works too; exported
shell variables take precedence. Then in the training script:

```python
import launchhelm

with launchhelm.init("quickstart", config={"lr": 3e-4, "batch": 64}) as run:
    for step in range(100):
        loss = train_one_step()
        run.log({"loss": loss}, step=step)
```

The first argument is the project **name**, which must match the project
the key belongs to; `LAUNCHHELM_PROJECT` is that project's **UUID**.

## Rich values

Beyond scalars, a stream can carry rendered values — text, media, tables
and histograms:

```python
run.text("notes", "## epoch 4\nloss **0.25**", format="markdown")
run.image("frames", "confusion.png")
run.log_table("sweep", [("lr", "number")], [[3e-4]])
run.histogram("grad", gradient_samples, bins=64)
```

Media uploads don't block the loop; `flush()` waits for them.

## PyTorch

```bash
pip install "launchhelm[torch]"
```

```python
import launchhelm.torch as lht

tr = lht.init("quickstart", config={"lr": 3e-4, "batch": 64})
model, optimizer = build()
tr.watch(model, optimizer, scheduler=sched)

for step in range(steps):
    loss = train_one_step()
    tr.clip_grad_norm_()          # current (controllable) max norm
    optimizer.step(); sched.step()
    tr.step(loss=loss, samples=batch_size)   # logs + services control; call on every rank

tr.save_checkpoint(extra={"epoch": epoch})
tr.finish()
```

`tr.step` logs the built-in series (`train/loss`, `optim/lr/group<i>`,
`optim/grad_norm`, `perf/step_time_s`, `perf/samples_per_s`,
`perf/tokens_per_s`) and services controls from the dashboard: `lr`,
`weight_decay`, `grad_clip`, `dropout`, `checkpoint`, `eval`, plus
`tr.tunable(name, ...)` for custom knobs. In DDP, call `step` on every
rank at the same cadence — a control applies on every rank at the same
step.

`save_checkpoint` writes a `torch.load(weights_only=True)`-safe bundle —
model, optimizer, scheduler, scaler, step, per-rank RNG, tunables,
`extra` — and a crash-resume finds the latest one.
`load_checkpoint("latest")` restores it. For FSDP models, configure a
full state dict before saving.

System metrics without torch: `launchhelm.system.start(run)` (the
`system` extra) emits CPU, memory, disk/network rates and per-GPU stats
under `system/...`.

Framework callbacks: `launchhelm.torch.hf.LaunchHelmCallback` (`hf`
extra) and `launchhelm.torch.lightning.LaunchHelmCallback` (`lightning`
extra) wire the same lifecycle through each framework's callback API.

## Delivery

| Call | Guarantee |
| --- | --- |
| `run.log(...)` | queued for upload |
| `run.flush(delivered=False)` | durable on this machine — survives a crash, uploads on restart |
| `run.flush()` | stored on the server — query-visible when it returns |
| `run.finish()` | delivers everything, then ends the run |

## Links

- [launchhelm.com/docs](https://launchhelm.com/docs/) —
  [getting started](https://launchhelm.com/docs/getting-started/),
  [Python guide](https://launchhelm.com/docs/python/),
  [concepts](https://launchhelm.com/docs/concepts/)
- Changelog: `CHANGELOG.md`, shipped in the source distribution
