bedrock

README

bedrock

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. See https://docs.aws.amazon.com/bedrock/ for the full reference.

Install

go get github.com/Tangerg/scope/models/bedrock

Constructors

Every constructor validates its config and returns a value implementing the Model contracts in core:

• NewChat
• NewEmbeddingModel
• NewReasoningPart
• NewRedactedReasoningPart

Testing

This module integrates a third-party service, so its tests cover what runs without live credentials: config validation, request and response mapping, and error classification. The shared conformance contract is core/modeltest for behavior and dev/providerconformance for construction and API consistency — this module runs it rather than copying it.

An integration probe skips unless its credential environment variable is set, so go test ./... is always runnable offline.

Boundaries

This is an independent leaf module: it carries only its own SDK dependency and never imports a sibling provider. The shared contract every module in this family obeys is in ../ARCHITECTURE.md.

See ARCHITECTURE.md for what this module owns.

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.

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
  • func NewChat(ctx context.Context, config ChatConfig) (*Chat, error)
  • func (c *Chat) Call(ctx context.Context, req *corechat.Request) (*corechat.Response, error)
  • func (c *Chat) Stream(ctx context.Context, req *corechat.Request) iter.Seq2[*corechat.Response, error]
• type ChatConfig
  • func (c ChatConfig) Validate() error
• type ChatRequestOptions
• type Credentials
• type EmbeddingModel
  • func NewEmbeddingModel(ctx context.Context, config EmbeddingModelConfig) (*EmbeddingModel, error)
  • func (e *EmbeddingModel) Call(ctx context.Context, req *embedding.Request) (*embedding.Response, error)
• type EmbeddingModelConfig
  • func (e EmbeddingModelConfig) Validate() error
• type EmbeddingRequestOptions
• type GuardrailOptions
• type ReasoningBlockKind
  • func ReasoningBlockKindOf(part corechat.Part) (ReasoningBlockKind, bool, error)
• 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"
)

Functions

func NewReasoningPart

func NewReasoningPart(text string, signature []byte) (corechat.Part, error)

func NewRedactedReasoningPart

func NewRedactedReasoningPart(content []byte) (corechat.Part, error)

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)

func (*Chat) Call

func (c *Chat) Call(ctx context.Context, req *corechat.Request) (*corechat.Response, error)

func (*Chat) Stream

func (c *Chat) Stream(ctx context.Context, req *corechat.Request) iter.Seq2[*corechat.Response, error]

Stream performs one Bedrock ConverseStream request and yields validated provider deltas with cumulative usage snapshots.

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      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

type Credentials struct {
	AccessKeyID     string
	SecretAccessKey string
	SessionToken    string
}

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)

func (*EmbeddingModel) Call

func (e *EmbeddingModel) Call(ctx context.Context, req *embedding.Request) (*embedding.Response, 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,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
)

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.