Skip to content

Reproducible Project Hygiene

The reusable package includes small operational controls that prevent common research-repo failures without encoding an environment or learner.

Source And Runtime Provenance

ExperimentSuiteConfig captures source and runtime provenance by default. Each run request records the Git revision, dirty state and worktree digest, Python implementation and platform, and requested package versions:

from rle.reusable.experiments.models import ExperimentSuiteConfig

suite = ExperimentSuiteConfig(
    env_name="example",
    export_dir="exports/example",
    provenance={"dataset_revision": "2026-08-01"},
    provenance_packages=("rle", "jax"),
    provenance_mode="capture",
)

Use provenance_mode="require_clean" for publication runs. Use "supplied" only when an external system already provides the complete source identity, such as a signed source bundle or container digest. Captured provenance enters the request hash, so a different commit, dirty state, runtime, or recorded package version cannot silently resume an old run.

find_project_root, ensure_project_import_paths, and set_cwd_to_project_root centralize the bootstrap previously duplicated by notebooks. notebooks/project_root.py is the thin notebook-facing facade.

Bounded Local Runs

Use the local wrapper for smoke tests that might initialize JAX or large thread pools:

scripts/run_safe_local.sh \
  --memory-max-gib 12 \
  --min-available-gib 16 \
  -- uv run python notebooks/example_mo.py

It checks available RAM, applies a virtual-memory limit, defaults JAX to CPU without preallocation, and bounds common numerical thread pools. The defaults can also be set with RLE_LOCAL_MEMORY_MAX_GIB and RLE_LOCAL_MIN_AVAILABLE_GIB. Learner-scale training still belongs on a resource-managed cluster.

Installation Surfaces

The base package excludes notebook, plotting, video, and learner-framework stacks. Install only the workflow needed by a consumer:

uv sync --extra notebooks --extra visualisation
uv sync --extra video
uv sync --extra jax
uv sync --extra torch
uv sync --extra rllib

Repository development and CI use uv sync --all-groups --all-extras. Public experiment and plotting data classes live in dedicated models.py modules, and must be imported from those modules. Schema versions live separately from orchestration code so persistence changes are reviewable.

CI sets headless SDL and CPU-only accelerator variables, enforces a pytest timeout, builds documentation strictly, and runs a non-mutating pinned Ruff pre-commit hook over maintained reusable and test code.

Adapting To Your Project

Keep the automatic provenance default, then add project-owned dataset, image, or source-bundle identifiers through provenance. Copy the root helper instead of duplicating notebook path searches. Tune the local memory limits to the smallest smoke workload the project supports, and retain heavyweight packages as extras so importing a generic utility does not require an accelerator stack. When changing an on-disk schema, increment its explicit version and add strict load and rejection coverage for the current record shape.