Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix: PR #372 — restore [image] extra on Python 3.13 via rapidocr 3.x adapter
chopratejasb154e178533e
diff --git a/headroom/image/compressor.py b/headroom/image/compressor.pyindex 67080338e..f9ba35a78 100644--- a/headroom/image/compressor.py+++ b/headroom/image/compressor.py@@ -36,6 +36,67 @@ from .trained_router import Techniquelogger = logging.getLogger(__name__)+# OCR backend resolution — see issue #372.+#+# After version 1.4.x the rapidocr ecosystem split:+# * rapidocr-onnxruntime — bundled-ORT, capped at Python <3.13.+# * rapidocr 3.x — engine-agnostic core, supports 3.13+;+# requires `onnxruntime` installed alongside+# for the same ORT backend; returns a+# RapidOCROutput dataclass instead of a tuple.+#+# We try v1 first (legacy / Python <3.13 install path), fall back to+# v3 (Python 3.13+ install path), and cache the resolved tuple at+# module scope. Result is intentionally None when neither package is+# installed — OCR is an optional capability gated by `[image]` extra.+_RESOLVED_OCR: tuple[Any | None, str | None] | None = None+++def _resolve_rapidocr() -> tuple[Any | None, str | None]:+ """Return ``(RapidOCR class, api_version)`` cached on first call.++ ``api_version`` is ``"v1"`` for ``rapidocr_onnxruntime`` (tuple+ result shape) and ``"v3"`` for ``rapidocr`` 3.x (dataclass result+ shape). Returns ``(None, None)`` when neither package is installed.++ Detection is at runtime (not based on Python version) because a+ user on Python 3.11 might choose to install the 3.x package, and+ a future ABI3 ORT release may make rapidocr-onnxruntime work on+ Python 3.13. The actual install state is the source of truth.+ """+ global _RESOLVED_OCR+ if _RESOLVED_OCR is not None:+ return _RESOLVED_OCR++ try:+ from rapidocr_onnxruntime import RapidOCR as _RapidOCRv1++ _RESOLVED_OCR = (_RapidOCRv1, "v1")+ return _RESOLVED_OCR+ except ImportError:+ pass++ try:+ from rapidocr import RapidOCR as _RapidOCRv3 # type: ignore[import-not-found]++ _RESOLVED_OCR = (_RapidOCRv3, "v3")+ return _RESOLVED_OCR+ except ImportError:+ pass++ _RESOLVED_OCR = (None, None)+ return _RESOLVED_OCR+++def _reset_resolved_ocr_for_tests() -> None:+ """Test-only hook: clear the module-level resolver cache so each+ test can re-monkeypatch ``sys.modules`` and exercise a fresh+ resolution. Production code never calls this.+ """+ global _RESOLVED_OCR+ _RESOLVED_OCR = None++@dataclassclass CompressionResult:"""Result of image compression."""@@ -308,45 +369,122 @@ class ImageCompressor:def _ocr_extract(self, image_data: bytes, min_confidence: float = 0.7) -> str | None:"""Extract text from image using RapidOCR.- Returns extracted text if OCR is confident, None otherwise (fallback to image).- """- try:- from rapidocr_onnxruntime import RapidOCR+ Adapts both API generations of the rapidocr ecosystem at runtime+ (issue #372):- if not hasattr(self, "_ocr_engine"):- self._ocr_engine = RapidOCR()+ * ``rapidocr-onnxruntime`` 1.4.x (Python <3.13) — call returns+ ``(list[(box, text, score)], elapsed)``.+ * ``rapidocr`` 3.x (Python 3.13+) — call returns a+ ``RapidOCROutput`` dataclass with ``.txts`` (list[str]),+ ``.scores`` (list[float]), ``.boxes`` (list); each may be+ ``None`` when nothing was detected.- result, _ = self._ocr_engine(image_data)- if not result:+ Returns extracted text if OCR is confident, ``None`` otherwise+ (caller falls back to image-as-image).+ """+ ocr_cls, api_version = _resolve_rapidocr()+ if ocr_cls is None:+ logger.debug(+ "OCR backend unavailable: neither rapidocr-onnxruntime nor "+ "rapidocr installed — skipping (event=ocr_backend_missing)"+ )+ return None++ if not hasattr(self, "_ocr_engine"):+ try:+ self._ocr_engine = ocr_cls()+ except Exception as exc:+ logger.warning(+ "OCR engine init failed (event=ocr_engine_init_failed, api=%s): %s",+ api_version,+ exc,+ )return None- # Check average confidence- confidences = [line[2] for line in result]- avg_confidence = sum(confidences) / len(confidences)+ try:+ raw = self._ocr_engine(image_data)+ except Exception as exc:+ logger.warning(+ "OCR call failed (event=ocr_call_failed, api=%s): %s",+ api_version,+ exc,+ )+ return None- if avg_confidence < min_confidence:- logger.debug(- f"OCR confidence too low ({avg_confidence:.0%} < {min_confidence:.0%}), "- f"falling back to image"+ if api_version == "v1":+ # 1.x returns (list_of_tuples, elapsed). list may be empty+ # or None when no text is detected.+ try:+ result, _elapsed = raw+ except (TypeError, ValueError):+ logger.warning(+ "OCR returned unexpected v1 shape (event=ocr_unknown_api_shape, api=v1): %r",+ type(raw).__name__,+ )+ return None+ if not result:+ return None+ try:+ texts = [line[1] for line in result]+ confidences = [line[2] for line in result]+ except (IndexError, TypeError):+ logger.warning(+ "OCR v1 result rows missing expected (box, text, score) "+ "shape (event=ocr_unknown_api_shape, api=v1)")return None- # Combine lines into text- text = "\n".join(line[1] for line in result)+ elif api_version == "v3":+ # 3.x returns RapidOCROutput with txts/scores attributes.+ # Both are None when detection found nothing — coerce to [].+ texts_attr = getattr(raw, "txts", None)+ scores_attr = getattr(raw, "scores", None)+ if texts_attr is None and scores_attr is None:+ # Probe failed to detect anything — not an error.+ return None+ texts = list(texts_attr or [])+ confidences = list(scores_attr or [])+ if not texts:+ return None+ if len(confidences) != len(texts):+ logger.warning(+ "OCR v3 returned mismatched txts/scores lengths "+ "(event=ocr_unknown_api_shape, api=v3, txts=%d, scores=%d)",+ len(texts),+ len(confidences),+ )+ return None- logger.info(- f"OCR extracted {len(result)} lines ({avg_confidence:.0%} avg confidence, "- f"{len(text)} chars)"+ else:+ logger.warning(+ "OCR resolver returned unknown api_version (event=ocr_unknown_api_shape, api=%r)",+ api_version,)- return text+ return None- except ImportError:- logger.debug("rapidocr-onnxruntime not installed, skipping OCR")+ if not confidences:return None- except Exception as e:- logger.warning(f"OCR failed: {e}")+ avg_confidence = sum(confidences) / len(confidences)+ if avg_confidence < min_confidence:+ logger.debug(+ "OCR confidence too low (event=ocr_low_confidence, "+ "avg=%.2f, min=%.2f, api=%s) — falling back to image",+ avg_confidence,+ min_confidence,+ api_version,+ )return None+ text = "\n".join(texts)+ logger.info(+ "OCR extracted %d lines (event=ocr_extracted, avg_confidence=%.2f, chars=%d, api=%s)",+ len(texts),+ avg_confidence,+ len(text),+ api_version,+ )+ return text+def _apply_compression(self,messages: list[dict[str, Any]],diff --git a/pyproject.toml b/pyproject.tomlindex 150af2c0d..c89af3ff6 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -110,10 +110,30 @@ relevance = ["numpy>=1.24.0",]# Image compression (ML-based routing + OCR)+#+# OCR backend uses ONNX Runtime regardless of Python version. The+# rapidocr ecosystem split into two flavors after 1.4.x:+# * rapidocr-onnxruntime 1.4.x — bundled-ORT package, capped at+# Python <3.13 by its requires-python metadata. Drop-in for our+# existing v1 tuple-shaped API call.+# * rapidocr 3.x — engine-agnostic core, supports Python 3.13+.+# Returns a RapidOCROutput dataclass (txts, scores, boxes, ...).+# Needs `onnxruntime` installed separately to use the ORT backend.+#+# `headroom/image/compressor.py` adapts both API shapes at runtime via+# a try/except cascade. See issue #372 for context.image = ["pillow>=10.0.0","sentencepiece>=0.1.99", # Required by SigLIP tokenizer (SiglipTokenizer)- "rapidocr-onnxruntime>=1.4.0", # ONNX-native OCR for text extraction from images (~15MB models)+ # Python 3.6–3.12: keep the proven ORT-bundled package directly.+ # ~15 MB ONNX models auto-downloaded on first use.+ "rapidocr-onnxruntime>=1.4.0,<2; python_version<'3.13'",+ # Python 3.13+: rapidocr-onnxruntime is unavailable (its wheels+ # declare requires-python<3.13). Use the successor `rapidocr` 3.x+ # core + `onnxruntime` engine; same ORT backend, just split into+ # two packages. Total install size and inference speed unchanged.+ "rapidocr>=3.0,<4; python_version>='3.13'",+ "onnxruntime>=1.7,<2; python_version>='3.13'",]# Report generationreports = [diff --git a/tests/test_image_ocr_api_compat.py b/tests/test_image_ocr_api_compat.pynew file mode 100644index 000000000..7459021ae--- /dev/null+++ b/tests/test_image_ocr_api_compat.py@@ -0,0 +1,235 @@+"""OCR backend API-compat regression tests for issue #372.++The rapidocr ecosystem split after 1.4.x:++* `rapidocr-onnxruntime` 1.4.x — Python <3.13 only; tuple result.+* `rapidocr` 3.x — Python 3.13+; `RapidOCROutput` dataclass result.++`headroom/image/compressor.py` adapts both at runtime via+`_resolve_rapidocr` + per-version branches in `_ocr_extract`. These+tests pin both branches so a future "let me clean up the v1 path"+refactor doesn't silently break Python <3.13 users.+"""++from __future__ import annotations++import sys+from types import ModuleType, SimpleNamespace+from typing import Any++import pytest++from headroom.image import compressor as compressor_module+from headroom.image.compressor import ImageCompressor+++def _install_fake_module(monkeypatch: pytest.MonkeyPatch, name: str, attrs: dict[str, Any]) -> None:+ """Inject a synthetic module into sys.modules so import sees it."""+ mod = ModuleType(name)+ for k, v in attrs.items():+ setattr(mod, k, v)+ monkeypatch.setitem(sys.modules, name, mod)+++def _hide_module(monkeypatch: pytest.MonkeyPatch, name: str) -> None:+ """Force ImportError when `name` is imported."""+ monkeypatch.setitem(sys.modules, name, None)++[email protected](autouse=True)+def _reset_resolver_cache() -> None:+ compressor_module._reset_resolved_ocr_for_tests()+ yield+ compressor_module._reset_resolved_ocr_for_tests()+++# ---------------------------------------------------------------------------+# Resolver+# ---------------------------------------------------------------------------+++def test_resolve_rapidocr_prefers_v1_when_both_available(monkeypatch: pytest.MonkeyPatch) -> None:+ class _V1RapidOCR:+ pass++ class _V3RapidOCR:+ pass++ _install_fake_module(monkeypatch, "rapidocr_onnxruntime", {"RapidOCR": _V1RapidOCR})+ _install_fake_module(monkeypatch, "rapidocr", {"RapidOCR": _V3RapidOCR})++ cls, api = compressor_module._resolve_rapidocr()+ assert cls is _V1RapidOCR+ assert api == "v1"+++def test_resolve_rapidocr_falls_back_to_v3_when_v1_missing(monkeypatch: pytest.MonkeyPatch) -> None:+ class _V3RapidOCR:+ pass++ _hide_module(monkeypatch, "rapidocr_onnxruntime")+ _install_fake_module(monkeypatch, "rapidocr", {"RapidOCR": _V3RapidOCR})++ cls, api = compressor_module._resolve_rapidocr()+ assert cls is _V3RapidOCR+ assert api == "v3"+++def test_resolve_rapidocr_returns_none_when_neither_installed(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ _hide_module(monkeypatch, "rapidocr_onnxruntime")+ _hide_module(monkeypatch, "rapidocr")++ cls, api = compressor_module._resolve_rapidocr()+ assert cls is None+ assert api is None+++# ---------------------------------------------------------------------------+# _ocr_extract — v1 tuple shape+# ---------------------------------------------------------------------------+++def _make_compressor() -> ImageCompressor:+ """Build an ImageCompressor with the heavy ML deps stubbed.++ `ImageCompressor.__init__` lazy-loads the trained router; we don't+ exercise it here. Constructing a bare instance bypasses the load.+ """+ return ImageCompressor.__new__(ImageCompressor)+++def test_ocr_extract_v1_tuple_shape_parses_correctly(monkeypatch: pytest.MonkeyPatch) -> None:+ class _V1Engine:+ def __call__(self, _image_data: bytes) -> tuple[list[tuple[Any, str, float]], float]:+ return (+ [+ (None, "hello", 0.95),+ (None, "world", 0.90),+ ],+ 0.123,+ )++ class _V1RapidOCR:+ def __init__(self) -> None: ...+ def __call__(self, image_data: bytes) -> Any: # noqa: D401+ return _V1Engine()(image_data)++ _install_fake_module(monkeypatch, "rapidocr_onnxruntime", {"RapidOCR": _V1RapidOCR})++ c = _make_compressor()+ text = c._ocr_extract(b"\x89PNG fake")+ assert text == "hello\nworld"+++def test_ocr_extract_v1_low_confidence_returns_none(monkeypatch: pytest.MonkeyPatch) -> None:+ class _V1RapidOCR:+ def __init__(self) -> None: ...+ def __call__(self, _image_data: bytes) -> tuple[list[Any], float]:+ return ([(None, "blurry", 0.3), (None, "smudge", 0.4)], 0.0)++ _install_fake_module(monkeypatch, "rapidocr_onnxruntime", {"RapidOCR": _V1RapidOCR})++ c = _make_compressor()+ assert c._ocr_extract(b"\x89PNG fake", min_confidence=0.7) is None+++def test_ocr_extract_v1_empty_result_returns_none(monkeypatch: pytest.MonkeyPatch) -> None:+ class _V1RapidOCR:+ def __init__(self) -> None: ...+ def __call__(self, _image_data: bytes) -> tuple[list[Any] | None, float]:+ return ([], 0.0)++ _install_fake_module(monkeypatch, "rapidocr_onnxruntime", {"RapidOCR": _V1RapidOCR})++ c = _make_compressor()+ assert c._ocr_extract(b"\x89PNG fake") is None+++# ---------------------------------------------------------------------------+# _ocr_extract — v3 dataclass shape+# ---------------------------------------------------------------------------+++def test_ocr_extract_v3_dataclass_shape_parses_correctly(monkeypatch: pytest.MonkeyPatch) -> None:+ class _V3RapidOCR:+ def __init__(self) -> None: ...+ def __call__(self, _image_data: bytes) -> Any:+ # Mirror the real `rapidocr.RapidOCROutput` minimal surface.+ return SimpleNamespace(+ txts=["hello", "world"],+ scores=[0.95, 0.90],+ boxes=[None, None],+ )++ _hide_module(monkeypatch, "rapidocr_onnxruntime")+ _install_fake_module(monkeypatch, "rapidocr", {"RapidOCR": _V3RapidOCR})++ c = _make_compressor()+ text = c._ocr_extract(b"\x89PNG fake")+ assert text == "hello\nworld"+++def test_ocr_extract_v3_low_confidence_returns_none(monkeypatch: pytest.MonkeyPatch) -> None:+ class _V3RapidOCR:+ def __init__(self) -> None: ...+ def __call__(self, _image_data: bytes) -> Any:+ return SimpleNamespace(txts=["blurry", "smudge"], scores=[0.3, 0.4], boxes=[None, None])++ _hide_module(monkeypatch, "rapidocr_onnxruntime")+ _install_fake_module(monkeypatch, "rapidocr", {"RapidOCR": _V3RapidOCR})++ c = _make_compressor()+ assert c._ocr_extract(b"\x89PNG fake", min_confidence=0.7) is None+++def test_ocr_extract_v3_none_attrs_when_no_text_detected(monkeypatch: pytest.MonkeyPatch) -> None:+ """Real-world v3 behavior: when detection finds nothing, RapidOCROutput+ has txts=None and scores=None. Verified in dispatch smoke test against+ rapidocr 3.8.1.+ """++ class _V3RapidOCR:+ def __init__(self) -> None: ...+ def __call__(self, _image_data: bytes) -> Any:+ return SimpleNamespace(txts=None, scores=None, boxes=None)++ _hide_module(monkeypatch, "rapidocr_onnxruntime")+ _install_fake_module(monkeypatch, "rapidocr", {"RapidOCR": _V3RapidOCR})++ c = _make_compressor()+ assert c._ocr_extract(b"\x89PNG fake") is None+++def test_ocr_extract_v3_mismatched_lengths_logs_and_returns_none(+ monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture+) -> None:+ class _V3RapidOCR:+ def __init__(self) -> None: ...+ def __call__(self, _image_data: bytes) -> Any:+ return SimpleNamespace(txts=["a", "b", "c"], scores=[0.9, 0.8], boxes=[None] * 3)++ _hide_module(monkeypatch, "rapidocr_onnxruntime")+ _install_fake_module(monkeypatch, "rapidocr", {"RapidOCR": _V3RapidOCR})++ c = _make_compressor()+ with caplog.at_level("WARNING", logger="headroom.image.compressor"):+ result = c._ocr_extract(b"\x89PNG fake")+ assert result is None+ assert any("event=ocr_unknown_api_shape" in r.getMessage() for r in caplog.records)+++# ---------------------------------------------------------------------------+# Backend missing+# ---------------------------------------------------------------------------+++def test_ocr_extract_returns_none_when_no_backend_installed(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ _hide_module(monkeypatch, "rapidocr_onnxruntime")+ _hide_module(monkeypatch, "rapidocr")++ c = _make_compressor()+ assert c._ocr_extract(b"\x89PNG fake") is None