Add benchmark validation suite, CLI command, and reporting artifacts

[jam-sudo]

Motivation

• Provide a reproducible validation/benchmark layer to track simulator behavior against reference PK curves and detect regressions.
• Enable automated, deterministic benchmark runs and human-readable reporting to speed validation during development.

Description

• Added a benchmark suite under benchmarks/ containing configs (benchmarks/configs/*.yaml), synthetic reference datasets (benchmarks/datasets/*.csv), and acceptance thresholds (benchmarks/expected/acceptance.json).
• Implemented physio_sim.validation package with benchmarks.py (suite runner that loads configs, runs simulate(), interpolates sim->obs, computes AUC, Cmax, Tmax, RMSE, evaluates pass/fail versus thresholds, and writes artifacts) and report.py (builds report.md).
• Exposed a non-breaking CLI subcommand benchmark in physio_sim.cli so the suite runs with python -m physio_sim.cli benchmark --suite benchmarks --out outputs/benchmarks and exits with code 1 when any case fails acceptance.
• Added deterministic seed support for the suite by using existing configure_random_seed in configs, and wrote smoke/determinism tests in tests/test_benchmark_smoke.py to assert outputs and reproducibility.
• Documentation: added docs/validation.md describing benchmark philosophy, dataset format, and instructions; README updated with quick example.
• Files added/modified (high level): benchmarks/ (configs, datasets, expected JSON), physio_sim/validation/__init__.py, physio_sim/validation/benchmarks.py, physio_sim/validation/report.py, physio_sim/cli.py (benchmark command), docs/validation.md, tests/test_benchmark_smoke.py, and pyproject.toml (include new package).

Testing

• Ran formatting and lint: python -m ruff format --check . and python -m ruff check . (passed).
• Static typing: python -m mypy physio_sim (passed).
• Unit tests: python -m pytest -q (all tests passed; 17 passed).
• Executed benchmark runner end-to-end: python -m physio_sim.cli benchmark --suite benchmarks --out outputs/benchmarks, which produced outputs/benchmarks/<drug>/overlay.png, metrics.json, summary.json, and report.md and completed successfully (benchmarks passed in this run).
• Note: bundled datasets (caffeine, warfarin, metoprolol) are synthetic example datasets and are explicitly documented in docs/validation.md.

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3916f2f55a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Resolve benchmark file paths from suite directory

run_benchmark_suite anchors relative subject_file/dataset paths to Path.cwd() rather than the provided suite_dir, so running benchmark --suite /absolute/path/to/benchmarks from a different working directory looks for files under that unrelated cwd (for example /tmp/examples/subject_default.yaml) and crashes. This makes valid --suite invocations fail unless callers also cd to the repo root, which is a brittle regression for CLI and programmatic use.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Fail when benchmark suite executes zero cases

overall_pass is derived from all(item["pass"] for item in results) without verifying that any configs were run, and in Python all([]) is True. If configs/*.yaml is empty or not discovered, the command emits a passing summary and exits 0 even though no benchmarks executed, which can silently mask broken validation in CI.

Useful? React with 👍 / 👎.