Documentation
¶
Overview ¶
Package bedrock wraps AWS Bedrock Runtime.
Bedrock is a model-aggregation gateway — a single endpoint that fronts foundation models from Anthropic, Meta, Mistral, Amazon Titan / Nova, Cohere, AI21, Stability and others. NewChat uses the unified Converse / ConverseStream API which speaks a provider-agnostic message shape; NewEmbeddingModel targets the native InvokeModel contracts for Titan Text Embeddings V1/V2 and Cohere Embed V3/V4. Provider-only embedding controls use EmbeddingRequestOptions under EmbeddingRequestExtensionKey.
Model selection is via the upstream model id (e.g. "anthropic.claude-3-5-sonnet-20241022-v2:0", "amazon.titan-embed-text-v2:0", "meta.llama3-1-70b-instruct-v1:0", "us.anthropic.claude-sonnet-4-20250514-v1:0"). Bedrock supports regional and cross-region inference-profile IDs.
AWS auth is handled by the standard aws-sdk-go-v2 chain (env vars, shared config, IRSA, instance role); no custom APIKey is required.
Stop reasons. Converse reports two truncations — max_tokens for the budget the caller set and model_context_window_exceeded for the model's own window filling first — and both report as a truncation. Guardrail and content filtering report as a policy outcome; malformed model output and malformed tool use have no portable match and keep their native value in the output metadata.
Stream termination. A messageStop event is the only claim that the message is whole. An event stream can end cleanly mid-message without the SDK reporting an error, so a stream that stops without one fails with [chat.ErrInvalidResponse] rather than passing off a partial answer.
Token usage. With prompt caching, Converse reports inputTokens as the non-cached part only and the cache counts beside it, so the store adds the three into the total Core reports and keeps the cache counts as breakdowns of it. Copying inputTokens through would understate the input by the whole cached prefix and put a breakdown above its own total.
Reasoning. Converse has no reasoning field: reasoning rides in additionalModelRequestFields, and its shape belongs to the model generation rather than to Converse — Claude 3.7 takes reasoning_config with a budget_tokens count, while newer models reject that form and take thinking with an output_config effort. A portable reasoning effort is therefore refused rather than translated into an invented token budget or a guessed generation; state the model's own parameters through the request extension's AdditionalModelRequestFields.
Stream shape. ConverseStream sends its metadata event — the one carrying usage — after messageStop, so the finish reason is held and stamped onto whichever delta turns out to be last. Reporting the end at messageStop put the usage delta after a finished stream, and a [chat.ResponseAccumulator] rejects that: a consumer that already saw the answer end cannot fold anything more into it. Exactly one delta reports the end, and it is the one a consumer sees last.
See https://docs.aws.amazon.com/bedrock/ for the full reference.
Index ¶
- Constants
- func NewReasoningPart(text string, signature []byte) (corechat.Part, error)
- func NewRedactedReasoningPart(content []byte) (corechat.Part, error)
- type Chat
- type ChatConfig
- type ChatRequestOptions
- type Credentials
- type EmbeddingModel
- type EmbeddingModelConfig
- type EmbeddingRequestOptions
- type GuardrailOptions
- type ReasoningBlockKind
- type StreamGuardrailOptions
Constants ¶
const ( // ChatRequestExtensionKey stores [ChatRequestOptions] in a Core request. ChatRequestExtensionKey = "bedrock/request" // ChatResponseExtensionKey preserves the complete official Converse output. ChatResponseExtensionKey = "bedrock/response" )
const ( // EmbeddingRequestExtensionKey stores [EmbeddingRequestOptions] in Core // embedding options. EmbeddingRequestExtensionKey = "bedrock/embedding_request" // EmbeddingResponseExtensionKey preserves the provider's JSON response body. // Titan batching stores one body per input; Cohere stores its single batch body. EmbeddingResponseExtensionKey = "bedrock/embedding_response" )
const (
Provider = "AmazonBedrock"
)
Provider is the stable backend name for host-side attribution.
Variables ¶
This section is empty.
Functions ¶
func NewReasoningPart ¶
NewReasoningPart preserves the signature Bedrock requires when reasoning is replayed in a later request.
Types ¶
type Chat ¶
type Chat struct {
// contains filtered or unexported fields
}
Chat implements Core chat through Bedrock's provider-neutral Converse API.
func NewChat ¶
func NewChat(ctx context.Context, config ChatConfig) (*Chat, error)
NewChat rejects an invalid provider binding before the first chat call.
type ChatConfig ¶
type ChatConfig struct {
DefaultOptions corechat.Options
Region string
BaseURL string
HTTPClient *http.Client
Credentials *Credentials
}
ChatConfig binds provider access and defaults shared by every chat call.
func (ChatConfig) Validate ¶
func (c ChatConfig) Validate() error
type ChatRequestOptions ¶
type ChatRequestOptions struct {
AdditionalModelRequestFields map[string]any `json:"additional_model_request_fields,omitempty"`
AdditionalModelResponseFieldPaths []string `json:"additional_model_response_field_paths,omitempty"`
Guardrail *GuardrailOptions `json:"guardrail,omitempty"`
StreamGuardrail *StreamGuardrailOptions `json:"stream_guardrail,omitempty"`
PerformanceLatency string `json:"performance_latency,omitempty"`
RequestMetadata map[string]string `json:"request_metadata,omitempty"`
ServiceTier string `json:"service_tier,omitempty"`
}
ChatRequestOptions carries serializable Bedrock Converse fields that have no provider-neutral Core equivalent. Common model, message, tool, and sampling fields are always derived from the Core request and take precedence.
type Credentials ¶
Credentials bypasses the ambient AWS credential chain when a caller needs an explicit identity, such as a tenant-scoped integration.
type EmbeddingModel ¶
type EmbeddingModel struct {
// contains filtered or unexported fields
}
EmbeddingModel implements the native InvokeModel wire contracts for Amazon Titan Text Embeddings V1/V2 and Cohere Embed V3/V4. Titan accepts one input per invocation; Cohere accepts up to 96 texts in one batch.
func NewEmbeddingModel ¶
func NewEmbeddingModel(ctx context.Context, config EmbeddingModelConfig) (*EmbeddingModel, error)
NewEmbeddingModel rejects an invalid provider binding before the first embedding call.
type EmbeddingModelConfig ¶
type EmbeddingModelConfig struct {
DefaultOptions embedding.Options
Region string
BaseURL string
HTTPClient *http.Client
Credentials *Credentials
}
EmbeddingModelConfig binds provider access and defaults shared by every embedding call.
func (EmbeddingModelConfig) Validate ¶
func (e EmbeddingModelConfig) Validate() error
type EmbeddingRequestOptions ¶
type EmbeddingRequestOptions struct {
// InputType is required by Cohere Embed and distinguishes retrieval queries,
// retrieval documents, classification inputs, and clustering inputs.
InputType string `json:"input_type,omitempty"`
// Truncate controls Cohere's over-length behavior.
Truncate string `json:"truncate,omitempty"`
// Normalize controls Amazon Titan Text Embeddings V2 output normalization.
Normalize *bool `json:"normalize,omitempty"`
}
EmbeddingRequestOptions carries official family-specific InvokeModel fields with no provider-neutral Core equivalent. Unsupported fields are rejected for the selected model family rather than silently ignored.
type GuardrailOptions ¶
type GuardrailOptions struct {
Identifier string `json:"identifier"`
Version string `json:"version"`
Trace string `json:"trace,omitempty"`
}
GuardrailOptions configures a Bedrock guardrail without exposing AWS SDK wire types.
type ReasoningBlockKind ¶
type ReasoningBlockKind string
ReasoningBlockKind identifies a Bedrock Converse reasoning-content variant.
const ( ReasoningBlockText ReasoningBlockKind = chatReasoningText ReasoningBlockRedacted ReasoningBlockKind = chatReasoningRedacted )
The vocabulary is closed because these kinds classify reasoning blocks the service returns. A redacted block carries no readable text but must still round trip intact, so it cannot be folded into the text kind.
func ReasoningBlockKindOf ¶
func ReasoningBlockKindOf(part corechat.Part) (ReasoningBlockKind, bool, error)
ReasoningBlockKindOf reports whether part contains Bedrock-issued reasoning replay state.
type StreamGuardrailOptions ¶
type StreamGuardrailOptions struct {
Identifier string `json:"identifier"`
Version string `json:"version"`
Trace string `json:"trace,omitempty"`
ProcessingMode string `json:"processing_mode,omitempty"`
}
StreamGuardrailOptions adds the streaming processing mode to a guardrail.
Source Files