Getting Started

What is Structure-D?

Structure-D is a document extraction framework built from the ground up for high-throughput structured inference with vLLM. It ingests any document format and returns validated, schema-constrained structured data guaranteed to match your Pydantic model — using vLLM's guided_json constrained decoding to make invalid output physically impossible.

When vLLM is not available, the same pipeline runs unchanged against OpenAI, Anthropic, Gemini, or Ollama — with zero code changes. Cloud providers are first-class citizens for prototyping, fallback, and frontier-model use cases.

It is designed around four principles:

• vLLM-first — PagedAttention + continuous batching + guided_json means hundreds of concurrent extractions on a single GPU with guaranteed schema conformance.
• Format-focused, not domain-specific — Structure-D handles file formats (PDF, DOCX, HTML, …), not document types. You define what you want to extract.
• Schema-driven — Your Pydantic model is the contract. Structure-D validates every output and retries automatically on failure.
• Async-first — Every I/O operation is async. Process thousands of documents in parallel without blocking.

How it works

Every document flows through a six-stage pipeline:

1. Ingestion — a format-appropriate parser extracts raw text, tables, and images from your file
2. Preprocessing — text is normalized, cleaned, and chunked into optimal-size segments
3. Model Routing — the router selects the best registered model for your task and schema
4. Inference — vLLM uses guided_json constrained decoding to guarantee schema-valid output; cloud providers (OpenAI, Anthropic, Gemini, Ollama) use structured output / function-calling APIs
5. Validation — every output is validated against the Pydantic model; invalid outputs trigger an automatic retry with a refined prompt
6. Storage — results are written to JSONL, CSV, Markdown, or a database destination

Quick start

Install Structure-D with the extras you need:

pip install "structure-d[ingestion,api,llm]"

Then extract structured data from any document:

import asyncio
from pathlib import Path
from pydantic import BaseModel
from structure_d.pipeline import Pipeline
from structure_d.inference.providers import VLLMProvider  # primary engine

# 1. Define your extraction schema as a Pydantic model
class Invoice(BaseModel):
    vendor: str
    invoice_number: str
    total_amount: float
    line_items: list[str]
    due_date: str | None = None

# 2. Create the pipeline — VLLMProvider uses guided_json for guaranteed schema conformance
async def main():
    pipeline = Pipeline(
        schema_cls=Invoice,
        provider=VLLMProvider(),     # default: http://localhost:8000/v1
        # provider=AnthropicProvider()  # swap in any cloud provider with no other changes
    )

    # 3. Run on a file — format is auto-detected (PDF, DOCX, HTML, images, ...)
    results = await pipeline.run(Path("invoice.pdf"))

    for result in results:
        print(result.structured_output)
        # {"vendor": "Acme Corp", "invoice_number": "INV-001", "total_amount": 1240.00, ...}

asyncio.run(main())

Structure-D automatically detects the file format, selects the appropriate parser, chunks the content, runs inference with constrained decoding (guided_json on vLLM, structured output on cloud providers), and validates the result — retrying up to 3 times with a refined prompt on failure.

from structure_d.schemas.generic import get_schema

# Use a built-in schema by name
KeyValue = get_schema("key_value")
pipeline = Pipeline(schema_cls=KeyValue, provider=OpenAIProvider())

Common use cases

Structure-D is built for any task where you need to pull structured fields out of a document.

Core concepts

Schema-driven extraction

Every extraction job is backed by a Pydantic model. Structure-D converts your model to a JSON Schema and passes it to the LLM as a guided_json constraint (vLLM) or a tool-use parameter (OpenAI, Anthropic). The model is forced to produce output that matches your type signature.

from pydantic import BaseModel, Field

class Contract(BaseModel):
    parties: list[str] = Field(description="Names of all signing parties")
    effective_date: str = Field(description="Contract start date in YYYY-MM-DD format")
    termination_clause: str | None = Field(None, description="Termination conditions verbatim")
    jurisdiction: str = Field(description="Governing law / jurisdiction")

Automatic format detection

When you pass a Path to pipeline.run(), Structure-D inspects the file extension and MIME type to select the right parser automatically. You can also specify a parser explicitly.

Validation and automatic retry

After inference, SchemaValidator runs the raw LLM output through Pydantic. If validation fails, RetryHandler sends the model a new prompt that includes the original output, the Pydantic error messages, and a reminder of the schema. The default retry budget is 3 attempts.

Next steps

• Installation — detailed install options, extras, and Rust CLI setup
• Configuration — configure providers, models, chunking, and storage
• Basic Usage Guide — more extraction examples across file formats
• Advanced Usage — batch processing, RAG, custom providers
• Core Pipeline API — full API reference

FAQ

files = list(Path("invoices/").glob("*.pdf"))
results = await pipeline.run_many(files, max_concurrent=8, save_format="jsonl")