Open Xtract

Extract structured data from documents, images, audio, and video using LLMs.

Installation

uv add open-xtract

Usage

from pydantic import BaseModel
from open_xtract import extract

class PdfInfo(BaseModel):
    summary: str
    language: str

result = extract(
    schema=PdfInfo,
    model="google-gla:gemini-3-flash-preview",
    url="https://example.com/document.pdf",
    instructions="return a 2 sentence summary and the primary language of the document",
)
print(result)

Logging

To enable logfire instrumentation for tracing:

from open_xtract import configure_logging

configure_logging()

Error Handling

from open_xtract import (
    extract,
    ExtractionError,
    ModelError,
    SchemaValidationError,
    UrlFetchError,
)

try:
    result = extract(...)
except UrlFetchError as e:
    print(f"Failed to fetch URL: {e}")
except SchemaValidationError as e:
    print(f"Output didn't match schema: {e}")
except ModelError as e:
    print(f"Model API error: {e}")
except ExtractionError as e:
    print(f"Extraction failed: {e}")

Durable Execution

For long-running extractions that need to survive failures, use Temporal-backed durable execution:

uv add open-xtract[temporal]

from open_xtract import extract, stop_temporal

result = extract(
    schema=PdfInfo,
    model="openai:gpt-5.2",
    url="https://example.com/document.pdf",
    instructions="Extract document info",
    durable=True,  # enables Temporal
    temporal_ui=True,  # optional, starts UI on http://localhost:8080
)

# Optional: clean up Docker containers when done
stop_temporal()

When durable=True:

• Automatically starts Temporal server via Docker (requires Docker to be running)
• Uses PostgreSQL for persistent workflow state
• Provides automatic retries and failure recovery
• Optionally starts Temporal UI for workflow monitoring

Supported Media Types

Contributing

See CONTRIBUTING.md for development setup and guidelines.