class BedrockTextGateway implements EmbeddingGateway, StepTextGateway

Traits

Constants

protected STRUCTURED_OUTPUT_TOOL

protected MODELS_REJECTING_FORCED_TOOL_CHOICE

Methods

createClient(string $baseUrl, array $headers = [], array $configuredHeaders = [], int|null $timeout = 60, bool $throw = true)

Create an HTTP client with the provider's request options.

string
httpConnection(Provider $provider)

Select a boot-registered connection without retaining dynamic provider names.

BedrockRuntimeClient
createBedrockClient(Provider $provider, int|null $timeout = null)

Create a new Bedrock client instance.

string
bedrockRegion(array $config)

Resolve the configured region, falling back to the default.

array
resolveAuthConfig(array $credentials, array $config, int|null $timeout = null)

Resolve the provider authentication configuration.

array
resolveSourceAuthConfig(array $credentials, array $config)

Resolve the auth configuration for static, or automatically discovered, credentials.

assumeRoleCredentialProvider(array $credentials, array $config, int|null $timeout = null)

Create a loader that assumes the configured role.

StsClient
createStsClient(array $credentials, array $config, int|null $timeout = null)

Create the STS client used to assume the configured role.

array
assumeRoleParameters(array $assumeRole)

Build the parameters for the STS assume role request.

array
decodeStructuredOutput(string|null $text)

Decode a structured output payload, tolerating markdown code fences.

mixed
withErrorHandling(string $providerName, Closure $callback)

Execute a callback with failoverable error handling.

int|null
retryAfterSeconds(Throwable $exception)

Get the short Retry-After delay of a rate limited or overloaded response, if it has one.

bool
isInsufficientCredits(RequestException $exception)

Determine if the response is a 402, or a 429 insufficient credits or quota error rather than a rate limit.

array
overloadedStatusCodes()

Get the status codes that indicate a provider is transiently unavailable and the request should fail over.

array
insufficientCreditPatterns()

Get the patterns used to detect insufficient credits or quota errors.

array
insufficientCreditCodes()

Get the error codes or types that indicate insufficient credits or quota on a 429 response.

static string
joinReasoning(iterable $blocks)

Join reasoning blocks, separating each block with a blank line.

array
mapAttachments(Collection $attachments)

Map the given Hypervel attachments to Bedrock content blocks.

array
buildDocumentBlock(Document $document)

Build a Bedrock document content block.

array
buildImageBlock(Image $image, string $bytes)

Build a Bedrock image content block.

string|null
getDocumentFormat(Document $document)

Map a Document's MIME type to a Bedrock document format.

string
getDocumentName(Document $document)

Build a Bedrock-compliant document name.

string
getImageFormat(Image $image)

Map an Image's MIME type to a Bedrock image format.

array
parseCohereEmbeddings(mixed $embeddings)

Normalize the embeddings of a Cohere response into a list of vectors.

__construct()

Create a Bedrock text gateway.

generateTextStep(TextProvider $provider, string $model, string|null $instructions, array $messages, array $tools, array|null $schema, TextGenerationOptions|null $options, int|null $timeout, StepContext $stepContext)

Generate text for a single Converse step.

generateStreamStep(string $invocationId, TextProvider $provider, string $model, string|null $instructions, array $messages, array $tools, array|null $schema, TextGenerationOptions|null $options, int|null $timeout, StepContext $stepContext)

Stream text for a single Converse step.

array
buildStepBody(TextProvider $provider, string $model, string|null $instructions, array $messages, array $tools, array|null $schema, TextGenerationOptions|null $options, StepContext $stepContext)

Build the Converse request parameters for the current text generation step.

extractUsage(array $data)

Extract usage data from a Converse response.

parseTextResponse(array $result, TextProvider $provider, string $model, bool $structured)

Parse a single Converse response into a step response.

string
extractReasoning(array $content)

Extract the reasoning text from Converse content blocks.

processTextStream(string $invocationId, TextProvider $provider, string $model, iterable $stream, bool $structured)

Stream a single Converse step, returning the parsed step response.

generateEmbeddings(EmbeddingProvider $provider, string $model, array $inputs, int $dimensions, int $timeout = 30, array $providerOptions = [])

Generate embeddings using AWS Bedrock.

generateCohereEmbeddings(EmbeddingProvider $provider, string $model, BedrockRuntimeClient $client, array $inputs, array $providerOptions = [])

Generate embeddings using a Cohere Bedrock model in a single batched call.

bool
isCohereEmbeddingModel(string $model)

Determine if the given model identifier refers to a Cohere embeddings model.

int
resolveMaxSteps(array $tools, TextGenerationOptions|null $options)

Resolve the maximum number of steps for the given tools and options.

FinishReason
extractFinishReason(array $data)

Extract and map the finish reason from the Bedrock Converse response.

array
buildConverseParameters(string $model, string|null $instructions, array $conversationMessages, array|null $schemaTools, array|null $formattedTools, bool $toolsEmpty, TextGenerationOptions|null $options, bool $isFinalStep, array|null $jsonSchema = null)

Build the request parameters for the Bedrock Converse API.

void
ensureValidPromptCacheOrder(TextGenerationOptions|null $options)

Ensure longer-lived cache points precede shorter-lived cache points.

array
cachePoint(string|null $ttl)

Build a Bedrock cache point for the requested TTL.

array
buildInferenceConfig(TextGenerationOptions|null $options)

Build the inferenceConfig block for Bedrock's Converse API.

array
buildAssistantConversationMessage(string $text, array $toolCalls, array $replayBlocks = [])

Build the assistant conversation message block combining text and tool calls.

array
ensureToolInputIsObject(array $content)

Cast empty toolUse.input arrays to objects so the Converse API doesn't reject them.

array
buildToolResultConversationMessage(array $toolResults)

Build the user conversation message block carrying tool results.

bool
rejectsForcedToolChoice(string $model)

Determine if the model rejects a forced tool choice, so structured output must come from the text answer.

bool
usesManualThinking(array $providerOptions)

Determine whether the request enables manual extended thinking.

string
jsonInstruction(array $schema)

Build the system instruction that asks for the final answer as JSON matching the schema.

array
buildSchemaTools(array $schema, array $tools)

Build the synthetic structured-output tool plus any real tools.

array|null
buildToolConfig(array|null $schemaTools, array|null $formattedTools, bool $toolsEmpty, bool $isFinalStep)

Build Bedrock's toolConfig for the current step.

array
formatMessages(array $messages)

Format Hypervel AI messages for Bedrock's Converse API.

array
formatAssistantMessage(AssistantMessage $message)

Format an AssistantMessage for the Converse API.

array
formatToolResultMessage(ToolResultMessage $message)

Format a ToolResultMessage for the Converse API.

array
formatUserMessage(UserMessage $message)

Format a UserMessage and its attachments for the Converse API.

array
formatGenericMessage(Message $message)

Format a generic Message (system/user/assistant) for the Converse API.

array
formatArrayMessage(array $message)

Format a raw array-shaped message for the Converse API.

array
formatTools(array $tools)

Format tools for the Converse API.

Details

in CreatesClient at line 21
protected PendingRequest createClient(string $baseUrl, array $headers = [], array $configuredHeaders = [], int|null $timeout = 60, bool $throw = true)

Create an HTTP client with the provider's request options.

Parameters

string $baseUrl
array $headers
array $configuredHeaders
int|null $timeout
bool $throw

Return Value

PendingRequest

in CreatesClient at line 43
protected string httpConnection(Provider $provider)

Select a boot-registered connection without retaining dynamic provider names.

Parameters

Provider $provider

Return Value

string

protected BedrockRuntimeClient createBedrockClient(Provider $provider, int|null $timeout = null)

Create a new Bedrock client instance.

Parameters

Provider $provider
int|null $timeout

Return Value

BedrockRuntimeClient

protected string bedrockRegion(array $config)

Resolve the configured region, falling back to the default.

Parameters

array $config

Return Value

string

in CreatesBedrockClient at line 101
protected array resolveAuthConfig(array $credentials, array $config, int|null $timeout = null)

Resolve the provider authentication configuration.

Parameters

array $credentials
array $config
int|null $timeout

Return Value

array

in CreatesBedrockClient at line 124
protected array resolveSourceAuthConfig(array $credentials, array $config)

Resolve the auth configuration for static, or automatically discovered, credentials.

Parameters

array $credentials
array $config

Return Value

array

in CreatesBedrockClient at line 153
protected Closure assumeRoleCredentialProvider(array $credentials, array $config, int|null $timeout = null)

Create a loader that assumes the configured role.

Parameters

array $credentials
array $config
int|null $timeout

Return Value

Closure

in CreatesBedrockClient at line 167
protected StsClient createStsClient(array $credentials, array $config, int|null $timeout = null)

Create the STS client used to assume the configured role.

Parameters

array $credentials
array $config
int|null $timeout

Return Value

StsClient

in CreatesBedrockClient at line 189
protected array assumeRoleParameters(array $assumeRole)

Build the parameters for the STS assume role request.

Parameters

array $assumeRole

Return Value

array

protected array decodeStructuredOutput(string|null $text)

Decode a structured output payload, tolerating markdown code fences.

Parameters

string|null $text

Return Value

array

protected mixed withErrorHandling(string $providerName, Closure $callback)

Execute a callback with failoverable error handling.

Parameters

string $providerName
Closure $callback

Return Value

mixed

protected int|null retryAfterSeconds(Throwable $exception)

Get the short Retry-After delay of a rate limited or overloaded response, if it has one.

Parameters

Throwable $exception

Return Value

int|null

protected bool isInsufficientCredits(RequestException $exception)

Determine if the response is a 402, or a 429 insufficient credits or quota error rather than a rate limit.

Parameters

RequestException $exception

Return Value

bool

protected array overloadedStatusCodes()

Get the status codes that indicate a provider is transiently unavailable and the request should fail over.

Return Value

array

protected array insufficientCreditPatterns()

Get the patterns used to detect insufficient credits or quota errors.

Return Value

array

protected array insufficientCreditCodes()

Get the error codes or types that indicate insufficient credits or quota on a 429 response.

Return Value

array

in JoinsReasoning at line 16
static protected string joinReasoning(iterable $blocks)

Join reasoning blocks, separating each block with a blank line.

Parameters

iterable $blocks

Return Value

string

in MapsAttachments at line 33
protected array mapAttachments(Collection $attachments)

Map the given Hypervel attachments to Bedrock content blocks.

Parameters

Collection $attachments

Return Value

array

in MapsAttachments at line 81
protected array buildDocumentBlock(Document $document)

Build a Bedrock document content block.

Parameters

Document $document

Return Value

array

in MapsAttachments at line 105
protected array buildImageBlock(Image $image, string $bytes)

Build a Bedrock image content block.

Parameters

Image $image
string $bytes

Return Value

array

in MapsAttachments at line 120
protected string|null getDocumentFormat(Document $document)

Map a Document's MIME type to a Bedrock document format.

Parameters

Document $document

Return Value

string|null

in MapsAttachments at line 148
protected string getDocumentName(Document $document)

Build a Bedrock-compliant document name.

Bedrock limits names to 200 characters containing alphanumerics, whitespace, hyphens, parentheses, and square brackets. mapAttachments resolves duplicates.

Parameters

Document $document

Return Value

string

in MapsAttachments at line 164
protected string getImageFormat(Image $image)

Map an Image's MIME type to a Bedrock image format.

Bedrock supports JPEG, PNG, GIF, and WebP images.

Parameters

Image $image

Return Value

string

Exceptions

InvalidArgumentException

in ParsesEmbeddings at line 18
protected array parseCohereEmbeddings(mixed $embeddings)

