Quark Onnx Quant Plan

Decision Table (MUST show to user)

ALWAYS present this table and WAIT for confirmation before finalizing. Fill the "Value" column from the user's request, the model analysis, and the deployment-target gates above.

After showing the table, ask: "Confirm this plan? Any changes?"

Do NOT proceed until the user confirms.

Per-Layer Overrides

For fine-grained control, individual layers can override the global config via QLayerConfig (see examples/onnx/yolo_quantization/quantize_yolo.py):

from quark.onnx import QConfig, QLayerConfig, XInt8Spec, CLEConfig

config = QConfig(
    global_config=QLayerConfig(activation=XInt8Spec(), weight=XInt8Spec()),
    algo_config=[CLEConfig()],
    EnableNPUCnn=True,
    exclude=[
        # YOLOX-style: keep a specific subgraph in float
        (["/_head/_modules_list.14/Transpose"], ["/_head/_modules_list.14/Concat_9"]),
    ],
)

Record any per-layer overrides under onnx_specific.subgraphs_to_exclude (list of (start_nodes, end_nodes) tuples) or onnx_specific.nodes_to_exclude (flat name list).

Rules

• Keep scope to plan creation only. Do not generate scripts, do not run quantization, do not export. Those are separate skills.
• Require a model analysis first. Without architecture, op histogram, opsets, and the already-QDQ flags, you cannot make informed preset / op-type recommendations. If model_analysis.json is missing, route back to quark-onnx-model-intake.
• Honor hard deployment-target constraints. NPU CNN ⇒ XINT8 family + PowerOfTwo* calibration + NHWC. NPU Transformer ⇒ INT8_TRANSFORMER_* / INT16_TRANSFORMER_*. Reject conflicting preset requests with a clear explanation.
• Custom-op preconditions for block formats. Any preset in {BFP16*, MX*, MXFP*, MXINT8*, BF16_*BFP*, BF16_*MXINT8*} requires the Quark custom-ops library to have compiled. If onnx_install_result.json shows the compile failed, suppress these presets from recommendations and emit a risk pointing back to quark-onnx-install.
• External-data flag tracks model size. If model_analysis.json.model.estimated_size_gb > 2, set onnx_specific.use_external_data_format = true automatically. Otherwise default false.
• Always present the decision table before finalizing. The user must explicitly confirm.
• Record risks. If the user picks a risky combination (e.g. XINT8 without PoF2 calibration, MXFP4 on a model that hasn't been validated with AutoMixprecision), keep the user's choice but record the risk in the plan.
• Do not duplicate fields between model_analysis.json and quant_plan.json. The plan references the analysis via analysis_ref.

Interaction Flow

1. Check prerequisites: Is model_analysis.json available? If not, route to quark-onnx-model-intake first. Is onnx_install_result.json available? If a block-format preset is on the table, require it.
2. Confirm deployment target: From session_context.json.constraints.deployment_target or ask. Apply the hard gates from the table above.
3. Narrow presets: Start from model_analysis.json.quantization_targets.onnx_specific.preset_candidates, filter by deployment target and custom-op availability, present the top 1–3 with rationale.
4. Pick calibration method: Default per target (MinMax for general; PowerOfTwo_MinMSE for NPU CNN; Percentile for outlier-heavy transformers; consider LayerWisePercentile when accuracy is critical). Decide data_size and batch_size.
5. Pick algorithms: Default per architecture and preset (CLE for INT8 CNN; AdaRound→AdaQuant for accuracy-tight CNN; BiasCorrection as a cheap post-hoc fixup). At most two algorithms unless justified.
6. Set extra options: From the table of common knobs, only set what's needed; document each.
7. Present the decision table: Show defaults, explain the tradeoffs, let the user adjust.
8. Confirm: Always required. Show the final plan summary before writing.
9. Emit: Write quant_plan.json. Surface any new constraints back to quark-onnx-router so they land in session_context.json.

Recovery

• If model_analysis.json shows has_qdq_already=true or has_quark_custom_ops=true — do not produce a plan. Route back to quark-onnx-model-intake with a recommendation to remove existing QDQ first (quark.onnx.tools.remove_qdq).
• If the user picks a preset that conflicts with their deployment target — explain why it won't work (e.g. "A8W8 uses non-PoF2 scales which the AMD NPU CNN runtime rejects"), suggest the closest viable alternative (e.g. XINT8), and respect the user's choice if they insist — recording the risk.
• If model_analysis.json shows architecture unknown — produce a draft plan with requires_confirmation: true, list the op histogram, and ask the user which of CNN / transformer / hybrid path to follow.
• If calibration data is unavailable — explain that PTQ requires representative inputs for accurate scale estimation, and ask the user to supply a small calibration set (≥ a few dozen samples) before the plan can be finalized.
• If a block-format preset is requested but custom-ops compile is unverified — hand off to quark-onnx-install to verify, then resume.
• If the user picks an unusual combination (e.g. CLE + transformer, three or more algorithms) — explain why it's atypical and suggest the standard recipe, but respect the user's choice with a recorded risk.