Make Puzzletron examples portable

[j-rausch]

What does this PR do?

Type of change: Bug fix

Puzzletron v2 examples contain site-specific paths and defaults that do not work for other contributors. This change makes the checked-in examples portable:

• Use runnable public model repository IDs while retaining immutable revisions.
• Use repository-relative checkout and virtual-environment defaults in the generic examples.
• Replace required site values with visible placeholders.
• Preserve the Qwen Slurm repository, virtualenv, container, mount, setup-script, vLLM, and AutoModel contract with explicit replacement values.
• Leave generic optional infrastructure and CPU-partition values unset.
• Replace the personalized defaults file with a portable example.
• Fix the Slurm, bare-metal, and execution examples so they are valid YAML.
• Clarify infrastructure prompts with generic guidance.
• Add regression coverage for the portable configuration contract.

Usage

python examples/puzzletron/puzzletron_setup_v2.py \
  --defaults examples/puzzletron/configs/setup/defaults.example.yaml

Copy the example and add the scheduler, container, data, and mount values required by your environment before using it for a campaign.

Testing

Covered by Puzzletron configuration and lightweight orchestration CI tests.

Summary by CodeRabbit

• Documentation

  • Added setup guidance for copying and customizing default configuration values.
  • Clarified execution configuration descriptions and site-specific replacement requirements.
  • Documented repository, virtual environment, container, mount, and pre-run command settings.

• Improvements

  • Made Slurm and bare-metal examples portable with placeholders and relative paths.
  • Updated model examples to reference public Hugging Face identities and revisions.
  • Added a standard setup defaults example.

• Tests

  • Added coverage verifying example configurations are portable, valid, and loadable.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 24bd66f8-2822-42cf-9b76-08b04de166a6

📥 Commits

Reviewing files that changed from the base of the PR and between 99326c5 and 66d59ff.

📒 Files selected for processing (4)

• examples/puzzletron/README.md
• examples/puzzletron/configs/families/qwen3_5/qwen3p5_9b/model.yaml
• puzzletron_setup/wizard.py
• tests/unit/torch/puzzletron/test_portable_configs.py

🚧 Files skipped from review as they are similar to previous changes (4)

• examples/puzzletron/README.md
• puzzletron_setup/wizard.py
• examples/puzzletron/configs/families/qwen3_5/qwen3p5_9b/model.yaml
• tests/unit/torch/puzzletron/test_portable_configs.py

---

📝 Walkthrough

Walkthrough

Puzzletron configuration examples now use portable paths, placeholders, optional defaults, and public Hugging Face model identities. Setup documentation and wizard prompts describe the corresponding infrastructure settings. Regression tests validate configuration portability and loadability.

Changes

Puzzletron portability

Layer / File(s)	Summary
Setup defaults and wizard guidance examples/puzzletron/README.md, examples/puzzletron/configs/setup/defaults.example.yaml, puzzletron_setup/wizard.py	Adds portable setup defaults and documents repository paths, virtual environments, containers, mounts, and prerun commands.
Portable execution examples examples/puzzletron/configs/orchestration/...	Replaces site-specific runner values with placeholders, relative paths, and optional defaults for Slurm and bare-metal execution.
Model identities and regression coverage examples/puzzletron/configs/families/..., tests/unit/torch/puzzletron/test_portable_configs.py	Documents public Hugging Face model identities and adds tests for portable, loadable Puzzletron configurations.

Estimated code review effort: 3 (Moderate) | ~20 minutes

🚥 Pre-merge checks | ✅ 5 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the PR's main change: making the checked-in Puzzletron examples portable across environments.
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.
Security Anti-Patterns	✅ Passed	Full PR diff adds no prohibited torch/numpy/Transformers loading, eval/exec, or # nosec patterns, and changes no dependency files.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch jrausch/puzzletron-v2-config-portability

---

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

[coderabbitai]

Warning

CodeRabbit couldn't request changes on this pull request because it doesn't have sufficient GitHub permissions.

Please grant CodeRabbit Pull requests: Read and write permission and re-run the review.

👉 Steps to fix this

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@examples/puzzletron/configs/families/qwen3_5/qwen3p5_9b/model.yaml`:
- Around line 7-8: Pin the Qwen 3.5 9B configuration by adding its validated
immutable Hugging Face commit to model_info.hf_revision in
examples/puzzletron/configs/families/qwen3_5/qwen3p5_9b/model.yaml. Update the
portable-config test in tests/unit/torch/puzzletron/test_portable_configs.py to
require every model example to define a non-empty immutable revision.

In `@examples/puzzletron/README.md`:
- Line 25: Update the sentence in the README so the comma following “evaluation
results” is replaced with a semicolon or period, preserving the surrounding
wording.

In `@puzzletron_setup/wizard.py`:
- Around line 1214-1220: Update the repository path prompt in the wizard flow to
use the repository-relative default "." instead of deriving the controller’s
absolute working directory via Path.cwd(). Keep the existing prompt text,
description, and support for user-provided shared absolute paths unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 6737a750-6c4d-4b56-9764-f28f9e69536f

📥 Commits

Reviewing files that changed from the base of the PR and between 05e1c5f and 99326c5.

📒 Files selected for processing (12)

• examples/puzzletron/README.md
• examples/puzzletron/configs/families/nemotron3/nano_30b_a3b_bf16/model.yaml
• examples/puzzletron/configs/families/qwen3_5/qwen3p5_9b/model.yaml
• examples/puzzletron/configs/families/qwen3_5/qwen3p6_35b_a3b/model.yaml
• examples/puzzletron/configs/orchestration/execution.example.yaml
• examples/puzzletron/configs/orchestration/qwen_moe/runner.slurm.yaml
• examples/puzzletron/configs/orchestration/runner.baremetal.example.yaml
• examples/puzzletron/configs/orchestration/runner.slurm.example.yaml
• examples/puzzletron/configs/setup/defaults.example.yaml
• nv-internal/sepehr_defaults.yaml
• puzzletron_setup/wizard.py
• tests/unit/torch/puzzletron/test_portable_configs.py

💤 Files with no reviewable changes (1)

• nv-internal/sepehr_defaults.yaml