Document field extractor node (Public preview)

Use the document field extractor node to extract specific fields from your documents.

Pre-requisites

Run the following command to enable watsonx Orchestrate Developer Edition to process documents:

BASH

orchestrate server start -e <.env file path> -d

Note: You need to configure a minimum allocation of 20GB RAM to your Docker engine during installation of watsonx Orchestrate Developer edition to support document processing features.

Limitations

Text extractors have the following limits and restrictions:

Area	Description
Maximum file size	10 MB (except for Microsoft Excel files). Note: The maximum file size for Microsoft Excel files is 0.1 MB.
Maximum number of uploaded files	5 files
Accepted file types	.doc, .docx, .jpe, .jpeg .jpg, .pdf, .png, .ppt, .pptx, .tif, .tiff, and .xlsx
Maximum number of pages	600 pages
Maximum number of images	No limit
Maximum number of images per page	No limit

Note: To run the document field extractor, you must define the WATSONX_SPACE_ID, WATSONX_APIKEY, and WATSONX_PROJECT_ID credentials in your .env file. For more information on configuring the .env file, see Installing the watsonx Orchestrate Developer Edition.

Configuring document extractor node in agentic workflows

Define the fields to extract. Create a class that defines the fields you want to extract. Each field must follow this structure:

Python

field: DocExtConfigField = Field(name="Field name", default=DocExtConfigField(name="Field name", field_name="field_name"))

Class example:

Python

class Fields(BaseModel):
    """
    Configuration schema for document extraction fields.
    
    Defines the fields to be extracted from contract documents, including
    their names, types, and descriptions. Each field is configured with
    a DocExtConfigField that specifies how the document extractor should
    identify and extract the information.
    
    In this example, we define a number of custom fields for a Contract or 
    Agreement document:
        buyer: The purchasing party in the contract
        seller: The selling party in the contract
        agreement_date: The date when the agreement was signed (date type)
        agreement_number: Unique identifier for the contract
        contract_type: Classification of the contract 
    """
    buyer: DocExtConfigField = Field(
        name="Buyer",
        default=DocExtConfigField(
            name="Buyer",
            field_name="buyer"
        )
    )

Configure the document extract node

In your agentic workflow, include a call to the docext() method to extract an field from a document. This method accepts the following input arguments:

string

required

Unique identifier for the node.

string

The LLM used for field extraction. The default value is watsonx/meta-llama/llama-3-2-90b-vision-instruct.

string

Display name for the node.

object

required

The fields you want to extract.

string

Description of the node.

DataMap

Define input mappings using a structured collection of Assignment objects.

bool

Enable the handwritten feature by setting this to true.

float

The minimum acceptable confidence for an extracted field value.

List[string]

The fields that require user review.

bool

Enables or disables the human-in-the-loop feature. Set to True to activate it and False to deactivate. The default value is False.

string

Selects the Document Extractor runtime. The default value is classic, which uses the Unstructured Document Extractor. To use the Structured Document Extractor, set the value to layout. For more information, see Choosing a tool option for extracting fields from documents.

PageRange

Limits extraction to a specific range of pages. Use this parameter only when field_extraction_method is set to layout. Using page_range with the classic method raises an error.

Show PageRange fields

int

required

The first page to extract. Pages are numbered from 1, inclusive.

int

required

The last page to extract. Pages are numbered from 1, inclusive.

Use PageRange(start=1, end=5) to extract fields from pages 1 through 5.

LanguageCode

The ISO-639 language code that specifies the document’s language for OCR processing. Use the LanguageCode enum to specify supported languages (e.g., LanguageCode.fr for French, LanguageCode.ja for Japanese). This parameter is essential for scanned PDFs and images containing non-Latin scripts, as it ensures the correct OCR engine is used to recognize characters accurately. Programmatic documents (PDF, .docx, .pptx) do not require this setting.

Note:The min_confidence and review_fields settings control the human-in-the-loop feature. This feature only works when you run the Flow from a chat session. If a field is extracted with confidence lower than min_confidence, and its name appears in review_fields, the agent opens a review window in the chat. You can then review and confirm the extracted values.

