pdf-extraction

name	pdf-extraction
description	Extract text, tables, and structured data from PDFs. Use when processing any PDF for text extraction, table extraction, search, metadata, or conversion to markdown. Supports text-based and scanned/image PDFs with OCR.

PDF Extraction

Extract text, tables, metadata, and structured information from PDF documents.

When to Use

• Pulling text, tables, or metadata from any PDF
• Converting PDFs to markdown for LLM context or RAG pipelines
• Searching within PDF content for specific sections or values
• Processing scanned/image-based PDFs with OCR

For domain-specific extraction, combine with:

• datasheet-extraction — electronics/component datasheets
• paper-extraction — academic/scientific papers

Image & Figure Extraction (Do This First)

Whenever the PDF contains images, diagrams, charts, or figures, extract them to PNGs before any OCR or analysis. Saving the raw PNGs gives you a ground-truth reference to review and correct extraction results.

# Extracts all figures to <pdf_stem>_figures/ subdirectory
uv run ~/.config/opencode/skills/pdf-extraction/scripts/extract_figures.py input.pdf

# Or specify an explicit output directory
uv run ~/.config/opencode/skills/pdf-extraction/scripts/extract_figures.py input.pdf my_figures/

Output naming: page{N:04d}_img{M:03d}.png for raster images, page{N:04d}_fig{M:03d}.png for vector/drawing regions.

Why first?

• OCR and extraction results can silently degrade or miss content; the PNG is the unambiguous source of truth
• Reviewing the PNGs lets you catch mis-detected regions, missed figures, or corrupt images before investing in downstream processing
• Figures directory doubles as a structured asset cache for any future re-extraction

After extraction, use the saved PNGs directly as input to OCR (pass them to Mistral OCR, pytesseract, or an LLM vision call) rather than re-extracting from the PDF.

Tool Selection

Scenario	Tool	Why
Fast text extraction	pymupdf4llm	Fastest, LLM-optimized markdown
Table extraction	pdfplumber	Best table detection and extraction
Scanned PDFs (API)	Mistral OCR	Best accuracy on scans, complex layouts
Scanned PDFs (local)	pytesseract + pdf2image	Free, offline, requires system deps
RAG / chunking	pymupdf4llm with page_chunks=True	Returns chunks with metadata
Figure/image extraction	extract_figures.py	Always run first when figures are present

Decision Flow

1. Does the PDF contain figures, diagrams, or images? → Extract figures first (extract_figures.py)
2. Is it scanned / image-based? → OCR path (Mistral OCR or pytesseract) — feed saved PNGs as input
3. Need tables? → pdfplumber
4. Need speed or markdown? → pymupdf4llm

Scripts

All scripts are standalone, uv-runnable with inline dependencies (PEP 723). No pre-install needed.

# 1. Extract figures/images to PNGs first (always do this when figures are present)
uv run scripts/extract_figures.py input.pdf               # → input_figures/
uv run scripts/extract_figures.py input.pdf my_figures/   # explicit output dir

# Fast markdown extraction (best default)
uv run scripts/extract_pymupdf.py input.pdf output.md

# Table-focused extraction
uv run scripts/extract_pdfplumber.py input.pdf output.md

# Scanned PDF via Mistral OCR API
MISTRAL_API_KEY="..." uv run scripts/extract_mistral_ocr.py input.pdf output.md

# Scanned PDF via local Tesseract OCR
uv run scripts/extract_with_ocr.py input.pdf output.txt

Scripts are in scripts/ relative to this skill. Use absolute paths: uv run ~/.config/opencode/skills/pdf-extraction/scripts/extract_figures.py input.pdf

Inline Extraction Patterns

Quick Text to Markdown

import pymupdf4llm

# Full document
md = pymupdf4llm.to_markdown("document.pdf")

# Specific pages
md = pymupdf4llm.to_markdown("document.pdf", pages=[0, 1, 2])

# RAG chunks with metadata
chunks = pymupdf4llm.to_markdown("document.pdf", page_chunks=True)
for chunk in chunks:
    print(f"Page {chunk['metadata']['page']}: {chunk['text'][:200]}...")

Table Extraction

import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    for page in pdf.pages:
        tables = page.extract_tables()
        for table in tables:
            # table[0] is header row, table[1:] is data
            for row in table:
                print(row)

Search Within PDF

import pdfplumber

def search_pdf(pdf_path, query, case_insensitive=True):
    """Find pages containing query text."""
    results = []
    with pdfplumber.open(pdf_path) as pdf:
        for i, page in enumerate(pdf.pages):
            text = page.extract_text() or ""
            match = query.lower() in text.lower() if case_insensitive else query in text
            if match:
                results.append({"page": i + 1, "text": text})
    return results

Extract by Region (Crop)

with pdfplumber.open("document.pdf") as pdf:
    page = pdf.pages[0]
    # bbox = (x0, top, x1, bottom) in points
    region = page.crop((0, 0, page.width, 150))
    print(region.extract_text())

Extract by Font Size

def extract_by_font_size(page, min_size=14):
    """Extract text in larger fonts (likely headings)."""
    chars = page.chars
    large = [c for c in chars if c['size'] >= min_size]
    if not large:
        return []
    lines, current = [], large[0]['text']
    for prev, c in zip(large, large[1:]):
        if abs(c['top'] - prev['top']) < 2:
            current += c['text']
        else:
            lines.append(current.strip())
            current = c['text']
    lines.append(current.strip())
    return [l for l in lines if l]

Metadata

import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    meta = pdf.metadata
    print(f"Title: {meta.get('Title')}")
    print(f"Author: {meta.get('Author')}")
    print(f"Pages: {len(pdf.pages)}")

OCR for Scanned Documents

Mistral OCR API (Recommended)

Best accuracy on complex layouts and scanned documents (98%+). ~$1/1000 pages.

from mistralai import Mistral
import base64

client = Mistral(api_key="your-key")

# From URL
response = client.ocr.process(
    model="mistral-ocr-latest",
    document={"type": "document_url", "document_url": "https://example.com/doc.pdf"}
)

# From local file
with open("scanned.pdf", "rb") as f:
    b64 = base64.standard_b64encode(f.read()).decode()
response = client.ocr.process(
    model="mistral-ocr-latest",
    document={"type": "base64", "base64": b64}
)

for page in response.pages:
    print(page.markdown)

Local OCR (Tesseract)

Free, offline. Requires: apt install tesseract-ocr poppler-utils.

import pytesseract
from pdf2image import convert_from_path

images = convert_from_path("scanned.pdf", dpi=300)
for i, img in enumerate(images):
    text = pytesseract.image_to_string(img, lang="eng")
    print(f"Page {i+1}: {text[:200]}...")

References

• references/local-tools.md — detailed comparison of all local extraction libraries
• references/api-services.md — API-based OCR services comparison and usage