Upload 7 files

Dockerfile

@@ -0,0 +1,166 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# MinerU OCR Service — Hugging Face Docker Space (CPU / pipeline backend)
+#
+# Optimized for FREE tier: 2 vCPU · 16 GB RAM · 50 GB Disk · No GPU
+#
+# ── OCR ROUTING ARCHITECTURE ──────────────────────────────────────────────────
+#
+# FAST PATH  (images: jpg/png/webp/bmp/heic/etc)
+#   rapidocr-onnxruntime ≥ 1.3.22
+#     - Pure ONNX inference — no PaddleOCR / paddlepaddle needed
+#     - Models bundled in the pip wheel (~50 MB); no first-use download
+#     - Target latency: 1–5 s on CPU
+#   Multi-pass: if RapidOCR confidence < 0.65 → MinerU fallback automatically
+#
+# HEAVY PATH (PDFs, multi-page, forms with layout)
+#   MinerU (magic-pdf pipeline backend)
+#     - Layout detection (doclayout_yolo)
+#     - OCR (paddleocr2pytorch — PyTorch reimplementation bundled in wheel)
+#     - Markdown reconstruction
+#     - Target latency: 5–30 s on CPU
+#
+# ── ROOT CAUSE HISTORY ────────────────────────────────────────────────────────
+#
+# FAILURE 1: [full-cpu] is NOT a valid extra → pip silently installs base only
+#   Fix: magic-pdf[full]==1.3.12
+#
+# FAILURE 2: opencv non-headless conflict
+#   Fix: Layer 4 force-reinstall of opencv-python-headless
+#
+# FAILURE 3: ch_PP-OCRv3_det_infer.pth not in HF repo (repo updated to v5)
+#   Fix: Layer 3.5 patches models_config.yml inside installed wheel:
+#        ch_PP-OCRv3_det → ch_PP-OCRv5_det   (all ch* langs)
+#        en_PP-OCRv3_det → Multilingual_PP-OCRv3_det  (en, latin)
+#   Arch safety: both replacement stems verified in arch_config.yaml
+#
+# ── System packages ────────────────────────────────────────────────────────────
+#   libgl1       — OpenCV needs libGL.so.1 for ALL image operations (not just GUI)
+#   libglib2.0-0 — GLib; required by OpenCV and many C extensions
+#   libgomp1     — OpenMP; required by ONNX Runtime and YOLO inference
+#   poppler-utils — pdfinfo/pdftoppm; used by MinerU PDF pre-processing
+# ─────────────────────────────────────────────────────────────────────────────
+
+FROM python:3.10-slim
+
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PORT=7860
+ENV MINERU_DEVICE_MODE=cpu
+ENV MINERU_BACKEND=pipeline
+
+# ── System dependencies ────────────────────────────────────────────────────────
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        libgl1 \
+        libglib2.0-0 \
+        libgomp1 \
+        poppler-utils \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# ── Layer 1: FastAPI + lightweight runtime deps ───────────────────────────────
+# rapidocr-onnxruntime: ONNX-based fast OCR engine; models bundled in wheel.
+#   - requires onnxruntime (will be auto-resolved or overridden by magic-pdf deps)
+#   - requires numpy, pyclipper, shapely — all covered by magic-pdf[full]
+#   - ~50 MB wheel; zero first-use model download needed
+# opencv-python-headless: placeholder; will be force-reinstalled in Layer 4
+RUN pip install --no-cache-dir --timeout 300 \
+        "fastapi>=0.115.0" \
+        "uvicorn[standard]>=0.32.0" \
+        "python-multipart>=0.0.12" \
+        "Pillow>=10.0.0" \
+        "pillow-heif>=0.18.0" \
+        "huggingface_hub>=0.25.0" \
+        "opencv-python-headless>=4.8.0" \
+        "rapidocr-onnxruntime>=1.3.22" \
+        "python-docx>=1.1.0" \
+        "python-pptx>=0.6.23" \
+        "openpyxl>=3.1.0"
+
+# ── Layer 2: CPU-only PyTorch — MUST precede magic-pdf ───────────────────────
+# PyPI serves the CUDA-enabled torch wheel by default (~2.5 GB).
+# Installing from the official CPU wheel index first causes pip to treat the
+# already-installed CPU build as satisfying magic-pdf's torch requirement.
+RUN pip install --no-cache-dir --timeout 600 \
+        --index-url https://download.pytorch.org/whl/cpu \
+        "torch>=2.2.2,!=2.5.0,!=2.5.1,<3" \
+        "torchvision>=0.15.2"
+
+# ── Layer 3: magic-pdf with the CORRECT extras ────────────────────────────────
+# [full] provides ultralytics, doclayout-yolo==0.0.2b1, rapid-table, shapely,
+# pyclipper, omegaconf, matplotlib, ftfy, dill, PyYAML, openai, albumentations.
+# doclayout-yolo==0.0.2b1 is ONLY on the myhloli index — not on PyPI.
+# onnxruntime resolved automatically as transitive dep of rapid-table.
+RUN pip install --no-cache-dir --timeout 600 \
+        --extra-index-url https://myhloli.github.io/wheels/ \
+        "magic-pdf[full]==1.3.12"
+
+# ── Layer 3.5: Patch OCR model config ────────────────────────────────────────
+# HF repo opendatalab/PDF-Extract-Kit-1.0 was updated to v5 det models.
+# magic-pdf 1.3.12 models_config.yml still references v3 det files (absent).
+# This patch runs at build time so download_models.py fetches correct files.
+RUN python3 - <<'PYEOF'
+import sys, yaml
+from pathlib import Path
+import magic_pdf
+
+pkg = Path(magic_pdf.__file__).parent
+cfg_path  = pkg / 'model/sub_modules/ocr/paddleocr2pytorch/pytorchocr/utils/resources/models_config.yml'
+arch_path = pkg / 'model/sub_modules/ocr/paddleocr2pytorch/pytorchocr/utils/resources/arch_config.yaml'
+
+print(f"Patching: {cfg_path}")
+
+with open(cfg_path) as f:
+    config = yaml.safe_load(f)
+with open(arch_path) as f:
+    arch_text = f.read()
+
+DET_MAP = {
+    'ch_PP-OCRv3_det_infer.pth':  'ch_PP-OCRv5_det_infer.pth',
+    'en_PP-OCRv3_det_infer.pth':  'Multilingual_PP-OCRv3_det_infer.pth',
+}
+
+patched = 0
+for lang, files in config['lang'].items():
+    old = files.get('det', '')
+    if old in DET_MAP:
+        new = DET_MAP[old]
+        arch_key = new[:-4]
+        if (arch_key + ':') not in arch_text:
+            print(f"ERROR: arch key '{arch_key}' not found in arch_config.yaml", file=sys.stderr)
+            sys.exit(1)
+        files['det'] = new
+        print(f"  [{lang}] det: {old}  ->  {new}")
+        patched += 1
+
+with open(cfg_path, 'w') as f:
+    yaml.dump(config, f, default_flow_style=False, allow_unicode=True)
+
+print(f"Patched {patched} language entries. models_config.yml updated.")
+PYEOF
+
+# ── Layer 4: Restore headless OpenCV ─────────────────────────────────────────
+# Layer 3 pulled opencv-python (non-headless) via doclayout-yolo/ultralytics/
+# rapid-table. Force-reinstall headless build so cv2 works on this slim image.
+RUN pip install --no-cache-dir --timeout 300 \
+        --force-reinstall \
+        "opencv-python-headless>=4.8.0"
+
+# ── Application code ──────────────────────────────────────────────────────────
+COPY download_models.py .
+COPY validate.py .
+COPY main.py .
+COPY entrypoint.sh .
+RUN chmod +x entrypoint.sh
+
+# ── Download models at build time ─────────────────────────────────────────────
+# MFR (formula recognition, ~1-2 GB) excluded — disabled in config.
+# rapidocr-onnxruntime models are BUNDLED in the pip wheel; no download needed.
+RUN python download_models.py
+
+RUN mkdir -p /app/config && cp /root/magic-pdf.json /app/config/magic-pdf.json
+
+# ── Runtime ───────────────────────────────────────────────────────────────────
+EXPOSE 7860
+ENTRYPOINT ["/app/entrypoint.sh"]

README.md

@@ -0,0 +1,9 @@
+---
+title: OpenSkill OCR
+emoji: 📄
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+---

download_models.py

