How to Implement Few-Shot Examples to Improve Extraction Accuracy for Specific Document Types

You can implement few-shot examples by defining an x-aws-idp-examples array in your config.yaml file, which the system automatically injects into LLM prompts via the {FEW_SHOT_EXAMPLES} placeholder, enabling the model to learn from concrete document examples and ground-truth attributes.

The accelerated-intelligent-document-processing-on-aws solution provides a built-in framework for few-shot learning that eliminates the need for custom prompt engineering. By supplying representative document images and expected extraction outputs in the configuration schema, you can significantly boost classification accuracy and structured data extraction for noisy or domain-specific document types without modifying the underlying Python service code.

Understanding the Few-Shot Example Architecture

The few-shot implementation consists of three core components working together to dynamically assemble prompts. The configuration schema defines the examples using the x-aws-idp-examples extension on class definitions. The few-shot builder utility resolves image paths and formats content blocks. Finally, the extraction and classification services detect the {FEW_SHOT_EXAMPLES} token and substitute it with the built content before invoking Amazon Bedrock.

This architecture resides in the lib/idp_common_pkg/idp_common/ module. The few_shot_example_builder.py file contains the build_few_shot_examples_content() function that iterates over class schemas, while extraction/service.py (around line 283) and classification/service.py (around line 1067) handle the placeholder substitution logic.

Configuring Few-Shot Examples in config.yaml

To implement few-shot learning, you must extend your document class definitions with the x-aws-idp-examples property. Each entry in this array requires three fields: classPrompt (a natural-language description), attributesPrompt (the expected JSON output), and imagePath (local or S3 URI to example images).

The Pattern-2 reference configuration at config_library/pattern-2/rvl-cdip-with-few-shot-examples/config.yaml demonstrates this structure:

x-aws-idp-examples:
  - classPrompt: This is an example of the class 'letter'
    name: Letter1
    attributesPrompt: |-
      expected attributes are:
          "sender_name": "Will E. Clark",
          "date": "10/31/1995",
          ...
    imagePath: >-
      config_library/pattern-2/rvl-cdip-package-sample-with-few-shot-examples/example-images/letter1.jpg

You can specify multiple examples per class. The imagePath field accepts both local filesystem paths and s3:// URIs, and may point to a directory containing multiple images, all of which are automatically included in the prompt.

How the Few-Shot Builder Works

The few_shot_example_builder.py module processes your configuration at runtime. When the service initializes, it calls build_few_shot_examples_content(config), which performs the following steps:

1. Schema iteration – traverses each class definition in the IDPConfig model to locate x-aws-idp-examples entries.
2. Path resolution – invokes _get_image_files_from_path() to validate and resolve image URIs, supporting both local and S3 locations.
3. Content assembly – constructs a list of content items (text blocks and image references) formatted for the Bedrock Converse API.

The builder returns these content items to the calling service, which inserts them at the exact position of the {FEW_SHOT_EXAMPLES} placeholder in the prompt template.

Integration with Extraction and Classification Services

Both the extraction and classification pipelines implement identical placeholder handling logic. In idp_common/extraction/service.py, the service checks for the {FEW_SHOT_EXAMPLES} token when assembling the prompt. If present, it invokes the builder and inserts the resulting content items before the <<CACHEPOINT>> delimiter.

Similarly, idp_common/classification/service.py (line 1067) performs the same substitution for classification tasks. This ensures that whether you are categorizing documents or extracting structured data, the model receives the contextual examples defined in your configuration.

Best Practices for Few-Shot Prompt Caching and Cost Optimization

Placing static content—including class definitions and few-shot examples—before the <<CACHEPOINT>> delimiter enables Amazon Bedrock prompt caching. This optimization caches the lengthy static portion of your prompt, reducing token costs when processing multiple documents against the same configuration.

To maximize efficiency and accuracy:

• Keep examples concise – limit each example to the most salient visual and textual cues to minimize token consumption.
• Use representative images – include diverse examples that cover the variation within your document type.
• Monitor token usage – balance the number of examples against the context window limits; start with 2-3 high-quality examples per class.
• Validate configurations – use the provided test_few_shot_extraction.ipynb and test_few_shot_classification.ipynb notebooks to verify your configuration before production deployment.

