---
slug: "okrapdf-pi"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/okrapdf/pi@main/README.md"
repo: "https://github.com/okrapdf/pi"
source_file: "README.md"
branch: "main"
---
# PDF Parse for Pi

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

```bash
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

```text
/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:

```text
/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:

```text
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](https://github.com/run-llama/parsebench) and okraPDF’s MIT-licensed parser implementation.

## Development

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

Node.js 22.19 or newer is required.