The docext node accepts input of type DocumentProcessingCommonInput, from the module ibm_watsonx_orchestrate.flow_builder.types. You can also supply page_range on DocumentProcessingCommonInput instead of setting it at design time on docext(). The same layout-only constraint applies: page_range has no effect unless you set field_extraction_method='layout' on the node. Example use of the docext node in an agentic workflow:

Python

from pydantic import BaseModel, Field
from ibm_watsonx_orchestrate.flow_builder.flows import (
    Flow, flow, START, END
)
from ibm_watsonx_orchestrate.flow_builder.types import DocExtConfigField, DocumentProcessingCommonInput


class Fields(BaseModel):
    """
    Configuration schema for document extraction fields.
    
    Defines the fields to be extracted from contract documents, including
    their names, types, and descriptions. Each field is configured with
    a DocExtConfigField that specifies how the document extractor should
    identify and extract the information.
    
    In this example, we define a number of custom fields for a Contract or 
    Agreement document:
        buyer: The purchasing party in the contract
        seller: The selling party in the contract
        agreement_date: The date when the agreement was signed (date type)
        agreement_number: Unique identifier for the contract
        contract_type: Classification of the contract 
    """
    buyer: DocExtConfigField = Field(
        name="Buyer",
        default=DocExtConfigField(
            name="Buyer",
            field_name="buyer"
        )
    )
    
    seller: DocExtConfigField = Field(
        name="Seller",
        default=DocExtConfigField(
            name="Seller",
            field_name="seller"
        )
    )
    
    agreement_date: DocExtConfigField = Field(
        name="Agreement date",
        default=DocExtConfigField(
            name="Agreement Date",
            field_name="agreement_date",
            type="date"
        )
    )
    
    agreement_number: DocExtConfigField = Field(
        name="Agreement number",
        default=DocExtConfigField(
            name="Agreement Number",
            field_name="agreement_number",
            description="The identifier of this contract."
        )
    )
    
    contract_type: DocExtConfigField = Field(
        name="Contract type",
        default=DocExtConfigField(
            name="Contract Type",
            field_name="contract_type",
            type="string",
            description="The type of contract between the buyer and the seller."
        )
    )


@flow(
    name ="custom_flow_docext_example",
    display_name="custom_flow_docext_example",
    description="Extraction of custom fields from a document, specified by the user.",
    input_schema=DocumentProcessingCommonInput
)
def build_docext_flow(aflow: Flow = None) -> Flow:
    # aflow.docext returns 2 objects: the document extractor node and the schema of the extracted values.
    # In this example, doc_ext_node is the node and is added to the flow.
    # _ExtractedValues is the output schema of doc_ext_node and can be used as the input schema of nodes downstream in the flow.

    doc_ext_node, _ExtractedValues = aflow.docext(
        name="contract_extractor",
        display_name="Extract fields from a contract",
        description="Extracts fields from an input contract file",
        llm="watsonx/mistralai/mistral-small-3-1-24b-instruct-2503",
        fields=Fields()
    )

    aflow.sequence(START, doc_ext_node, END)
    return aflow

Using the language parameter

For scanned PDFs and images containing non-Latin scripts, specify the document’s language to ensure accurate OCR processing:

Python

from pydantic import BaseModel, Field
from ibm_watsonx_orchestrate.flow_builder.flows import (
    Flow, flow, START, END
)
from ibm_watsonx_orchestrate.flow_builder.types import (
    DocExtConfigField, DocumentProcessingCommonInput, LanguageCode
)


class Fields(BaseModel):
    """
    Configuration schema for document extraction fields.
    
    Defines the fields to be extracted from contract documents, including
    their names, types, and descriptions.
    """
    buyer: DocExtConfigField = Field(
        default=DocExtConfigField(
            name="Buyer",
            field_name="buyer"
        )
    )
    
    seller: DocExtConfigField = Field(
        default=DocExtConfigField(
            name="Seller",
            field_name="seller"
        )
    )
    
    agreement_date: DocExtConfigField = Field(
        default=DocExtConfigField(
            name="Agreement Date",
            field_name="agreement_date",
            type="date"
        )
    )
    
    agreement_number: DocExtConfigField = Field(
        default=DocExtConfigField(
            name="Agreement Number",
            field_name="agreement_number",
            description="The identifier of this contract."
        )
    )
    
    contract_type: DocExtConfigField = Field(
        default=DocExtConfigField(
            name="Contract Type",
            field_name="contract_type",
            type="string",
            description="The type of contract between the buyer and the seller."
        )
    )


@flow(
    name="document_extractor_with_language",
    display_name="Document Extractor with Language",
    description=(
        "Extracts custom fields from a document using a specified OCR language. "
        "Setting the language ensures the correct OCR engine is used for scanned PDFs "
        "and images, improving field extraction accuracy for non-Latin script documents."
    ),
    input_schema=DocumentProcessingCommonInput
)
def build_docext_language_flow(aflow: Flow = None) -> Flow:
    """
    Build a document extraction flow with language-aware OCR support.
    
    This example demonstrates how to use the language parameter to select the
    correct OCR engine before field extraction.
    
    Use the LanguageCode enum to specify the ISO-639 language code that matches
    the document's language.
    """
    doc_ext_node, _ExtractedValues = aflow.docext(
        name="contract_extractor_language",
        display_name="Extract Fields (Japanese)",
        description=(
            "Extracts fields from a Japanese-language scanned contract document. "
            "Uses the Japanese OCR engine to correctly recognise non-Latin characters."
        ),
        llm="watsonx/meta-llama/llama-4-maverick-17b-128e-instruct-fp8",
        fields=Fields(),
        language=LanguageCode.ja,
    )
    
    aflow.sequence(START, doc_ext_node, END)
    return aflow

Using the language parameter with structured document extractor

When using the layout field extraction method, you can also specify the language parameter:

Python

@flow(
    name="document_extractor_structured_with_language",
    display_name="Structured Document Extractor with Language",
    description=(
        "Extracts custom fields from a document using the structured extractor "
        "with a specified OCR language for improved accuracy."
    ),
    input_schema=DocumentProcessingCommonInput
)
def build_docext_structured_language_flow(aflow: Flow = None) -> Flow:
    """
    Build a structured document extraction flow with language-aware OCR support.
    """
    doc_ext_node, _ExtractedValues = aflow.docext(
        name="contract_extractor_structured_language",
        display_name="Extract Fields (German)",
        description=(
            "Extracts fields from a German-language scanned contract document. "
            "Uses the German OCR engine to correctly recognise Latin-script characters."
        ),
        llm="watsonx/mistralai/mistral-small-3-1-24b-instruct-2503",
        field_extraction_method="layout",
        fields=Fields(),
        language=LanguageCode.de,
    )
    
    aflow.sequence(START, doc_ext_node, END)
    return aflow

Extracting table fields

Use DocExtConfigTableField to extract tabular data — such as invoice line items — from structured documents. Table extraction requires field_extraction_method="layout". Import DocExtConfigTableField alongside DocExtConfigField:

Python

from ibm_watsonx_orchestrate.flow_builder.types import (
    DocExtConfigField,
    DocExtConfigTableField,
    DocumentProcessingCommonInput,
)

Each DocExtConfigTableField defines a table with a list of column definitions, where each column is a standard DocExtConfigField.

Python

from pydantic import BaseModel, Field
from ibm_watsonx_orchestrate.flow_builder.flows import END, START, Flow, flow
from ibm_watsonx_orchestrate.flow_builder.types import (
    DocExtConfigField,
    DocExtConfigTableField,
    DocumentProcessingCommonInput,
)


class Fields(BaseModel):
    """
    Extraction schema for an invoice document, mixing atomic fields
    and a table field for line items.
    """
    buyer: DocExtConfigField = Field(
        default=DocExtConfigField(name="Buyer", field_name="buyer")
    )
    seller: DocExtConfigField = Field(
        default=DocExtConfigField(name="Seller", field_name="seller")
    )
    agreement_date: DocExtConfigField = Field(
        default=DocExtConfigField(
            name="Agreement Date", field_name="agreement_date", type="date"
        )
    )

    # Table field: each row is a line item with four columns
    line_items: DocExtConfigTableField = Field(
        default=DocExtConfigTableField(
            name="Invoice Line Items",
            field_name="line_items",
            description="The line items of the invoice.",
            fields=[
                DocExtConfigField(
                    name="Item Name",
                    field_name="item",
                    type="string",
                    description="Name of the item",
                    example_value="Product ABC",
                ),
                DocExtConfigField(
                    name="Quantity",
                    field_name="quantity",
                    type="number",
                    description="Quantity of items ordered",
                    example_value="10",
                ),
                DocExtConfigField(
                    name="Unit Price",
                    field_name="unit_price",
                    type="number",
                    description="Price per unit",
                    example_value="50.00",
                ),
                DocExtConfigField(
                    name="Amount",
                    field_name="amount",
                    type="number",
                    description="Total amount for the line item",
                    example_value="500.00",
                ),
            ],
        )
    )


