fix(pdf): abort early on scanned PDFs with an OCR hint

[virgiliojr94]

Summary (Required)

A scanned (image-only) PDF used to fail only at the very end of the pipeline — after Docling had processed the entire book in technical mode — and the error blamed "Unicode sanitization" instead of saying "this is a scan, run OCR". This probes the first 5 pages up front and fails in ~0.01s with an actionable ocrmypdf hint.

Type of change (Required)

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ Feature (non-breaking change that adds capability)
• ⚡ Performance (faster / cheaper, no behavior change)
• ♻️ Refactor (no behavior change)
• 📝 Docs only
• 🔒 Security
• 🧹 Chore / CI / tooling
• 💥 Breaking change (changes existing behavior or a public interface)

What it does (Required)

• Fixes: an image-only PDF ran the whole extraction chain (Docling on every page in --mode technical, then pdftotext → pypdf → pdfminer) before the final if not text.strip() guard in extract_single_file raised — with a message about Unicode sanitization that never mentions OCR. Root cause: there was no pre-flight check, and the guard sat at the end of the function.
• Fixes: the PDF chain tested if text: at four call sites. extract_with_pypdf joins per-page strings, so an image-only PDF yields "\n\n\n…" — truthy — and extraction was marked successful (method="pypdf") with no real text. Now if text and text.strip():.
• Improves: time-to-error on a scanned PDF from a full Docling pass over the book down to a measured 0.01s, and the message now names the actual problem and the fix command.

Motivation & context (Required)

Reported directly by a non-technical user who ran book-to-skill on a scanned PDF: it "spent ages trying to identify it and only then said it couldn't read it", burning agent time and tokens on a file that was never going to work. Her suggestion was exactly this — bail on the first pages.

Closes #n/a — reported in a live conversation, not via an issue.

How it works (Required for anything non-trivial)

looks_image_only() shells out to pdftotext -f 1 -l 5 and returns True when those pages produce no non-whitespace text. extract_single_file calls it as the first thing in the .pdf branch, before the extractor is chosen, so Docling never starts on a scan.

Deliberately conservative:

• No OCR here. Keeping OCR out of the tool is an existing product decision; this PR only makes the failure fast and legible, and points at ocrmypdf.
• Degrades to a no-op. Without pdftotext on PATH the probe returns False and the normal chain (plus the unchanged final empty-text guard) runs exactly as before. Same for a timeout or any subprocess error.
• 5 pages, not 1. A single scanned cover page in an otherwise text PDF must not trip the guard.

Known limit, accepted: a book whose first 5 pages are images but whose body is real text would now be rejected. I could not construct a realistic instance of that, and the trade is a fast honest failure against minutes of work ending in a misleading message.

Evidence (Required)

• Tests: new TestLooksImageOnly — 4 cases: whitespace-only first pages ⇒ True and the probe is capped at -l 5; real text ⇒ False; no pdftotext on PATH ⇒ False (probe skipped); and an end-to-end extract_single_file on a .pdf raising ExtractionError whose message contains both "scanned" and "ocrmypdf".
• Before / after: built two real PDFs with reportlab — text.pdf (8 pages of text) and scan.pdf (8 pages of drawn rectangles, zero text operators) — and ran the real extraction path on both.

$ python -c "... extract_single_file(scan.pdf) ..."
Extracting PDF: /tmp/.../scan.pdf
-> ExtractionError after 0.01s:
scan.pdf looks like a scanned (image-only) PDF: its first pages contain no extractable text, only images.
Run OCR on it first, then retry:
  ocrmypdf input.pdf output.pdf

$ python -c "... extract_single_file(text.pdf) ..."
Extracting PDF: /tmp/.../text.pdf
Mode: text — using pdftotext...
Trying pdftotext... OK
-> OK text.pdf: method=pdftotext chars=343 (0.03s)

$ pytest -q       ->  274 passed, 1 skipped
$ ruff check .    ->  All checks passed!

Before this change, the same scan.pdf reached the end of the chain and raised Extracted text from scan.pdf contained no visible content after Unicode sanitization. — and in --mode technical only after Docling had walked every page.

Checklist (Required — all must be checked)

• One focused change (one feature/fix per PR; not a stack of unrelated work)
• Branch is rebased on the latest master and has no merge conflicts
• Tests added/updated for behavior changes
• pytest -q is green on a clean checkout
• ruff check . is clean
• python3 tools/validate_skill.py SKILL.md passes (if SKILL.md changed) — n/a, SKILL.md untouched
• PR title follows Conventional Commits (fix:, feat:, docs:… — it becomes the changelog entry; do NOT edit CHANGELOG.md by hand)
• No raw book text shipped; no net SKILL.md bloat without justification

Notes for reviewers (Optional)

The text.strip() tightening at the four call sites is strictly a second line of defense — with the probe in place it should be unreachable for scans — but if text: on a whitespace string was wrong on its own terms, so I fixed it rather than leaving a latent silent-success path for any future extractor that returns blank pages.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None