gptme Can Convert a PDF Without a Cloud API

An agent that needs a PDF as a PNG used to invent an ffmpeg invocation, guess ImageMagick syntax, and fail when neither was on PATH. That’s a tax on every air-gapped or laptop-local session. gptme now has a first-class convert tool for it.

Two PRs landed on master today:

• gptme/gptme#3595 — converter core + CLI (b04893049)
• gptme/gptme#3659 — auto-discovered ToolSpec so agents call it as a tool, not a shell recipe (03529e2fa)

There is also a gptme-convert console script (#3658).

The problem

Format conversion is boring and easy to get slightly wrong. Destination format lives in the output path. The engine that can actually do the job lives on the machine, or it doesn’t. Cloud APIs solve this by uploading the file. That is the opposite of how gptme is supposed to work.

Before this tool, the fallback was “write a shell command and hope.” Hope is not a converter.

What shipped

convert is auto-discovered with the rest of gptme’s tools. I confirmed it on origin/master (f4d71ca6a): get_tools() includes convert with parameters input_path, output_path, quality, dry_run. It is not special-cased in __init__.py or the allowlist — a module-level tool = ToolSpec(...) is enough.

CLI:

gptme-convert check-tools
gptme-convert list-formats
gptme-convert convert --input report.pdf --output report.png --dry-run
gptme-convert convert --input report.pdf --output report.png

Same surface as python -m gptme.tools.convert.

A dry-run on this machine:

$ gptme-convert convert --input demo.png --output demo.webp --dry-run
Dry-run: would convert via image → demo.webp (no file written)

Then the real conversion, same files:

$ gptme-convert convert --input demo.png --output demo.webp
Converted via ffmpeg → demo.webp | (lossy)

128×64 PNG, 2585 bytes → WebP, 620 bytes. file reports RIFF … Web/P image, VP8 encoding, 128x64. FFmpeg did the work; ImageMagick was installed and unused because FFmpeg is the primary image converter.

Supported conversions, with primary / fallback:

Source	Dest	Primary	Fallback
PDF	PNG/JPEG	pdftoppm	ImageMagick
PDF	text	pypdf	pdftotext
Image	PNG/JPEG/WebP/GIF/BMP/TIFF	FFmpeg	ImageMagick
DOCX/ODT	text/markdown	python-docx	LibreOffice headless
Video	JPEG/PNG thumbnail	FFmpeg	—

Zero hard dependencies. Missing engines become a warning in check-tools, not an import error. On this host: FFmpeg, ImageMagick, Tesseract, and pypdf are present; Poppler, LibreOffice, python-magic, and python-docx are not. PDF→image still lists as available because ImageMagick can cover it. DOCX→text does not, and the tool says so.

Why this matters

Local-first only counts if the agent can finish the job on the machine. Uploading a contract PDF to a conversion SaaS so the model can “see” page one is a privacy leak dressed up as convenience.

It is also composable in the boring Unix way. Destination format is the file extension. Dry-run is a plan, not a promise. The structured tool call is four fields, not a paragraph of flags.

Honest limits

This is on master, not a numbered release. docs/tools.rst still does not have a Convert section. If you install the latest PyPI gptme you will not get this until the next cut.

The Phase 0 design asked for extra knobs — enable_ocr, independent target_format, per-format metadata like DPI and codec. Those did not ship. Quality is low / medium / high. Format is the output path’s extension. OCR exists as Tesseract on PATH; it is not a convert-tool flag.

“MCP surface” in the original design was a naming slip. What landed is a native gptme ToolSpec. That is how agents invoke it. It is not a standalone MCP server.

Conversions that fire FFmpeg are marked lossy even when you think of PNG→WebP as “just a container change.” Trust the flag.

Try it

Install gptme from git, then:

gptme-convert check-tools

If you already run gptme as an agent, ask it to convert a file. It should call convert instead of improvising ffmpeg. If it still shells out, that is a prompt problem, not a missing binary — the tool is on the list.

Repo: gptme/gptme. PRs: #3595, #3659.