docs: constrain grpcio-tools in Planner installation examples

[jasonqinzhou]

Why and what changed

This addresses the remaining dependency-installation issue reported in NVBug 6785216: [aisimulate][release/0.12.0][Docs] "With Dynamo" installation instructions omit Planner prerequisites. The original failure was ModuleNotFoundError: No module named 'sklearn' when loading the Planner adapter after the basic wheel installation. Merged PR #231 documents the complete Planner prerequisites and adds a runnable CPU-only example.

Following #231's installation steps can leave pip check failing: AISimulate's google-vizier dependency can install a newer grpcio-tools, then the separate Planner requirements installation pins protobuf to 6.33.6 without constraining the already-installed tooling.

Both Planner installation examples now include "grpcio-tools<=1.76.0" in the same pip invocation as the matching Planner requirements. This matches Dynamo 1.5.0 RC9's common requirements at ffd7c1a90eb403c0d43911690c5c9b8457acd826. The explanations link that source and tell readers to revisit the cap when changing Dynamo revisions.

Review map

• Risk level: low; two documentation files only.
• Start with the installation commands in README.md and docs/cli/examples/dynamo-planner/README.md.
• Public or serialized contract changed: no runtime, package metadata, schema, or CLI changes.
• Compatibility: the cap is scoped to the documented RC9 setup; other revisions must use their corresponding constraints.

Evidence

Qun Chi recorded in NVBug 6785216 comment 2 that the original documentation at 7ebe37aeeb826c61f60c16c56c536c8ab8f8afa2 was verified in a fresh Python 3.12 environment using the exact AIS 0.12.0.dev2 and Dynamo RC9 QA wheels. The Planner CLI completed all 12 requests and generated prediction.json and requests.jsonl, but pip check still reported a grpcio-tools/protobuf conflict. This PR addresses that remaining conflict; the QA result predates this correction.

A focused, isolated Python 3.12.11 environment on macOS reproduced and repaired the dependency conflict:

pip install grpcio-tools==1.84.0
pip install protobuf==6.33.6
pip check
  exit 1: grpcio-tools 1.84.0 has requirement protobuf<8.0.0,>=7.35.1,
          but you have protobuf 6.33.6.

pip install 'grpcio-tools<=1.76.0' protobuf==6.33.6
pip check
  exit 0: No broken requirements found.
  resolved grpcio-tools 1.76.0 and protobuf 6.33.6

• All 16 shell blocks in the two documents pass bash -n.
• Repository documentation destination checks, SPDX checks, packaged legal-file checks, and git diff --check pass.
• Hosted CI and exact-head review will be recorded in this PR's checks and review activity.
• This focused resolver test does not install the full Planner environment or the exact Linux RC9 wheels. QA should rerun the documented installation with those artifacts and confirm a clean pip check, 12 completed requests, and both output files.

Modeling or data provenance

N/A; no simulation, performance data, or prediction changes.

Tracking

• Bug: NVBug 6785216, kept open by QA pending verification of this dependency correction and release inclusion.
• Main fix sequence: docs: document Dynamo Planner installation prerequisites #231 supplies the missing Planner setup; this PR adds the compatible tooling constraint.
• Release follow-up: docs: backport Planner installation prerequisites to 0.12 #237 backports the original documentation to release/0.12.0; the correction from this PR must also reach that branch.
• Closure requires the complete documentation fix on release/0.12.0 and QA verification with the exact matching wheels: clean pip check, 12 completed requests, and both output files. Merging this main-branch PR alone does not close the bug.

