Metadata-Version: 2.4
Name: gemmd
Version: 0.1.0
Summary: Convert PDF to Markdown using Google Gemini. Optimized for academic papers with math.
Author: Kett
License-Expression: MIT
Project-URL: Homepage, https://github.com/ktl-ao/gemmd
Project-URL: Repository, https://github.com/ktl-ao/gemmd
Project-URL: Issues, https://github.com/ktl-ao/gemmd/issues
Keywords: pdf,markdown,gemini,academic,latex,math,converter
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-generativeai>=0.8
Requires-Dist: python-dotenv>=1.0
Requires-Dist: tqdm>=4.60
Requires-Dist: pypdf>=4.0
Dynamic: license-file

# 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

```bash
pip install gemmd
```

Or install from source:

```bash
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](https://aistudio.google.com/apikey).

**Quick start** (interactive):

```bash
gemmd setup
```

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

**Or configure individually:**

```bash
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

```bash
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:

```bash
cd ~/papers
gemmd
```

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

### List available models

```bash
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
