| name | pdf |
| description | Read PDFs locally without OCR or an API key — classify text-based versus scanned in tens of milliseconds and name the pages that still need OCR, convert to markdown with headings, lists and tables intact, and pull positioned text or the exact characters inside a box on a page. |
pdf
The pdf worker parses PDF documents on the machine. A PDF is not text: reading
one with a file-reading function returns binary noise and spends the context on
it, so every PDF goes through pdf::* instead. Parsing is local, needs no
credential, and sends nothing anywhere.
Its first job is a routing decision. pdf::classify samples the document's
content streams and answers whether the pages hold real characters or are
photographs of pages, plus which individual pages cannot be read without a
vision model and why. That verdict decides whether the rest of the work is
worth doing at all, and it is what separates "this document is empty" from
"this document is a scan".
Its second job is reading. Text-based documents convert to markdown that keeps
the shape of the original, because headings, lists and tables are recovered
from font sizes and page geometry rather than from any structure the file
promises. Underneath that sit the positions themselves, for callers that need
to know where text is and not only what it says.
This worker is called on demand. It registers no harness hook and injects
nothing into any prompt, so a conversation that never touches a document never
pays for it. Reach for it when one appears.
When to Use
- A conversation names a PDF path or hands one over: call
pdf::classify
before anything else. Never read a PDF with a file-reading function; it
returns binary noise and spends the context on it.
- Read a document:
pdf::to-markdown, narrowed with pages when it is long.
- Search or embed a document rather than read it:
pdf::extract-text.
- Decide whether a document is worth sending to a vision model, and which of
its pages:
pdf::classify, then read pages_needing_ocr and ocr_reasons.
- A vision model located a region and you want the real characters rather than
its transcription:
pdf::extract-regions.
- Reason about layout, headings by size, or where a value sits on the page:
pdf::extract-items.
Boundaries
- Nothing here rasterizes a page, so nothing here can OCR. Scanned and
image-based documents are classified and routed, never read. Image content
is reported as a placeholder with a real box and no pixels.
document::ocr
is where routed pages go when the document worker is installed: it renders
them and reads them with a vision model, so it costs money per page. Hand it
the pages_needing_ocr this worker named rather than the whole file.
suspected_garbled_text in ocr_reasons means the text layer decodes to
nonsense. Do not trust the extraction, whatever document_type says.- Responses are capped.
truncated: true with a much larger total_chars
means you hold a fragment and must not answer from it. Narrow with pages
rather than raising the cap: conversion cost scales with the document, so a
page filter is faster as well as smaller. max_chars: 0 lifts the cap and
belongs in a pipeline moving a document to storage, not in a call whose
result lands in the conversation.
- Encrypted documents take a
password on pdf::classify and
pdf::to-markdown only. The other three cannot decrypt and say so.
- Page numbers are 1-indexed everywhere, in requests and responses.
- Coordinates differ by function and every response states which it used:
pdf::extract-items reports PDF points from the bottom left,
pdf::extract-regions takes boxes in PDF points from the top left. Assuming
the wrong one returns text from the wrong end of the page with no error.
Functions
pdf::classify — the routing call. Document type, confidence, page count,
the 1-indexed pages needing OCR, and a machine-readable reason per page.pdf::to-markdown — markdown with headings, lists, links and tables
recovered; optional page filter, per-page output, and a fidelity or compact
profile.pdf::extract-text — plain text, no structure recovery. Cheaper than
markdown when the result will be searched or embedded.pdf::extract-items — every positioned run of characters with its box,
font, size, and recovered bold, italic, underline and strikeout.pdf::extract-regions — the text, or a markdown table, inside given boxes
on given pages.
