riffer 0.6.1 → 0.8.0

data/lib/riffer/providers/open_ai.rb

@@ -1,85 +1,130 @@
 # frozen_string_literal: true
 
+# OpenAI provider for GPT models.
+#
+# Requires the +openai+ gem to be installed.
 class Riffer::Providers::OpenAI < Riffer::Providers::Base
   # Initializes the OpenAI provider.
-  # @param options [Hash] optional client options. Use `:api_key` to override `Riffer.config.openai.api_key`.
-  # @raise [Riffer::ArgumentError] if an API key is not provided either via `:api_key` or `Riffer.config.openai.api_key`.
+  #
+  # options:: Hash - optional client options
+  #
+  # Use +:api_key+ to override +Riffer.config.openai.api_key+.
   def initialize(**options)
     depends_on "openai"
 
     api_key = options.fetch(:api_key, Riffer.config.openai.api_key)
-    raise Riffer::ArgumentError, "OpenAI API key is required. Set it via Riffer.configure or pass :api_key option" if api_key.nil? || api_key.empty?
-
     @client = ::OpenAI::Client.new(api_key: api_key, **options.except(:api_key))
   end
 
   private
 
-  def perform_generate_text(messages, model:, reasoning: nil)
-    params = build_request_params(messages, model, reasoning)
+  def perform_generate_text(messages, model:, **options)
+    params = build_request_params(messages, model, options)
     response = @client.responses.create(params)
 
-    output = response.output.find { |o| o.type == :message }
-
-    if output.nil?
-      raise Riffer::Error, "No output returned from OpenAI API"
-    end
-
-    content = output.content.find { |c| c.type == :output_text }
-
-    if content.nil?
-      raise Riffer::Error, "No content returned from OpenAI API"
-    end
-
-    if content.type == :refusal
-      raise Riffer::Error, "Request was refused: #{content.refusal}"
-    end
-
-    if content.type != :output_text
-      raise Riffer::Error, "Unexpected content type: #{content.type}"
-    end
-
-    Riffer::Messages::Assistant.new(content.text)
+    extract_assistant_message(response.output)
   end
 
-  def perform_stream_text(messages, model:, reasoning: nil)
+  def perform_stream_text(messages, model:, **options)
     Enumerator.new do |yielder|
-      params = build_request_params(messages, model, reasoning)
+      params = build_request_params(messages, model, options)
       stream = @client.responses.stream(params)
 
       process_stream_events(stream, yielder)
     end
   end
 
-  def build_request_params(messages, model, reasoning)
-    {
-      input: convert_message_to_openai_format(messages),
+  def build_request_params(messages, model, options)
+    reasoning = options[:reasoning]
+    tools = options[:tools]
+
+    params = {
+      input: convert_messages_to_openai_format(messages),
       model: model,
       reasoning: reasoning && {
         effort: reasoning,
         summary: "auto"
-      }
+      },
+      **options.except(:reasoning, :tools)
     }
+
+    if tools && !tools.empty?
+      params[:tools] = tools.map { |t| convert_tool_to_openai_format(t) }
+    end
+
+    params.compact
   end
 
-  def convert_message_to_openai_format(messages)
-    messages.map do |message|
+  def convert_messages_to_openai_format(messages)
+    messages.flat_map do |message|
       case message
       when Riffer::Messages::System
         {role: "developer", content: message.content}
       when Riffer::Messages::User
         {role: "user", content: message.content}
       when Riffer::Messages::Assistant
-        {role: "assistant", content: message.content}
+        convert_assistant_to_openai_format(message)
       when Riffer::Messages::Tool
-        raise NotImplementedError, "Tool messages are not supported by OpenAI provider yet"
+        {
+          type: "function_call_output",
+          call_id: message.tool_call_id,
+          output: message.content
+        }
+      end
+    end
+  end
+
+  def convert_assistant_to_openai_format(message)
+    if message.tool_calls.empty?
+      {role: "assistant", content: message.content}
+    else
+      items = []
+      items << {type: "message", role: "assistant", content: message.content} if message.content && !message.content.empty?
+      message.tool_calls.each do |tc|
+        items << {
+          type: "function_call",
+          id: tc[:id],
+          call_id: tc[:call_id] || tc[:id],
+          name: tc[:name],
+          arguments: tc[:arguments].is_a?(String) ? tc[:arguments] : tc[:arguments].to_json
+        }
+      end
+      items
+    end
+  end
+
+  def extract_assistant_message(output_items)
+    text_content = ""
+    tool_calls = []
+
+    output_items.each do |item|
+      case item.type
+      when :message
+        text_block = item.content&.find { |c| c.type == :output_text }
+        text_content = text_block&.text || "" if text_block
+      when :function_call
+        tool_calls << {
+          id: item.id,
+          call_id: item.call_id,
+          name: item.name,
+          arguments: item.arguments
+        }
       end
     end
+
+    if text_content.empty? && tool_calls.empty?
+      raise Riffer::Error, "No output returned from OpenAI API"
+    end
+
+    Riffer::Messages::Assistant.new(text_content, tool_calls: tool_calls)
   end
 
   def process_stream_events(stream, yielder)
+    tool_info = {}
+
     stream.each do |raw_event|
-      event = convert_event(raw_event)
+      track_tool_info(raw_event, tool_info)
+      event = convert_event(raw_event, tool_info)
 
       next unless event
 
@@ -87,7 +132,17 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     end
   end
 
-  def convert_event(event)
+  def track_tool_info(event, tool_info)
+    return unless event.type == :"response.output_item.added"
+    return unless event.item&.type == :function_call
+
+    tool_info[event.item.id] = {
+      name: event.item.name,
+      call_id: event.item.call_id
+    }
+  end
+
+  def convert_event(event, tool_info = {})
     case event.type
     when :"response.output_text.delta"
       Riffer::StreamEvents::TextDelta.new(event.delta)
@@ -97,6 +152,31 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
       Riffer::StreamEvents::ReasoningDelta.new(event.delta)
     when :"response.reasoning_summary_text.done"
       Riffer::StreamEvents::ReasoningDone.new(event.text)
+    when :"response.function_call_arguments.delta"
+      tracked = tool_info[event.item_id] || {}
+      Riffer::StreamEvents::ToolCallDelta.new(
+        item_id: event.item_id,
+        name: tracked[:name],
+        arguments_delta: event.delta
+      )
+    when :"response.function_call_arguments.done"
+      tracked = tool_info[event.item_id] || {}
+      Riffer::StreamEvents::ToolCallDone.new(
+        item_id: event.item_id,
+        call_id: tracked[:call_id] || event.item_id,
+        name: tracked[:name],
+        arguments: event.arguments
+      )
     end
   end
+
+  def convert_tool_to_openai_format(tool)
+    {
+      type: "function",
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters_schema,
+      strict: true
+    }
+  end
 end

data/lib/riffer/providers/repository.rb

@@ -1,14 +1,19 @@
+# Registry for finding provider classes by identifier.
 class Riffer::Providers::Repository
+  # Mapping of provider identifiers to provider class lambdas.
   REPO = {
-    openai: -> { Riffer::Providers::OpenAI },
     amazon_bedrock: -> { Riffer::Providers::AmazonBedrock },
+    anthropic: -> { Riffer::Providers::Anthropic },
+    openai: -> { Riffer::Providers::OpenAI },
     test: -> { Riffer::Providers::Test }
   }.freeze
 
   class << self
-    # Finds a provider class by identifier
-    # @param identifier [String, Symbol] the identifier to search for
-    # @return [Class, nil] the provider class, or nil if not found
+    # Finds a provider class by identifier.
+    #
+    # identifier:: String or Symbol - the identifier to search for
+    #
+    # Returns Class or nil - the provider class, or nil if not found.
     def find(identifier)
       REPO.fetch(identifier.to_sym, nil)&.call
     end

data/lib/riffer/providers/test.rb

@@ -1,27 +1,75 @@
 # frozen_string_literal: true
 
+# Test provider for mocking LLM responses in tests.
+#
+# No external gems required.
 class Riffer::Providers::Test < Riffer::Providers::Base
+  # Array of recorded method calls for assertions.
+  #
+  # Returns Array of Hash.
   attr_reader :calls
 
+  # Initializes the test provider.
+  #
+  # options:: Hash - optional configuration
+  #
+  # Use +:responses+ to pre-configure responses.
   def initialize(**options)
     @responses = options[:responses] || []
     @current_index = 0
     @calls = []
