lite-runner

LiteRunner

[![Tests][tests-badge]][tests-link] [![codecov][codecov-badge]][codecov-link] [![PyPI version][pypi-version-badge]][pypi-link] [![PyPI platforms][pypi-platforms-badge]][pypi-link] [![Total downloads][pepy-badge]][pepy-link]
[![Made Using tsvikas/python-template][template-badge]][template-link] [![GitHub Discussion][github-discussions-badge]][github-discussions-link] [![PRs Welcome][prs-welcome-badge]][prs-welcome-link]

Overview

Runner for generative models with local and W&B tracking.

Write a small Python script per model that declares params, outputs, and metrics. lite-runner handles the rest: CLI parsing, interactive prompts for missing values, subprocess execution, stdout/stderr capture, metric extraction, file uploads to W&B, and code snapshots for reproducibility.

Quick start

Create a run.py for your model:

#!/usr/bin/env -S uv run
# /// script
# dependencies = ["lite-runner"]
# ///
from lite_runner import Runner, Param, Metric

runner = Runner(
    command="python generate.py",
    params=[
        Param("prompt", help="Text prompt"),
        Param("seed", type="int", default=42),
        Param("output-path", value="$output/video.mp4", type="path-video"),
    ],
    metrics=[
        Metric("loss", pattern=r"loss=([\d.]+)"),
    ],
)

if __name__ == "__main__":
    runner.run()

Then run it (requires uv):

chmod +x run.py
./run.py --prompt "a cat walking"           # interactive TUI fills missing params
./run.py --prompt "a cat" --no-interactive  # non-interactive, fail if missing
./run.py --prompt "a cat" --dry-run         # print command, don't run
./run.py --seed=-                           # unset a param (omit from command)
./run.py --image - - -                      # unset a multi-value param

What it does

Each runner.run() call:

1. Parses CLI args (all params are optional in argparse; missing ones trigger TUI prompts)
2. Creates an output directory at ~/lite_runs/<project>/<timestamp>_<run_name>/
3. Inits a W&B run and logs all params, git info, and host metadata
4. Saves a code snapshot (git archive + dirty diff) as a W&B artifact
5. Builds and runs the subprocess, streaming stdout/stderr to terminal and log files
6. Extracts metrics from stdout via regex
7. Uploads output files (videos, images, artifacts) to W&B
8. Logs duration, exit code, and status to W&B summary

Param

Param("name")                               # basic string param
Param("seed", type="int", default=42)       # typed with default
Param("mode", choices=["fast", "quality"])  # select from choices
Param("verbose", type="bool")               # --verbose flag (store_true, always defaults to False)
Param("image", type="path-image")           # file input, uploaded to W&B before run
Param(
    "output-path",
    value="$output/video.mp4",              # fixed value, $output interpolated
    type="path-video",
)                                           # after the run, uploaded to W&B as a video
Param(
    "input-image",
    type=["path-image", "float", "float"],  # multi-value flag
    labels=["img", "start", "strength"],
)                                           # each part prompted separately in TUI

Type — controls parsing, casting, and file upload intent. All param values are logged to run.config. The path-* variants additionally upload the file at that path to W&B:

Type	Parsed as	File upload
"str" (default)	str	—
"int"	int	—
"float"	float	—
"bool"	flag	—
"path"	str	—
"path-image"	str	as image
"path-video"	str	as video
"path-artifact"	str	as artifact
"path-text"	str	as text

"bool" params are special: they generate a --flag (no value), always default to False (any other default= is ignored), and cannot appear in multi-value type lists.

Other fields: