Issue Station
Sign In
Tools hereToolbox

litellm - ✅(Solved) Fix [Feature]: add citations and context support for document content blocks in Converse API [1 pull requests, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
BerriAI/litellm#26937•Fetched 2026-05-01 05:34:21
View on GitHub
Comments
0
Participants
1
Timeline
4
Reactions
0
Author
elvis-caielvis-cai
Participants
elvis-caielvis-cai
Timeline (top)
cross-referenced ×1labeled ×1referenced ×1renamed ×1

The Bedrock Converse API supports citations and context fields on DocumentBlock (used when passing PDFs/documents to Claude models via Bedrock). These fields are not currently forwarded when converting Anthropic-style document content blocks to Bedrock format.

Root Cause

The Bedrock Converse API supports citations and context fields on DocumentBlock (used when passing PDFs/documents to Claude models via Bedrock). These fields are not currently forwarded when converting Anthropic-style document content blocks to Bedrock format.

Fix Action

Fixed

PR fix notes

PR #26948: fix(bedrock): handle document content blocks with citations and context in Converse API

Description (problem / solution / changelog)

Relevant issues

Fixes #26937

Pre-Submission checklist

  • I have Added testing in the tests/test_litellm/ directory, Adding at least 1 test is a hard requirement - see details
  • My PR passes all unit tests on make test-unit
  • My PR's scope is as isolated as possible, it only solves 1 specific problem

Type

🐛 Bug Fix / ✨ Enhancement

Changes

document content blocks (PDF, CSV, etc. via Anthropic's API format) were silently dropped during Bedrock Converse API message conversion. Additionally, the Bedrock Converse API supports citations and context fields on DocumentBlock which were never forwarded.

Root cause

  1. The for element in message_block["content"] loop in both the sync and async Bedrock Converse message paths had no elif element["type"] == "document" branch — blocks were skipped silently.
  2. _convert_to_bedrock_tool_call_result() only handled text and image_url, dropping document blocks in tool results.
  3. DocumentBlock in litellm/types/llms/bedrock.py was missing citations and context fields.

Fix

  • Added _process_document_message() static method on BedrockConverseMessagesProcessor:
    • Validates source.type == "base64"
    • Maps media_type → Bedrock format string (pdf, csv, docx, xlsx, html, txt, md, etc.)
    • Generates a deterministic document name using SHA-256 content hashing
    • Forwards citations: {enabled: true} → CitationsConfig(enabled=True) (Bedrock Converse API docs)
    • Forwards context field
  • Added elif element["type"] == "document" branch in the async user-message path
  • Added elif element["type"] == "document" branch in the sync user-message path (_bedrock_converse_messages_pt)
  • Added elif content["type"] == "document" branch in _convert_to_bedrock_tool_call_result() (tool results)
  • Added CitationsConfig TypedDict and extended DocumentBlock with optional citations and context fields

Before / After

messages = [{"role": "user", "content": [
    {"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": "dGVzdA=="},
     "citations": {"enabled": True}, "context": "Q4 report"},
    {"type": "text", "text": "What is the title?"},
]}]

result = _bedrock_converse_messages_pt(messages, "anthropic.claude-sonnet-4-6", "bedrock")

# Before: [{'text': 'What is the title?'}]   — document dropped, citations/context lost
# After:  [{'document': {'source': {'bytes': 'dGVzdA=='}, 'format': 'pdf', 'name': '...',
#            'citations': {'enabled': True}, 'context': 'Q4 report'}},
#           {'text': 'What is the title?'}]

Tests added (tests/test_litellm/litellm_core_utils/prompt_templates/test_bedrock_document_blocks.py)

TestWhat it verifies
test_document_block_basicDocument block produces correct format, source.bytes, and name
test_document_block_not_dropped_with_textMixed document + text preserves both blocks
test_document_block_citations_forwardedcitations.enabled=True forwarded to CitationsConfig
test_document_block_citations_not_set_when_disabledcitations absent when disabled
test_document_block_context_forwardedcontext field forwarded to DocumentBlock
test_document_block_deterministic_nameSame data always produces the same name
test_document_format_mapping7 MIME types map to correct Bedrock format strings
test_document_in_tool_resultDocument in tool result produces correct content block
test_non_base64_source_raisesNon-base64 source raises a clear error

🤖 Generated with Claude Code

Changed files

  • litellm/litellm_core_utils/prompt_templates/factory.py (modified, +70/-0)
  • litellm/types/llms/bedrock.py (modified, +10/-4)
  • tests/test_litellm/litellm_core_utils/prompt_templates/__init__.py (added, +0/-0)
  • tests/test_litellm/litellm_core_utils/prompt_templates/test_bedrock_document_blocks.py (added, +164/-0)

Code Example

return BedrockContentBlock(
    document=BedrockDocumentBlock(
        source=BedrockSourceBlock(bytes=data),
        format=doc_format,
        name=document_name,
    )
)
# citations and context fields from the input block are never forwarded
RAW_BUFFERClick to expand / collapse

Summary

The Bedrock Converse API supports citations and context fields on DocumentBlock (used when passing PDFs/documents to Claude models via Bedrock). These fields are not currently forwarded when converting Anthropic-style document content blocks to Bedrock format.

Current behaviour

When a document content block includes citations: {enabled: true} or a context field, these are silently dropped during conversion in BedrockConverseMessagesProcessor._process_document_message():

return BedrockContentBlock(
    document=BedrockDocumentBlock(
        source=BedrockSourceBlock(bytes=data),
        format=doc_format,
        name=document_name,
    )
)
# citations and context fields from the input block are never forwarded

Expected behaviour

  • If the Anthropic-style block has citations: {enabled: true}, it should be forwarded to Bedrock's DocumentBlock as CitationsConfig(enabled=True)
  • If the block has a context field, it should be forwarded to DocumentBlock.context

Also affected

DocumentBlock in litellm/types/llms/bedrock.py is missing citations and context fields — it needs total=False and those two optional fields added.

Related

extent analysis

TL;DR

Update the BedrockConverseMessagesProcessor._process_document_message() method to forward citations and context fields from Anthropic-style document content blocks to Bedrock's DocumentBlock.

Guidance

  • Modify the BedrockConverseMessagesProcessor._process_document_message() method to include citations and context fields in the BedrockDocumentBlock constructor.
  • Update the DocumentBlock model in litellm/types/llms/bedrock.py to include citations and context fields with total=False.
  • Verify that the updated code correctly forwards citations and context fields by testing the conversion of Anthropic-style document content blocks to Bedrock format.
  • Check the Bedrock Converse API documentation to ensure that the updated fields are correctly formatted and supported.

Example

return BedrockContentBlock(
    document=BedrockDocumentBlock(
        source=BedrockSourceBlock(bytes=data),
        format=doc_format,
        name=document_name,
        citations=CitationsConfig(enabled=input_block.citations.enabled) if input_block.citations else None,
        context=input_block.context
    )
)

Notes

The exact implementation details may vary depending on the specific requirements and constraints of the project. Additionally, the CitationsConfig and BedrockDocumentBlock classes may need to be updated or modified to support the new fields.

Recommendation

Apply workaround: Update the BedrockConverseMessagesProcessor._process_document_message() method and the DocumentBlock model to include the missing fields, as this will allow for correct forwarding of citations and context fields from Anthropic-style document content blocks to Bedrock's DocumentBlock.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#memory management#API rate limit#retriever error#indexing error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

litellm - ✅(Solved) Fix [Feature]: add citations and context support for document content blocks in Converse API [1 pull requests, 1 participants]