Normalize the embeddings of a Cohere response into a list of vectors.

Parameters

mixed $embeddings

Return Value

array

Exceptions

AiException

at line 84
__construct()

Create a Bedrock text gateway.

at line 91
StepResponse generateTextStep(TextProvider $provider, string $model, string|null $instructions, array $messages, array $tools, array|null $schema, TextGenerationOptions|null $options, int|null $timeout, StepContext $stepContext)

Generate text for a single Converse step.

Parameters

TextProvider $provider
string $model
string|null $instructions
array $messages
array $tools
array|null $schema
TextGenerationOptions|null $options
int|null $timeout
StepContext $stepContext

Return Value

StepResponse

at line 124
Generator generateStreamStep(string $invocationId, TextProvider $provider, string $model, string|null $instructions, array $messages, array $tools, array|null $schema, TextGenerationOptions|null $options, int|null $timeout, StepContext $stepContext)

Stream text for a single Converse step.

Parameters

string $invocationId
TextProvider $provider
string $model
string|null $instructions
array $messages
array $tools
array|null $schema
TextGenerationOptions|null $options
int|null $timeout
StepContext $stepContext

Return Value

Generator

at line 168
protected array buildStepBody(TextProvider $provider, string $model, string|null $instructions, array $messages, array $tools, array|null $schema, TextGenerationOptions|null $options, StepContext $stepContext)

Build the Converse request parameters for the current text generation step.

Parameters

TextProvider $provider
string $model
string|null $instructions
array $messages
array $tools
array|null $schema
TextGenerationOptions|null $options
StepContext $stepContext

Return Value

array

at line 201
protected TextUsage extractUsage(array $data)

Extract usage data from a Converse response.

Parameters

array $data

Return Value

TextUsage

at line 218
protected StepResponse parseTextResponse(array $result, TextProvider $provider, string $model, bool $structured)

Parse a single Converse response into a step response.

Parameters

array $result
TextProvider $provider
string $model
bool $structured

Return Value

StepResponse

at line 283
protected string extractReasoning(array $content)

Extract the reasoning text from Converse content blocks.

Parameters

array $content

Return Value

string

at line 296
protected Generator processTextStream(string $invocationId, TextProvider $provider, string $model, iterable $stream, bool $structured)

Stream a single Converse step, returning the parsed step response.

Parameters

string $invocationId
TextProvider $provider
string $model
iterable $stream
bool $structured

Return Value

Generator

at line 600
EmbeddingsResponse generateEmbeddings(EmbeddingProvider $provider, string $model, array $inputs, int $dimensions, int $timeout = 30, array $providerOptions = [])

Generate embeddings using AWS Bedrock.

Parameters

EmbeddingProvider $provider
string $model
array $inputs
int $dimensions
int $timeout
array $providerOptions

Return Value

EmbeddingsResponse

at line 660
protected EmbeddingsResponse generateCohereEmbeddings(EmbeddingProvider $provider, string $model, BedrockRuntimeClient $client, array $inputs, array $providerOptions = [])

Generate embeddings using a Cohere Bedrock model in a single batched call.

Parameters

EmbeddingProvider $provider
string $model
BedrockRuntimeClient $client
array $inputs
array $providerOptions

Return Value

EmbeddingsResponse

at line 701
protected bool isCohereEmbeddingModel(string $model)

Determine if the given model identifier refers to a Cohere embeddings model.

Parameters

string $model

Return Value

bool

at line 711
protected int resolveMaxSteps(array $tools, TextGenerationOptions|null $options)

Resolve the maximum number of steps for the given tools and options.

Parameters

array $tools
TextGenerationOptions|null $options

Return Value

int

at line 723
protected FinishReason extractFinishReason(array $data)

Extract and map the finish reason from the Bedrock Converse response.

Parameters

array $data

Return Value

FinishReason

at line 742
protected array buildConverseParameters(string $model, string|null $instructions, array $conversationMessages, array|null $schemaTools, array|null $formattedTools, bool $toolsEmpty, TextGenerationOptions|null $options, bool $isFinalStep, array|null $jsonSchema = null)