@@ -0,0 +1,185 @@
+"""
+Download MinerU pipeline models from Hugging Face Hub.
+
+Called once during Docker build: python download_models.py
+
+Optimizations vs original:
+  - Skip-if-exists: if models are already present (Docker layer cache reuse),
+    the entire download is skipped without re-downloading anything.
+  - MFR excluded: formula recognition models (unimernet, ~1-2 GB) are not
+    downloaded because formula recognition is disabled in the config. Excluding
+    them cuts download time and image size significantly.
+  - layoutreader optional: if download fails (network issue, repo unavailable),
+    the script logs a warning and continues. MinerU falls back to its built-in
+    layout ordering without layoutreader.
+
+── FORENSIC: OCR MODEL AVAILABILITY IN opendatalab/PDF-Extract-Kit-1.0 ───────
+
+models_config.yml in magic-pdf 1.3.12 was patched in Dockerfile Layer 3.5 to
+use the weight files that ARE present in the HF repo. After the patch:
+
+  DEFAULT CPU path (ch_lite):
+    det: ch_PP-OCRv5_det_infer.pth      ← present in HF repo ✓
+    rec: ch_PP-OCRv5_rec_infer.pth      ← present in HF repo ✓
+
+  en / latin det (patched):
+    det: Multilingual_PP-OCRv3_det_infer.pth  ← present in HF repo ✓
+
+  NOT IN REPO (these files do NOT exist and are not needed for default usage):
+    ch_PP-OCRv3_det_infer.pth           ← absent; patched to v5
+    en_PP-OCRv3_det_infer.pth           ← absent; patched to multilingual
+    en_PP-OCRv4_rec_infer.pth           ← absent; en rec unavailable
+    korean/japan/chinese_cht/etc v3 rec ← absent; those langs need explicit
+                                           lang= arg which is not default
+
+  BUNDLED IN WHEEL (not downloaded here):
+    magic_pdf/resources/slanet_plus/slanet-plus.onnx  ← table model, in wheel
+    magic_pdf/resources/fasttext-langdetect/lid.176.ftz
+    magic_pdf/resources/yolov11-langdetect/yolo_v11_ft.pt
+
+Models saved to /app/models/
+Config written to /root/magic-pdf.json
+"""
+
+import json
+import os
+import sys
+
+MODELS_DIR = "/app/models"
+EXTRACT_KIT_DIR = os.path.join(MODELS_DIR, "PDF-Extract-Kit-1.0")
+LAYOUTREADER_DIR = os.path.join(MODELS_DIR, "layoutreader")
+
+# Canary files: both must exist for the skip-if-exists check to pass.
+# Using the OCR det weight (not just the Layout dir) ensures a stale cache
+# that predates the v3→v5 model rename cannot produce a false positive.
+_CANARY_DIR  = os.path.join(EXTRACT_KIT_DIR, "models", "Layout")
+_CANARY_FILE = os.path.join(
+    EXTRACT_KIT_DIR, "models", "OCR", "paddleocr_torch",
+    "ch_PP-OCRv5_det_infer.pth"           # patched det; absent in v3-era cache
+)
+
+
+def _models_present() -> bool:
+    """Return True only when BOTH the Layout directory AND the OCR v5 det weight
+    exist.  This prevents stale Docker layer caches (built before the v3→v5 patch)
+    from reporting models as present when the required file is missing."""
+    return os.path.isdir(_CANARY_DIR) and os.path.isfile(_CANARY_FILE)
+
+
+def _write_config(layoutreader_dir: str) -> None:
+    config = {
+        "bucket_info": {},
+        "models-dir": os.path.join(EXTRACT_KIT_DIR, "models"),
+        "layoutreader-model-dir": layoutreader_dir,
+        "device-mode": "cpu",
+        "layout-config": {
+            "model": "doclayout_yolo"
+        },
+        "formula-config": {
+            "mfd_model": "yolo_v8_mfd",
+            "mfr_model": "unimernet_small",
+            "enable": False
+        },
+        "table-config": {
+            "model": "rapid_table",
+            "enable": True,
+            "max_time": 400
+        },
+        "backend": "pipeline"
+    }
+    config_path = os.path.expanduser("~/magic-pdf.json")
+    with open(config_path, "w") as f:
+        json.dump(config, f, indent=2)
+    print(f"Config written → {config_path}")
+    return config_path
+
+
+def download() -> None:
+    try:
+        from huggingface_hub import snapshot_download
+    except ImportError:
+        print("ERROR: huggingface_hub not installed", file=sys.stderr)
+        sys.exit(1)
+
+    # ── Skip-if-exists ────────────────────────────────────────────────────────
+    if _models_present():
+        print("Models already present — skipping download (Docker layer cache).")
+        # Config may still need writing if this is a fresh container from cached layer
+        lr_dir = LAYOUTREADER_DIR if os.path.isdir(LAYOUTREADER_DIR) else ""
+        _write_config(lr_dir)
+        return
+
+    os.makedirs(MODELS_DIR, exist_ok=True)
+
+    # ── PDF-Extract-Kit-1.0 ───────────────────────────────────────────────────
+    # Excluded via ignore_patterns:
+    #   models/MFR — formula recognition (unimernet). Disabled in config.
+    #                Saves ~1-2 GB of download and disk.
+    #
+    # OCR models (models/OCR/paddleocr_torch/) ARE included (not ignored).
+    # After the Layer 3.5 patch, the files models_config.yml references match
+    # what is actually present in the repo:
+    #   ch_PP-OCRv5_det_infer.pth     ← present ✓
+    #   ch_PP-OCRv5_rec_infer.pth     ← present ✓
+    #   Multilingual_PP-OCRv3_det_infer.pth ← present ✓
+    print("=" * 60)
+    print("Downloading PDF-Extract-Kit-1.0 ...")
+    print("  (MFR/formula-recognition excluded — disabled in config)")
+    print("=" * 60)
+    snapshot_download(
+        repo_id="opendatalab/PDF-Extract-Kit-1.0",
+        local_dir=EXTRACT_KIT_DIR,
+        ignore_patterns=[
+            "*.git*",
+            ".gitattributes",
+            "models/MFR*",
+            "models/MFR/*",
+        ],
+    )
+    print(f"  → {EXTRACT_KIT_DIR}")
+
+    # Verify canary file landed correctly
+    if not os.path.isfile(_CANARY_FILE):
+        print(
+            f"\nERROR: Expected OCR model not found after download:\n"
+            f"  {_CANARY_FILE}\n"
+            f"The HF repo may have changed its file structure.\n"
+            f"Run:  python3 -c \"from huggingface_hub import list_repo_files; "
+            f"[print(f) for f in list_repo_files('opendatalab/PDF-Extract-Kit-1.0')]\"\n"
+            f"to inspect the current repo contents.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    print(f"  Canary verified: {os.path.basename(_CANARY_FILE)} ✓")
+
+    # ── layoutreader (optional) ───────────────────────────────────────────────
+    # Improves reading-order accuracy. If unavailable, MinerU uses fallback.
+    layoutreader_dir = ""
+    print("=" * 60)
+    print("Downloading layoutreader (optional, improves reading order) ...")
+    print("=" * 60)
+    try:
+        snapshot_download(
+            repo_id="hantian/layoutreader",
+            local_dir=LAYOUTREADER_DIR,
+            ignore_patterns=["*.git*", ".gitattributes"],
+        )
+        layoutreader_dir = LAYOUTREADER_DIR
+        print(f"  → {LAYOUTREADER_DIR}")
+    except Exception as exc:
+        print(f"  WARNING: layoutreader download failed ({exc})")
+        print("  Continuing without layoutreader — MinerU will use fallback ordering.")
+
+    # ── Write config ──────────────────────────────────────────────────────────
+    _write_config(layoutreader_dir)
+
+    print("\n✓ Model setup complete.")
+    print(f"  models-dir          : {os.path.join(EXTRACT_KIT_DIR, 'models')}")
+    print(f"  layoutreader-dir    : {layoutreader_dir or '(not available)'}")
+    print(f"  device-mode         : cpu")
+    print(f"  formula recognition : disabled (MFR models excluded)")
+    print(f"  table recognition   : enabled (slanet-plus.onnx bundled in wheel)")
+
+
+if __name__ == "__main__":
+    download()

entrypoint.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# ─────────────────────────────────────────────────────────────────────────────
+# MinerU OCR Service — container entrypoint
+#
+# Sequence:
+#   1. Restore magic-pdf.json if wiped (HF container restart)
+#   2. Run validate.py (pre-flight dependency check)
+#      → exits 1 and kills container if any critical dep is missing
+#      → this surfaces a clear error in HF logs instead of a silent bad start
+#   3. Start uvicorn (single worker — CPU Basic, no RAM contention)
+# ─────────────────────────────────────────────────────────────────────────────
+set -e
+
+CONFIG_FILE="${HOME}/magic-pdf.json"
+
+# ── 1. Restore config if /root was wiped (HF container restart) ───────────────
+if [ ! -f "$CONFIG_FILE" ]; then
+    echo "[entrypoint] magic-pdf.json missing — restoring from baked copy..."
+    cp /app/config/magic-pdf.json "$CONFIG_FILE"
+fi
+
+echo "[entrypoint] Config   : $CONFIG_FILE"
+echo "[entrypoint] Port     : ${PORT:-7860}"
+
+# ── 2. Pre-flight validation ──────────────────────────────────────────────────
+# validate.py exits 0 on pass, exits 1 on any CRITICAL failure.
+# 'set -e' above ensures a non-zero exit from validate.py aborts this script,
+# preventing a broken uvicorn from starting and appearing healthy.
+echo "[entrypoint] Running pre-flight validation..."
+python /app/validate.py
+echo "[entrypoint] Validation passed."
+
+# ── 3. Start API server ───────────────────────────────────────────────────────
+echo "[entrypoint] Starting uvicorn on 0.0.0.0:${PORT:-7860}..."
+exec uvicorn main:app \
+    --host 0.0.0.0 \
+    --port "${PORT:-7860}" \
+    --workers 1 \
+    --timeout-keep-alive 120 \
+    --log-level info

main.py

@@ -0,0 +1,1401 @@
+"""
+OpenSkill OCR Service — v4.0
+FastAPI application for Hugging Face Docker Space (CPU / pipeline backend)
+
+═══════════════════════════════════════════════════════════════════════════════
+ARCHITECTURE (v4.0 — OCR-only, AI-first)
+═══════════════════════════════════════════════════════════════════════════════
+
+This service is an extraction layer only. It does NOT:
+  - classify documents
+  - extract named entities
+  - validate fields
+  - generate summaries
+  - perform board/marksheet/JEE-specific logic
+
+All document understanding is delegated to the AI layer downstream.
+
+PATH A — Fast OCR  (images: jpg / png / webp / bmp / heic / heif / avif)
+  Engine : rapidocr-onnxruntime ≥ 1.3.22
+  Models : Bundled in pip wheel — zero first-use download, ~50 MB
+  Resize : images capped at MAX_OCR_SIDE px (default 1600) before inference
+  Target : 1–4 s  (acceptable < 8 s)
+  Fallback: if confidence < FAST_CONFIDENCE_THRESHOLD → MinerU fallback
+
+PATH B — Full pipeline  (PDFs, multi-page, layout-sensitive docs)
+  Engine : MinerU magic-pdf pipeline backend
+  Models : opendatalab/PDF-Extract-Kit-1.0 (downloaded at build time)
+  Target : 5–20 s  (acceptable < 30 s)
+
+═══════════════════════════════════════════════════════════════════════════════
+RESPONSE FORMAT (v4.0)
+═══════════════════════════════════════════════════════════════════════════════
+
+  {
+    "success":          true,
+    "filename":         "scan.jpg",
+    "engine":           "rapidocr",
+    "confidence":       0.91,
+    "text":             "...",
+    "markdown":         "...",
+    "pageCount":        1,
+    "cached":           false,
+    "processingTimeMs": 1840,
+    "timings": {
+      "uploadMs":      12,
+      "hashMs":         4,
+      "memCheckMs":     8,
+      "decodeMs":      55,
+      "resizeMs":      18,
+      "detectMs":     610,
+      "recognizeMs":  980,
+      "postProcessMs": 14,
+      "totalMs":      1840
+    },
+    "metadata": {
+      "imgW":         3024,
+      "imgH":         4032,
+      "imgWResized":  1200,
+      "imgHResized":  1600,
+      "textBlocks":     47,
+      "passesUsed":      1,
+      "backend":     "rapidocr"
+    }
+  }
+
+═══════════════════════════════════════════════════════════════════════════════
+API ENDPOINTS
+═══════════════════════════════════════════════════════════════════════════════
+
+  GET  /health       Liveness (always fast)
+  GET  /status       Node status: memory, uptime, cache, engine state
+  GET  /warmup       Pre-load both OCR engines (also called at startup)
+  GET  /diagnostics  Full environment + model inventory
+  POST /benchmark    Multi-size RapidOCR timing benchmark (small/medium/large)
+  POST /extract      Single file — PDF or image — with SHA256 cache
+  POST /batch        Up to 8 files, sequential, per-file error isolation
+"""
+
+import hashlib
+import io
+import os
+import re
+import shutil
+import sys
+import tempfile
+import threading
+import time
+import traceback
+import logging
+from importlib.metadata import version as pkg_version
+from typing import Any, Optional
+
+import fitz        # PyMuPDF
+import numpy as np
+from PIL import Image
+
+from fastapi import FastAPI, File, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+# ── Logging ───────────────────────────────────────────────────────────────────
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s  %(levelname)-8s  %(name)s  %(message)s",
+)
+logger = logging.getLogger("ocr-service")
+
+# ── Start time ────────────────────────────────────────────────────────────────
+_START_TIME: float = time.time()
+
+# ── Upload / batch limits ─────────────────────────────────────────────────��───
+MAX_UPLOAD_BYTES = 30 * 1024 * 1024   # 30 MB
+BATCH_MAX_FILES  = 8
+
+# ── File type sets ────────────────────────────────────────────────────────────
+PDF_EXTENSIONS          = {"pdf"}
+NATIVE_IMAGE_EXTENSIONS = {"jpg", "jpeg", "png"}
+PILLOW_IMAGE_EXTENSIONS = {"webp", "bmp", "tiff", "tif", "gif", "heic", "heif", "avif"}
+IMAGE_EXTENSIONS        = NATIVE_IMAGE_EXTENSIONS | PILLOW_IMAGE_EXTENSIONS
+OFFICE_EXTENSIONS       = {"docx", "pptx", "xlsx"}
+ALLOWED_EXTENSIONS      = PDF_EXTENSIONS | IMAGE_EXTENSIONS | OFFICE_EXTENSIONS
+
+# ── OCR tuning ────────────────────────────────────────────────────────────────
+FAST_CONFIDENCE_THRESHOLD = 0.65   # below this → MinerU fallback
+MAX_OCR_SIDE              = 1600   # pixels — longest side cap before OCR
+#                                  # General-purpose safe value.  Lowering to 1280 gains ~20%
+#                                  # speed but risks losing small text in UI/code screenshots:
+#                                  # a 1913px-wide screen at 1280px canvas → 11 px fonts scale
+#                                  # to ~8 px, which is the CRNN recognition floor.
+#                                  # Performance table (119 blocks, measured calibration 967 ms/batch):
+#                                  #   1600 px / batch=6  (pre-optimisation): ~19 300 ms
+#                                  #   1600 px / batch=24 (v4.1, this build): ~4 800 ms  (−75%)
+#                                  #   1280 px / batch=24 (marksheet-only):   ~3 900 ms  (−80%)
+#                                  # Set to 1280 only if all inputs are printed A4 documents.
+
+REC_BATCH_NUM             = 24     # recognition batch size (default in RapidOCR wheel: 6)
+#                                  # Higher → fewer sequential ONNX calls → faster.
+#                                  # 119 blocks / 6  = 20 calls  →  119 / 24 = 5 calls
+#                                  # Accuracy impact: NONE — same model, same crops, same CTC decode.
+#                                  # Memory impact: negligible on 16 GB HF free tier.
+
+DET_BOX_THRESH            = 0.50   # detection confidence threshold (RapidOCR default: 0.50)
+#                                  # Keep at 0.50 for general-purpose use.  Raising to 0.60 drops
+#                                  # ~15% of blocks (noise) and saves one ONNX call on dense docs,
+#                                  # but risks missing low-contrast text in UI/code screenshots
+#                                  # (dark-background text can score in the 0.50–0.65 range).
+#                                  # Safe to raise to 0.60–0.65 only for printed-document pipelines.
+
+# ── Memory safety ─────────────────────────────────────────────────────────────
+BYTES_PER_OCR_PAGE  = 100 * 1024 * 1024
+IMAGE_MEMORY_FACTOR = 4
+# 100 MB floor — was 1024.  psutil reads HOST RAM on HF Spaces (not the
+# container cgroup), so the floor must be small enough to pass on a busy
+# host that has only a few hundred MB of host-level free memory.  The
+# per-file estimate already encodes the request's working-memory cost;
+# this floor is purely a last-resort guard against near-empty headroom.
+MEM_SAFETY_FLOOR_MB = 100
+
+# ── SHA256 extraction cache ───────────────────────────────────────────────────
+_cache: dict[str, dict[str, Any]] = {}
+_cache_lock = threading.Lock()
+
+# ── Active-request counter ────────────────────────────────────────────────────
+_active_requests: int = 0
+_active_lock = threading.Lock()
+
+# ── Engine state ──────────────────────────────────────────────────────────────
+_rapidocr_engine:   Any  = None
+_rapidocr_lock            = threading.Lock()
+_rapidocr_load_ms: int   = 0
+_rapidocr_ready:   bool  = False
+
+_pipeline_ready:   bool  = False
+_pipeline_lock            = threading.Lock()
+_pipeline_load_ms: int   = 0
+
+# ── Startup issues ────────────────────────────────────────────────────────────
+_startup_issues: list[str] = []
+_startup_done:   bool      = False
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# Structured error
+# ═════════════════════════════════════════════════════════════════════════════
+class ExtractionError(Exception):
+    def __init__(
+        self,
+        stage: str,
+        code: str,
+        message: str,
+        http_status: int = 422,
+        root_cause: str = "",
+        recommendation: str = "",
+    ) -> None:
+        self.stage          = stage
+        self.code           = code
+        self.message        = message
+        self.http_status    = http_status
+        self.root_cause     = root_cause or message
+        self.recommendation = recommendation
+        super().__init__(message)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "success":        False,
+            "stage":          self.stage,
+            "errorCode":      self.code,
+            "rootCause":      self.root_cause,
+            "recommendation": self.recommendation,
+            "message":        self.message,
+        }
+
+
+def _err(
+    stage: str,
+    code: str,
+    msg: str,
+    status: int = 422,
+    root_cause: str = "",
+    recommendation: str = "",
+) -> ExtractionError:
+    return ExtractionError(stage, code, msg, status, root_cause, recommendation)
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# Active-request helpers
+# ═════════════════════════════════════════════════════════════════════════════
+def _inc_active() -> None:
+    global _active_requests
+    with _active_lock:
+        _active_requests += 1
+
+
+def _dec_active() -> None:
+    global _active_requests
+    with _active_lock:
+        _active_requests = max(0, _active_requests - 1)
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# Engine loaders
+# ═════════════════════════════════════════════════════════════════════════════
+def _ensure_rapidocr() -> Any:
+    """Load the RapidOCR engine once; return the singleton on every subsequent call."""
+    global _rapidocr_engine, _rapidocr_ready, _rapidocr_load_ms
+    if _rapidocr_ready:
+        return _rapidocr_engine
+    with _rapidocr_lock:
+        if _rapidocr_ready:
+            return _rapidocr_engine
+        t0 = time.perf_counter()
+        try:
+            from rapidocr_onnxruntime import RapidOCR
+            _rapidocr_engine = RapidOCR(
+                det_limit_side_len=MAX_OCR_SIDE,
+                det_limit_type="max",
+                # ── Recognition batch size ───────────────────────────────────
+                # Default in RapidOCR wheel is 6; 24 reduces ONNX calls by ~4×
+                # for typical documents (76 blocks → 4 calls instead of 13).
+                # Accuracy impact: zero — same CRNN model, same crops, same CTC.
+                rec_batch_num=REC_BATCH_NUM,
+                # ── Angle classifier disabled ────────────────────────────────
+                # Classifier (ch_ppocr_mobile_v2.0_cls_infer.onnx) runs a full
+                # ONNX pass on every crop to detect 180° rotation. For straight
+                # document scans (marksheets, certificates) this is pure overhead.
+                # Saves ~1 300 ms on 119 blocks (cls_batch_num=6 × ~65 ms/call).
+                # Re-enable if the service receives upside-down images.
+                use_cls=False,
+            )
+            _rapidocr_load_ms = int((time.perf_counter() - t0) * 1000)
+            _rapidocr_ready   = True
+            logger.info("RapidOCR engine ready  load_ms=%d", _rapidocr_load_ms)
+        except Exception as exc:
+            raise _err(
+                "model_load", "RAPIDOCR_LOAD_FAILED",
+                f"RapidOCR failed to load: {exc}", 503,
+                root_cause=str(exc),
+                recommendation="Check that rapidocr-onnxruntime is installed.",
+            ) from exc
+    return _rapidocr_engine
+
+
+def _ensure_pipeline() -> None:
+    """Import and verify the MinerU pipeline once."""
+    global _pipeline_ready, _pipeline_load_ms
+    if _pipeline_ready:
+        return
+    with _pipeline_lock:
+        if _pipeline_ready:
+            return
+        config_path = os.path.expanduser("~/magic-pdf.json")
+        if not os.path.exists(config_path):
+            raise _err(
+                "model_load", "CONFIG_MISSING",
+                f"magic-pdf.json not found at {config_path}.", 503,
+                root_cause="download_models.py did not run or /root was wiped.",
+                recommendation="Check Docker build log for download_models.py output.",
+            )
+        t0 = time.perf_counter()
+        try:
+            from magic_pdf.data.dataset import PymuDocDataset, ImageDataset  # noqa
+            from magic_pdf.data.data_reader_writer import (           # noqa
+                FileBasedDataReader, FileBasedDataWriter)
+        except ImportError as exc:
+            raise _err(
+                "model_load", "IMPORT_FAILED",
+                f"magic_pdf not importable: {exc}", 503,
+                root_cause=str(exc),
+                recommendation="Check that magic-pdf[full]==1.3.12 is installed.",
+            ) from exc
+        _pipeline_load_ms = int((time.perf_counter() - t0) * 1000)
+        _pipeline_ready   = True
+        logger.info("MinerU pipeline ready  load_ms=%d", _pipeline_load_ms)
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# FastAPI app
+# ═════════════════════════════════════════════════════════════════════════════
+app = FastAPI(
+    title="OpenSkill OCR Service",
+    description="OCR-only text extraction. Document understanding is handled by the AI layer.",
+    version="4.0.0",
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["GET", "POST"],
+    allow_headers=["*"],
+)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Startup — pre-load RapidOCR so first request has zero cold-start cost
+# ─────────────────────────────────────────────────────────────────────────────
+@app.on_event("startup")
+async def startup_warmup() -> None:
+    """
+    Pre-load the RapidOCR engine at container start.
+
+    Without this, the first /extract request pays 600–2 500 ms for ONNX model
+    loading on top of normal inference time. Loading here moves that cost to
+    startup where it is invisible to the user.
+    """
+    global _startup_done
+    issues: list[str] = []
+
+    # ── Dependency smoke-check ────────────────────────────────────────────────
+    checks = [
+        ("cv2",       lambda: __import__("cv2").__version__),
+        ("torch",     lambda: __import__("torch").__version__),
+        ("rapidocr",  lambda: pkg_version("rapidocr-onnxruntime")),
+        ("magic_pdf", lambda: __import__("magic_pdf").__version__),
+    ]
+    for name, fn in checks:
+        try:
+            ver = fn()
+            logger.info("startup ✓  %-12s  %s", name, ver)
+        except Exception as exc:
+            msg = f"{name} unavailable: {exc}"
+            issues.append(msg)
+            logger.critical("startup FAIL  %s", msg)
+
+    if not os.path.exists(os.path.expanduser("~/magic-pdf.json")):
+        issues.append("magic-pdf.json missing")
+    if not os.path.isdir("/app/models/PDF-Extract-Kit-1.0/models"):
+        issues.append("Models directory missing: /app/models/PDF-Extract-Kit-1.0/models")
+
+    # ── Pre-load RapidOCR ─────────────────────────────────────────────────────
+    try:
+        _ensure_rapidocr()
+        logger.info("startup: RapidOCR pre-loaded  load_ms=%d", _rapidocr_load_ms)
+    except Exception as exc:
+        msg = f"RapidOCR warmup failed: {exc}"
+        issues.append(msg)
+        logger.error("startup: %s", msg)
+
+    _startup_issues.extend(issues)
+    _startup_done = True
+    if issues:
+        logger.error("Startup completed with %d issue(s): %s", len(issues), issues)
+    else:
+        logger.info("Startup complete — all systems ready.")
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# GET /health
+# ═════════════════════════════════════════════════════════════════════════════
+@app.get("/health")
+def health() -> dict[str, Any]:
+    return {"status": "healthy", "version": "4.0.0"}
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# GET /status
+# ═════════════════════════════════════════════════════════════════════════════
+@app.get("/status")
+def status() -> dict[str, Any]:
+    used_mb, total_mb = _mem_mb()
+    return {
+        "status":         "healthy" if not _startup_issues else "degraded",
+        "version":        "4.0.0",
+        "architecture":   "ocr-only",
+        "engines": {
+            "rapidocr": {
+                "ready":   _rapidocr_ready,
+                "loadMs":  _rapidocr_load_ms,
+                "purpose": "images (1–4 s)",
+            },
+            "mineru": {
+                "ready":   _pipeline_ready,
+                "loadMs":  _pipeline_load_ms,
+                "purpose": "PDFs + fallback",
+            },
+        },
+        "config": {
+            "maxOcrSidePx":          MAX_OCR_SIDE,
+            "confidenceThreshold":   FAST_CONFIDENCE_THRESHOLD,
+            "maxUploadMb":           MAX_UPLOAD_BYTES // (1024 * 1024),
+        },
+        "startupIssues":  _startup_issues,
+        "uptimeSeconds":  int(time.time() - _START_TIME),
+        "memoryUsedMB":   used_mb,
+        "memoryTotalMB":  total_mb,
+        "activeRequests": _active_requests,
+        "cacheEntries":   len(_cache),
+    }
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# GET /warmup
+# ═════════════════════════════════════════════════════════════════════════════
+@app.get("/warmup")
+def warmup() -> dict[str, Any]:
+    """Explicitly pre-load engines. Idempotent — safe to call repeatedly."""
+    results: dict[str, Any] = {}
+    t0 = time.perf_counter()
+    try:
+        _ensure_rapidocr()
+        results["rapidocr"] = {"status": "ready", "loadMs": _rapidocr_load_ms}
+    except Exception as exc:
+        results["rapidocr"] = {"status": "failed", "error": str(exc)}
+    try:
+        _ensure_pipeline()
+        results["mineru"] = {"status": "ready", "loadMs": _pipeline_load_ms}
+    except Exception as exc:
+        results["mineru"] = {"status": "failed", "error": str(exc)}
+    results["totalElapsedMs"] = int((time.perf_counter() - t0) * 1000)
+    results["allReady"] = _rapidocr_ready and _pipeline_ready
+    return results
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# GET /diagnostics
+# ═════════════════════════════════════════════════════════════════════════════
+@app.get("/diagnostics")
+def diagnostics() -> dict[str, Any]:
+    import platform
+    pkgs: dict[str, str] = {}
+    for name in (
+        "magic-pdf", "rapidocr-onnxruntime", "torch", "torchvision",
+        "ultralytics", "doclayout-yolo", "rapid-table", "onnxruntime",
+        "opencv-python-headless", "Pillow", "fastapi", "uvicorn",
+    ):
+        try:
+            pkgs[name] = pkg_version(name)
+        except Exception:
+            pkgs[name] = "not found"
+
+    models_root = "/app/models/PDF-Extract-Kit-1.0/models"
+    model_files: dict[str, str] = {}
+    for rel in [
+        "OCR/paddleocr_torch/ch_PP-OCRv5_det_infer.pth",
+        "OCR/paddleocr_torch/ch_PP-OCRv5_rec_infer.pth",
+        "Layout/YOLO/doclayout_yolo_docstructbench_imgsz1280_2501.pt",
+    ]:
+        full = os.path.join(models_root, rel)
+        model_files[rel] = (
+            f"{os.path.getsize(full) / (1024 * 1024):.1f} MB"
+            if os.path.isfile(full) else "MISSING"
+        )
+
+    used_mb, total_mb = _mem_mb()
+    return {
+        "python":     platform.python_version(),
+        "packages":   pkgs,
+        "modelFiles": model_files,
+        "memory":     {"usedMB": used_mb, "totalMB": total_mb},
+        "engines": {
+            "rapidocr": {"ready": _rapidocr_ready, "loadMs": _rapidocr_load_ms},
+            "mineru":   {"ready": _pipeline_ready, "loadMs": _pipeline_load_ms},
+        },
+        "config": {
+            "maxOcrSidePx":        MAX_OCR_SIDE,
+            "confidenceThreshold": FAST_CONFIDENCE_THRESHOLD,
+        },
+        "uptime":       int(time.time() - _START_TIME),
+        "cacheEntries": len(_cache),
+    }
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# GET /benchmark
+# Runs RapidOCR on three synthetic images (small / medium / large) and returns
+# full stage timings for each. Use this to measure the resize optimisation.
+# ═════════════════════════════════════════════════════════════════════════════
+@app.get("/benchmark")
+async def benchmark() -> JSONResponse:
+    import cv2
+
+    def _make_test_image(width: int, height: int) -> "np.ndarray":
+        img = np.ones((height, width, 3), dtype=np.uint8) * 255
+        lines = [
+            "184 ENGLISH LNG & LIT.  073  020  093",
+            "085 HINDI COURSE-B      075  020  095",
+            "041 MATHEMATICS STD     063  020  083",
+            "086 SCIENCE             065  020  085",
+            "087 SOCIAL SCIENCE      057  020  077",
+            "Roll No: 28169763   Name: TEST STUDENT",
+            "Total: 433 / 500   Percentage: 86.6%",
+        ]
+        line_h = max(20, height // (len(lines) + 2))
+        scale  = max(0.5, min(1.5, width / 900))
+        for i, text in enumerate(lines):
+            y = line_h * (i + 1)
+            if y < height - 10:
+                cv2.putText(img, text, (20, y),
+                            cv2.FONT_HERSHEY_SIMPLEX, scale, (0, 0, 0), 2)
+        return img
+
+    SIZES = [
+        ("small",  800,  1200),
+        ("medium", 1600, 2400),
+        ("large",  3000, 4000),
+    ]
+    results: dict[str, Any] = {}
+
+    engine = _ensure_rapidocr()
+
+    for label, w, h in SIZES:
+        img = _make_test_image(w, h)
+        orig_h, orig_w = img.shape[:2]
+
+        # Resize
+        t_resize = time.perf_counter()
+        img_resized, was_resized = _resize_for_ocr(img)
+        resize_ms = int((time.perf_counter() - t_resize) * 1000)
+        new_h, new_w = img_resized.shape[:2]
+
+        # OCR
+        t_ocr = time.perf_counter()
+        ocr_result, elapse = engine(img_resized, box_thresh=DET_BOX_THRESH)
+        ocr_ms = int((time.perf_counter() - t_ocr) * 1000)
+
+        det_ms, rec_ms = _split_elapse(elapse, ocr_ms)
+        texts  = [item[1] for item in (ocr_result or []) if len(item) > 1]
+        scores = [item[2] for item in (ocr_result or []) if len(item) > 2 and item[2] is not None]
+        conf   = round(sum(scores) / len(scores), 4) if scores else 0.0
+
+        results[label] = {
+            "originalDimensions":  f"{orig_w}×{orig_h}",
+            "resizedDimensions":   f"{new_w}×{new_h}",
+            "wasResized":          was_resized,
+            "resizeMs":            resize_ms,
+            "detectMs":            det_ms,
+            "recognizeMs":         rec_ms,
+            "ocrTotalMs":          ocr_ms,
+            "textBlocks":          len(texts),
+            "confidence":          conf,
+        }
+
+    used_mb, total_mb = _mem_mb()
+    return JSONResponse(content={
+        "results":   results,
+        "memory":    {"usedMB": used_mb, "totalMB": total_mb},
+        "maxOcrSide": MAX_OCR_SIDE,
+        "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    })
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# POST /extract
+# ═════════════════════════════════════════════════════════════════════════════
+@app.post("/extract")
+async def extract(file: UploadFile = File(...)) -> JSONResponse:
+    t_upload_start = time.perf_counter()
+    try:
+        raw, filename, ext = await _read_upload(file)
+        upload_ms = int((time.perf_counter() - t_upload_start) * 1000)
+        result = _run_extraction(raw, filename, ext, upload_ms=upload_ms)
+        return JSONResponse(content=result)
+    except ExtractionError as exc:
+        logger.warning("/extract [%s/%s]: %s", exc.stage, exc.code, exc.message)
+        return JSONResponse(status_code=exc.http_status, content=exc.to_dict())
+    except Exception as exc:
+        logger.exception("/extract unhandled error")
+        return JSONResponse(
+            status_code=500,
+            content={
+                "success":        False,
+                "stage":          "unknown",
+                "errorCode":      "INTERNAL_ERROR",
+                "rootCause":      str(exc),
+                "recommendation": "Check HF Space logs for full traceback.",
+                "message":        str(exc),
+                "traceback":      traceback.format_exc()[-3000:],
+            },
+        )
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# POST /batch
+# ═════════════════════════════════════════════════════════════════════════════
+@app.post("/batch")
+async def batch(files: list[UploadFile] = File(...)) -> JSONResponse:
+    candidates = files[:BATCH_MAX_FILES]
+    results: list[dict[str, Any]] = []
+    for upload in candidates:
+        t0 = time.perf_counter()
+        try:
+            raw, filename, ext = await _read_upload(upload)
+            result = _run_extraction(
+                raw, filename, ext,
+                upload_ms=int((time.perf_counter() - t0) * 1000),
+            )
+        except ExtractionError as exc:
+            result = exc.to_dict()
+            result["filename"] = _sanitize_filename(upload.filename or "upload")
+        except Exception as exc:
+            fname = _sanitize_filename(upload.filename or "upload")
+            logger.exception("Batch item failed: %s", fname)
+            result = {
+                "success":        False,
+                "filename":       fname,
+                "stage":          "unknown",
+                "errorCode":      "INTERNAL_ERROR",
+                "rootCause":      str(exc),
+                "recommendation": "Check HF Space logs.",
+                "message":        str(exc),
+            }
+        results.append(result)
+    return JSONResponse(content={
+        "success":   True,
+        "processed": len(results),
+        "results":   results,
+    })
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# Upload reader
+# ═════════════════════════════════════════════════════════════════════════════
+async def _read_upload(upload: UploadFile) -> tuple[bytes, str, str]:
+    filename = _sanitize_filename(upload.filename or "upload")
+    ext = filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
+
+    if ext not in ALLOWED_EXTENSIONS:
+        raise _err(
+            "validation", "UNSUPPORTED_TYPE",
+            f"Unsupported file type '.{ext}'. "
+            f"Supported: {sorted(ALLOWED_EXTENSIONS)}",
+            415,
+            root_cause=f"Extension '{ext}' is not in the allowed set.",
+            recommendation="Convert to PDF, JPG, PNG, or WEBP before uploading.",
+        )
+    raw = await upload.read(MAX_UPLOAD_BYTES + 1)
+    if len(raw) > MAX_UPLOAD_BYTES:
+        raise _err(
+            "upload", "FILE_TOO_LARGE",
+            f"'{filename}' exceeds {MAX_UPLOAD_BYTES // 1024 // 1024} MB.", 413,
+            root_cause=f"File is {len(raw) // 1024 // 1024} MB.",
+            recommendation="Compress or split the file.",
+        )
+    if len(raw) == 0:
+        raise _err("upload", "EMPTY_FILE", f"'{filename}' is empty.", 400,
+                   root_cause="Zero bytes received.",
+                   recommendation="Check the file before uploading.")
+    return raw, filename, ext
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# Extraction dispatcher
+# ═════════════════════════════════════════════════════════════════════════════
+def _run_extraction(
+    raw: bytes, filename: str, ext: str, upload_ms: int = 0
+) -> dict[str, Any]:
+    logger.info("request_received  file=%s  size=%d  ext=%s", filename, len(raw), ext)
+
+    # ── Hash + cache lookup ───────────────────────────────────────────────────
+    t_hash = time.perf_counter()
+    file_hash = hashlib.sha256(raw).hexdigest()
+    hash_ms = int((time.perf_counter() - t_hash) * 1000)
+    logger.info("cache_lookup  sha256=%.12s…  hash_ms=%d", file_hash, hash_ms)
+
+    with _cache_lock:
+        cached = _cache.get(file_hash)
+    if cached is not None:
+        logger.info("cache_hit  sha256=%.12s…  file=%s", file_hash, filename)
+        out = {**cached}
+        out["cached"]          = True
+        out["processingTimeMs"] = 0
+        out["timings"]         = {**cached.get("timings", {}), "totalMs": 0}
+        return out
+
+    logger.info("cache_miss  sha256=%.12s…", file_hash)
+
+    # ── Memory safety ─────���───────────────────────────────────────────────────
+    t_mem = time.perf_counter()
+    _assert_memory_safe(raw, ext)
+    mem_check_ms = int((time.perf_counter() - t_mem) * 1000)
+
+    _inc_active()
+    work_dir = tempfile.mkdtemp(prefix="ocr_")
+    t0 = time.perf_counter()
+    try:
+        if ext in PDF_EXTENSIONS:
+            logger.info("engine_selected  engine=mineru  file=%s", filename)
+            _ensure_pipeline()
+            result = _process_pdf(raw, filename, work_dir, upload_ms=upload_ms)
+        elif ext in OFFICE_EXTENSIONS:
+            logger.info("engine_selected  engine=office_text  file=%s  ext=%s", filename, ext)
+            result = _process_office(raw, filename, ext, upload_ms=upload_ms)
+        else:
+            logger.info("engine_selected  engine=rapidocr  file=%s", filename)
+            result = _process_image(raw, filename, ext, work_dir, upload_ms=upload_ms)
+
+        total_ms = int((time.perf_counter() - t0) * 1000)
+        result["timings"]["uploadMs"]  = upload_ms
+        result["timings"]["hashMs"]    = hash_ms
+        result["timings"]["memCheckMs"] = mem_check_ms
+        result["timings"]["totalMs"]   = total_ms
+        result["processingTimeMs"]     = total_ms
+        result["cached"]               = False
+
+        # Store in cache (strip per-request fields that change on replay)
+        entry = {k: v for k, v in result.items()
+                 if k not in ("cached", "processingTimeMs", "timings")}
+        entry["timings"] = {k: v for k, v in result["timings"].items()
+                            if k not in ("totalMs", "hashMs", "memCheckMs", "uploadMs")}
+        with _cache_lock:
+            _cache[file_hash] = entry
+
+        logger.info(
+            "response_sent  file=%s  engine=%s  conf=%.3f  total_ms=%d",
+            filename, result.get("engine", "?"), result.get("confidence", 0), total_ms,
+        )
+        return result
+
+    except ExtractionError:
+        raise
+    except Exception as exc:
+        logger.exception("extraction_failed  file=%s", filename)
+        raise _err(
+            "unknown", "INTERNAL_ERROR", f"Unexpected error: {exc}", 500,
+            root_cause=str(exc),
+            recommendation="Check HF Space logs for full traceback.",
+        ) from exc
+    finally:
+        _dec_active()
+        shutil.rmtree(work_dir, ignore_errors=True)
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# Image processor — RapidOCR fast path + MinerU fallback
+# ═════════════════════════════════════════════════════════════════════════════
+def _process_image(
+    raw: bytes, filename: str, ext: str, work_dir: str, upload_ms: int = 0
+) -> dict[str, Any]:
+    import cv2
+
+    # ── Decode ────────────────────────────────────────────────────────────────
+    t_decode = time.perf_counter()
+    img_bgr = _decode_image_to_bgr(raw, ext)
+    decode_ms = int((time.perf_counter() - t_decode) * 1000)
+    orig_h, orig_w = img_bgr.shape[:2]
+    logger.info("image_decoded  file=%s  dims=%dx%d  decode_ms=%d",
+                filename, orig_w, orig_h, decode_ms)
+
+    # ── Resize ────────────────────────────────────────────────────────────────
+    t_resize = time.perf_counter()
+    img_ocr, was_resized = _resize_for_ocr(img_bgr)
+    resize_ms = int((time.perf_counter() - t_resize) * 1000)
+    new_h, new_w = img_ocr.shape[:2]
+    logger.info("image_resized  file=%s  original=%dx%d  resized=%dx%d"
+                "  was_resized=%s  resize_ms=%d",
+                filename, orig_w, orig_h, new_w, new_h, was_resized, resize_ms)
+
+    # ── RapidOCR ──────────────────────────────────────────────────────────────
+    logger.info("ocr_started  file=%s  engine=rapidocr  dims=%dx%d",
+                filename, new_w, new_h)
+    t_ocr = time.perf_counter()
+    try:
+        engine = _ensure_rapidocr()
+        # box_thresh: drops detection boxes below this confidence BEFORE recognition.
+        # Zero recognition cost for dropped boxes. See DET_BOX_THRESH constant.
+        ocr_result, elapse = engine(img_ocr, box_thresh=DET_BOX_THRESH)
+    except ExtractionError:
+        raise
+    except Exception as exc:
+        raise _err(
+            "ocr", "OCR_ENGINE_FAILED", f"RapidOCR failed: {exc}", 500,
+            root_cause=str(exc),
+            recommendation="Check rapidocr-onnxruntime in Dockerfile Layer 1.",
+        ) from exc
+    ocr_ms = int((time.perf_counter() - t_ocr) * 1000)
+    det_ms, rec_ms = _split_elapse(elapse, ocr_ms)
+    logger.info("ocr_finished  file=%s  engine=rapidocr  ocr_ms=%d"
+                "  det_ms=%d  rec_ms=%d", filename, ocr_ms, det_ms, rec_ms)
+
+    # ── Parse output ──────────────────────────────────────────────────────────
+    t_post = time.perf_counter()
+    plain_text, confidence = _parse_rapidocr_output(ocr_result)
+    post_ms = int((time.perf_counter() - t_post) * 1000)
+    logger.info("post_process  file=%s  conf=%.3f  text_len=%d  blocks=%d  post_ms=%d",
+                filename, confidence, len(plain_text),
+                len(ocr_result) if ocr_result else 0, post_ms)
+
+    # ── MinerU fallback if confidence is low ──────────────────────────────────
+    passes_used = 1
+    engine_name = "rapidocr"
+    if confidence < FAST_CONFIDENCE_THRESHOLD and plain_text.strip():
+        logger.info(
+            "fallback_triggered  conf=%.3f < %.2f  file=%s  trying mineru",
+            confidence, FAST_CONFIDENCE_THRESHOLD, filename,
+        )
+        try:
+            _ensure_pipeline()
+            mr = _process_image_mineru(raw, filename, ext, work_dir)
+            if len(mr.get("text", "")) > len(plain_text) * 0.8:
+                mr["engine"]             = "mineru_fallback"
+                mr["metadata"]["passesUsed"] = 2
+                mr["timings"]["pass1RapidOCRMs"] = ocr_ms
+                mr["timings"]["decodeMs"]        = decode_ms
+                mr["timings"]["resizeMs"]        = resize_ms
+                logger.info("fallback_used  file=%s  mineru result accepted", filename)
+                return mr
+        except Exception as exc:
+            logger.warning("fallback_failed  file=%s  error=%s  using rapidocr result", filename, exc)
+        passes_used = 2
+    else:
+        logger.info("fallback_not_needed  conf=%.3f  file=%s", confidence, filename)
+
+    return {
+        "success":    True,
+        "filename":   filename,
+        "engine":     engine_name,
+        "confidence": confidence,
+        "text":       plain_text,
+        "markdown":   plain_text,
+        "pageCount":  1,
+        "timings": {
+            "uploadMs":     upload_ms,
+            "hashMs":       0,
+            "memCheckMs":   0,
+            "decodeMs":     decode_ms,
+            "resizeMs":     resize_ms,
+            "detectMs":     det_ms,
+            "recognizeMs":  rec_ms,
+            "postProcessMs": post_ms,
+            "totalMs":      0,
+        },
+        "metadata": {
+            "imgW":       orig_w,
+            "imgH":       orig_h,
+            "imgWResized": new_w,
+            "imgHResized": new_h,
+            "wasResized":  was_resized,
+            "textBlocks":  len(ocr_result) if ocr_result else 0,
+            "passesUsed":  passes_used,
+            "backend":     "rapidocr",
+        },
+    }
+
+
+def _process_image_mineru(
+    raw: bytes, filename: str, ext: str, work_dir: str
+) -> dict[str, Any]:
+    from magic_pdf.data.data_reader_writer import (
+        FileBasedDataReader, FileBasedDataWriter)
+    from magic_pdf.data.dataset import ImageDataset
+    from magic_pdf.model.doc_analyze_by_custom_model import doc_analyze
+
+    images_dir = os.path.join(work_dir, "images_mineru")
+    os.makedirs(images_dir, exist_ok=True)
+
+    if ext in PILLOW_IMAGE_EXTENSIONS:
+        raw = _convert_to_png(raw, ext)
+        save_ext = "png"
+    else:
+        save_ext = ext
+
+    img_path = os.path.join(work_dir, f"input_mineru.{save_ext}")
+    with open(img_path, "wb") as fh:
+        fh.write(raw)
+
+    t_ocr = time.perf_counter()
+    try:
+        reader       = FileBasedDataReader(work_dir)
+        image_bytes  = reader.read(f"input_mineru.{save_ext}")
+        ds           = ImageDataset(image_bytes)
+        infer_result = ds.apply(doc_analyze, ocr=True)
+        pipe_result  = infer_result.pipe_ocr_mode(FileBasedDataWriter(images_dir))
+    except Exception as exc:
+        raise _err(
+            "ocr", "OCR_PIPELINE_FAILED",
+            f"MinerU image pipeline failed: {exc}", 500,
+            root_cause=str(exc),
+            recommendation="Check magic-pdf installation and model files.",
+        ) from exc
+    ocr_ms = int((time.perf_counter() - t_ocr) * 1000)
+
+    t_md = time.perf_counter()
+    try:
+        markdown = pipe_result.get_markdown(images_dir)
+    except Exception as exc:
+        raise _err("markdown", "MARKDOWN_FAILED", f"get_markdown failed: {exc}") from exc
+    md_ms = int((time.perf_counter() - t_md) * 1000)
+
+    plain_text = _markdown_to_plain(markdown)
+
+    return {
+        "success":    True,
+        "filename":   filename,
+        "engine":     "mineru",
+        "confidence": 0.85,
+        "text":       plain_text,
+        "markdown":   markdown,
+        "pageCount":  1,
+        "timings": {
+            "uploadMs":      0,
+            "hashMs":        0,
+            "memCheckMs":    0,
+            "decodeMs":      0,
+            "resizeMs":      0,
+            "detectMs":      0,
+            "recognizeMs":   ocr_ms,
+            "postProcessMs": md_ms,
+            "totalMs":       0,
+        },
+        "metadata": {
+            "imgW": 0, "imgH": 0,
+            "imgWResized": 0, "imgHResized": 0,
+            "wasResized":  False,
+            "textBlocks":  0,
+            "passesUsed":  1,
+            "backend":     "pipeline",
+        },
+    }
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# Office document processor — DOCX / PPTX / XLSX (text extraction, no OCR)
+# No image rendering or OCR is performed. Text is read directly from the
+# structured XML inside the Office Open XML container.
+# ═════════════════════════════════════════════════════════════════════════════
+def _process_office(
+    raw: bytes, filename: str, ext: str, upload_ms: int = 0
+) -> dict[str, Any]:
+    t0 = time.perf_counter()
+    logger.info("ocr_started  file=%s  engine=office_text  ext=%s", filename, ext)
+
+    try:
+        if ext == "docx":
+            plain_text, page_count = _extract_docx(raw)
+        elif ext == "pptx":
+            plain_text, page_count = _extract_pptx(raw)
+        elif ext == "xlsx":
+            plain_text, page_count = _extract_xlsx(raw)
+        else:
+            raise _err("decode", "UNSUPPORTED_OFFICE_TYPE",
+                       f"Unrecognised office extension: {ext}", 415)
+    except ExtractionError:
+        raise
+    except Exception as exc:
+        raise _err(
+            "ocr", "OFFICE_EXTRACT_FAILED",
+            f"Could not extract text from {ext.upper()}: {exc}", 422,
+            root_cause=str(exc),
+            recommendation=f"Ensure the file is a valid, non-password-protected {ext.upper()}.",
+        ) from exc
+
+    extract_ms = int((time.perf_counter() - t0) * 1000)
+    logger.info("ocr_finished  file=%s  engine=office_text  extract_ms=%d  text_len=%d",
+                filename, extract_ms, len(plain_text))
+
+    return {
+        "success":    True,
+        "filename":   filename,
+        "engine":     f"office_text_{ext}",
+        "confidence": 1.0,
+        "text":       plain_text,
+        "markdown":   plain_text,
+        "pageCount":  page_count,
+        "timings": {
+            "uploadMs":      upload_ms,
+            "hashMs":        0,
+            "memCheckMs":    0,
+            "decodeMs":      0,
+            "resizeMs":      0,
+            "detectMs":      0,
+            "recognizeMs":   extract_ms,
+            "postProcessMs": 0,
+            "totalMs":       0,
+        },
+        "metadata": {
+            "imgW": 0, "imgH": 0,
+            "imgWResized": 0, "imgHResized": 0,
+            "wasResized":  False,
+            "textBlocks":  plain_text.count("\n") + 1,
+            "passesUsed":  1,
+            "backend":     f"office_text_{ext}",
+        },
+    }
+
+
+def _extract_docx(raw: bytes) -> tuple[str, int]:
+    """Extract plain text from a DOCX file. Returns (text, page_estimate)."""
+    try:
+        import docx as _docx
+    except ImportError as exc:
+        raise _err("decode", "DOCX_DEPS_MISSING",
+                   "python-docx is not installed.", 503,
+                   recommendation="Add python-docx to Dockerfile Layer 1.") from exc
+    doc = _docx.Document(io.BytesIO(raw))
+    paragraphs = [p.text for p in doc.paragraphs if p.text.strip()]
+    # Tables
+    for table in doc.tables:
+        for row in table.rows:
+            row_text = "  |  ".join(
+                cell.text.strip() for cell in row.cells if cell.text.strip()
+            )
+            if row_text:
+                paragraphs.append(row_text)
+    text = "\n".join(paragraphs)
+    # Rough page estimate: ~3 000 chars per page
+    pages = max(1, len(text) // 3000)
+    return text, pages
+
+
+def _extract_pptx(raw: bytes) -> tuple[str, int]:
+    """Extract plain text from a PPTX file. Returns (text, slide_count)."""
+    try:
+        from pptx import Presentation as _Presentation
+    except ImportError as exc:
+        raise _err("decode", "PPTX_DEPS_MISSING",
+                   "python-pptx is not installed.", 503,
+                   recommendation="Add python-pptx to Dockerfile Layer 1.") from exc
+    prs   = _Presentation(io.BytesIO(raw))
+    lines: list[str] = []
+    for slide_num, slide in enumerate(prs.slides, 1):
+        lines.append(f"--- Slide {slide_num} ---")
+        for shape in slide.shapes:
+            if hasattr(shape, "text") and shape.text.strip():
+                lines.append(shape.text.strip())
+    return "\n".join(lines), len(prs.slides)
+
+
+def _extract_xlsx(raw: bytes) -> tuple[str, int]:
+    """Extract plain text from an XLSX file. Returns (text, sheet_count)."""
+    try:
+        import openpyxl as _openpyxl
+    except ImportError as exc:
+        raise _err("decode", "XLSX_DEPS_MISSING",
+                   "openpyxl is not installed.", 503,
+                   recommendation="Add openpyxl to Dockerfile Layer 1.") from exc
+    wb    = _openpyxl.load_workbook(io.BytesIO(raw), read_only=True, data_only=True)
+    lines: list[str] = []
+    for sheet in wb.worksheets:
+        lines.append(f"--- Sheet: {sheet.title} ---")
+        for row in sheet.iter_rows(values_only=True):
+            row_text = "  |  ".join(
+                str(cell) for cell in row if cell is not None and str(cell).strip()
+            )
+            if row_text:
+                lines.append(row_text)
+    wb.close()
+    return "\n".join(lines), len(wb.worksheets)
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# PDF processor — MinerU
+# ═════════════════════════════════════════════════════════════════════════════
+def _process_pdf(
+    raw: bytes, filename: str, work_dir: str, upload_ms: int = 0
+) -> dict[str, Any]:
+    from magic_pdf.data.data_reader_writer import FileBasedDataWriter
+    from magic_pdf.data.dataset import PymuDocDataset
+    from magic_pdf.model.doc_analyze_by_custom_model import doc_analyze
+    from magic_pdf.config.enums import SupportedPdfParseMethod
+
+    images_dir = os.path.join(work_dir, "images")
+    os.makedirs(images_dir, exist_ok=True)
+    page_count = _pdf_page_count(raw)
+
+    logger.info("pdf_classify  file=%s  pages=%d", filename, page_count)
+    t_classify = time.perf_counter()
+    try:
+        ds     = PymuDocDataset(raw)
+        method = ds.classify()
+    except Exception as exc:
+        raise _err(
+            "decode", "PDF_PARSE_FAILED", f"Could not parse PDF: {exc}", 422,
+            root_cause=str(exc),
+            recommendation="Ensure the file is a valid, non-encrypted PDF.",
+        ) from exc
+    classify_ms = int((time.perf_counter() - t_classify) * 1000)
+
+    logger.info("ocr_started  file=%s  engine=mineru  method=%s", filename, method)
+    t_ocr = time.perf_counter()
+    try:
+        image_writer = FileBasedDataWriter(images_dir)
+        if method == SupportedPdfParseMethod.TXT:
+            infer_result = ds.apply(doc_analyze, ocr=False)
+            pipe_result  = infer_result.pipe_txt_mode(image_writer)
+            parse_method = "txt"
+        else:
+            infer_result = ds.apply(doc_analyze, ocr=True)
+            pipe_result  = infer_result.pipe_ocr_mode(image_writer)
+            parse_method = "ocr"
+    except Exception as exc:
+        raise _err(
+            "ocr", "OCR_PIPELINE_FAILED", f"doc_analyze/pipe failed: {exc}", 500,
+            root_cause=str(exc),
+            recommendation="Check model files in /app/models and validate.py output.",
+        ) from exc
+    ocr_ms = int((time.perf_counter() - t_ocr) * 1000)
+    logger.info("ocr_finished  file=%s  engine=mineru  ocr_ms=%d", filename, ocr_ms)
+
+    t_md = time.perf_counter()
+    try:
+        markdown = pipe_result.get_markdown(images_dir)
+    except Exception as exc:
+        raise _err("markdown", "MARKDOWN_FAILED", f"get_markdown failed: {exc}") from exc
+    md_ms = int((time.perf_counter() - t_md) * 1000)
+
+    plain_text = _markdown_to_plain(markdown)
+
+    return {
+        "success":    True,
+        "filename":   filename,
+        "engine":     "mineru",
+        "confidence": 0.9 if parse_method == "txt" else 0.85,
+        "text":       plain_text,
+        "markdown":   markdown,
+        "pageCount":  page_count,
+        "timings": {
+            "uploadMs":      upload_ms,
+            "hashMs":        0,
+            "memCheckMs":    0,
+            "decodeMs":      classify_ms,
+            "resizeMs":      0,
+            "detectMs":      0,
+            "recognizeMs":   ocr_ms,
+            "postProcessMs": md_ms,
+            "totalMs":       0,
+        },
+        "metadata": {
+            "imgW": 0, "imgH": 0,
+            "imgWResized": 0, "imgHResized": 0,
+            "wasResized":  False,
+            "textBlocks":  0,
+            "passesUsed":  1,
+            "backend":     "pipeline",
+            "parseMethod": parse_method,
+            "pages":       page_count,
+        },
+    }
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# Image helpers
+# ════════��════════════════════════════════════════════════════════════════════
+def _resize_for_ocr(img: "np.ndarray") -> tuple["np.ndarray", bool]:
+    """
+    Resize image so the longest side is at most MAX_OCR_SIDE pixels.
+
+    Returns (resized_img, was_resized).
+
+    Uses cv2.INTER_AREA which is the correct algorithm for downscaling:
+    it averages pixels (anti-aliasing) rather than sampling individual pixels,
+    preserving text legibility at smaller sizes.
+
+    No upscaling: images smaller than MAX_OCR_SIDE are returned unchanged.
+    """
+    import cv2
+    h, w = img.shape[:2]
+    longest = max(h, w)
+    if longest <= MAX_OCR_SIDE:
+        return img, False
+    scale     = MAX_OCR_SIDE / longest
+    new_w     = int(w * scale)
+    new_h     = int(h * scale)
+    resized   = cv2.resize(img, (new_w, new_h), interpolation=cv2.INTER_AREA)
+    return resized, True
+
+
+def _decode_image_to_bgr(raw: bytes, ext: str) -> "np.ndarray":
+    import cv2
+    if ext in {"heic", "heif"}:
+        try:
+            from pillow_heif import register_heif_opener
+            register_heif_opener()
+        except ImportError:
+            raise _err(
+                "decode", "HEIF_NOT_SUPPORTED",
+                "HEIC/HEIF requires pillow-heif.", 415,
+                recommendation="Add pillow-heif to Dockerfile Layer 1.",
+            )
+        try:
+            pil_img = Image.open(io.BytesIO(raw)).convert("RGB")
+            buf = io.BytesIO()
+            pil_img.save(buf, format="PNG")
+            raw = buf.getvalue()
+        except Exception as exc:
+            raise _err("decode", "HEIF_DECODE_FAILED",
+                       f"HEIF decode error: {exc}") from exc
+
+    arr = np.frombuffer(raw, np.uint8)
+    img = cv2.imdecode(arr, cv2.IMREAD_COLOR)
+    if img is None:
+        try:
+            pil_img = Image.open(io.BytesIO(raw)).convert("RGB")
+            img = cv2.cvtColor(np.array(pil_img), cv2.COLOR_RGB2BGR)
+        except Exception as exc:
+            raise _err(
+                "decode", "IMAGE_DECODE_FAILED",
+                f"Could not decode image: {exc}", 422,
+                root_cause=str(exc),
+                recommendation="Ensure the file is a valid, non-corrupted image.",
+            ) from exc
+    return img
+
+
+def _convert_to_png(raw: bytes, ext: str) -> bytes:
+    if ext in {"heic", "heif"}:
+        try:
+            from pillow_heif import register_heif_opener
+            register_heif_opener()
+        except ImportError:
+            raise _err("decode", "HEIF_NOT_SUPPORTED",
+                       "HEIC/HEIF requires pillow-heif.", 415)
+    try:
+        img = Image.open(io.BytesIO(raw)).convert("RGB")
+        buf = io.BytesIO()
+        img.save(buf, format="PNG")
+        return buf.getvalue()
+    except Exception as exc:
+        raise _err("decode", "IMAGE_DECODE_FAILED",
+                   f"Pillow could not open image: {exc}", 422) from exc
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# RapidOCR output parser
+# Returns (plain_text, mean_confidence)
+# ═════════════════════════════════════════════════════════════════════════════
+def _parse_rapidocr_output(result: Any) -> tuple[str, float]:
+    if not result:
+        return "", 0.0
+
+    def _avg_y(item: Any) -> float:
+        box = item[0]
+        try:
+            return sum(pt[1] for pt in box) / 4
+        except Exception:
+            return 0.0
+
+    def _avg_x(item: Any) -> float:
+        box = item[0]
+        try:
+            return sum(pt[0] for pt in box) / 4
+        except Exception:
+            return 0.0
+
+    sorted_items = sorted(result, key=_avg_y)
+
+    LINE_GAP = 20
+    lines: list[list[Any]] = []
+    if sorted_items:
+        current: list[Any] = [sorted_items[0]]
+        for item in sorted_items[1:]:
+            if abs(_avg_y(item) - _avg_y(current[-1])) < LINE_GAP:
+                current.append(item)
+            else:
+                lines.append(current)
+                current = [item]
+        lines.append(current)
+
+    text_lines: list[str] = []
+    for line in lines:
+        words = sorted(line, key=_avg_x)
+        text_lines.append("  ".join(str(item[1]) for item in words if len(item) > 1))
+
+    plain_text = "\n".join(text_lines)
+    scores     = [item[2] for item in result if len(item) > 2 and item[2] is not None]
+    mean_conf  = float(sum(scores) / len(scores)) if scores else 0.5
+    return plain_text, round(mean_conf, 4)
+
+
+def _split_elapse(elapse: Any, total_ms: int) -> tuple[int, int]:
+    """
+    Extract det_ms / rec_ms from RapidOCR's elapse return value.
+
+    rapidocr-onnxruntime ≥ 1.3 returns a dict: {"det": s, "rec": s, "cls": s}.
+    Older versions return a scalar total. We handle both.
+    """
+    if isinstance(elapse, dict):
+        det_ms = int(elapse.get("det", 0) * 1000)
+        rec_ms = int(elapse.get("rec", 0) * 1000)
+        return det_ms, rec_ms
+    # Scalar fallback — measured total, no reliable split available
+    return 0, total_ms
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# Misc helpers
+# ═════════════════════════════════════════════════════════════════════════════
+def _sanitize_filename(name: str) -> str:
+    name = os.path.basename(name)
+    name = re.sub(r"[^\w.\-]", "_", name)
+    return name[:200] or "upload"
+
+
+def _markdown_to_plain(markdown: str) -> str:
+    text = re.sub(r"!\[.*?\]\(.*?\)", "", markdown)
+    text = re.sub(r"\[([^\]]+)\]\([^\)]+\)", r"\1", text)
+    text = re.sub(r"#{1,6}\s*", "", text)
+    text = re.sub(r"\*{1,2}([^*]+)\*{1,2}", r"\1", text)
+    text = re.sub(r"`{1,3}[^`]*`{1,3}", "", text)
+    text = re.sub(r"\|", " ", text)
+    text = re.sub(r"-{3,}", "", text)
+    text = re.sub(r"\n{3,}", "\n\n", text)
+    return text.strip()
+
+
+def _pdf_page_count(raw: bytes) -> int:
+    try:
+        doc   = fitz.open(stream=raw, filetype="pdf")
+        count = doc.page_count
+        doc.close()
+        return count
+    except Exception:
+        return 1
+
+
+def _mem_mb() -> tuple[int, int]:
+    try:
+        import psutil
+        vm = psutil.virtual_memory()
+        return (vm.total - vm.available) // (1024 * 1024), vm.total // (1024 * 1024)
+    except Exception:
+        pass
+    try:
+        info: dict[str, int] = {}
+        with open("/proc/meminfo") as f:
+            for line in f:
+                parts = line.split()
+                if len(parts) >= 2:
+                    info[parts[0].rstrip(":")] = int(parts[1])
+        total_kb = info.get("MemTotal", 0)
+        avail_kb = info.get("MemAvailable", 0)
+        return (total_kb - avail_kb) // 1024, total_kb // 1024
+    except Exception:
+        return 0, 0
+
+
+def _assert_memory_safe(raw: bytes, ext: str) -> None:
+    """
+    Reject requests that would likely exhaust available RAM.
+
+    For images: estimate from raw byte count only (no Pillow decode needed —
+    avoids the double-decode that existed in v3.0). Raw JPEG at 3 MP ≈ 1–3 MB;
+    the decompressed BGR array is w*h*3 bytes. We conservatively multiply by
+    IMAGE_MEMORY_FACTOR to cover both the decode buffer and OCR working memory.
+    """
+    used_mb, total_mb = _mem_mb()
+    if total_mb == 0:
+        return
+    available_mb = total_mb - used_mb
+    if ext in PDF_EXTENSIONS:
+        page_count   = max(1, _pdf_page_count(raw))
+        estimated_mb = (page_count * BYTES_PER_OCR_PAGE) // (1024 * 1024)
+    else:
+        # Estimate from compressed size — no Pillow decode required.
+        # Compressed-to-raw expansion ratio for JPEG ≈ 10–20×; we use 20× and
+        # multiply by IMAGE_MEMORY_FACTOR for working memory overhead.
+        estimated_mb = len(raw) * 20 * IMAGE_MEMORY_FACTOR // (1024 * 1024)
+
+    free_after = available_mb - estimated_mb
+    logger.info(
+        "memory_check  avail_mb=%d  est_mb=%d  free_after_mb=%d",
+        available_mb, estimated_mb, free_after,
+    )
+    if free_after < MEM_SAFETY_FLOOR_MB:
+        raise _err(
+            "validation", "LOW_MEMORY",
+            f"Insufficient memory. Available: {available_mb} MB, "
+            f"Estimated needed: {estimated_mb} MB.", 507,
+            root_cause=f"Container has {available_mb} MB free; "
+                       f"pipeline needs ~{estimated_mb} MB.",
+            recommendation="Wait for active requests to complete, "
+                           "or use a smaller file.",
+        )

requirements.txt

@@ -0,0 +1,54 @@
+# Reference only — dependencies are installed directly in the Dockerfile
+# to allow layered pip caching. See Dockerfile for the authoritative install order.
+#
+# ── Layer 1 — FastAPI + lightweight runtime deps ──────────────────────────────
+fastapi>=0.115.0
+uvicorn[standard]>=0.32.0
+python-multipart>=0.0.12
+Pillow>=10.0.0
+pillow-heif>=0.18.0
+huggingface_hub>=0.25.0
+opencv-python-headless>=4.8.0   # placeholder; force-reinstalled in Layer 4
+#
+# ── Layer 2 — CPU-only PyTorch ────────────────────────────────────────────────
+# pip install --index-url https://download.pytorch.org/whl/cpu torch torchvision
+# MUST come before magic-pdf. PyPI serves the CUDA wheel by default (~2.5 GB).
+# Pre-installing the CPU build causes pip to skip the CUDA wheel when resolving
+# magic-pdf's `torch` requirement.
+torch>=2.2.2,!=2.5.0,!=2.5.1,<3
+torchvision>=0.15.2
+#
+# ── Layer 3 — magic-pdf with CORRECT extras ───────────────────────────────────
+# pip install --extra-index-url https://myhloli.github.io/wheels/ magic-pdf[full]==1.3.12
+#
+# FORENSIC SUMMARY:
+#
+# [full-cpu] is NOT a valid extra in magic-pdf 1.3.12.
+# Valid extras: [full], [full_old_linux], [lite]
+# Using an invalid extra causes pip to install base-only — omitting
+# ultralytics, doclayout-yolo, rapid-table, and OCR support entirely.
+#
+# [full] provides:
+#   ultralytics >=8.3.48     YOLO framework, required by doclayout-yolo
+#   doclayout-yolo ==0.0.2b1 layout detection (myhloli index only)
+#   rapid-table >=1.0.5      table detection (onnxruntime pulled as transitive dep)
+#   shapely, pyclipper       used by paddleocr2pytorch (baked into magic-pdf wheel)
+#   omegaconf, matplotlib, ftfy, dill, PyYAML, openai, albumentations
+#
+# [lite] is NOT used because:
+#   - paddlepaddle==3.0.0b1 pinned by [lite] does not exist on PyPI (removed beta)
+#   - paddleocr==2.7.3 requires opencv-python <=4.6.0.66, incompatible with
+#     ultralytics (>=4.6.0) and doclayout-yolo (>=4.6.0)
+#   - paddlepaddle/paddleocr are NOT needed: pipeline backend uses paddleocr2pytorch,
+#     a self-contained PyTorch reimplementation bundled inside the magic-pdf wheel
+#
+# --extra-index-url https://myhloli.github.io/wheels/ is required because
+# doclayout-yolo==0.0.2b1 is only on the myhloli wheel server, not on PyPI.
+magic-pdf[full]==1.3.12
+#
+# ── Layer 4 — Restore headless OpenCV (MUST be last) ─────────────────────────
+# pip install --force-reinstall opencv-python-headless>=4.8.0
+# Layer 3 installs opencv-python (non-headless) via doclayout-yolo + ultralytics
+# + rapid-table transitive deps. Force-reinstalling headless overwrites cv2 with
+# the build that works on this container without X11 libs.
+opencv-python-headless>=4.8.0  # force-reinstalled in Layer 4

validate.py

@@ -0,0 +1,633 @@
+#!/usr/bin/env python3
+"""
+Pre-flight validation script for MinerU OCR Service.
+
+Run by entrypoint.sh BEFORE uvicorn starts.
+Exits 0 if all checks pass.
+Exits 1 if any CRITICAL check fails — this crashes the container loudly
+so Hugging Face logs show an actionable error instead of a silent crash
+or a healthy-looking service that fails on every request.
+
+Usage:
+    python validate.py           # run all checks, exit 0/1
+    python validate.py --soft    # run all checks, always exit 0 (log only)
+
+── FORENSIC NOTES (2025-06) ──────────────────────────────────────────────────
+
+OCR engine:
+  The pipeline (full) backend uses paddleocr2pytorch — a self-contained
+  PyTorch reimplementation of PaddleOCR bundled inside the magic-pdf wheel.
+  It uses: torch, cv2, numpy, pyclipper, shapely, yaml.
+  paddlepaddle and paddleocr packages are NOT installed and NOT needed.
+
+  pp_structure_v2.py (which imports paddleocr) is only loaded in 'lite' model
+  mode. Pipeline backend always uses 'full' mode (CustomPEKModel). That file is
+  never imported at runtime.
+
+OCR model path resolution (from pytorch_paddle.py):
+  ocr_models_dir = os.path.join(get_local_models_dir(), 'OCR', 'paddleocr_torch')
+  det_model_path = os.path.join(ocr_models_dir, det_filename)
+  where det_filename comes from models_config.yml keyed by language.
+
+  Default CPU path: lang='ch' → forced to 'ch_lite' on CPU device.
+  After Dockerfile Layer 3.5 patch:
+    ch_lite.det = ch_PP-OCRv5_det_infer.pth  (was ch_PP-OCRv3 — not in HF repo)
+    ch_lite.rec = ch_PP-OCRv5_rec_infer.pth  (unchanged — already in HF repo)
+
+Arch config lookup (from pytorchocr_utility.py):
+  get_arch_config(model_path) uses Path(model_path).stem as the key into
+  arch_config.yaml (bundled in magic-pdf wheel). Both replacement filenames
+  have entries in arch_config.yaml — verified before patch was written.
+
+OpenCV conflict handling:
+  doclayout-yolo, ultralytics, and rapid-table all declare opencv-python
+  (non-headless) as a required dep. pip installs the full build in Layer 3.
+  Layer 4 force-reinstalls opencv-python-headless to overwrite cv2. Both
+  packages expose an identical cv2 API so all callers work correctly at
+  runtime. pip-check shows warnings but they are harmless.
+
+onnxruntime:
+  rapid-table declares onnxruntime>1.17.0 as a required (non-optional) dep.
+  pip resolves it automatically when magic-pdf[full] is installed in Layer 3.
+
+slanet-plus.onnx (table model):
+  Bundled inside the magic-pdf wheel at:
+    magic_pdf/resources/slanet_plus/slanet-plus.onnx
+  NOT downloaded from HF Hub — no separate download needed.
+"""
+
+import importlib
+import json
+import os
+import shutil
+import sys
+import tempfile
+import traceback
+
+SOFT_MODE = "--soft" in sys.argv  # never exit 1, just print
+
+MODELS_DIR = "/app/models"
+EXTRACT_KIT_MODELS = os.path.join(MODELS_DIR, "PDF-Extract-Kit-1.0", "models")
+LAYOUT_MARKER = os.path.join(EXTRACT_KIT_MODELS, "Layout")  # canary directory
+CONFIG_PATH = os.path.expanduser("~/magic-pdf.json")
+
+
+# ── helpers ────────────────────────────────────────────────────────────────────
+def ok(label: str, detail: str = "") -> None:
+    suffix = f"  ({detail})" if detail else ""
+    print(f"  ✓  {label}{suffix}", flush=True)
+
+
+def fail(label: str, detail: str, critical: bool = True) -> None:
+    tag = "CRITICAL" if critical else "WARNING"
+    print(f"  ✗  [{tag}] {label}: {detail}", flush=True)
+
+
+def section(title: str) -> None:
+    print(f"\n{'─' * 60}", flush=True)
+    print(f"  {title}", flush=True)
+    print(f"{'─' * 60}", flush=True)
+
+
+# ── check registry ─────────────────────────────────────────────────────────────
+failures: list[tuple[str, str]] = []
+warnings: list[tuple[str, str]] = []
+
+
+def record_fail(label: str, detail: str, critical: bool = True) -> None:
+    fail(label, detail, critical)
+    if critical:
+        failures.append((label, detail))
+    else:
+        warnings.append((label, detail))
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+print("\n" + "═" * 60, flush=True)
+print("  MinerU OCR Service — Pre-flight Validation", flush=True)
+print("═" * 60, flush=True)
+
+# ── 1. Python version ──────────────────────────────────────────────────────────
+section("1. Python runtime")
+pv = sys.version_info
+if pv >= (3, 10):
+    ok("Python version", f"{pv.major}.{pv.minor}.{pv.micro}")
+else:
+    record_fail("Python version",
+                f"{pv.major}.{pv.minor} detected — magic-pdf requires >= 3.10")
+
+# ── 2. cv2 ─────────────────────────────────────────────────────────────────────
+section("2. OpenCV (cv2)")
+try:
+    import cv2
+    ok("cv2 import", f"version {cv2.__version__}")
+    build = cv2.getBuildInformation()
+    if "GTK" in build or "Qt" in build:
+        record_fail("cv2 build", "GUI backend detected — use opencv-python-headless",
+                    critical=False)
+    else:
+        ok("cv2 headless", "no GUI backend detected")
+except ImportError as exc:
+    record_fail(
+        "cv2 import",
+        f"{exc}. "
+        "Layer 4 force-reinstall of opencv-python-headless may have failed. "
+        "Check Docker build log for the 'pip install --force-reinstall opencv-python-headless' step.",
+    )
+except Exception as exc:
+    record_fail("cv2 import", f"unexpected error: {exc}")
+
+# ── 3. PyTorch ─────────────────────────────────────────────────────────────────
+section("3. PyTorch + TorchVision")
+try:
+    import torch
+    ok("torch import", f"version {torch.__version__}")
+    if torch.cuda.is_available():
+        record_fail("torch CUDA", "CUDA detected on CPU-only space — unexpected",
+                    critical=False)
+    else:
+        ok("torch device", "CPU-only (expected for free tier)")
+except ImportError as exc:
+    record_fail(
+        "torch import",
+        f"{exc}. "
+        "Install from PyTorch CPU index BEFORE magic-pdf in Dockerfile Layer 2: "
+        "pip install --index-url https://download.pytorch.org/whl/cpu torch torchvision",
+    )
+except Exception as exc:
+    record_fail("torch import", f"unexpected: {exc}")
+
+try:
+    import torchvision
+    ok("torchvision import", f"version {torchvision.__version__}")
+except ImportError as exc:
+    record_fail("torchvision import", str(exc))
+except Exception as exc:
+    record_fail("torchvision import", f"unexpected: {exc}")
+
+# ── 4. ultralytics ─────────────────────────────────────────────────────────────
+section("4. ultralytics (YOLO — required by doclayout_yolo)")
+try:
+    import ultralytics
+    ok("ultralytics import", f"version {ultralytics.__version__}")
+except ImportError as exc:
+    record_fail(
+        "ultralytics import",
+        f"{exc}. "
+        "Provided by magic-pdf[full]. "
+        "ROOT CAUSE: [full-cpu] is NOT a valid extra in magic-pdf 1.3.12 — "
+        "pip silently installed only the base package when given an unknown extra. "
+        "Dockerfile Layer 3 must use magic-pdf[full]==1.3.12 (not [full-cpu]).",
+    )
+except Exception as exc:
+    record_fail("ultralytics import", f"unexpected: {exc}")
+
+# ── 5. doclayout_yolo ──────────────────────────────────────────────────────────
+section("5. doclayout_yolo (layout detection model)")
+try:
+    import doclayout_yolo
+    ok("doclayout_yolo import", f"version {getattr(doclayout_yolo, '__version__', 'unknown')}")
+except ImportError as exc:
+    record_fail(
+        "doclayout_yolo import",
+        f"{exc}. "
+        "Provided by magic-pdf[full] (version 0.0.2b1). "
+        "doclayout-yolo==0.0.2b1 is only on the myhloli custom wheel index — "
+        "Dockerfile Layer 3 must include: "
+        "--extra-index-url https://myhloli.github.io/wheels/",
+    )
+except Exception as exc:
+    record_fail("doclayout_yolo import", f"unexpected: {exc}")
+
+# ── 6. rapid_table ─────────────────────────────────────────────────────────────
+section("6. rapid_table (table extraction)")
+try:
+    import rapid_table
+    ok("rapid_table import", f"version {getattr(rapid_table, '__version__', 'unknown')}")
+except ImportError as exc:
+    record_fail(
+        "rapid_table import",
+        f"{exc}. Provided by magic-pdf[full]. Check Layer 3 install.",
+    )
+except Exception as exc:
+    record_fail("rapid_table import", f"unexpected: {exc}")
+
+# ── 7. onnxruntime ─────────────────────────────────────────────────────────────
+section("7. onnxruntime (required by rapid-table for table model inference)")
+# onnxruntime is a required (non-optional) dep of rapid-table>=1.0.5.
+# pip resolves it automatically when magic-pdf[full] is installed in Layer 3.
+# If it is missing it means rapid-table itself failed to install.
+try:
+    import onnxruntime
+    ok("onnxruntime import", f"version {onnxruntime.__version__}")
+except ImportError as exc:
+    record_fail(
+        "onnxruntime import",
+        f"{exc}. "
+        "onnxruntime is a required dep of rapid-table>=1.0.5. "
+        "Its absence means rapid-table failed to install in Layer 3. "
+        "Check Docker build log for rapid-table install errors.",
+    )
+except Exception as exc:
+    record_fail("onnxruntime import", f"unexpected: {exc}")
+
+# ── 8. magic_pdf core imports ──────────────────────────────────────────────────
+section("8. magic_pdf core imports")
+
+REQUIRED_IMPORTS = [
+    ("magic_pdf.data.dataset",                     ["PymuDocDataset", "ImageDataset"]),
+    ("magic_pdf.data.data_reader_writer",          ["FileBasedDataReader", "FileBasedDataWriter"]),
+    ("magic_pdf.model.doc_analyze_by_custom_model", ["doc_analyze"]),
+    ("magic_pdf.config.enums",                     ["SupportedPdfParseMethod"]),
+]
+
+for module_path, symbols in REQUIRED_IMPORTS:
+    try:
+        mod = importlib.import_module(module_path)
+        missing = [s for s in symbols if not hasattr(mod, s)]
+        if missing:
+            record_fail(f"{module_path}", f"missing symbols: {missing}")
+        else:
+            ok(module_path, ", ".join(symbols))
+    except ImportError as exc:
+        record_fail(module_path, str(exc))
+    except Exception as exc:
+        record_fail(module_path, f"unexpected: {exc}")
+
+# ── 8b. paddleocr2pytorch (OCR engine bundled inside magic-pdf wheel) ──────────
+section("8b. paddleocr2pytorch (PyTorch OCR — bundled in magic-pdf wheel)")
+# This is the actual OCR engine for the pipeline backend.
+# It is NOT a separate pip package — it lives inside the magic-pdf wheel at
+#   magic_pdf/model/sub_modules/ocr/paddleocr2pytorch/
+# If it is missing, the entire magic-pdf package did not install correctly.
+try:
+    from magic_pdf.model.sub_modules.ocr.paddleocr2pytorch.pytorch_paddle import PytorchPaddleOCR
+    ok("PytorchPaddleOCR (paddleocr2pytorch)", "bundled inside magic-pdf wheel — no paddlepaddle pkg needed")
+except ImportError as exc:
+    record_fail(
+        "PytorchPaddleOCR import",
+        f"{exc}. "
+        "This module is bundled inside magic_pdf/model/sub_modules/ocr/paddleocr2pytorch/. "
+        "If missing, magic-pdf itself did not install correctly.",
+    )
+except Exception as exc:
+    record_fail("PytorchPaddleOCR import", f"unexpected: {exc}")
+
+# ── 8c. Deprecated API check ───────────────────────────────────────────────────
+section("8c. Deprecated API check (should NOT exist)")
+OBSOLETE = [
+    "magic_pdf.pipe.UNIPipe",
+    "magic_pdf.rw.DiskReaderWriter",
+]
+for mod_path in OBSOLETE:
+    try:
+        importlib.import_module(mod_path)
+        record_fail(mod_path, "still importable — code may use old API", critical=False)
+    except ImportError:
+        ok(f"{mod_path} (correctly absent)")
+
+# ── 9. End-to-end pipeline smoke test ─────────────────────────────────────────
+section("9. End-to-end pipeline smoke test")
+try:
+    from magic_pdf.model.doc_analyze_by_custom_model import doc_analyze  # noqa: F401
+    import ultralytics  # noqa: F401
+    from magic_pdf.data.dataset import ImageDataset  # noqa: F401
+    from magic_pdf.data.data_reader_writer import FileBasedDataReader, FileBasedDataWriter  # noqa: F401
+    ok("Pipeline imports (doc_analyze + ultralytics + ImageDataset + readers)", "all OK")
+except ImportError as exc:
+    record_fail(
+        "Pipeline smoke test",
+        f"Full pipeline import chain failed: {exc}. "
+        "This means POST /extract will fail on every request.",
+    )
+except Exception as exc:
+    record_fail("Pipeline smoke test", f"unexpected: {exc}")
+
+# ── 10. Config file ────────────────────────────────────────────────────────────
+section("10. MinerU config (magic-pdf.json)")
+_cfg: dict = {}
+if os.path.exists(CONFIG_PATH):
+    try:
+        with open(CONFIG_PATH) as f:
+            _cfg = json.load(f)
+        required_keys = ["models-dir", "device-mode"]
+        missing_keys = [k for k in required_keys if k not in _cfg]
+        if missing_keys:
+            record_fail("Config keys", f"missing: {missing_keys}")
+        else:
+            ok("Config file", CONFIG_PATH)
+            ok("device-mode", _cfg.get("device-mode", "?"))
+            ok("models-dir",  _cfg.get("models-dir",  "?"))
+            ok("formula-enable", str(_cfg.get("formula-config", {}).get("enable", "?")))
+            ok("table-enable",   str(_cfg.get("table-config",   {}).get("enable", "?")))
+    except json.JSONDecodeError as exc:
+        record_fail("Config file", f"invalid JSON: {exc}")
+    except Exception as exc:
+        record_fail("Config file", str(exc))
+else:
+    record_fail(
+        "Config file",
+        f"not found at {CONFIG_PATH}. "
+        "Run download_models.py or check Docker build log.",
+    )
+
+# ── 11. Model directory structure ─────────────────────────────────────────────
+section("11. Model directory structure")
+
+model_dir_checks = [
+    ("PDF-Extract-Kit-1.0 root",  os.path.join(MODELS_DIR, "PDF-Extract-Kit-1.0")),
+    ("Layout models",             os.path.join(EXTRACT_KIT_MODELS, "Layout")),
+    ("Layout/YOLO",               os.path.join(EXTRACT_KIT_MODELS, "Layout", "YOLO")),
+    ("OCR models",                os.path.join(EXTRACT_KIT_MODELS, "OCR")),
+    ("OCR/paddleocr_torch",       os.path.join(EXTRACT_KIT_MODELS, "OCR", "paddleocr_torch")),
+    ("Table models (TabRec)",     os.path.join(EXTRACT_KIT_MODELS, "TabRec")),
+]
+
+for label, path in model_dir_checks:
+    if os.path.isdir(path):
+        try:
+            n = sum(1 for _ in os.scandir(path))
+            ok(label, f"{n} entries  [{path}]")
+        except OSError:
+            ok(label, path)
+    else:
+        record_fail(label, f"directory not found: {path}")
+
+lr_dir = os.path.join(MODELS_DIR, "layoutreader")
+if os.path.isdir(lr_dir):
+    ok("layoutreader (optional)", lr_dir)
+else:
+    record_fail("layoutreader (optional)",
+                "not found — MinerU will use fallback ordering (non-critical)",
+                critical=False)
+
+# ── 11b. Critical model weight files ──────────────────────────────────────────
+section("11b. Critical model weight files")
+#
+# These are the EXACT files MinerU will try to open when processing a document
+# on a CPU deployment (default language = ch → forced to ch_lite on CPU).
+#
+# After Dockerfile Layer 3.5 patch, models_config.yml now references:
+#   ch_lite.det = ch_PP-OCRv5_det_infer.pth  (patched from v3 — v3 NOT in repo)
+#   ch_lite.rec = ch_PP-OCRv5_rec_infer.pth  (unchanged — always in repo)
+#
+# Layout uses doclayout_yolo (from magic-pdf.json layout-config).
+# Table (rapid_table) uses slanet-plus.onnx BUNDLED IN THE WHEEL — not here.
+# Formula is DISABLED — MFD/MFR files not required.
+#
+# Any CRITICAL failure here = service boots but crashes on first document.
+
+_ocr_dir = os.path.join(EXTRACT_KIT_MODELS, "OCR", "paddleocr_torch")
+
+CRITICAL_WEIGHT_FILES: list[tuple[str, str, str]] = [
+    # (label, relative-to-EXTRACT_KIT_MODELS, reason)
+    (
+        "OCR det weight (ch_lite, default CPU lang)",
+        os.path.join("OCR", "paddleocr_torch", "ch_PP-OCRv5_det_infer.pth"),
+        "Patched from ch_PP-OCRv3_det_infer.pth (absent in HF repo). "
+        "Missing = all OCR will crash at model load time."
+    ),
+    (
+        "OCR rec weight (ch_lite)",
+        os.path.join("OCR", "paddleocr_torch", "ch_PP-OCRv5_rec_infer.pth"),
+        "Recognition model for ch_lite. "
+        "Missing = OCR loads det but crashes at recognition."
+    ),
+    (
+        "OCR cls weight (angle classifier)",
+        os.path.join("OCR", "paddleocr_torch", "ch_ptocr_mobile_v2.0_cls_infer.pth"),
+        "Used when use_angle_cls=True. Default is False so non-critical, "
+        "but its absence causes crash if angle classification is enabled."
+    ),
+    (
+        "Layout YOLO weight (doclayout_yolo)",
+        os.path.join("Layout", "YOLO", "doclayout_yolo_docstructbench_imgsz1280_2501.pt"),
+        "Layout detection model. Missing = layout detection crashes on every document."
+    ),
+    (
+        "Layout LayoutLMv3 weight",
+        os.path.join("Layout", "LayoutLMv3", "model_final.pth"),
+        "Alternative layout model. Required even when doclayout_yolo is primary "
+        "because model_configs.yaml always lists it."
+    ),
+    (
+        "Multilingual OCR det (en/latin fallback)",
+        os.path.join("OCR", "paddleocr_torch", "Multilingual_PP-OCRv3_det_infer.pth"),
+        "Patched det for en and latin languages. Missing = crash if lang=en/latin."
+    ),
+]
+
+# cls weight is only critical if use_angle_cls=True (default False)
+NON_CRITICAL_LABELS = {"OCR cls weight (angle classifier)"}
+
+for label, rel_path, reason in CRITICAL_WEIGHT_FILES:
+    full_path = os.path.join(EXTRACT_KIT_MODELS, rel_path)
+    is_critical = label not in NON_CRITICAL_LABELS
+    if os.path.isfile(full_path):
+        size_mb = os.path.getsize(full_path) / (1024 * 1024)
+        ok(label, f"{size_mb:.1f} MB  [{full_path}]")
+    else:
+        record_fail(
+            label,
+            f"FILE NOT FOUND: {full_path}\n"
+            f"    Reason: {reason}",
+            critical=is_critical,
+        )
+
+# ── 11c. models_config.yml consistency check ──────────────────────────────────
+section("11c. models_config.yml consistency check")
+#
+# Reads the installed models_config.yml (inside magic_pdf package) and verifies
+# that every det/rec file it references for the default CPU language (ch_lite)
+# actually exists on disk in the expected location.
+#
+# This catches future version drift between the magic-pdf package and the HF repo
+# BEFORE the service starts, rather than mid-request.
+
+try:
+    import magic_pdf
+    import yaml as _yaml
+    from pathlib import Path as _Path
+
+    _pkg = _Path(magic_pdf.__file__).parent
+    _mcfg = _pkg / 'model/sub_modules/ocr/paddleocr2pytorch/pytorchocr/utils/resources/models_config.yml'
+
+    if not _mcfg.exists():
+        record_fail("models_config.yml", f"not found at expected path: {_mcfg}")
+    else:
+        with open(_mcfg) as _f:
+            _mc = _yaml.safe_load(_f)
+
+        _ocr_torch = os.path.join(EXTRACT_KIT_MODELS, "OCR", "paddleocr_torch")
+
+        # Check the two languages actually used on this CPU deployment
+        _check_langs = ["ch_lite", "ch"]
+        _mc_ok = True
+        for _lang in _check_langs:
+            _entry = _mc.get("lang", {}).get(_lang, {})
+            for _field in ("det", "rec"):
+                _fname = _entry.get(_field)
+                if not _fname:
+                    continue
+                _fpath = os.path.join(_ocr_torch, _fname)
+                if os.path.isfile(_fpath):
+                    ok(f"models_config[{_lang}].{_field}", _fname)
+                else:
+                    record_fail(
+                        f"models_config[{_lang}].{_field}",
+                        f"Config references '{_fname}' but file not found at:\n"
+                        f"    {_fpath}\n"
+                        f"    Dockerfile Layer 3.5 patch may not have run, "
+                        f"or HF repo changed its file structure again.",
+                        critical=True,
+                    )
+                    _mc_ok = False
+
+        if _mc_ok:
+            ok("models_config.yml consistency", "all referenced det/rec files exist on disk")
+
+except Exception as _exc:
+    record_fail("models_config.yml consistency check", f"unexpected error: {_exc}", critical=False)
+
+# ── 11d. Bundled wheel resources ──────────────────────────────────────────────
+section("11d. Bundled wheel resources (inside magic_pdf package)")
+#
+# These files are shipped inside the magic-pdf wheel itself.
+# They do NOT come from the HF download. Their absence means the wheel
+# installed incorrectly or was corrupted.
+
+try:
+    import magic_pdf as _mp
+    from pathlib import Path as _P
+
+    _pkg_root = _P(_mp.__file__).parent
+    _bundled = [
+        ("slanet-plus.onnx (table model)",
+         _pkg_root / "resources" / "slanet_plus" / "slanet-plus.onnx"),
+        ("fasttext langdetect model",
+         _pkg_root / "resources" / "fasttext-langdetect" / "lid.176.ftz"),
+        ("YOLO langdetect model",
+         _pkg_root / "resources" / "yolov11-langdetect" / "yolo_v11_ft.pt"),
+        ("model_configs.yaml (weight path map)",
+         _pkg_root / "resources" / "model_config" / "model_configs.yaml"),
+    ]
+    for _lbl, _p in _bundled:
+        if _p.exists():
+            _sz = _p.stat().st_size / (1024 * 1024)
+            ok(_lbl, f"{_sz:.2f} MB")
+        else:
+            record_fail(_lbl, f"expected inside wheel at {_p} — magic-pdf install may be corrupted")
+
+except Exception as _exc:
+    record_fail("Bundled wheel resources check", f"unexpected: {_exc}", critical=False)
+
+# ── 12. Temp storage ───────────────────────────────────────────────────────────
+section("12. Temp storage")
+try:
+    td = tempfile.mkdtemp(prefix="mineru_validate_")
+    test_file = os.path.join(td, "write_test.bin")
+    with open(test_file, "wb") as f:
+        f.write(b"x" * 4096)
+    assert os.path.getsize(test_file) == 4096
+    shutil.rmtree(td)
+    ok("Temp write + delete", tempfile.gettempdir())
+except Exception as exc:
+    record_fail("Temp storage", str(exc))
+
+# ── 13. System memory (cgroups) ────────────────────────────────────────────────
+section("13. System memory (cgroups)")
+mem_source = "unknown"
+total_mb = used_mb = 0
+
+try:
+    with open("/sys/fs/cgroup/memory.max") as f:
+        raw = f.read().strip()
+    if raw != "max":
+        total_mb = int(raw) // (1024 * 1024)
+        with open("/sys/fs/cgroup/memory.current") as f:
+            used_mb = int(f.read().strip()) // (1024 * 1024)
+        mem_source = "cgroups v2"
+except (FileNotFoundError, ValueError):
+    pass
+
+if total_mb == 0:
+    try:
+        with open("/sys/fs/cgroup/memory/memory.limit_in_bytes") as f:
+            limit = int(f.read().strip())
+        with open("/sys/fs/cgroup/memory/memory.usage_in_bytes") as f:
+            used_bytes = int(f.read().strip())
+        if limit < 128 * 1024 * 1024 * 1024:
+            total_mb = limit // (1024 * 1024)
+            used_mb  = used_bytes // (1024 * 1024)
+            mem_source = "cgroups v1"
+    except (FileNotFoundError, ValueError):
+        pass
+
+if total_mb == 0:
+    try:
+        info: dict[str, int] = {}
+        with open("/proc/meminfo") as f:
+            for line in f:
+                parts = line.split()
+                if len(parts) >= 2:
+                    info[parts[0].rstrip(":")] = int(parts[1])
+        total_mb = info.get("MemTotal", 0) // 1024
+        used_mb  = (info.get("MemTotal", 0) - info.get("MemAvailable", 0)) // 1024
+        mem_source = "/proc/meminfo (may show host RAM)"
+    except Exception:
+        pass
+
+ok("Memory source", mem_source)
+ok("Total memory",  f"{total_mb} MB")
+ok("Used memory",   f"{used_mb} MB")
+ok("Free memory",   f"{total_mb - used_mb} MB")
+
+if total_mb > 32 * 1024:
+    record_fail(
+        "Memory total",
+        f"{total_mb} MB seems too large — cgroups may not be available; "
+        "/proc/meminfo showing host RAM. Memory guard in main.py will be conservative.",
+        critical=False,
+    )
+
+# ── 14. /proc/meminfo sanity ───────────────────────────────────────────────────
+section("14. /proc/meminfo (reference)")
+try:
+    with open("/proc/meminfo") as f:
+        lines = f.readlines()[:5]
+    for line in lines:
+        parts = line.split()
+        if len(parts) >= 2:
+            kb = int(parts[1])
+            ok(parts[0].rstrip(":"), f"{kb // 1024} MB")
+except Exception as exc:
+    record_fail("/proc/meminfo", str(exc), critical=False)
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Summary
+# ═══════════════════════════════════════════════════════════════════════════════
+print("\n" + "═" * 60, flush=True)
+print("  Validation Summary", flush=True)
+print("═" * 60, flush=True)
+
+if warnings:
+    print(f"\n  ⚠  {len(warnings)} warning(s):", flush=True)
+    for label, detail in warnings:
+        print(f"     • {label}: {detail}", flush=True)
+
+if failures:
+    print(f"\n  ✗  {len(failures)} CRITICAL failure(s):", flush=True)
+    for label, detail in failures:
+        print(f"     • {label}: {detail}", flush=True)
+    print("\n  Service will NOT start until these are resolved.", flush=True)
+    print("  Check Dockerfile pip layers and Docker build log.", flush=True)
+    print("═" * 60 + "\n", flush=True)
+    if not SOFT_MODE:
+        sys.exit(1)
+else:
+    print(f"\n  ✓  All critical checks passed", flush=True)
+    if warnings:
+        print(f"  ⚠  {len(warnings)} non-critical warning(s) — see above", flush=True)
+    print("\n  Service is ready to start.", flush=True)
+    print("═" * 60 + "\n", flush=True)
+    sys.exit(0)