runlog

Small Python library for tracking experimental runs. Each run gets its own output directory and a small metadata sidecar (config, timestamp, git state) so results stay reproducible.

Layout

<log_dir>/<run_name>/
    metadata/
        run.yaml      # run_name, timestamp, git_commit, git_dirty
        config.yaml   # the cfg passed to start_run
    output/           # write your run artifacts here

run_name defaults to a legible timestamp (YYYY-MM-DD_HH-MM-SS).

API

from pathlib import Path
from runlog import start_run, load_run, list_runs, load_metadata, RunBrowser

# Start a run — returns the output directory to write artifacts into.
# cfg can be a jsonargparse loaded config for even better reproducibility
out_dir = start_run(Path("logs"), cfg={"lr": 1e-3, "batch": 32})

# Load a previous run's config + output directory.
cfg, out_dir = load_run(Path("logs"), "2026-05-23_18-32-31")

# List runs (reverse alphabetical → most recent timestamps first).
names = list_runs(Path("logs"))

# Load just the metadata record.
meta = load_metadata(Path("logs"), names[0])  # -> RunMetadata

RunBrowser

Reacton component for Jupyter. Renders a dropdown of runs and shows the selected run's index, metadata, and config.

from runlog import RunBrowser
RunBrowser(log_dir=Path("logs"))