frontend.py Source File

frontend.py Source File#

Mobilint SDK qb Compiler: frontend.py Source File
Mobilint SDK qb Compiler v1.3
MCS002-EN
 
import warnings
from collections.abc import Callable
from typing import Any, List, Optional, Union
 
import torch
from qbcompiler.compiler.compiler_legacy import LegacyCompiler
from qbcompiler.compiler.compiler_legacy import _quantization_task
from qbcompiler.compiler.execution import (
    execute_mblt_compile_request,
    execute_quantize_request,
)
from qbcompiler.compiler.utils import validate_target_device
from qbcompiler.configs import (
    CompileConfig,
    CalibrationConfig,
    BitConfig,
    ResourceManagementConfig,
    HessianQuantConfig,
    LayerBiasCorrectionConfig,
    ModConfig,
    LlmConfig,
    EquivalentTransformationConfig,
    SearchWeightScaleConfig,
    SaveSampleConfig,
    Uint8InputConfig,
    PreprocessingConfig,
)
from qbcompiler.model_dict.backends import (
    MODEL_DICT_BACKENDS,
    normalize_backend,
)
from qbcompiler.compile_requests import (
    UNSET,
    MxqCompileResolveRequest,
    build_mblt_compile_request,
    build_quantize_request,
)
from qbcompiler.artifact.input import is_existing_mblt_input
from qbcompiler.config_resolver import ConfigManager, save_compile_config
from qbcompiler.config_resolver.deprecations import reject_hf_config
from qbcompiler.reporting.logging import get_logger
from qbcompiler.reporting.progress import emit_progress, progress_context
 
logger = get_logger(__name__)
 
 
 
class Model_Dict(LegacyCompiler):
    """
    @brief Wrapper around the Mobilint compiler to support compilation and inference workflows.
 
    @details Capabilities include:
    - Compilation of models into MXQ artifacts runnable on Mobilint NPUs.
    - Inference using the full-precision high-level compiled model on CPU or GPU.
    - Inference with the quantized model on CPU or GPU.
    """
 
    def __init__(
        self,
        model,
        backend="onnx",
        device="cpu",
        feed_dict=None,
        dynamic_axes=None,
        in_dformats=None,
        yolo_decode_include=False,
        exclude_first_subgraph=False,
        **kwargs,
    ):
        """
        @brief Initialize the Mobilint compiler wrapper.
 
        @param model string or model instance. Model path or in-memory model to compile.
        @param backend string. Framework identifier for the model (for example "onnx"). Defaults to "onnx".
        @param device string. Target device for inference ("cpu" or "gpu"). Defaults to "cpu".
        @param feed_dict dict. Example inputs for shape resolution.
        @param dynamic_axes dict. Marks model axes as dynamic.
        @param in_dformats dict. Describes input data formats.
        @param yolo_decode_include bool. Runs YOLO decode on NPU when @c True.
        @param exclude_first_subgraph bool. Applies only when CPU offloading is enabled: exclude the first subgraph from the final graph if it is unsupported.
        @param kwargs dict. Additional compiler arguments.
        """
 
        super().__init__(
            model=model,
            backend=backend,
            device=device,
            feed_dict=feed_dict,
            in_dformats=in_dformats,
            dynamic_axes=dynamic_axes,
            yolo_decode_include=yolo_decode_include,
            exclude_first_subgraph=exclude_first_subgraph,
            **kwargs,
        )
 
    def compile(
        self,
        save_subgraph_type: int = 0,
        output_subgraph_path="",
        compile_config: CompileConfig = None,
        **kwargs,
    ):
        """
        @brief Compile the wrapped model into an MXQ artifact.
 
        @param save_subgraph_type int. Controls optional MBLT exports: 0 disables; 1 saves graph structure; 2 saves
        structure and weights; 3 splits structure into multiple subgraphs; 4 splits structure and weights.
        @param output_subgraph_path string. Destination for exported .mblt when @p save_subgraph_type is 1–4.
        @param compile_config CompileConfig. Compile configuration object.
        @param kwargs dict. Additional arguments forwarded to the compiler.
 
        """
        save_sample = kwargs.pop("save_sample", None)
        sample_dtype = kwargs.pop("sample_dtype", None)
        if save_sample is not None or sample_dtype is not None:
            warnings.warn(
                "save_sample and sample_dtype are deprecated. Use compile_config with saveSample instead.",
                DeprecationWarning,
                stacklevel=2,
            )
            if compile_config is None:
                compile_config = CompileConfig()
            if not compile_config.save_sample.apply:
                save_sample_kwargs = {}
                if save_sample is not None:
                    save_sample_kwargs["apply"] = save_sample
                if sample_dtype is not None:
                    save_sample_kwargs["dtype"] = sample_dtype
                compile_config = compile_config.with_save_sample(**save_sample_kwargs)
 
        super().compile(
            save_subgraph_type=save_subgraph_type,
            output_subgraph_path=output_subgraph_path,
            compile_config=compile_config,
            **kwargs,
        )
 
 