@flow(
    name="invoice_extractor_with_tables",
    display_name="Invoice Extractor with Tables",
    description="Extracts atomic fields and a line-items table from an invoice.",
    input_schema=DocumentProcessingCommonInput,
)
def build_docext_tables_flow(aflow: Flow) -> Flow:
    doc_ext_node, _ExtractedValues = aflow.docext(
        name="invoice_extractor",
        display_name="Extract invoice fields and line items",
        description="Extracts header fields and tabular line items from an invoice",
        llm="watsonx/mistralai/mistral-small-3-1-24b-instruct-2503",
        fields=Fields(),
        field_extraction_method="layout",  # Required for table extraction
    )

    aflow.sequence(START, doc_ext_node, END)
    return aflow

Table extraction requires field_extraction_method="layout". Using DocExtConfigTableField with the default classic method raises an error.

Using available_options to constrain extracted values

Use the available_options parameter on a DocExtConfigField to restrict the extracted value to a predefined list. This is useful when the field value must be inferred from visual cues — for example, a currency symbol (€) that should map to "EUR" — and you want to prevent the LLM from hallucinating invalid values. available_options requires field_extraction_method="layout".

Python

from pydantic import BaseModel, Field
from ibm_watsonx_orchestrate.flow_builder.flows import END, START, Flow, flow
from ibm_watsonx_orchestrate.flow_builder.types import DocExtConfigField, DocumentProcessingCommonInput


class Fields(BaseModel):
    """
    Extraction schema for an invoice. The currency field uses available_options
    to map currency symbols to their ISO codes and prevent hallucinations.
    """
    buyer: DocExtConfigField = Field(
        default=DocExtConfigField(
            name="Buyer",
            field_name="buyer",
            description="The purchasing party",
        )
    )
    seller: DocExtConfigField = Field(
        default=DocExtConfigField(
            name="Seller",
            field_name="seller",
            description="The selling party",
        )
    )
    currency: DocExtConfigField = Field(
        default=DocExtConfigField(
            name="Currency",
            field_name="currency",
            type="string",
            description=(
                "The currency used in the invoice. "
                "May appear as symbols (€, $, £, ¥) rather than spelled out."
            ),
            available_options=["USD", "EUR", "GBP", "JPY", "CAD", "AUD", "CHF", "CNY"],
        )
    )


@flow(
    name="invoice_extractor_with_options",
    display_name="Invoice Extractor with Available Options",
    description="Extracts invoice fields using available_options to constrain inferred values.",
    input_schema=DocumentProcessingCommonInput,
)
def build_docext_with_options_flow(aflow: Flow) -> Flow:
    doc_ext_node, _ExtractedValues = aflow.docext(
        name="invoice_extractor_with_options",
        display_name="Extract Invoice Fields with Options",
        description="Extracts invoice fields with available_options to reduce hallucinations",
        llm="watsonx/mistralai/mistral-small-3-1-24b-instruct-2503",
        fields=Fields(),
        field_extraction_method="layout",  # Required for available_options
    )

    aflow.sequence(START, doc_ext_node, END)
    return aflow

available_options requires field_extraction_method="layout". It has no effect when using the default classic extraction method.

Release Notes

Get Started

Build

Deploy

Analyze

Developer experience

Legal notices

Document field extractor node (Public preview)

Pre-requisites

Limitations

Configuring document extractor node in agentic workflows

Using the language parameter

Using the language parameter with structured document extractor

Extracting table fields

Using available_options to constrain extracted values

​Pre-requisites

​Limitations

​Configuring document extractor node in agentic workflows

​Using the language parameter

​Using the language parameter with structured document extractor

​Extracting table fields

​Using available_options to constrain extracted values

Pre-requisites

Limitations

Configuring document extractor node in agentic workflows

Using the language parameter

Using the language parameter with structured document extractor

Extracting table fields

Using available_options to constrain extracted values