Page-Level vs Holistic Document Classification in AWS IDP Pattern 2: Key Differences and Configuration

Pattern 2 of the AWS accelerated intelligent document processing solution supports two distinct classification methods—page-level (multimodalPageLevelClassification) processes individual pages using text and images with boundary detection, while holistic (textbasedHolisticClassification) analyzes the entire document as a single text prompt requiring high-context models like Nova Premier.

The AWS Solutions Library's accelerated intelligent document processing (IDP) repository provides Pattern 2, which combines Amazon Textract with Amazon Bedrock for intelligent document classification. Understanding the differences between page-level and holistic document classification is critical for optimizing accuracy, cost, and performance in production workloads.

Overview of Pattern 2 Classification Methods

Pattern 2 implements two classification pipelines selectable via the classificationMethod configuration parameter in lib/idp_common_pkg/idp_common/config/system_defaults/base-classification.yaml. The ClassificationService class in lib/idp_common_pkg/idp_common/classification/service.py routes requests to the appropriate pipeline based on this setting, handling distinct prompt construction and response parsing requirements for each method at lines 73-78.

Page-Level Classification (multimodalPageLevelClassification)

Individual Page Analysis with Multimodal Input

The page-level method processes each page as an independent classification unit. For every page, the system constructs a prompt containing both {DOCUMENT_TEXT} from Amazon Textract OCR and {DOCUMENT_IMAGE} representing the page raster. This multimodal approach leverages visual layout elements—such as logos, headers, and form structures—that pure text extraction might miss.

Boundary Detection and Document Splitting

A distinctive feature of page-level classification is the boundary flag returned for each page. The model outputs a document_boundary field with values "start" or "continue", enabling BIO-style sequence segmentation. This automatic boundary detection is essential for processing multi-document packets—such as several invoices bundled together—without manual separation. The sectionSplitting configuration (defaulting to llm_determined) then groups pages into logical documents using these boundary signals.

Performance Characteristics

Page-level requests are small, independent, and highly parallelizable. They work with standard-size Bedrock models such as us.amazon.nova-pro-v1:0 and typically incur lower latency and token costs because each request processes limited content. The optional contextPagesCount parameter can include N pages before and after the target page to improve classification accuracy while maintaining reasonable request sizes.

Holistic Classification (textbasedHolisticClassification)

Full-Document Text Analysis

The holistic method takes a fundamentally different approach by sending the entire document packet—concatenated OCR text from all pages—as a single prompt to the LLM. Unlike the page-level approach, holistic classification does not utilize image data; it relies entirely on text-based semantic analysis. The prompt typically instructs the model to "identify distinct document segments and label each segment," requiring the LLM to infer logical boundaries from content flow.

Page-Range Metadata and Segmentation

Rather than per-page boundary flags, holistic classification returns page-range metadata indicating start and end pages for each identified document segment. The model must process the full context window and return structured output mapping document types to specific page ranges (for example, "Pages 1-5: Contract, Pages 6-8: Amendment").

Model Requirements and Constraints

Holistic classification imposes stringent requirements on model capabilities. Because the prompt can exceed the token limits of standard models, this method requires high-context models such as us.amazon.nova-premier-v1:0 with expanded context windows (≥1 million tokens). The single large request per document results in higher latency and significantly greater token consumption compared to the page-level approach.

Key Differences at a Glance

Feature	Page-Level (multimodalPageLevelClassification)	Holistic (textbasedHolisticClassification)
Input Modality	Text + Image per page	Text only (full document)
Processing Unit	Individual pages (parallel)	Entire document packet (single request)
Boundary Detection	Per-page flags (start/continue)	Page-range metadata inferred by LLM
Model Requirements	Standard models (e.g., Nova Pro)	High-context models (e.g., Nova Premier)
Performance	Lower latency, parallelizable, lower cost	Higher latency, sequential, higher token cost
Best Use Case	Multi-document packets, visual layout matters	Cross-page semantics, long narratives

Configuration and Implementation

Selecting the Method in Config Files

The classification method is controlled via the classificationMethod field in Pattern 2 configuration files. As defined in lib/idp_common_pkg/idp_common/config/system_defaults/base-classification.yaml, the default value is multimodalPageLevelClassification:

classification:
  classificationMethod: multimodalPageLevelClassification
  model: us.amazon.nova-pro-v1:0
  contextPagesCount: 1

To enable holistic classification, override this in your custom config:

classification:
  classificationMethod: textbasedHolisticClassification
  model: us.amazon.nova-premier-v1:0  # Required for large context windows

Service Implementation Details

The ClassificationService class in lib/idp_common_pkg/idp_common/classification/service.py implements the routing logic at lines 73-78, where it inspects self.classification_method to determine which prompt builder and response parser to invoke. The classify_pages method (lines 1787-1802) handles the actual execution, constructing either multimodal per-page requests or single holistic text prompts based on the configuration.

CLI Deployment Example

Deploy with page-level classification (default):

idp-cli deploy \
  --stack-name my-idp-stack \
  --pattern pattern-2 \
  --custom-config ./config_library/pattern-2/bank-statement-sample/config.yaml \
  --wait

Switch to holistic by modifying the configuration:

sed -i 's/multimodalPageLevelClassification/textbasedHolisticClassification/' \
  ./config_library/pattern-2/bank-statement-sample/config.yaml

# Update model to Nova Premier for holistic method

sed -i 's/nova-pro-v1:0/nova-premier-v1:0/' \
  ./config_library/pattern-2/bank-statement-sample/config.yaml

When to Use Each Method

Choose Page-Level Classification when processing packets that may contain multiple distinct documents (such as several invoices or mixed correspondence), when visual layout elements like logos or form structures are critical for accurate classification, or when working with large documents that would exceed the context limits of standard LLMs. This method provides superior performance through parallelization and lower token costs, as implemented in the service logic at lib/idp_common_pkg/idp_common/classification/service.py.

Choose Holistic Classification when documents contain narratives or contracts where meaning depends on cross-page context and semantic flow, when you have access to high-context models like Nova Premier, and when the document volume per packet is small enough to fit within the model's context window. This approach excels at understanding document structure from textual coherence rather than visual cues, though it requires the high-context capabilities documented in docs/classification.md lines 65-71.

Summary

• Pattern 2 supports two distinct classification strategies selectable via the classificationMethod configuration parameter in lib/idp_common_pkg/idp_common/config/system_defaults/base-classification.yaml.
• Page-level classification (multimodalPageLevelClassification) processes individual pages using both text and images, returns per-page boundary flags for automatic document splitting, and works with standard Bedrock models like Nova Pro.
• Holistic classification (textbasedHolisticClassification) processes the entire document as a single text prompt, requires high-context models like Nova Premier, and returns page-range metadata for segmentation.
• The ClassificationService in lib/idp_common_pkg/idp_common/classification/service.py routes requests based on the configuration value, implementing the branching logic at lines 73-78 and the classification execution at lines 1787-1802.

Frequently Asked Questions

Can I switch between page-level and holistic classification without redeploying the stack?

No, the classificationMethod is typically set in the configuration file used during deployment. While the ClassificationService supports runtime selection based on configuration, changing the method requires updating your config file and redeploying the stack via the idp-cli or CloudFormation template to ensure the correct model permissions and resources are provisioned.

Why does holistic classification require Nova Premier while page-level works with Nova Pro?

Holistic classification concatenates the OCR text from all pages into a single prompt, which can exceed the token limits of standard models like Nova Pro. Nova Premier provides an expanded context window (≥1 million tokens) capable of processing these large document packets, whereas page-level classification sends smaller, individual requests that fit comfortably within standard model limits.

Does page-level classification support documents where the text continues across page boundaries?

Yes, the page-level method includes an optional contextPagesCount parameter that includes N pages before and after the target page in the prompt. This provides the model with cross-page context while maintaining the benefits of per-page processing and boundary detection, though it increases the request size proportionally.

Which method is better for processing batches of mixed document types like invoices and receipts?

Page-level classification is generally superior for mixed document batches because it returns per-page boundary flags (start/continue) that enable automatic splitting of multi-document packets. The holistic method processes the entire batch as a single text stream and requires the LLM to infer boundaries, which can be less reliable for visually distinct but textually similar documents.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}