def mxq_compile(
    model,
    target_device: str,
    calib_data_path: Union[str, List[str]] = UNSET,
    save_subgraph_type: int = 0,
    output_subgraph_path="",
    save_path: Union[str, List[str]] = UNSET,
    backend="onnx",
    # -- ModelDict params --
    feed_dict=None,
    dynamic_axes=None,
    in_dformats=None,
    yolo_decode_include=False,
    exclude_first_subgraph=False,
    # -- CompileConfig-overridable (UNSET = defer to config) --
    device=UNSET,
    inference_scheme=UNSET,
    use_random_calib=UNSET,
    cpu_offload=UNSET,
    optimize_option=UNSET,
    buffer_mode=UNSET,
    input_shape_dict=UNSET,
    force_npu_input_reposition=UNSET,
    force_npu_output_reposition=UNSET,
    image_channels=UNSET,
    split_blocks=UNSET,
    split_parts=UNSET,
    # -- Config objects --
    config_preset: Optional[str] = None,
    compile_config: Optional[CompileConfig] = None,
    resource_management_config: Optional[ResourceManagementConfig] = None,
    calibration_config: Optional[CalibrationConfig] = None,
    bit_config: Optional[BitConfig] = None,
    llm_config: Optional[LlmConfig] = None,
    hessian_quant_config: Optional[HessianQuantConfig] = None,
    mod_config: Optional[ModConfig] = None,
    equivalent_transformation_config: Optional[EquivalentTransformationConfig] = None,
    search_weight_scale_config: Optional[SearchWeightScaleConfig] = None,
    save_sample_config: Optional[SaveSampleConfig] = None,
    uint8_input_config: Optional[Uint8InputConfig] = None,
    preprocessing_config: Optional[PreprocessingConfig] = None,
    layer_bias_correction=UNSET,
    layer_bias_correction_config: Optional[LayerBiasCorrectionConfig] = None,
    model_part: Optional[str] = None,
    model_part_options: Optional[dict] = None,
    config_save_path: Optional[str] = None,
    **kwargs,
):
    """
    @brief Compile a model into a Mobilint eXeCUtable (MXQ) package for execution on Mobilint NPUs.
 
    @details When no explicit value is provided for a parameter marked with @c UNSET, the default
    from CompileConfig is used. This allows a compile_config file or object to supply the value
    without being overridden by function-level defaults.
 
    Configuration is resolved in priority order (highest to lowest):
    1. Explicitly passed function arguments
    2. Individual sub-config objects (calibration_config, llm_config, etc.)
    3. kwargs partial overrides (quantization_method, weight_dtype, etc.)
    4. compile_config (CompileConfig object or JSON/YAML file) or config_preset
    5. CompileConfig field defaults
 
    @param model string or model instance. Model path. When using @c backend="onnx", this should be the path to an ONNX
    model file. When @c backend is "torchscript", provide a TorchScript module; when "torch", provide a standard
    PyTorch model. For @c backend="tf", pass the directory that contains the TensorFlow SavedModel graph and assets. For
    @c backend="tflite", pass the TF Lite model path.
    @param calib_data_path string or list of strings. Path(s) to the calibration dataset. Accepts either a text/json file
    that lists NumPy files or a directory that contains the pre-processed NumPy files.
    @param save_subgraph_type int. Controls optional MBLT subgraph exports: 0 disables exports; 1 saves only the graph
    structure; 2 saves graph structure plus weights; 3 saves the graph structure split into multiple subgraphs; 4 saves
    both structure and weights split into multiple subgraphs. Defaults to 0.
    @param output_subgraph_path string. Destination path for the exported .mblt file when @p save_subgraph_type is 1–4.
    The resulting file can be used for visualization. Defaults to "".
    @param save_path string or list of strings. Output MXQ filename(s). When omitted, defaults to "{model_name}.mxq"
    derived from the model path basename.
    @param backend string. Framework used to generate the Mobilint IR. Case-insensitive, so "ONNX" and "onnx" are
    the same backend. "onnx" and "torch" are parsed by the current parser; "tf" (also spelled "tensorflow"), "tflite" and
    "torchscript" go through the legacy parser. Any other value raises @c ValueError. Defaults to "onnx". When @p model is a path to an already-compiled .mblt file (the
    output of @c mblt_compile()), it is compiled directly with MXQ regardless of the @p backend value,
    and the file is validated beforehand; it must be a runnable
    artifact produced by @c mblt_compile() rather than a @c save_subgraph_type preview export.
    @param target_device string. Target NPU device for parser/compiler configuration (for example "aries-rb"). Required by execution paths that parse or quantize a model.
    @param device string. Compilation and inference device: "cpu" or "gpu". When omitted, uses CompileConfig default.
    @param feed_dict dict. Example input tensors for shape inference and inference validation.
    @param dynamic_axes dict. Marks model axes as dynamic. Keys are input names and values map dimension indices to
    aliases (for example {"input": {2: "seq_len"}}).
    @param in_dformats dict. Describes input tensor data formats.
    @param inference_scheme string. NPU inference scheme. One of "single", "multi", "global", "global4", or
    "global8". When omitted, uses CompileConfig default.
    @param yolo_decode_include bool. Determines whether YOLO decode runs on NPU. Defaults to @c False.
    @param use_random_calib bool. Generates random calibration data to validate model compilability.
    When omitted, uses CompileConfig default.
    @param cpu_offload bool. Enables CPU offloading during NPU inference. When omitted, uses CompileConfig default.
    @param optimize_option int. Compiler optimization strategy selector. When omitted, uses CompileConfig default.
    @param buffer_mode int. Buffer serialization mode: 0 uses a naive buffer, 1 uses an mmap-backed buffer.
    When omitted, uses CompileConfig default.
    @param input_shape_dict dict. Multi-shape compilation specification for STT/TTS models only (e.g., Conformer-CTC,
    MeloTTS). The dynamic axis is defined with respect to each input tensor's shape. During compilation, the same axis
    is varied across all model inputs using the provided values. Currently, only a single entry key ("multi_shape0") is
    supported. Example: {"multi_shape0": {"axis": 2, "values": [100, 200, 300]}}
    @param force_npu_input_reposition bool. Force input reposition operations to run on NPU instead of CPU.
    When omitted, uses CompileConfig default.
    @param force_npu_output_reposition bool. Force output reposition operations to run on NPU instead of CPU.
    When omitted, uses CompileConfig default.
    @param image_channels int. Number of image channels (0 for auto-detect).
    When omitted, uses CompileConfig default.
    @param split_blocks list of int. Multi-MXQ split points by transformer block index.
    Only supported for LLM models. When omitted, uses CompileConfig default.
    @param split_parts int. Evenly split transformer blocks into N MXQ parts.
    Only supported for LLM models. When omitted, uses CompileConfig default.
    @param layer_bias_correction bool. Enables calibration-derived layer bias correction.
    When omitted, uses @p layer_bias_correction_config or the CompileConfig value.
    @param exclude_first_subgraph bool. Applies only when CPU offloading is enabled: exclude the first subgraph from
    the final graph if it is unsupported. Defaults to @c False.
    @param config_preset string. Name of a built-in configuration preset. When provided, loads the preset
    via CompileConfig.from_preset(). Defaults to None (no preset). Available presets:
    - "classification": Image classification models (ResNet, EfficientNet, ViT, etc.)
    - "detection": Object detection models (YOLO, SSD, DETR, etc.)
    - "classification_torchvision": Torchvision classification models with standard preprocessing
    - "yolo_640": YOLO detection models with 640x640 letterbox preprocessing
    - "yolo_1280": YOLO detection models with 1280x1280 letterbox preprocessing
    - "llm": Large Language Models (LLaMA, Qwen, Gemma, etc.)
    - "llm_fast": LLM with faster compilation (less accuracy optimization)
    - "vision_transformer": Vision Transformer models (ViT, DeiT, Swin, etc.)
    - "multimodal": Multimodal models (CLIP, BLIP, LLaVA, etc.)
    @param compile_config CompileConfig or string. CompileConfig object or path to JSON/YAML configuration file
    containing all compilation settings (resourceManagement, calibration, bit, hessianQuant, mod, llm, etc.).
    @param config_save_path string. When provided, the fully resolved configuration - the normalized
    CompileConfig after every layer of the precedence order above has been applied, including all
    sub-configurations - is written to this path before compilation starts. The format follows the path
    suffix: ".yaml"/".yml" produce YAML, anything else produces JSON. Parent directories are created as
    needed. The saved file can be fed back as @p compile_config to reproduce the same compilation.
    Defaults to None (no config file is written).
    @param resource_management_config ResourceManagementConfig. Resource management configuration object.
    @param calibration_config CalibrationConfig. Calibration configuration object.
    @param bit_config BitConfig. Bit configuration object for quantization precision settings.
    @param llm_config LlmConfig. LLM configuration object.
    @param hessian_quant_config HessianQuantConfig. HessianQuant (Hessian-based Quantization) configuration object.
    @param layer_bias_correction_config LayerBiasCorrectionConfig. Calibration-derived layer bias correction settings.
    @param model_part string. Selects a specific part of a torch model to parse ("vision", "language",
    "encoder", ...). Typically used to support models with complex architectures (e.g. Qwen3-VL) by compiling
    one part at a time. Parts a model declares: parser.patcher.parts.available_parts(model).
    A model declaring exactly one part resolves it from None; one declaring several requires a name.
    @param model_part_options dict. Extra arguments for the named part (e.g. {"mel_frames": 100} for Qwen3-ASR audio).
    @param mod_config ModConfig. MOD (Metric-based Optimization and Distillation) configuration object.
    @param equivalent_transformation_config EquivalentTransformationConfig. Configuration for equivalent
    transformations like SmoothQuant.
    @param search_weight_scale_config SearchWeightScaleConfig. Configuration for weight scale search.
    @param save_sample_config SaveSampleConfig. Configuration for sample data generation and saving.
    @param uint8_input_config Uint8InputConfig. Configuration for uint8 input handling.
    @param preprocessing_config PreprocessingConfig. Preprocessing pipeline configuration.
    @param kwargs dict. Additional compiler arguments. Supports partial config overrides such as
    @c quantization_method, @c quantization_mode, @c percentile, @c weight_dtype, @c ram_usage,
    @c max_sequence_length, etc. Also accepts deprecated parameters (@c quantization_config,
    @c advanced_quantization_config, @c input_process_config, @c save_sample, @c sample_dtype)
    which will emit DeprecationWarning.
    @return None.
 
    @par Using configuration
    There are three ways to configure quantization settings:
 
    1. Load all settings from a JSON/YAML config file:
    @code{.py}
    from qbcompiler import mxq_compile
 
    mxq_compile(
        model="path/to/model.onnx",
        target_device="aries-rb",
        calib_data_path="path/to/calib",
        compile_config="path/to/config.json",  # or config.yaml
        device="gpu",
    )
    @endcode
 
    2. Pass individual sub-config objects:
    @code{.py}
    from qbcompiler import mxq_compile
    from qbcompiler.configs import (
        ResourceManagementConfig,
        CalibrationConfig,
        BitConfig,
        HessianQuantConfig,
        ModConfig,
        LlmConfig,
    )
 
    resource_mgmt = ResourceManagementConfig(weight_dtype="float32")
    calib_cfg = CalibrationConfig(method=1, mode=1)
    bit_cfg = BitConfig(...)
    hessian_quant_cfg = HessianQuantConfig(apply=True)
    mod_cfg = ModConfig(apply=False)
    llm_cfg = LlmConfig(apply=True)
 
    mxq_compile(
        model="path/to/model.onnx",
        target_device="aries-rb",
        calib_data_path="path/to/calib",
        resource_management_config=resource_mgmt,
        calibration_config=calib_cfg,
        bit_config=bit_cfg,
        hessian_quant_config=hessian_quant_cfg,
        mod_config=mod_cfg,
        llm_config=llm_cfg,
        device="gpu",
    )
    @endcode
 
    3. Automatically applied partial configuration overrides:
    @code{.py}
    from qbcompiler import mxq_compile
 
    mxq_compile(
        model="path/to/model.onnx",
        target_device="aries-rb",
        calib_data_path="path/to/calib",
        quantization_method=1, # per channel quantization
        quantization_mode=1, # max percentile quantization
        percentile=0.999, # percentile value for max percentile quantization
        quantization_output=0, # per layer quantization for the output layer
        device="gpu",
    )
    @endcode
    Please refer to the mxq_compile function and the quantization configuration section for the meaning of the quantization-related numeric values.
 
 
    @par Compiling models with custom inputs (ONNX/Torch/TensorFlow)
    Provide NumPy inputs whenever the model omits shape information so that qbcompiler can infer unknown dimensions and data
    formats.
 
    @code{.py}
    from qbcompiler import mxq_compile
    import numpy as np
 
    example_input = {
        "input_node_name_1": np.random.randn(1, 3, 224, 224).astype(np.float32),
        "input_node_name_2": np.random.randn(1, 8, 224, 224).astype(np.float32),
        "input_node_name_3": np.random.randn(1, 4, 56, 56).astype(np.float32),
    }
 
    in_dformats = {
        "input_node_name_1": "NCHW",
        "input_node_name_2": "NCHW",
        "input_node_name_3": "NCHW",
    }
 
    onnx_model_path = "path/to/your/model.onnx"
    mxq_compile(
        model=onnx_model_path,
        target_device="aries-rb",
        feed_dict=example_input,
        in_dformats=in_dformats,
        backend="onnx",
        compile_config="path/to/config.json",
    )
    @endcode
    """
    target_device = validate_target_device(target_device)
    reject_hf_config(kwargs)
 
    if is_existing_mblt_input(model):
        if model_part is not None or model_part_options is not None:
            raise ValueError(
                "model_part / model_part_options apply to parsing a live model; "
                f"{model!r} is an already-parsed .mblt. Pass the part when "
                "producing the mblt (mblt_compile), or pass the source model here."
            )
        mxq_compile_from_mblt(
            mblt=model,
            calib_data_path=calib_data_path,
            save_path=save_path,
            backend=backend,
            device=device,
            inference_scheme=inference_scheme,
            use_random_calib=use_random_calib,
            cpu_offload=cpu_offload,
            optimize_option=optimize_option,
            buffer_mode=buffer_mode,
            input_shape_dict=input_shape_dict,
            force_npu_input_reposition=force_npu_input_reposition,
            force_npu_output_reposition=force_npu_output_reposition,
            image_channels=image_channels,
            split_blocks=split_blocks,
            split_parts=split_parts,
            config_preset=config_preset,
            compile_config=compile_config,
            resource_management_config=resource_management_config,
            calibration_config=calibration_config,
            bit_config=bit_config,
            llm_config=llm_config,
            hessian_quant_config=hessian_quant_config,
            mod_config=mod_config,
            equivalent_transformation_config=equivalent_transformation_config,
            search_weight_scale_config=search_weight_scale_config,
            save_sample_config=save_sample_config,
            uint8_input_config=uint8_input_config,
            preprocessing_config=preprocessing_config,
            layer_bias_correction=layer_bias_correction,
            layer_bias_correction_config=layer_bias_correction_config,
            config_save_path=config_save_path,
            target_device=target_device,
            **kwargs,
        )
        return
 
    mxq_compile_from_source(
        model=model,
        calib_data_path=calib_data_path,
        save_subgraph_type=save_subgraph_type,
        output_subgraph_path=output_subgraph_path,
        save_path=save_path,
        backend=backend,
        feed_dict=feed_dict,
        dynamic_axes=dynamic_axes,
        in_dformats=in_dformats,
        yolo_decode_include=yolo_decode_include,
        exclude_first_subgraph=exclude_first_subgraph,
        device=device,
        inference_scheme=inference_scheme,
        use_random_calib=use_random_calib,
        cpu_offload=cpu_offload,
        optimize_option=optimize_option,
        buffer_mode=buffer_mode,
        input_shape_dict=input_shape_dict,
        force_npu_input_reposition=force_npu_input_reposition,
        force_npu_output_reposition=force_npu_output_reposition,
        image_channels=image_channels,
        split_blocks=split_blocks,
        split_parts=split_parts,
        config_preset=config_preset,
        compile_config=compile_config,
        resource_management_config=resource_management_config,
        calibration_config=calibration_config,
        bit_config=bit_config,
        llm_config=llm_config,
        hessian_quant_config=hessian_quant_config,
        mod_config=mod_config,
        equivalent_transformation_config=equivalent_transformation_config,
        search_weight_scale_config=search_weight_scale_config,
        save_sample_config=save_sample_config,
        uint8_input_config=uint8_input_config,
        preprocessing_config=preprocessing_config,
        layer_bias_correction=layer_bias_correction,
        layer_bias_correction_config=layer_bias_correction_config,
        model_part=model_part,
        model_part_options=model_part_options,
        config_save_path=config_save_path,
        target_device=target_device,
        **kwargs,
    )
 
 