Build the request parameters for the Bedrock Converse API.

Parameters

string $model
string|null $instructions
array $conversationMessages
array|null $schemaTools
array|null $formattedTools

pre-formatted real tools (used when no schema is active)

bool $toolsEmpty

whether the caller passed any real tools at all

TextGenerationOptions|null $options
bool $isFinalStep
array|null $jsonSchema

Return Value

array

at line 813
protected void ensureValidPromptCacheOrder(TextGenerationOptions|null $options)

Ensure longer-lived cache points precede shorter-lived cache points.

Parameters

TextGenerationOptions|null $options

Return Value

void

at line 825
protected array cachePoint(string|null $ttl)

Build a Bedrock cache point for the requested TTL.

Parameters

string|null $ttl

Return Value

array

at line 833
protected array buildInferenceConfig(TextGenerationOptions|null $options)

Build the inferenceConfig block for Bedrock's Converse API.

Parameters

TextGenerationOptions|null $options

Return Value

array

at line 852
protected array buildAssistantConversationMessage(string $text, array $toolCalls, array $replayBlocks = [])

Build the assistant conversation message block combining text and tool calls.

Parameters

string $text
array $toolCalls
array $replayBlocks

Return Value

array

at line 865
protected array ensureToolInputIsObject(array $content)

Cast empty toolUse.input arrays to objects so the Converse API doesn't reject them.

Parameters

array $content

Return Value

array

at line 881
protected array buildToolResultConversationMessage(array $toolResults)

Build the user conversation message block carrying tool results.

Parameters

array $toolResults

Return Value

array

at line 899
protected bool rejectsForcedToolChoice(string $model)

Determine if the model rejects a forced tool choice, so structured output must come from the text answer.

Parameters

string $model

Return Value

bool

at line 907
protected bool usesManualThinking(array $providerOptions)

Determine whether the request enables manual extended thinking.

Parameters

array $providerOptions

Return Value

bool

at line 915
protected string jsonInstruction(array $schema)

Build the system instruction that asks for the final answer as JSON matching the schema.

Parameters

array $schema

Return Value

string

at line 924
protected array buildSchemaTools(array $schema, array $tools)

Build the synthetic structured-output tool plus any real tools.

Parameters

array $schema
array $tools

Return Value

array

at line 947
protected array|null buildToolConfig(array|null $schemaTools, array|null $formattedTools, bool $toolsEmpty, bool $isFinalStep)

Build Bedrock's toolConfig for the current step.

When a schema is present, toolChoice is only forced to the synthetic tool on the final step so real tools can be invoked on earlier iterations.

Parameters

array|null $schemaTools
array|null $formattedTools
bool $toolsEmpty
bool $isFinalStep

Return Value

array|null

at line 968
protected array formatMessages(array $messages)

Format Hypervel AI messages for Bedrock's Converse API.

Parameters

array $messages

Return Value

array

at line 982
protected array formatAssistantMessage(AssistantMessage $message)

Format an AssistantMessage for the Converse API.

Parameters

AssistantMessage $message

Return Value

array

at line 1013
protected array formatToolResultMessage(ToolResultMessage $message)

Format a ToolResultMessage for the Converse API.

Parameters

ToolResultMessage $message

Return Value

array

at line 1034
protected array formatUserMessage(UserMessage $message)

Format a UserMessage and its attachments for the Converse API.

Parameters

UserMessage $message

Return Value

array

at line 1048
protected array formatGenericMessage(Message $message)

Format a generic Message (system/user/assistant) for the Converse API.

Parameters

Message $message

Return Value

array

at line 1061
protected array formatArrayMessage(array $message)

Format a raw array-shaped message for the Converse API.

Parameters

array $message

Return Value

array

at line 1074
protected array formatTools(array $tools)

Format tools for the Converse API.

Parameters

array $tools

Return Value

array