riffer 0.28.0 → 0.29.1

data/lib/riffer/providers/gemini.rb

@@ -8,6 +8,10 @@ require "uri"
 
 # Google Gemini provider for Gemini models via the Gemini REST API.
 class Riffer::Providers::Gemini < Riffer::Providers::Base
+  # @rbs @api_key: String?
+  # @rbs @open_timeout: Integer
+  # @rbs @read_timeout: Integer
+
   BASE_URI = URI("https://generativelanguage.googleapis.com") #: URI::Generic
   VALID_MODEL_PATTERN = /\A[a-zA-Z0-9._-]+\z/ #: Regexp
   DEFAULT_OPEN_TIMEOUT = 10 #: Integer
@@ -36,7 +40,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     params = {
       model: model,
       contents: partitioned[:contents]
-    }
+    } #: Hash[Symbol, untyped]
 
     params[:systemInstruction] = partitioned[:system_instruction] if partitioned[:system_instruction]
 
@@ -96,12 +100,12 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   end
 
   #--
-  #: (Hash[Symbol, untyped]) -> Riffer::TokenUsage?
+  #: (Hash[Symbol, untyped]) -> Riffer::Providers::TokenUsage?
   def extract_token_usage(response)
     usage = response[:usageMetadata]
     return nil unless usage
 
-    Riffer::TokenUsage.new(
+    Riffer::Providers::TokenUsage.new(
       input_tokens: usage[:promptTokenCount] || 0,
       output_tokens: usage[:candidatesTokenCount] || 0
     )
@@ -114,6 +118,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     body = params.except(:model)
 
     uri = URI("#{BASE_URI}/#{api_path(model, "streamGenerateContent")}?alt=sse")
+    host = uri.hostname #: String
     request = Net::HTTP::Post.new(uri)
     request["Content-Type"] = "application/json"
     request["x-goog-api-key"] = @api_key
@@ -126,7 +131,8 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
       buffer << chunk
 
       while (match = buffer.match(/\r?\n\r?\n/))
-        frame = buffer.slice!(0, match.end(0)).strip
+        match_end = match.end(0) #: Integer
+        frame = buffer.slice!(0, match_end).to_s.strip
         next unless frame.start_with?("data: ")
 
         json_str = frame.delete_prefix("data: ").strip
@@ -155,7 +161,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
         usage = parsed[:usageMetadata]
         if usage && usage[:candidatesTokenCount]
           yielder << Riffer::StreamEvents::TokenUsageDone.new(
-            token_usage: Riffer::TokenUsage.new(
+            token_usage: Riffer::Providers::TokenUsage.new(
               input_tokens: usage[:promptTokenCount] || 0,
               output_tokens: usage[:candidatesTokenCount] || 0
             )
@@ -164,7 +170,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
       end
     end
 
-    Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, open_timeout: @open_timeout, read_timeout: @read_timeout) do |http|
+    Net::HTTP.start(host, uri.port, use_ssl: true, open_timeout: @open_timeout, read_timeout: @read_timeout) do |http|
       http.request(request) do |response|
         handle_api_error!(response) unless response.is_a?(Net::HTTPSuccess)
 
@@ -182,8 +188,8 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   #--
   #: (Array[Riffer::Messages::Base]) -> Hash[Symbol, untyped]
   def partition_messages(messages)
-    system_parts = []
-    contents = []
+    system_parts = [] #: Array[Hash[Symbol, untyped]]
+    contents = [] #: Array[Hash[Symbol, untyped]]
 
     messages.each do |message|
       case message
@@ -212,7 +218,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
       end
     end
 
-    result = {contents: contents}
+    result = {contents: contents} #: Hash[Symbol, untyped]
     result[:system_instruction] = {parts: system_parts} unless system_parts.empty?
     result
   end
@@ -220,7 +226,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   #--
   #: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
   def convert_assistant_to_gemini_format(message)
-    parts = []
+    parts = [] #: Array[Hash[Symbol, untyped]]
     parts << {text: message.content} if message.content && !message.content.empty?
 
     message.tool_calls.each do |tc|
@@ -236,7 +242,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::FilePart) -> Hash[Symbol, untyped]
+  #: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
   def convert_file_part_to_gemini_format(file)
     if file.url?
       raise Riffer::ArgumentError,
@@ -268,11 +274,12 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   #: (String, Hash[Symbol, untyped]) -> Net::HTTPResponse
   def post_request(path, body)
     uri = URI("#{BASE_URI}/#{path}")
+    host = uri.hostname #: String
     request = Net::HTTP::Post.new(uri)
     request["Content-Type"] = "application/json"
     request["x-goog-api-key"] = @api_key
     request.body = body.to_json
-    Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, open_timeout: @open_timeout, read_timeout: @read_timeout) { |http| http.request(request) }
+    Net::HTTP.start(host, uri.port, use_ssl: true, open_timeout: @open_timeout, read_timeout: @read_timeout) { |http| http.request(request) }
   end
 
   #--