def mxq_compile_from_source(
    model,
    target_device: str,
    calib_data_path: Union[str, List[str]] = UNSET,
    save_subgraph_type: int = 0,
    output_subgraph_path="",
    save_path: Union[str, List[str]] = UNSET,
    backend="onnx",
    # -- ModelDict params --
    feed_dict=None,
    dynamic_axes=None,
    in_dformats=None,
    yolo_decode_include=False,
    exclude_first_subgraph=False,
    # -- CompileConfig-overridable (UNSET = defer to config) --
    device=UNSET,
    inference_scheme=UNSET,
    use_random_calib=UNSET,
    cpu_offload=UNSET,
    optimize_option=UNSET,
    buffer_mode=UNSET,
    input_shape_dict=UNSET,
    force_npu_input_reposition=UNSET,
    force_npu_output_reposition=UNSET,
    image_channels=UNSET,
    split_blocks=UNSET,
    split_parts=UNSET,
    # -- Config objects --
    config_preset: Optional[str] = None,
    compile_config: Optional[CompileConfig] = None,
    resource_management_config: Optional[ResourceManagementConfig] = None,
    calibration_config: Optional[CalibrationConfig] = None,
    bit_config: Optional[BitConfig] = None,
    llm_config: Optional[LlmConfig] = None,
    hessian_quant_config: Optional[HessianQuantConfig] = None,
    mod_config: Optional[ModConfig] = None,
    equivalent_transformation_config: Optional[EquivalentTransformationConfig] = None,
    search_weight_scale_config: Optional[SearchWeightScaleConfig] = None,
    save_sample_config: Optional[SaveSampleConfig] = None,
    uint8_input_config: Optional[Uint8InputConfig] = None,
    preprocessing_config: Optional[PreprocessingConfig] = None,
    layer_bias_correction=UNSET,
    layer_bias_correction_config: Optional[LayerBiasCorrectionConfig] = None,
    model_part: Optional[str] = None,
    model_part_options: Optional[dict] = None,
    config_save_path: Optional[str] = None,
    **kwargs,
):
    """
    @brief Compile a raw framework model (ONNX / PyTorch / TensorFlow / TF-Lite) into an MXQ package.
 
    @details This is the raw-model half of @c mxq_compile(): it parses the model into
    Mobilint IR and then quantizes and compiles it in one pass. The parameters, their
    defaults, and the configuration precedence rules are identical to @c mxq_compile() —
    see that function for the full reference and usage examples.
 
    Passing the path of an existing @c .mblt file here raises @c ValueError; use
    @c mxq_compile_from_mblt() for that input instead. @c mxq_compile() routes between
    the two automatically.
 
    @param model string or model instance. Raw model or path to one. Must not be an
    existing @c .mblt file.
    @param target_device string. Target NPU device (for example "aries-rb").
    @return None.
    """
    if is_existing_mblt_input(model):
        raise ValueError(
            "mxq_compile_from_source() does not accept an existing .mblt file. Call "
            "mxq_compile_from_mblt() instead, or mxq_compile() to route automatically."
        )
 
    target_device = validate_target_device(target_device)
    backend = normalize_backend(backend)
    reject_hf_config(kwargs)
 
    if backend in MODEL_DICT_BACKENDS:
        _mxq_compile_pipeline(
            model=model,
            calib_data_path=calib_data_path,
            save_subgraph_type=save_subgraph_type,
            output_subgraph_path=output_subgraph_path,
            save_path=save_path,
            backend=backend,
            target_device=target_device,
            feed_dict=feed_dict,
            dynamic_axes=dynamic_axes,
            in_dformats=in_dformats,
            yolo_decode_include=yolo_decode_include,
            exclude_first_subgraph=exclude_first_subgraph,
            device=device,
            inference_scheme=inference_scheme,
            use_random_calib=use_random_calib,
            cpu_offload=cpu_offload,
            optimize_option=optimize_option,
            buffer_mode=buffer_mode,
            input_shape_dict=input_shape_dict,
            force_npu_input_reposition=force_npu_input_reposition,
            force_npu_output_reposition=force_npu_output_reposition,
            image_channels=image_channels,
            split_blocks=split_blocks,
            split_parts=split_parts,
            layer_bias_correction=layer_bias_correction,
            config_preset=config_preset,
            compile_config=compile_config,
            config_save_path=config_save_path,
            resource_management_config=resource_management_config,
            calibration_config=calibration_config,
            bit_config=bit_config,
            llm_config=llm_config,
            hessian_quant_config=hessian_quant_config,
            layer_bias_correction_config=layer_bias_correction_config,
            mod_config=mod_config,
            equivalent_transformation_config=equivalent_transformation_config,
            search_weight_scale_config=search_weight_scale_config,
            save_sample_config=save_sample_config,
            uint8_input_config=uint8_input_config,
            preprocessing_config=preprocessing_config,
            model_part=model_part,
            model_part_options=model_part_options,
            **kwargs,
        )
        return
 
    if model_part is not None or model_part_options is not None:
        raise ValueError(
            "model_part / model_part_options are only implemented for the "
            f"{', '.join(sorted(MODEL_DICT_BACKENDS))} backends; backend="
            f"{backend!r} parses through the legacy parser, which selects the "
            "submodule to compile in the model-specific script instead."
        )
 
    _mxq_compile_legacy(
        model=model,
        target_device=target_device,
        calib_data_path=calib_data_path,
        save_subgraph_type=save_subgraph_type,
        output_subgraph_path=output_subgraph_path,
        save_path=save_path,
        backend=backend,
        feed_dict=feed_dict,
        dynamic_axes=dynamic_axes,
        in_dformats=in_dformats,
        yolo_decode_include=yolo_decode_include,
        exclude_first_subgraph=exclude_first_subgraph,
        device=device,
        inference_scheme=inference_scheme,
        use_random_calib=use_random_calib,
        cpu_offload=cpu_offload,
        optimize_option=optimize_option,
        buffer_mode=buffer_mode,
        input_shape_dict=input_shape_dict,
        force_npu_input_reposition=force_npu_input_reposition,
        force_npu_output_reposition=force_npu_output_reposition,
        image_channels=image_channels,
        split_blocks=split_blocks,
        split_parts=split_parts,
        config_preset=config_preset,
        compile_config=compile_config,
        resource_management_config=resource_management_config,
        calibration_config=calibration_config,
        bit_config=bit_config,
        llm_config=llm_config,
        hessian_quant_config=hessian_quant_config,
        mod_config=mod_config,
        equivalent_transformation_config=equivalent_transformation_config,
        search_weight_scale_config=search_weight_scale_config,
        save_sample_config=save_sample_config,
        uint8_input_config=uint8_input_config,
        preprocessing_config=preprocessing_config,
        layer_bias_correction=layer_bias_correction,
        layer_bias_correction_config=layer_bias_correction_config,
        config_save_path=config_save_path,
        **kwargs,
    )
 
 
