Turn a PDF into clean Markdown plus one PNG snapshot per page.

Mistral OCR is the default. Azure Document Intelligence is available as an optional provider.

You need uv and a Mistral API key.

uv tool install read_pdf_tool

This installs the canonical read_pdf_tool command. The legacy read_pdf entry point remains available for compatibility.

read_pdf_tool setup --interactive

The prompt looks like this:

$ read_pdf_tool setup --interactive
read_pdf_tool setup

Mistral OCR configuration
Credentials will be stored in /home/you/.read_pdf_tool/.env (mode 600).

Mistral API key (hidden):

Configuration saved.
  File: /home/you/.read_pdf_tool/.env
  Provider: Mistral OCR
  Model: mistral-ocr-latest

The key is hidden while you type and stored locally in a private file.

read_pdf_tool path/to/document.pdf

The command prints the output paths when it finishes. Open pages.md for the extracted text and the page_N.png files to visually check each page.

Use the PyPI package name as the command:

uvx read_pdf_tool path/to/document.pdf

Useful for servers and automation:

export MISTRAL_API_KEY="..."
read_pdf_tool setup --non-interactive

You can also leave the key in the environment and skip setup entirely:

MISTRAL_API_KEY="..." uvx read_pdf_tool document.pdf

Existing configuration is never overwritten silently. Use --force when an intentional replacement is needed.

A default Mistral run creates a timestamped directory under ~/.read_pdf_tool/conversions/:

~/.read_pdf_tool/conversions/20260722T101624Z_document_ab12cd34/
├── pages.md       # all pages, wrapped with page boundaries
├── document.md    # combined OCR Markdown
├── page_1.md      # OCR text for page 1
├── page_1.png     # rendered snapshot for visual verification
├── response.json  # complete provider response
└── metadata.json  # paths, provider, model, and page counts

The terminal summary contains the exact directory and file paths. Use --json when another program needs to consume that summary.

# Write a copy of the merged Markdown to a specific path
read_pdf_tool document.pdf --output /tmp/document.md

# Process only pages 4 and 5
read_pdf_tool document.pdf --start-page 4 --max-pages 2

# Skip local PNG rendering
read_pdf_tool document.pdf --no-images

# Print machine-readable result metadata
read_pdf_tool document.pdf --json

# See every option
read_pdf_tool --help

The intended default workflow is:

1. Run read_pdf_tool <path>.
2. Read the pages_md path from the terminal summary.
3. Inspect every returned page_N.png snapshot unless the user says visual verification is unnecessary.

If read_pdf_tool fails, uvx markitdown <path> can be used as a text-only fallback. Make it clear that the fallback may produce lower-quality output.

Mistral is the default. To configure Azure instead:

export AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT="https://example.cognitiveservices.azure.com/"
export AZURE_API_KEY="..."
read_pdf_tool setup --non-interactive --provider azure

For a one-off Azure run:

read_pdf_tool document.pdf --provider azure

Azure defaults to the prebuilt-layout model and can use DefaultAzureCredential when no API key is supplied.

The default configuration file is ~/.read_pdf_tool/.env and is created with mode 600.

Environment variables take precedence over values loaded from the config file.

Versions before 0.3 stored configuration in ~/.read_pdf/.env. If the new configuration file does not exist, read_pdf_tool still reads that legacy file as a compatibility fallback. The old READ_PDF_PROVIDER variable is also accepted. New setup runs always write to ~/.read_pdf_tool/.env.

PDF contents are sent to the selected OCR provider. Do not process documents that you are not allowed to share with that provider.

Mistral OCR is usage-priced, not generally free. Check the current Mistral API pricing before use.

Missing Mistral API key

Run read_pdf_tool setup --interactive, or export MISTRAL_API_KEY.

The wrong provider is selected

Pass --provider mistral or --provider azure, or update READ_PDF_TOOL_PROVIDER in ~/.read_pdf_tool/.env.

Start over with setup

read_pdf_tool setup --interactive --force

From a local checkout:

uv sync
uv run pytest
uv run read_pdf_tool --help
uv build

Test the package through its real entry point before publishing:

uvx --from . read_pdf_tool --help