coreml-diffusion 0.1.0__tar.gz → 0.1.1__tar.gz

coreml_diffusion-0.1.1/.github/workflows/tier2.yml

@@ -0,0 +1,74 @@
+name: Tier 2 — M2 / ANE (self-hosted)
+
+on:
+  pull_request:
+    # `labeled` fires when run-m2 is first added; `synchronize`/`reopened`
+    # re-run on every subsequent push while the label is present, so the result
+    # tracks the PR head instead of going stale. The `if` below keeps the run
+    # gated on the run-m2 label for all pull_request events.
+    types: [labeled, synchronize, reopened]
+  schedule:
+    # Nightly at 04:00 UTC (~05/06 in PL). Keeps the ANE path honest without
+    # burning the runner on every PR.
+    - cron: "0 4 * * *"
+  workflow_dispatch:
+
+jobs:
+  m2:
+    if: |
+      github.event_name == 'schedule' ||
+      github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'pull_request' &&
+       contains(github.event.pull_request.labels.*.name, 'run-m2'))
+    # Self-hosted Apple Silicon runner (shared with ComfyUI-CoreMLSuite's Tier 2,
+    # same `coreml` label). The runner's environment MUST export
+    # COREML_DIFFUSION_TEST_CKPT: an absolute path to a cached single-file SD1.5
+    # checkpoint. The gate converts it fresh and runs the comfy-free inference
+    # golden — no ComfyUI involved.
+    runs-on: [self-hosted, macOS, ARM64, coreml]
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: uv sync
+        run: uv sync
+
+      - name: Check cached checkpoint
+        # The runner's .env must export COREML_DIFFUSION_TEST_CKPT — an absolute
+        # path to a cached single-file SD1.5 checkpoint.
+        run: |
+          set -euo pipefail
+          if [ -z "${COREML_DIFFUSION_TEST_CKPT:-}" ]; then
+            echo "COREML_DIFFUSION_TEST_CKPT unset — add it to the runner's .env."
+            exit 1
+          fi
+          test -f "$COREML_DIFFUSION_TEST_CKPT" || {
+            echo "checkpoint not found: $COREML_DIFFUSION_TEST_CKPT"; exit 1; }
+          echo "Tier 2: checkpoint \`$COREML_DIFFUSION_TEST_CKPT\`" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Convert UNet fresh (batch=2 for CFG)
+        # Convert on every run. The .mlpackage cache key is conversion
+        # *parameters* only, not the conversion code or toolchain — a stale model
+        # would let a conversion regression pass. batch=2 because guided CFG feeds
+        # uncond+cond in a single forward pass, and ANE input shapes are fixed at
+        # convert time.
+        run: |
+          set -euo pipefail
+          MLPKG="$RUNNER_TEMP/sd15_b2.mlpackage"
+          rm -rf "$MLPKG"
+          uv run coreml-diffusion convert \
+            --ckpt "$COREML_DIFFUSION_TEST_CKPT" \
+            --model-version SD15 \
+            --out "$MLPKG" \
+            --batch-size 2 --height 512 --width 512 --attn-impl SPLIT_EINSUM
+          echo "COREML_DIFFUSION_TEST_MLPACKAGE=$MLPKG" >> "$GITHUB_ENV"
+
+      - name: Run Tier 2 (m2 marker)
+        # Builds a stock diffusers pipeline around the converted UNet and asserts
+        # the generated image against the committed golden (exact match, else
+        # PSNR >= GOLDEN_PSNR_MIN_DB). VAE/text encoder on torch, UNet on the ANE.
+        run: uv run --no-sync pytest -m m2 tests/ -v

{coreml_diffusion-0.1.0 → coreml_diffusion-0.1.1}/.gitignore

@@ -6,3 +6,4 @@ __pycache__/
 dist/
 build/
 *.egg-info/
+CLAUDE.md