data/lib/riffer/providers/mock.rb

@@ -5,6 +5,10 @@
 #
 # No external gems required.
 class Riffer::Providers::Mock < Riffer::Providers::Base
+  # @rbs @responses: Array[Hash[Symbol, untyped]]
+  # @rbs @current_index: Integer
+  # @rbs @stubbed_responses: Array[Hash[Symbol, untyped]]
+
   # Returns the preferred skill adapter for the given mock model.
   #
   # Mock is used to stand in for any real provider in tests, so the model
@@ -25,10 +29,21 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
 
   # Initializes the mock provider.
   #
+  # +responses:+ accepts an array of response hashes in the same shape
+  # +#stub_response+ takes — raw +tool_calls:+ hashes are normalised to
+  # +Riffer::Messages::Assistant::ToolCall+ instances. This is the canonical
+  # way to pre-configure canned LLM responses on an agent via
+  # +provider_options responses: [...]+.
+  #
+  #   Riffer::Providers::Mock.new(responses: [
+  #     {content: "", tool_calls: [{name: "tool_a", arguments: "{}"}]},
+  #     {content: "Final answer"}
+  #   ])
+  #
   #--
   #: (**untyped) -> void
   def initialize(**options)
-    @responses = options[:responses] || []
+    @responses = (options[:responses] || []).map { |r| normalize_response(r) }
     @current_index = 0
     @calls = []
     @stubbed_responses = []
@@ -40,19 +55,12 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   #
   #   provider.stub_response("Hello")
   #   provider.stub_response("", tool_calls: [{name: "my_tool", arguments: '{"key":"value"}'}])
-  #   provider.stub_response("Final response", token_usage: Riffer::TokenUsage.new(input_tokens: 10, output_tokens: 5))
+  #   provider.stub_response("Final response", token_usage: Riffer::Providers::TokenUsage.new(input_tokens: 10, output_tokens: 5))
   #
   #--
-  #: (String, ?tool_calls: Array[Hash[Symbol, untyped]], ?token_usage: Riffer::TokenUsage?) -> void
+  #: (String, ?tool_calls: Array[Hash[Symbol, untyped]], ?token_usage: Riffer::Providers::TokenUsage?) -> void
   def stub_response(content, tool_calls: [], token_usage: nil)
-    formatted_tool_calls = tool_calls.map.with_index do |tc, idx|
-      Riffer::Messages::Assistant::ToolCall.new(
-        call_id: tc[:call_id] || tc[:id] || "mock_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, token_usage: token_usage}
+    @stubbed_responses << normalize_response(content: content, tool_calls: tool_calls, token_usage: token_usage)
   end
 
   # Clears all stubbed responses.
@@ -65,6 +73,30 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
 
   private
 
+  # Normalises a response hash into Mock's internal format. Accepts the
+  # +#stub_response+ kwargs shape (+content:+, +tool_calls:+, +token_usage:+)
+  # or a pre-built hash with already-converted ToolCall instances. Raw
+  # +tool_calls:+ hashes are wrapped in +Riffer::Messages::Assistant::ToolCall+.
+  #
+  #--
+  #: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+  def normalize_response(response)
+    formatted_tool_calls = (response[:tool_calls] || []).map.with_index do |tc, idx|
+      next tc if tc.is_a?(Riffer::Messages::Assistant::ToolCall)
+      Riffer::Messages::Assistant::ToolCall.new(
+        call_id: tc[:call_id] || tc[:id] || "mock_call_#{idx}",
+        name: tc[:name],
+        arguments: tc[:arguments].is_a?(String) ? tc[:arguments] : tc[:arguments].to_json
+      )
+    end
+    {
+      role: response[:role] || "assistant",
+      content: response[:content] || "",
+      tool_calls: formatted_tool_calls,
+      token_usage: response[:token_usage]
+    }
+  end
+
   #--
   #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def build_request_params(messages, model, options)
@@ -82,7 +114,7 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped) -> Riffer::TokenUsage?
+  #: (untyped) -> Riffer::Providers::TokenUsage?
   def extract_token_usage(response)
     response[:token_usage]
   end
