Routing Scanned PDFs to Gemini by Chars per Page

The short version

Extracting a PDF’s text layer with pdfjs-dist does not error on a scanned (image) PDF; it returns near-empty text. We solved it with a fallback that, only when the non-whitespace character count per page falls below a threshold (20), discards the extracted text and sends the PDF bytes themselves to Gemini as a file part, substituting the OCR result.

What it looks like

Build a PDF text-extraction path on the sole premise “a text PDF is parsed locally”, and handing it a PDF with no text layer (material that was merely scanned in) makes the routine run all the way to a normal finish with near-empty contents. With no exception thrown it is hard to notice, and downstream cannot distinguish “the PDF’s contents are thin” from “the reading itself failed”.

Why

pdfjs-dist’s getTextContent() only pulls out a page’s text layer (the character information embedded inside the PDF). A scanned PDF has each page as a single image, and the text layer either does not exist or is minimal. Having no text layer is not an abnormal state under the PDF spec at all, so the parser has no reason to error and simply returns a near-empty string and finishes normally.

Fixing it

Compute the per-page density from the page count and the extracted text’s non-whitespace character count.

const SCANNED_PDF_MAX_NONWS_CHARS_PER_PAGE = 20;

function isLikelyScannedPdf(text: string, pageCount: number): boolean {
  if (pageCount <= 0) return false;
  const nonWhitespace = text.replace(/\s/g, "").length;
  return nonWhitespace < pageCount * SCANNED_PDF_MAX_NONWS_CHARS_PER_PAGE;
}

Only when this is true and an OCR client is injected does it return the OCR result rather than the extracted text.

if (this.ocr && isLikelyScannedPdf(text, pageCount)) {
  const ocrResult = await this.ocr.recognize(source.bytes, PDF_MEDIA_TYPE);
  return {
    text: ocrResult.text,
    format: "pdf",
    meta: { pageCount, ocrUsed: true, confidence: ocrResult.confidence },
  };
}
return { text, format: "pdf", meta: { pageCount } };

The part handed to OCR (Gemini) differs in type between images and PDFs.

const sourcePart =
  mediaType === "application/pdf"
    ? ({ type: "file", data: bytes, mediaType: "application/pdf" } as const)
    : ({ type: "image", image: bytes, mediaType } as const);

Passing a PDF as a file part makes Gemini rasterise and OCR it natively, so no Node-side preprocessing converting pages into images one at a time is needed. Images stay on the image part as before.

Preventing a repeat

The threshold is set low, at 20 characters per page. A real text PDF reaches hundreds of characters per page while a scanned one is near zero, so the gap between them is wide, and 20 sits near the bottom of it. That wide gap is the premise on which 20 can safely be chosen.

OCR is a superset of text-layer extraction (it reads the whole document, so running it on a text PDF still gives a correct result), so the misjudgement this setting can actually produce — a genuinely short PDF falling under 20 and going to OCR unnecessarily — tips toward the result being unchanged and only the egress cost rising. What we want to avoid is the other direction: lower the threshold further and a genuinely scanned PDF clears it, is never OCR’d, and comes back thin. That miss is invisible to the caller.

When no OCR client is injected, the decision still runs but no actual fallback is possible, so the thin text is returned rather than failing closed. In exchange for not stopping the extraction itself, the presence of meta.ocrUsed lets the caller tell whether the OCR path was taken.