llm_gateway 0.3.0 → 0.5.0

data/lib/llm_gateway/adapters/openai/chat_completions/input_mapper.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module LlmGateway
+  module Adapters
+    module OpenAI
+      module ChatCompletions
+        class InputMapper
+          def self.map(data)
+            {
+              messages: map_messages(data[:messages]),
+              tools: map_tools(data[:tools]),
+              system: map_system(data[:system])
+            }
+          end
+
+          def self.map_content(content)
+            content = { type: "text", text: content } unless content.is_a?(Hash)
+
+            case content[:type]
+            when "text"
+              map_text_content(content)
+            when "file"
+              map_file_content(content)
+            when "image"
+              map_image_content(content)
+            when "tool_use", "function"
+              map_tool_use_content(content)
+            when "tool_result"
+              map_tool_result_content(content)
+            else
+              content
+            end
+          end
+
+          class << self
+            private
+
+            def map_messages(messages)
+              return messages unless messages
+
+              mapped_messages = messages.map do |msg|
+                msg = msg.merge(role: "user") if msg[:role] == "developer"
+
+                content = if msg[:content].is_a?(Array)
+                  msg[:content].map { |content| map_content(content) }
+                else
+                  [ map_content(msg[:content]) ]
+                end
+
+                {
+                  role: msg[:role],
+                  content: content
+                }
+              end
+
+              mapped_messages.flat_map do |msg|
+                tool_calls = []
+                regular_content = []
+                tool_messages = []
+                msg[:content].each do |content|
+                  case content[:type] || content[:role]
+                  when "tool"
+                    tool_messages << content
+                  when "function"
+                    tool_calls << content
+                  else
+                    regular_content << content
+                  end
+                end
+                result = []
+
+                if tool_calls.any? || regular_content.any?
+                  main_msg = msg.dup
+                  main_msg[:role] = "assistant" if !main_msg[:role]
+                  main_msg[:tool_calls] = tool_calls if tool_calls.any?
+                  main_msg[:content] = regular_content.any? ? regular_content : nil
+                  result << main_msg
+                end
+
+                result + tool_messages
+              end
+            end
+
+            def map_tools(tools)
+              return tools unless tools
+
+              tools.map do |tool|
+                {
+                  type: "function",
+                  function: {
+                    name: tool[:name],
+                    description: tool[:description],
+                    parameters: tool[:input_schema]
+                  }
+                }
+              end
+            end
+
+            def map_system(system)
+              if !system || system.empty?
+                []
+              else
+                system.map do |msg|
+                  msg[:role] == "system" ? msg.merge(role: "developer") : msg
+                end
+              end
+            end
+
+            def map_text_content(content)
+              {
+                type: "text",
+                text: content[:text]
+              }
+            end
+
+            def map_file_content(content)
+              media_type = content[:media_type] == "text/plain" ? "application/pdf" : content[:media_type]
+              {
+                type: "file",
+                file: {
+                  filename: content[:name],
+                  file_data: "data:#{media_type};base64,#{Base64.encode64(content[:data])}"
+                }
+              }
+            end
+
+            def map_image_content(content)
+              {
+                type: "image_url",
+                image_url: {
+                  url: "data:#{content[:media_type]};base64,#{content[:data]}"
+                }
+              }
+            end
+
+            def map_tool_use_content(content)
+              {
+                id: content[:id],
+                type: "function",
+                function: {
+                  name: content[:name],
+                  arguments: content[:input].to_json
+                }
+              }
+            end
+
+            def map_tool_result_content(content)
+              mapped_content = content[:content]
+              if mapped_content.is_a?(Array)
+                mapped_content = mapped_content.map do |item|
+                  item.is_a?(Hash) ? map_content(item.transform_keys(&:to_sym)) : item
+                end
+              end
+
+              {
+                role: "tool",
+                tool_call_id: content[:tool_use_id],
+                content: mapped_content
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llm_gateway/adapters/openai/chat_completions/input_message_sanitizer.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "../../input_message_sanitizer"
+
+module LlmGateway
+  module Adapters
+    module OpenAI
+      module ChatCompletions
+        class InputMessageSanitizer < LlmGateway::Adapters::InputMessageSanitizer
+          def self.sanitize(messages, target_provider:, target_api:, target_model:)
+            sanitized = super
+            normalize_tool_call_ids(sanitized, target_provider: target_provider)
+          end
+
+          def self.normalize_tool_call_ids(messages, target_provider:)
+            return messages unless messages.is_a?(Array)
+
+            id_map = {}
+
+            messages.map do |message|
+              next message unless message.is_a?(Hash) && message[:content].is_a?(Array)
+
+              content = message[:content].map do |block|
+                next block unless block.is_a?(Hash)
+
+                type = block[:type] || block["type"]
+
+                case type
+                when "tool_use", "function"
+                  original_id = block[:id] || block["id"]
+                  normalized_id = normalize_tool_call_id(original_id, target_provider: target_provider)
+                  id_map[original_id] = normalized_id if original_id && normalized_id
+                  block.merge(id: normalized_id)
+                when "tool_result"
+                  original_tool_use_id = block[:tool_use_id] || block["tool_use_id"]
+                  normalized_tool_use_id = id_map[original_tool_use_id] || normalize_tool_call_id(original_tool_use_id, target_provider: target_provider)
+                  block.merge(tool_use_id: normalized_tool_use_id)
+                else
+                  block
+                end
+              end
+
+              message.merge(content: content)
+            end
+          end
+
+          def self.normalize_tool_call_id(id, target_provider:)
+            return id unless id.is_a?(String)
+
+            if id.include?("|")
+              call_id = id.split("|", 2).first
+              call_id.gsub(/[^a-zA-Z0-9_-]/, "_")[0, 40]
+            elsif target_provider == "openai"
+              id[0, 40]
+            else
+              id
+            end
+          end
+
+          private_class_method :normalize_tool_call_ids, :normalize_tool_call_id
+        end
+      end
+    end
+  end
+end

data/lib/llm_gateway/adapters/openai/chat_completions/option_mapper.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module LlmGateway
+  module Adapters
+    module OpenAI
+      module ChatCompletions
+        module OptionMapper
+          DEFAULT_MAX_COMPLETION_TOKENS = 20_480
+          VALID_REASONING_LEVELS = %w[low medium high xhigh].freeze
+
+          # Source: https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create/index.md
+          # API: OpenAI Chat Completions Create; accessed 2026-05-18.
+          # Body parameters listed by the API reference: messages, model, audio,
+          # frequency_penalty, function_call, functions, logit_bias, logprobs,
+          # max_completion_tokens, max_tokens, metadata, modalities, n,
+          # parallel_tool_calls, prediction, presence_penalty, prompt_cache_key,
+          # prompt_cache_retention, reasoning_effort, response_format,
+          # safety_identifier, seed, service_tier, stop, store, stream,
+          # stream_options, temperature, tool_choice, tools, top_logprobs, top_p,
+          # user, verbosity, web_search_options.
+          # This mapper intentionally excludes transcript/tool structural fields
+          # (messages, tools) from option handling.
+
+          VALID_OPTIONS = %i[
+            model
+            audio
+            frequency_penalty
+            function_call
+            functions
+            logit_bias
+            logprobs
+            max_completion_tokens
+            max_tokens
+            metadata
+            modalities
+            n
+            parallel_tool_calls
+            prediction
+            presence_penalty
+            prompt_cache_key
+            prompt_cache_retention
+            reasoning_effort
+            response_format
+            safety_identifier
+            seed
+            service_tier
+            stop
+            store
+            stream
+            stream_options
+            temperature
+            tool_choice
+            top_logprobs
+            top_p
+            user
+            verbosity
+            web_search_options
+          ].freeze
+
+          MANAGED_OPTIONS = %i[
+            reasoning
+            cache_key
+            cache_retention
+          ].freeze
+
+          module_function
+
+          def map(options)
+            mapped_options = options.reject { |key, _| MANAGED_OPTIONS.include?(key) }
+            mapped_options[:max_completion_tokens] = options[:max_completion_tokens] || DEFAULT_MAX_COMPLETION_TOKENS
+
+            cache_key = options[:cache_key]
+            mapped_options[:prompt_cache_key] = cache_key unless cache_key.nil?
+
+            cache_retention = options[:cache_retention]
+            mapped_options[:prompt_cache_retention] = normalize_cache_retention(cache_retention) \
+              unless cache_retention.nil?
+
+            if mapped_options[:prompt_cache_key] && !mapped_options[:prompt_cache_retention]
+              mapped_options[:prompt_cache_retention] = normalize_cache_retention("short")
+            end
+
+            if cache_retention.to_s == "none"
+              mapped_options.delete(:prompt_cache_key)
+              mapped_options.delete(:prompt_cache_retention)
+            end
+
+            reasoning = options[:reasoning]
+            mapped_options[:reasoning_effort] = normalize_reasoning_effort(reasoning) \
+              unless reasoning.nil? || reasoning.to_s == "none"
+
+            validate_options!(mapped_options)
+            mapped_options
+          end
+
+          def validate_options!(mapped_options)
+            unknown_options = mapped_options.keys - VALID_OPTIONS
+            return if unknown_options.empty?
+
+            raise ArgumentError,
+                  "Unknown OpenAI Chat Completions options: #{unknown_options.join(', ')}. " \
+                  "Valid options: #{VALID_OPTIONS.join(', ')}."
+          end
+
+          def normalize_cache_retention(cache_retention)
+            case cache_retention.to_s
+            when "short"
+              "in_memory"
+            when "long"
+              "24h"
+            when "none"
+              nil
+            else
+              raise ArgumentError,
+                    "Invalid cache_retention '#{cache_retention}'. Use 'short', 'long', or 'none'."
+            end
+          end
+
+          def normalize_reasoning_effort(reasoning)
+            effort = reasoning.to_s
+            return effort if VALID_REASONING_LEVELS.include?(effort)
+
+            raise ArgumentError, "Invalid reasoning '#{reasoning}'. Use 'none', 'low', 'medium', 'high', or 'xhigh'."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llm_gateway/adapters/openai/chat_completions/stream_mapper.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require_relative "../../stream_mapper"
+
+module LlmGateway
+  module Adapters
+    module OpenAI
+      module ChatCompletions
+        class StreamMapper < LlmGateway::Adapters::StreamMapper
+          def map(chunk, &block)
+            data = chunk[:data] || {}
+            raise_stream_error!(data) if chunk[:event] == "error" || data[:error] || data[:type] == "error"
+
+            push_patches(patches_for(data), &block)
+          end
+
+          private
+
+          def patches_for(data)
+            choices = data[:choices] || []
+            return final_usage_patches(data) if choices.empty?
+
+            choice = choices.first || {}
+            delta = choice[:delta] || {}
+            patches = []
+            active_block_type = accumulator.active_block_type
+            active_tool = active_tool_block
+
+            append_patches(patches, message_start_patches(data, delta))
+
+            active_block_type, active_tool = append_patches(
+              patches,
+              reasoning_patches(delta[:reasoning], active_block_type:),
+              active_block_type,
+              active_tool
+            )
+            active_block_type, active_tool = append_patches(
+              patches,
+              text_patches(delta[:content], active_block_type:),
+              active_block_type,
+              active_tool
+            )
+            delta.fetch(:tool_calls, []).each do |tool_call|
+              active_block_type, active_tool = append_patches(
+                patches,
+                patches_for_tool_call(tool_call, active_block_type:, active_tool:),
+                active_block_type,
+                active_tool
+              )
+            end
+            append_patches(patches, finish_patches(choice[:finish_reason], active_block_type:))
+
+            patches
+          end
+
+          def append_patches(patches, new_patches, active_block_type = nil, active_tool = nil)
+            patches.concat(new_patches)
+
+            new_patches.each do |patch|
+              case patch[:type]
+              when :text_start
+                active_block_type = :text
+                active_tool = nil
+              when :reasoning_start
+                active_block_type = :reasoning
+                active_tool = nil
+              when :tool_start
+                active_block_type = :tool
+                active_tool = { id: patch[:id], name: patch[:name] }
+              when :text_end, :reasoning_end, :tool_end
+                active_block_type = nil
+                active_tool = nil
+              end
+            end
+
+            [ active_block_type, active_tool ]
+          end
+
+          def message_start_patches(data, delta)
+            return [] unless accumulator.message_hash.empty?
+
+            return [] unless delta.key?(:role) ||
+                             data[:id] ||
+                             data[:model] ||
+                             delta[:content] ||
+                             delta[:reasoning] ||
+                             delta[:tool_calls]&.any?
+
+            [
+              {
+                type: :message_start,
+                delta: {
+                  id: data[:id],
+                  model: data[:model],
+                  role: delta[:role] || "assistant"
+                }.compact,
+                usage_increment: {}
+              }
+            ]
+          end
+
+          # Groq exposes OpenAI-compatible chat completion chunks, but may include
+          # `delta.reasoning` before normal `delta.content`.
+          def reasoning_patches(reasoning, active_block_type: accumulator.active_block_type)
+            return [] if reasoning.to_s.empty?
+
+            [
+              *close_active_non_reasoning_patches(active_block_type:),
+              {
+                type: active_block_type == :reasoning ? :reasoning_delta : :reasoning_start,
+                delta: reasoning,
+                signature: ""
+              }
+            ]
+          end
+
+          def text_patches(content, active_block_type: accumulator.active_block_type)
+            return [] if content.to_s.empty?
+
+            [
+              *close_active_non_text_patches(active_block_type:),
+              {
+                type: active_block_type == :text ? :text_delta : :text_start,
+                delta: content
+              }
+            ]
+          end
+
+          def patches_for_tool_call(tool_call, active_block_type: accumulator.active_block_type, active_tool: active_tool_block)
+            id = tool_call[:id]
+            name = tool_call.dig(:function, :name)
+            arguments = tool_call.dig(:function, :arguments).to_s
+
+            patches = []
+
+            if id || name
+              if active_block_type == :tool
+                patches.concat(close_active_block_patches(active_block_type:)) if new_active_tool?(id, name, active_tool:)
+              else
+                patches.concat(close_active_non_tool_patches(active_block_type:))
+              end
+
+              unless active_block_type == :tool && patches.empty?
+                patches << {
+                  type: :tool_start,
+                  delta: "",
+                  id: id,
+                  name: name
+                }
+              end
+            end
+
+            patches << { type: :tool_delta, delta: arguments } unless arguments.empty?
+            patches
+          end
+
+          def new_active_tool?(id, name, active_tool: active_tool_block)
+            return true unless active_tool
+
+            (id && active_tool[:id] != id) || (name && active_tool[:name] != name)
+          end
+
+          def active_tool_block
+            return nil unless accumulator.active_tool?
+
+            accumulator.blocks.reverse.find { |block| block&.fetch(:type, nil) == "tool_use" }
+          end
+
+          def close_active_block_patches(active_block_type: accumulator.active_block_type)
+            case active_block_type
+            when :text
+              [ { type: :text_end, delta: "" } ]
+            when :reasoning
+              [ { type: :reasoning_end, delta: "", signature: "" } ]
+            when :tool
+              [ { type: :tool_end, delta: "" } ]
+            else
+              []
+            end
+          end
+
+          def close_active_non_text_patches(active_block_type: accumulator.active_block_type)
+            active_block_type == :text ? [] : close_active_block_patches(active_block_type:)
+          end
+
+          def close_active_non_reasoning_patches(active_block_type: accumulator.active_block_type)
+            active_block_type == :reasoning ? [] : close_active_block_patches(active_block_type:)
+          end
+
+          def close_active_non_tool_patches(active_block_type: accumulator.active_block_type)
+            active_block_type == :tool ? [] : close_active_block_patches(active_block_type:)
+          end
+
+          def finish_patches(finish_reason, active_block_type: accumulator.active_block_type)
+            return [] unless finish_reason
+
+            [
+              *close_active_block_patches(active_block_type:),
+              {
+                type: :message_delta,
+                delta: { stop_reason: normalize_stop_reason(finish_reason) },
+                usage_increment: {}
+              }
+            ]
+          end
+
+          def final_usage_patches(data)
+            [
+              {
+                type: accumulator.message_hash.empty? ? :message_start : :message_delta,
+                delta: {},
+                usage_increment: usage_increment(data)
+              }
+            ]
+          end
+
+          def usage_increment(data)
+            usage = data[:usage] || {}
+
+            {
+              input_tokens: usage[:prompt_tokens] || 0,
+              cache_creation_input_tokens: 0,
+              cache_read_input_tokens: usage.dig(:prompt_tokens_details, :cached_tokens) || 0,
+              output_tokens: usage[:completion_tokens] || 0,
+              reasoning_tokens: usage.dig(:completion_tokens_details, :reasoning_tokens) || 0
+            }
+          end
+
+          def normalize_stop_reason(finish_reason)
+            case finish_reason
+            when "tool_calls"
+              "tool_use"
+            else
+              finish_reason
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llm_gateway/adapters/openai/chat_completions_adapter.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "../adapter"
+require_relative "acts_like_chat_completions"
+require_relative "chat_completions/input_mapper"
+require_relative "chat_completions/input_message_sanitizer"
+require_relative "chat_completions/option_mapper"
+require_relative "file_output_mapper"
+require_relative "chat_completions/stream_mapper"
+
+module LlmGateway
+  module Adapters
+    module OpenAI
+      class ChatCompletionsAdapter < Adapter
+        include ActsLikeOpenAIChatCompletions
+      end
+    end
+  end
+end

data/lib/llm_gateway/adapters/{open_ai → openai}/file_output_mapper.rb

@@ -2,7 +2,7 @@
 
 module LlmGateway
   module Adapters
-    module OpenAi
+    module OpenAI
       class FileOutputMapper
         def self.map(data)
           bytes = data.delete(:bytes)

data/lib/llm_gateway/adapters/openai/prompt_cache_option_mapper.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module LlmGateway
+  module Adapters
+    module OpenAI
+      module PromptCacheOptionMapper
+        def self.included(base)
+          base.extend(self)
+        end
+
+        def map_cache_key!(mapped_options)
+          cache_key = mapped_options.delete(:cache_key)
+          mapped_options.delete(:prompt_cache_key)
+          mapped_options[:prompt_cache_key] = cache_key unless cache_key.nil?
+        end
+
+        def map_prompt_cache_retention!(mapped_options)
+          retention = mapped_options.delete(:cache_retention)
+          mapped_options.delete(:prompt_cache_retention)
+          retention ||= "short" if mapped_options.key?(:prompt_cache_key)
+
+          case retention&.to_s
+          when nil
+            nil
+          when "short"
+            mapped_options[:prompt_cache_retention] = "in_memory"
+          when "long"
+            mapped_options[:prompt_cache_retention] = "24h"
+          when "none"
+            mapped_options.delete(:prompt_cache_key)
+          else
+            raise ArgumentError,
+              "Invalid cache_retention '#{retention}'. Use 'short', 'long', or 'none'."
+          end
+        end
+      end
+    end
+  end
+end