Helper scripts live in this skill's `scripts/` directory (copy or vendor
them into your repo). All helpers are also reachable through a unified
dispatcher with the same argument names and exit codes:

```bash
pixi run python scripts/import_model.py inspect <HF_MODEL_ID>
pixi run python scripts/import_model.py scaffold <HF_MODEL_ID> --start-from llama3 --output-dir ./
pixi run python scripts/import_model.py list-archs --match LlamaForCausalLM
pixi run python scripts/import_model.py check-walls <HF_MODEL_ID>
pixi run python scripts/import_model.py list-keys <HF_MODEL_ID> --summary
pixi run python scripts/import_model.py gates <HF_MODEL_ID> --port-dir <port_dir>/
pixi run python scripts/import_model.py compare <HF_MODEL_ID> --slug <slug> --port 8000

• <port_dir>

  — slug folder containing

  arch.py

  and

  ARCHITECTURES

  in

  __init__.py

  (usually

  <output_dir>/<slug>/

  ). Pass this path to both

  --custom-architectures

  and

  run_oss_gates.py --port-dir

  .

--custom-architectures <port_dir>

dirname(<port_dir>)

sys.path

basename(<port_dir>)

custom-arch

modular/max/python/max/pipelines/architectures/<donor>/

Guard: is the architecture already registered in MAX? Before writing any code, check whether MAX already registers the architecture class in your model's

config.json::architectures[0]

. If

pixi run python list_native_archs.py --match <Class>

returns a slug, run

pixi run max serve --model <HF_MODEL_ID>

and stop — no port needed. Full procedure: native-arch-check.md.

https://huggingface.co/<HF_MODEL_ID>

• The paper or blog post. Skim its architecture section — authors call out the interesting modifications (QK-norm, MLA, sliding-window attention, MoE routing) because those are what they want credit for.
• "Tricks" mentioned in the card. Phrases like "we introduce", "unlike prior models", "this is the first model to" mark deltas that will bite you during implementation if you miss them now.

scaffold.py

pixi run python scaffold.py <HF_MODEL_ID> --start-from <max_arch_slug> --output-dir <output_dir>

architectures[0]

config.json

arch.py::name

<output_dir>/<slug>/

• arch.py

  — registration shell (verify

  name=

  and encoding)

• model_config.py

  — donor config (must be rewired during implementation)

• model.py

  — pipeline model shell

• weight_adapters.py

  — donor renames (must be rewritten for your checkpoint)

• <slug>.py

  — donor graph (must be edited to match HF during implementation)

<slug>.py

1. model_config.py

   — wire every

   config.json

   key from Phase 1 /

   inspect_hf.py

   . Set

   get_kv_params()

   head counts and head_dim to match HF.

2. weight_adapters.py

   — map your checkpoint's safetensor keys to the MAX module names you will use. Run

   list_checkpoint_keys.py

   first; see rename-weights.md. After load, wire the coverage audit in state-dict-audit.md (especially MoE and

   strict=False

   tied embeddings).

3. <slug>.py

   — for each row in the delta list, edit or replace the donor class so MAX

   forward()

   mirrors HF

   forward()

   :
   • Attention (Q/K/V, RoPE, mask, GQA, softcap, …)
   • MLP or MoE (activation, routing, shared experts, …)
   • Decoder block (norm order and residual wiring — not interchangeable with Llama)
   • Final norm and LM head (tie, logit scale, softcap)

4. arch.py

   — confirm

   name=

   matches

   architectures[0]

   ;

   default_encoding

   matches Hub

   torch_dtype

   .

5. model.py

   — only if HF wraps the backbone differently (VL, multi-modal).

modeling_<type>.py

pixi run rg -i -n 'qwen|llama|mistral|cohere|gemma|phi|deepseek|exaone|olmo|granite|qwen3|mixtral|single-GPU|single GPU|RMSNorm|QK-norm' <port_dir>/

"docstrings rewritten to the three-sentence pattern; rg returns N hits, all legitimate lineage references"

pixi run python run_oss_gates.py <HF_MODEL_ID> --port-dir <port_dir>/

Guard: local smoke gate (mandatory before Phase 3).

pixi run max serve

cold-compiles for 5–25 minutes. Before serving, run the four local checks in serve-and-iterate.md (import smoke, graph dry-build, adapter⇄graph key diff, weights-format preflight).

run_oss_gates.py

covers walls, checkpoint metadata, and

arch.py

name/encoding — not a substitute for those four.

1. Read the HF reference implementation to understand what should happen at each layer.
2. Dump intermediate tensors from both implementations and find the first layer where they diverge.
3. Fix that layer.
4. Re-run the layer check.
5. Repeat until all layers match.

modeling_<type>.py

• A norm whose variant or position differs from the template
• A scale factor applied somewhere (

  hidden_states * scale

  ,

  attn_weights / sqrt(d)

  , MuP multipliers)
• A different activation function in the MLP
• A different RoPE style (split-half vs. interleaved, partial vs. full)
• A boundary condition that only fires at certain layers (sliding-window vs. global attention, sink-token handling)

MyModelDecoderLayer(GraniteDecoderLayer)

pixi run python compare_layers.py <HF_MODEL_ID> \
  --slug <your_slug> --port 8000 \
  --prompt "The capital of France is"

pixi run max serve

--custom-architectures <port_dir>

• Prints HF-only per-layer stats (embedding + each block output) as a diagnostic snapshot while you read the modeling code.
• Compares top-1 logprob at the prompt between HF and MAX via

  /v1/completions?logprobs=…

  .

ops.output(...)

<slug>.py

• Scaffold ≠ port. Do not serve or verify until the graph implements every delta in

  <slug>.py

  .
• Sed-rename leaves donor docstrings intact. Class names get renamed, but docstrings and comments still describe the donor. Rewrite them and run the audit grep before declaring the implementation done.