Skip to main content
skill CX Codex

migrate-max-v2-to-v3 — Claude Code skill: what it does and install

migrate-max-v2-to-v3 — a skill for Claude Code and Codex that migrates MAX framework models from the legacy V2 graph API to ModuleV3. It updates imports, swaps TensorValue for Tensor, and switches graph building to compile().

Apache-2.0 324 installs ★ 213 updated 2026-11-07

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add modular/skills --skill migrate-max-v2-to-v3 -a claude-code
Open on GitHub

What migrate-max-v2-to-v3 does

The skill converts deep learning model definitions from the deprecated max.nn.legacy graph API to current max.nn conventions. Running the workflow requires a working MAX environment installed via pip or pixi, the original V2 model source code, and a GPU.

The assistant swaps TensorValue and BufferValue types for Tensor, redirects execution logic from __call__() into forward(), and switches layers to ModuleList. Instead of manual Graph assembly, model instantiation runs inside an F.lazy() context followed by compile(weights=state_dict). Missing parameters in the state dict trigger a KeyError, so the migration process aligns attribute paths with checkpoint keys.

Without an accessible GPU, verifying that greedy outputs match the V2 implementation is impossible. If the original model used sharding, the workflow moves those partitions onto a DeviceMesh.

What it helps with

  • rewrite layers from max.nn.legacy to max.nn
  • replace deprecated TensorValue objects with Tensor
  • switch explicit Graph construction to F.lazy() and compile()
  • align checkpoint weight keys with the new module hierarchy

Example prompts for the agent

  • Migrate the model in models/my_model.py from V2 graph API to ModuleV3
  • Convert TensorValue usages to Tensor in transformer.py
  • Update imports from max.nn.legacy to max.nn and configure compile()

How to install migrate-max-v2-to-v3

1Skills CLI (Vercel)

npx skills add modular/skills --skill migrate-max-v2-to-v3 -a claude-code

2Manually: put the files in place

~/.claude/skills/migrate-max-v2-to-v3/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/migrate-max-v2-to-v3/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about migrate-max-v2-to-v3

How to install migrate-max-v2-to-v3 in Claude Code?

Run npx skills add modular/skills --skill migrate-max-v2-to-v3 -a claude-code in your terminal. The skill file is placed in ~/.claude/skills/migrate-max-v2-to-v3/SKILL.md.

What does migrate-max-v2-to-v3 do?

It provides a guided workflow to port MAX models from legacy graph construction to ModuleV3, updating tensor types, layer signatures, and weight compilation.

What prerequisites are needed to verify the migration?

You need MAX installed via pip or pixi, the original model code, and a GPU to compare greedy output tensors against the V2 baseline.

Source text

SKILL.md · Apache-2.0
---
name: migrate-max-v2-to-v3
description: >
  Use when migrating a MAX model from the V2 graph API (max.nn.legacy, TensorValue,
  explicit Graph construction) to ModuleV3 (max.nn, Tensor,
  F.lazy() + compile()). Triggers on: "migrate to ModuleV3", "port a max.nn.legacy
  model to max.experimental", "convert TensorValue to Tensor", "update my
  model to the V3 API", "ModuleV3 migration". Workflow: read the concept map,
  rewrite imports and __call__ signatures, and replace graph building with
  compile(weights=...). Align weight names with the new module hierarchy and
  move the KV cache unflatten into forward(). Port sharding to a DeviceMesh
  when the V2 model is sharded, then verify greedy outputs match the V2
  implementation.
compatibility: Requires a MAX install (pip or pixi), the V2 model source to migrate, and a GPU to verify outputs.
metadata:
  argument-hint: "[path to your V2 model code, for example 'models/my_model.py']"
---

# Migrate a MAX model from V2 to ModuleV3

**Input**: the V2 model source to migrate (`$ARGUMENTS`).

ModuleV3 (`max.nn`) is the current MAX model API. A V2 model
builds an explicit `Graph` over `TensorValue` values with layers from
`max.nn.legacy`. A ModuleV3 model declares a `forward()` over `Tensor` values and
compiles with `F.lazy()` + `compile()`. Read
[references/v2-v3-basics.md](references/v2-v3-basics.md) first. It covers
`F.lazy()`, `compile(weights=...)`, dtype handling with `auto_cast`,
`forward()` vs `__call__()`, the distributed mapping, and the import
rules.

For architecture serving integration, read the
[module registration compatibility reference](references/module-registration.md).
Prefer supported ModuleV3 role registration without an architecture-specific
`PipelineModel`. The standalone compilation examples below explain the model
API; the registration runtime owns those steps for registered architectures.
Keep a custom pipeline for a documented unsupported task, backend or feature.
Draft/speculator module registration has not been added.

## Workflow

### 1. Confirm the model is V2

Classify by imports, and read the file when grep and the imports disagree.
V2 code imports its layers from `max.nn.legacy` and builds an explicit `Graph`
over `TensorValue`. ModuleV3 code imports `max.nn` and
subclasses its `Module`. Scoped greps shortcut the read:

```bash
grep -rn "max.experimental" <model-path>
grep -rEn "^\s*(from|import) max\.nn" <model-path>
```

Hits from the first mean the model is already (at least partly) V3 and
needs review, not migration. Hits from the second mean V2. Imports from
`max.graph` alone don't decide: V3 code keeps `TensorType` and
`DeviceRef` from `max.graph` for input specs. A file that hits both is
mixed. Read it before migrating anything.

### 2. Keep the V2 code, add the V3 variant

Leave the V2 implementation untouched so it keeps working while the V3
variant is under construction. Put the V3 code alongside it: a
`<name>_modulev3` directory when migrating a registered architecture, or a
new module file when the model lives in your own package. When migrating a
registered architecture, name the V3 variant with the `_ModuleV3` suffix.
`max serve --prefer-module-v3` selects it while the V2 name keeps serving
by default.

### 3. Rewrite imports

```python
# REMOVE:
from max.graph import Graph, TensorValue, BufferValue, ops
from max.nn.legacy.layer import Module, LayerList
from max.nn.legacy.linear import Linear
from max.nn.legacy.norm.rms_norm import RMSNorm

# ADD:
from max import functional as F
from max.tensor import Tensor
from max.nn import Module
from max.nn.linear import Linear
from max.nn.norm import RMSNorm
from max.nn.sequential import ModuleList

# KEEP (TensorValue-free, shared with V2):
from max.nn.kv_cache import KVCacheParams, KVCacheParamInterface
from max.nn.attention_mask import MHAMaskVariant
```

- `TensorType` and `DeviceRef` stay from `max.graph`. They define input
  specs, not graph values.
- `max.nn.legacy` imports are fine when the imported class doesn't use
  `TensorValue`.
- `PagedCacheValues` comes from
  `max.nn.common_layers.kv_cache` for the V3 type. `max.nn.legacy`
  exports a `PagedCacheValues` of its own, an alias for the V2 input type
  without `from_upstream()`. Import from the `max.experimental` path to
  get the V3 type.

### 4. Rewrite the module surface

- `__call__()` becomes `forward()`.
- `TensorValue` and `BufferValue` become `Tensor`.
- `Module` takes the call signature:
  `class MyModel(Module[[Tensor, ...], tuple[Tensor, ...]])`. Prefer
  specific types, and use `...` only when `forward()` has `*args`.
- Layer constructors take keyword args and drop `dtype=` and `device=`.
  V3 uses default dtype and device contexts, and `model.to(device)` moves
  the module to one device after construction.
- `LayerList` becomes `ModuleList` from `max.nn.sequential`.
  `ModuleList` subclasses `list`, so it takes a single iterable:
  `ModuleList(layers)`. `ModuleList(*layers)` raises `TypeError`.
- Parameters are plain `Tensor` objects. Create them with `Tensor.zeros()`,
  `max.functional.random.*`, and similar factories.

### 5. Rewrite operations

`ops.*` becomes `F.*` (`ops.gather()` → `F.gather()`). Most shape ops are
methods on `Tensor`: `reshape()`, `transpose()`, `permute()`, `squeeze()`,
`unsqueeze()`, `split()`, `cast()`. `flatten()` is the exception. It's
functional-only (`F.flatten(tensor, start_dim)`).

