Validate Terra Runtime And Local Model Integration#62
Conversation
|
Warning Review limit reached
Next review available in: 53 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (4)
📝 WalkthroughWalkthroughThe PR adds immutable Hugging Face model-source verification to validation and release workflows, replaces the recommended AWQ model entry, and raises the default local context window to 32,768 tokens. GPU images now install startup compatibility hooks for Transformers and vLLM runtime checks. Launcher diagnostics distinguish early runtime exits from timeouts. Terra documentation, notebook instructions, Jupyter kernel isolation, and OpenHands Skill path guidance are also updated. Sequence Diagram(s)sequenceDiagram
participant ValidateWorkflow
participant ModelSourceVerifier
participant SnapshotCatalog
participant HuggingFaceAPI
ValidateWorkflow->>ModelSourceVerifier: verify recommended sources
ModelSourceVerifier->>SnapshotCatalog: load repository and revision pins
ModelSourceVerifier->>HuggingFaceAPI: query immutable revision endpoint
HuggingFaceAPI-->>ModelSourceVerifier: return id and sha
ModelSourceVerifier-->>ValidateWorkflow: complete or report verification status
Possibly related issues
Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
This PR incorporates findings from Terra live validation to harden local-model (vLLM) startup and the Terra Jupyter experience, while improving governance checks that recommended Hugging Face model pins remain immutable and resolvable.
Changes:
- Update the recommended 16 GB GPU model snapshot (Qwen2.5 7B Instruct AWQ) and standardize the default local context window to 32,768 tokens across planning/CLI/gateway.
- Ensure the reviewed Transformers 5 compatibility boundary is applied in all vLLM processes (including child processes) and expand GPU runtime verification checks.
- Add CI/release-time verification of recommended Hugging Face model revisions; document and test the Terra workflow updates (proxy, runtime behavior, safe shutdown, and troubleshooting).
Reviewed changes
Copilot reviewed 30 out of 30 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| packages/gateway/tests/test_openhands_sdk.py | Asserts updated OpenHands system suffix guidance for Skill-path resolution. |
| packages/gateway/tests/test_model_snapshots.py | Updates expected recommended Terra snapshot ID/repo. |
| packages/gateway/tests/test_local_models.py | Aligns local-model plan expectations with 32,768 context and new model IDs. |
| packages/gateway/tests/test_gateway_contract.py | Updates expected first recommended model ID in gateway contract tests. |
| packages/gateway/src/heartwood/gateway/_openhands_sdk.py | Adjusts AgentContext system suffix to constrain Skill path resolution. |
| packages/gateway/src/heartwood/gateway/_local_model_contract.py | Raises default local context window to 32,768. |
| packages/compliance/tests/test_release_governance.py | Ensures workflows invoke the model-source verification script. |
| packages/compliance/tests/test_model_source_verification.py | Adds unit tests for the model-source verification script and outage handling. |
| packages/compliance/tests/test_container_assets.py | Extends container-asset expectations (IPYTHONDIR isolation; vLLM runtime assets). |
| packages/cli/tests/test_launch.py | Adds coverage for early vLLM exit messaging; updates context window expectations. |
| packages/cli/src/heartwood/cli/_launch.py | Reports early runtime exit distinctly from readiness timeout. |
| images/platform/scripts/terra_jupyter_contract_smoke.sh | Verifies the Heartwood kernel sets IPYTHONDIR for isolation. |
| images/platform/Dockerfile | Adds ipykernel --env IPYTHONDIR and installs vLLM sitecustomize. |
| images/gpu/sitecustomize.py | Applies Transformers compatibility hook on interpreter startup. |
| images/gpu/heartwood-vllm | Sets PYTHONPATH to the isolated runtime bin for child-process inheritance. |
| images/gpu/heartwood_vllm.py | Expands Transformers/vLLM verification, tokenizer cache subprocess check, and Qwen registry inspection. |
| images/generic/local-runtime/snapshots.toml | Renames/updates the recommended 16 GB GPU snapshot to Qwen2.5 7B Instruct AWQ. |
| images/generic/Dockerfile | Installs vLLM sitecustomize into the GPU runtime environment. |
| docs/troubleshooting.md | Updates guidance for early runtime exit vs timeout. |
| docs/terra-jupyter-demo.md | Expands Terra runbook (config order, interface roles, safe shutdown, updated model IDs). |
| docs/terra-jupyter-demo.ipynb | Aligns notebook prompt/task wording with the updated runbook command. |
| docs/platform-support.md | Refines Terra validation claims and clarifies what was/wasn’t validated in 0.2.0-beta.2. |
| docs/getting-started-offline.md | Updates context-window defaults/claims when model metadata is missing. |
| docs/container-images.md | Updates 16 GB NVIDIA model download guidance to the new model ID. |
| design/07-testing-eval.md | Adds runtime-integration details about GPU-image verification and external-source preflight. |
| design/03-architecture.md | Updates architecture text to reflect the 32,768 default when model metadata is missing. |
| deploy/verify_model_sources.py | Adds a script to verify recommended Hugging Face repos resolve at pinned commits. |
| deploy/carina/bootstrap.sh | Installs vLLM sitecustomize into the Carina vLLM bundle. |
| .github/workflows/validate.yml | Adds a CI job to verify recommended model sources (allowing bounded outages). |
| .github/workflows/create-release.yml | Adds strict model-source verification to the release workflow. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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 `@docs/platform-support.md`:
- Line 45: Revise the documentation paragraph to describe only the currently
validated Terra deployment behavior and limitations. Remove the
development-history details about prior image failures, test-only intervention,
replacing recommendations, and vLLM compatibility fixes; retain the requirement
for real workspace validation and the stated Heartwood authorization boundaries.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 28d6a7d0-f197-49a3-af1c-c4ff83a0b84a
📒 Files selected for processing (30)
.github/workflows/create-release.yml.github/workflows/validate.ymldeploy/carina/bootstrap.shdeploy/verify_model_sources.pydesign/03-architecture.mddesign/07-testing-eval.mddocs/container-images.mddocs/getting-started-offline.mddocs/platform-support.mddocs/terra-jupyter-demo.ipynbdocs/terra-jupyter-demo.mddocs/troubleshooting.mdimages/generic/Dockerfileimages/generic/local-runtime/snapshots.tomlimages/gpu/heartwood-vllmimages/gpu/heartwood_vllm.pyimages/gpu/sitecustomize.pyimages/platform/Dockerfileimages/platform/scripts/terra_jupyter_contract_smoke.shpackages/cli/src/heartwood/cli/_launch.pypackages/cli/tests/test_launch.pypackages/compliance/tests/test_container_assets.pypackages/compliance/tests/test_model_source_verification.pypackages/compliance/tests/test_release_governance.pypackages/gateway/src/heartwood/gateway/_local_model_contract.pypackages/gateway/src/heartwood/gateway/_openhands_sdk.pypackages/gateway/tests/test_gateway_contract.pypackages/gateway/tests/test_local_models.pypackages/gateway/tests/test_model_snapshots.pypackages/gateway/tests/test_openhands_sdk.py
♻️ Current Situation & Problem
Progresses #42 and #51.
The published
0.2.0-beta.2Terra image preserved Jupyter, project persistence, the authenticated proxy route, and the shared CLI, browser, and notebook contracts. A synthetic NVIDIA T4 validation also exposed three release-blocking gaps: the 16 GB model recommendation referenced the wrong repository revision, vLLM child processes did not inherit the required Transformers 5 compatibility boundary, and the isolated Heartwood kernel inherited incompatible Terra IPython startup extensions. The immutable beta image required test-time repair before it could complete a local-model OpenHands action, so it is not recorded as fully live-validated.This pull request incorporates the live findings without introducing model weights, credentials, workspace data, or controlled data into the repository.
⚙️ Release Notes
📚 Documentation
The Terra guide now follows one goal-oriented path from environment creation through synthetic validation and compute shutdown. The tutorial notebook, local-model guide, troubleshooting guide, platform support matrix, container guide, and architecture and testing references are aligned with the same behavior and evidence boundary.
The support matrix records that
0.2.0-beta.2required test-time intervention and that a corrected immutable artifact still needs the complete live workflow before a full Terra validation claim is made.✅ Testing
uv run pytest: 611 tests passed with 90.37% coverage.gpu-ci-validatestage and is the authoritative container build for this change.Code of Conduct & Contributing Guidelines
By creating and submitting this pull request, you agree to follow our Code of Conduct and Contributing Guidelines: