llm_gateway 0.2.0 → 0.4.0

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module LlmGateway
+  module Adapters
+    module OpenAI
+      module ChatCompletions
+        module OptionMapper
+          include LlmGateway::Adapters::OpenAI::PromptCacheOptionMapper
+
+          VALID_REASONING_LEVELS = %w[low medium high xhigh].freeze
+
+          module_function
+
+          def map(options)
+            mapped_options = options.dup
+            mapped_options[:max_completion_tokens] ||= 20_480
+
+            map_cache_key!(mapped_options)
+            map_prompt_cache_retention!(mapped_options)
+
+            return mapped_options unless mapped_options.key?(:reasoning)
+
+            reasoning = mapped_options.delete(:reasoning)
+            return mapped_options if reasoning.nil? || reasoning.to_s == "none"
+
+            mapped_options.merge(reasoning_effort: normalize_reasoning_effort(reasoning))
+          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/output_mapper.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module LlmGateway
+  module Adapters
+    module OpenAI
+      module ChatCompletions
+        class OutputMapper
+        def self.map(data)
+          {
+            id: data[:id],
+            model: data[:model],
+            usage: data[:usage],
+            choices: map_choices(data[:choices])
+          }
+        end
+
+        private
+
+        def self.map_choices(choices)
+          return [] unless choices
+          message_mapper = BidirectionalMessageMapper.new(LlmGateway::DIRECTION_OUT)
+
+          choices.map do |choice|
+            message = choice[:message] || {}
+            content_item = message_mapper.map_content(message[:content])
+            tool_calls = message[:tool_calls] ? message[:tool_calls].map { |tool_call| message_mapper.map_content(tool_call) } : []
+
+            # Only include content_item if it has actual text content
+            content_array = []
+            content_array << content_item if LlmGateway::Utils.present?(content_item[:text])
+            content_array += tool_calls
+
+            { role: message[:role], content: content_array }
+          end
+        end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require_relative "../../structs"
+
+module LlmGateway
+  module Adapters
+    module OpenAI
+      module ChatCompletions
+        class StreamMapper
+          def map(chunk)
+            queued_event = shift_queued_event
+            return queued_event if queued_event
+
+            data = chunk[:data] || {}
+            raise_stream_error!(data) if chunk[:event] == "error" || data[:error] || data[:type] == "error"
+
+            choices = data[:choices] || []
+
+            if choices.empty?
+              return message_event(
+                delta: pending_finish_delta,
+                usage_increment: usage_increment(data)
+              )
+            end
+
+            choice = choices.first || {}
+            delta = choice[:delta] || {}
+            finish_reason = choice[:finish_reason]
+
+            event = map_choice_delta(data, choice, delta)
+            return event if event
+
+            return finish_event_for(finish_reason) if finish_reason
+
+            nil
+          end
+
+          private
+
+          def map_choice_delta(data, choice, delta)
+            if !message_started? && delta[:tool_calls]&.any?
+              @message_started = true
+              stash_message_attributes(data, delta)
+              return tool_event(delta[:tool_calls].first)
+            end
+
+            if !message_started? && (delta.key?(:role) || data[:id] || data[:model])
+              @message_started = true
+              return AssistantStreamMessageEvent.new(
+                type: :message_start,
+                delta: {
+                  id: data[:id],
+                  model: data[:model],
+                  role: delta[:role]
+                }.compact,
+                usage_increment: {}
+              )
+            end
+
+            if (content = delta[:content]) && !content.empty?
+              return text_event(content, choice[:index] || 0)
+            end
+
+            return tool_event(delta[:tool_calls].first) if delta[:tool_calls]&.any?
+
+            nil
+          end
+
+          def finish_event_for(finish_reason)
+            normalized = normalize_stop_reason(finish_reason)
+            stash_pending_finish_delta(stop_reason: normalized)
+
+            case normalized
+            when "tool_use"
+              AssistantStreamEvent.new(type: :tool_end, content_index: last_started_tool_index || 0, delta: "")
+            else
+              AssistantStreamEvent.new(type: :text_end, content_index: last_started_text_index || 0, delta: "")
+            end
+          end
+
+          def message_event(delta:, usage_increment: {})
+            AssistantStreamMessageEvent.new(
+              type: pending_message_attributes.empty? ? :message_delta : :message_start,
+              delta: pending_message_attributes.merge(delta),
+              usage_increment:
+            ).tap do
+              clear_pending_message_attributes
+              clear_pending_finish_delta
+            end
+          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 text_event(content, content_index)
+            @last_started_text_index = content_index
+
+            if started_text_blocks.include?(content_index)
+              AssistantStreamEvent.new(type: :text_delta, content_index:, delta: content)
+            else
+              started_text_blocks << content_index
+              AssistantStreamEvent.new(type: :text_start, content_index:, delta: content)
+            end
+          end
+
+          def tool_event(tool_call)
+            tool_index = tool_call[:index] || 0
+            @last_started_tool_index = tool_index
+            function = tool_call[:function] || {}
+            arguments = function[:arguments] || ""
+
+            unless started_tool_blocks.include?(tool_index)
+              pending_tool_calls[tool_index] = merge_tool_call(pending_tool_calls[tool_index], tool_call)
+              pending = pending_tool_calls[tool_index]
+
+              return nil unless pending[:id] && pending.dig(:function, :name)
+
+              started_tool_blocks << tool_index
+              return AssistantToolStartEvent.new(
+                type: :tool_start,
+                content_index: tool_index,
+                delta: "",
+                id: pending[:id],
+                name: pending.dig(:function, :name)
+              )
+            end
+
+            AssistantStreamEvent.new(type: :tool_delta, content_index: tool_index, delta: arguments)
+          end
+
+          def stash_message_attributes(data, delta)
+            @pending_message_attributes = {
+              id: data[:id],
+              model: data[:model],
+              role: delta[:role]
+            }.compact
+          end
+
+          def pending_message_attributes
+            @pending_message_attributes ||= {}
+          end
+
+          def clear_pending_message_attributes
+            @pending_message_attributes = {}
+          end
+
+          def stash_pending_finish_delta(delta)
+            @pending_finish_delta = pending_finish_delta.merge(delta)
+          end
+
+          def pending_finish_delta
+            @pending_finish_delta ||= {}
+          end
+
+          def clear_pending_finish_delta
+            @pending_finish_delta = {}
+          end
+
+          def merge_tool_call(existing, incoming)
+            existing ||= {}
+            incoming ||= {}
+
+            existing_function = existing[:function] || {}
+            incoming_function = incoming[:function] || {}
+
+            {
+              index: incoming[:index] || existing[:index],
+              id: incoming[:id] || existing[:id],
+              type: incoming[:type] || existing[:type],
+              function: {
+                name: incoming_function[:name] || existing_function[:name],
+                arguments: "#{existing_function[:arguments]}#{incoming_function[:arguments]}"
+              }
+            }
+          end
+
+          def normalize_stop_reason(finish_reason)
+            case finish_reason
+            when "tool_calls"
+              "tool_use"
+            else
+              finish_reason
+            end
+          end
+
+          def message_started?
+            @message_started ||= false
+          end
+
+          def started_text_blocks
+            @started_text_blocks ||= []
+          end
+
+          def started_tool_blocks
+            @started_tool_blocks ||= []
+          end
+
+          def pending_tool_calls
+            @pending_tool_calls ||= {}
+          end
+
+          def last_started_text_index
+            @last_started_text_index
+          end
+
+          def last_started_tool_index
+            @last_started_tool_index
+          end
+
+          def shift_queued_event
+            queued_events.shift
+          end
+
+          def queued_events
+            @queued_events ||= []
+          end
+
+          def raise_stream_error!(data)
+            error = data[:error].is_a?(Hash) ? data[:error] : data
+            message = error[:message] || "Stream error"
+            code = error[:code] || error[:type]
+
+            if LlmGateway::Errors.context_overflow_message?(message)
+              raise LlmGateway::Errors::PromptTooLong.new(message, code)
+            end
+
+            raise LlmGateway::Errors::APIStatusError.new(message, code)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# 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/output_mapper"
+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/openai/file_output_mapper.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module LlmGateway
+  module Adapters
+    module OpenAI
+      class FileOutputMapper
+        def self.map(data)
+          bytes = data.delete(:bytes)
+          data.delete(:object) # Didnt see much value in this only option is "file"
+          data.delete(:status) # Deprecated so no need to pull through
+          data.delete(:status_details)  # Deprecated so no need to pull through
+          created_at = data.delete(:created_at)
+          time = Time.at(created_at, in: "UTC")
+          iso_format = time.iso8601(6)
+          data.merge(
+            size_bytes: bytes,
+            downloadable: data[:purpose] != "user_data",
+            mime_type: nil,
+            created_at: iso_format # Claude api format, easier for human reading so kept it this way
+          )
+        end
+      end
+    end
+  end
+end

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