### 6. Replace graph building with `compile()`

V2:

```python
nn_model = MyModel(config)
nn_model.load_state_dict(state_dict)

with Graph("my_model", input_types=input_types) as graph:
    outputs = nn_model(*graph.inputs)
    graph.output(*outputs)

model = session.load(graph, weights_registry=state_dict)
```

V3:

```python
with F.lazy():
    nn_model = MyModel(config)
    nn_model.to(device)

model = nn_model.compile(*input_types, weights=state_dict)
```

- `F.lazy()` wraps construction and records weight tensors symbolically.
  The checkpoint passed to `compile(weights=...)` replaces them.
- Every parameter needs a state-dict entry of matching shape and dtype:
  a missing one raises `KeyError` and a mismatched one `ValueError`. An
  entry that matches no parameter is left out without an error, so diff
  the state-dict keys against `parameters` after migrating (step 7).
- A dtype mismatch between a parameter and its loaded tensor raises by
  default. Pass `auto_cast=True` to permit safe dtype casts.
- Call the compiled model directly (`model(tokens, ...)`). Compiled outputs
  are `Tensor` objects. Code that consumed `Buffer` outputs reads the
  buffer via `.driver_tensor`.

### 7. Align weight names with the compiled hierarchy

`compile(weights=...)` resolves names from the root compiled module's
attribute hierarchy. When migration introduces or renames wrapper
attributes, checkpoint key mappings must follow: a root module storing
`self.language_model = ...` needs every inner weight prefixed with
`language_model.`. After migrating, check that every state-dict key is a
valid attribute path from the root module.

Tied embeddings need explicit handling: conditionally create `lm_head`, and
multiply by `embed_tokens.weight.T` in `forward()` when
`tie_word_embeddings` is set. Keep one copy of the shared weight in the
state dict.

### 8. Move the KV cache unflatten into `forward()`

The KV cache parameter types stay in `max.nn.legacy`. The values type has a V3
home in `max.nn.common_layers.kv_cache`. Use the methods on
`kv_params` plus `PagedCacheValues.from_upstream()`:

```python
def forward(self, tokens: Tensor, ..., *variadic_args: Tensor):
    kv_inputs = iter(arg._graph_value for arg in variadic_args)
    symbolic_inputs = self.kv_params.unflatten_kv_inputs(kv_inputs)
    kv = PagedCacheValues.from_upstream(symbolic_inputs, tokens.mapping)
```

You need the `._graph_value` extraction: `variadic_args` arrive as
`Tensor` objects while the unflatten methods expect raw graph values. For
sliding plus global attention, declare `MultiKVCacheParams` and use
`unflatten_basic_kv_tree()`, wrapping each tree with its own
`PagedCacheValues.from_upstream()`.

### 9. Port sharding when the V2 model is sharded

V2 sharding sets a `ShardingStrategy` on each layer and calls
`.shard(devices)` to get a per-device module list. V3 puts a `DeviceMesh` on
the model and a placement mapping on each weight:

```python
from max.nn.common_layers.linear import row_parallel
from max.tensor.sharding import DeviceMesh

model.mesh = DeviceMesh(devices, (n_devices,), ("tp",))
linear = row_parallel(Linear(in_dim, out_dim))
```

`col_parallel()` and `row_parallel()` set which mesh axis each weight
dimension shards over, and V3 has no per-device module list. The V2
distributed machinery maps onto V3 as follows:

- **`Allreduce` and `Signals`**: the sharding solver reads the tensors'
  placements and inserts the collective each op needs. For example, adding
  a row-parallel output (a `Partial` sum) to a replicated residual
  all-reduces it. Call
  `F.allreduce_sum()`, `F.reduce_scatter()`, or `F.allgather()` where the
  model controls the reduction. `compile()` adds the signal buffers the
  collectives use as graph inputs and supplies them at run time.
- **`.shard()` and per-device lists**: construct the model inside
  `default_device(mesh)`, and each weight is created on the mesh with the
  placement it declares. `Module.to()` moves a module to one device only and
  raises for a multi-device mesh. Per-device code runs through
  `F.functional()`, or through `t.local_shards` and
  `Tensor.from_shard_values()`.