-    @stubbed_response = nil
-    @stubbed_reasoning = nil
+    @stubbed_responses = []
   end
 
-  def stub_response(content, tool_calls: [], reasoning: nil)
-    @stubbed_response = {role: "assistant", content: content, tool_calls: tool_calls}
-    @stubbed_reasoning = reasoning
+  # Stubs the next response from the provider.
+  #
+  # Can be called multiple times to queue responses.
+  #
+  # content:: String - the response content
+  # tool_calls:: Array of Hash - optional tool calls to include
+  #
+  # Returns void.
+  #
+  #   provider.stub_response("Hello")
+  #   provider.stub_response("", tool_calls: [{name: "my_tool", arguments: '{"key":"value"}'}])
+  #   provider.stub_response("Final response")
+  #
+  def stub_response(content, tool_calls: [])
+    formatted_tool_calls = tool_calls.map.with_index do |tc, idx|
+      {
+        id: tc[:id] || "test_id_#{idx}",
+        call_id: tc[:call_id] || tc[:id] || "test_call_#{idx}",
+        name: tc[:name],
+        arguments: tc[:arguments].is_a?(String) ? tc[:arguments] : tc[:arguments].to_json
+      }
+    end
+    @stubbed_responses << {role: "assistant", content: content, tool_calls: formatted_tool_calls}
+  end
+
+  # Clears all stubbed responses.
+  #
+  # Returns void.
+  def clear_stubs
+    @stubbed_responses = []
   end
 
   private
 
-  def perform_generate_text(messages, model: nil, reasoning: nil)
-    @calls << {messages: messages.map(&:to_h), model: model, reasoning: reasoning}
-    response = @stubbed_response || @responses[@current_index] || {role: "assistant", content: "Test response"}
-    @current_index += 1
+  def next_response
+    if @stubbed_responses.any?
+      @stubbed_responses.shift
+    elsif @responses[@current_index]
+      response = @responses[@current_index]
+      @current_index += 1
+      response
+    else
+      {role: "assistant", content: "Test response"}
+    end
+  end
+
+  def perform_generate_text(messages, model: nil, **options)
+    @calls << {messages: messages.map(&:to_h), model: model, **options}
+    response = next_response
 
     if response.is_a?(Hash)
       Riffer::Messages::Assistant.new(response[:content], tool_calls: response[:tool_calls] || [])
@@ -30,26 +78,32 @@ class Riffer::Providers::Test < Riffer::Providers::Base
     end
   end
 
-  def perform_stream_text(messages, model: nil, reasoning: nil)
-    @calls << {messages: messages.map(&:to_h), model: model, reasoning: reasoning}
-    response = @stubbed_response || @responses[@current_index] || {role: "assistant", content: "Test response"}
-    @current_index += 1
+  def perform_stream_text(messages, model: nil, **options)
+    @calls << {messages: messages.map(&:to_h), model: model, **options}
+    response = next_response
     Enumerator.new do |yielder|
-      if @stubbed_reasoning
-        reasoning_parts = @stubbed_reasoning.split(". ").map { |part| part + (part.end_with?(".") ? "" : ".") }
+      full_content = response[:content] || ""
+      tool_calls = response[:tool_calls] || []
 
-        reasoning_parts.each do |part|
-          yielder << Riffer::StreamEvents::ReasoningDelta.new(part + " ")
+      unless full_content.empty?
+        content_parts = full_content.split(". ").map { |part| part + (part.end_with?(".") ? "" : ".") }
+        content_parts.each do |part|
+          yielder << Riffer::StreamEvents::TextDelta.new(part + " ")
         end
-
-        yielder << Riffer::StreamEvents::ReasoningDone.new(@stubbed_reasoning)
       end
 
-      full_content = response[:content]
-      content_parts = full_content.split(". ").map { |part| part + (part.end_with?(".") ? "" : ".") }
-
-      content_parts.each do |part|
-        yielder << Riffer::StreamEvents::TextDelta.new(part + " ")
+      tool_calls.each do |tc|
+        yielder << Riffer::StreamEvents::ToolCallDelta.new(
+          item_id: tc[:id],
+          name: tc[:name],
+          arguments_delta: tc[:arguments]
+        )
+        yielder << Riffer::StreamEvents::ToolCallDone.new(
+          item_id: tc[:id],
+          call_id: tc[:call_id],
+          name: tc[:name],
+          arguments: tc[:arguments]
+        )
       end
 
       yielder << Riffer::StreamEvents::TextDone.new(full_content)

