[FEATURE] Add support of s3Location to image and document content types

[Unshure]

Problem Statement

Update the document, image, and video content types to support S3 location based on Bedrock support:

• https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_VideoSource.html
• https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ImageBlock.html
• https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_DocumentBlock.html

Use Case

Adding sources in S3 for content, enabling users to reference media files stored in Amazon S3 buckets instead of passing raw bytes.

---

Implementation Requirements

Based on AWS Bedrock API documentation and clarification discussion:

1. New Type Definition

Add S3Location TypedDict to src/strands/types/media.py:

class S3Location(TypedDict, total=False):
    """A storage location in an Amazon S3 bucket.
    
    Attributes:
        uri: An object URI starting with `s3://`.
        bucketOwner: If the bucket belongs to another AWS account, specify that account's ID.
    """
    uri: str  # Required - pattern: s3://[bucket]/[key]
    bucketOwner: str  # Optional - 12-digit AWS account ID

2. Update Source Types

Update source types in src/strands/types/media.py to support S3 locations (Union pattern - only one field should be specified):

ImageSource:

class ImageSource(TypedDict, total=False):
    bytes: bytes
    s3Location: S3Location  # NEW

DocumentSource:

class DocumentSource(TypedDict, total=False):
    bytes: bytes
    s3Location: S3Location  # NEW

VideoSource:

class VideoSource(TypedDict, total=False):
    bytes: bytes
    s3Location: S3Location  # NEW

3. Bedrock Model Provider Updates

Update src/strands/models/bedrock.py _format_request_message_content method to handle s3Location in image, document, and video sources:

• When s3Location is present in source, include it in the formatted output
• Maintain backward compatibility with existing bytes handling

4. Other Model Providers - Warning & Filter

For model providers that don't support S3 sources (Anthropic, OpenAI, Gemini, LiteLLM, Ollama, Mistral, LlamaAPI, LlamaCpp, SageMaker, Writer):

• Add detection for s3Location in image/document/video sources
• Log a warning when S3 source is detected (e.g., "S3 sources are not supported by {provider}, skipping content block")
• Filter out/skip content blocks that use S3 sources
• Continue processing remaining content blocks

5. Testing Requirements

Unit Tests (tests/strands/types/):

• Test S3Location type definition
• Test updated ImageSource, DocumentSource, VideoSource with s3Location

Unit Tests (tests/strands/models/):

• Test Bedrock model correctly formats S3 location sources
• Test Bedrock model maintains backward compatibility with bytes sources
• Test other model providers log warning and filter S3 content blocks

Files to Modify

File	Changes
src/strands/types/media.py	Add S3Location, update ImageSource, DocumentSource, VideoSource
src/strands/models/bedrock.py	Handle s3Location in _format_request_message_content
src/strands/models/anthropic.py	Add S3 detection, warning, and filtering
src/strands/models/openai.py	Add S3 detection, warning, and filtering
src/strands/models/gemini.py	Add S3 detection, warning, and filtering
src/strands/models/litellm.py	Add S3 detection, warning, and filtering
src/strands/models/ollama.py	Add S3 detection, warning, and filtering
src/strands/models/mistral.py	Add S3 detection, warning, and filtering
src/strands/models/llamaapi.py	Add S3 detection, warning, and filtering
src/strands/models/llamacpp.py	Add S3 detection, warning, and filtering
src/strands/models/sagemaker.py	Add S3 detection, warning, and filtering
src/strands/models/writer.py	Add S3 detection, warning, and filtering
tests/strands/types/test_media.py	New file - tests for S3Location and updated source types
tests/strands/models/test_bedrock.py	Add tests for S3 source handling
Various provider test files	Add tests for S3 warning/filter behavior

Acceptance Criteria

• S3Location type is defined with uri (required) and bucketOwner (optional) fields
• ImageSource, DocumentSource, VideoSource support optional s3Location field
• Bedrock model provider correctly formats requests with S3 location sources
• Bedrock model provider maintains backward compatibility with bytes sources
• Non-Bedrock model providers log warnings when S3 sources are detected
• Non-Bedrock model providers filter out S3 source content blocks gracefully
• Unit tests cover all new functionality
• All existing tests continue to pass
• Code follows repository style guidelines (type annotations, Google docstrings, structured logging)

[Unshure]

/strands

[github-actions]

Repository Analysis & Clarifying Questions

I've analyzed the repository structure and AWS Bedrock API documentation. Here's my understanding and a few questions to ensure proper implementation:

Repository Analysis

Current Implementation (src/strands/types/media.py):

• DocumentSource, ImageSource, and VideoSource currently only support bytes field
• These types are used throughout the SDK (A2A executor, MCP client, model providers)
• The Bedrock model provider (src/strands/models/bedrock.py) has explicit handling for these content types

AWS API Changes Required (from linked docs):

1. S3Location - New type with:

   • uri (required): S3 URI starting with s3://
   • bucketOwner (optional): Account ID for cross-account bucket access

2. ImageSource/VideoSource - Add optional s3Location field (Union with bytes)

3. DocumentSource - Add optional s3Location field (Union with bytes)

   • Note: AWS API also supports text and content fields for DocumentSource

Clarifying Questions

1. DocumentSource Additional Fields: The AWS DocumentSource API supports additional fields beyond s3Location:

   • text: Text content of the document
   • content: Array of DocumentContentBlock objects (structured content)

   Should we add these fields as well, or focus only on s3Location for this feature?

2. Model Provider Support: Currently, S3 location support appears to be Bedrock-specific. Should we:

   • Only update the Bedrock model provider to handle S3 sources?
   • Or should we add placeholder/error handling in other providers (Anthropic, OpenAI, etc.) when S3 sources are used?

3. Validation: Should we add any validation for S3 URIs (pattern matching for s3://bucket/key format), or rely on the Bedrock API to validate?

Implementation Scope Assessment

This task appears appropriately scoped for a single PR:

• Update types in src/strands/types/media.py
• Update Bedrock model provider to handle S3 sources
• Add unit tests for new types
• No workflow changes required

Please respond when you have a chance, and I'll update the issue description with the finalized requirements.

[Unshure]

/strands

1. Just s3 location for now
2. Add a warning to other model providers when they detect an s3 content type, and then filter it out
3. Bedrock api

[github-actions]

Task Refinement Complete

I've updated the issue description with comprehensive implementation requirements based on our discussion.

Summary of Clarifications Applied

1. DocumentSource fields: Only adding s3Location (deferring text and content fields)
2. Model provider support:
   • Bedrock: Full S3 location support
   • Other providers: Warning + filter when S3 sources detected
3. Validation: Relying on Bedrock API for S3 URI validation

Implementation Scope

• Type updates: Add S3Location type, update ImageSource, DocumentSource, VideoSource
• Bedrock model: Handle S3 sources in content formatting
• Other providers: Add detection, warning logging, and graceful filtering (10 providers)
• Testing: Unit tests for types and all affected model providers

Ready for Implementation

This issue is now ready for implementation. The scope is appropriate for a single PR and can be completed by a single developer.

Recommendations

• Consider creating a helper function for S3 source detection/filtering that can be shared across non-Bedrock providers to reduce code duplication
• Use the structured logging format specified in AGENTS.md for warning messages

[Unshure]

/strands implement