Convert

Convert#

The convert tool reformats files offline using system converters, falling back gracefully when a specific one is unavailable. Choose the destination format by the output_path extension (.png, .jpg, .txt, .md), and pass dry_run to see the converter plan without executing. It has no markdown-fence block type, so ask for it in natural language and let the model call it with structured arguments:

gptme "convert report.pdf to report-page-1.png at high quality, dry run first"

File format conversion tool for gptme.

Provides offline, multi-format file conversion with auto-detection and graceful degradation when specific converters are unavailable.

Supported conversions:

  • PDF → PNG/JPEG (Poppler/pdftoppm, ImageMagick fallback)

  • Image → Image: PNG ↔ JPEG ↔ WebP (FFmpeg primary, ImageMagick fallback)

  • DOCX → text/markdown (python-docx, LibreOffice headless fallback)

  • MP4/video → JPEG thumbnail (FFmpeg)

  • PDF → text (pypdf, Poppler/pdftotext fallback)

class gptme.tools.convert.ConversionResult

ConversionResult(success: ‘bool’, output_path: ‘Path | None’, converter_used: ‘str’, warnings: ‘list[str]’ = <factory>, error: ‘str | None’ = None, lossy: ‘bool’ = False, metadata: ‘dict’ = <factory>)

__init__(success: bool, output_path: ~pathlib.Path | None, converter_used: str, warnings: list[str] = <factory>, error: str | None = None, lossy: bool = False, metadata: dict = <factory>) → None
class gptme.tools.convert.Converter
class gptme.tools.convert.DocumentToTextConverter

DOCX/ODT/etc. → plain text or markdown via python-docx or LibreOffice.

class gptme.tools.convert.ImageConverter

Image ↔ image format conversion via FFmpeg (primary) or ImageMagick.

class gptme.tools.convert.PDFToImageConverter

PDF pages → raster images (PNG/JPEG) via pdftoppm or ImageMagick.

class gptme.tools.convert.PDFToTextConverter

PDF → plain text via pypdf or pdftotext (Poppler).

class gptme.tools.convert.ToolAvailability

ToolAvailability(ffmpeg: ‘bool’ = <factory>, imagemagick: ‘bool’ = <factory>, pdftoppm: ‘bool’ = <factory>, pdftotext: ‘bool’ = <factory>, libreoffice: ‘bool’ = <factory>, tesseract: ‘bool’ = <factory>, python_magic: ‘bool’ = <factory>, python_docx: ‘bool’ = <factory>, pypdf: ‘bool’ = <factory>)

__init__(ffmpeg: bool = <factory>, imagemagick: bool = <factory>, pdftoppm: bool = <factory>, pdftotext: bool = <factory>, libreoffice: bool = <factory>, tesseract: bool = <factory>, python_magic: bool = <factory>, python_docx: bool = <factory>, pypdf: bool = <factory>) → None
class gptme.tools.convert.VideoThumbnailConverter

Video → JPEG thumbnail via FFmpeg.

gptme.tools.convert.convert_file(src: Path, dest: Path, quality: str = 'medium', dry_run: bool = False, **kwargs) → ConversionResult

Main entry point for file conversion.

Parameters:

  • src – Source file path.

  • dest – Destination file path (extension determines target format).

  • quality – One of ‘low’, ‘medium’, ‘high’.

  • dry_run – If True, return converter plan without executing.