pi-pdf-reader

Pi extension for reading local PDF files as:

• extracted text,
• layout-aware Markdown with page/block coordinates and font hints,
• embedded image metadata and optional extracted image files,
• rendered page PNG images so vision-capable models can inspect formatting, charts, diagrams, scanned pages, and complex layouts.

The package is split into:

TypeScript Pi extension -> tool registration, path resolution, image return
Python worker           -> PyMuPDF PDF parsing/rendering/extraction

Install/load

Install from Git

Install globally for all Pi projects:

pi install https://git.otmatas.com/pi-extensions/pi-pdf-reader

Install only for the current project by writing to .pi/settings.json:

pi install -l https://git.otmatas.com/pi-extensions/pi-pdf-reader

Try it once without adding it to settings:

pi -e https://git.otmatas.com/pi-extensions/pi-pdf-reader

Pi clones Git packages under:

~/.pi/agent/git/git.otmatas.com/pi-extensions/pi-pdf-reader/

On Windows this is usually:

%USERPROFILE%\.pi\agent\git\git.otmatas.com\pi-extensions\pi-pdf-reader\

Project-local installs are cloned under:

.pi/git/git.otmatas.com/pi-extensions/pi-pdf-reader/

Update the package later with:

pi update --extension https://git.otmatas.com/pi-extensions/pi-pdf-reader

Remove it with:

pi remove https://git.otmatas.com/pi-extensions/pi-pdf-reader

Load from this workspace

From this workspace, load directly:

pi -e ./pi-pdf-reader

Pi package entry:

{
  "pi": {
    "extensions": ["./extensions/pdf-reader.ts"]
  }
}

Python dependencies

Install Python support inside the Pi agent container/host, then install the worker dependency.

If you installed from Git globally on Windows cmd.exe, use %USERPROFILE% because ~ is not expanded by cmd:

py -m pip install -r "%USERPROFILE%\.pi\agent\git\git.otmatas.com\pi-extensions\pi-pdf-reader\requirements.txt"

On PowerShell:

python -m pip install -r "$env:USERPROFILE\.pi\agent\git\git.otmatas.com\pi-extensions\pi-pdf-reader\requirements.txt"

On macOS/Linux shells:

python -m pip install -r ~/.pi/agent/git/git.otmatas.com/pi-extensions/pi-pdf-reader/requirements.txt

If you are running from this workspace:

python -m pip install -r requirements.txt

Required package:

PyMuPDF

Check availability in Pi:

/pdf-python-check

Config/data path

Development convention path:

~/.pi/agent/pi-pdf-reader/

This extension stores no persistent config, accounts, tokens, or credentials. When saveRenderedPages or extractImages is used without imageOutputDir, output files are written under:

~/.pi/agent/pi-pdf-reader/output/<timestamp>/

Environment variables, project-local config, legacy config, and migration files are not supported in this development version.

Commands

/pdf-python-check

Checks that Python and PyMuPDF are available to the worker.

Tools

pdf_read

Reads a local .pdf file.

Parameters:

• path (required): PDF path. Relative paths resolve from the current workspace; a leading @ is accepted.
• pages: 1-based list/ranges like "1", "1-3,7", or "all". Default: all pages, limited by maxPages.
• password: password for encrypted PDFs.
• mode: "text", "layout", or "visual". Default: "layout".
• renderPages: attach rendered page PNGs. Default true only for mode="visual".
• maxRenderPages: maximum selected pages to render. Default 3.
• dpi: render DPI. Default 144.
• maxImageBytes: maximum rendered PNG bytes per page before downscaling/skipping. Default 6000000.
• saveRenderedPages: save rendered page PNGs to disk.
• extractImages: save embedded raster images to disk.
• imageOutputDir: output directory for saved images. Relative paths resolve from the current workspace.
• maxPages: maximum pages to process for text/layout. Default 20.
• maxTextChars: maximum Markdown characters returned. Default 80000.

Examples:

{
  "path": "docs/report.pdf",
  "pages": "1-3",
  "mode": "layout"
}

{
  "path": "@docs/scanned-contract.pdf",
  "pages": "1",
  "mode": "visual",
  "renderPages": true,
  "dpi": 180
}

{
  "path": "docs/catalog.pdf",
  "pages": "all",
  "mode": "layout",
  "extractImages": true,
  "imageOutputDir": "pdf-images"
}

Security notes

• The tool reads local PDF files requested by the agent/user.
• It does not execute PDF JavaScript, submit forms, or contact network resources.
• Embedded images/rendered pages can contain sensitive document contents; saved outputs should be handled like the source PDF.
• Passwords are passed only to the worker process request file in a temporary directory and are not persisted by the extension.