fix(whisper): rewind audio file and preserve real error in requests fallback

When litellm.transcription fails and wdoc falls back to a direct requests
call, it reused the same file handle that litellm had already read to EOF, so
the fallback uploaded an empty body. Endpoints answer an empty upload with a
misleading status (e.g. 415 Unsupported Media Type) that has nothing to do
with the actual failure, which is likely what produced the confusing 415 seen
behind an auth proxy. Rewind the handle with seek(0) before the fallback POST.

Also, the original litellm error was only logged as a warning and then lost
when the fallback failed. Wrap the fallback request so its failure re-raises
with BOTH the endpoint error and the original litellm error, so the true root
cause (often an auth/proxy misconfiguration) survives.

Adds two regression tests (call the undecorated function to bypass the joblib
doc-loaders cache): one asserts the fallback uploads the full file, one
asserts the raised error mentions both the endpoint and litellm errors.

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

Author: thiswillbeyourgithub

tests/test_wdoc.py

@@ -746,3 +746,98 @@ def _boom(**kwargs):
     # warn mode keeps the traceback attached exactly once (via exc_info), not
     # inlined into the message
     assert warn_rec["exception"] is not None
+
+
+@pytest.mark.basic
+def test_whisper_fallback_rewinds_file(tmp_path, monkeypatch):
+    """When litellm.transcription fails and wdoc falls back to a direct request,
+    it must rewind the audio file first. litellm reads the handle to EOF, so
+    without a seek(0) the fallback uploads an empty body and the endpoint answers
+    with a misleading error (e.g. 415 Unsupported Media Type) unrelated to the
+    real failure. Regression test: the fallback must upload the full file."""
+    import litellm
+    import requests
+
+    from wdoc.utils.loaders import shared_audio
+
+    monkeypatch.setenv("WDOC_WHISPER_API_KEY", "test-key")
+    monkeypatch.setenv("WDOC_WHISPER_ENDPOINT", "https://fake.endpoint/")
+
+    audio_path = tmp_path / "sample.mp3"
+    payload = b"FAKE_AUDIO_BYTES_0123456789"
+    audio_path.write_bytes(payload)
+
+    def fake_transcription(**kwargs):
+        # emulate litellm consuming the file to EOF before failing
+        kwargs["file"].read()
+        raise RuntimeError("litellm boom")
+
+    uploaded = {}
+
+    class FakeResponse:
+        def raise_for_status(self):
+            return None
+
+        def json(self):
+            return {"text": "ok"}
+
+    def fake_post(url, files=None, data=None, headers=None):
+        uploaded["content"] = files["file"].read()
+        return FakeResponse()
+
+    monkeypatch.setattr(litellm, "transcription", fake_transcription)
+    monkeypatch.setattr(requests, "post", fake_post)
+
+    # call the undecorated function to bypass the joblib disk cache, so the test
+    # actually exercises the code and stays reproducible across runs
+    out = shared_audio.transcribe_audio_whisper.func(
+        audio_path=audio_path,
+        audio_hash="rewind-hash",
+        language=None,
+        prompt=None,
+    )
+
+    assert out == {"text": "ok"}
+    # the crux: the fallback uploaded the whole file, not the empty EOF leftover
+    assert uploaded["content"] == payload
+
+
+@pytest.mark.basic
+def test_whisper_fallback_surfaces_both_errors(tmp_path, monkeypatch):
+    """If the direct-request fallback also fails, the raised error must mention
+    BOTH the endpoint error and the original litellm error, so the real root
+    cause (often an auth/proxy misconfiguration) is not masked by a spurious
+    status code."""
+    import litellm
+    import requests
+
+    from wdoc.utils.loaders import shared_audio
+
+    monkeypatch.setenv("WDOC_WHISPER_API_KEY", "test-key")
+    monkeypatch.setenv("WDOC_WHISPER_ENDPOINT", "https://fake.endpoint/")
+
+    audio_path = tmp_path / "sample.mp3"
+    audio_path.write_bytes(b"FAKE_AUDIO_BYTES_0123456789")
+
+    def fake_transcription(**kwargs):
+        kwargs["file"].read()
+        raise RuntimeError("original litellm auth failure")
+
+    def fake_post(url, files=None, data=None, headers=None):
+        raise requests.exceptions.HTTPError("415 Unsupported Media Type")
+
+    monkeypatch.setattr(litellm, "transcription", fake_transcription)
+    monkeypatch.setattr(requests, "post", fake_post)
+
+    # call the undecorated function to bypass the joblib disk cache
+    with pytest.raises(Exception) as excinfo:
+        shared_audio.transcribe_audio_whisper.func(
+            audio_path=audio_path,
+            audio_hash="both-errors-hash",
+            language=None,
+            prompt=None,
+        )
+
+    msg = str(excinfo.value)
+    assert "415 Unsupported Media Type" in msg
+    assert "original litellm auth failure" in msg

wdoc/utils/loaders/shared_audio.py

@@ -290,14 +290,32 @@ def transcribe_audio_whisper(
                 if whisper_api_key:
                     headers["Authorization"] = f"Bearer {whisper_api_key}"
 
+                # Rewind the file: litellm.transcription above already read
+                # `audio_file` to EOF, so without this seek the fallback would
+                # upload an empty body and the endpoint would answer with a
+                # misleading error (e.g. 415 Unsupported Media Type) that has
+                # nothing to do with the real failure.
+                audio_file.seek(0)
+
                 # Make the request
                 endpoint_url = (
                     env.WDOC_WHISPER_ENDPOINT.rstrip("/") + "/v1/audio/transcriptions"
                 )
-                response = requests.post(
-                    endpoint_url, files=files, data=data, headers=headers
-                )
-                response.raise_for_status()
+                try:
+                    response = requests.post(
+                        endpoint_url, files=files, data=data, headers=headers
+                    )
+                    response.raise_for_status()
+                except Exception as fallback_err:
+                    # Surface both errors: the fallback error is what the endpoint
+                    # returned, but the original litellm error is often the real
+                    # root cause (e.g. an auth/proxy misconfiguration) and would
+                    # otherwise be discarded, leaving a misleading message.
+                    raise Exception(
+                        f"Whisper transcription failed. Direct request to "
+                        f"'{endpoint_url}' raised: {fallback_err}. The initial "
+                        f"litellm.transcription attempt raised: {litellm_err}"
+                    ) from fallback_err
                 transcript = response.json()
 
         t2 = time.time()