[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.

[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: 805f6229-9fa9-4fd1-893e-dcb42adc9333

📥 Commits

Reviewing files that changed from the base of the PR and between 920453e and c005295.

📒 Files selected for processing (2)

• README.md
• docs/cli/examples/dynamo-planner/README.md

🔗 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; 11 remain after this review.

📜 Recent review details

⏰ Context from checks skipped due to timeout. (1)

• GitHub Check: Fast CI Success

🧰 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/README.md
• README.md

Read REVIEW.md before commenting.

⚙️ CodeRabbit configuration file

Files:

• docs/cli/examples/dynamo-planner/README.md
• 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/README.md
• README.md

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

Linked repositories findings

ai-dynamo/dynamo

• container/deps/requirements.common.txt:15,33 already caps grpcio-tools<=1.76.0 and pins protobuf==6.33.6, matching the documented compatibility target. [::ai-dynamo/dynamo::]
• container/deps/requirements.planner.txt:11-22 treats grpcio and protobuf as Planner runtime dependencies, with protobuf==6.33.6 and a comment requiring gRPC pin synchronization with the common requirements. [::ai-dynamo/dynamo::]
• Planner protobuf/gRPC stubs are checked into the repository, so grpcio-tools is needed for regeneration rather than normal runtime imports (components/src/dynamo/planner/plugins/proto/v1/README.md:47-60). [::ai-dynamo/dynamo::]

ai-dynamo/aiconfigurator

• The Dynamo integration only generates Planner configuration and selects the Planner image; it does not install Planner dependencies (src/aiconfigurator/generator/dynamo_features.py:148-181, src/aiconfigurator/generator/builders/k8s_builder.py:171-198). [::ai-dynamo/aiconfigurator::]

🔇 Additional comments (2)

README.md (1)

65-65: LGTM!

Also applies to: 70-74

docs/cli/examples/dynamo-planner/README.md (1)

39-39: LGTM!

Also applies to: 44-51

---

📝 Summary

Risk: Medium. Human attention should focus on:

1. Validate the Linux RC9 Planner installation with exact wheels.
2. Confirm Planner runtime behavior after the grpcio-tools<=1.76.0 cap.
3. Check that users update the cap when they change DYNAMO_REF.

The change affects only Planner installation documentation. It adds the grpcio-tools<=1.76.0 constraint beside the Planner requirements and documents its RC9 and protobuf==6.33.6 scope. It does not change runtime code, package metadata, schemas, CLI behavior, or public APIs.

The supplied checks exited successfully, but their output contains no diff details. The provided summary reports passing focused dependency, shell syntax, documentation destination, SPDX/legal-file, and whitespace checks. No current review severity findings were supplied.

Technical quality is supported for the documented dependency change. Merge readiness remains incomplete. Exact Linux RC9 wheel validation, full Planner execution, hosted CI, NVIDIA runner admission, and human CODEOWNER approval are still pending.

Walkthrough

Changes

Planner dependency documentation

Layer / File(s)	Summary
Dependency installation guidance README.md, docs/cli/examples/dynamo-planner/README.md	Planner installation commands cap grpcio-tools at 1.76.0. The documentation describes protobuf compatibility, resolver ordering, and updating the cap with DYNAMO_REF.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~5 minutes

Merge Risk: ⚪ Minimal · up to c0052

The Planner installation guidance is consistently updated in both documented entry points, with no identified merge-blocking risk.

🚥 Pre-merge checks | ✅ 8

✅ Passed checks (8 passed)

Check name	Status	Explanation
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.
Cross-Layer Contract	✅ Passed	PASS. The review-scoped diff changes only README.md and docs/cli/examples/dynamo-planner/README.md; it changes no Rust, Python, CLI, serialization, schema, package metadata, or test consumer. The …
Modeling And Data Evidence	✅ Passed	PASS: The authoritative diff changes only README.md and the Planner installation README. It adds a grpcio-tools<=1.76.0 install constraint and compatibility guidance. It does not introduce formulas,…
Compatibility Boundaries	✅ Passed	PASS: The pull request changes only README.md and the Planner example. Both documented commands add grpcio-tools<=1.76.0 to the same installation as the RC9 Planner requirements. The cited Dynamo …
Review Evidence	✅ Passed	The PR description names the relevant commands and results: the two pip install cases and pip check with failure before the cap and success after it. It includes boundary evidence by stating that …
Description check	✅ Passed	The description covers the problem, behavior change, affected consumers, review map, risk, compatibility scope, test evidence, pending QA, provenance, and tracking information. It is complete enough f…
Title check	✅ Passed	The title precisely states the behavioral change: it constrains grpcio-tools in the Planner installation examples. It is specific and directly related to the changeset.

---

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

[jasonqinzhou]

Self-review of published head c00529535716623e0f5e860db2812267fe925d32 against main 920453e6a6cfb958eae2b2f725db9b767788b4c7 found no actionable issue in the complete two-file diff. The local checkout matches the remote head and is clean.

The two commands now apply the RC9 common-requirements cap in the same resolver invocation as Planner's protobuf pin. Both documents scope the cap to that revision and explain how to update it for another revision. The focused Python 3.12 reproduction fails pip check before the cap and passes afterward with grpcio-tools==1.76.0 and protobuf==6.33.6. All 16 shell blocks, repository documentation destinations, SPDX/legal checks, and whitespace checks pass.

The exact Linux RC9 wheel setup remains a separate QA validation; this review does not substitute the focused dependency test for the full Planner run. No self-review correction threads were needed. Hosted review and CI remain pending, including normal NVIDIA runner admission. Human CODEOWNER approval remains required before merge.