def _mxq_compile_legacy(
    *,
    model,
    target_device: str,
    calib_data_path: Union[str, List[str]] = UNSET,
    save_subgraph_type: int = 0,
    output_subgraph_path="",
    save_path: Union[str, List[str]] = UNSET,
    backend="onnx",
    feed_dict=None,
    dynamic_axes=None,
    in_dformats=None,
    yolo_decode_include=False,
    exclude_first_subgraph=False,
    device=UNSET,
    inference_scheme=UNSET,
    use_random_calib=UNSET,
    cpu_offload=UNSET,
    optimize_option=UNSET,
    buffer_mode=UNSET,
    input_shape_dict=UNSET,
    force_npu_input_reposition=UNSET,
    force_npu_output_reposition=UNSET,
    image_channels=UNSET,
    split_blocks=UNSET,
    split_parts=UNSET,
    config_preset: Optional[str] = None,
    compile_config: Optional[CompileConfig] = None,
    resource_management_config: Optional[ResourceManagementConfig] = None,
    calibration_config: Optional[CalibrationConfig] = None,
    bit_config: Optional[BitConfig] = None,
    llm_config: Optional[LlmConfig] = None,
    hessian_quant_config: Optional[HessianQuantConfig] = None,
    mod_config: Optional[ModConfig] = None,
    equivalent_transformation_config: Optional[EquivalentTransformationConfig] = None,
    search_weight_scale_config: Optional[SearchWeightScaleConfig] = None,
    save_sample_config: Optional[SaveSampleConfig] = None,
    uint8_input_config: Optional[Uint8InputConfig] = None,
    preprocessing_config: Optional[PreprocessingConfig] = None,
    layer_bias_correction=UNSET,
    layer_bias_correction_config: Optional[LayerBiasCorrectionConfig] = None,
    config_save_path: Optional[str] = None,
    **kwargs,
) -> None:
    """Quantize and compile through the legacy ``Model_Dict`` parser.
 
    Reached for the backends the pipeline does not implement -- tf, tflite, hf,
    torchscript and the model-specific misc parsers. Configuration resolution
    goes through the same ``ConfigManager.resolve_mxq_compile`` the pipeline
    path uses, so only the parser differs; the kwargs it hands back are the
    ones the bindings registry did not consume, which is what the parser gets.
 
    Callers route here through :func:`mxq_compile_from_source`, which has
    already validated ``target_device`` and normalized ``backend``.
    """
    resolved = ConfigManager.resolve_mxq_compile(
        MxqCompileResolveRequest(
            model=model,
            calib_data_path=calib_data_path,
            save_path=save_path,
            device=device,
            inference_scheme=inference_scheme,
            use_random_calib=use_random_calib,
            cpu_offload=cpu_offload,
            optimize_option=optimize_option,
            buffer_mode=buffer_mode,
            input_shape_dict=input_shape_dict,
            force_npu_input_reposition=force_npu_input_reposition,
            force_npu_output_reposition=force_npu_output_reposition,
            image_channels=image_channels,
            split_blocks=split_blocks,
            split_parts=split_parts,
            layer_bias_correction=layer_bias_correction,
            config_preset=config_preset,
            compile_config=compile_config,
            resource_management_config=resource_management_config,
            calibration_config=calibration_config,
            bit_config=bit_config,
            llm_config=llm_config,
            hessian_quant_config=hessian_quant_config,
            layer_bias_correction_config=layer_bias_correction_config,
            mod_config=mod_config,
            equivalent_transformation_config=equivalent_transformation_config,
            search_weight_scale_config=search_weight_scale_config,
            save_sample_config=save_sample_config,
            uint8_input_config=uint8_input_config,
            preprocessing_config=preprocessing_config,
            kwargs=kwargs,
        )
    )
    compile_cfg = resolved.compile_config
    # Whatever the bindings registry did not claim belongs to the parser.
    kwargs = resolved.remaining_kwargs
 
    resolved_device = resolved.resolved_device
 
    if config_save_path is not None:
        save_compile_config(compile_cfg, config_save_path)
 
    if is_existing_mblt_input(model):
        _quantization_task(
            model, compile_config=compile_cfg, target_device=target_device
        )
    else:
        model_dict = Model_Dict(
            model=model,
            backend=backend,
            target_device=target_device,
            device=resolved_device,
            feed_dict=feed_dict,
            in_dformats=in_dformats,
            dynamic_axes=dynamic_axes,
            yolo_decode_include=yolo_decode_include,
            exclude_first_subgraph=exclude_first_subgraph,
            **kwargs,
        )
        model_dict.compile(
            save_subgraph_type=save_subgraph_type,
            output_subgraph_path=output_subgraph_path,
            compile_config=compile_cfg,
        )
        torch.cuda.empty_cache()
        del model_dict
 
 