data/lib/riffer/providers.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
 
+# Namespace for LLM provider adapters in the Riffer framework.
+#
+# Providers connect Riffer to LLM services:
+# - Riffer::Providers::OpenAI - OpenAI GPT models
+# - Riffer::Providers::AmazonBedrock - AWS Bedrock models
+# - Riffer::Providers::Test - Mock provider for testing
 module Riffer::Providers
 end

data/lib/riffer/stream_events/base.rb

@@ -1,12 +1,24 @@
 # frozen_string_literal: true
 
+# Base class for all streaming events in the Riffer framework.
+#
+# Subclasses must implement the +to_h+ method.
 class Riffer::StreamEvents::Base
+  # The message role (typically :assistant).
+  #
+  # Returns Symbol.
   attr_reader :role
 
-  def initialize(role: "assistant")
+  # Creates a new stream event.
+  #
+  # role:: Symbol - the message role (defaults to :assistant)
+  def initialize(role: :assistant)
     @role = role
   end
 
+  # Converts the event to a hash.
+  #
+  # Raises NotImplementedError if not implemented by subclass.
   def to_h
     raise NotImplementedError, "Subclasses must implement #to_h"
   end

data/lib/riffer/stream_events/reasoning_delta.rb

@@ -1,13 +1,27 @@
 # frozen_string_literal: true
 
+# Represents an incremental reasoning chunk during streaming.
+#
+# Emitted when the LLM produces reasoning/thinking content incrementally.
+# Only available with providers that support reasoning (e.g., OpenAI with reasoning option).
 class Riffer::StreamEvents::ReasoningDelta < Riffer::StreamEvents::Base
+  # The incremental reasoning content.
+  #
+  # Returns String.
   attr_reader :content
 
-  def initialize(content, role: "assistant")
+  # Creates a new reasoning delta event.
+  #
+  # content:: String - the incremental reasoning content
+  # role:: Symbol - the message role (defaults to :assistant)
+  def initialize(content, role: :assistant)
     super(role: role)
     @content = content
   end
 
+  # Converts the event to a hash.
+  #
+  # Returns Hash with +:role+ and +:content+ keys.
   def to_h
     {role: @role, content: @content}
   end

data/lib/riffer/stream_events/reasoning_done.rb

@@ -1,13 +1,27 @@
 # frozen_string_literal: true
 
+# Represents completion of reasoning during streaming.
+#
+# Emitted when the LLM has finished producing reasoning/thinking content.
+# Only available with providers that support reasoning (e.g., OpenAI with reasoning option).
 class Riffer::StreamEvents::ReasoningDone < Riffer::StreamEvents::Base
+  # The complete reasoning content.
+  #
+  # Returns String.
   attr_reader :content
 
-  def initialize(content, role: "assistant")
+  # Creates a new reasoning done event.
+  #
+  # content:: String - the complete reasoning content
+  # role:: Symbol - the message role (defaults to :assistant)
+  def initialize(content, role: :assistant)
     super(role: role)
     @content = content
   end
 
+  # Converts the event to a hash.
+  #
+  # Returns Hash with +:role+ and +:content+ keys.
   def to_h
     {role: @role, content: @content}
   end

data/lib/riffer/stream_events/text_delta.rb

@@ -1,13 +1,26 @@
 # frozen_string_literal: true
 
+# Represents an incremental text chunk during streaming.
+#
+# Emitted when the LLM produces text content incrementally.
 class Riffer::StreamEvents::TextDelta < Riffer::StreamEvents::Base
+  # The incremental text content.
+  #
+  # Returns String.
   attr_reader :content
 
-  def initialize(content, role: "assistant")
+  # Creates a new text delta event.
+  #
+  # content:: String - the incremental text content
+  # role:: Symbol - the message role (defaults to :assistant)
+  def initialize(content, role: :assistant)
     super(role: role)
     @content = content
   end
 
+  # Converts the event to a hash.
+  #
+  # Returns Hash with +:role+ and +:content+ keys.
   def to_h
     {role: @role, content: @content}
   end

