Raix::Bedrock

AWS Bedrock provider for the Raix AI framework. This gem allows you to use AWS Bedrock's language models (including Anthropic Claude) with Raix's powerful features like function calling, prompt management, and MCP (Model Context Protocol) support.

Features

Integration: Works as a drop-in replacement for OpenAI in Raix applications
Compatibility: Aims for full support of Raix features including function dispatch and MCP
Message Format Translation: Automatically converts between OpenAI and Bedrock message formats
Tool Support: Full support for function/tool calling with compatible models

Installation

Add this line to your application's Gemfile:

gem "raix"
gem "raix-bedrock"

And then execute:

bundle install

Or install it yourself as:

gem install raix-bedrock

Configuration

Prerequisites

Ensure you have AWS credentials configured. The gem uses the standard AWS SDK authentication chain:

Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
AWS IAM roles
AWS configuration files

Setup Options

There are two ways to configure Raix with Bedrock:

Option 1: Use as the openai_client in your configuration

require "raix"
require "raix/bedrock"

Raix.configure do |config|
  config.openai_client = Raix::Bedrock::Provider.new(
    region: "us-west-2",  # Optional, defaults to AWS_REGION env var
    model: "us.anthropic.claude-sonnet-4-20250514-v1:0"  # Optional default model
  )
end

Option 2: Using the To-Be-Merged provider interface

require "raix"
require "raix/bedrock"

Raix.configure do |config|
  config.register_provider :bedrock, Raix::Bedrock::OpenAIProxy.new(
    region: "us-west-2",
    model: "us.anthropic.claude-sonnet-4-20250514-v1:0"
  )
end

Both options provide identical functionality. The OpenAI proxy ensures compatibility with existing versions of Raix that don't support registering different providers.

Usage

Simple Chat

class ChatAssistant
  include Raix::ChatCompletion

  def initialize
    @model = "us.anthropic.claude-sonnet-4-20250514-v1:0"
    @system = "You are a helpful assistant."
  end

  def ask(question)
    chat_completion(question)
  end
end

assistant = ChatAssistant.new
response = assistant.ask("What is the capital of France?")
puts response # => "The capital of France is Paris."

With Function Calling

class WeatherAssistant
  include Raix::ChatCompletion
  include Raix::FunctionDispatch

  def initialize
    # Use a model that supports tools
    @model = "us.anthropic.claude-3-7-sonnet-20250219-v1:0"
    @system = "You are a weather assistant."
  end

  function(
    :get_weather,
    "Get the current weather for a location",
    location: {
      type: "string",
      description: "The city and state, e.g. San Francisco, CA",
      required: true
    },
    unit: {
      type: "string",
      enum: ["celsius", "fahrenheit"],
      description: "Temperature unit"
    }
  ) do |args|
    # Your weather API implementation here
    location = args[:location]
    unit = args[:unit] || "fahrenheit"

    # Mock response
    {
      location: location,
      temperature: 72,
      unit: unit,
      condition: "sunny"
    }.to_json
  end

  def ask(question)
    chat(question)
  end
end

assistant = WeatherAssistant.new
response = assistant.ask("What's the weather in San Francisco?")

Direct Provider Usage

You shouldn't do this, just use aws-sdk-bedrockruntime, but it's interesting that Claude generated this example, so I'll leave it.

You can also use the provider directly without Raix's abstractions:

provider = Raix::Bedrock::Provider.new

result = provider.chat(parameters: {
  model: "us.anthropic.claude-sonnet-4-20250514-v1:0",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Tell me a joke." }
  ],
  temperature: 0.7,
  max_completion_tokens: 100
})

puts result.dig("choices", 0, "message", "content")

MCP (Model Context Protocol) Integration

The Bedrock provider works seamlessly with Raix's MCP support:

class MCPAssistant
  include Raix::ChatCompletion
  include Raix::MCP

  client = Raix::MCP::StdioClient.new(
    "npx",
    "-y",
    "@modelcontextprotocol/server-github",
    { "GITHUB_PERSONAL_ACCESS_TOKEN" => ENV["GITHUB_TOKEN"] }
  )

  # Register only the specific GitHub tools we want
  mcp(
    client: client,
    only: %i[
      search_repositories
      get_repository
      get_issue
      list_issues
      create_issue
      create_pull_request
      search_code
    ]
  )

  def initialize
    @model = "us.anthropic.claude-3-7-sonnet-20250219-v1:0"
    @system = "You are an assistant with access to MCP tools."
  end
end

# MCP servers provide tools automatically
assistant = MCPAssistant.new
response = assistant.chat("Search for open issues in rails/rails repository")

Model Selection

Recommended Models

For general use: us.anthropic.claude-sonnet-4-20250514-v1:0
- Best overall performance and capabilities
For tool/function usage: us.anthropic.claude-3-7-sonnet-20250219-v1:0
- Full support for function calling and tools
- Slightly older model but with complete tool support
Older without tool calls: anthropic.claude-3-5-sonnet-20241022-v2:0
- Good for less complex tasks
- Doesn't support tool calls `

Model Format

Use inference profile IDs (e.g., us.anthropic.claude-*) for better performance and availability rather than base model IDs.

Limitations

No Streaming Support: The Bedrock Converse API doesn't currently support streaming responses
Token Limits: Maximum tokens are clamped to 8,192 to ensure compatibility
Model-Specific Features: Some models may have specific requirements or limitations

Examples

The examples/ directory contains complete working examples:

simple_chat.rb - Basic chat functionality and tool usage
mcp_integration.rb - MCP server integration with Bedrock
github_mcp/ - Complete GitHub MCP integration example

To run an example:

cd examples
ruby simple_chat.rb

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Running Tests

bundle exec rspec

Console

bin/console

This will give you an interactive prompt with the gem loaded.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/martinemde/raix-bedrock. This project is intended to be a safe, welcoming space for collaboration.

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

License

The gem is available as open source under the terms of the MIT License.

raix-bedrock

Runtime