PDF Parse for Pi

Parse local PDFs into layout-aware Markdown and normalized bounding boxes using vision models already authenticated in Pi. The package also provides phrase search and page screenshots for the agent’s follow-up work.

pi install npm:@okrapdf/pi

Tools

• pdf_parse — semantic Markdown and layout blocks using a validated model/prompt pair
• pdf_search — phrase hits with page numbers and 0–1000 bounding boxes
• pdf_screenshot — selected pages returned as image blocks and saved as PNG files

pdf_parse prefers subscription or local models before metered models, estimates metered cost, supports a hard cost ceiling, and writes durable artifacts beside the source PDF.

Commands

/pdf-parse models
/pdf-parse models default google/gemini-3-flash-preview
/pdf-parse doctor report.pdf
/pdf-parse parse report.pdf --dry-run
/pdf-parse parse report.pdf --pages 1-3,8 --max-cost 0.10
/pdf-parse parse report.pdf -m google/gemini-3-flash-preview

Authentication

The package does not read or store provider keys itself. It asks Pi’s model registry for the same API key, OAuth token, headers, and provider environment Pi uses for normal requests.

Use /login <provider> inside Pi to add or replace credentials:

/login google

/pdf-parse models shows authenticated vision models, their access class, matched prompt, and estimated per-page usage. Unmatched models remain visible as untested, but are never auto-selected.

Output

A parse writes the following under <document>.okra/ unless output_dir is supplied:

doc.md
blocks.json
manifest.json
raw/page-NNNN.txt
screenshots/page-NNNN.png

If a provider responds but the matched prompt decodes no layout blocks, the raw response and partial artifacts are preserved for diagnosis.

Only rendered page images are sent directly through the selected Pi provider. Search uses local artifacts or the native PDF text layer. Screenshot rendering is local. The package makes no requests to okrapdf services and emits no telemetry.

The layout prompts and decoder are derived from ParseBench and okraPDF’s MIT-licensed parser implementation.

Development

npm install
npm test
npm run typecheck
npm run build
npm pack --dry-run

Node.js 22.19 or newer is required.