Metadata-Version: 2.4
Name: runtimelr
Version: 0.1.3
Summary: Runtime-controllable LR scaling for PyTorch LambdaLR via file-queue commands.
Author: thb-bici
License: MIT
Keywords: distributed,learning-rate,pytorch,scheduler,training
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: <3.14,>=3.10
Requires-Dist: torch>=2.0
Description-Content-Type: text/markdown

# runtimelr

Runtime LR control for PyTorch `LambdaLR` using a file-queue control plane.

## Features

- Wraps `torch.optim.lr_scheduler.LambdaLR`
- Runtime commands via JSON files in a queue directory
- Distributed-safe: rank 0 decides polling, broadcasts a poll flag, then reads commands and broadcasts to all ranks
- Drains all queued commands in order on each poll
- Moves processed command files to `processed/` for debugging
- Supports step-based checks (`check_every`) and optional time-based checks (`check_every_seconds`)
- Command validation + versioning schema
- CLI helper (`runtimelr`) to enqueue commands
- `queue_dir=None` creates a process-scoped temporary queue directory
- Control-plane polling is forced to eager mode to avoid `torch.compile`/Dynamo tracing warnings

## Install

```bash
pip install runtimelr
```

For local development:

```bash
pip install -e .
```

## Command schema

```json
{"version": 1, "kind": "set_lr_scale", "value": 0.5}
```

or

```json
{"version": 1, "kind": "mult_lr_scale", "value": 0.5}
```

## Usage

```python
from runtimelr import ControlledLambdaLR

sched = ControlledLambdaLR(
    optimizer,
    lr_lambda=lambda step: 1.0,
    queue_dir=None,
    check_every=500,
    check_every_seconds=2.0,
)

for step in range(100000):
    # train step
    sched.step()
```

Send commands at runtime:

```bash
runtimelr --queue_dir /tmp/lr_cmds set_lr_scale 1e-3
runtimelr --queue_dir /tmp/lr_cmds mult_lr_scale 0.5
```