def mxq_compile_from_mblt(
    mblt: str,
    target_device: str,
    calib_data_path: Union[str, List[str]] = UNSET,
    save_path: Union[str, List[str]] = UNSET,
    backend="onnx",
    device=UNSET,
    inference_scheme=UNSET,
    use_random_calib=UNSET,
    cpu_offload=UNSET,
    optimize_option=UNSET,
    buffer_mode=UNSET,
    input_shape_dict=UNSET,
    force_npu_input_reposition=UNSET,
    force_npu_output_reposition=UNSET,
    image_channels=UNSET,
    split_blocks=UNSET,
    split_parts=UNSET,
    config_preset: Optional[str] = None,
    compile_config: Optional[CompileConfig] = None,
    resource_management_config: Optional[ResourceManagementConfig] = None,
    calibration_config: Optional[CalibrationConfig] = None,
    bit_config: Optional[BitConfig] = None,
    llm_config: Optional[LlmConfig] = None,
    hessian_quant_config: Optional[HessianQuantConfig] = None,
    mod_config: Optional[ModConfig] = None,
    equivalent_transformation_config: Optional[EquivalentTransformationConfig] = None,
    search_weight_scale_config: Optional[SearchWeightScaleConfig] = None,
    save_sample_config: Optional[SaveSampleConfig] = None,
    uint8_input_config: Optional[Uint8InputConfig] = None,
    preprocessing_config: Optional[PreprocessingConfig] = None,
    layer_bias_correction=UNSET,
    layer_bias_correction_config: Optional[LayerBiasCorrectionConfig] = None,
    config_save_path: Optional[str] = None,
    **kwargs,
):
    """
    @brief Compile an existing Mobilint IR (@c .mblt) file into an MXQ package.
 
    @details This is the pre-parsed half of @c mxq_compile(): parsing already happened
    (via @c mblt_compile()), so this function only quantizes and compiles. Quantization
    parameters, their defaults, and the configuration precedence rules are identical to
    @c mxq_compile() — see that function for the full reference and usage examples.
 
    Parser-only arguments (@c save_subgraph_type, @c output_subgraph_path, @c feed_dict,
    @c dynamic_axes, @c in_dformats, @c yolo_decode_include, @c exclude_first_subgraph)
    are absent because the graph is already parsed. @c mxq_compile() accepts them for
    backward compatibility and drops them when routing here.
 
    @param mblt string. Path to a runnable @c .mblt produced by @c mblt_compile(). The
    file is validated up front; a @c save_subgraph_type preview export is rejected.
    @param target_device string. Target NPU device (for example "aries-rb").
    @param backend string. Retained for backward compatibility and ignored: the graph is
    already parsed, so no parser backend is selected.
    @return None.
 
    @exception ValueError @p mblt is not an existing @c .mblt file, or it is not a
    runnable artifact for the requested @p cpu_offload setting.
    """
    target_device = validate_target_device(target_device)
    reject_hf_config(kwargs)
 
    if not is_existing_mblt_input(mblt):
        raise ValueError(
            f"mxq_compile_from_mblt() requires an existing .mblt file, got {mblt!r}. "
            "Produce one with mblt_compile() first."
        )
    # The artifact itself is validated in the pipeline planner, where
    # cpu_offload has been resolved against compile_config / config_preset.
 
    _mxq_compile_pipeline(
        model=mblt,
        calib_data_path=calib_data_path,
        save_path=save_path,
        backend=backend,
        device=device,
        inference_scheme=inference_scheme,
        use_random_calib=use_random_calib,
        cpu_offload=cpu_offload,
        optimize_option=optimize_option,
        buffer_mode=buffer_mode,
        input_shape_dict=input_shape_dict,
        force_npu_input_reposition=force_npu_input_reposition,
        force_npu_output_reposition=force_npu_output_reposition,
        image_channels=image_channels,
        split_blocks=split_blocks,
        split_parts=split_parts,
        config_preset=config_preset,
        compile_config=compile_config,
        resource_management_config=resource_management_config,
        calibration_config=calibration_config,
        bit_config=bit_config,
        llm_config=llm_config,
        hessian_quant_config=hessian_quant_config,
        mod_config=mod_config,
        equivalent_transformation_config=equivalent_transformation_config,
        search_weight_scale_config=search_weight_scale_config,
        save_sample_config=save_sample_config,
        uint8_input_config=uint8_input_config,
        preprocessing_config=preprocessing_config,
        layer_bias_correction=layer_bias_correction,
        layer_bias_correction_config=layer_bias_correction_config,
        config_save_path=config_save_path,
        target_device=target_device,
        **kwargs,
    )
 
 
