> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Document field extractor node

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 BASH theme={null}
orchestrate server start -e <.env file path> -d
```

> [!NOTE]
>
> **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]
>
> **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](https://developer.watson-orchestrate.ibm.com/developer_edition/wxOde_setup.md).

## Configuring document extractor node in agentic workflows

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

   ```py Python theme={null}
   field: DocExtConfigField = Field(name="Field name", default=DocExtConfigField(name="Field name", field_name="field_name"))
   ```

   `DocExtConfigField` has two distinct attributes that serve different purposes:

   | Attribute | Purpose | Example |
   | - | - | - |
   | `name` | Human-readable display label shown in the UI and used by the LLM to identify the field during extraction. | `"Invoice Number"` |
   | `field_name` | Machine-readable normalized key used to reference the extracted value in output mappings and downstream nodes. Must be a valid Python identifier (lowercase, underscores). | `"invoice_number"` |

   When you map the output of a `docext` node to a downstream node or the flow output, use `field_name` — not `name` — in the expression:

   ```py Python theme={null}
   # Correct: use field_name in the output expression
   flow.map_output(output_variable="invoice_number", expression='flow["extractor_node"].output.invoice_number')

   # Incorrect: name is a display label, not the output key
   # flow.map_output(output_variable="Invoice Number", ...)
   ```

   Class example:

   ```py Python [expandable] theme={null}
   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"
           )
       )
   ```

2. 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:

**name** `string` *required*

Unique identifier for the node.

**llm** `string`

The LLM used for field extraction.

Recommended models:

* For Structured Document Extractor (with `field_extraction_method = "layout"`): `watsonx/mistralai/mistral-small-3-1-24b-instruct-2503`
* For Unstructured Document Extractor (with `field_extraction_method = "classic"`): `watsonx/meta-llama/llama-4-maverick-17b-128e-instruct-fp8`

**display\_name** `string`

Display name for the node.

**fields** `object` *required*

The fields you want to extract.

**description** `string`

Description of the node.

**input\_map** `DataMap`

Define input mappings using a structured collection of Assignment objects.

**enable\_hw** `bool`

Enable the handwritten feature by setting this to `true`.

**min\_confidence** `float`

The minimum acceptable confidence for an extracted field value.

**review\_fields** `List[string]`

The fields that require user review.

**enable\_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`.

**field\_extraction\_method** `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](https://ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=builder-adding-document-extractors#tools-agent-doc-extractor__doc_extractor_tool_options__title__1).

**page\_range** `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.

**PageRange fields**

**page\_range.start** `int` *required*

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

**page\_range.end** `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.

**language** `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]
>
> **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:

```py Python [expandable] theme={null}
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:

```py Python [expandable] theme={null}
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:

```py Python [expandable] theme={null}
@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`:

```py Python theme={null}
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`.

```py Python [expandable] theme={null}
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
```

> [!NOTE]
>
> 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"`.

```py Python [expandable] theme={null}
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
```

> [!NOTE]
>
> `available_options` requires `field_extraction_method="layout"`. It has no effect when using the default `classic` extraction method.
