> ## 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" required>
  The LLM used for field extraction. The default value is `watsonx/mistralai/mistral-small-3-1-24b-instruct-2503`.
</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>

<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 input to a `docext` node is expected to be of type `DocExtInput`, from the module `ibm_watsonx_orchestrate.flow_builder.types`.

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