def mblt_compile(
    model: str | Any,
    mblt_save_path: str,
    target_device: str,
    backend="onnx",
    device="cpu",
    feed_dict=None,
    dynamic_axes=None,
    in_dformats=None,
    yolo_decode_include=False,
    cpu_offload=False,
    exclude_first_subgraph=False,
    model_part: Optional[str] = None,
    model_part_options: Optional[dict] = None,
    **kwargs,
):
    """
    @brief Export a model to the Mobilint .mblt format without producing an MXQ package.
 
    @param model string or model instance. Source model or path to compile.
    @param mblt_save_path string. Output path for the .mblt artifact.
    @param backend string. Framework identifier, case-insensitive. "onnx" and "torch" are parsed by the current
    parser; "tf" (also spelled "tensorflow"), "tflite" and "torchscript" go through the legacy parser.
    Any other value raises @c ValueError. Defaults to "onnx".
    @param device string. Compilation device ("cpu" or "gpu"). Defaults to "cpu".
    @param feed_dict dict. Example inputs used for shape inference.
    @param dynamic_axes dict. Declares dynamic axes per input name.
    @param in_dformats dict. Input dataformat metadata.
    @param yolo_decode_include bool. Runs YOLO decode on NPU when True.
    @param cpu_offload bool. Enables CPU offloading for unsupported groups.
    @param exclude_first_subgraph bool. Applies only when CPU offloading is enabled: exclude the first subgraph from the final graph if it is unsupported.
    @param model_part string. Selects a specific part of a torch model to parse ("vision", "language",
    "encoder", ...). Typically used to support models with complex architectures (e.g. Qwen3-VL) by compiling
    one part at a time. Parts a model declares: parser.patcher.parts.available_parts(model).
    A model declaring exactly one part resolves it from None; one declaring several requires a name.
    @param model_part_options dict. Extra arguments for the named part (e.g. {"mel_frames": 100} for Qwen3-ASR audio).
    @param kwargs dict. Additional arguments forwarded to the compiler.
    @return None.
    """
    _mblt_compile_dispatch(
        model=model,
        mblt_save_path=mblt_save_path,
        target_device=target_device,
        backend=backend,
        device=device,
        feed_dict=feed_dict,
        dynamic_axes=dynamic_axes,
        in_dformats=in_dformats,
        yolo_decode_include=yolo_decode_include,
        cpu_offload=cpu_offload,
        exclude_first_subgraph=exclude_first_subgraph,
        model_part=model_part,
        model_part_options=model_part_options,
        **kwargs,
    )
 
 
