raix-bedrock 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0a127460347edbf04426ee850a2cf0553f09c43fdda9888c589053d302869efa
+  data.tar.gz: e2209b270ead4e6015591d3657a883e7b0b57e6aceb90769bc3a6da5552f7a6b
+SHA512:
+  metadata.gz: 79d2080315f2b52efe14b187532aa56ae796ccb3ab086ac110314ade1167b6cff40aa1a7dca7642282fd1cedca54f87cf71ed9fe3979b3ce60aa05c770388a8a
+  data.tar.gz: b6a290017981cd3f911d156ea9194c111986d3fcb5e4a2a5253d8f8ac68172c57a63e4af04375c802253a70876ed28b21ce29d1af1cda37d6ce352c4ce5c2784

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-08-17
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Martin Emde
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,281 @@
+# Raix::Bedrock
+
+AWS Bedrock provider for the [Raix](https://github.com/OlympiaAI/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:
+
+```ruby
+gem "raix"
+gem "raix-bedrock"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+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
+
+```ruby
+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
+
+```ruby
+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
+
+```ruby
+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
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+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:
+
+```bash
+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
+
+```bash
+bundle exec rspec
+```
+
+### Console
+
+```bash
+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.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/raix/bedrock/openai_proxy.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Raix
+  module Bedrock
+    # A proxy class that allows Raix to use the Bedrock provider as an OpenAI client.
+    # This provides backward compatibility if the provider interface is not accepted upstream.
+    class OpenAIProxy
+      def initialize(provider = nil, **provider_options)
+        @provider = provider || Provider.new(**provider_options)
+      end
+
+      def chat(parameters:)
+        @provider.chat(parameters: parameters)
+      end
+    end
+  end
+end

data/lib/raix/bedrock/provider.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "aws-sdk-bedrockruntime"
+
+module Raix
+  module Bedrock
+    # Bedrock provider for Raix.
+    class Provider
+      attr_reader :client
+
+      def initialize(
+        # Prefer inference profile IDs for models that don't support on-demand throughput
+        model: "us.anthropic.claude-sonnet-4-20250514-v1:0",
+        # Alternative with tools: "us.anthropic.claude-3-7-sonnet-20250219-v1:0",
+        region: ENV["AWS_REGION"] || ENV["AMAZON_REGION"] || ENV["AWS_DEFAULT_REGION"] || "us-east-1"
+      )
+        @model = model
+        @client = Aws::BedrockRuntime::Client.new(region: region)
+      end
+
+      # Support for configure.openai_client = Raix::Bedrock::Provider.new(...)
+      # You must tell Raix to use openai in your configuration.
+      def chat(parameters:)
+        # Extract model and messages from the parameters hash
+        # These were merged in by the caller
+        params = parameters.dup
+        model = params.delete(:model)
+        messages = params.delete(:messages)
+
+        # The caller has already modified params:
+        # - Converted max_tokens to max_completion_tokens (unless prediction mode)
+        # - Added stream_options if streaming
+        # - Removed temperature for certain models
+        # We just pass these through as-is since they're already in the expected format
+
+        # Call the main request method
+        request(params: params, model: model, messages: messages)
+      end
+
+      # Support for configure.register_provider(:bedrock, Raix::Bedrock::Provider.new(...))
+      def request(params:, model:, messages:)
+        params = params.dup
+
+        # Remove streaming option - Bedrock Converse API doesn't support streaming
+        params.delete(:stream)
+
+        # Convert OpenAI messages to Bedrock format
+        system_blocks = []
+        convo_messages = []
+
+        messages.each do |m|
+          role = (m[:role] || m["role"]).to_s
+          content = m[:content] || m["content"]
+
+          # OpenAI tool result messages → Bedrock tool_result on a user message
+          if role == "tool"
+            tool_call_id = m[:tool_call_id] || m["tool_call_id"]
+            next unless tool_call_id
+
+            tool_text = content.to_s.strip
+            convo_messages << {
+              role: "user",
+              content: [
+                {
+                  tool_result: {
+                    tool_use_id: tool_call_id,
+                    content: tool_text.empty? ? [] : [{ text: tool_text }],
+                    status: "success"
+                  }
+                }
+              ]
+            }
+            next
+          end
+
+          case role
+          when "system"
+            sys_text = content.to_s.strip
+            system_blocks << { text: sys_text } unless sys_text.empty?
+          when "user"
+            user_text = content.to_s.strip
+            next if user_text.empty?
+
+            convo_messages << { role: "user", content: [{ text: user_text }] }
+          when "assistant"
+            blocks = []
+            # Add text content first if present
+            asst_text = content.to_s.strip
+            blocks << { text: asst_text } unless asst_text.empty?
+
+            # Then add tool_calls
+            tool_calls = m[:tool_calls] || m["tool_calls"]
+            if tool_calls.is_a?(Array)
+              tool_calls.each do |tc|
+                fn = tc[:function] || tc["function"] || {}
+                name = fn[:name] || fn["name"]
+                next unless name
+
+                args = fn[:arguments] || fn["arguments"] || "{}"
+                input_obj = begin
+                  args.is_a?(String) ? JSON.parse(args) : args
+                rescue StandardError
+                  {}
+                end
+                tu_id = tc[:id] || tc["id"] || SecureRandom.uuid
+                blocks << { tool_use: { tool_use_id: tu_id, name: name, input: input_obj } }
+              end
+            end
+            convo_messages << { role: "assistant", content: blocks } if blocks.any?
+          end
+        end
+
+        # Normalize messages
+        normalized_messages = normalize_messages(convo_messages)
+
+        # Build Bedrock parameters
+        bedrock_params = {
+          model_id: model || @model,
+          messages: normalized_messages
+        }
+        bedrock_params[:system] = system_blocks unless system_blocks.empty?
+
+        # Map inference config
+        inference_config = build_inference_config(params)
+        bedrock_params[:inference_config] = inference_config unless inference_config.empty?
+
+        # Map tools if provided
+        if params[:tools].is_a?(Array) && !params[:tools].empty?
+          tool_config = build_tool_config(params[:tools], params[:tool_choice])
+          bedrock_params[:tool_config] = tool_config if tool_config
+        end
+
+        # Make the Bedrock API call
+        response = @client.converse(bedrock_params)
+
+        # Convert Bedrock response to OpenAI format
+        convert_response(response)
+      end
+
+      private
+
+      def normalize_messages(messages)
+        messages.filter_map do |msg|
+          blocks = (msg[:content] || []).filter_map do |blk|
+            if blk[:text]
+              txt = blk[:text].to_s.strip
+              next nil if txt.empty?
+
+              { text: txt }
+            elsif blk[:tool_use]
+              blk
+            elsif blk[:tool_result]
+              normalize_tool_result(blk[:tool_result])
+            end
+          end
+          next if blocks.empty?
+
+          { role: msg[:role], content: blocks }
+        end
+      end
+
+      def normalize_tool_result(tool_result)
+        content = (tool_result[:content] || []).filter_map do |c|
+          if c[:text]
+            t = c[:text].to_s.strip
+            next nil if t.empty?
+
+            { text: t }
+          else
+            c
+          end
+        end
+        # Ensure at least one content block exists
+        content = [{ json: {} }] if content.empty?
+        { tool_result: tool_result.merge(content: content) }
+      end
+
+      def build_inference_config(params)
+        config = {}
+        # Clamp max tokens to model limits; default sensibly if absent
+        max_tokens = params[:max_tokens] || params[:max_completion_tokens] || 1024
+        max_tokens = [max_tokens.to_i, 8192].min
+
+        config[:temperature] = params[:temperature] if params[:temperature]
+        config[:max_tokens] = max_tokens
+        config[:top_p] = params[:top_p] if params[:top_p]
+        config
+      end
+
+      def build_tool_config(tools, tool_choice)
+        bedrock_tools = tools.filter_map do |t|
+          next unless (t[:type] || t["type"]).to_s == "function"
+
+          fn = t[:function] || t["function"] || {}
+          name = fn[:name] || fn["name"]
+          next unless name
+
+          desc = fn[:description] || fn["description"] || ""
+          schema = fn[:parameters] || fn["parameters"] || {}
+          # Convert schema to use string keys for AWS compatibility
+          schema_json = JSON.parse(JSON.generate(schema))
+          { tool_spec: { name: name.to_s, description: desc, input_schema: { json: schema_json } } }
+        end
+
+        return nil if bedrock_tools.empty?
+
+        config = { tools: bedrock_tools }
+
+        # Map tool_choice
+        if tool_choice
+          if tool_choice.is_a?(String)
+            case tool_choice
+            when "auto"
+              config[:tool_choice] = { auto: {} }
+            when "any", "required"
+              config[:tool_choice] = { any: {} }
+            when "none"
+              return nil
+            end
+          elsif tool_choice.is_a?(Hash)
+            tc_type = tool_choice[:type] || tool_choice["type"]
+            if tc_type.to_s == "function"
+              fn = tool_choice[:function] || tool_choice["function"] || {}
+              name = fn[:name] || fn["name"]
+              config[:tool_choice] = { tool: { name: name } } if name
+            end
+          end
+        end
+
+        config
+      end
+
+      def convert_response(response)
+        tool_calls = []
+        text = +""
+
+        (response.output&.message&.content || []).each do |c|
+          text << c.text.to_s if c.respond_to?(:text) && c.text
+          next unless c.respond_to?(:tool_use) && c.tool_use
+
+          tu = c.tool_use
+          args_json = begin
+            input = tu.input
+            # Ensure we have a proper hash with string keys
+            if input.is_a?(Hash)
+              stringified_input = JSON.parse(JSON.generate(input))
+              JSON.dump(stringified_input)
+            elsif input.is_a?(String)
+              input
+            else
+              JSON.dump(input || {})
+            end
+          rescue StandardError => e
+            warn "Error converting tool input: #{e.message}"
+            "{}"
+          end
+
+          tool_calls << {
+            "id" => tu.tool_use_id,
+            "type" => "function",
+            "function" => { "name" => tu.name, "arguments" => args_json }
+          }
+        end
+
+        {
+          "choices" => [
+            {
+              "message" => begin
+                msg = { "role" => "assistant" }
+                msg["content"] = (tool_calls.empty? ? text : nil)
+                msg["tool_calls"] = tool_calls if tool_calls.any?
+                msg
+              end
+            }
+          ],
+          "usage" => {
+            "input_tokens" => response.usage&.input_tokens,
+            "output_tokens" => response.usage&.output_tokens,
+            "total_tokens" => response.usage&.total_tokens
+          }
+        }
+      end
+    end
+  end
+end

data/lib/raix/bedrock/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Raix
+  module Bedrock
+    VERSION = "0.1.0"
+  end
+end

data/lib/raix/bedrock.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "bedrock/version"
+require_relative "bedrock/provider"
+require_relative "bedrock/openai_proxy"
+
+module Raix
+  module Bedrock
+    class Error < StandardError; end
+  end
+end

data/sig/raix/bedrock.rbs

@@ -0,0 +1,6 @@
+module Raix
+  module Bedrock
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: raix-bedrock
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Martin Emde
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-bedrockruntime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: raix
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: AWS Bedrock provider for Raix with tool and MCP support.
+email:
+- me@martinemde.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/raix/bedrock.rb
+- lib/raix/bedrock/openai_proxy.rb
+- lib/raix/bedrock/provider.rb
+- lib/raix/bedrock/version.rb
+- sig/raix/bedrock.rbs
+homepage: https://github.com/martinemde/raix-bedrock
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/martinemde/raix-bedrock
+  source_code_uri: https://github.com/martinemde/raix-bedrock
+  changelog_uri: https://github.com/martinemde/raix-bedrock/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: AWS Bedrock provider for Raix.
+test_files: []