gemmd 0.1.0

Convert PDF to Markdown using Google Gemini. Optimized for academic papers with math.

gemmd

Convert PDF to Markdown using Google Gemini. Built for academic papers and textbooks with heavy math.

Why gemmd?

Most PDF-to-Markdown tools rely on OCR or layout analysis, which butcher mathematical notation. gemmd takes a different approach: it feeds PDF pages directly to Gemini's multimodal model, which reads the document like a human would — understanding structure, math, and context all at once.

Designed for:

• Research papers with LaTeX-heavy equations
• Textbooks with theorems, proofs, and definitions
• Any PDF where math fidelity matters

Key features:

• Inline ($...$) and block ($$...$$) math preservation with \tag{} numbering
• Concurrent chunk processing with correct ordering
• Smart sentence-boundary merging across page breaks
• Batch mode — convert an entire folder in one command
• Graceful partial failure handling (failed chunks get visible markers, not silent drops)
• Post-conversion verification (page coverage + PDF outline section check)
• Academic post-processing: theorem/lemma normalization, duplicate heading removal, notation cleanup
• Cross-platform: works on macOS, Linux, and Windows

Installation

Requirements: Python >= 3.9

pip install gemmd

Or install from source:

git clone https://github.com/ktl-ao/gemmd.git
cd gemmd
pip install -e .

Setup

gemmd requires a Google Gemini API key. Get one for free at Google AI Studio.

Quick start (interactive):

gemmd setup

This will prompt you for your API key and preferred default model, then save to ~/.config/gemmd/config.

Or configure individually:

gemmd config key YOUR_API_KEY          # set API key
gemmd config model gemini-2.5-pro      # set default model
gemmd config                           # view current config

You can also use environment variables (GEMINI_API_KEY, GEMMD_MODEL) or a .env file in your working directory.

Config resolution order

Setting	Flag	Env / Config key	Default
Model	--model	GEMMD_MODEL	gemini-2.5-flash
API Key	—	GEMINI_API_KEY	—

Priority: CLI flags > local .env > ~/.config/gemmd/config > defaults.

Usage

Single file

gemmd paper.pdf                          # → paper.md
gemmd paper.pdf -o notes.md              # custom output path
gemmd paper.pdf -m gemini-2.5-pro        # use a different model
gemmd paper.pdf --chunk-size 5           # 5 pages per chunk (default: 3)
gemmd paper.pdf -c 10                    # limit to 10 concurrent requests

Batch mode

Run gemmd with no arguments to convert all PDFs in the current directory:

cd ~/papers
gemmd

• Skips files that already have a corresponding .md
• Continues on failure — check output files for [!!! MISSING CONTENT !!!] markers

List available models

gemmd --list-models

Options

Flag	Short	Default	Description
--output	-o	<input>.md	Output file path
--model	-m	gemini-2.5-flash	Gemini model to use
--concurrency	-c	20	Max concurrent API requests
--chunk-size		3	Pages per chunk
--list-models			List available Gemini models and exit

Commands

Command	Description
gemmd setup	Interactive first-time configuration
gemmd config	View current configuration
gemmd config key <KEY>	Set API key
gemmd config model <MODEL>	Set default model

How it works

1. Split — PDF is divided into chunks (default: 3 pages each)
2. Transcribe — Chunks are uploaded to Gemini concurrently with a carefully tuned prompt for academic content
3. Merge — Results are reassembled in order with intelligent sentence-boundary detection
4. Post-process — Regex pipeline normalizes theorems, deduplicates headings, fixes LaTeX artifacts
5. Verify — Page coverage check + PDF outline cross-reference to detect missing sections

If any chunks fail (rate limits, timeouts, etc.), gemmd inserts visible [!!! MISSING CONTENT !!!] markers and exits with code 1, so you can re-run to fill gaps.

Cost

Using gemini-2.5-flash (default), converting a typical 30-page paper costs fractions of a cent. The Gemini API free tier is generous enough for most personal/research use.

License

MIT