[API] Run, get, list experiments

[podkidyshev]

Summary

• Add the public cloudai.api entry points to run scenarios from configuration paths and list or load their unified experiment output.
• Support run, dry-run, and Slurm single-sbatch execution while keeping signal handling, output overrides, and exit-code translation in the CLI.
• Constrain experiment lookup to result directories under the configured system output path. Listing returns experiment IDs and absolute result-directory paths without parsing every experiment.json.
• Publish the initial Experiment through on_start after experiment.json is created, allowing wrappers to obtain the real experiment ID while synchronous execution continues.
• Document the Python API and preserve the deprecated handler interfaces.

Test Plan

• Automated CI.

Additional Notes

Based on #1049. run_experiment remains synchronous; callers decide whether to execute it in a background process.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

⚙️ Run configuration

Configuration used: Repository: NVIDIA/cloudai/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 164ab251-6908-432c-826b-2d7a45f978ac

📥 Commits

Reviewing files that changed from the base of the PR and between bbb9ad1 and 2ad2a21.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: NVIDIA/cloudai/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 087165b6-ebd9-4e08-ba6b-4c06282e27c5

📥 Commits

Reviewing files that changed from the base of the PR and between 7b08159 and bbb9ad1.

📒 Files selected for processing (12)

• doc/api.rst
• doc/index.rst
• src/cloudai/_core/runner.py
• src/cloudai/api.py
• src/cloudai/cli/cli.py
• src/cloudai/cli/handlers.py
• src/cloudai/handlers.py
• src/cloudai/parser.py
• tests/test_acceptance.py
• tests/test_api.py
• tests/test_cloudaigym.py
• tests/test_handlers.py

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds reusable experiment setup and execution, public functions to run and retrieve experiments, and CLI signal and compatibility handling. Parser errors can propagate to API callers, and runner construction accepts an explicit runner class.

Changes

Experiment lifecycle

Layer / File(s)	Summary
Parser and runner construction contracts src/cloudai/parser.py, src/cloudai/_core/runner.py, tests/test_handlers.py, tests/test_cloudaigym.py	Parser errors can propagate instead of causing a process exit. Runner accepts a runner_class override and warns when callers use the legacy constructor signature. Tests use explicit runner classes and check the warning.
Reusable experiment lifecycle src/cloudai/handlers.py, tests/test_handlers.py	Handlers load and validate experiment inputs, configure a runner, check or install prerequisites, execute jobs, and finalize output. Job handlers now determine mode from the runner instead of CLI arguments.
CLI execution and compatibility forwarding src/cloudai/cli/cli.py, src/cloudai/cli/handlers.py, tests/test_acceptance.py	The CLI registers signal handlers and owns run handling. Compatibility functions forward to the CLI or preserve former job-handler arguments.
Public experiment API src/cloudai/api.py, tests/test_api.py, doc/api.rst, doc/index.rst	The API runs experiments and lists or loads saved results. Tests cover execution, callbacks, and invalid lookups. The API documentation is added to the documentation navigation.

Priority: ⬇️ Low

Estimated code review effort: 4 (Complex) | ~40 minutes

Change: Feature

Merge Risk: ⚪ Minimal · up to bbb9a

The experiment API preserves failure-status finalization and rejects unsupported scheduler configurations. No concrete issue remains that should block merging after normal checks.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding API support to run, retrieve, and list experiments.
Description check	✅ Passed	The description directly matches the changeset. It covers the public API entry points, execution modes, experiment lookup, callbacks, documentation, and compatibility interfaces.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

_{Comment @coderabbitai help to get the list of available commands.}

[podkidyshev]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.