From 3c1e8512b9eba4a1b0551c9b66395a72035f115c Mon Sep 17 00:00:00 2001
From: Jamie Pine <32987599+jamiepine@users.noreply.github.com>
Date: Sat, 18 Apr 2026 17:43:31 -0700
Subject: [PATCH] fix(build): install mlx-audio/mlx-lm with --no-deps to bypass
 transformers 5.x conflict (#482)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous fix (#481) capped transformers at 4.57.6 in requirements-mlx.txt,
but pip's clean resolver in CI can't satisfy that alongside mlx-audio>=0.3.1
(declares `transformers==5.0.0rc3` or `>=5.0.0`) — it backtracks through every
transformers and tokenizers version and exits with `ResolutionImpossible`.

The dev install worked only because mlx-audio 0.4.1 was already present, so
pip never tried to re-resolve.

mlx-audio 0.4.1 + mlx-lm 0.31.1 both declare transformers>=5.x but the API
surface we actually use works fine on 4.57.x in practice (verified across all
engines in dev). Install both --no-deps to bypass the resolver; transitive
runtime deps (huggingface_hub, librosa, numpy, numba, pyloudnorm, etc.) are
already pulled in by requirements.txt.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .github/workflows/release.yml |  9 +++++++++
 backend/requirements-mlx.txt  | 18 ++++++++++--------
 2 files changed, 19 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index c3edd02c..c438e5eb 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -68,6 +68,15 @@ jobs:
         if: matrix.backend == 'mlx'
         run: |
           pip install -r backend/requirements-mlx.txt
+          # mlx-audio>=0.3.1 and mlx-lm>=0.31.1 both declare transformers>=5.x,
+          # which conflicts with our 4.57.x cap. The runtime APIs we use work
+          # fine on transformers 4.57.x in practice (verified in dev), so install
+          # them --no-deps. mlx-audio's other runtime deps (huggingface_hub,
+          # librosa, numpy, numba, pyloudnorm) are already in requirements.txt;
+          # the rest (sounddevice, miniaudio, protobuf, sentencepiece, pyyaml,
+          # jinja2) are pulled in by other engines.
+          pip install --no-deps mlx-lm==0.31.1
+          pip install --no-deps mlx-audio==0.4.1
 
       - name: Build Python server (Linux/macOS)
         if: matrix.platform != 'windows-latest'
diff --git a/backend/requirements-mlx.txt b/backend/requirements-mlx.txt
index 4bd1798c..fb99faeb 100644
--- a/backend/requirements-mlx.txt
+++ b/backend/requirements-mlx.txt
@@ -2,12 +2,14 @@
 # These should only be installed on aarch64-apple-darwin platforms
 
 mlx>=0.30.0
-mlx-audio>=0.3.1
 
-# Restate the transformers cap from requirements.txt. mlx-audio depends on
-# `transformers` with no upper bound, so installing it after requirements.txt
-# lets pip upgrade transformers past 4.57.x (latest is 5.x), which breaks
-# qwen-custom-voice (`@check_model_inputs()` API change), tada-1b (dataclass
-# `mutable default` enforcement), and luxtts (Whisper init path) in the
-# frozen MLX bundle. Keep this constraint in sync with requirements.txt.
-transformers>=4.36.0,<=4.57.6
+# NOTE: mlx-audio is intentionally not listed here. From 0.3.1 onward it
+# declares `transformers==5.0.0rc3` / `>=5.0.0`, which conflicts with the
+# `transformers<=4.57.6` cap in requirements.txt and breaks CI's clean
+# resolver. The mlx-audio API surface we use (mlx_audio.tts.load,
+# mlx_audio.stt.load) works fine on transformers 4.57.x in practice.
+#
+# Install it via `pip install --no-deps mlx-audio==0.4.1` after this file
+# (see .github/workflows/release.yml). All other mlx-audio runtime deps
+# (huggingface_hub, librosa, miniaudio, mlx-lm, numba, numpy, protobuf,
+# pyloudnorm, sounddevice, tqdm) are already in requirements.txt.