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 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.
Without explicit Credentials, AWS auth follows the SDK's ambient credential and Bedrock bearer configuration. Explicit Credentials binds SigV4 to that identity and excludes ambient bearer tokens. The SDK owns regional endpoint resolution. Explicit endpoints, including AWS environment configuration, also bind the HTTP origin. Redirects are refused because they can change the destination or signed operation; the host's client and its resolved transport timeouts remain unchanged.
Call aggregates Stream through Core's ResponseAccumulator; both methods share transport, parsing, cancellation, and terminal errors. Converse requires enabled tool definitions even for tool calls and results in history. It has no native tool choice "none"; disabling or omitting tools with that history returns errors.ErrUnsupported before provider I/O.
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.
Request ownership. AdditionalModelRequestFields accepts provider-only controls. Native aliases for Core facts are rejected even when the Core option is absent or unsupported by this binding. This includes top_k, reasoning_effort, output_config.effort, and reasoningConfig.maxReasoningEffort; an extension cannot bypass Core admission. Static defaults and resolved requests use the same ownership check. Model-only token budgets and thinking modes remain native fields.
Reasoning. Converse has no portable reasoning control, so ReasoningEffort is refused rather than translated into an invented token budget or a guessed model generation. A model's distinct native controls, such as thinking or reasoning_config token budgets, use AdditionalModelRequestFields. Signed and redacted response blocks retain their boundaries when replayed. Unsigned reasoning remains visible in Core output, but is excluded from later Converse requests, as in the documented DeepSeek multi-turn workflow.
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
Constants ¶
const ( // ChatRequestExtensionKey stores [ChatRequestOptions] in a Core request. ChatRequestExtensionKey = Provider + "/request" // ChatMessageStopExtensionKey preserves the terminal provider outcome and native fields. ChatMessageStopExtensionKey = Provider + "/message_stop" // ChatMetadataExtensionKey preserves provider usage, metrics, and trace data. ChatMetadataExtensionKey = Provider + "/metadata" )
const ( // EmbeddingRequestExtensionKey stores [EmbeddingRequestOptions] in Core // embedding options. EmbeddingRequestExtensionKey = Provider + "/embedding_request" // EmbeddingResponseExtensionKey preserves the provider's JSON response body. // Titan batching stores one body per input; Cohere stores its single batch body. EmbeddingResponseExtensionKey = Provider + "/embedding_response" )
const (
Provider = "bedrock"
)
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. Responses support text, reasoning, and client tool calls. Native content without a Core mapping returns errors.ErrUnsupported.
func (*Chat) Stream ¶
func (c *Chat) Stream(ctx context.Context, req *corechat.Request) iter.Seq2[*corechat.ResponseDelta, error]
Stream performs one Bedrock ConverseStream request and yields validated provider deltas with cumulative usage snapshots. Invalid message or content block lifecycles return corechat.ErrInvalidResponse, including clean transport EOF before messageStop. Termination follows all metadata and transport checks. Server tool use returns errors.ErrUnsupported before publishing a tool call.
type ChatConfig ¶
type ChatConfig struct {
DefaultOptions corechat.Options
Region string
BaseURL string
HTTPClient *http.Client
Credentials *Credentials
}
func (ChatConfig) Validate ¶
func (c ChatConfig) Validate() error
type ChatRequestOptions ¶
type ChatRequestOptions struct {
AdditionalModelRequestFields metadata.Map `json:"additional_model_request_fields,omitempty"`
AdditionalModelResponseFieldPaths []string `json:"additional_model_response_field_paths,omitempty"`
Guardrail *GuardrailOptions `json:"guardrail,omitzero"`
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 derived exclusively from the Core request.
func (*ChatRequestOptions) UnmarshalJSON ¶ added in v0.58.0
func (c *ChatRequestOptions) UnmarshalJSON(data []byte) error
type Credentials ¶
Credentials binds SigV4 authentication to an explicit identity, such as a tenant-scoped integration. Ambient credentials and Bedrock bearer tokens cannot replace that identity.
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)
type EmbeddingModelConfig ¶
type EmbeddingModelConfig struct {
DefaultOptions embedding.Options
Region string
BaseURL string
HTTPClient *http.Client
Credentials *Credentials
}
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,omitzero"`
}
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.
func (*EmbeddingRequestOptions) UnmarshalJSON ¶ added in v0.58.0
func (e *EmbeddingRequestOptions) UnmarshalJSON(data []byte) error
type GuardrailOptions ¶
type ReasoningBlockKind ¶
type ReasoningBlockKind string
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. Text without a signature is display-only and is omitted from later requests.
Source Files