extract()

Overview

The extract() function is the primary API for Struktur. It takes artifacts, a JSON schema, and an extraction strategy, then returns validated, structured data.

Function signature

export const extract = async <T>(
  options: ExtractionOptions<T>,
): Promise<ExtractionResult<T>>

Parameters

options

ExtractionOptions<T>

required

Configuration object for the extraction process.

Show properties

artifacts

Artifact[]

required

Array of artifacts to extract data from. Each artifact represents a pre-parsed document with text and optional media content.

schema

TypedJSONSchema<T> | AnyJSONSchema

required

JSON Schema definition for the output type. Use JSONSchemaType<T> from Ajv for type-safe results.

strategy

ExtractionStrategy<T>

required

The extraction strategy to use (e.g., simple(), parallel(), sequential()). Strategies define how artifacts are chunked, processed, and merged.

events

ExtractionEvents

default:"undefined"

Optional event handlers for monitoring extraction progress.

Show properties

onStep

(info: StepInfo) => void | Promise<void>

Called at each major step of the extraction process.

Show StepInfo properties

step

number

required

Current step number (1-indexed).

total

number

Total estimated steps for this strategy.

label

string

Human-readable label (e.g., “start”, “extract”, “merge”, “complete”).

onMessage

(info: MessageInfo) => void | Promise<void>

Called when messages are exchanged with the LLM.

Show MessageInfo properties

role

'system' | 'user' | 'assistant' | 'tool'

required

The role of the message sender.

content

unknown

required

The message content.

onProgress

(info: ProgressInfo) => void | Promise<void>

Called during chunking or batch processing.

Show ProgressInfo properties

current

number

required

Current progress count.

total

number

required

Total items to process.

percent

number

Optional percentage (0-100).

onTokenUsage

(info: TokenUsageInfo) => void | Promise<void>

Called after each LLM call with token usage information.

Show TokenUsageInfo properties

inputTokens

number

required

Number of input tokens used.

outputTokens

number

required

Number of output tokens generated.

totalTokens

number

required

Total tokens (input + output).

model

string

Model identifier that was used.

Returns

ExtractionResult<T>

Promise<ExtractionResult<T>>

A promise that resolves to the extraction result.

Show properties

data

required

The extracted data, validated against the provided schema. If extraction fails, this will be null (cast to T).

usage

Usage

required

Token usage statistics for the extraction.

Show properties

inputTokens

number

required

Total input tokens consumed across all LLM calls.

outputTokens

number

required

Total output tokens generated across all LLM calls.

totalTokens

number

required

Sum of input and output tokens.

error

Error

Present if the extraction failed. When an error occurs, data will be null and usage will show zero tokens.

Basic example

import { extract, simple } from "@mateffy/struktur";
import type { JSONSchemaType } from "ajv";
import { google } from "@ai-sdk/google";

type Output = { title: string; description: string };

const schema: JSONSchemaType<Output> = {
  type: "object",
  properties: {
    title: { type: "string" },
    description: { type: "string" },
  },
  required: ["title", "description"],
  additionalProperties: false,
};

const result = await extract({
  artifacts: [myArtifact],
  schema,
  strategy: simple({ model: google("gemini-2.0-flash-exp") }),
});

if (result.error) {
  console.error("Extraction failed:", result.error);
} else {
  console.log(result.data.title);
  console.log("Used", result.usage.totalTokens, "tokens");
}

Parallel extraction example

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

const result = await extract({
  artifacts: multiPageDocument,
  schema,
  strategy: parallel({
    model: google("gemini-2.0-flash-exp"),
    mergeModel: google("gemini-2.0-flash-exp"),
    chunkSize: 10_000,
    concurrency: 4,
  }),
});

With event handlers

import { extract, simple } from "@mateffy/struktur";

const result = await extract({
  artifacts,
  schema,
  strategy: simple({ model }),
  events: {
    onStep: ({ step, total, label }) => {
      console.log(`Step ${step}/${total}: ${label}`);
    },
    onTokenUsage: ({ inputTokens, outputTokens, model }) => {
      console.log(`${model}: ${inputTokens} in, ${outputTokens} out`);
    },
  },
});

Error handling

The extract() function catches all errors and returns them in the result object rather than throwing:

const result = await extract({ artifacts, schema, strategy });

if (result.error) {
  // Extraction failed - handle the error
  console.error("Failed:", result.error.message);
  // result.data will be null (cast to T)
  // result.usage will show { inputTokens: 0, outputTokens: 0, totalTokens: 0 }
} else {
  // Success - use result.data
  console.log(result.data);
}

Core API

Strategies

Artifacts

CLI

Overview

Function signature

Parameters

Returns

Basic example

Parallel extraction example

With event handlers

Error handling

See also

Build docs developers (and LLMs) love

Core API

Strategies

Artifacts

CLI

​Overview

​Function signature

​Parameters

​Returns

​Basic example

​Parallel extraction example

​With event handlers

​Error handling

​See also

Build docs developers (and LLMs) love

Overview

Function signature

Parameters

Returns

Basic example

Parallel extraction example

With event handlers

Error handling

See also