@@ -146,7 +178,7 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   def next_response
     if @stubbed_responses.any?
       @stubbed_responses.shift
-    elsif @responses[@current_index]
+    elsif @current_index < @responses.size
       response = @responses[@current_index]
       @current_index += 1
       response

data/lib/riffer/providers/open_ai.rb

@@ -36,9 +36,9 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
         summary: "auto"
       },
       **options.except(:reasoning, :tools, :structured_output, :web_search)
-    }
+    } #: Hash[Symbol, untyped]
 
-    openai_tools = []
+    openai_tools = [] #: Array[Hash[Symbol, untyped]]
     openai_tools.concat(tools.map { |t| convert_tool_to_openai_format(t) }) if tools && !tools.empty?
 
     if web_search
@@ -66,51 +66,54 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   end
 
   #--
-  #: (Hash[Symbol, untyped]) -> OpenAI::Models::Responses::Response
+  #: (Hash[Symbol, untyped]) -> untyped
   def execute_generate(params)
     @client.responses.create(params)
   end
 
   #--
-  #: (OpenAI::Models::Responses::Response) -> Riffer::TokenUsage?
+  #: (untyped) -> Riffer::Providers::TokenUsage?
   def extract_token_usage(response)
-    usage = response.usage
+    typed_response = response #: OpenAI::Models::Responses::Response
+    usage = typed_response.usage
     return nil unless usage
 
-    Riffer::TokenUsage.new(
+    Riffer::Providers::TokenUsage.new(
       input_tokens: usage.input_tokens,
       output_tokens: usage.output_tokens
     )
   end
 
   #--
-  #: (OpenAI::Models::Responses::Response) -> String
+  #: (untyped) -> String
   def extract_content(response)
+    typed_response = response #: OpenAI::Models::Responses::Response
     text_content = ""
 
-    response.output.each do |item|
-      if item.type == :message
-        text_block = item.content&.find { |c| c.type == :output_text }
-        text_content = text_block&.text || "" if text_block
-      end
+    typed_response.output.each do |item|
+      next unless item.is_a?(::OpenAI::Models::Responses::ResponseOutputMessage)
+
+      text_block = item.content.find { |c| c.is_a?(::OpenAI::Models::Responses::ResponseOutputText) }
+      text_content = text_block.text if text_block.is_a?(::OpenAI::Models::Responses::ResponseOutputText)
     end
 
     text_content
   end
 
   #--
-  #: (OpenAI::Models::Responses::Response) -> Array[Riffer::Messages::Assistant::ToolCall]
+  #: (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
   def extract_tool_calls(response)
-    tool_calls = []
-
-    response.output.each do |item|
-      if item.type == :function_call
-        tool_calls << Riffer::Messages::Assistant::ToolCall.new(
-          call_id: item.call_id,
-          name: decode_tool_name(item.name, tools: @current_tools),
-          arguments: item.arguments
-        )
-      end
+    typed_response = response #: OpenAI::Models::Responses::Response
+    tool_calls = [] #: Array[Riffer::Messages::Assistant::ToolCall]
+
+    typed_response.output.each do |item|
+      next unless item.is_a?(::OpenAI::Models::Responses::ResponseFunctionToolCall)
+
+      tool_calls << Riffer::Messages::Assistant::ToolCall.new(
+        call_id: item.call_id,
+        name: decode_tool_name(item.name, tools: @current_tools),
+        arguments: item.arguments
+      )
     end
 
     tool_calls
@@ -121,7 +124,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   def execute_stream(params, yielder)
     current_state = {
       tool_info: {}
-    }
+    } #: Hash[Symbol, untyped]
 
     stream = @client.responses.stream(params)
     begin
