feat: optional OCR fallback for text-less PDFs (scanned / CAD exports)

[D4NGYY]

Problem

Scanned and CAD-export PDFs have no usable text layer. Today they ingest as zero
chunks and silently report success, so File Search returns nothing for them. PDFs
that pypdf cannot parse at all surface only a generic "Error processing file".

Cause

In app/utils/document_loader.py, SafePyPDFLoader relies on pypdf text
extraction, which returns empty strings for image-only pages without raising. The
empty result is split into 0 chunks and treated as a successful ingest.

Fix

An opt-in OCR fallback (off by default — no behavior change unless enabled):

• New app/utils/ocr.py:
  • has_text_layer(pages, min_chars) — detects an empty/garbage text layer.
  • ocr_pdf(filepath, *, pages=None, min_confidence=..., ...) — rasterizes pages with
    pypdfium2 and OCRs them with rapidocr-onnxruntime (already a dependency),
    returning one Document per page. Accepts an explicit page subset (for page-aware
    fallback) and drops OCR blocks below a confidence threshold.
  • NoExtractableTextError — raised when nothing is recoverable even after OCR.
• SafePyPDFLoader now performs a page-aware fallback: it extracts normally, then
  OCRs only the pages whose text layer is below RAG_PDF_OCR_MIN_CHARS, keeping
  native text pages untouched. This handles mixed PDFs (some pages have a text layer,
  some are image-only) instead of treating the document as all-or-nothing. If the whole
  document still has no usable text, it raises NoExtractableTextError.
• Confidence filtering: low-confidence OCR blocks (below RAG_PDF_OCR_MIN_CONFIDENCE)
  are dropped before chunking, so noisy recognitions don't pollute the vector store.
• Structured metrics: each OCR pass emits a single JSON log line
  (pdf_ocr_metrics: pages_total, pages_ocr_applied, chars_extracted,
  ocr_confidence_avg) so ingestion behavior is observable in production.
• document_routes.py maps a non-recoverable document to a clear 422 ("no extractable
  text, even after OCR"), and maps encrypted/password-protected PDFs to a clear 422 as
  well — instead of a generic failure or silent success.
• Config (env): RAG_PDF_OCR_ENABLED (default False), RAG_PDF_OCR_MIN_CHARS
  (16), RAG_PDF_OCR_DPI (200), RAG_PDF_OCR_MAX_PAGES (50),
  RAG_PDF_OCR_MIN_CONFIDENCE (0.0, i.e. keep everything; raise to ~0.5 to filter noise).

Dependencies

• Adds one pip dependency: pypdfium2 (permissive license, ships its own binary
  — no system packages).
• Reuses the existing rapidocr-onnxruntime + opencv-python-headless.
• No Dockerfile change: the image already installs libgl1 / libglib2.0-0 for
  opencv, and pip install -r requirements.txt picks up pypdfium2.

Backward compatibility

OCR is opt-in (RAG_PDF_OCR_ENABLED=False by default). With it off, the PDF path is
byte-for-byte unchanged. Verified: the existing SafePyPDFLoader tests still pass.

Tests

• tests/utils/test_ocr.py — unit tests with an injected fake OCR (fast) + one
  integration/slow test running the real engine on a committed fixture. Covers
  confidence filtering, mean-confidence reporting, page-subset selection, and the
  tuple-returning OCR callable.
• tests/utils/test_document_loader.py — wiring tests: OCR off skips OCR; OCR on
  recovers text; OCR on but still empty raises; text-present PDFs skip OCR; mixed PDF
  OCRs only the deficient page; configured min_confidence is threaded to ocr_pdf.

How to try

# in .env
RAG_PDF_OCR_ENABLED=true
# upload a scanned/CAD PDF via File Search → it is now chunked & searchable

Scope / honesty

OCR is reliable on scanned text and table-like layouts (e.g. terminal plans). Dense
graphical schematics with very small labels remain hard — this PR makes the broad
"no text layer" case work and fail loudly when it can't, rather than chasing perfect
recognition of dense line art.

Future work (out of scope here)

• Vision-language extraction for graphically complex pages (wiring diagrams,
  schematics), behind a separate flag — a model that reads layout/relationships, not
  just glyphs, is the real answer where classic OCR is weak.
• OCR result caching (by file hash) to avoid re-OCRing the same document on re-upload.
• Surfacing the OCR limitation in the LibreChat UI so users know a scanned upload was
  recovered best-effort and extracted values should be verified against the source.

[SebasSotoA]

🙏🙏🙏