Upgrade Deps

Usage

/upgrade-deps <package==version> [<package==version> ...]

Arguments: One or more pinned package versions, e.g., /upgrade-deps megatron-core==0.17.0 sglang==0.5.10 vllm==0.18.0 transformers==4.58.0.

If a package is omitted, its current version can be preserved or upgraded, depending on the resolution of uv lock.

Architecture

Dual-Manifest Model

AReaL maintains two pyproject files because SGLang and vLLM pin mutually-incompatible torch / torchao versions:

Both share the same core dependencies, megatron extras, and dev group. They diverge only in inference backend extras and torch/torchao version constraints.

The Dockerfile builds both variants from a single file using ARG VARIANT (sglang or vllm). The base image, torch install, and flash-attn wheels are all variant-specific.

Focused Packages

The following packages are focused — their API usage in AReaL is cataloged, and any version change triggers the API compatibility audit (Step 6):

torch is tracked in the Package Impact Matrix below for scope and Docker awareness, but is not a focused package — it does not receive API auditing.

Package Impact Matrix

Every entry below has a variant scope that determines which files to edit, which lock files to regenerate, and whether the Dockerfile needs review. All focused packages plus torch (tracked for Docker impact only, not API-audited) are listed.

Scope rules:

• sglang-only / vllm-only: Edit and lock only the affected variant.
• shared: Edit both files; lock both variants.
• shared-divergent: The two variants intentionally use different versions of the same package. If the user supplies a single target version, ask which variant(s) to apply it to rather than assuming convergence. If the user supplies two targets (e.g., torch==2.9.1@sglang torch==2.10.0@vllm), apply each accordingly.

Upgrade Families

Some packages are tightly coupled and should be upgraded together:

When the user upgrades one member, check the checklist of all family members for required co-upgrades and warn if a co-upgrade is needed but not requested.

Per-Package API Checklists

Each focused package has a dedicated markdown file under checklists/ that documents how AReaL uses that package's APIs:

.agents/skills/upgrade-deps/
├── SKILL.md
└── checklists/
    ├── megatron-core.md
    ├── megatron-bridge.md
    ├── vllm.md
    ├── sglang.md
    ├── transformers.md
    ├── peft.md
    └── torchao.md

Each checklist file MUST contain the following sections:

---
package: <pip-package-name>
github: <org/repo>                    # e.g., NVIDIA/Megatron-LM
branch_template: "v${VERSION}"        # how to construct the git branch/tag from version
upstream_paths:                        # source paths to cross-reference
  - path/to/relevant/file.py
  - path/to/relevant/module/
---

## Affected Files

### Primary (most likely to break)
| File | Imports / Usage |
| ---- | --------------- |
| ...  | ...             |

### Secondary
...

### Tertiary (tests, infra)
...

## API Usage Catalog

For each function/class, verify the call signature against the upstream source.
Focus on: removed params, renamed params, new required params, changed return types,
moved/renamed modules.

### 1. `module.submodule.function_or_class`

**Source:** `upstream_path/file.py`