- **Expert parallelism**: V3 reuses `EPBatchManager`. Its
  `comm_buffers()` returns the communication buffers as `Tensor` values,
  and the MoE layer passes each device's shard to the dispatch calls as a
  `TensorValue`. For registered ModuleV3 decoders, the shared runtime uses
  `DeploymentConfig` / `ExpertParallelDeploymentConfig` to configure EP;
  see the [registration reference](references/module-registration.md).
  `_init_distributed_runtime()` is an existing custom-pipeline integration
  pattern, not boilerplate to add to a registered architecture.

`gemma3_modulev3/` (TP) and `deepseekV3_modulev3/` (TP, TP + EP, DP + EP)
show each pattern.

### 10. Verify against V2

Run both implementations on the same inputs and compare greedy tokens
(and logits where convenient). Identical outputs confirm the migration.
Run mypy over the migrated module. V3 relies on the `Module[[...], ...]`
signatures, so type errors point to migration bugs.

## Reference implementations

The registered architectures ship as readable Python source in the
installed MAX package, under `max/pipelines/architectures/`. The V3
migrations to read:

- Single-GPU V3: `olmo3/`, `gpt_oss_modulev3/`, `llama3_modulev3/`
- Sharded V3: `kimik2_5_modulev3/`, `gemma3_modulev3/`, `deepseekV3_modulev3/`
- Hybrid attention with recurrent state: `nemotron_h_modulev3/`
- V2 for comparison: `gpt_oss/`, `llama3/`

## When there is no `Tensor` equivalent

Every graph op and kernel is callable from V3: `F.functional(fn)` turns a
function over `TensorValue` into one over `Tensor`. The options, and the
wrapper pattern for bridging a per-device `TensorValue` helper into a
`Tensor` API, are in
[references/v2-v3-basics.md](references/v2-v3-basics.md).

The wrapper rules, which a reviewer enforces:

- Wrap **one** graph op or kernel per `F.functional` call. A body that calls
  two ops hides its intermediate placements from the sharding rules, and one
  unplaceable step silently turns the whole body into per-device code.
- `TensorValue` appears only in a wrapper's body. A helper that takes or
  returns one for any other reason becomes a function of `Tensor`s.
- Code that must read each device's own rows — a replica's row offsets —
  goes in `F.call_on_mesh(fn, mesh, out_specs=...)`. For one raw graph op,
  a rule-less `F.functional(ops.x)` is the shorthand; claim its `Unknown`
  result with `rebind_mapping()`. An `Unknown()` operand needs a rule row
  that names it.

© modular · Apache-2.0 · modular/skills

Similar skills

All skills for AI and ML →

From the same set11

The whole set →
mojo-python-interop mojo-python-interop — a skill that keeps your agent on current Mojo syntax when the code calls Python or exposes Mojo types to it. CX Codex +1 2,700installs new-modular-project new-modular-project initializes fresh Mojo or MAX projects using pixi or uv package managers. It clarifies missing project settings and configures stable or nightly release channels. CX Codex +1 2,600installs import-model import-model — a skill for Claude Code ports new neural network architectures from Hugging Face into MAX. Executes when importing model weights or scaffolding ModuleV3 layers. CX Codex +1 1,600installs debug-model The debug-model skill for Claude Code diagnoses a MAX model that serves and emits tokens but disagrees with a reference. It compares tensor dumps before fixes. CX Codex +1 1,400installs profile-model profile-model — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode that profiles models running on MAX — identifying which kernels consume GPU time and whether the GPU is saturated. CX Codex +1 1,300installs serve-model serve-model — a skill that takes you from no environment to an Anthropic-compatible server via max serve, flags included. CX Codex +1 1,100installs eval-model eval-model runs a text model served by MAX through standard benchmarks and writes reproducible per-task scores. Useful when you need to check a served model against its card. CX Codex +1 1,100installs benchmark-model benchmark-model drives load against a running max serve endpoint and reports tokens/sec, TTFT and TPOT. Useful when you need to know what a MAX model actually holds. CX Codex +1 1,000installs

Project sponsors

Companies that keep this analytics open