docs: document Dynamo Planner installation prerequisites

[jasonqinzhou]

A basic pip install aisimulate ai-dynamo installation can run Dynamo prediction but lacks dependencies required to load dynamo.planner, including scikit-learn.

This PR targets main and addresses NVBug 6785216. It documents installing the full Planner requirements from the same Dynamo revision as the installed wheels, distinguishes exact RC artifacts from package versions, and identifies the matching Planner image as a prebuilt alternative.

The four-file change includes a CPU-only CLI example with Planner load scaling, 12 synthetic requests, local model metadata, fixed timing, and fixed KV capacity. It documents the working directory and expected output files. No model weights, GPU, or Kubernetes cluster are needed.

Validation on head 0fafbbb2 against main (612fbcf4):

• The core YAML passes the current main AISimulate schema; its Planner section passes the Dynamo RC9 schema at ffd7c1a90eb403c0d43911690c5c9b8457acd826 using current AISimulate schema types.
• Local Markdown destinations, all documented shell blocks, model JSON, SPDX headers, packaged legal files, and whitespace checks pass. The matching Dynamo requirements file includes scikit-learn.
• Stable patch-ID comparison confirms the original reviewed four-file documentation patch is unchanged after reconciling release ancestry with main. No dependency or runtime changes are included.

Exact RC-wheel runtime verification remains pending with QA: confirm a clean installation, 12 completed requests, and both output files using the exact release artifacts. This PR does not claim that verification or close the bug. Current-head hosted CI and review are recorded in the checks and review activity.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[jasonqinzhou]

Self-review of 7ebe37aeeb826c61f60c16c56c536c8ab8f8afa2 against release/0.12.0 (1f728534910187ecb2f021ef5e4bd4949bd555d0) found no actionable issue in the four-file diff. No corrective review threads were needed.

The core YAML validates against this release's AIS schema and the Planner section against the Dynamo RC9 schema at ffd7c1a90eb403c0d43911690c5c9b8457acd826. The model metadata matches the existing repository fixture. Shell syntax, local links, the requirements URL, source compliance, packaged legal files, ownership coverage, and whitespace checks pass.

Exact RC-wheel runtime verification is still pending. I sent Qun Chi the verification request and linked the PR in NVBug 6785216. Please verify the documented fresh-environment setup, 12 completed requests, and both output artifacts before closing the bug.

This remains draft and is not yet ready for human review: NVIDIA runner admission requires the normal PR-vetter validation, and the full CI run is not present on this head. Maintainer approval and QA verification remain outstanding. No merge is requested.

[jasonqinzhou]

Retargeting to main as requested. The release branch has separate backport history, so a base-only change currently expands the comparison from the intended four documentation/example files to 116 files. I will reconcile this PR with current main, preserving main and applying only the original Planner documentation change, then validate the resulting four-file diff and current-head CI before merging.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 533323c7-6751-4d8a-a8c6-8b3971c9a30a

📥 Commits

Reviewing files that changed from the base of the PR and between 612fbcf and 0fafbbb.

📒 Files selected for processing (4)

• README.md
• docs/cli/examples/dynamo-planner/README.md
• docs/cli/examples/dynamo-planner/model/config.json
• docs/cli/examples/dynamo-planner/prediction.yaml

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• ai-dynamo/dynamo (manual)
• ai-dynamo/aiconfigurator (manual)

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

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (3)

Check commands, defaults, supported runtimes, public names, and claims against executable behavior.

⚙️ CodeRabbit configuration file

Files:

• docs/cli/examples/dynamo-planner/model/config.json
• docs/cli/examples/dynamo-planner/README.md
• docs/cli/examples/dynamo-planner/prediction.yaml
• README.md

Read REVIEW.md before commenting.

⚙️ CodeRabbit configuration file

Files:

• docs/cli/examples/dynamo-planner/model/config.json
• docs/cli/examples/dynamo-planner/README.md
• docs/cli/examples/dynamo-planner/prediction.yaml
• README.md

