fix(asr): cap setuptools <80 so pkg_resources stays present (#224) (#225)

Windows v0.3 users hit two transcription failures with models installed:
- WhisperX: "Transcription produced no segments. No module named 'pkg_resources'"
- Whisper PyTorch fallback: "No ASR backend is ready. … set OMNIVOICE_PRELOAD_TTS_ASR=1"

Shared root cause: whisperx / faster-whisper import `pkg_resources` at runtime,
and setuptools 80+ DROPPED the bundled pkg_resources. The existing pin
`setuptools>=75` therefore resolved to 82.0.1 — which has no pkg_resources — so
`import whisperx` fails. That both breaks WhisperX transcription and makes its
is_available() return false, which is why every backend reports "not ready" and
the engine asks for the PyTorch fallback (the user's PowerShell env var never
reached the GUI-launched app, a separate red herring).

Fix: pin `setuptools>=75,<80`. Verified: <80 resolves to 79.0.1 which ships
pkg_resources; 82 does not. `uv lock` changed only setuptools (82.0.1→79.0.1).
This fixes BOTH errors — WhisperX imports again, so it's available and the
fallback is no longer needed.

Adds tests/test_pkg_resources_available.py to guard the pin from regressing.
Full suite 602 passed (incl. the new test), 0 failures.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

pyproject.toml

@@ -40,10 +40,14 @@ dependencies = [
     "webdataset",
     "numpy",
     "soundfile",
-    # pkg_resources is used by whisperx/faster-whisper at runtime.
-    # On Python 3.12+ it's no longer bundled by default — pin a modern
-    # setuptools to guarantee it's present (fixes #58).
-    "setuptools>=75.0",
+    # whisperx / faster-whisper import `pkg_resources` at runtime. setuptools
+    # 80+ DROPPED the bundled pkg_resources, so an unpinned ">=75" now resolves
+    # to a version WITHOUT it → "No module named 'pkg_resources'", which both
+    # breaks WhisperX transcription and makes its is_available() report false
+    # ("No ASR backend is ready"). Cap below 80 so pkg_resources stays present
+    # (issue #224; also #58). Revisit when whisperx/faster-whisper drop the
+    # pkg_resources dependency.
+    "setuptools>=75,<80",
     "psutil>=7.2.2",
     # Pinned to 3.x — pyannote 4.x removed `use_auth_token` from `Inference`
     # which whisperx 3.4.2 still passes, blowing up `whisperx.load_model()`

tests/test_pkg_resources_available.py

@@ -0,0 +1,16 @@
+"""Regression for #224 (and #58): whisperx / faster-whisper import
+`pkg_resources` at runtime. setuptools 80+ dropped the bundled pkg_resources,
+so an unpinned `setuptools>=75` resolves to a version WITHOUT it — which both
+breaks WhisperX transcription ("No module named 'pkg_resources'") and makes its
+is_available() report "No ASR backend is ready". The setuptools pin (<80) must
+keep a version that still ships pkg_resources.
+"""
+import importlib.util
+
+
+def test_pkg_resources_importable():
+    assert importlib.util.find_spec("pkg_resources") is not None, (
+        "pkg_resources is missing — the installed setuptools dropped it. "
+        "Keep the setuptools pin below the version that removed pkg_resources "
+        "(pyproject.toml / issue #224)."
+    )

uv.lock

@@ -3154,7 +3154,7 @@ requires-dist = [
     { name = "requests", marker = "extra == 'ui'" },
     { name = "s3prl", marker = "extra == 'eval'" },
     { name = "scalar-fastapi" },
-    { name = "setuptools", specifier = ">=75.0" },
+    { name = "setuptools", specifier = ">=75,<80" },
     { name = "soundfile" },
     { name = "supertonic", marker = "extra == 'supertonic'", specifier = "==1.3.1" },
     { name = "tensorboardx" },
@@ -5038,11 +5038,11 @@ wheels = [
 
 [[package]]
 name = "setuptools"
-version = "82.0.1"
+version = "79.0.1"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/4f/db/cfac1baf10650ab4d1c111714410d2fbb77ac5a616db26775db562c8fab2/setuptools-82.0.1.tar.gz", hash = "sha256:7d872682c5d01cfde07da7bccc7b65469d3dca203318515ada1de5eda35efbf9", size = 1152316, upload-time = "2026-03-09T12:47:17.221Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/bb/71/b6365e6325b3290e14957b2c3a804a529968c77a049b2ed40c095f749707/setuptools-79.0.1.tar.gz", hash = "sha256:128ce7b8f33c3079fd1b067ecbb4051a66e8526e7b65f6cec075dfc650ddfa88", size = 1367909, upload-time = "2025-04-23T22:20:59.241Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/9d/76/f789f7a86709c6b087c5a2f52f911838cad707cc613162401badc665acfe/setuptools-82.0.1-py3-none-any.whl", hash = "sha256:a59e362652f08dcd477c78bb6e7bd9d80a7995bc73ce773050228a348ce2e5bb", size = 1006223, upload-time = "2026-03-09T12:47:15.026Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/6d/b4752b044bf94cb802d88a888dc7d288baaf77d7910b7dedda74b5ceea0c/setuptools-79.0.1-py3-none-any.whl", hash = "sha256:e147c0549f27767ba362f9da434eab9c5dc0045d5304feb602a0af001089fc51", size = 1256281, upload-time = "2025-04-23T22:20:56.768Z" },
 ]
 
 [[package]]