Structured extraction for PythonPython 3.12+ · MIT
Any file.
Structured data.
Turn documents, images, audio, and video into validated Pydantic models.
pip install 'openextract[all]'
Define it. Extract it.
Set your provider’s API key, then pass a schema and a file.
Your code
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",
)
Validated result
- vendor
- Halvorsen Print Co.
- total
- 1240.0
- currency
- EUR
A few details.
What do I pass in?
extract(schema, model, source, instructions=None, *, media_type=None)
- schema
- The Pydantic model you want back.
- model
- A pydantic-ai model string like "anthropic:claude-sonnet-5", or a configured Model.
- source
- Where the file is: a path like "./invoice.pdf", a pathlib.Path, or an https:// URL. Or the file's raw bytes. A string is never read as the document's text.
- instructions
- Optional guidance, like "Amounts are in EUR."
- media_type
- Only needed to override what openextract infers.
How does it know the file type?
It takes the first answer it finds: the media_type you passed, the file extension, the URL's Content-Type header, then the file's leading bytes.
- Recognized by content
- PDF, PNG, JPEG, GIF, WebP, MP3, WAV, FLAC, OGG, MP4, and UTF-8 text.
What happens when it fails?
Every error subclasses ExtractionError and keeps the original exception as its cause.
- ModelError
- The provider returns an error.
- SchemaValidationError
- The output doesn't match your schema.
- ProviderNotInstalledError
- The provider's SDK isn't installed.
- ExtractionError
- A URL can't be fetched.
Which models can I use?
Any model pydantic-ai supports. Install the matching extra and set its API key.
pip install 'openextract[anthropic]' # openai, google, bedrock, groq, mistral,
# cohere, huggingface, openrouter, xai, all
Can I use decision models?
Yes. Use OpenAI Decisions with OPENAI_API_KEY, or Jev with OPENROUTER_API_KEY. Both read text and images into bool, Literal, or Enum fields. No provider extra is needed.
triage = extract(
Triage, "openai-decisions:gpt-6-luna",
source="./receipt.png",
)
- Fields
- bool, Literal, or Enum. Any other type raises a TypeError.
- Questions
- Each field becomes one question, phrased by its description.
- bool
- True when the probability of yes is at least 0.5.
- OpenAI
- Use openai-decisions: for Decisions; openai: keeps general extraction. Supports 1–400 fields.
- Sources
- Text and images only.
Is there an async version?
Yes. It takes the same arguments. Await it.
invoice = await extract_async(Invoice, "openai:gpt-5", source="./invoice.pdf")