quark-onnx-shapeshifter-run

Purpose

Apply one or more existing ShapeShifter ONNX passes to an .onnx model by authoring a ShapeShifter YAML config and running the quark-cli shapeshifter CLI. ShapeShifter is Quark's pass-based graph-transformation framework; this skill covers invoking its built-in onnx_* passes (fold BatchNorm, simplify, convert opset, fuse LayerNorm/GELU, align scales, XINT8/NPU adaptation, etc.) as a standalone file→file transform — separate from authoring a new pass (quark-create-shapeshifter-pass) and from a full quantization run (quark-onnx-ptq). It exists so graph preprocessing/postprocessing can be run and inspected on its own, and so the driving YAML is a reusable, reviewable artifact.

Inputs

• Required: path to an .onnx model (optionally with an adjacent .onnx_data external-weights file).
• Required: the pass(es) to apply and their config keys. If the user names an effect ("fold batch norm") rather than a pass name, map it to the pass via the catalog in docs/source/quark_shapeshifter_onnx_passes.rst.
• Required: an output .onnx path.
• Optional: whether these are preprocessing (float model) or postprocessing (quantized Q/DQ model) passes — affects which passes are valid and the recommended order.

Outputs: shapeshifter_config.yaml

The primary artifact is the ShapeShifter YAML config that drives the run — reusable and reviewable. Side effect: the transformed model written to the user's output .onnx path.

input_model_path: /path/to/model.onnx
passes:
  onnx_convert_opset_version:
    target_opset_version: 21
  onnx_simplify:
    simplify: true
  onnx_fold_batch_norm:
    fold_batch_norm: true
output_model_path: /path/to/model_out.onnx

No JSON schema — this is a ShapeShifter CLI config (see quark/shapeshifter/utils.py), not a cross-skill contract artifact.

Interaction Flow

1. Intake — confirm the input .onnx path exists, capture the requested transformation(s) and the output path. Map effect words to concrete pass names.
2. Route — verify every requested pass is an ONNX pass (onnx_*) and exists in quark/shapeshifter/passes/. If the user asked to create a pass, hand off to quark-create-shapeshifter-pass; if they asked to quantize, hand off to quark-onnx-ptq.
3. Plan — present the YAML config (pass order + config keys) before writing. Confirm the config key for each pass (many passes are a silent no-op without their enable flag — see Recovery).
4. Confirm — get approval before running the CLI (it writes the output file).
5. Execute or Summarize — write shapeshifter_config.yaml, run the CLI, then verify the output model loads and the transformation took effect. Summarize what changed.

Invoking the CLI

Write the YAML (see Outputs), then:

quark-cli shapeshifter shapeshifter_config.yaml

The CLI loads the model, runs each pass in the order listed (each on the previous pass's output), and writes output_model_path. JSON configs also work. An explicit model config is equivalent to the flat form and clearer when in doubt:

input_model_config:
  model_type: onnx        # discriminator
  input_model_path: /path/to/model.onnx
passes: { ... }
output_model_path: /path/to/model_out.onnx

Pass Selection

Full catalog + config keys: docs/source/quark_shapeshifter_onnx_passes.rst. Common choices:

Intent	Pass	Config key
Constant-fold / clean graph	onnx_simplify	simplify: true
Upgrade opset	onnx_convert_opset_version	target_opset_version: 21
Fold BatchNorm into Conv/Gemm	onnx_fold_batch_norm	fold_batch_norm: true
Fuse LayerNorm / GELU	onnx_fuse_layer_norm / onnx_fuse_gelu	fuse_layer_norm: true / fuse_gelu: true
Layout NCHW→NHWC	onnx_convert_nchw_to_nhwc	convert_nchw_to_nhwc: true
Cross-layer equalization	onnx_cross_layer_equalization	cross_layer_equalization: true
Align Q/DQ scales (quantized)	onnx_align_scale	align_scale: [Concat, MaxPool]
XINT8/NPU adapt (quantized)	onnx_xint8_adjust / onnx_xint8_simulate	xint8_adjust: true / xint8_simulate: true

Preprocessing passes run on the float model (before quantization); postprocessing passes (onnx_align_scale, onnx_adjust_bias_scale, onnx_xint8_*, bfloat16 passes) expect a quantized Q/DQ model. Do not run postprocessing passes on a float model.

Ordering tip: put opset conversion and onnx_simplify first (some fusions require a newer opset and a cleaner graph), then folding/fusion, then per-node initializer passes.

Relationship to quantization

If the goal is to run these passes as part of quantization rather than standalone, they can be driven from the quantizer instead via extra_options={"ShapeShifterYaml": "config.yaml"} with preprocess_passes: / postprocess_passes: groups — that path belongs to quark-onnx-ptq. Use this skill only for the standalone file→file transform.

Recovery

• Pass ran but nothing changed (silent no-op) — most passes require their enable flag; e.g. onnx_convert_clip_to_relu needs convert_clip_to_relu: true. A missing/false flag logs a warning and returns the model unchanged. Re-check the config key against the docs.
• Pass '<name>' is not registered — misspelled pass name or a pytorch_* name. List valid names with ls quark/shapeshifter/passes/; this skill is ONNX-only.
• ValueError: ... is not an ONNX pass — a pytorch_* pass slipped into the config. All passes in one run must be ONNX.
• Postprocessing pass errors on a float model — onnx_align_scale / onnx_xint8_* need a quantized Q/DQ model. Quantize first (quark-onnx-ptq), then apply.
• CLI errors / onnxruntime traceback — hand off to quark-onnx-debug with the exact message.
• Output opset too low for a fusion — onnx_fuse_gelu (opset ≥ 20) and onnx_fuse_layer_norm (opset ≥ 17) auto-skip on lower opsets; add onnx_convert_opset_version earlier in the list.

Notes

• CLI wrapper: quark/experimental/cli/shapeshifter.py (the deprecated onnx-adapter alias still works). Config loader: quark/shapeshifter/utils.py (LoadConfigFromFileOrDict — accepts a dict, JSON string, or YAML/JSON file path). Execution loop + model-type detection: quark/shapeshifter/engine.py.
• Passes run sequentially in listed order; there is no parallelism (deterministic by design).
• For an in-memory (no-disk) transform in Python, the shapeshifter() API takes a model= arg and returns the transformed ModelProto — but this skill is the CLI file→file path.
• Do not silently skip output verification; confirm the model loads and the intended nodes changed.