Extraction Strategies

The Agent strategy is the default and recommended way to use Struktur. It gives the LLM a virtual filesystem and lets it autonomously decide how to extract your data.

For documents where you need more control, Struktur also provides alternative strategies that use fixed chunking and parallelism patterns.

Strategy comparison

Agent (Default)

Autonomous extraction using a virtual filesystem. The agent decides when to read files, search for patterns, and build output incrementally.

How it works

1. Document loaded into virtual filesystem (/artifacts/artifact.json, /artifacts/manifest.json, /artifacts/images/)
2. Agent explores using tools: read files, grep for patterns, list directories, execute commands
3. Incremental extraction — calls set_output_data when first data found, update_output_data as more discovered
4. Validation — schema validation on every output update, with automatic retry on errors
5. Completion — agent calls finish when done, or fail if extraction impossible

The agent adapts to your document:

• Small documents — reads everything at once
• Large documents — navigates systematically, searching for relevant sections
• Complex schemas — builds output incrementally, validating as it goes

Configuration

Context prefill

The agent normally spends its first steps reading /artifact.json and looking at the image overview. Prefill hands it that context up front so it can extract immediately:

import { extract, agent } from "@struktur/sdk";

const result = await extract({
  artifacts,
  schema,
  strategy: agent({
    provider: "openrouter",
    modelId: "deepseek/deepseek-v4.1-flash",
    prefill: { textTokens: 300_000, maxImages: 4 },
  }),
});

The block is deterministic — stable tool-call ids, no timestamps — so the same document always produces the same prefix and providers can prompt-cache it. Images get far less budget than text because a single page image is 1–4 MB of base64; the defaults load the image overview only.

Example

# Agent is the default — no --strategy needed
struktur extract --input ./document.pdf \
  --schema ./schema.json \
  --model anthropic/claude-sonnet-4

# With max steps limit
struktur extract --input ./document.pdf \
  --schema ./schema.json \
  --model anthropic/claude-sonnet-4 \
  --max-steps 30

import { extract, agent } from "@struktur/sdk";

const result = await extract({
  artifacts,
  schema,
  strategy: agent({
    provider: "anthropic",
    modelId: "claude-sonnet-4",
    maxSteps: 50,
  }),
});

When to use

• Always try agent first — it's the default for a reason
• Works well for most document types and sizes
• Automatically adapts to document structure
• Best for complex schemas with nested objects

Model requirements

The agent imposes two hard requirements that the other strategies do not:

Both are hard requirements, but only one is checked for you: the agent queries the provider's model catalogue for the input modalities a model accepts, and reports the result via onVisionStatus. Tool/function-calling support is not detected — a model without it fails at the provider when the first tool call is sent. Check what a provider currently offers before choosing:

struktur config models list --provider openrouter

Speed and cost

Wall-clock time often differs more between deployments of the same model than between different models. On OpenRouter, append :nitro to route to the fastest available provider:

--model "openrouter/deepseek/deepseek-v4.1-flash:nitro"

On our real-estate exposé corpus this roughly halved median extraction time for a high-volume model (~81s to ~42s), but the gain depends on how loaded the default provider is — measure on your own documents rather than assuming it. :floor is the cheapest-provider counterpart.

Reasoning models trade latency for thinking budget. --reasoning-effort low is usually enough for structured extraction, and is what Struktur's own configuration uses.

Virtual filesystem

The agent has access to a virtual filesystem containing:

• /artifacts/artifact.json — All artifacts in JSON format (images replaced by virtual paths)
• /artifacts/manifest.json — Summary and metadata
• /artifacts/images/ — Extracted image files (when artifacts have embedded images), including the generated image overview

The agent can:

• Read files with pagination (offset, limit)
• Grep for patterns
• Find files by name
• List directories
• View images by virtual path with view_image (only when the model accepts image input)
• Bash execute commands (on virtual filesystem only)

Every extracted image carries a virtualPath. The image overview is a labelled contact sheet of all of them, built at parse time, so the agent can see the whole document's visual content in one image and then open only the images that matter. See Image Overview.

Output management

Special tools for building extraction output:

• set_output_data(data) — Set initial output (first time data is found)
• update_output_data(changes) — Merge changes into existing output
• finish() — Complete extraction (only works if data validates)
• fail(reason) — Mark extraction as impossible

The agent is encouraged to update output continuously as it explores, not wait until the end.

Simple

Single-shot extraction for small inputs. Use when the agent is overkill for tiny documents.

Configuration

Algorithm

1. Build extraction prompt from artifacts + schema
2. Send to LLM
3. Validate output against the schema
4. Retry on validation failure (up to 3 attempts)
5. Return validated output

Example

struktur extract --input document.txt --schema schema.json --strategy simple

import { extract, simple } from "@struktur/sdk";
import { openai } from "@ai-sdk/openai";

const result = await extract({
  artifacts,
  schema,
  strategy: simple({
    model: openai("gpt-4o-mini"),
  }),
});

When to use

• Document fits within the model's context window (~10k tokens)
• Simple schema without nested arrays
• Testing or prototyping
• Speed is the priority
• When you want predictable token costs (agent costs vary by document)

Parallel

Concurrent batch processing with LLM merge.

Configuration

Algorithm

1. Split artifacts into batches (respecting chunkSize and maxImages)
2. Extract from each batch concurrently
3. Validate each batch output with retry
4. Send all partial results to mergeModel for LLM merge
5. Validate merged output
6. Return final result

Example

struktur extract --input large.pdf --schema schema.json --strategy parallel --model openai/gpt-4o-mini

import { extract, parallel } from "@struktur/sdk";
import { openai } from "@ai-sdk/openai";

const result = await extract({
  artifacts,
  schema,
  strategy: parallel({
    model: openai("gpt-4o-mini"),
    mergeModel: openai("gpt-4o-mini"),
    chunkSize: 10000,
    concurrency: 3,
  }),
});

When to use

• Speed is the top priority
• Chunks are relatively independent
• Many documents to process
• Can accept potential loss of cross-chunk context
• When agent costs are too high for your use case

Sequential

Process chunks in order with context preservation.

Configuration

Algorithm

1. Split artifacts into batches
2. For each batch in order:
   • Build prompt including previous extraction result as context
   • Extract from batch
   • Validate with retry
   • Store result for next iteration
3. Return final result

Example

struktur extract --input report.pdf --schema schema.json --strategy sequential --model openai/gpt-4o-mini

import { extract, sequential } from "@struktur/sdk";
import { openai } from "@ai-sdk/openai";

const result = await extract({
  artifacts,
  schema,
  strategy: sequential({
    model: openai("gpt-4o-mini"),
    chunkSize: 10000,
  }),
});

When to use

• Context between chunks matters
• Building data incrementally (e.g., accumulating line items)
• Later sections reference earlier sections
• Need better accuracy than parallel
• Agent is making too many tool calls for your document structure

Auto-Merge Strategies

parallelAutoMerge

Parallel extraction with schema-aware merge and deduplication.

Best for: Array extraction from large inputs where speed matters.

sequentialAutoMerge

Sequential extraction with schema-aware merge and deduplication.

Best for: Ordered array extraction where context matters.

doublePassAutoMerge

Double-pass extraction with schema-aware merge and deduplication.

Best for: Large array extraction with maximum quality requirement.

Choosing a Strategy

Start with the Agent. It's the default because it works best for most documents.

Quick decision flowchart

flowchart TD
    A[Start] --> B{Try Agent first?}
    B -->|Yes| C[Use agent — default]
    B -->|Need fixed costs| D{Input fits in context?}
    D -->|Yes| E[Use simple]
    D -->|No| F{Extracting arrays?}
    F -->|Yes| G{Cross-chunk context matters?}
    F -->|No| H{Cross-chunk context matters?}
    G -->|Yes| I[sequentialAutoMerge or doublePassAutoMerge]
    G -->|No| J[parallelAutoMerge]
    H -->|Yes| K[sequential or doublePass]
    H -->|No| L[parallel]

See also

• The Extraction Pipeline — where strategies fit
• Chunking & Token Budgets — how batches are formed
• Validation & Retries — the retry loop