Document classifier node

Use the document classifier node to classify 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.

Note: To run the document classifier, you must define the WO_INSTANCE, WO_API_KEY, and AUTHORIZATION_URL credentials in your .env file. For more information on configuring the .env file, see Installing the watsonx Orchestrate Developer Edition.

Limitations

The document classifier node has the following limits and restrictions:

Area	Description
Maximum number of classes	10 classes per classifier node
Accepted file types	.pdf, .png, .jpg, .jpeg, .tif, .tiff, .doc, .docx, .ppt, .pptx
Human-in-the-loop in embedded chat	The human-in-the-loop review feature is not supported when the workflow is accessed through embedded web chat. It only works in a standard chat session.

Configuring document extractor node in agentic workflows

Define document classes. Create a class that defines the document classes to classify. Each document class must follow this structure:

Python

class CustomClasses(BaseModel):
"""
Configuration schema for document classification classes.

Defines the document types/classes that the classifier can identify.
Each class is configured with a DocClassifierClass that specifies the
class name used for categorizing input documents. The classifier uses
an LLM to analyze documents and assign them to one of these classes.

Example custom classes:
    invoice: Configuration for identifying invoice documents
    contract: Configuration for identifying contract documents
    tax_form: Configuration for identifying tax form documents
    bill_of_lading: Configuration for identifying bill of lading documents
"""
invoice: DocClassifierClass = Field(default=DocClassifierClass(class_name="Invoice"))
contract: DocClassifierClass = Field(default=DocClassifierClass(class_name="Contract"))
tax_form: DocClassifierClass = Field(default=DocClassifierClass(class_name="TaxForm"))
bill_of_lading: DocClassifierClass = Field(default=DocClassifierClass(class_name="BillOfLading"))

Configure the document classifier node

Include a call to the docclassifier() method in your agentic workflow to classify the document. This method accepts the following input arguments:

string

required

Unique identifier for the node.

string

required

The LLM used for document classification. The default value is watsonx/meta-llama/llama-4-maverick-17b-128e-instruct-fp8.

string

Display name for the node.

object

required

The document classification classes.

string

Description of the node.

float

Minimum confidence threshold for classification.

DataMap

Define input mappings using a structured collection of Assignment objects.

bool

Enable the handwritten feature by setting this to true.

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.

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 setting controls the human-in-the-loop feature. This feature only works when you run the Flow from a chat session. If the document is classified with confidence lower than min_confidence, or as Other, the agent opens a review window in the chat. You can then review and confirm the extracted values.

Example use of the docext node in an agentic workflow:

Python

from pydoc import Doc
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 DocClassifierClass, DocumentProcessingCommonInput, DocumentClassificationResponse


class CustomClasses(BaseModel):
    """
    Configuration schema for document classification classes.
    
    Defines the document types/classes that the classifier can identify.
    Each class is configured with a DocClassifierClass that specifies the
    class name used for categorizing input documents. The classifier uses
    an LLM to analyze documents and assign them to one of these classes.
    
    Example custom classes:
        invoice: Configuration for identifying invoice documents
        contract: Configuration for identifying contract documents
        tax_form: Configuration for identifying tax form documents
        bill_of_lading: Configuration for identifying bill of lading documents
    """
    invoice: DocClassifierClass = Field(default=DocClassifierClass(class_name="Invoice"))
    contract: DocClassifierClass = Field(default=DocClassifierClass(class_name="Contract"))
    tax_form: DocClassifierClass = Field(default=DocClassifierClass(class_name="TaxForm"))
    bill_of_lading: DocClassifierClass = Field(default=DocClassifierClass(class_name="BillOfLading"))


@flow(
    name ="custom_flow_docclassifier_example",
    display_name="custom_flow_docclassifier_example",
    description="Classifies documents into custom classes.",
    input_schema=DocumentProcessingCommonInput
)
def build_docclassifier_flow(aflow: Flow = None) -> Flow:
    # aflow.docclassifier returns a DocClassifierNode object.
    # The output schema of a DocClassifierNode is a DocumentClassifierResponse object.

    doc_classifier_node = aflow.docclassifier(
        name="document_classifier_node",
        display_name="document_classifier_node",
        description="Classifies documents into one custom class.",
        llm="watsonx/meta-llama/llama-4-maverick-17b-128e-instruct-fp8",
        classes=CustomClasses(),
    )

    aflow.sequence(START, doc_classifier_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 (
    DocClassifierClass, DocumentProcessingCommonInput, LanguageCode
)


class CustomClasses(BaseModel):
    """
    Configuration schema for document classification classes.
    
    Defines the document types/classes that the classifier can identify.
    Each class is configured with a DocClassifierClass that specifies the
    class name used for categorizing input documents.
    """
    invoice: DocClassifierClass = Field(default=DocClassifierClass(class_name="Invoice"))
    contract: DocClassifierClass = Field(default=DocClassifierClass(class_name="Contract"))
    tax_form: DocClassifierClass = Field(default=DocClassifierClass(class_name="TaxForm"))
    bill_of_lading: DocClassifierClass = Field(default=DocClassifierClass(class_name="BillOfLading"))


@flow(
    name="document_classifier_with_language",
    display_name="Document Classifier with Language",
    description=(
        "Classifies documents into custom classes using a specified OCR language. "
        "Setting the language ensures the correct OCR engine is used for scanned PDFs "
        "and images, improving classification accuracy for non-Latin script documents."
    ),
    input_schema=DocumentProcessingCommonInput
)
def build_docclassifier_flow_with_language(aflow: Flow = None) -> Flow:
    """
    Build a document classifier flow with language-aware OCR support.
    
    This example demonstrates how to use the language parameter to select the
    correct OCR engine before classification.
    
    Use the LanguageCode enum to specify the ISO-639 language code that matches
    the document's language.
    """
    doc_classifier_node = aflow.docclassifier(
        name="document_classifier_language_node",
        display_name="Classify Document (French)",
        description=(
            "Classifies French-language scanned documents or images into custom classes. "
            "Uses the French OCR engine to correctly recognise Latin-script characters."
        ),
        llm="watsonx/meta-llama/llama-4-maverick-17b-128e-instruct-fp8",
        classes=CustomClasses(),
        language=LanguageCode.fr,
    )
    
    aflow.sequence(START, doc_classifier_node, END)
    return aflow

Release Notes

Get Started

Build

Deploy

Analyze

Developer experience

Legal notices

Pre-requisites

Limitations

Configuring document extractor node in agentic workflows

Using the language parameter

​Pre-requisites

​Limitations

​Configuring document extractor node in agentic workflows

​Using the language parameter

Pre-requisites

Limitations

Configuring document extractor node in agentic workflows

Using the language parameter