pdf-ingestion

name	pdf-ingestion
description	Get a PDF into the model without blowing the context window or losing structure. Native PDF beats OCR-then-text for most cases; extract-then-summarize beats native for very long docs.
when_to_use	user drops a PDF, "read this report", extracting tables/figures from a doc, long-form doc summarization, spec document that lives as PDF
targets	["*"]

PDF Ingestion

Three ways to feed a PDF to the model, in increasing order of preprocessing:

1. Native PDF input - pass the file directly. Model sees pages as images + extracted text. Best for docs under ~100 pages with meaningful layout (tables, figures, forms). Preserves structure.

2. Text extraction then send - pdftotext / pypdf / equivalent, then send the text. Loses layout but cheap. Fine for prose-heavy docs where tables don't matter.

3. Extract → chunk → summarize → send - for docs >100 pages or when you'll query the same doc many times. Preprocess once, cache the summary.

Deciding which path

Doc shape	Path
<20 pages, layout matters (report, form, invoice)	Native
<20 pages, pure prose (article, memo)	Text extraction
20-100 pages, mixed	Native, but chunk if context tight
>100 pages	Extract → chunk → summarize
Scanned PDF (no text layer)	OCR first (Tesseract or vision model), then treat as extracted text
Tables are the point	Native - text extractors mangle tables
Figures/diagrams are the point	Native + explicit "describe the figure on page N" prompt

Native PDF - the good defaults

• Cache the PDF at a prompt-caching breakpoint (see prompt-caching). Native PDFs are large - every uncached turn costs full input price on the whole doc.
• Ask about specific pages ("summarize section 3.2 on page 14") rather than the whole doc. The model handles targeted queries better than "summarize this 80-page report".
• Follow up with page-cited claims - "on which page does the doc say X?" - as a sanity check the model isn't hallucinating.

Extract-then-send - the traps

• pdftotext reading order. Multi-column PDFs come out as interleaved lines. Use pdftotext -layout for column preservation, or pdftotext -raw for straight reading order - pick per doc, don't guess.
• Tables become word soup. If tables are load-bearing, native or per-table image extraction. Not text.
• Headers/footers repeat on every page. Strip them before sending, or the model will treat them as content.
• Footnotes drift to random positions in the extracted stream. Filter or accept the noise.

Extract → chunk → summarize (long docs)

• Chunk by section, not by token count. A section-aware split respects the doc's logic; a naive 4K-token split cuts sentences and tables.
• Summarize per section into a "map" - 1-2 paragraphs each. Keep the map short enough to fit in context whole (~2-4K tokens for a 200-page doc).
• Store the full section text alongside the map (paths in a manifest). Fetch on demand when a question needs detail beyond the summary.
• Cache the map at a prompt-caching breakpoint so multi-turn Q&A over the doc doesn't reprocess.

Red flags

• Sending a 200-page PDF native to answer one question. Extract the relevant page range first.
• Trusting the text extractor on a form or invoice. Layout carries meaning. Use native.
• OCR'ing a PDF that already has a text layer. Check pdftotext -q file.pdf - first - if text comes out, no OCR needed.
• No page citations in output. Model can hallucinate confidently across long PDFs. Force page numbers into the response format.
• Re-uploading the same PDF every turn without caching. Cost climbs linearly; a 5-minute cache fixes it.

Loopkit-adjacent

If the PDF is a spec, extract it into PROMPT.md via spec-first - the agent should re-read prose, not re-scan the PDF, on every turn.