Code Examples

Loading Configuration and Running Extraction

The following Python snippet demonstrates how to load a Pattern-2 configuration containing few-shot examples and execute extraction:

from idp_common.config.models import IDPConfig
from idp_common.extraction.service import ExtractionService
from pathlib import Path

# Load the configuration containing x-aws-idp-examples

config_path = Path(
    "config_library/pattern-2/rvl-cdip-with-few-shot-examples/config.yaml"
)
config = IDPConfig.from_yaml_file(config_path)

# Initialize the extraction service

extractor = ExtractionService(config)

# Provide document content and optional image URI

document_text = "..."  # OCR output from your document

document_image = "s3://my-bucket/docs/doc1.jpg"

# Execute extraction - few-shot examples inject automatically

result = extractor.extract(
    document_text=document_text,
    document_image=document_image,
    document_class="letter",  # Must match class in config

)

print(result)  # JSON matching your attributes schema

No additional code is required to handle few-shot examples; the service automatically detects the configuration and performs placeholder substitution.

Adding New Examples to Existing Classes

To extend an existing class with additional examples, append to the x-aws-idp-examples list in your config.yaml:

- classPrompt: "Another letter example showing a handwritten signature"
  name: Letter3
  attributesPrompt: |-
    expected attributes are:
        "sender_name": "Maria L. Gomez",
        "date": "03/12/2021",
        "signature": "Maria L. Gomez"
  imagePath: >-
    config_library/pattern-2/rvl-cdip-package-sample-with-few-shot-examples/example-images/letter3.jpg

After saving the file, redeploy your stack or restart the CLI. The few_shot_example_builder.py utility will automatically load the new examples on the next invocation.

Running Batch Inference via CLI

You can also trigger few-shot extraction using the command-line interface:

idp-cli run-inference \
    --stack-name my-idp-stack \
    --dir ./samples/ \
    --config ./config_library/pattern-2/rvl-cdip-with-few-shot-examples/config.yaml \
    --monitor

The CLI forwards the configuration path to the underlying Python SDK, which executes the same injection logic as the programmatic API.

Summary

• Define examples in config.yaml using the x-aws-idp-examples schema with classPrompt, attributesPrompt, and imagePath fields.
• Automatic injection occurs via the {FEW_SHOT_EXAMPLES} placeholder handled by extraction/service.py and classification/service.py.
• Prompt caching is enabled by placing static few-shot content before the <<CACHEPOINT>> delimiter, significantly reducing Bedrock costs for batch processing.
• No code changes required – simply reference a configuration containing examples to activate few-shot learning for both classification and extraction tasks.

Frequently Asked Questions

How many few-shot examples should I include per document class?

Start with two to three high-quality examples per class that represent the diversity of your document type. According to the source code analysis, each example increases the prompt token count, so monitor your context window usage. The docs/few-shot-examples.md file recommends focusing on quality and diversity over quantity to maximize accuracy gains while minimizing cost.

Can I use S3 URIs for the example images, or do they need to be local files?

The few_shot_example_builder.py utility supports both local filesystem paths and s3:// URIs in the imagePath field. The _get_image_files_from_path() function automatically resolves S3 locations, allowing you to centralize your example images in Amazon S3 storage rather than packaging them with your deployment artifacts.

Do I need to modify the Python service code to enable few-shot examples?

No. The architecture is fully modular. When you use a configuration containing x-aws-idp-examples, the ExtractionService and ClassificationService automatically detect the {FEW_SHOT_EXAMPLES} placeholder and invoke build_few_shot_examples_content() to inject the examples. You only need to edit the YAML configuration to add or modify examples.

What is the purpose of the <<CACHEPOINT>> delimiter in few-shot prompts?

The <<CACHEPOINT>> delimiter separates static content (class definitions and few-shot examples) from dynamic content (the target document being processed). Placing this delimiter after your examples enables Amazon Bedrock prompt caching, which caches the static portion across multiple invocations. This optimization drastically reduces token costs when processing large batches of documents against the same few-shot configuration.

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