one-run1 0.1.2

ml run wrapper for reprodusible experiments and documentation

one-run

CLI wrapper for job management on local machines and SLURM

install

pip install -e .

published package install:

pip install one-run1

commands

• one-run --version: print installed package version
• one-run --automation ...: prefer json outputs by default for automation
• one-run run <manifest.yaml>: execute locally (blocking)
• one-run run --watch <manifest.yaml>: execute locally in background
• one-run run <manifest.yaml> --json: machine-readable run result
• one-run submit <manifest.yaml>: submit to SLURM
• one-run submit <manifest.yaml> --json: machine-readable submit result
• one-run status <run_id>: inspect run status
• one-run status -l <run_id>: extended run status (metadata/runtime/paths)
• one-run status <run_id> --json: machine-readable status payload for scripts/CI
• one-run status <run_id> --wait --timeout 30m: wait for terminal state (non-zero on timeout)
• one-run cancel <run_id>: cancel a running local watch or SLURM run.
• one-run cancel --force <run_id>: force-kill local run (SIGKILL) / SLURM KILL signal.
• one-run cancel <run_id> --json: machine-readable cancel result.
• one-run ls: list runs.
• one-run ls --long: detailed run list.
• one-run ls --state success: filter by state.
• one-run ls --tag gpu: filter runs by tag (repeatable).
• one-run ls --group-by-tag: group listed runs by tag.
• one-run ls --json: machine-readable run list payload.
• one-run ps: show active runs (pending/running) with process/job identity.
• one-run ps --tag train: filter active runs by tag.
• one-run ps --json: machine-readable active runs payload.
• one-run ps -w --interval 2: live refreshing process table.
• one-run validate <manifest.yaml>: validate manifest + placeholders.
• one-run validate <manifest.yaml> --json: machine-readable validation result.
• one-run tail <run_id> [-n 30] [--stderr] [-f] [--since 10m]: tail run logs.
• one-run gc [--state failed] [--older-than 7d] [--dry-run]: cleanup run directories.
• one-run gc ... --json: machine-readable cleanup result.

automation defaults:

• set ONE_RUN_AUTOMATION=1 to make json the default output mode for commands that support --json
• or pass --automation before the command, e.g. one-run --automation status <run_id>
• explicit --json still works the same

docker local execution:

• fixture example: tests/fixtures/manifest.docker.yaml
• set environment.kind: docker
• set environment.image
• optional environment.workdir and environment.mounts
• optional environment.env and environment.env_file
• optional environment.pull_policy: always | if_missing | never
• optional environment.labels for container traceability

slurm retry policy (optional):

• backend.slurm.retry_max_attempts: retry count after first failure (e.g. 1)
• backend.slurm.retry_backoff_sec: delay before retry submit (e.g. 30)
• backend.slurm.retry_on_states: subset of failed | timeout | cancelled
• retries are triggered during status refresh (one-run status ...)

ls color from manifest:

• experiment.color: black | red | green | yellow | blue | magenta | cyan | white
• ls colors the experiment column for runs that define experiment.color

run directory

runs/<run_id>/
  config.snapshot.yaml
  metadata.json
  status.json
  runtime.json
  summary.json
  summary_min.json
  events.jsonl
  local.pid
  local.exit_code
  logs/stdout.log
  logs/stderr.log
  artifacts/
  metrics/