fix(ocr): warn when LLM extraction fails

packages/markitdown-ocr/src/markitdown_ocr/_ocr_service.py

@@ -4,8 +4,9 @@
 """
 
 import base64
-from typing import Any, BinaryIO
+import warnings
 from dataclasses import dataclass
+from typing import Any, BinaryIO
 
 from markitdown import StreamInfo
 
@@ -105,6 +106,9 @@ def extract_text(
                 backend_used="llm_vision",
             )
         except Exception as e:
+            warnings.warn(
+                f"LLM vision OCR failed with {type(e).__name__}", stacklevel=2
+            )
             return OCRResult(text="", backend_used="llm_vision", error=str(e))
         finally:
             image_stream.seek(0)

packages/markitdown-ocr/tests/test_ocr_service.py

@@ -0,0 +1,26 @@
+import io
+from unittest.mock import MagicMock
+
+import pytest
+from markitdown import StreamInfo
+
+from markitdown_ocr._ocr_service import LLMVisionOCRService
+
+
+def test_extract_text_warns_when_llm_request_fails() -> None:
+    client = MagicMock()
+    client.chat.completions.create.side_effect = RuntimeError(
+        "simulated API failure"
+    )
+    image_stream = io.BytesIO(b"image data")
+
+    with pytest.warns(UserWarning, match="RuntimeError") as warning_info:
+        result = LLMVisionOCRService(client, "test-model").extract_text(
+            image_stream,
+            stream_info=StreamInfo(mimetype="image/png"),
+        )
+
+    assert "simulated API failure" not in str(warning_info[0].message)
+    assert result.text == ""
+    assert result.error == "simulated API failure"
+    assert image_stream.tell() == 0