structx

Advanced structured data extraction from any document using LLMs with multimodal support.

See the project roadmap for planned portable business rules and semantic validation work.

structx is a powerful Python library for extracting structured data from text, tables, and documents using Large Language Models (LLMs). It passes existing PDFs directly to vision-capable models; the optional docs extra converts other document formats to PDF first.

🔔 Package rename notice (PyPI)

The PyPI distribution has been renamed from structx-llm to structx (September 2025).

• Imports are unchanged: continue using import structx
• Document processing now lives in the optional docs extra
• Please update your environments and requirement files to use the new name

Upgrade commands:

pip uninstall -y structx-llm
pip install -U structx

If you previously pinned structx-llm in requirements or lock files, replace it with structx. Install structx[docs] for non-PDF document conversion.

✨ Key Features

🎯 Advanced Document Processing

• � Multimodal PDF Pipeline: Passes PDFs directly to vision-capable models and converts supported non-PDF documents to PDF
• 🖼️ Vision-Enabled Extraction: Native instructor multimodal support for PDFs and images
• 🔄 Smart Format Detection: Automatic processing mode selection for best results
• 📊 Flexible File Support: CSV, Excel, JSON, Parquet, raw text, and existing PDFs in the base install; DOCX, PPTX, images, and more via structx[docs]

🚀 Intelligent Data Extraction

• 🔄 Dynamic Model Generation: Create type-safe Pydantic models from natural language queries
• 🎯 Automatic Schema Inference: Intelligent schema generation and refinement
• 📊 Complex Data Structures: Support for nested and hierarchical data
• 🔄 Natural Language Refinement: Improve models with conversational instructions

⚡ Performance & Reliability

• 🚀 High-Performance Processing: Threaded sync and native async row requests
• 🔄 Robust Error Handling: Automatic retry mechanism with exponential backoff
• 📈 Token Usage Tracking: Detailed step-by-step metrics for cost monitoring
• Flexible Configuration: Model settings from arguments, YAML, environment variables, dotenv files, and secrets through Pydantic Settings
• 🔌 Multiple LLM Providers: Support through litellm integration

Installation

pip install structx

For converting DOCX, PowerPoint, OpenDocument, markup, image, and other non-PDF document formats:

pip install "structx[docs]"

For estimating PDF page and text counts before extraction, without running an extraction:

pip install "structx[measurement]"        # embedded text only
pip install "structx[measurement-ocr]"    # adds local OCR for scanned pages

🔧 What The Package Provides

• Structured readers for CSV, Excel, JSON, Parquet, and Feather
• Instructor multimodal vision support
• Optional Docling document parsing with CPU-only PyTorch resolution for uv on Linux
• Optional WeasyPrint PDF rendering for non-PDF document formats
• Optional standalone document measurement, separate from the extraction path

Quick Start

Basic Text Extraction

from structx import Extractor

# Initialize extractor
extractor = Extractor.from_litellm(
    model="gpt-4o",
    api_key="your-api-key",
    max_retries=3,      # Automatically retry on transient errors
    min_wait=1,         # Start with 1 second wait
    max_wait=10         # Maximum 10 seconds between retries
)

# Extract from text
result = extractor.extract(
    data="System check on 2024-01-15 detected high CPU usage (92%) on server-01.",
    query="extract incident date and details"
)

# Access results
print(f"Successful rows: {result.success_count}")
print(result.data[0].model_dump_json(indent=2))

📄 Document Processing with Multimodal Support

Install structx[docs] before using non-PDF document formats. Existing PDFs can be passed directly through the multimodal path with the base installation.

# Process a PDF invoice through the multimodal pipeline
result = extractor.extract(
    data="scripts/example_input/S0305SampleInvoice.pdf",
    query="extract the invoice number, total amount, and line items"
)

# Convert a DOCX contract and process with multimodal support
result = extractor.extract(
    data="scripts/example_input/free-consultancy-agreement.docx",
    query="extract parties, effective date, and payment terms"
)

📏 Document Measurement Before Extraction

Install structx[measurement] to size a PDF without extracting it. This path is independent of extraction: it never converts or replaces the input file.

from structx.measurement import DocumentMeasurer

measurement = DocumentMeasurer(ocr_mode="auto").measure(
    "scripts/example_input/S0305SampleInvoice.pdf"
)

# Estimates, plus whether every page could actually be measured
print(measurement.page_count, measurement.character_count, measurement.status)

📊 Token Usage Monitoring

# Check token usage for cost monitoring
usage = result.usage
if usage:
    print(f"Total tokens: {usage.total_tokens}")
    for step, calls in usage.steps.items():
        print(step.value, [call.total_tokens for call in calls])

🚀 Why Multimodal PDF Processing?

The innovative multimodal approach provides significant advantages over traditional text-based extraction:

• 📄 Context Preservation: Full document layout and structure are maintained
• 🎯 Higher Accuracy: Vision models can interpret tables, charts, and complex layouts
• 🔄 No Chunking Issues: Eliminates problems with information split across chunks
• 📊 Universal Format: Existing PDFs are passed through directly; supported non-PDF documents become processable through PDF conversion
• 🖼️ Visual Understanding: Handles documents with visual elements, formatting, and structure

📚 Documentation

For comprehensive documentation, examples, and guides, visit our documentation site.

• Getting Started
• Basic Extraction
• Working with Results
• Unstructured Text Processing
• Async Operations
• Multiple Queries
• Custom Models
• Token Usage Tracking
• API Reference

Examples

Check out our example gallery for real-world use cases,

📁 Supported File Formats

📊 Structured Data (Direct Processing)

• CSV: Comma-separated values with custom delimiters
• Excel: .xlsx/.xls with sheet selection and custom options
• JSON: JavaScript Object Notation with nested support
• Parquet: Columnar storage format for large datasets
• Feather: Fast binary format for data frames

📄 Unstructured Documents (Multimodal Pipeline)

🔄 Processing Pipeline

• PDF passthrough: Existing PDFs are sent directly to multimodal extraction
• Docling parsing: Reads non-PDF document-like inputs into a structured document model
• WeasyPrint rendering: Converts Docling HTML to a temporary PDF for non-PDF inputs
• Multimodal extraction: Sends the rendered PDF to instructor's multimodal API

Contributing

Contributions are welcome! Please read our Contributing Guidelines for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.