def _mblt_compile_dispatch(
    model: str | Any,
    mblt_save_path: str,
    target_device: str,
    backend="onnx",
    device=UNSET,
    feed_dict=None,
    dynamic_axes=None,
    in_dformats=None,
    yolo_decode_include=False,
    cpu_offload=UNSET,
    exclude_first_subgraph=False,
    model_part: Optional[str] = None,
    model_part_options: Optional[dict] = None,
    **kwargs,
) -> None:
    """Route a compile-to-mblt call to the pipeline or the legacy parser.
 
    Shared by :func:`mblt_compile` and :func:`mblt_compile_with_callback` so
    both validate ``target_device``, normalize ``backend`` and pick the parser
    the same way. ``device`` / ``cpu_offload`` default to ``UNSET`` here rather
    than to concrete values: that is what lets the callback wrapper forward only
    the flags its caller actually set and leave the rest to the merged
    ``CompileConfig``. :func:`mblt_compile` keeps its own historical
    ``"cpu"`` / ``False`` defaults and passes them explicitly.
    """
    target_device = validate_target_device(target_device)
    backend = normalize_backend(backend)
    reject_hf_config(kwargs)
 
    if backend in MODEL_DICT_BACKENDS:
        _mblt_compile_pipeline(
            model=model,
            mblt_save_path=mblt_save_path,
            backend=backend,
            target_device=target_device,
            device=device,
            feed_dict=feed_dict,
            dynamic_axes=dynamic_axes,
            in_dformats=in_dformats,
            yolo_decode_include=yolo_decode_include,
            cpu_offload=cpu_offload,
            exclude_first_subgraph=exclude_first_subgraph,
            model_part=model_part,
            model_part_options=model_part_options,
            **kwargs,
        )
        return
 
    if model_part is not None or model_part_options is not None:
        raise ValueError(
            "model_part / model_part_options are only implemented for the "
            f"{', '.join(sorted(MODEL_DICT_BACKENDS))} backends; backend="
            f"{backend!r} parses through the legacy parser, which selects the "
            "submodule to compile in the model-specific script instead."
        )
 
    _mblt_compile_legacy(
        model=model,
        mblt_save_path=mblt_save_path,
        target_device=target_device,
        backend=backend,
        device=device,
        feed_dict=feed_dict,
        dynamic_axes=dynamic_axes,
        in_dformats=in_dformats,
        yolo_decode_include=yolo_decode_include,
        cpu_offload=cpu_offload,
        exclude_first_subgraph=exclude_first_subgraph,
        **kwargs,
    )
 
 
def _mblt_compile_legacy(
    *,
    model: str | Any,
    mblt_save_path: str,
    target_device: str,
    backend: str,
    device=UNSET,
    feed_dict=None,
    dynamic_axes=None,
    in_dformats=None,
    yolo_decode_include=False,
    cpu_offload=UNSET,
    exclude_first_subgraph=False,
    **kwargs,
) -> None:
    """Export to ``.mblt`` through the legacy ``Model_Dict`` parser.
 
    Reached for the backends the pipeline does not implement -- tf, tflite, hf,
    torchscript and the model-specific misc parsers. This parser has no
    ``CompileConfig`` fallback for ``device`` / ``cpu_offload``, so an unset
    value takes :func:`mblt_compile`'s documented default.
    """
    device = "cpu" if device is UNSET else device
    cpu_offload = False if cpu_offload is UNSET else cpu_offload
 
    model_dict = Model_Dict(
        model=model,
        backend=backend,
        target_device=target_device,
        device=device,
        feed_dict=feed_dict,
        dynamic_axes=dynamic_axes,
        in_dformats=in_dformats,
        yolo_decode_include=yolo_decode_include,
        exclude_first_subgraph=exclude_first_subgraph,
        **kwargs,
    )
 
    model_dict.mblt_compile(
        model,
        mblt_save_path=mblt_save_path,
        backend=backend,
        cpu_offload=cpu_offload,
        **kwargs,
    )
 
 
def _mxq_compile_pipeline(
    model,
    target_device: str,
    calib_data_path: Union[str, List[str]] = UNSET,
    save_subgraph_type: int = 0,
    output_subgraph_path="",
    save_path: Union[str, List[str]] = UNSET,
    backend="onnx",
    feed_dict=None,
    dynamic_axes=None,
    in_dformats=None,
    yolo_decode_include=False,
    exclude_first_subgraph=False,
    device=UNSET,
    inference_scheme=UNSET,
    use_random_calib=UNSET,
    cpu_offload=UNSET,
    optimize_option=UNSET,
    buffer_mode=UNSET,
    input_shape_dict=UNSET,
    force_npu_input_reposition=UNSET,
    force_npu_output_reposition=UNSET,
    image_channels=UNSET,
    split_blocks=UNSET,
    split_parts=UNSET,
    config_preset: Optional[str] = None,
    compile_config: Optional[CompileConfig | str] = None,
    resource_management_config: Optional[ResourceManagementConfig] = None,
    calibration_config: Optional[CalibrationConfig] = None,
    bit_config: Optional[BitConfig] = None,
    llm_config: Optional[LlmConfig] = None,
    hessian_quant_config: Optional[HessianQuantConfig] = None,
    mod_config: Optional[ModConfig] = None,
    equivalent_transformation_config: Optional[EquivalentTransformationConfig] = None,
    search_weight_scale_config: Optional[SearchWeightScaleConfig] = None,
    save_sample_config: Optional[SaveSampleConfig] = None,
    uint8_input_config: Optional[Uint8InputConfig] = None,
    preprocessing_config: Optional[PreprocessingConfig] = None,
    layer_bias_correction=UNSET,
    layer_bias_correction_config: Optional[LayerBiasCorrectionConfig] = None,
    model_part: Optional[str] = None,
    model_part_options: Optional[dict] = None,
    config_save_path: Optional[str] = None,
    **kwargs,
) -> None:
    """Quantize and compile through the ConfigManager-resolved pipeline.
 
    Serves the backends in ``MODEL_DICT_BACKENDS``; the callers
    (:func:`mxq_compile_from_source`, :func:`mxq_compile_from_mblt`) have
    already validated ``target_device`` and normalized ``backend``.
    """
    request = build_quantize_request(
        model=model,
        save_path=save_path,
        backend=backend,
        target_device=target_device,
        feed_dict=feed_dict,
        dynamic_axes=dynamic_axes,
        in_dformats=in_dformats,
        yolo_decode_include=yolo_decode_include,
        exclude_first_subgraph=exclude_first_subgraph,
        save_subgraph_type=save_subgraph_type,
        output_subgraph_path=output_subgraph_path,
        calib_data_path=calib_data_path,
        device=device,
        inference_scheme=inference_scheme,
        use_random_calib=use_random_calib,
        cpu_offload=cpu_offload,
        optimize_option=optimize_option,
        buffer_mode=buffer_mode,
        input_shape_dict=input_shape_dict,
        force_npu_input_reposition=force_npu_input_reposition,
        force_npu_output_reposition=force_npu_output_reposition,
        image_channels=image_channels,
        split_blocks=split_blocks,
        split_parts=split_parts,
        layer_bias_correction=layer_bias_correction,
        config_preset=config_preset,
        compile_config=compile_config,
        resource_management_config=resource_management_config,
        calibration_config=calibration_config,
        bit_config=bit_config,
        llm_config=llm_config,
        hessian_quant_config=hessian_quant_config,
        layer_bias_correction_config=layer_bias_correction_config,
        mod_config=mod_config,
        equivalent_transformation_config=equivalent_transformation_config,
        search_weight_scale_config=search_weight_scale_config,
        save_sample_config=save_sample_config,
        uint8_input_config=uint8_input_config,
        preprocessing_config=preprocessing_config,
        model_part=model_part,
        model_part_options=model_part_options,
        **kwargs,
    )
    resolved_request = ConfigManager.resolve_quantize_request(request)
    if config_save_path is not None:
        # Written before the (potentially hours-long) compile starts, so the
        # record survives a failure. Two fields still hold their defaults here
        # because ``MxqCompileStage`` fills them at execution time:
        # ``model_paths`` -- which for a raw-model input is a throwaway path in
        # the pipeline tempdir -- and ``runtime_options.version``.
        save_compile_config(resolved_request.compile_config, config_save_path)
    execute_quantize_request(resolved_request)
 
 
