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

> Understand page-level vs holistic document classification in AWS IDP Pattern 2. Learn key differences and configuration for enhanced document processing efficiency.

- Repository: [aws-solutions-library-samples/accelerated-intelligent-document-processing-on-aws](https://github.com/aws-solutions-library-samples/accelerated-intelligent-document-processing-on-aws)
- Tags: deep-dive
- Published: 2026-02-25

---

**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`](https://github.com/aws-solutions-library-samples/accelerated-intelligent-document-processing-on-aws/blob/main/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`](https://github.com/aws-solutions-library-samples/accelerated-intelligent-document-processing-on-aws/blob/main/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`](https://github.com/aws-solutions-library-samples/accelerated-intelligent-document-processing-on-aws/blob/main/lib/idp_common_pkg/idp_common/config/system_defaults/base-classification.yaml), the default value is `multimodalPageLevelClassification`:

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

```

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

```yaml
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`](https://github.com/aws-solutions-library-samples/accelerated-intelligent-document-processing-on-aws/blob/main/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):

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

```bash
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`](https://github.com/aws-solutions-library-samples/accelerated-intelligent-document-processing-on-aws/blob/main/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`](https://github.com/aws-solutions-library-samples/accelerated-intelligent-document-processing-on-aws/blob/main/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`](https://github.com/aws-solutions-library-samples/accelerated-intelligent-document-processing-on-aws/blob/main/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`](https://github.com/aws-solutions-library-samples/accelerated-intelligent-document-processing-on-aws/blob/main/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.