@@ -224,7 +227,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     return unless usage
 
     yielder << Riffer::StreamEvents::TokenUsageDone.new(
-      token_usage: Riffer::TokenUsage.new(
+      token_usage: Riffer::Providers::TokenUsage.new(
         input_tokens: usage.input_tokens,
         output_tokens: usage.output_tokens
       )
@@ -242,11 +245,11 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   def handle_output_item_done_web_search(event, yielder:)
     action = event.item.action
     case action
-    when OpenAI::Models::Responses::ResponseFunctionWebSearch::Action::OpenPage
+    when ::OpenAI::Models::Responses::ResponseFunctionWebSearch::Action::OpenPage
       # OpenPage carries a url but no query or sources, so it doesn't fit
       # WebSearchDone — emit as a status notification instead.
       yielder << Riffer::StreamEvents::WebSearchStatus.new("open_page", url: action.url)
-    when OpenAI::Models::Responses::ResponseFunctionWebSearch::Action::Search
+    when ::OpenAI::Models::Responses::ResponseFunctionWebSearch::Action::Search
       sources = (action.sources || []).map { |s| {title: nil, url: s.url} }
       yielder << Riffer::StreamEvents::WebSearchDone.new(action.query, sources: sources)
     end
@@ -275,6 +278,8 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
           call_id: message.tool_call_id,
           output: message.content
         }
+      else
+        raise Riffer::ArgumentError, "unsupported message type: #{message.class}"
       end
     end
   end
@@ -285,7 +290,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     if message.tool_calls.empty?
       {role: "assistant", content: message.content}
     else
-      items = []
+      items = [] #: Array[Hash[Symbol, untyped]]
       items << {type: "message", role: "assistant", content: message.content} if message.content && !message.content.empty?
       message.tool_calls.each do |tc|
         items << {
@@ -300,7 +305,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::FilePart) -> Hash[Symbol, untyped]
+  #: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
   def convert_file_part_to_openai_format(file)
     if file.image?
       image_url = file.url? ? file.url : "data:#{file.media_type};base64,#{file.data}"

data/lib/riffer/providers/open_router.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "json"
+
+# OpenRouter provider for the OpenRouter unified gateway (https://openrouter.ai).
+#
+# Requires the +openai+ gem to be installed. OpenRouter exposes an
+# OpenAI-compatible Chat Completions endpoint, so this provider reuses
+# the OpenAI Ruby SDK with a +base_url+ override.
+#
+# The +api_key+ falls back to <tt>Riffer.config.openrouter.api_key</tt>
+# and then to +OPENROUTER_API_KEY+.
+class Riffer::Providers::OpenRouter < Riffer::Providers::Base
+  BASE_URL = "https://openrouter.ai/api/v1" #: String
+
+  # Initializes the OpenRouter provider.
+  #
+  #--
+  #: (?api_key: String?, **untyped) -> void
+  def initialize(api_key: nil, **options)
+    depends_on "openai"
+
+    api_key ||= Riffer.config.openrouter.api_key || ENV["OPENROUTER_API_KEY"]
+
+    @client = ::OpenAI::Client.new(api_key: api_key, base_url: BASE_URL, **options)
+  end
+
+  private
+
+  #--
+  #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+  def build_request_params(messages, model, options)
+    reasoning = options[:reasoning]
+    tools = options[:tools]
+    structured_output = options[:structured_output]
+
+    params = {
+      model: model,
+      messages: convert_messages_to_chat_completions_format(messages),
+      **options.except(:reasoning, :tools, :structured_output)
+    } #: Hash[Symbol, untyped]
+
+    if reasoning
+      params[:reasoning] = reasoning.is_a?(String) ? {effort: reasoning} : reasoning
+    end
+
+    if tools && !tools.empty?
+      params[:tools] = tools.map { |t| convert_tool_to_chat_completions_format(t) }
+    end
+
+    if structured_output
+      params[:response_format] = {
+        type: "json_schema",
+        json_schema: {
+          name: "response",
+          schema: structured_output.json_schema(strict: true),
+          strict: true
+        }
+      }
+    end
+
+    params.compact
+  end
+
+  #--
+  #: (Hash[Symbol, untyped]) -> untyped
+  def execute_generate(params)
+    @client.chat.completions.create(**params)
+  end
+
+  #--
+  #: (untyped) -> Riffer::Providers::TokenUsage?
+  def extract_token_usage(response)
+    typed_response = response #: OpenAI::Models::Chat::ChatCompletion
+    usage = typed_response.usage
+    return nil unless usage
+
+    Riffer::Providers::TokenUsage.new(
+      input_tokens: usage.prompt_tokens,
+      output_tokens: usage.completion_tokens
+    )
+  end
+
+  #--
+  #: (untyped) -> String
+  def extract_content(response)
+    typed_response = response #: OpenAI::Models::Chat::ChatCompletion
+    typed_response.choices.first&.message&.content || ""
+  end
+
+  #--
+  #: (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
+  def extract_tool_calls(response)
+    typed_response = response #: OpenAI::Models::Chat::ChatCompletion
+    message = typed_response.choices.first&.message
+    return [] unless message
+
+    tool_calls = message.tool_calls
+    return [] if tool_calls.nil? || tool_calls.empty?
+
+    tool_calls.filter_map do |tc|
+      next unless tc.is_a?(::OpenAI::Models::Chat::ChatCompletionMessageFunctionToolCall)
+
+      Riffer::Messages::Assistant::ToolCall.new(
+        call_id: tc.id,
+        name: decode_tool_name(tc.function.name, tools: @current_tools),
+        arguments: tc.function.arguments
+      )
+    end
+  end
+
+  #--
+  #: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+  def execute_stream(params, yielder)
+    # OpenRouter omits usage from streams unless explicitly opted in.
+    stream_options = (params[:stream_options] || {}).merge(include_usage: true)
+    stream_params = params.merge(stream_options: stream_options)
+
+    state = {
+      text: +"",
+      reasoning: +"",
+      tool_calls: {}
+    } #: Hash[Symbol, untyped]
+
+    # Use stream_raw (not stream) — the latter yields a higher-level
+    # ChatChunkEvent helper that aggregates content/tool calls into typed
+    # events. We want raw ChatCompletionChunk objects with
+    # +choices.first.delta+ so we can map deltas to Riffer::StreamEvents
+    # ourselves.
+    stream = @client.chat.completions.stream_raw(**stream_params)
+    begin
+      stream.each do |chunk|
+        handle_stream_chunk(chunk, state: state, yielder: yielder)
+      end
+    ensure
+      # The OpenAI SDK does not auto-close the SSE socket on iteration
+      # interrupt, so close explicitly. Idempotent and a no-op after EOF.
+      stream.close
+    end
+
+    # Chat Completions has no per-tool terminal event, so flush any leftover
+    # tool calls here in case finish_reason is missing or not "tool_calls".
+    emit_tool_call_done_events(state: state, yielder: yielder) unless state[:tool_calls].empty?
+
+    yielder << Riffer::StreamEvents::TextDone.new(state[:text]) unless state[:text].empty?
+    yielder << Riffer::StreamEvents::ReasoningDone.new(state[:reasoning]) unless state[:reasoning].empty?
+  end
+
+  #--
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  def handle_stream_chunk(chunk, state:, yielder:)
+    typed_chunk = chunk #: OpenAI::Models::Chat::ChatCompletionChunk
+    choice = typed_chunk.choices&.first
+    delta = choice&.delta
+
+    if delta
+      handle_text_delta(delta, state: state, yielder: yielder)
+      handle_reasoning_delta(delta, state: state, yielder: yielder)
+      handle_tool_call_deltas(delta, state: state, yielder: yielder)
+    end
+
+    if choice && finish_reason_is_tool_calls?(choice)
+      emit_tool_call_done_events(state: state, yielder: yielder)
+    end
+
+    return unless typed_chunk.usage
+
+    yielder << Riffer::StreamEvents::TokenUsageDone.new(
+      token_usage: Riffer::Providers::TokenUsage.new(
+        input_tokens: typed_chunk.usage.prompt_tokens,
+        output_tokens: typed_chunk.usage.completion_tokens
+      )
+    )
+  end
+
+  #--
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  def handle_text_delta(delta, state:, yielder:)
+    typed_delta = delta #: OpenAI::Models::Chat::ChatCompletionChunk::Choice::Delta
+    content = typed_delta.content
+    return if content.nil? || content.empty?
+
+    state[:text] << content
+    yielder << Riffer::StreamEvents::TextDelta.new(content)
+  end
+
+  #--
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  def handle_reasoning_delta(delta, state:, yielder:)
+    # The openai gem's typed Delta model strips fields not in OpenAI's spec
+    # (so +delta.reasoning+ raises NoMethodError), but the underlying data
+    # hash retains them. Access via +#[]+ which reads from BaseModel#@data.
+    reasoning = delta[:reasoning] if delta.respond_to?(:[])
+    return if reasoning.nil? || reasoning.empty?
+
+    state[:reasoning] << reasoning
+    yielder << Riffer::StreamEvents::ReasoningDelta.new(reasoning)
+  end
+
+  #--
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  def handle_tool_call_deltas(delta, state:, yielder:)
+    typed_delta = delta #: OpenAI::Models::Chat::ChatCompletionChunk::Choice::Delta
+    tool_calls = typed_delta.tool_calls
+    return if tool_calls.nil? || tool_calls.empty?
+
+    tool_calls.each do |tc|
+      entry = state[:tool_calls][tc.index] ||= {id: nil, name: nil, arguments: +""}
+      entry[:id] = tc.id if tc.id
+
+      fn = tc.function
+      next unless fn
+
+      entry[:name] = decode_tool_name(fn.name, tools: @current_tools) if fn.name
+
+      args_delta = fn.arguments
+      next if args_delta.nil? || args_delta.empty?
+
+      entry[:arguments] << args_delta
+      yielder << Riffer::StreamEvents::ToolCallDelta.new(
+        item_id: entry[:id] || "tool_#{tc.index}",
+        name: entry[:name],
+        arguments_delta: args_delta
+      )
+    end
+  end
+
+  #--
+  #: (state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  def emit_tool_call_done_events(state:, yielder:)
+    state[:tool_calls].each do |index, entry|
+      fallback = "tool_#{index}"
+      yielder << Riffer::StreamEvents::ToolCallDone.new(
+        item_id: entry[:id] || fallback,
+        call_id: entry[:id] || fallback,
+        name: entry[:name],
+        arguments: entry[:arguments]
+      )
+    end
+    state[:tool_calls] = {}
+  end
+
+  #--
+  #: (untyped) -> bool
+  def finish_reason_is_tool_calls?(choice)
+    typed_choice = choice #: OpenAI::Models::Chat::ChatCompletionChunk::Choice
+    typed_choice.finish_reason.to_s == "tool_calls"
+  end
+
+  #--
+  #: (Array[Riffer::Messages::Base]) -> Array[Hash[Symbol, untyped]]
+  def convert_messages_to_chat_completions_format(messages)
+    messages.flat_map do |message|
+      case message
+      when Riffer::Messages::System
+        {role: "system", content: message.content}
+      when Riffer::Messages::User
+        if message.files.empty?
+          {role: "user", content: message.content}
+        else
+          content = [{type: "text", text: message.content}]
+          message.files.each { |file| content << convert_file_part_to_chat_completions_format(file) }
+          {role: "user", content: content}
+        end
+      when Riffer::Messages::Assistant
+        convert_assistant_to_chat_completions_format(message)
+      when Riffer::Messages::Tool
+        {role: "tool", tool_call_id: message.tool_call_id, content: message.content}
+      else
+        raise Riffer::ArgumentError, "unsupported message type: #{message.class}"
+      end
+    end
+  end
+
+  #--
+  #: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
+  def convert_assistant_to_chat_completions_format(message)
+    msg = {role: "assistant"} #: Hash[Symbol, untyped]
+    msg[:content] = message.content if message.content && !message.content.empty?
+
+    unless message.tool_calls.empty?
+      msg[:tool_calls] = message.tool_calls.map do |tc|
+        {
+          id: tc.call_id,
+          type: "function",
+          function: {
+            name: encode_tool_name(tc.name),
+            arguments: tc.arguments.is_a?(String) ? tc.arguments : tc.arguments.to_json
+          }
+        }
+      end
+    end
+
+    msg
+  end
+
+  #--
+  #: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  def convert_file_part_to_chat_completions_format(file)
+    if file.image?
+      image_url = file.url? ? file.url : "data:#{file.media_type};base64,#{file.data}"
+      {type: "image_url", image_url: {url: image_url}}
+    else
+      data_uri = "data:#{file.media_type};base64,#{file.data}"
+      block = {type: "file", file: {file_data: data_uri}} #: Hash[Symbol, untyped]
+      block[:file][:filename] = file.filename if file.filename
+      block
+    end
+  end
+
+  #--
+  #: (singleton(Riffer::Tool)) -> Hash[Symbol, untyped]
+  def convert_tool_to_chat_completions_format(tool)
+    {
+      type: "function",
+      function: {
+        name: encode_tool_name(tool.name),
+        description: tool.description,
+        parameters: tool.parameters_schema(strict: true),
+        strict: true
+      }
+    }
+  end
+end