aszc-dev-ComfyUI-CoreMLSuite/docs/deps.md

Dependency decisions

Phase 5: ml-stable-diffusion compatibility under the bumped toolchain

Scope

Bumped: Python 3.11 → 3.12, torch 2.0.1 → 2.7.1, coremltools 8.2 → 9.0. Not bumped: numpy stays in the 1.24..1.x range. Phase 5 spec asked for numpy 2 as a goal; in practice the bump is decoupled — see "Why not numpy 2" below.

Problem

python_coreml_stable_diffusion pins three transitive dependencies in its setup.py that block any modern install:

install_requires=[
    "coremltools>=8.0",
    "diffusers[torch]==0.30.2",
    "transformers==4.44.2",
    "huggingface-hub==0.24.6",
    "numpy<1.24",
    ...
]

The exact-pin lines on diffusers/transformers/huggingface-hub block the Python-3.12 / torch-2.7 / coremltools-9 combo. The numpy ceiling at 1.24 also blocks newer numpy.

The upstream main branch as of 2026-05-24 (commit e12202c1f) has the same pins as our Phase 1 e5d960c4 SHA — no working alternative exists upstream. No maintained fork on PyPI either.

Decision

Keep the SHA pinned at e5d960c4 (Phase 1 baseline) and apply [tool.uv] override-dependencies to relax the four blocking pins:

[tool.uv]
override-dependencies = [
    "numpy>=1.24,<2",
    "diffusers>=0.30",
    "transformers>=4.44",
    "huggingface-hub>=0.24",
]

Why not bump the SHA, vendor the code, or fork?

• Bump SHA: the only newer SHA on main (e12202c1f) has identical pins. No upstream fix.
• Vendor the imports: our code only uses unet.UNet2DConditionModel, unet.UNet2DConditionModelXL, unet.AttentionImplementations, unet.calculate_conv2d_output_shape, and coreml_model.CoreMLModel. Copying these into coreml_suite/_vendor/ would work but adds hundreds of lines of code, owns a maintenance burden we don't want yet, and detaches us from upstream bug fixes.
• Public fork: would also need maintenance + CI to keep current with Apple's main.

The override is the smallest workable patch: it trusts that the API surface we touch (unet.* + coreml_model.CoreMLModel) is stable across the bumped versions — verified empirically by Tier 1 (synthetic UNet round-trip through ct.convert) and Tier 2 (real SD1.5 conversion

• golden image PSNR ≥ 25 dB).

Why not numpy 2

The Phase 5 spec asked for numpy 2 alongside the Python / coremltools / torch bumps. Tier 0 + Tier 1 are happy on numpy 2 — none of our own modules touch numpy in a way that breaks. The SD UNet conversion path is not:

1. coremltools 9.0 (and 8.3) _cast(int)inconverters/mil/frontend/torch/ops.pydoesdtype(x.val)wherex.valis a numpy ndarray with a single element. Under numpy 2 that raisesTypeError: only 0-dimensional arrays can be converted to Python scalars. Fixable via a np.ndarray.item()` shim.
2. After patching (1), view then trips mb.cast(x=shape, dtype="int32") where shape is a Python list of non-scalar Vars — a code path the upstream guard all([isinstance(dim, Var) and len(dim.shape) == 0 for dim in shape]) doesn't cover. Different bug class; needs a separate, larger shim on the view op (and probably more elsewhere — each patch reveals the next).

Neither bug is a Phase-5 deliverable. None of our code paths require numpy 2. Decision: hold numpy at >=1.24,<2 and unblock the rest of the bump. numpy 2 stays as an explicit follow-up once coremltools ships an upstream fix (or we sign up for the shim work).

Tier 2 PSNR threshold

Phase 2 anchored the golden image as a SHA256 + 40 dB PSNR fallback. The toolchain bump changes the bit-exact output: the SD1.5 baseline at seed=42 lands at ~29 dB against the Phase 2 PNG. The image is visually identical (same composition, same colors, sub-pixel drift), just numerically different — typical for a coremltools/torch upgrade.

tests/m2/test_golden_image.py was bumped to a 25 dB threshold and the golden anchor was re-captured against the bumped toolchain. Refactor PRs (Phase 3-style "should not change math") should raise the threshold via GOLDEN_PSNR_MIN_DB=40 (or higher); future toolchain bumps can repeat the Phase 5 dance and recapture.

Bench diff vs Phase 1

metric	Phase 1 (ct8.2/np1.23/py3.11)	Phase 5 (ct9.0/np1.26/py3.12/torch2.7)	delta
SD1.5 NE fwd median (ms)	196.97	197.32	+0.2%
SD1.5 GPU fwd median (ms)	270.26	272.01	+0.6%
Model size (MB)	1641	1641	0

Within run-to-run noise (Phase 1 reproducibility check landed at +0.0% / -0.3% across two consecutive runs). The bump is performance- neutral on the SD1.5 baseline.

Rollback

Reverting Phase 5 = restoring the Phase 1 pin set:

requires-python = ">=3.11,<3.12"
dependencies = [
    "python-coreml-stable-diffusion @ git+https://github.com/apple/ml-stable-diffusion.git@e5d960c41a6a4ab200b8db379194127607b1c590",
    "torch==2.0.1",
    "coremltools==8.2",
    "numpy<1.25",
    "overrides",
    "diffusers>=0.22",
    "peft>=0.6.2",
    "omegaconf>=2.3",
]
# Drop the [tool.uv] override-dependencies block entirely.
# Restore tests/m2/test_golden_image.py GOLDEN_PSNR_MIN_DB to 40.
# Restore tests/m2/goldens/sd15_seed42.{png,sha256} from the
# `modernize/phase4-tiered-ci` branch tip (the Phase 2 anchor).

Concretely: git revert <Phase 5 commit> followed by rm -rf .venv && uv venv --python 3.11 && uv sync will restore the Phase 1 environment. The Phase 1 bench/results/ef2a18c.json is the performance reference the rollback gets you back to.

Symbols we depend on from ml-stable-diffusion

If we ever do need to vendor (option above), this is the surface to copy:

Import path	Used in
python_coreml_stable_diffusion.unet.UNet2DConditionModel	coreml_suite/converter.py
python_coreml_stable_diffusion.unet.UNet2DConditionModelXL	coreml_suite/converter.py
python_coreml_stable_diffusion.unet.AttentionImplementations	coreml_suite/converter.py, coreml_suite/nodes.py
python_coreml_stable_diffusion.unet.calculate_conv2d_output_shape	coreml_suite/converter.py
python_coreml_stable_diffusion.coreml_model.CoreMLModel	coreml_suite/nodes.py

Plus the LCM-specific conversion helpers in coreml_suite/lcm/converter.py (same unet.* symbols).