feat: add paddle ocr

Dockerfile

@@ -16,6 +16,13 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     libssl-dev \
     nodejs \
     zlib1g-dev \
+    # Runtime libs for PaddleOCR / opencv-contrib-python (cv2), mirroring the
+    # reference reconciliation-file-processing-service Dockerfile.
+    libglib2.0-0 \
+    libsm6 \
+    libxext6 \
+    libxrender-dev \
+    libgomp1 \
     && rm -rf /var/lib/apt/lists/*
 
 RUN groupadd --gid 1000 appuser && \

app/api/server.py

@@ -111,6 +111,19 @@ async def lifespan(app: FastAPI):
     _logger.info("Embedding service initialized with dims: %s", _embedding_service.loaded_dimensions)
     _logger.info("Vector store service initialized with %d existing stores", len(_vector_store_service.list_stores()))
 
+    # Warm the OCR engine at startup so the PP-OCRv6 models are downloaded and
+    # cached before the first request (avoids slow first OCR). Runs on the
+    # shared thread pool; failure is non-fatal (engine initializes lazily on
+    # first use).
+    try:
+        from app.core.thread_pool import run_in_executor
+        from app.services.ocr_service import warmup as warmup_ocr
+
+        await run_in_executor(warmup_ocr)
+        _logger.info("OCR engine warmed up at startup")
+    except Exception as exc:
+        _logger.warning("OCR engine warm-up failed (will lazy-init on first use): %s", exc)
+
     redis = create_redis_client(_settings.redis_url) if _settings.redis_url else None
     scripts = await load_scripts(redis) if redis else {}
     app.state.redis = redis

app/config.py

@@ -31,6 +31,8 @@ class Settings(BaseSettings):
     max_batch_files: int = 10
     max_batch_urls: int = 20
 
+    # Legacy RapidOCR flags -- retained for the commented-out RapidOCR engine
+    # (see app/services/ocr_service.py). No longer used at runtime.
     ocr_det_cuda: bool = False
     ocr_det_dml: bool = False
     ocr_cls_cuda: bool = False
@@ -38,6 +40,21 @@ class Settings(BaseSettings):
     ocr_rec_cuda: bool = False
     ocr_rec_dml: bool = False
 
+    # PaddleOCR PP-OCRv6 engine (default: PP-OCRv6 small tier on ONNX Runtime,
+    # mirroring the reference reconciliation-file-processing-service setup).
+    ocr_engine: str = "onnxruntime"  # paddle | paddle_static | paddle_dynamic | onnxruntime | transformers
+    ocr_device: str = "cpu"
+    ocr_lang: Optional[str] = None  # e.g. "en"; None uses the model defaults
+    ocr_det_model_name: str = "PP-OCRv6_small_det"
+    ocr_rec_model_name: str = "PP-OCRv6_small_rec"
+    ocr_use_doc_orientation_classify: bool = False
+    ocr_use_doc_unwarping: bool = False
+    ocr_use_textline_orientation: bool = True
+    # Max concurrent predictions on the shared PaddleOCR engine. PaddleX
+    # pipelines are not documented thread-safe, so this serializes inference
+    # on the shared instance (not a new worker pool).
+    ocr_max_concurrent: int = 1
+
     self_ping_url: str = "https://aetherbase-llm-ready-data.hf.space/ping"
     spacy_model: str = "en_core_web_sm"
 

app/services/ocr_service.py

@@ -17,34 +17,113 @@ _settings = get_settings()
 _lock = threading.Lock()
 _engine = None
 
+# ---------------------------------------------------------------------------
+# Legacy RapidOCR implementation (RapidOCR) -- commented out, NOT deleted.
+#
+# It used the ONNX Runtime based `rapidocr_onnxruntime` package with per-module
+# CUDA/DML flags. Kept here for reference / easy rollback.
+#
+# def _get_engine():
+#     global _engine
+#     if _engine is None:
+#         with _lock:
+#             if _engine is None:
+#                 from rapidocr_onnxruntime import RapidOCR
+#                 _engine = RapidOCR(
+#                     Det={"use_cuda": _settings.ocr_det_cuda, "use_dml": _settings.ocr_det_dml},
+#                     Cls={"use_cuda": _settings.ocr_cls_cuda, "use_dml": _settings.ocr_cls_dml},
+#                     Rec={"use_cuda": _settings.ocr_rec_cuda, "use_dml": _settings.ocr_rec_dml},
+#                     print_verbose=False,
+#                 )
+#     return _engine
+#
+# def ocr_image(source, *, use_det=True, use_cls=True, use_rec=True, text_score=0.5) -> str:
+#     engine = _get_engine()
+#     img = _to_numpy(source)
+#     result, _ = engine(
+#         img,
+#         use_det=use_det,
+#         use_cls=use_cls,
+#         use_rec=use_rec,
+#         text_score=text_score,
+#     )
+#     if not result:
+#         return ""
+#     lines = [item[1] for item in result if len(item) > 1 and item[1]]
+#     return "\n".join(lines)
+# ---------------------------------------------------------------------------
+
+# Guards the shared PaddleOCR pipeline instance. PaddleOCR/PaddleX pipelines are
+# not documented as thread-safe for concurrent predict() calls, so OCR inference
+# is serialized on the shared engine (CPU-bound anyway). This is NOT a new worker
+# pool -- it merely limits concurrent use of the single shared model instance.
+_infer_semaphore = threading.BoundedSemaphore(
+    max(1, _settings.ocr_max_concurrent)
+)
+
 
 def _get_engine():
+    """Return the shared PaddleOCR PP-OCRv6 Small engine (lazy singleton).
+
+    Uses the PP-OCRv6 *small* tier models (PP-OCRv6_small_det /
+    PP-OCRv6_small_rec) shipped with PaddleOCR 3.7.0, executed on the ONNX
+    Runtime backend (engine="onnxruntime"). This mirrors the OCR benchmark /
+    reference reconciliation-file-processing-service, which pairs
+    ``paddleocr==3.7.0`` with PP-OCRv6-small models and the ONNX Runtime engine.
+    """
     global _engine
     if _engine is None:
         with _lock:
             if _engine is None:
-                from rapidocr_onnxruntime import RapidOCR
-                _engine = RapidOCR(
-                    Det={"use_cuda": _settings.ocr_det_cuda, "use_dml": _settings.ocr_det_dml},
-                    Cls={"use_cuda": _settings.ocr_cls_cuda, "use_dml": _settings.ocr_cls_dml},
-                    Rec={"use_cuda": _settings.ocr_rec_cuda, "use_dml": _settings.ocr_rec_dml},
-                    print_verbose=False,
+                from paddleocr import PaddleOCR
+
+                kwargs: dict = {
+                    "text_detection_model_name": _settings.ocr_det_model_name,
+                    "text_recognition_model_name": _settings.ocr_rec_model_name,
+                    "use_doc_orientation_classify": _settings.ocr_use_doc_orientation_classify,
+                    "use_doc_unwarping": _settings.ocr_use_doc_unwarping,
+                    "use_textline_orientation": _settings.ocr_use_textline_orientation,
+                    "engine": _settings.ocr_engine,
+                    "device": _settings.ocr_device,
+                }
+                if _settings.ocr_lang:
+                    kwargs["lang"] = _settings.ocr_lang
+                _engine = PaddleOCR(**kwargs)
+                _logger.info(
+                    "PaddleOCR engine ready (engine=%s device=%s det=%s rec=%s)",
+                    _settings.ocr_engine,
+                    _settings.ocr_device,
+                    _settings.ocr_det_model_name,
+                    _settings.ocr_rec_model_name,
                 )
     return _engine
 
 
+def _to_rgb(img: Image.Image) -> Image.Image:
+    """Normalise an image to 3-channel RGB.
+
+    PaddleOCR's recognition model asserts a 3-channel input (``imgC ==
+    img.shape[2]``), so RGBA (4-channel) and palette/grayscale inputs must be
+    converted -- unlike RapidOCR, which accepted RGBA arrays as-is.
+    """
+    if img.mode == "RGBA":
+        # Flatten alpha onto a white background: standard for scanned documents
+        # and avoids black halos around transparent regions.
+        background = Image.new("RGB", img.size, (255, 255, 255))
+        background.paste(img, mask=img.split()[-1])
+        return background
+    if img.mode != "RGB":
+        return img.convert("RGB")
+    return img
+
+
 def _to_numpy(source) -> Union[np.ndarray, str]:
     if isinstance(source, Image.Image):
-        img = source
-        if img.mode not in ("RGB", "L", "RGBA"):
-            img = img.convert("RGB")
-        return np.array(img)
+        return np.array(_to_rgb(source))
 
     if isinstance(source, (bytes, bytearray)):
         img = Image.open(io.BytesIO(source))
-        if img.mode not in ("RGB", "L", "RGBA"):
-            img = img.convert("RGB")
-        return np.array(img)
+        return np.array(_to_rgb(img))
 
     if isinstance(source, str):
         parsed = urlparse(source)
@@ -53,12 +132,14 @@ def _to_numpy(source) -> Union[np.ndarray, str]:
             resp = httpx.get(source, follow_redirects=True, timeout=30)
             resp.raise_for_status()
             img = Image.open(io.BytesIO(resp.content))
-            if img.mode not in ("RGB", "L", "RGBA"):
-                img = img.convert("RGB")
-            return np.array(img)
+            return np.array(_to_rgb(img))
         return source
 
     if isinstance(source, np.ndarray):
+        # Defensive: PaddleOCR needs 3-channel input. If a 4-channel array was
+        # passed directly, drop the alpha channel.
+        if source.ndim == 3 and source.shape[2] == 4:
+            source = source[:, :, :3]
         return source
 
     raise TypeError(
@@ -66,6 +147,47 @@ def _to_numpy(source) -> Union[np.ndarray, str]:
     )
 
 
+def _append_rec_texts(item: dict, texts: list[str], text_score: float) -> None:
+    """Append recognized lines from one PaddleOCR result dict.
+
+    ``rec_texts`` holds the recognized strings and ``rec_scores`` the matching
+    confidences (same index order). Lines below ``text_score`` are dropped,
+    mirroring the old RapidOCR ``text_score`` behaviour.
+    """
+    rec_texts = item.get("rec_texts") or []
+    rec_scores = item.get("rec_scores")
+    for idx, text in enumerate(rec_texts):
+        if not text:
+            continue
+        if rec_scores is not None and idx < len(rec_scores):
+            try:
+                score = float(rec_scores[idx])
+            except (TypeError, ValueError):
+                score = text_score
+            if score < text_score:
+                continue
+        texts.append(text)
+
+
+def _flatten_result(result, *, text_score: float = 0.5) -> list[str]:
+    """Flatten a PaddleOCR ``predict()`` result into recognized text lines.
+
+    Handles both the single-dict form and the nested list-of-dicts form the
+    pipeline can return (the reference project iterates the same shapes).
+    """
+    texts: list[str] = []
+    if not result:
+        return texts
+    for item in result:
+        if isinstance(item, dict):
+            _append_rec_texts(item, texts, text_score)
+        elif isinstance(item, (list, tuple)):
+            for sub in item:
+                if isinstance(sub, dict):
+                    _append_rec_texts(sub, texts, text_score)
+    return texts
+
+
 def ocr_image(
     source,
     *,
@@ -74,18 +196,32 @@ def ocr_image(
     use_rec: bool = True,
     text_score: float = 0.5,
 ) -> str:
+    """Run OCR on an image and return the recognized text lines.
+
+    API contract is unchanged from the RapidOCR implementation. Note: the
+    PaddleOCR 3.x pipeline always performs detection + recognition together;
+    ``use_det`` / ``use_cls`` / ``use_rec`` are accepted for backward
+    compatibility. ``use_cls`` maps to the textline-orientation module, which is
+    configured at engine initialisation (``ocr_use_textline_orientation``).
+    """
+    if not (use_det and use_rec):
+        _logger.warning(
+            "ocr_image: use_det/use_rec are no-ops with the PaddleOCR pipeline "
+            "(detection+recognition always run); got use_det=%s use_rec=%s",
+            use_det,
+            use_rec,
+        )
+    if not use_cls:
+        _logger.warning(
+            "ocr_image: use_cls=%s is ignored; textline orientation is fixed at "
+            "engine init via ocr_use_textline_orientation",
+            use_cls,
+        )
     engine = _get_engine()
     img = _to_numpy(source)
-    result, _ = engine(
-        img,
-        use_det=use_det,
-        use_cls=use_cls,
-        use_rec=use_rec,
-        text_score=text_score,
-    )
-    if not result:
-        return ""
-    lines = [item[1] for item in result if len(item) > 1 and item[1]]
+    with _infer_semaphore:
+        result = engine.predict(img)
+    lines = _flatten_result(result, text_score=text_score)
     return "\n".join(lines)
 
 
@@ -119,3 +255,15 @@ def ocr_pdf(source: Union[str, bytes], *, dpi: int = 150) -> str:
 class OCRService:
     def __init__(self) -> None:
         self._engine = _get_engine()
+
+
+def warmup() -> None:
+    """Force model download + engine initialisation at startup.
+
+    PaddleOCR downloads the PP-OCRv6 small ONNX models and caches them under
+    ``~/.paddlex/official_models`` on first use. Calling this during the app
+    lifespan (in the shared thread pool) means the first OCR request never
+    pays the download/init cost.
+    """
+    _get_engine()
+    _logger.info("PaddleOCR engine warmed up (models downloaded and cached)")

requirements.txt

@@ -10,12 +10,25 @@ aiohttp==3.11.13
 # --- Media / file processing ---
 numpy==2.2.6
 pillow==10.3.0
-opencv-python-headless==4.12.0.88
+# Aligned with paddlex[ocr-core]'s opencv-contrib-python==4.10.0.84 pin (both
+# provide cv2; same version avoids install-time file conflicts). Mirrors the
+# reference reconciliation-file-processing-service requirements.
+opencv-python-headless==4.10.0.84
 pypdfium2==4.30.0
+# Legacy RapidOCR engine -- kept installed for the commented-out implementation
+# in app/services/ocr_service.py (enables easy rollback).
 rapidocr-onnxruntime==1.4.4
 onnxruntime==1.20.1
 markitdown[all]==0.1.5
 
+# --- OCR: PaddleOCR PP-OCRv6 Small on ONNX Runtime ---
+# PaddleOCR 3.7.0 ships the PP-OCRv6 model family (tiny/small/medium). The
+# engine runs on ONNX Runtime (engine="onnxruntime"), which does NOT require the
+# PaddlePaddle framework -- PaddleX 3.7 avoids importing `paddle` unless a
+# paddle_static/paddle_dynamic engine is selected. PP-OCRv6-small ONNX models
+# are downloaded on first use to ~/.paddlex/official_models.
+paddleocr==3.7.0
+
 # --- Data / analysis ---
 pandas==3.0.1
 matplotlib==3.9.2