Before making any change under: `python/aisimulate/src/aiconfigurator/generator/**` MUST read: `python/aisimulate/.claude/rules/generator-development.md` Before making any change under `python/aisimulate/collector/**` MUST read: `python/ais...

📄 CodeRabbit inference engine (AGENTS.md)

Files:

• docs/cli/examples/dynamo-planner/model/config.json
• docs/cli/examples/dynamo-planner/README.md
• docs/cli/examples/dynamo-planner/prediction.yaml
• README.md

🔀 Multi-repo context ai-dynamo/dynamo, ai-dynamo/aiconfigurator

Linked repositories findings

ai-dynamo/dynamo

• container/deps/requirements.planner.txt contains the Planner runtime prerequisites, including scikit-learn, pmdarima, prophet, and plotly. The Planner image installs this file plus the staged aisimulate*.whl in container/templates/planner.Dockerfile; this supports the documentation’s same-revision dependency/image requirement. [::ai-dynamo/dynamo::]
• Existing DynoSim documentation uses aisimulate predict --stack dynamo, states that it runs locally without a cluster, and writes prediction.json output (docs/fern/pages/kubernetes/operations/simulation-with-dynosim/dynosim-planner-replay.mdx:8-15, 91-101). [::ai-dynamo/dynamo::]
• The documented Planner fields used by the new example—load scaling, five-second adjustment intervals, sensitivity, minimum observations, GPU limits, and minimum workers—match Dynamo’s current prediction examples and Planner configuration reference. [::ai-dynamo/dynamo::]

ai-dynamo/aiconfigurator

• The migration guide explicitly says configurations using Dynamo Router or Planner adapters require a Dynamo runner factory (docs/aisimulate_migration.md:64-67), consistent with the PR’s explanation of Dynamo-owned adapters. [::ai-dynamo/aiconfigurator::]
• The AIC 0.12 compatibility wheel is a separate migration artifact: it preserves the aiconfigurator command and explicitly does not install an aisimulate top-level command (docs/aisimulate_migration.md:21-31). The new aisimulate predict instructions therefore need to target the documented AISimulate RC artifacts, not the AIC compatibility wheel. [::ai-dynamo/aiconfigurator::]

---

📝 Summary

Risk: Low for runtime code; medium for documentation accuracy.

Human attention:

1. Confirm exact RC wheel and Planner dependency compatibility.
2. Verify the documented CLI example produces 12 completed requests and both output files.
3. Confirm the Planner image, model metadata, and configuration match the target Dynamo revision.

Changes

• Documents Dynamo and AISimulate version compatibility.
• Documents matching requirements.planner.txt, dynamo-planner images, and RC artifact installation.
• Adds a CPU-only public CLI example with synthetic traffic, Planner load scaling, fixed timing, and fixed KV capacity.
• Adds model metadata and prediction configuration for a two-replica H200 vLLM engine.
• Documents the working directory, expected output files, overwrite behavior, and missing-dependency remediation.

No runtime, dependency, or exported API changes are included.

Evidence

• Schema, shell-block, link, model-metadata, licensing, packaging, ownership, and whitespace checks reportedly passed.
• Self-review reported no actionable issues.
• The supplied material does not include test logs or current review findings, so review severity counts are unavailable.

Missing evidence and merge readiness

• QA must verify installation with exact RC artifacts.
• QA must confirm 12 completed requests and both documented output files.
• Full CI, normal PR-vetter validation, and maintainer approval remain pending.
• Technical quality appears documented by the reported checks, but merge readiness is not established.

Walkthrough

The documentation updates describe compatible Dynamo installations, Planner dependency requirements, and optional adapter validation. A new example verifies Planner predictions with synthetic traffic, a Llama model configuration, and load-based scaling settings.

Changes

Dynamo Planner setup

Layer / File(s)	Summary
Installation and dependency guidance README.md	The installation guidance specifies compatible AISimulate and Dynamo releases, Dynamo-owned adapters, matching Planner requirements or images, an RC installation example, and dependency validation limits.
Planner prediction verification docs/cli/examples/dynamo-planner/README.md, docs/cli/examples/dynamo-planner/model/config.json, docs/cli/examples/dynamo-planner/prediction.yaml	The example documents environment setup, matching wheels, Planner verification, expected outputs, and troubleshooting. It adds a Llama model configuration and a synthetic prediction configuration with Planner scaling and a two-GPU budget.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 0fafb

The change adds documentation and a verification example without an established functional or operational regression; pending QA runtime verification is routine follow-up.

🚥 Pre-merge checks | ✅ 7 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Cross-Layer Contract	⚠️ Warning	The PR adds a new Planner-enabled public CLI path, but no test consumes the added configuration or example. The changed-file inventory contains only README and example files. Existing tests cover gene…	Add an automated integration test or CI job that uses the documented working directory and exact matching AISimulate and Dynamo artifacts. Install the pinned Planner requirements or matching image. Load the added YAML and model metadata thr…

✅ Passed checks (7 passed)

Check name	Status	Explanation
Modeling And Data Evidence	✅ Passed	PASS: The PR adds documentation and a synthetic Planner input fixture only. The authoritative diff contains four documentation/example files and no golden, benchmark, performance-data, or predicted-re…
Compatibility Boundaries	✅ Passed	PASS: The authoritative range changes only README documentation and one Planner example with JSON/YAML data. No Python or Rust source, public API, schema implementation, binding, package manifest, or …
Review Evidence	✅ Passed	The PR description identifies the relevant installation command and validation results. It records local schema, Markdown, shell-block, metadata, licensing, packaging, and whitespace checks; it states…
Title check	✅ Passed	The title precisely states that the change documents Dynamo Planner installation prerequisites. It avoids vague wording.
Description check	✅ Passed	The description clearly states the problem, behavior change, scope, validation status, pending QA work, and related bug. It does not use the template headings and omits some structured evidence fields…
Linked Issues check	✅ Passed	The description links NVBug 6785216 and correctly states that the PR does not claim to close the bug.
Out of Scope Changes check	✅ Passed	The changes match the stated documentation objective. The summary reports no dependency, runtime, model, GPU, or deployment changes.

Full details: Cross-Layer Contract

Explanation

The PR adds a new Planner-enabled public CLI path, but no test consumes the added configuration or example. The changed-file inventory contains only README and example files. Existing tests cover generic adapter and runtime-hook contracts, not this exact planner schema, RC9 adapter compatibility, documented working directory, 12-request execution, or the two output files. The PR description also states that exact RC-wheel runtime verification remains pending. Therefore the new path is untested, and the compatibility and output claims lack repository-backed evidence.

Resolution

Add an automated integration test or CI job that uses the documented working directory and exact matching AISimulate and Dynamo artifacts. Install the pinned Planner requirements or matching image. Load the added YAML and model metadata through the public CLI, compile the dynamo.planner adapter, verify adapter-to-replay serialization and Rust runtime-hook consumption, and assert 12 completed requests plus prediction.json and requests.jsonl. Pin or record the tested wheel and Dynamo revisions so schema and compatibility drift fails the check.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

---

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

[jasonqinzhou]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Already reviewed the last commit. Use @coderabbitai full review to rerun a review of the entire changeset.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[jasonqinzhou]

Retargeted to main and reconciled at 0fafbbb2b363c6b193718d9caa78156d71a105d2, based on 612fbcf45053f2c5bdef7a37d8fbecc1c732640a. The stable patch ID proves the original approved four-file documentation change is unchanged; release backports add no diff against main.

Current-head validation:

• Fast CI: successful.
• Full CI: 53 successful jobs; only the expected release-staging skip.
• CodeRabbit reviewed all four files on this head and generated no actionable review comments. No unresolved review threads remain.
• Current-main core schema and pinned Dynamo RC9 Planner schema validation, shell syntax, Markdown destinations, SPDX/legal checks, model JSON, and whitespace checks pass.

GitHub retains the existing human approvals and reports APPROVED/MERGEABLE. The documentation-only patch was preserved during the merge with main. Exact RC-wheel end-to-end verification remains the stated QA follow-up in NVBug 6785216; it is not claimed by this CI result.

Proceeding with the requested SHA-guarded squash merge into main.