Skip to content
gemini-document-processing logo

Gemini Document Processing

gemini-document-processing

Guide for implementing Google Gemini API document processing - analyze PDFs with native vision to extract text, images, diagrams, charts, and tables. Use when processing documents, extracting structured data, summarizing PDFs, answering questions about document content, or converting documents to...

mattnigh/skills_collection0installs24stars

SKILL.md

Full skill instructions

Gemini Document Processing

Process and analyze PDF documents using Google Gemini's native vision capabilities. Extract structured information, summarize content, answer questions, and understand complex documents with text, images, diagrams, charts, and tables.

Core Capabilities

  • PDF Vision Processing: Native understanding of PDFs up to 1,000 pages (258 tokens/​page)
  • Multimodal Analysis: Process text, images, diagrams, charts, and tables
  • Structured Extraction: Output to JSON with schema validation
  • Document Q&A: Answer questions based on document content
  • Summarization: Generate summaries preserving context
  • Format Conversion: Transcribe to HTML while preserving layout

When to Use This Skill

Use this skill when you need to:

  • Extract structured data from PDF documents (invoices, resumes, forms)
  • Summarize long documents or reports
  • Answer questions about PDF content
  • Analyze documents with complex layouts, charts, or diagrams
  • Convert PDFs to structured formats (JSON, HTML)
  • Process multiple documents in batch
  • Build document processing pipelines

Quick Setup

1. API Key Configuration

The skill supports both Google AI Studio and Vertex AI endpoints.

Option 1: Google AI Studio (Default)

The skill checks for GEMINI_API_KEY in this priority order:

  1. Process environment variable
  2. Project root .env
  3. .claude/​.env
  4. .claude/​skills/​.env
  5. .env file in skill directory (.claude/​skills/​gemini-document-processing/​.env)

Get your API key: https://aistudio.google.com/apikey

Environment Variable (Recommended)

export GEMINI_API_KEY="your-api-key-here"

Or in .env file:

echo "GEMINI_API_KEY=your-api-key-here" > .env
Option 2: Vertex AI

To use Vertex AI instead:

# Enable Vertex AI
export GEMINI_USE_VERTEX=true
export VERTEX_PROJECT_ID=your-gcp-project-id
export VERTEX_LOCATION=us-central1  # Optional, defaults to us-central1

Or in .env file:

GEMINI_USE_VERTEX=true
VERTEX_PROJECT_ID=your-gcp-project-id
VERTEX_LOCATION=us-central1

2. Install Dependencies

pip install google-genai python-dotenv

Common Use Cases

1. Extract Structured Data from PDF

# Use the provided script
python .claude/​skills/​gemini-document-processing/​scripts/​process-document.py \
  --file invoice.pdf \
  --prompt "Extract invoice details as JSON" \
  --format json

2. Summarize Long Document

# Process and summarize
python .claude/​skills/​gemini-document-processing/​scripts/​process-document.py \
  --file report.pdf \
  --prompt "Provide a concise executive summary"

3. Answer Questions About Document

# Q&A on document content
python .claude/​skills/​gemini-document-processing/​scripts/​process-document.py \
  --file contract.pdf \
  --prompt "What are the key terms and conditions?"

4. Process with Python SDK

from google import genai

client = genai.Client()

# Read PDF
with open('document.pdf', 'rb') as f:
    pdf_data = f.read()

# Process document
response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents=[
        'Extract key information from this document',
        genai.types.Part.from_bytes(
            data=pdf_data,
            mime_type='application/​pdf'
        )
    ]
)

print(response.text)

5. Structured Output with JSON Schema

from google import genai
from pydantic import BaseModel

class InvoiceData(BaseModel):
    invoice_number: str
    date: str
    total: float
    vendor: str

client = genai.Client()

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents=[
        'Extract invoice details',
        genai.types.Part.from_bytes(
            data=open('invoice.pdf', 'rb').read(),
            mime_type='application/​pdf'
        )
    ],
    config=genai.types.GenerateContentConfig(
        response_mime_type='application/​json',
        response_schema=InvoiceData
    )
)

invoice_data = InvoiceData.model_validate_json(response.text)

Key Constraints

  • Format: Only PDFs get vision processing (TXT, HTML, Markdown are text-only)
  • Size: < 20MB use inline encoding, > 20MB use File API
  • Pages: Max 1,000 pages per document
  • Storage: File API stores for 48 hours only
  • Cost: 258 tokens per page (fixed, regardless of content density)

Performance Tips

  1. Use Inline Encoding for PDFs < 20MB (simpler, single request)
  2. Use File API for larger files or repeated queries (enables context caching)
  3. Place Prompt After PDF for single-page documents
  4. Use Context Caching when querying same PDF multiple times
  5. Process in Parallel for multiple independent documents
  6. Use gemini-2.5-flash for best price/​performance ratio

Decision Guide

PDF < 20MB?
├─ Yes → Use inline base64 encoding
└─ No  → Use File API

Need structured JSON output?
├─ Yes → Define response_schema with Pydantic
└─ No  → Get text response

Multiple queries on same PDF?
├─ Yes → Use File API + Context Caching
└─ No  → Inline encoding is sufficient

Script Reference

The skill includes a ready-to-use processing script:

# Basic usage
python scripts/​process-document.py --file document.pdf --prompt "Your prompt"

# With JSON output
python scripts/​process-document.py --file document.pdf --prompt "Extract data" --format json

# With File API (for large files)
python scripts/​process-document.py --file large-document.pdf --prompt "Summarize" --use-file-api

# Multiple prompts
python scripts/​process-document.py --file document.pdf --prompt "Question 1" --prompt "Question 2"

References

For comprehensive documentation, see:

  • references/​gemini-document-processing-report.md - Complete API reference
  • references/​quick-reference.md - Quick lookup guide
  • references/​code-examples.md - Additional code patterns

Troubleshooting

API Key Not Found:

# Check API key is set
./​scripts/​check-api-key.sh

File Too Large:

  • Use File API for files > 20MB
  • Add --use-file-api flag to the script

Vision Not Working:

  • Ensure file is PDF format
  • Other formats (TXT, HTML) don't support vision processing

Support

More skills from mattnigh

TypeScript厳格モードによる型安全性設計を専門とするスキル。 📖 参照書籍: - 『Effective TypeScript』(Dan Vanderkam): 型設計 📚 リソース参照: - `resources/Level1_basics.md`: レベル1の基礎ガイド - `resources/Level2_intermediate.md`: レベル2の実務ガイド - `resources/Level3_advanced.md`: レベル3の応用ガイド - `resources/Level4_expert.md`: レベル4の専門ガイド - `resources/di...

24 0
View
deploying-cloud-k8s logo
mattnigh/skills_collection

deploying-cloud-k8s

Deploys applications to cloud Kubernetes (AKS/GKE/DOKS) with CI/CD pipelines. Use when deploying to production, setting up GitHub Actions, troubleshooting deployments. Covers build-time vs runtime vars, architecture matching, and battle-tested debugging.

24 0
View
moai-alfred-agent-guide logo
mattnigh/skills_collection

moai-alfred-agent-guide

19-agent team structure, decision trees for agent selection, Haiku vs Sonnet model selection, and agent collaboration principles. Use when deciding which sub-agent to invoke, understanding team responsibilities, or learning multi-agent orchestration.

24 0
View
mermaid-diagram-generator logo
mattnigh/skills_collection

mermaid-diagram-generator

Converts architecture descriptions, module specs, or workflow docs into Mermaid diagrams. Use when visualizing brick module relationships, workflows (DDD, investigation), or system architecture. Supports: flowcharts, sequence diagrams, class diagrams, state machines, entity relationship diagrams,...

24 0
View
pre-flight-check logo
mattnigh/skills_collection

pre-flight-check

INVOKE FIRST before any code work. Validates git workflow (branch, issue, worklog) and checks approach. Use at START of every task and END before completing. Prevents skipped steps.

24 0
View
browser-dev-tools logo
mattnigh/skills_collection

browser-dev-tools

This skill should be used when working with browser-rendered artifacts (i.e. Bun, React/React Native) to proactively validate that development work on localhost is being built appropriately and to support debugging browser-rendered content. Use this skill after making frontend changes to verify t...

24 0
View
lead-dev logo
mattnigh/skills_collection

lead-dev

Lead Développeur - Coordination technique opérationnelle, code review, mentoring et livraison. Pair de web-dev-process au niveau OPÉRATIONS.

24 0
View
worker-monitor logo
mattnigh/skills_collection

worker-monitor

Monitor Docker workers, RQ queue health, and auto-scale workers (max 4). Use when: checking job progress, monitoring queue depth, scaling workers up/down, diagnosing slow processing, or waiting for jobs to complete. Referenced by data-quality skill during reprocessing.

24 0
View
quality-advisor logo
mattnigh/skills_collection

quality-advisor

Proactive quality guidance system that monitors artifact creation and provides real-time feedback on documentation quality

24 0
View
bump-version logo
mattnigh/skills_collection

bump-version

This skill should be used when the user wants to bump the version number in the workspace. It updates versions across all pyproject.toml files (root, tde, and tda packages) and the CHANGELOG.md to keep them synchronized.

24 0
View
check-code-quality logo
mattnigh/skills_collection

check-code-quality

Run comprehensive Rust code quality checks including compilation, linting, documentation, and tests. Use after completing code changes and before creating commits.

24 0
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View