Reusable Components

rle.reusable is the part of RL Engine meant to survive outside RL Engine. When starting a new paper, benchmark, or project repository, this package should be copy-pasteable infrastructure: small, modular utilities that make the new repo feel civilized before any project-specific code exists.

The reusable layer is intentionally boring. It does not encode RL Engine environment assumptions, algorithm choices, or experiment layouts. It provides the common support code that most research repos otherwise reimplement in their first week.

Components

The package root re-exports public functions. Data models are imported from their dedicated modules:

from rle.reusable import (
    ProgressBar,
    RecordVideo,
    configure_logging,
    load_timings,
    log,
    plot_metric_grid,
    run_experiment_suite,
    save_timings,
    timed,
)
from rle.reusable.experiments.models import AlgorithmSpec, ExperimentSuiteConfig
from rle.reusable.visualisation.models import MetricPlotSpec, PlotStyle

Porting To A New Repo

For a fresh project, copy src/rle/reusable into the new package and rename the top-level import path if needed. The base install stays small; workflow-specific packages are optional extras:

Use uv sync --all-groups --all-extras when developing this repository. A consumer can select extras independently, for example uv sync --extra visualisation --extra notebooks.

timings uses only the standard library, with optional runtime detection of torch if it is already installed. It does not require torch.

For experiment workflows, copy the stub notebook too:

notebooks/reusable/experiments/stub_env_mo.py

Use one notebook per environment, keep environment and trainer imports in the notebook or project package, and let rle.reusable.experiments own the boring parts: selected algorithm dispatch, seeded run records, resumption, restart on complete run sets, optional checkpoint manifests, progress bars, and timing sidecars.

Design Rules

• Keep reusable code independent of RL Engine environments, notebooks, and algorithms.
• Prefer explicit, low-magic APIs that are easy to paste into a small repo.
• Store outputs in ordinary files such as .log and .json, not framework state.
• Make notebook and batch-job workflows first-class, since both appear in research projects.
• Document copy-paste assumptions next to each component so future projects can decide what to keep.
• Keep trainer checkpoint payloads, paper-specific figure composition, and environment construction in the project that owns them; surface those outputs as ordinary artifact paths or checkpoint manifest metadata in reusable run records.

Adapting To Your Project

Start by deciding whether the new project wants to vendor the reusable package as-is or rename it into the project's own namespace. For a quick paper repo, the usual path is to copy src/rle/reusable into something like src/<project>/reusable and then replace imports from rle.reusable with <project>.reusable. Keep the public API small and boring in the new namespace; environment builders, trainers, plotting recipes, and paper-specific constants should live beside the project code that owns them.

Copy the generic notebooks only when they match the workflow you expect to use:

notebooks/reusable/experiments/stub_env_mo.py
notebooks/reusable/generic/lock_status_mo.py
notebooks/reusable/generic/timings_mo.py
notebooks/reusable/generic/visualisation_mo.py
notebooks/reusable/generic/legend_mo.py

The experiment notebook is the one most projects should duplicate first. Rename it for the environment, replace the stub environment block, replace stub_algorithm_specs() with real AlgorithmSpec registrations, and leave the runner call alone unless the project needs a very different export layout. The auto environment discovery pattern can sit above that when the project needs to run, test, document, or summarize many environments. The generic timings, visualisation, and legend notebooks work from timing sidecars plus csh-compatible visualisation archives:

exports/<group>/<algorithm_slug>/timings.json
exports/<group>/runs/<algorithm_slug>_<run_idx>.np

The functions most often adjusted in a new project are not the runner internals; they are the small configuration surfaces around them:

• ExperimentSuiteConfig: choose env_name, export_dir, shared run flags, checkpoint toggles, per-algorithm config blocks, and caller-supplied provenance.
• AlgorithmSpec: add one per algorithm, with an enabled_flag, config, optional prepare, optional fingerprinted required_artifacts, and a run hook.
• MetricPlotSpec: define the project metrics that appear in figures.
• PlotStyle: choose bands, smoothing, truncation, seed traces, palette, and event markers.
• DEFAULT_PALETTE and ALGORITHM_LEGEND_ORDER: extend them when the project introduces new canonical Base-Variant algorithm labels that should have stable colors and ordering.

Keep the reusable layer honest by resisting project-specific imports inside it. If a future project needs a world model loader, a contract synthesizer, a trainer checkpoint format, or a custom matplotlib composition, put that code in the project package and connect it through the reusable extension points: AlgorithmSpec.prepare, ExperimentRunResult.artifacts and artifact_paths, ExperimentCheckpointContext, and the metric/legend visualisation helpers.