open-xtract 0.2.0
Extract structured data from documents, images, audio, and video using LLMs
Requires Python: >=3.12
Keywords: ai, document, extraction, llm, pydantic, structured-data

# Open Xtract

[![PyPI version](https://img.shields.io/pypi/v/open-xtract.svg)](https://pypi.org/project/open-xtract/)
[![PyPI downloads](https://img.shields.io/pypi/dm/open-xtract.svg)](https://pypi.org/project/open-xtract/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![CI](https://github.com/Mellow-Artificial-Intelligence/open-xtract/actions/workflows/ci.yml/badge.svg)](https://github.com/Mellow-Artificial-Intelligence/open-xtract/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/Mellow-Artificial-Intelligence/open-xtract)
[![Pydantic v2](https://img.shields.io/badge/pydantic-v2-E92063.svg)](https://docs.pydantic.dev/)
[![pydantic-ai](https://img.shields.io/badge/pydantic--ai-1.37+-7C3AED.svg)](https://ai.pydantic.dev/)

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

## Installation

```bash
uv add open-xtract
```

## Usage

```python
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:

```python
from open_xtract import configure_logging

configure_logging()
```

## Error Handling

```python
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:

```bash
uv add open-xtract[temporal]
```

```python
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

| Type | Extensions |
|------|------------|
| Documents | `.pdf`, `.doc`, `.docx`, `.txt`, `.html`, `.csv`, `.xls`, `.xlsx` |
| Images | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.bmp`, `.svg` |
| Audio | `.mp3`, `.wav`, `.ogg`, `.flac`, `.aac`, `.m4a` |
| Video | `.mp4`, `.mov`, `.avi`, `.mkv`, `.webm`, `.wmv` |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.