Metadata-Version: 2.3
Name: syvain-training-utils
Version: 0.0.170
Summary: Shared runtime, diagnostics, and checkpoint utilities for Syvain training runs
Requires-Dist: obstore>=0.11.0,<0.12.0
Requires-Dist: pydantic>=2.13.4
Requires-Dist: torch>=2.13.0
Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
Requires-Dist: ruff>=0.15.12 ; extra == 'dev'
Requires-Dist: ty>=0.0.34 ; extra == 'dev'
Requires-Python: >=3.14, <3.15
Provides-Extra: dev
Description-Content-Type: text/markdown

# syvain-training-utils

Internal [Syvain](https://syvain.com/) helpers for small, explicit ML training
runs. No secret sauce here, just shared runtime, device-diagnostic, and
checkpoint patterns.

## Install

```bash
uv add syvain-training-utils
```

## Runtime setup

```python
from syvain_training_utils import (
    generate_run_id,
    require_torch_compile_toolchain,
    select_device,
)

run_id = generate_run_id()
device = select_device()
require_torch_compile_toolchain()
```

## Device smoke test

```python
import json

from syvain_training_utils import run_device_smoke_test

report = run_device_smoke_test(require_cuda=True)
print(json.dumps({"smoke": report}, indent=2, sort_keys=True))
```

## Checkpoint a training run

```python
from syvain_training_utils import (
    TrainingLoopState,
    load_training_checkpoint_if_available,
    save_model_checkpoint,
)

loop_state = TrainingLoopState(
    global_step=global_step,
    curriculum_stage=curriculum_stage,
    curriculum_step=curriculum_step,
)

save_model_checkpoint(
    object_store=object_store,
    base_path=base_model_path,
    experiment_slug=experiment_slug,
    run_id=run_id,
    model=model,
    optimizer=optimizer,
    scheduler=scheduler,
    loop_state=loop_state,
    checkpoint_label=f"step-{global_step:012d}",
)

resume = load_training_checkpoint_if_available(
    object_store=object_store,
    base_path=base_model_path,
    model=model,
    optimizer=optimizer,
    scheduler=scheduler,
    device=device,
)
```

The manifest remains a small pointer to the current checkpoint. Each checkpoint
contains the model, optimizer, optional scheduler, and PyTorch RNG state needed
by the common single-file training-run contract.
