One function: give it a Pydantic schema, a model, and a file. You get back a validated instance.

from pydantic import BaseModel
from openextract import extract


class Invoice(BaseModel):
    vendor: str
    total: float
    currency: str


invoice = extract(Invoice, "openai:gpt-5", source="./invoice.pdf")  # path to a file on disk
print(invoice.total)

Install

pip install 'openextract[all]'   # or just your provider: [openai], [anthropic], [google], ...

Requires Python 3.12+. Set the API key your provider expects, such as OPENAI_API_KEY.

Usage

extract(schema, model, source, instructions=None, *, media_type=None)
await extract_async(schema, model, source, instructions=None, *, media_type=None)

• source is where the file is: a path on disk, a pathlib.Path, or an http(s):// URL. openextract opens it for you. You can also pass the file's raw bytes. A string is always treated as a path or URL, never as the document's text; to extract from text you already have, pass text.encode().
• model is any pydantic-ai model string ("anthropic:claude-sonnet-5", "google-gla:gemini-2.5-pro", "ollama:llama3", ...) or a configured pydantic-ai Model.
• instructions are optional extra guidance for the model.
• media_type is inferred for you. openextract checks the file extension, then the URL's Content-Type, then the file's leading bytes (PDF, PNG, JPEG, GIF, WebP, MP3, WAV, FLAC, OGG, MP4, UTF-8 text). Pass it only to override the result.

from pathlib import Path

extract(Invoice, "openai:gpt-5", source="./invoices/2291.pdf")  # file path
extract(Invoice, "openai:gpt-5", source=Path("invoices") / "2291.pdf")  # pathlib.Path
extract(Invoice, "anthropic:claude-sonnet-5", source="https://example.com/2291.pdf")  # URL
extract(Invoice, "openai:gpt-5", source=pdf_bytes, instructions="Amounts are in EUR.")  # bytes

Decision models

Jev, TypeSafe's decision model on OpenRouter, answers typed questions instead of writing text. Pass openrouter:typesafe/jev-1.14 (or openrouter:~typesafe/jev-latest) to fill a schema whose fields are all bool, Literal, or Enum:

from typing import Literal

from pydantic import BaseModel, Field


class Triage(BaseModel):
    document_type: Literal["invoice", "receipt", "contract"] = Field(
        description="What kind of document is this?"
    )
    is_paid: bool = Field(description="Has the amount been paid in full?")


triage = extract(Triage, "openrouter:typesafe/jev-1.14", source="./receipt.png")

Each field becomes one question, phrased by its description. A bool field is True when the probability of yes is at least 0.5. Set OPENROUTER_API_KEY; no extra is needed. Decision models read text and images only, and any other field type raises a TypeError.

Errors

Every error subclasses ExtractionError and keeps the original exception as __cause__.

If openextract can't infer the media type, it raises a ValueError and asks you to pass media_type.

License

MIT