Petey

Petey is a framework for PDF data extraction. It wires the PDF parser of your choice to the LLM of your choice, and with a simple blueprint from the user, pulls data out of PDF documents.

pip install petey

For the web version, demos and tutorials, visit Petey.

Why Petey?

The PDF format was designed to look identical on any screen or printer. It was format and technology agnostic, a universal container for the printed page. But all that mattered was its visual presentation. As long as it rendered correctly, the internal representation didn't matter.

And so the inside of a PDF is often chaotic. It is just a bunch of items — words, characters, shapes, images — and their coordinates, with little or no regard for the relationship between anything. What reads as one cohesive line of text could be three groups of words that happened to be positioned sequentially with the same y-value.

A lot of hard-working folks have developed tools to extract text from PDFs over the years. AI can be a big help too — you don't need a particularly advanced LLM to interpret some fairly difficult documents. But models need infrastructure, and not everyone has time to wire it all together.

Petey does the wiring for you. Just pass it your files and a blueprint that explains what you want, and it returns a JSON or CSV with your data.

How it works

1. Parse — extract text from the PDF using a local or cloud parser
2. LLM — send the text to an LLM with your blueprint to get the fields you want back
3. Output — return the results as JSON or CSV

Parsers

See petey list parsers for all available parsers.

LLM Backends

Petey ships direct, hand-coded backends per provider family and uses litellm only as a fallback for the long tail. The right backend is auto-detected from the model name; override with --llm-backend when the default isn't right (e.g. running gpt-4o through Azure rather than direct OpenAI).

Run petey list llm to see every backend wired up in your install.

Custom model registry

The built-in registry covers common cases. To add your own — e.g. an Azure OpenAI tenant with its own endpoint, or a remote Ollama host — edit ~/.petey/models.yaml:

petey models init      # writes a commented template
petey models path      # prints the resolved file path
petey models list      # shows all registered models with provenance

# ~/.petey/models.yaml
my-azure-gpt-4o:
  provider: azure_openai
  model: gpt-4o                                            # Azure deployment name
  config:
    api_version: "2024-06-01"
    azure_endpoint: https://my-tenant.openai.azure.com
    api_key_env: MY_AZURE_KEY                              # env var holding the key

remote-qwen:
  provider: ollama
  model: qwen2.5:7b
  config:
    base_url: http://gpu-box.local:11434/v1

Then petey extract -m my-azure-gpt-4o ... works from any directory. User-config entries override built-ins on key collision. Use $PETEY_MODELS=path/to/file.yaml to point at a different file, or --models-config PATH for a one-off run.

Setup

Add your API key to a .env file:

OPENAI_API_KEY=sk-...

Or for other providers:

ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=...
DEEPSEEK_API_KEY=...
MISTRAL_API_KEY=...
TOGETHER_API_KEY=...
OPENROUTER_API_KEY=...
FIREWORKS_API_KEY=...
GROQ_API_KEY=...
DATALAB_API_KEY=...

Azure OpenAI, Bedrock, and Vertex use platform-specific auth (OPENAI_API_BASE + API_VERSION, AWS boto3 chain, GCP service account). For those, register the deployment in ~/.petey/models.yaml (see Custom model registry) so endpoint and version travel with the model name.

Blueprints

Every extraction starts with a blueprint — a .bpt file (YAML format) that tells Petey what to look for.

name: Invoice
fields:
  vendor:
    type: string
    description: Company name on the invoice
  amount:
    type: number
    description: Total amount due
  date:
    type: date
  status:
    type: category
    values: [Paid, Unpaid, Overdue]

Field types

All fields are nullable — Petey returns null for anything it can't find rather than guessing.

Blueprint options

CLI

# Basic extraction
petey extract --blueprint invoice.bpt ./invoices/ -o results.csv

# With options
petey extract --blueprint blueprint.bpt --model claude-sonnet-4-6 --parser datalab ./pdfs/

# Route a model through a non-default backend (here: gpt-4o on Azure)
petey extract --blueprint blueprint.bpt -m gpt-4o --llm-backend azure_openai ./pdfs/

# Inspect what's available
petey list parsers
petey list llm
petey models list

Python API

from petey import extract, load_blueprint

response_model, spec = load_blueprint("invoice.bpt")

result = extract("invoice.pdf", response_model)

# With options
result = extract(
    "invoice.pdf",
    response_model,
    model="claude-sonnet-4-6",
    parser="datalab",
    llm_backend="azure_openai",   # optional override
)

Custom models registered in ~/.petey/models.yaml are picked up automatically — no code changes needed; just reference the entry by name in model=.

Migrating to v0.5.1

User-facing concepts have been renamed from "schema" to "blueprint" and the file extension from .yaml to .bpt. The YAML format itself is unchanged.

Old names still work in v0.5.1 with a DeprecationWarning and will be removed in v0.6.0. To migrate existing .yaml blueprint files, just rename them — the file format is unchanged:

find . -name "*.yaml" -exec sh -c 'mv "$1" "${1%.yaml}.bpt"' _ {} \;

Optional Dependencies

pip install petey                    # Core (pymupdf, pdfplumber, openai, anthropic, litellm)
pip install petey[unstructured]      # + Unstructured API client
pip install petey[all]               # Everything

Direct backends with extra SDK requirements: