riffer 0.6.1 → 0.8.0

data/lib/riffer/messages/tool.rb

@@ -1,19 +1,73 @@
 # frozen_string_literal: true
 
+# Represents a tool execution result in a conversation.
+#
+#   msg = Riffer::Messages::Tool.new(
+#     "The weather is sunny.",
+#     tool_call_id: "call_123",
+#     name: "weather_tool"
+#   )
+#   msg.role          # => :tool
+#   msg.tool_call_id  # => "call_123"
+#   msg.error?        # => false
+#
 class Riffer::Messages::Tool < Riffer::Messages::Base
-  attr_reader :tool_call_id, :name
+  # The ID of the tool call this result responds to.
+  #
+  # Returns String.
+  attr_reader :tool_call_id
 
-  def initialize(content, tool_call_id:, name:)
+  # The name of the tool that was called.
+  #
+  # Returns String.
+  attr_reader :name
+
+  # The error message if the tool execution failed.
+  #
+  # Returns String or nil.
+  attr_reader :error
+
+  # The type of error (:unknown_tool, :validation_error, :execution_error, :timeout_error).
+  #
+  # Returns Symbol or nil.
+  attr_reader :error_type
+
+  # Creates a new tool result message.
+  #
+  # content:: String - the tool execution result
+  # tool_call_id:: String - the ID of the tool call
+  # name:: String - the tool name
+  # error:: String or nil - optional error message
+  # error_type:: Symbol or nil - optional error type
+  def initialize(content, tool_call_id:, name:, error: nil, error_type: nil)
     super(content)
     @tool_call_id = tool_call_id
     @name = name
+    @error = error
+    @error_type = error_type
+  end
+
+  # Returns true if the tool execution resulted in an error.
+  #
+  # Returns Boolean.
+  def error?
+    !@error.nil?
   end
 
+  # Returns :tool.
   def role
-    "tool"
+    :tool
   end
 
+  # Converts the message to a hash.
+  #
+  # Returns Hash with message data including error info if present.
   def to_h
-    {role: role, content: content, tool_call_id: tool_call_id, name: name}
+    hash = {role: role, content: content, tool_call_id: tool_call_id, name: name}
+    if error?
+      hash[:error] = error
+      hash[:error_type] = error_type
+    end
+    hash
   end
 end

data/lib/riffer/messages/user.rb

@@ -1,7 +1,14 @@
 # frozen_string_literal: true
 
+# Represents a user message in a conversation.
+#
+#   msg = Riffer::Messages::User.new("Hello!")
+#   msg.role     # => :user
+#   msg.content  # => "Hello!"
+#
 class Riffer::Messages::User < Riffer::Messages::Base
+  # Returns :user.
   def role
-    "user"
+    :user
   end
 end

data/lib/riffer/messages.rb

@@ -1,4 +1,11 @@
 # frozen_string_literal: true
 
+# Namespace for message types in the Riffer framework.
+#
+# Message objects represent the conversation between users and the assistant:
+# - Riffer::Messages::System - System instructions
+# - Riffer::Messages::User - User input
+# - Riffer::Messages::Assistant - LLM responses
+# - Riffer::Messages::Tool - Tool execution results
 module Riffer::Messages
 end

data/lib/riffer/providers/amazon_bedrock.rb

@@ -1,12 +1,18 @@
 # frozen_string_literal: true
 
+require "json"
+
+# Amazon Bedrock provider for Claude and other foundation models.
+#
+# Requires the +aws-sdk-bedrockruntime+ gem to be installed.
+#
+# See https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/BedrockRuntime/Client.html
 class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   # Initializes the Amazon Bedrock provider.
   #
-  # @param options [Hash] options passed to Aws::BedrockRuntime::Client
-  # @option options [String] :api_token Bearer token for API authentication (requires :region)
-  # @option options [String] :region AWS region
-  # @see https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/BedrockRuntime/Client.html
+  # api_token:: String or nil - Bearer token for API authentication
+  # region:: String or nil - AWS region
+  # options:: Hash - additional options passed to Aws::BedrockRuntime::Client
   def initialize(api_token: nil, region: nil, **options)
     depends_on "aws-sdk-bedrockruntime"
 
@@ -27,37 +33,87 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
 
   private
 
-  def perform_generate_text(messages, model:, reasoning: nil)
+  def perform_generate_text(messages, model:, **options)
     partitioned_messages = partition_messages(messages)
+    tools = options[:tools]
 
     params = {
       model_id: model,
       system: partitioned_messages[:system],
-      messages: partitioned_messages[:conversation]
+      messages: partitioned_messages[:conversation],
+      **options.except(:tools)
     }
 
+    if tools && !tools.empty?
+      params[:tool_config] = {
+        tools: tools.map { |t| convert_tool_to_bedrock_format(t) }
+      }
+    end
+
     response = @client.converse(**params)
     extract_assistant_message(response)
   end
 
-  def perform_stream_text(messages, model:, reasoning: nil)
+  def perform_stream_text(messages, model:, **options)
     Enumerator.new do |yielder|
       partitioned_messages = partition_messages(messages)
+      tools = options[:tools]
 
       params = {
         model_id: model,
         system: partitioned_messages[:system],
-        messages: partitioned_messages[:conversation]
+        messages: partitioned_messages[:conversation],
+        **options.except(:tools)
       }
 
+      if tools && !tools.empty?
+        params[:tool_config] = {
+          tools: tools.map { |t| convert_tool_to_bedrock_format(t) }
+        }
+      end
+
       accumulated_text = ""
+      current_tool_use = nil
 
       @client.converse_stream(**params) do |stream|
+        stream.on_content_block_start_event do |event|
+          if event.start&.tool_use
+            tool_use = event.start.tool_use
+            current_tool_use = {
+              id: tool_use.tool_use_id,
+              name: tool_use.name,
+              arguments: ""
+            }
+          end
+        end
+
         stream.on_content_block_delta_event do |event|
           if event.delta&.text
             delta_text = event.delta.text
             accumulated_text += delta_text
             yielder << Riffer::StreamEvents::TextDelta.new(delta_text)
+          elsif event.delta&.tool_use
+            input_delta = event.delta.tool_use.input
+            if current_tool_use && input_delta
+              current_tool_use[:arguments] += input_delta
+              yielder << Riffer::StreamEvents::ToolCallDelta.new(
+                item_id: current_tool_use[:id],
+                name: current_tool_use[:name],
+                arguments_delta: input_delta
+              )
+            end
+          end
+        end
+
+        stream.on_content_block_stop_event do |_event|
+          if current_tool_use
+            yielder << Riffer::StreamEvents::ToolCallDone.new(
+              item_id: current_tool_use[:id],
+              call_id: current_tool_use[:id],
+              name: current_tool_use[:name],
+              arguments: current_tool_use[:arguments]
+            )
+            current_tool_use = nil
           end
         end
 
@@ -79,9 +135,17 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
       when Riffer::Messages::User
         conversation_messages << {role: "user", content: [{text: message.content}]}
       when Riffer::Messages::Assistant
-        conversation_messages << {role: "assistant", content: [{text: message.content}]}
+        conversation_messages << convert_assistant_to_bedrock_format(message)
       when Riffer::Messages::Tool
-        raise NotImplementedError, "Tool messages are not supported by Amazon Bedrock provider yet"
+        conversation_messages << {
+          role: "user",
+          content: [{
+            tool_result: {
+              tool_use_id: message.tool_call_id,
+              content: [{text: message.content}]
+            }
+          }]
+        }
       end
     end
 
@@ -91,6 +155,28 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     }
   end
 
+  def convert_assistant_to_bedrock_format(message)
+    content = []
+    content << {text: message.content} if message.content && !message.content.empty?
+
+    message.tool_calls.each do |tc|
+      content << {
+        tool_use: {
+          tool_use_id: tc[:id] || tc[:call_id],
+          name: tc[:name],
+          input: parse_tool_arguments(tc[:arguments])
+        }
+      }
+    end
+
+    {role: "assistant", content: content}
+  end
+
+  def parse_tool_arguments(arguments)
+    return {} if arguments.nil? || arguments.empty?
+    arguments.is_a?(String) ? JSON.parse(arguments) : arguments
+  end
+
   def extract_assistant_message(response)
     output = response.output
     raise Riffer::Error, "No output returned from Bedrock API" if output.nil? || output.message.nil?
@@ -98,9 +184,38 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     content_blocks = output.message.content
     raise Riffer::Error, "No content returned from Bedrock API" if content_blocks.nil? || content_blocks.empty?
 
-    text_block = content_blocks.find { |block| block.respond_to?(:text) && block.text }
-    raise Riffer::Error, "No text content returned from Bedrock API" if text_block.nil?
+    text_content = ""
+    tool_calls = []
+
+    content_blocks.each do |block|
+      if block.respond_to?(:text) && block.text
+        text_content = block.text
+      elsif block.respond_to?(:tool_use) && block.tool_use
+        tool_calls << {
+          id: block.tool_use.tool_use_id,
+          call_id: block.tool_use.tool_use_id,
+          name: block.tool_use.name,
+          arguments: block.tool_use.input.to_json
+        }
+      end
+    end
+
+    if text_content.empty? && tool_calls.empty?
+      raise Riffer::Error, "No content returned from Bedrock API"
+    end
+
+    Riffer::Messages::Assistant.new(text_content, tool_calls: tool_calls)
+  end
 
-    Riffer::Messages::Assistant.new(text_block.text)
+  def convert_tool_to_bedrock_format(tool)
+    {
+      tool_spec: {
+        name: tool.name,
+        description: tool.description,
+        input_schema: {
+          json: tool.parameters_schema
+        }
+      }
+    }
   end
 end

data/lib/riffer/providers/anthropic.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "json"
+
+# Anthropic provider for Claude models via the Anthropic API.
+#
+# Requires the +anthropic+ gem to be installed.
+#
+# See https://github.com/anthropics/anthropic-sdk-ruby
+class Riffer::Providers::Anthropic < Riffer::Providers::Base
+  # Initializes the Anthropic provider.
+  #
+  # api_key:: String or nil - Anthropic API key
+  # options:: Hash - additional options passed to Anthropic::Client
+  def initialize(api_key: nil, **options)
+    depends_on "anthropic"
+
+    api_key ||= Riffer.config.anthropic.api_key
+
+    @client = Anthropic::Client.new(api_key: api_key, **options)
+  end
+
+  private
+
+  def perform_generate_text(messages, model:, **options)
+    partitioned_messages = partition_messages(messages)
+    tools = options[:tools]
+
+    max_tokens = options.fetch(:max_tokens, 4096)
+
+    params = {
+      model: model,
+      messages: partitioned_messages[:conversation],
+      max_tokens: max_tokens,
+      **options.except(:tools, :max_tokens)
+    }
+
+    params[:system] = partitioned_messages[:system] if partitioned_messages[:system]
+
+    if tools && !tools.empty?
+      params[:tools] = tools.map { |t| convert_tool_to_anthropic_format(t) }
+    end
+
+    response = @client.messages.create(**params)
+    extract_assistant_message(response)
+  end
+
+  def perform_stream_text(messages, model:, **options)
+    Enumerator.new do |yielder|
+      partitioned_messages = partition_messages(messages)
+      tools = options[:tools]
+
+      max_tokens = options.fetch(:max_tokens, 4096)
+
+      params = {
+        model: model,
+        messages: partitioned_messages[:conversation],
+        max_tokens: max_tokens,
+        **options.except(:tools, :max_tokens)
+      }
+
+      params[:system] = partitioned_messages[:system] if partitioned_messages[:system]
+
+      if tools && !tools.empty?
+        params[:tools] = tools.map { |t| convert_tool_to_anthropic_format(t) }
+      end
+
+      accumulated_text = ""
+      accumulated_reasoning = ""
+      current_tool_use = nil
+
+      stream = @client.messages.stream(**params)
+      stream.each do |event|
+        case event
+        when Anthropic::Streaming::TextEvent
+          accumulated_text += event.text
+          yielder << Riffer::StreamEvents::TextDelta.new(event.text)
+
+        when Anthropic::Streaming::ThinkingEvent
+          accumulated_reasoning += event.thinking
+          yielder << Riffer::StreamEvents::ReasoningDelta.new(event.thinking)
+
+        when Anthropic::Streaming::InputJsonEvent
+          # Tool call JSON delta - we need to track the tool use block
+          if current_tool_use.nil?
+            # Find the current tool use block being built
+            current_tool_use = {id: nil, name: nil, arguments: ""}
+          end
+          current_tool_use[:arguments] += event.partial_json
+          yielder << Riffer::StreamEvents::ToolCallDelta.new(
+            item_id: current_tool_use[:id] || "pending",
+            name: current_tool_use[:name],
+            arguments_delta: event.partial_json
+          )
+
+        when Anthropic::Streaming::ContentBlockStopEvent
+          content_block = event.content_block
+          if content_block.respond_to?(:type)
+            block_type = content_block.type.to_s
+            if block_type == "tool_use"
+              # content_block.input is already a JSON string when streaming
+              arguments = content_block.input.is_a?(String) ? content_block.input : content_block.input.to_json
+              yielder << Riffer::StreamEvents::ToolCallDone.new(
+                item_id: content_block.id,
+                call_id: content_block.id,
+                name: content_block.name,
+                arguments: arguments
+              )
+              current_tool_use = nil
+            elsif block_type == "thinking" && !accumulated_reasoning.empty?
+              yielder << Riffer::StreamEvents::ReasoningDone.new(accumulated_reasoning)
+            end
+          end
+
+        when Anthropic::Streaming::MessageStopEvent
+          yielder << Riffer::StreamEvents::TextDone.new(accumulated_text)
+        end
+      end
+    end
+  end
+
+  def partition_messages(messages)
+    system_prompts = []
+    conversation_messages = []
+
+    messages.each do |message|
+      case message
+      when Riffer::Messages::System
+        system_prompts << {type: "text", text: message.content}
+      when Riffer::Messages::User
+        conversation_messages << {role: "user", content: message.content}
+      when Riffer::Messages::Assistant
+        conversation_messages << convert_assistant_to_anthropic_format(message)
+      when Riffer::Messages::Tool
+        conversation_messages << {
+          role: "user",
+          content: [{
+            type: "tool_result",
+            tool_use_id: message.tool_call_id,
+            content: message.content
+          }]
+        }
+      end
+    end
+
+    {
+      system: system_prompts.empty? ? nil : system_prompts,
+      conversation: conversation_messages
+    }
+  end
+
+  def convert_assistant_to_anthropic_format(message)
+    content = []
+    content << {type: "text", text: message.content} if message.content && !message.content.empty?
+
+    message.tool_calls.each do |tc|
+      content << {
+        type: "tool_use",
+        id: tc[:id] || tc[:call_id],
+        name: tc[:name],
+        input: parse_tool_arguments(tc[:arguments])
+      }
+    end
+
+    {role: "assistant", content: content}
+  end
+
+  def parse_tool_arguments(arguments)
+    return {} if arguments.nil? || arguments.empty?
+    arguments.is_a?(String) ? JSON.parse(arguments) : arguments
+  end
+
+  def extract_assistant_message(response)
+    content_blocks = response.content
+    raise Riffer::Error, "No content returned from Anthropic API" if content_blocks.nil? || content_blocks.empty?
+
+    text_content = ""
+    tool_calls = []
+
+    content_blocks.each do |block|
+      block_type = block.type.to_s
+      case block_type
+      when "text"
+        text_content = block.text
+      when "tool_use"
+        tool_calls << {
+          id: block.id,
+          call_id: block.id,
+          name: block.name,
+          arguments: block.input.to_json
+        }
+      end
+    end
+
+    if text_content.empty? && tool_calls.empty?
+      raise Riffer::Error, "No content returned from Anthropic API"
+    end
+
+    Riffer::Messages::Assistant.new(text_content, tool_calls: tool_calls)
+  end
+
+  def convert_tool_to_anthropic_format(tool)
+    {
+      name: tool.name,
+      description: tool.description,
+      input_schema: tool.parameters_schema
+    }
+  end
+end

data/lib/riffer/providers/base.rb

@@ -1,46 +1,51 @@
 # frozen_string_literal: true
 
+# Base class for all LLM providers in the Riffer framework.
+#
+# Subclasses must implement +perform_generate_text+ and +perform_stream_text+.
 class Riffer::Providers::Base
   include Riffer::Helpers::Dependencies
   include Riffer::Messages::Converter
 
   # Generates text using the provider.
   #
-  # @param prompt [String, nil] the user prompt (required when `messages` is not provided)
-  # @param system [String, nil] an optional system message
-  # @param messages [Array<Hash, Riffer::Messages::Base>, nil] optional messages array
-  # @param model [String, nil] optional model string to override the configured model
-  # @param reasoning [String, nil] optional reasoning level or instructions
-  # @return [Riffer::Messages::Assistant] the generated assistant message
-  def generate_text(prompt: nil, system: nil, messages: nil, model: nil, reasoning: nil)
+  # prompt:: String or nil - the user prompt (required when messages is not provided)
+  # system:: String or nil - an optional system message
+  # messages:: Array or nil - optional messages array
+  # model:: String or nil - optional model string to override the configured model
+  # options:: Hash - additional options passed to the model invocation
+  #
+  # Returns Riffer::Messages::Assistant - the generated assistant message.
+  def generate_text(prompt: nil, system: nil, messages: nil, model: nil, **options)
     validate_input!(prompt: prompt, system: system, messages: messages)
     normalized_messages = normalize_messages(prompt: prompt, system: system, messages: messages)
     validate_normalized_messages!(normalized_messages)
-    perform_generate_text(normalized_messages, model: model, reasoning: reasoning)
+    perform_generate_text(normalized_messages, model: model, **options)
   end
 
   # Streams text from the provider.
   #
-  # @param prompt [String, nil] the user prompt (required when `messages` is not provided)
-  # @param system [String, nil] an optional system message
-  # @param messages [Array<Hash, Riffer::Messages::Base>, nil] optional messages array
-  # @param model [String, nil] optional model string to override the configured model
-  # @param reasoning [String, nil] optional reasoning level or instructions
-  # @return [Enumerator] an enumerator yielding stream events or chunks (provider-specific)
-  def stream_text(prompt: nil, system: nil, messages: nil, model: nil, reasoning: nil)
+  # prompt:: String or nil - the user prompt (required when messages is not provided)
+  # system:: String or nil - an optional system message
+  # messages:: Array or nil - optional messages array
+  # model:: String or nil - optional model string to override the configured model
+  # options:: Hash - additional options passed to the model invocation
+  #
+  # Returns Enumerator - an enumerator yielding stream events.
+  def stream_text(prompt: nil, system: nil, messages: nil, model: nil, **options)
     validate_input!(prompt: prompt, system: system, messages: messages)
     normalized_messages = normalize_messages(prompt: prompt, system: system, messages: messages)
     validate_normalized_messages!(normalized_messages)
-    perform_stream_text(normalized_messages, model: model, reasoning: reasoning)
+    perform_stream_text(normalized_messages, model: model, **options)
   end
 
   private
 
-  def perform_generate_text(messages, model: nil, reasoning: nil)
+  def perform_generate_text(messages, model: nil, **options)
     raise NotImplementedError, "Subclasses must implement #perform_generate_text"
   end
 
-  def perform_stream_text(messages, model: nil, reasoning: nil)
+  def perform_stream_text(messages, model: nil, **options)
     raise NotImplementedError, "Subclasses must implement #perform_stream_text"
   end