data/lib/llm_gateway/adapters/openai/responses/bidirectional_message_mapper.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module LlmGateway
+  module Adapters
+    module OpenAI
+      module Responses
+        class BidirectionalMessageMapper < OpenAI::ChatCompletions::BidirectionalMessageMapper
+          def map_content(content)
+            # Convert string content to text format
+            #
+
+            content = { type: "text", text: content } unless content.is_a?(Hash)
+            case content[:type]
+            when "text"
+              map_text_content(content)
+            when "image"
+              map_image_content(content)
+            when "message"
+              map_messages(content)
+            when "output_text"
+              map_output_text_content(content)
+            when "tool_use"
+              map_tool_use_content(content)
+            when "function_call"
+              map_tool_use_content(content)
+            when "tool_result"
+              map_tool_result_content(content)
+            when "reasoning"
+              map_reasoning_content(content)
+            else
+              content
+            end
+          end
+
+        private
+
+          def map_messages(message)
+            message[:content].map { |content| map_content(content) }
+          end
+
+          def map_tool_result_content(content)
+            output = content[:content]
+            if output.is_a?(Array)
+              output = output.map do |item|
+                if item.is_a?(Hash)
+                  map_content(item.transform_keys(&:to_sym))
+                else
+                  item
+                end
+              end
+            end
+
+            {
+              "type": "function_call_output",
+              "call_id": content[:tool_use_id],
+              "output": output
+            }
+          end
+
+          def map_tool_use_content(content)
+            if direction == LlmGateway::DIRECTION_OUT
+              { id: content[:call_id], type: "tool_use", name: content[:name], input: parse_tool_arguments(content[:arguments]) }
+            else
+              { id: content[:id] }
+            end
+          end
+
+          def map_output_text_content(content)
+            {
+              type: direction == LlmGateway::DIRECTION_IN ? "input_text" : "text",
+              text: content[:text]
+            }
+          end
+
+          def map_reasoning_content(content)
+            if direction == LlmGateway::DIRECTION_IN
+              return { id: content[:id] } if content[:id]
+
+              content
+            else
+              {
+                type: "reasoning",
+                reasoning: normalize_reasoning_text(content[:summary]),
+                signature: content[:signature]
+              }
+            end
+          end
+
+          def map_image_content(content)
+            {
+              type: "input_image",
+              image_url: "data:#{content[:media_type]};base64,#{content[:data]}"
+            }
+          end
+
+          def map_text_content(content)
+            {
+              type: "input_text",
+              text: content[:text]
+            }
+          end
+
+          def normalize_reasoning_text(summary)
+            return summary if summary.is_a?(String)
+            return nil unless summary.is_a?(Array)
+            return nil if summary.empty?
+
+            summary.filter_map do |item|
+              next item if item.is_a?(String)
+
+              item[:text] || item[:summary_text] || item[:reasoning]
+            end.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "base64"
+require_relative "bidirectional_message_mapper"
+
+module LlmGateway
+  module Adapters
+    module OpenAI
+      module Responses
+        class InputMapper < OpenAI::ChatCompletions::InputMapper
+          def self.message_mapper
+            BidirectionalMessageMapper.new(LlmGateway::DIRECTION_IN)
+          end
+
+          def self.map_tools(tools)
+            return tools unless tools
+            mapper = message_mapper
+
+            tools.map do |tool|
+              mapped_tool = {
+                type: "function",
+                name: tool[:name],
+                description: tool[:description],
+                parameters: tool[:input_schema]
+              }
+
+              [ :contents, :content ].each do |key|
+                next unless tool[key].is_a?(Array)
+
+                mapped_tool[key] = tool[key].map do |entry|
+                  entry.is_a?(Hash) ? mapper.map_content(entry.transform_keys(&:to_sym)) : entry
+                end
+              end
+
+              mapped_tool
+            end
+          end
+
+          def self.map_messages(messages)
+            return messages unless messages
+            mapper = message_mapper
+
+            messages.flat_map do |msg|
+              if msg[:id] && msg[:content].is_a?(Array)
+                # Full AssistantMessage#to_h — expand content for stateless multi-turn
+                map_assistant_history_message(msg)
+              elsif msg[:id]
+                # Bare item-reference (e.g. manually constructed { id: "item_xxx" })
+                msg.slice(:id)
+              else
+                content = if msg[:content].is_a?(Array)
+                    msg[:content].map do |content|
+                      mapper.map_content(content)
+                    end
+                else
+                  [ mapper.map_content(msg[:content]) ]
+                end
+                if msg.dig(:content).is_a?(Array) && msg.dig(:content, 0, :type) == "tool_result"
+                  content
+                else
+                  {
+                    role: msg[:role],
+                    content: content
+                  }
+                end
+              end
+            end
+          end
+
+          # Map a full AssistantMessage#to_h into Responses API input items for
+          # stateless multi-turn conversations.
+          #
+          #   text blocks   → { role: "assistant", content: [{ type: "output_text", ... }] }
+          #   tool_use blocks → top-level function_call items
+          #   thinking blocks → omitted (model handles reasoning internally)
+          def self.map_assistant_history_message(msg)
+            blocks = (msg[:content] || []).map { |b| b.transform_keys(&:to_sym) }
+
+            text_blocks     = blocks.select { |b| b[:type] == "text" }
+            tool_use_blocks = blocks.select { |b| b[:type] == "tool_use" }
+
+            result = []
+
+            if text_blocks.any?
+              result << {
+                role: "assistant",
+                content: text_blocks.map { |b| { type: "output_text", text: b[:text] } }
+              }
+            end
+
+            tool_use_blocks.each do |b|
+              result << {
+                type: "function_call",
+                call_id: b[:id],
+                name: b[:name],
+                arguments: b[:input].is_a?(Hash) ? b[:input].to_json : (b[:input] || {}).to_json
+              }
+            end
+
+            result
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module LlmGateway
+  module Adapters
+    module OpenAI
+      module Responses
+        module OptionMapper
+          include LlmGateway::Adapters::OpenAI::PromptCacheOptionMapper
+
+          VALID_REASONING_LEVELS = %w[low medium high xhigh].freeze
+
+          module_function
+
+          def map(options)
+            mapped_options = options.dup
+
+            max_completion_tokens = mapped_options.delete(:max_completion_tokens)
+            mapped_options[:max_output_tokens] = max_completion_tokens || mapped_options[:max_output_tokens] || 20_480
+
+            map_cache_key!(mapped_options)
+            map_prompt_cache_retention!(mapped_options)
+
+            return mapped_options unless mapped_options.key?(:reasoning)
+
+            reasoning = mapped_options.delete(:reasoning)
+            return mapped_options if reasoning.nil? || reasoning.to_s == "none"
+
+            mapped_options.merge(reasoning: normalize_reasoning(reasoning))
+          end
+
+          def normalize_reasoning(reasoning)
+            effort = reasoning.to_s
+            return { effort: effort, summary: "detailed" } if VALID_REASONING_LEVELS.include?(effort)
+
+            raise ArgumentError, "Invalid reasoning '#{reasoning}'. Use 'none', 'low', 'medium', 'high', or 'xhigh'."
+          end
+        end
+      end
+    end
+  end
+end