def _mblt_compile_pipeline(
    model: str | object,
    target_device: str,
    mblt_save_path: str,
    backend="onnx",
    device: object = UNSET,
    feed_dict=None,
    dynamic_axes=None,
    in_dformats=None,
    yolo_decode_include=False,
    cpu_offload: object = UNSET,
    exclude_first_subgraph=False,
    model_part: Optional[str] = None,
    model_part_options: Optional[dict] = None,
    config_preset: Optional[str] = None,
    compile_config: Optional[CompileConfig | str] = None,
    compilation_mode: Optional[str] = None,
    **kwargs,
) -> None:
    """Export to ``.mblt`` through the ConfigManager-resolved pipeline.
 
    ``compilation_mode`` is an internal knob: one of
    ``{"release", "dev", "debug"}`` or ``None`` (default) to defer to the
    ``MBLT_APP_ENV`` environment variable. When set it overrides the env
    and drives the parser's ``inference_validation`` / ``device_alloc``
    / ``log_level`` cascade — the same preset as ``MBLT_APP_ENV``. Not
    surfaced in the CLI on purpose; intended for in-process scripts and
    tests that want scoped dev-mode validation without mutating
    process-wide environment.
    """
    request = build_mblt_compile_request(
        model=model,
        mblt_save_path=mblt_save_path,
        backend=backend,
        target_device=target_device,
        device=device,
        feed_dict=feed_dict,
        dynamic_axes=dynamic_axes,
        in_dformats=in_dformats,
        yolo_decode_include=yolo_decode_include,
        cpu_offload=cpu_offload,
        exclude_first_subgraph=exclude_first_subgraph,
        model_part=model_part,
        model_part_options=model_part_options,
        config_preset=config_preset,
        compile_config=compile_config,
        compilation_mode=compilation_mode,
        **kwargs,
    )
    resolved_request = ConfigManager.resolve_mblt_compile_request(request)
    execute_mblt_compile_request(resolved_request)
 
 
def mblt_compile_with_callback(
    model: str,
    mblt_save_path: str,
    target_device: str,
    backend: str = "onnx",
    device: Optional[str] = None,
    cpu_offload: Optional[bool] = None,
    config_preset: Optional[str] = None,
    compile_config: Optional[CompileConfig | str] = None,
    compilation_mode: Optional[str] = None,
    *,
    progress_callback: Callable[[int, str], None],
) -> None:
    """Compile-to-mblt entry point with progress callbacks.
 
    Only forwards explicitly-set values so the ``UNSET`` defaults (and the
    merged ``CompileConfig`` behind them) apply when the caller omits a flag --
    which is why this goes through ``_mblt_compile_dispatch`` rather than
    :func:`mblt_compile`, whose own ``device`` / ``cpu_offload`` defaults would
    override the config. ``target_device`` is required and has no config
    fallback — callers (e.g. the CLI) validate it via
    ``validate_target_device`` before invoking (QC-228).
    """
    call_kwargs: dict[str, Any] = {
        "model": model,
        "mblt_save_path": mblt_save_path,
        "backend": backend,
        "target_device": target_device,
    }
    if device is not None:
        call_kwargs["device"] = device
    if cpu_offload is not None:
        call_kwargs["cpu_offload"] = cpu_offload
    if config_preset is not None:
        call_kwargs["config_preset"] = config_preset
    if compile_config is not None:
        call_kwargs["compile_config"] = compile_config
    if compilation_mode is not None:
        call_kwargs["compilation_mode"] = compilation_mode
 
    with progress_context(progress_callback):
        emit_progress(0, "Initializing compiler")
        _mblt_compile_dispatch(**call_kwargs)
        emit_progress(100, "Complete")
 
 
def mxq_compile_with_callback(
    model: str,
    target_device: str,
    save_path: str,
    backend: str = "onnx",
    device: Optional[str] = None,
    calib_data_path: Optional[Union[str, List[str]]] = None,
    use_random_calib: Optional[bool] = None,
    config_preset: Optional[str] = None,
    compile_config: Optional[CompileConfig | str] = None,
    config_save_path: Optional[str] = None,
    *,
    progress_callback: Callable[[int, str], None],
) -> None:
    """Compile/quantize entry point with progress callbacks.
 
    ``target_device`` is required and has no config fallback — callers
    (e.g. the CLI) validate it via ``validate_target_device`` before
    invoking, and the wrapper forwards it unconditionally (QC-228).
 
    Like :func:`mblt_compile_with_callback`, only explicitly-set values are
    forwarded, so :func:`mxq_compile`'s ``UNSET`` defaults (and the merged
    ``CompileConfig`` behind them) still apply to whatever the caller omits.
    ``config_save_path`` passes straight through, and the resolved config is
    written there before compilation starts; this is what backs the CLI's
    ``--config-save-path`` on ``quantize`` / ``compile``.
    """
    call_kwargs: dict[str, object] = {
        "model": model,
        "save_path": save_path,
        "backend": backend,
        "target_device": target_device,
    }
    if device is not None:
        call_kwargs["device"] = device
    if calib_data_path is not None:
        call_kwargs["calib_data_path"] = calib_data_path
    if use_random_calib is not None:
        call_kwargs["use_random_calib"] = use_random_calib
    if config_preset is not None:
        call_kwargs["config_preset"] = config_preset
    if compile_config is not None:
        call_kwargs["compile_config"] = compile_config
    if config_save_path is not None:
        call_kwargs["config_save_path"] = config_save_path
 
    with progress_context(progress_callback):
        emit_progress(0, "Initializing compiler")
        mxq_compile(**call_kwargs)
        emit_progress(100, "Complete")
 
 