cherruq/pdf2md-agent

pdf2md-agent

Convert any PDF to clean, language-preserving Markdown — powered by a CrewAI vision pipeline against the MiniMax-M3 endpoint (or any OpenAI-compatible vision API you point it at).

pdf2md-agent renders each page of a PDF to an image, hands the image to a chain of small vision-language agents (extractor → formatter → running summarizer), and emits strict CommonMark Markdown that preserves the source language verbatim — including CJK content.

It is designed to be robust on adversarial inputs:

• Token-budgeted — every per-page call is sized (and the page image

downscaled) to stay under the model's context window.

• Retry-aware — transient API failures retry with Fibonacci backoff

(1, 1, 2, 3, 5, 8, 13, …) × --retry-initial-delay, capped at --retry-max-delay (default 900s / 15 min), + jitter; on retry exhaustion the page falls back to the PDF's native text layer (with a clearly-marked stub) instead of crashing the run.

• Resumable — per-page outputs and the running summary are cached, so

re-running only fills in the pages that failed. Per-resource opt-outs (--no-cache-{render,text,resized,extract,format,summary}) let you invalidate a single resource without redoing the whole pipeline.

Table of contents

• Installation
• Quick start
• Configuration
• CLI reference
• How it works
• Caching and resumption

• Troubleshooting
• Development
• License

Installation

pdf2md-agent requires Python 3.10+.

# Recommended: use uv (https://github.com/astral-sh/uv)
git clone https://github.com/cherruq/pdf2md-agent.git
cd pdf2md-agent
uv sync
uv run pdf2md-agent --help

Or with pip:

git clone https://github.com/cherruq/pdf2md-agent.git
cd pdf2md-agent
python -m venv .venv
source .venv/bin/activate
pip install -e .
pdf2md-agent --help