Bedrock support for remote s3 document

[dumbbellcode]

Adds support for passing S3-hosted documents to Bedrock's Converse API by reference, so users don't have to download and re-upload large files inline.

Fixes #475

Usage

use Laravel\Ai\Files\S3Document;

$document = new S3Document('s3://my-bucket/reports/q1.pdf', mimeType: 'application/pdf');

// Cross-account access
$document = new S3Document(
    url: 's3://shared-bucket/file.pdf',
    bucketOwner: '123456789012',
    mimeType: 'application/pdf',
);

ai('bedrock')->text('summarize this', [$document]);

Approach

• Introduces a dedicated S3Document type for S3 location references (it does not have inline content — only a URL and an optional bucket owner).
• The Bedrock text gateway dispatches on document type to build the correct Converse source block: s3Location for S3Document, bytes for inline document types. Unsupported document types raise a clear error.
• This mirrors the attachment-mapping pattern already used by the Anthropic and Gemini gateways, keeping provider-specific JSON shapes inside the gateway.
• Refs: https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-bedrock-runtime-2023-09-30.html#converse

Note on contract change

Document::content(): string is documented as "raw bytes of the file" and every existing subclass honors that. S3Document::content() throws instead, since the bytes never live on the client. Any caller that handles arbitrary Document instances and calls ->content() will now need to either type-check first or handle the exception — relevant only for code consuming Document polymorphically (e.g. custom gateways or middleware), not for normal ai('bedrock')->text(...) usage.

[pushpak1300]

@dumbbellcode I change approach a little to extend this as a separate class for future interpretability.

[dumbbellcode]

@dumbbellcode I change approach a little to extend this as a separate class for future interpretability.

Thanks @pushpak1300, since we are going with a new class, i have added a small commit to also support bucketOwner converse parameter

[taylorotwell]

AI assisted review:

1. P2: Document::fromUrl('s3://...') produces Bedrock payloads with the wrong document format

   src/Files/Document.php:57-60 returns an S3Document without MIME metadata, but Bedrock formatting still derives document.format only from mimeType() and defaults missing MIME to text/plain / txt in src/Gateway/Bedrock/Concerns/MapsAttachments.php:88-101.

   That means this newly supported path:
   ai('bedrock')->text('summarize', [
   Document::fromUrl('s3://my-bucket/path/report.pdf'),
   ]);

   emits format => 'txt' for a PDF S3 object. Bedrock’s format is the document extension/type, so this can cause failed requests or incorrect parsing. Either avoid auto-promoting s3:// URLs through fromUrl, add a MIME/format inference path for S3Document names, or make the helper require/accept MIME metadata.

[dumbbellcode]

I have made the following changes:

1. I have removed the default txt fallback because remote parameter is optional for document block in bedrock: link.

2. I have removed the auto promoting of s3:// because fromUrl is specifically for remote documents which can be accessed via HTTPs, also the S3Document class isn't supported in non-bedrock providers

[dumbbellcode]

thinking of renaming S3Document to BedrockS3Document as most of it's content is specific to bedrock, what do you think @pushpak1300 ?