strutex 0.8.1

Structured AI document processing with robust fallback strategies.

strutex

Structured Text Extraction — Extract structured JSON from documents using LLMs

---

Features

• Plugin System v2 — Auto-registration via inheritance, lazy loading, entry points
• Hooks — Callbacks and decorators for pre/post processing pipeline
• CLI Tooling — strutex plugins list|info|refresh commands
• Multi-Provider LLM Support — Gemini, OpenAI, Anthropic, and custom endpoints
• Universal Document Support — PDFs, images, Excel, and custom formats
• Schema-Driven Extraction — Define your output structure, get consistent JSON
• Verification & Self-Correction — built-in audit loop for high accuracy
• Security First — Built-in input sanitization and output validation

---

What's New in v0.8.1 🚀

• Smart Caching: Built-in Memory, SQLite, and Redis-ready caching to save costs on redundant extractions.
• Async & Batching: High-performance aprocess and process_batch for high-volume workflows.
• Verification Loop: Auto-correction agent that audits and fixes its own extractions.
• Expanded Providers: First-class support for OpenAI, Anthropic, Ollama, Groq, and Langdock.

---

Quick Start

Installation

View on PyPI: https://pypi.org/project/strutex/

# Core only
pip install strutex

# With CLI commands
pip install strutex[cli]

# With OCR support
pip install strutex[ocr]

# Everything
pip install strutex[all]

Basic Usage

from strutex import DocumentProcessor, Object, String, Number, Array

# Define your output schema
invoice_schema = Object(
    description="Invoice data",
    properties={
        "invoice_number": String(description="The invoice ID"),
        "total": Number(),
        "items": Array(
            items=Object(
                properties={
                    "description": String(),
                    "amount": Number(),
                }
            )
        )
    }
)

# Process a document
processor = DocumentProcessor(provider="gemini")
result = processor.process(
    file_path="invoice.pdf",
    prompt="Extract the invoice details.",
    schema=invoice_schema
)

print(result["invoice_number"])  # "INV-2024-001"
print(result["total"])           # 1250.00

Advanced Usage

1. Caching

Save API costs by caching results. Smart hashing avoids re-processing identical files/prompts.

from strutex.cache import SQLiteCache

# Persistent cache across runs
processor = DocumentProcessor(
    provider="openai",
    cache=SQLiteCache("strutex_cache.db")
)

2. Async Processing

Process multiple documents in parallel.

import asyncio

async def main():
    processor = DocumentProcessor(provider="anthropic")

    # Run in parallel
    results = await asyncio.gather(
        processor.aprocess("doc1.pdf", "Summary", schema),
        processor.aprocess("doc2.pdf", "Summary", schema)
    )

asyncio.run(main())

3. Verification & Self-Correction

Enable the audit loop to have the LLM double-check its work.

result = processor.process(
    "contract.pdf",
    prompt="Extract clauses",
    schema=contract_schema,
    verify=True  # triggers self-correction loop
)

---

CLI Commands (v0.3.0+)

# List all plugins
strutex plugins list

# Filter by type
strutex plugins list --type provider

# Get plugin details
strutex plugins info gemini --type provider

# Refresh discovery cache
strutex plugins refresh

---

Plugin System

Everything is pluggable. Just inherit from a base class:

from strutex.plugins import Provider

class MyProvider(Provider):
    """Auto-registered as 'myprovider'"""
    capabilities = ["vision"]

    def process(self, file_path, prompt, schema, mime_type, **kwargs):
        # Your LLM logic
        ...

# Customize with class arguments
class FastProvider(Provider, name="fast"):
    """Registered as 'fast' with high priority"""
    priority = 90  # Class attribute
    cost = 0.5

    def process(self, ...): ...

For Distributable Packages

Use entry points in pyproject.toml:

[project.entry-points."strutex.providers"]
my_provider = "my_package:MyProvider"

Plugin Types

Type	Purpose	Examples
provider	LLM backends	Gemini, OpenAI, Claude, Ollama
security	Input/output protection	Injection detection, sanitization
extractor	Document parsing	PDF, Image OCR, Excel
validator	Output validation	Schema, sum checks, date formats
postprocessor	Data transformation	Date/number normalization

---

Supported Formats

Format	Extensions	Method
PDF	.pdf	Text extraction with fallback chain
Images	.png, .jpg, .tiff	Direct vision or OCR
Excel	.xlsx, .xls	Converted to structured text
Text	.txt, .csv	Direct input

---

Roadmap

See ROADMAP.md for the full development plan.

Recent releases:

• v0.1.0 — Core functionality
• v0.2.0 — Plugin registry + Security layer
• v0.3.0 — Plugin System v2
• v0.6.0 — Built-in Schemas & Logging
• v0.7.0 — Providers & Retries
• v0.8.0 — Async, Batch, Cache, Verification
• v0.8.1 — Documentation & Coverage Fixes

---

Documentation

📚 Read the Docs

# Install docs dependencies
pip install mkdocs mkdocs-material mkdocstrings[python] mike

# Serve locally
mkdocs serve

# Build static site
mkdocs build

# Deploy with versioning
mike deploy 0.3.0 latest --push

---

License

This project is licensed under the GNU General Public License v3.0 — see LICENSE for details.

---

Contributing

Contributions welcome! Priority areas:

1. New plugins — Providers, extractors, validators
2. Documentation — Examples and tutorials
3. Testing — Expand test coverage