Gemini PDF

PDF-to-Markdown Conversion (via Antigravity CLI)

Note: The skill folder is named gemini-pdf for backward compatibility with the /gemini-pdf slash command. Internally it drives Antigravity CLI (agy), Google's successor to the original Gemini CLI.

When to Use

• Academic papers with mathematical notation (LaTeX reconstructed from the rendered page)
• Papers with complex tables, theorems, proofs, or two-column layouts
• Scanned PDFs (the native vision pathway OCRs them; the Mathpix fallback also handles them)
• Zero-cost conversion via a Google One AI subscription (no API keys for the primary path)

When NOT to Use

• Need exact LaTeX source → ask the author or use Mathpix directly
• Enormous documents (>500 pages) → split into chapters first (hard page ceiling)

Locating the script

Examples below call the script through $GEMINI_PDF. Set it once per shell so they work whether the skill was installed as a plugin or copied manually:

if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then
  GEMINI_PDF="$CLAUDE_PLUGIN_ROOT/skills/gemini-pdf"   # installed as a Claude Code plugin
else
  GEMINI_PDF="$HOME/.claude/skills/gemini-pdf"          # installed by manual copy
fi

(The script self-resolves its own helper scripts, so it runs correctly from any location.)

Quick Usage

# Basic: native pipeline, outputs paper.md alongside paper.pdf
bash "$GEMINI_PDF/scripts/pdf_to_markdown.sh" paper.pdf

# Specify output path
bash "$GEMINI_PDF/scripts/pdf_to_markdown.sh" paper.pdf /tmp/output.md

# Choose a pipeline explicitly
bash "$GEMINI_PDF/scripts/pdf_to_markdown.sh" paper.pdf --pipeline text
bash "$GEMINI_PDF/scripts/pdf_to_markdown.sh" paper.pdf --hybrid
bash "$GEMINI_PDF/scripts/pdf_to_markdown.sh" paper.pdf --force-mathpix

# Disable auto-chunking (single agy pass over the whole PDF)
bash "$GEMINI_PDF/scripts/pdf_to_markdown.sh" paper.pdf --no-chunk

# Disable the quality-gated fallback chain
bash "$GEMINI_PDF/scripts/pdf_to_markdown.sh" paper.pdf --no-fallback

# Custom quality threshold (default: 60)
bash "$GEMINI_PDF/scripts/pdf_to_markdown.sh" paper.pdf --quality-threshold 40

Architecture

Native pipeline (default)

agy reads the PDF directly through Gemini's vision/document pathway — math layout, column order, and table geometry are seen as rendered, not guessed back from lossy text extraction:

pdfinfo → page count P
P ≤ 10 → single chunk (whole PDF)
P > 10 → split_pdf_pages.py → chunk PDFs of ≤ 10 pages (1-indexed inclusive ranges)
for each chunk SEQUENTIALLY (global agy lock):
    isolated temp dir containing only that chunk PDF
    agy --model "$MODEL" --add-dir <dir> --print-timeout <T>s -p "<prompt>"
    validate (nonce end-sentinel + ratio guards) → retry → bisect on repeated failure
concatenate → quality gates → sanitize → output.md

• The first chunk's prompt produces YAML front matter (title/authors/year/journal/doi) plus the # Title heading; continuation chunks follow a seam protocol (transcribe from the first character of the page, resume exactly after the previous chunk's tail — provided as read-only context — never skip, never repeat).
• Failed/truncated chunks are retried once, then recursively bisected down to single pages before a <!-- CHUNK N FAILED --> placeholder is accepted.
• Prompts instruct the model to flag unreadable passages as <!-- UNCERTAIN: ... --> rather than guess — a flagged gap always beats fluent fabrication.

Concurrency constraint (hard, probe-verified)

Two concurrent agy --print processes hang (0 bytes output, both ignore their own --print-timeout; verified live 2026-07-07 on agy 1.0.16, plain and with --new-project). Consequently:

• All agy calls run strictly sequentially under a global lock ($TMPDIR/gemini-pdf-agy.lock); concurrent script invocations serialize automatically.
• Every agy call is wrapped in an external watchdog (TIMEOUT+60s) that kills the whole process group and sweeps orphans — agy's own timeout cannot be trusted under contention.
• agy --sandbox also hangs the native read (probe-verified) and is not used.

Fallback chain (auto, quality-gated)

native ──eligible & ≥threshold──→ done
   │ low
   ▼
hybrid: mathpix --mode extract → agy structural cleanup (math preserved verbatim)
   │ low
   ▼
mathpix standalone → best eligible attempt wins

Winner selection is two-stage: eligibility gates first (no failed chunks, fidelity floors, completeness floor), then comparison on literalness-neutral dimensions only (math quality, structure, OCR, failed chunks) — recall-vs-source dimensions would unfairly reward the most literal attempt. A later stage must beat an earlier one by ≥5 points to displace it. Losing attempts are kept as output.attempt-<stage>.md.

Degraded environments: agy missing → Mathpix standalone (the text pipeline needs agy too); poppler missing → text pipeline with markitdown; pypdf missing → poppler page splitter.

Model configuration

agy ≥ 1.0.5 has a working --model flag; the script passes GEMINI_PDF_MODEL (default "Gemini 3.1 Pro (High)") on every call and falls back to the ~/.gemini/antigravity-cli/settings.json model only if the installed agy lacks the flag. List models with agy models.

Quality verification

scripts/quality_check.py scores 0-100 with per-dimension breakdown:

Plus: comparison_score (literalness-neutral, for cross-attempt selection), eligible + reasons, UNCERTAIN-marker count (small penalty), and front-matter detection. Corrupted PDF text layers (some 1990s journal PDFs encode . as + or ( as Ž) are detected automatically and the source-dependent dimensions are skipped — recall against a garbled reference would punish a correct conversion. Without source text, a legacy five-dimension weighting applies. Non-mathematical documents redistribute the math weight adaptively.

Sanitization

Converted Markdown originates from an untrusted PDF; scripts/sanitize_md.py strips <script>/<iframe>/<object> blocks, HTML event-handler attributes, and javascript: URLs before any downstream use, reporting every removal.

Optional reference-library sync

Opt-in and off by default. When GEMINI_PDF_REFERENCE_DIR points to an existing directory (layout: pdf/, md/, reference.bib), the final winner (only — never intermediate attempts) is synced there: with --bib-key KEY, PDF → pdf/KEY.pdf, MD → md/KEY.md, and a BibTeX entry is appended (metadata precedence: JSON sidecar → the MD's own YAML front matter → key-only entry). Copies are skip-if-exists; --force-sync overwrites the PDF/MD copies (bib entries are never replaced). Without the env var set, nothing is written outside your output path. See docs/gemini-pdf.md.

Environment Variables

Flags

Output files

For output.md the script may also write: output.err (agy stderr per chunk), output.meta.json (per-chunk ledger: page ranges, bytes, retries, status), output.quality.json (full quality report), and output.attempt-<stage>.md (losing fallback attempts, kept for manual override).

Troubleshooting