Called in `areal/path/to/file.py:LINE`:
\```python
actual_call_site_code()
\```

**Check:** [what to verify]

### 2. ...

## Version-Guarded Code (if any)
- [file:line] description of version guard and when it can be removed

To populate a checklist, catalog AReaL's usage of the package by grepping for imports and call sites, then fill in the template sections. Each checklist should be self-contained — all API signatures, file paths, and upstream references must be recorded directly in the checklist file.

Workflow

Step 0: Parse Input and Record Baseline

1. Parse arguments. Each argument is <package==version> or, for shared-divergent packages, <package==version@variant> (e.g., torchao==0.16.0@vllm).
2. Validate that each package name is a recognized focused package (see Focused Packages table). If unrecognized, warn but proceed — it may be a transitive dependency the user wants to pin.
3. For shared-divergent packages (torch, torchao): if the user supplies a single version without a @variant qualifier, ask which variant(s) to apply it to before proceeding.
4. Record the current resolved versions of ALL focused packages from the applicable lock file(s) as the baseline snapshot. Use uv.lock for sglang-scoped and shared packages; uv.vllm.lock for vllm-scoped and shared packages. Packages scoped to a single variant appear only in that variant's lock file. This baseline will be used later to detect which packages actually changed — including transitive bumps caused by uv lock resolution, not just explicit pin changes.

Step 0.5: Validate and Update Checklists

Before modifying any dependencies, verify that the API checklists for the packages being upgraded are structurally complete — i.e., they document all current AReaL import sites and call patterns. Stale checklists lead to missed breaking changes in Step 6.

For each focused package explicitly requested in the command that has a checklist file under checklists/:

1. Discover all usages. Grep the AReaL codebase (areal/, tests/, examples/) for all imports matching the package's import path(s). See the Import Patterns table in CHECKLIST_MAINTENANCE.md § 2 for package-specific grep patterns. For HTTP-based integrations (sglang, vllm), also scan request-building code for endpoint paths and JSON field names.

2. Compare against the checklist. Diff the discovered files against the Affected Files tables (Primary / Secondary / Tertiary) in the checklist. Identify:

   • Missing — files that import the package but are not listed in any tier.
   • Stale — files listed in the checklist that no longer import the package.
   • Changed — files whose actual imports differ from what's documented.

3. Classify and update. For each discrepancy, follow the Structural Validation Procedure in CHECKLIST_MAINTENANCE.md § 3:

   • Add missing files to the appropriate tier (Primary / Secondary / Tertiary).
   • Add new API Usage Catalog entries for genuinely new call patterns.
   • Remove stale entries.
   • Renumber catalog entries if needed.

4. Update the Checklist File Status table at the bottom of this file if entry counts changed.

5. Report changes before proceeding:

   Checklist validation for <package>:
   - Added N files to Affected Files (P primary, S secondary, T tertiary)
   - Added M new API catalog entries: [brief list]
   - Removed K stale entries: [brief list]
   - No changes needed (if clean)

If a requested focused package does not have a checklist file, create one from checklists/_TEMPLATE.md using the full procedure in CHECKLIST_MAINTENANCE.md § 5.

Scope note: This step validates only the packages explicitly named in the command. Packages that are transitively bumped are identified later in Step 5; their checklists are validated at that point using the same procedure before the API audit in Step 6.

Step 1: Update Pyproject Files

For each requested package, using the Package Impact Matrix:

1. Determine the variant scope (sglang-only, vllm-only, shared, shared-divergent).
2. Edit the version pin in all declaration locations for each affected pyproject file. A single package may appear in multiple locations:
   • [project].dependencies
   • [project.optional-dependencies].<extra>
   • [tool.uv].override-dependencies
3. For upgrade families: if megatron-core is being upgraded, also check whether megatron-bridge needs a corresponding version bump. Warn if it does but was not included in the command.

Step 2: Lock Dependencies (Variant-Aware)

Regenerate lock files for each affected variant. A variant is affected if any of its pyproject file's dependencies were modified. If conflicts arise during locking, do NOT attempt to resolve them in this step — just report them and defer resolution to Step 3.

SGLang variant (if pyproject.toml was modified):

bash scripts/uv_lock.sh

vLLM variant (if pyproject.vllm.toml was modified):

bash scripts/uv_lock.sh

If uv lock fails for either variant:

1. Read the error message carefully.
2. If it's a version conflict, proceed to Step 3 to resolve, then return here to re-lock.
3. Do NOT modify dependencies without user approval to make the lock succeed.

Validation: After locking, verify both lock files exist and are non-empty.

Step 3: Resolve Dependency Conflicts

Resolve any conflicts from Step 2. After all conflicts are resolved, return to Step 2 and re-lock the affected variant(s). Classify each conflict:

Auto-resolvable — only AReaL's pin conflicts with an upstream package, and the upstream's required version is acceptable. Update AReaL's pin automatically.

Needs user input — two upstream packages have mutual conflicts (e.g., sglang requires torch==2.9.1 but vllm requires torch==2.10.0). Summarize and ask the user.

Output format:

Summary

---
Auto-resolved (no action required):
- <name>: <packageA> requires <versionA>, <packageB> requires <versionB>,
  AReaL specified <oldVersion>, updated to <newVersion>
- ...

---
Conflicts (need user resolution):
- <name>: <packageA> requires <versionA>, <packageB> requires <versionB>
- ...

You may use override-dependencies in [tool.uv] to force-pin versions where needed. Remember that sglang and vllm are separate variants maintained in different pyproject files — they are never installed together in the same environment.