> ## 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 (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 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.
</Note>

## 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](../../developer_edition/wxOde_setup).
</Note>

## 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"))
   ```

   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:

<ParamField path="name" type="string" required>
  Unique identifier for the node.
</ParamField>

<ParamField path="llm" type="string">
  The LLM used for field extraction. The default value is `watsonx/meta-llama/llama-3-2-90b-vision-instruct`.
</ParamField>

<ParamField path="display_name" type="string">
  Display name for the node.
</ParamField>

<ParamField path="fields" type="object" required>
  The fields you want to extract.
</ParamField>

<ParamField path="description" type="string">
  Description of the node.
</ParamField>

<ParamField path="input_map" type="DataMap">
  Define input mappings using a structured collection of Assignment objects.
</ParamField>

<ParamField path="enable_hw" type="bool">
  Enable the handwritten feature by setting this to `true`.
</ParamField>

<ParamField path="min_confidence" type="float">
  The minimum acceptable confidence for an extracted field value.
</ParamField>

<ParamField path="review_fields" type="List[string]">
  The fields that require user review.
</ParamField>

<ParamField path="enable_review" type="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`.
</ParamField>

<ParamField path="field_extraction_method" type="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).
</ParamField>

<ParamField path="page_range" type="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.

  <Expandable title="PageRange fields">
    <ParamField path="page_range.start" type="int" required>
      The first page to extract. Pages are numbered from 1, inclusive.
    </ParamField>

    <ParamField path="page_range.end" type="int" required>
      The last page to extract. Pages are numbered from 1, inclusive.
    </ParamField>
  </Expandable>

  Use `PageRange(start=1, end=5)` to extract fields from pages 1 through 5.
</ParamField>

<ParamField path="language" type="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.
</ParamField>

<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.
</Note>

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
```