coreml_diffusion-0.1.1/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: coreml-diffusion
+Version: 0.1.1
+Summary: Convert diffusion-model checkpoints (SD1.5/SDXL) to Core ML for Apple Neural Engine — framework-free, ComfyUI-independent.
+Project-URL: Homepage, https://github.com/aszc-dev/coreml-diffusion
+Project-URL: Repository, https://github.com/aszc-dev/coreml-diffusion
+Project-URL: Issues, https://github.com/aszc-dev/coreml-diffusion/issues
+Author-email: Adrian Szczepański <hi@aszc.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ane,apple-neural-engine,comfyui,core-ml,coreml,diffusers,diffusion,sdxl,stable-diffusion
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: <3.13,>=3.12
+Requires-Dist: coremltools<10,>=9
+Requires-Dist: diffusers>=0.30
+Requires-Dist: numpy<3,>=2
+Requires-Dist: omegaconf>=2.3
+Requires-Dist: peft>=0.13
+Requires-Dist: torch>=2.7
+Requires-Dist: transformers<5,>=4.44
+Description-Content-Type: text/markdown
+
+# coreml-diffusion
+
+Convert diffusion-model checkpoints into Core ML `.mlpackage` artifacts for the
+Apple Neural Engine (ANE) — framework-free and standalone.
+
+`coreml-diffusion` takes a single-file Stable Diffusion checkpoint and produces a
+Core ML UNet you can run on-device (macOS/iOS) via Core ML, in a Python pipeline,
+or load into any host that consumes the artifact.
+
+## What this is
+
+A standalone toolkit and knowledge base for running diffusion models on the Apple
+Neural Engine via Core ML. The niche is **diffusion on the ANE**: low-power,
+GPU-free, embeddable in a Swift/iOS app. ANE is the differentiator — this is about
+feasibility and power efficiency for SD1.5/SDXL on ANE, not a raw-throughput claim
+against desktop GPUs.
+
+The scope is diffusion architectures generally, not Stable Diffusion specifically.
+The project aims to gather, in one place: the conversion path, a reproducible
+benchmarking suite for objective comparison, a per-model catalogue documenting the
+quirks of each architecture on the ANE, and the sources behind it all.
+
+Supported today: SD1.5 and SDXL (verified). SDXL refiner and LCM convert but are
+not yet golden-verified (experimental).
+
+## Install
+
+```sh
+uv pip install coreml-diffusion          # from PyPI
+uv pip install -e .                       # from a checkout
+```
+
+Requires Python 3.12 and (for conversion) `coremltools` 9 — conversion runs on
+macOS; the package imports and its CLI parse on any platform.
+
+## CLI
+
+```sh
+coreml-diffusion convert \
+    --ckpt path/to/model.safetensors \
+    --model-version SD15 \
+    --out unet.mlpackage \
+    --height 512 --width 512 \
+    --attn-impl SPLIT_EINSUM \
+    --quantize none
+```
+
+Options: `--batch-size`, `--controlnet`, `--lora PATH[:STRENGTH]` (repeatable),
+`--config` (original-config YAML). `--quantize {none,8,6,4}` applies k-means
+weight palettization. Run `coreml-diffusion convert --help` for the full list.
+
+The output `.mlpackage` is the deliverable: load it natively in Swift/Core ML, run
+it through the Python inference pipeline below, or hand it to any consuming host.
+
+### Model sources
+
+Register directories so `--ckpt` accepts a bare name instead of a full path:
+
+```sh
+coreml-diffusion sources add comfy /path/to/ComfyUI/models   # --kind comfy|flat
+coreml-diffusion sources list                                # sources + checkpoints
+coreml-diffusion convert --ckpt v1-5-pruned-emaonly --model-version SD15 --out unet.mlpackage
+```
+
+Sources are recorded in `~/.config/coreml-diffusion/sources.toml`. `comfy` knows the
+`models/{checkpoints,loras,vae,...}` layout; `flat` is a plain checkpoint directory.
+
+## Library
+
+```python
+import coreml_diffusion
+from coreml_diffusion import ModelVersion
+
+coreml_diffusion.convert(
+    "model.safetensors", ModelVersion.SD15, "unet.mlpackage",
+    height=512, width=512, attn_impl="SPLIT_EINSUM",
+)
+```
+
+## Inference (in progress)
+
+A framework-free inference path lets a converted `.mlpackage` generate images with
+no host framework: a `diffusers` pipeline runs the stock VAE / text encoder on
+torch while the UNet is served from Core ML on the ANE. This doubles as the
+package's own regression anchor — the Tier 2 (`m2`) golden image, asserted on an
+Apple Silicon runner — and as the reference for the on-device write-up. See
+`tests/m2/`.
+
+## Discovery API
+
+`list_model_versions`, `list_attention_impls`, `list_quant_modes`, and
+`CONTRACT_VERSION` report what this build can convert. The identifiers are an
+additive-only contract: removing or renaming one is a major version bump, because
+downstream consumers reference these strings verbatim.
+
+## ComfyUI
+
+[ComfyUI-CoreMLSuite](https://github.com/aszc-dev/ComfyUI-CoreMLSuite) consumes
+this package for its conversion path and drives its node dropdowns from the
+discovery API above — installing a newer `coreml-diffusion` surfaces new
+conversion types in the node with no Suite change. The Suite is one consumer;
+this package neither depends on nor requires ComfyUI.
+
+## License
+
+MIT

coreml_diffusion-0.1.1/README.md

@@ -0,0 +1,106 @@
+# coreml-diffusion
+
+Convert diffusion-model checkpoints into Core ML `.mlpackage` artifacts for the
+Apple Neural Engine (ANE) — framework-free and standalone.
+
+`coreml-diffusion` takes a single-file Stable Diffusion checkpoint and produces a
+Core ML UNet you can run on-device (macOS/iOS) via Core ML, in a Python pipeline,
+or load into any host that consumes the artifact.
+
+## What this is
+
+A standalone toolkit and knowledge base for running diffusion models on the Apple
+Neural Engine via Core ML. The niche is **diffusion on the ANE**: low-power,
+GPU-free, embeddable in a Swift/iOS app. ANE is the differentiator — this is about
+feasibility and power efficiency for SD1.5/SDXL on ANE, not a raw-throughput claim
+against desktop GPUs.
+
+The scope is diffusion architectures generally, not Stable Diffusion specifically.
+The project aims to gather, in one place: the conversion path, a reproducible
+benchmarking suite for objective comparison, a per-model catalogue documenting the
+quirks of each architecture on the ANE, and the sources behind it all.
+
+Supported today: SD1.5 and SDXL (verified). SDXL refiner and LCM convert but are
+not yet golden-verified (experimental).
+
+## Install
+
+```sh
+uv pip install coreml-diffusion          # from PyPI
+uv pip install -e .                       # from a checkout
+```
+
+Requires Python 3.12 and (for conversion) `coremltools` 9 — conversion runs on
+macOS; the package imports and its CLI parse on any platform.
+
+## CLI
+
+```sh
+coreml-diffusion convert \
+    --ckpt path/to/model.safetensors \
+    --model-version SD15 \
+    --out unet.mlpackage \
+    --height 512 --width 512 \
+    --attn-impl SPLIT_EINSUM \
+    --quantize none
+```
+
+Options: `--batch-size`, `--controlnet`, `--lora PATH[:STRENGTH]` (repeatable),
+`--config` (original-config YAML). `--quantize {none,8,6,4}` applies k-means
+weight palettization. Run `coreml-diffusion convert --help` for the full list.
+
+The output `.mlpackage` is the deliverable: load it natively in Swift/Core ML, run
+it through the Python inference pipeline below, or hand it to any consuming host.
+
+### Model sources
+
+Register directories so `--ckpt` accepts a bare name instead of a full path:
+
+```sh
+coreml-diffusion sources add comfy /path/to/ComfyUI/models   # --kind comfy|flat
+coreml-diffusion sources list                                # sources + checkpoints
+coreml-diffusion convert --ckpt v1-5-pruned-emaonly --model-version SD15 --out unet.mlpackage
+```
+
+Sources are recorded in `~/.config/coreml-diffusion/sources.toml`. `comfy` knows the
+`models/{checkpoints,loras,vae,...}` layout; `flat` is a plain checkpoint directory.
+
+## Library
+
+```python
+import coreml_diffusion
+from coreml_diffusion import ModelVersion
+
+coreml_diffusion.convert(
+    "model.safetensors", ModelVersion.SD15, "unet.mlpackage",
+    height=512, width=512, attn_impl="SPLIT_EINSUM",
+)
+```
+
+## Inference (in progress)
+
+A framework-free inference path lets a converted `.mlpackage` generate images with
+no host framework: a `diffusers` pipeline runs the stock VAE / text encoder on
+torch while the UNet is served from Core ML on the ANE. This doubles as the
+package's own regression anchor — the Tier 2 (`m2`) golden image, asserted on an
+Apple Silicon runner — and as the reference for the on-device write-up. See
+`tests/m2/`.
+
+## Discovery API
+
+`list_model_versions`, `list_attention_impls`, `list_quant_modes`, and
+`CONTRACT_VERSION` report what this build can convert. The identifiers are an
+additive-only contract: removing or renaming one is a major version bump, because
+downstream consumers reference these strings verbatim.
+
+## ComfyUI
+
+[ComfyUI-CoreMLSuite](https://github.com/aszc-dev/ComfyUI-CoreMLSuite) consumes
+this package for its conversion path and drives its node dropdowns from the
+discovery API above — installing a newer `coreml-diffusion` surfaces new
+conversion types in the node with no Suite change. The Suite is one consumer;
+this package neither depends on nor requires ComfyUI.
+
+## License
+
+MIT

{coreml_diffusion-0.1.0 → coreml_diffusion-0.1.1}/coreml_diffusion/__init__.py

@@ -40,6 +40,8 @@ __all__ = [
     "compose_out_name",
     "lora_names_from_params",
     "convert",
+    "build_pipeline",
+    "CoreMLUNet",
 ]
 
 
@@ -105,4 +107,8 @@ def __getattr__(name):
         from coreml_diffusion.convert import convert as _convert
 
         return _convert
+    if name in ("build_pipeline", "CoreMLUNet"):
+        from coreml_diffusion import inference
+
+        return getattr(inference, name)
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{coreml_diffusion-0.1.0 → coreml_diffusion-0.1.1}/coreml_diffusion/cli.py

@@ -14,6 +14,7 @@ Example:
 import argparse
 
 import coreml_diffusion
+from coreml_diffusion import sources
 
 
 def _parse_lora(spec):
@@ -31,8 +32,9 @@ def _parse_lora(spec):
 def _convert_cmd(args):
     sample_size = (args.height // 8, args.width // 8)
     lora_weights = [_parse_lora(spec) for spec in (args.lora or [])]
+    ckpt = sources.resolve_checkpoint(args.ckpt, args.source)
     coreml_diffusion.convert(
-        args.ckpt,
+        ckpt,
         coreml_diffusion.ModelVersion[args.model_version],
         args.out,
         batch_size=args.batch_size,
@@ -45,6 +47,31 @@ def _convert_cmd(args):
     )
 
 
+def _sources_add_cmd(args):
+    entry = sources.add_source(args.name, args.path, args.kind)
+    print(f"Added source {args.name!r} ({entry['kind']}): {entry['path']}")
+
+
+def _sources_list_cmd(args):
+    registered = sources.load_sources()
+    if not registered:
+        print(f"No sources registered. Config: {sources.config_path()}")
+        return
+    for name, entry in sorted(registered.items()):
+        ckpts = sources.iter_checkpoints(entry)
+        print(f"{name} ({entry['kind']}): {entry['path']}")
+        if ckpts:
+            for stem in ckpts:
+                print(f"  - {stem}")
+        else:
+            print("  (no checkpoints found)")
+
+
+def _sources_remove_cmd(args):
+    sources.remove_source(args.name)
+    print(f"Removed source {args.name!r}")
+
+
 def build_parser():
     parser = argparse.ArgumentParser(
         prog="coreml-diffusion",
@@ -54,7 +81,15 @@ def build_parser():
 
     conv = sub.add_parser("convert", help="Convert a checkpoint's UNet to a .mlpackage")
     conv.add_argument(
-        "--ckpt", required=True, help="Path to the source .safetensors checkpoint"
+        "--ckpt",
+        required=True,
+        help="Checkpoint path, or a name resolved against registered sources "
+        "(see 'coreml-diffusion sources')",
+    )
+    conv.add_argument(
+        "--source",
+        default=None,
+        help="Restrict --ckpt name resolution to this registered source",
     )
     conv.add_argument(
         "--model-version",
@@ -101,6 +136,28 @@ def build_parser():
         help="K-means weight palettization bits (default none = unquantized)",
     )
     conv.set_defaults(func=_convert_cmd)
+
+    src = sub.add_parser("sources", help="Manage model source directories")
+    src_sub = src.add_subparsers(dest="sources_command", required=True)
+
+    s_add = src_sub.add_parser("add", help="Register (or overwrite) a model source")
+    s_add.add_argument("name", help="Short name for the source, e.g. 'comfy'")
+    s_add.add_argument("path", help="Base directory of the source")
+    s_add.add_argument(
+        "--kind",
+        choices=sources.SOURCE_KINDS,
+        default="comfy",
+        help="Directory layout (default comfy: models/{checkpoints,loras,vae,...})",
+    )
+    s_add.set_defaults(func=_sources_add_cmd)
+
+    s_list = src_sub.add_parser("list", help="List sources and their checkpoints")
+    s_list.set_defaults(func=_sources_list_cmd)
+
+    s_rm = src_sub.add_parser("remove", help="Unregister a source")
+    s_rm.add_argument("name", help="Source name to remove")
+    s_rm.set_defaults(func=_sources_remove_cmd)
+
     return parser
 
 

coreml_diffusion-0.1.1/coreml_diffusion/inference.py

@@ -0,0 +1,176 @@
+"""Framework-free inference for a converted Core ML UNet.
+
+Runs a `.mlpackage` UNet inside a stock ``diffusers`` pipeline with NO ComfyUI:
+the VAE and text encoder run on torch (CPU/MPS) while the UNet is served from
+Core ML on the ANE. This is the package-side counterpart to ``convert`` — it
+proves a converted artifact generates an image end-to-end, and provides the
+Tier 2 (``m2``) golden anchor (``tests/m2/``).
+
+``CoreMLUNet`` is the inverse of ``conversion.unet.CoreMLUNetWrapper``: the
+wrapper adapts diffusers UNet *inputs* into the flat Core ML tensor contract at
+convert time; this adapter unpacks a diffusers call back into that same flat
+contract at run time, feeds it to ``coremltools``, and re-wraps the output as a
+diffusers ``UNet2DConditionOutput``.
+
+Core ML input contract (see ``convert.convert_unet``): every input is float16.
+  sample (B,C,H,W), timestep (B,), encoder_hidden_states (B,77,cross_dim);
+  + LCM:  timestep_cond (B,256)
+  + SDXL: time_ids (B,6), text_embeds (B,proj_dim)
+  + ctrl: additional_residual_0..N
+Single output ``noise_pred`` (float32).
+
+The traced model has FIXED input shapes: the batch and resolution are baked in
+at conversion. Classifier-free guidance feeds a batch of 2 (uncond+cond), so the
+artifact must be converted with ``batch_size=2`` to run a guided pipeline in one
+forward pass. Height/width must match the converted ``sample_size``.
+"""
+
+import numpy as np
+import torch
+
+from coreml_diffusion.logger import logger
+from coreml_diffusion.model_version import ModelVersion
+
+# Compute-unit default: let Core ML place ops on the ANE (falling back to CPU for
+# unsupported ops). Override per call for A/B against CPU_ONLY / CPU_AND_GPU.
+DEFAULT_COMPUTE_UNIT = "CPU_AND_NE"
+
+
+def _f16(tensor):
+    """diffusers tensor -> contiguous float16 numpy, matching the trace dtype."""
+    return np.ascontiguousarray(tensor.detach().to(torch.float16).cpu().numpy())
+
+
+class CoreMLUNet(torch.nn.Module):
+    """A ``UNet2DConditionModel`` stand-in backed by a Core ML ``.mlpackage``.
+
+    Carries the reference UNet's ``config`` so the surrounding diffusers pipeline
+    reads the right ``in_channels`` / ``addition_embed_type`` / ``time_cond_proj_dim``
+    etc., but runs the forward pass through coremltools instead of torch.
+    """
+
+    def __init__(
+        self, mlpackage_path, ref_unet, model_version, compute_unit=DEFAULT_COMPUTE_UNIT
+    ):
+        super().__init__()
+        import coremltools as ct
+
+        self.config = ref_unet.config
+        self.dtype = torch.float16
+        self.model_version = model_version
+
+        unit = (
+            compute_unit
+            if isinstance(compute_unit, ct.ComputeUnit)
+            else ct.ComputeUnit[compute_unit]
+        )
+        logger.info(f"Loading {mlpackage_path} to {unit.name}")
+        self.model = ct.models.MLModel(mlpackage_path, compute_units=unit)
+        self._output_name = self.model.get_spec().description.output[0].name
+
+    @property
+    def _is_lcm(self):
+        return self.model_version is ModelVersion.LCM
+
+    @property
+    def _is_sdxl(self):
+        return self.model_version in {ModelVersion.SDXL, ModelVersion.SDXL_REFINER}
+
+    def forward(
+        self,
+        sample,
+        timestep,
+        encoder_hidden_states,
+        timestep_cond=None,
+        added_cond_kwargs=None,
+        down_block_additional_residuals=None,
+        mid_block_additional_residual=None,
+        return_dict=True,
+        **_ignored,
+    ):
+        batch = sample.shape[0]
+
+        # timestep arrives as a python scalar, 0-dim, or (1,) tensor; the trace
+        # baked a (B,) timestep, so broadcast to the batch.
+        ts = torch.as_tensor(timestep, dtype=torch.float32).reshape(-1)
+        if ts.numel() == 1:
+            ts = ts.expand(batch)
+
+        inputs = {
+            "sample": _f16(sample),
+            "timestep": _f16(ts),
+            "encoder_hidden_states": _f16(encoder_hidden_states),
+        }
+
+        if self._is_lcm:
+            if timestep_cond is None:
+                raise ValueError(
+                    "LCM UNet requires timestep_cond (guidance embedding)."
+                )
+            inputs["timestep_cond"] = _f16(timestep_cond)
+
+        if self._is_sdxl:
+            if not added_cond_kwargs or "time_ids" not in added_cond_kwargs:
+                raise ValueError(
+                    "SDXL UNet requires added_cond_kwargs with time_ids/text_embeds."
+                )
+            inputs["time_ids"] = _f16(added_cond_kwargs["time_ids"])
+            inputs["text_embeds"] = _f16(added_cond_kwargs["text_embeds"])
+
+        if down_block_additional_residuals is not None:
+            residuals = list(down_block_additional_residuals)
+            if mid_block_additional_residual is not None:
+                residuals.append(mid_block_additional_residual)
+            for i, residual in enumerate(residuals):
+                inputs[f"additional_residual_{i}"] = _f16(residual)
+
+        prediction = self.model.predict(inputs)[self._output_name]
+        noise_pred = torch.from_numpy(np.ascontiguousarray(prediction)).to(
+            sample.device
+        )
+
+        if not return_dict:
+            return (noise_pred,)
+        from diffusers.models.unets.unet_2d_condition import UNet2DConditionOutput
+
+        return UNet2DConditionOutput(sample=noise_pred)
+
+
+# Stock diffusers pipeline per verified model. Experimental versions are convertible
+# but their pipelines are not wired here yet.
+_PIPELINE_IMPORTS = {
+    ModelVersion.SD15: ("diffusers", "StableDiffusionPipeline"),
+    ModelVersion.SDXL: ("diffusers", "StableDiffusionXLPipeline"),
+}
+
+
+def build_pipeline(
+    ckpt_path,
+    mlpackage_path,
+    model_version,
+    *,
+    compute_unit=DEFAULT_COMPUTE_UNIT,
+    torch_device="cpu",
+    **from_single_file_kwargs,
+):
+    """Load a stock diffusers pipeline from ``ckpt_path`` and swap in the Core ML UNet.
+
+    The VAE / text encoder / scheduler come from the same checkpoint and run on
+    ``torch_device``; only the UNet is served from ``mlpackage_path`` via Core ML.
+    Returns the pipeline ready to call. Wired for SD15 and SDXL; the golden
+    anchor that verifies output is captured by the Tier 2 (``m2``) test tier.
+    """
+    if model_version not in _PIPELINE_IMPORTS:
+        raise NotImplementedError(
+            f"No inference pipeline wired for {model_version.name}; "
+            f"supported: {[v.name for v in _PIPELINE_IMPORTS]}."
+        )
+    import importlib
+
+    module_name, class_name = _PIPELINE_IMPORTS[model_version]
+    pipeline_cls = getattr(importlib.import_module(module_name), class_name)
+
+    pipe = pipeline_cls.from_single_file(ckpt_path, **from_single_file_kwargs)
+    pipe.to(torch_device)
+    pipe.unet = CoreMLUNet(mlpackage_path, pipe.unet, model_version, compute_unit)
+    return pipe