data/lib/riffer/stream_events/text_done.rb

@@ -1,13 +1,26 @@
 # frozen_string_literal: true
 
+# Represents completion of text generation during streaming.
+#
+# Emitted when the LLM has finished producing text content.
 class Riffer::StreamEvents::TextDone < Riffer::StreamEvents::Base
+  # The complete text content.
+  #
+  # Returns String.
   attr_reader :content
 
-  def initialize(content, role: "assistant")
+  # Creates a new text done event.
+  #
+  # content:: String - the complete text content
+  # role:: Symbol - the message role (defaults to :assistant)
+  def initialize(content, role: :assistant)
     super(role: role)
     @content = content
   end
 
+  # Converts the event to a hash.
+  #
+  # Returns Hash with +:role+ and +:content+ keys.
   def to_h
     {role: @role, content: @content}
   end

data/lib/riffer/stream_events/tool_call_delta.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Riffer::StreamEvents::ToolCallDelta represents an incremental tool call chunk during streaming.
+#
+# Emitted when the LLM is building a tool call, containing partial argument data.
+class Riffer::StreamEvents::ToolCallDelta < Riffer::StreamEvents::Base
+  # The tool call item identifier.
+  attr_reader :item_id
+
+  # The tool name (may only be present in first delta).
+  attr_reader :name
+
+  # The incremental arguments JSON fragment.
+  attr_reader :arguments_delta
+
+  # Creates a new tool call delta event.
+  #
+  # item_id:: String - the tool call item identifier
+  # name:: String or nil - the tool name (may only be present in first delta)
+  # arguments_delta:: String - the incremental arguments JSON fragment
+  # role:: Symbol - the message role (defaults to :assistant)
+  def initialize(item_id:, arguments_delta:, name: nil, role: :assistant)
+    super(role: role)
+    @item_id = item_id
+    @name = name
+    @arguments_delta = arguments_delta
+  end
+
+  # Converts the event to a hash.
+  #
+  # Returns Hash - the event data.
+  def to_h
+    {role: @role, item_id: @item_id, name: @name, arguments_delta: @arguments_delta}.compact
+  end
+end

data/lib/riffer/stream_events/tool_call_done.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Riffer::StreamEvents::ToolCallDone represents a completed tool call during streaming.
+#
+# Emitted when the LLM has finished building a tool call with complete arguments.
+class Riffer::StreamEvents::ToolCallDone < Riffer::StreamEvents::Base
+  # The tool call item identifier.
+  attr_reader :item_id
+
+  # The call identifier for response matching.
+  attr_reader :call_id
+
+  # The tool name.
+  attr_reader :name
+
+  # The complete arguments JSON string.
+  attr_reader :arguments
+
+  # Creates a new tool call done event.
+  #
+  # item_id:: String - the tool call item identifier
+  # call_id:: String - the call identifier for response matching
+  # name:: String - the tool name
+  # arguments:: String - the complete arguments JSON string
+  # role:: Symbol - the message role (defaults to :assistant)
+  def initialize(item_id:, call_id:, name:, arguments:, role: :assistant)
+    super(role: role)
+    @item_id = item_id
+    @call_id = call_id
+    @name = name
+    @arguments = arguments
+  end
+
+  # Converts the event to a hash.
+  #
+  # Returns Hash - the event data.
+  def to_h
+    {role: @role, item_id: @item_id, call_id: @call_id, name: @name, arguments: @arguments}
+  end
+end

data/lib/riffer/stream_events.rb

@@ -1,4 +1,13 @@
 # frozen_string_literal: true
 
+# Namespace for streaming event types in the Riffer framework.
+#
+# When streaming responses, these events are yielded to represent incremental updates:
+# - Riffer::StreamEvents::TextDelta - Incremental text content
+# - Riffer::StreamEvents::TextDone - Complete text content
+# - Riffer::StreamEvents::ToolCallDelta - Incremental tool call arguments
+# - Riffer::StreamEvents::ToolCallDone - Complete tool call
+# - Riffer::StreamEvents::ReasoningDelta - Incremental reasoning content
+# - Riffer::StreamEvents::ReasoningDone - Complete reasoning content
 module Riffer::StreamEvents
 end