Mistral PDF to Markdown Converter

Convert PDF documents to Markdown via Mistral's OCR API, preserving headers and structure and extracting embedded images. OCR makes it work on scanned, image-based PDFs.

Quick Start

<skill-dir> in the commands below is the directory containing this SKILL.md — substitute the real path.

# Convert entire PDF
uv run --script <skill-dir>/scripts/convert_pdf_to_markdown.py input.pdf output.md

# Convert specific pages
uv run --script <skill-dir>/scripts/convert_pdf_to_markdown.py input.pdf output.md --pages "1-5"
uv run --script <skill-dir>/scripts/convert_pdf_to_markdown.py input.pdf output.md --pages "1,3,5"

Output Structure

Each conversion is a self-contained folder. Passing Output/PDFConversions/paperalpha.md creates Output/PDFConversions/paperalpha/paper_alpha.md, with extracted images beside it under images/ as JPEGs, referenced relatively:

Output/PDFConversions/
├── paper_alpha/
│   ├── paper_alpha.md   # references images/img-N.jpeg
│   └── images/
│       ├── img-0.jpeg
│       └── img-1.jpeg
└── paper_beta/
    ├── paper_beta.md
    └── images/
        ├── img-0.jpeg
        └── ...

An existing foldered markdown path such as Output/PDFConversions/paperalpha/paperalpha.md is kept as given. A directory creates <directory>/<input-pdf-stem>.md.

Usage in Code

from pathlib import Path
import subprocess

# Run conversion script
result = subprocess.run([
    "uv", "run", "--script",
    "<skill-dir>/scripts/convert_pdf_to_markdown.py",
    "input.pdf",
    "Output/PDFConversions/output.md",
    "--pages", "1-10"
], capture_output=True, text=True)

print(result.stdout)

Requirements

A Mistral API key (below), plus mistralai, python-dotenv, pypdf, and pyyaml — declared inline in the script's PEP 723 header.

API Key Setup

The script checks these locations in order (first match wins):

1. Environment variable MISTRALAPIKEY — recommended for personal use (e.g. export MISTRALAPIKEY=your-key in secrets.sh)
2. Shared config — .claude/agent-contract.yaml or ~/.config/agent-contract/config.yaml under paper-reader.mistralapikey
3. Notes/.env — add MISTRALAPIKEY=your-key; gitignored but Dropbox-synced, so it travels with a shared project folder

Never commit API keys to git. Use environment variables or Dropbox-synced Notes/.env instead.

Error Handling

API Key Not Found:

Error: Mistral API key not found

→ Configure it per API Key Setup above

Page Out of Range:

Warning: Page 100 out of range, skipping

→ Check the PDF page count and adjust the page selection

API Rate Limit: → Retry after a moment, or reduce the page count per request

Notes

• Large PDFs take longer — API limits apply. Narrow with --pages.
• Use the pdf skill instead for local manipulation and plain text extraction with no OCR or API calls.
• Load [references/reference.md](references/reference.md) for the OCR API surface, programmatic and batch usage, cost, and troubleshooting.