llm_gateway 0.3.0 → 0.5.0

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

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module LlmGateway
+  module Adapters
+    module OpenAI
+      module Responses
+        class InputMapper < OpenAI::ChatCompletions::InputMapper
+          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 "image"
+              map_image_content(content)
+            when "message"
+              map_messages_content(content)
+            when "output_text"
+              map_output_text_content(content)
+            when "tool_use", "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
+
+          class << self
+            private
+
+            def map_tools(tools)
+              return tools unless tools
+
+              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) ? map_content(entry.transform_keys(&:to_sym)) : entry
+                  end
+                end
+
+                mapped_tool
+              end
+            end
+
+            def map_messages(messages)
+              return messages unless messages
+
+              messages.flat_map do |msg|
+                if msg[:id] && msg[:content].is_a?(Array)
+                  map_assistant_history_message(msg)
+                elsif msg[:id]
+                  msg.slice(:id)
+                else
+                  content = if msg[:content].is_a?(Array)
+                    msg[:content].map { |content| map_content(content) }
+                  else
+                    [ 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
+
+            def 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
+
+            def map_messages_content(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|
+                  item.is_a?(Hash) ? map_content(item.transform_keys(&:to_sym)) : item
+                end
+              end
+
+              {
+                type: "function_call_output",
+                call_id: content[:tool_use_id],
+                output: output
+              }
+            end
+
+            def map_tool_use_content(content)
+              { id: content[:id] }
+            end
+
+            def map_output_text_content(content)
+              {
+                type: "input_text",
+                text: content[:text]
+              }
+            end
+
+            def map_reasoning_content(content)
+              return { id: content[:id] } if content[:id]
+
+              content
+            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
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module LlmGateway
+  module Adapters
+    module OpenAI
+      module Responses
+        module OptionMapper
+          DEFAULT_MAX_OUTPUT_TOKENS = 20_480
+          VALID_REASONING_LEVELS = %w[low medium high xhigh].freeze
+
+          # Source: https://developers.openai.com/api/reference/resources/responses/methods/create/index.md
+          # API: OpenAI Responses Create; accessed 2026-05-18.
+          # Body parameters listed by the API reference: background,
+          # context_management, conversation, include, input, instructions,
+          # max_output_tokens, max_tool_calls, metadata, model,
+          # parallel_tool_calls, previous_response_id, prompt, prompt_cache_key,
+          # prompt_cache_retention, reasoning, safety_identifier, service_tier,
+          # store, stream, stream_options, temperature, text, tool_choice, tools,
+          # top_logprobs, top_p, truncation, user.
+          # This mapper intentionally excludes transcript/tool/system structural
+          # fields (input, instructions, tools) from option handling.
+          VALID_OPTIONS = %i[
+            background
+            context_management
+            conversation
+            include
+            max_output_tokens
+            max_tool_calls
+            metadata
+            model
+            parallel_tool_calls
+            previous_response_id
+            prompt
+            prompt_cache_key
+            prompt_cache_retention
+            reasoning
+            safety_identifier
+            service_tier
+            store
+            stream
+            stream_options
+            temperature
+            text
+            tool_choice
+            top_logprobs
+            top_p
+            truncation
+            user
+          ].freeze
+
+          MANAGED_OPTIONS = %i[
+            max_completion_tokens
+            response_format
+            cache_key
+            cache_retention
+          ].freeze
+
+          module_function
+
+          def map(options)
+            mapped_options = options.reject { |key, _| MANAGED_OPTIONS.include?(key) }
+            mapped_options[:max_output_tokens] = options[:max_completion_tokens] || options[:max_output_tokens] || DEFAULT_MAX_OUTPUT_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
+
+            response_format = options[:response_format]
+            mapped_options[:text] = text_with_response_format(mapped_options[:text], response_format) unless response_format.nil?
+
+            reasoning = mapped_options.delete(:reasoning)
+            mapped_options[:reasoning] = normalize_reasoning(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 Responses 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(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
+
+          def text_with_response_format(text, response_format)
+            text_options = text ? text.dup : {}
+            text_options[:format] = response_format.is_a?(String) ? { type: response_format } : response_format
+            text_options
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require_relative "../../stream_mapper"
+
+module LlmGateway
+  module Adapters
+    module OpenAI
+      module Responses
+        class StreamMapper < LlmGateway::Adapters::StreamMapper
+          def map(chunk, &block)
+            event_type = chunk[:event]
+            data = chunk[:data] || {}
+            raise_stream_error!(data) if event_type == "error" || data[:error] || data[:type] == "error"
+
+            push_patches(patches_for(event_type, data), &block)
+          end
+
+          private
+
+          def patches_for(event_type, data)
+            case event_type
+            when "response.created"
+              response_created_patches(data[:response])
+            when "response.output_item.added"
+              output_item_added_patches(data)
+            when "response.content_part.added"
+              content_part_added_patches(data)
+            when "response.content_part.done"
+              content_part_done_patches(data)
+            when "response.output_text.delta"
+              [ { type: :text_delta, delta: data[:delta] || "" } ]
+            when "response.function_call_arguments.delta"
+              [ { type: :tool_delta, delta: data[:delta] || "" } ]
+            when "response.function_call_arguments.done"
+              [ { type: :tool_end, delta: "" } ]
+            when "response.reasoning_summary_part.added"
+              [ { type: :reasoning_start, delta: "", signature: "" } ]
+            when "response.reasoning_summary_text.delta"
+              [ { type: :reasoning_delta, delta: data[:delta] || "", signature: "" } ]
+            when "response.reasoning_summary_part.done"
+              [ { type: :reasoning_end, delta: "", signature: "" } ]
+            when "response.completed"
+              response_completed_patches(data[:response])
+            else
+              []
+            end
+          end
+
+          def response_created_patches(response)
+            response ||= {}
+
+            [
+              {
+                type: :message_start,
+                delta: {
+                  id: response[:id],
+                  model: response[:model],
+                  role: "assistant"
+                }.compact,
+                usage_increment: {}
+              }
+            ]
+          end
+
+          def output_item_added_patches(data)
+            item = data[:item] || {}
+
+            case item[:type]
+            when "message"
+              return [] unless accumulator.message_hash.empty?
+
+              [
+                {
+                  type: :message_start,
+                  delta: { role: item[:role] || "assistant" },
+                  usage_increment: {}
+                }
+              ]
+            when "function_call"
+              [
+                {
+                  type: :tool_start,
+                  delta: "",
+                  id: item[:call_id] || item[:id],
+                  name: item[:name]
+                }
+              ]
+            else
+              []
+            end
+          end
+
+          def content_part_added_patches(data)
+            part = data[:part] || {}
+            return [] unless part[:type] == "output_text"
+
+            [ { type: :text_start, delta: "" } ]
+          end
+
+          def content_part_done_patches(data)
+            part = data[:part] || {}
+            return [] unless part.empty? || part[:type] == "output_text"
+
+            [ { type: :text_end, delta: "" } ]
+          end
+
+          def response_completed_patches(response)
+            response ||= {}
+
+            [
+              {
+                type: accumulator.message_hash.empty? ? :message_start : :message_delta,
+                delta: {
+                  id: response[:id],
+                  model: response[:model],
+                  role: "assistant",
+                  stop_reason: stop_reason_for(response)
+                }.compact,
+                usage_increment: usage_increment(response)
+              }
+            ]
+          end
+
+          def usage_increment(response)
+            usage = response[:usage] || {}
+
+            {
+              input_tokens: usage[:input_tokens] || 0,
+              cache_creation_input_tokens: 0,
+              cache_read_input_tokens: usage.dig(:input_tokens_details, :cached_tokens) || 0,
+              output_tokens: usage[:output_tokens] || 0,
+              reasoning_tokens: usage.dig(:output_tokens_details, :reasoning_tokens) || 0
+            }
+          end
+
+          def stop_reason_for(response)
+            output = response[:output] || []
+            last_item = output.last || {}
+
+            tool_seen? || last_item[:type] == "function_call" ? "tool_use" : "stop"
+          end
+
+          def tool_seen?
+            accumulator.blocks.any? { |content_block| content_block && content_block[:type] == "tool_use" }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "../adapter"
+require_relative "acts_like_responses"
+require_relative "../input_message_sanitizer"
+require_relative "responses/input_mapper"
+require_relative "responses/option_mapper"
+require_relative "file_output_mapper"
+require_relative "responses/stream_mapper"
+
+module LlmGateway
+  module Adapters
+    module OpenAI
+      class ResponsesAdapter < Adapter
+        include ActsLikeOpenAIResponses
+      end
+    end
+  end
+end

data/lib/llm_gateway/adapters/openai_codex/input_mapper.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../openai/responses/input_mapper"
+
+module LlmGateway
+  module Adapters
+    module OpenAICodex
+      # Custom input mapper for the Codex backend.
+      #
+      # The Codex Responses endpoint rejects several content block types that
+      # the standard OpenAI Responses InputMapper passes through:
+      #   - "reasoning" and "summary_text" blocks are never accepted as input.
+      #   - "thinking" blocks are only valid when they carry an encrypted
+      #     `signature`; unsigned thinking blocks must be dropped.
+      #
+      # Additional normalisation:
+      #   - Tool-result output is coerced to recognised Responses input types
+      #     (input_text / input_image).
+      #   - Assistant text content is always sent as "output_text" (not
+      #     "input_text") because Codex is strict about directionality.
+      #   - function_call / tool_use blocks inside an assistant turn are
+      #     promoted to top-level function_call items so that Codex can match
+      #     them against the subsequent function_call_output items.
+      class InputMapper < OpenAI::Responses::InputMapper
+        def self.map_messages(messages)
+          return messages unless messages.is_a?(Array)
+
+          mapper = self
+          stripped = strip_reasoning_blocks(messages)
+
+          mapped = stripped.each_with_object([]) do |msg, acc|
+            next unless msg.is_a?(Hash)
+
+            role    = msg[:role]
+            content = msg[:content]
+
+            if %w[user developer].include?(role) && tool_result_message?(content)
+              # Responses API expects tool results as top-level input items.
+              # Also normalise nested tool_result output blocks to Responses
+              # input types (text → input_text, image → input_image).
+              content.each { |part| acc << map_tool_result_for_responses(part, mapper) }
+              next
+            end
+
+            if role == "assistant" && content.is_a?(Array)
+              acc.concat(map_assistant_content(content, mapper))
+              next
+            end
+
+            mapped_content =
+              if content.is_a?(Array)
+                content.map { |part| mapper.map_content(part) }
+              else
+                [ mapper.map_content(content) ]
+              end
+
+            acc << { role: role, content: mapped_content }
+          end
+
+          normalize_assistant_content_types(mapped)
+        end
+
+        # Recursively strip Codex-incompatible content blocks from a message tree.
+        #
+        #   "reasoning"    → always removed
+        #   "summary_text" → always removed
+        #   "thinking"     → removed unless :signature is present
+        def self.strip_reasoning_blocks(obj)
+          case obj
+          when Array
+            obj.map { |item| strip_reasoning_blocks(item) }.compact
+          when Hash
+            type = obj[:type]
+            return nil if %w[reasoning summary_text].include?(type)
+            return nil if type == "thinking" && obj[:signature].nil?
+
+            obj.each_with_object({}) do |(k, v), acc|
+              result = strip_reasoning_blocks(v)
+              acc[k] = result unless result.nil?
+            end
+          else
+            obj
+          end
+        end
+
+        # Ensure assistant messages carry "output_text" rather than "input_text".
+        # The base Responses input mapper maps plain text blocks to "input_text";
+        # Codex is strict about directionality and rejects "input_text" on the
+        # assistant side.
+        def self.normalize_assistant_content_types(messages)
+          return messages unless messages.is_a?(Array)
+
+          messages.map do |msg|
+            next msg unless msg.is_a?(Hash) && msg[:role] == "assistant" && msg[:content].is_a?(Array)
+
+            msg.merge(
+              content: msg[:content].map do |part|
+                part.is_a?(Hash) && part[:type] == "input_text" ? part.merge(type: "output_text") : part
+              end
+            )
+          end
+        end
+
+        def self.tool_result_message?(content)
+          content.is_a?(Array) &&
+            content.first.is_a?(Hash) &&
+            content.first[:type] == "tool_result"
+        end
+
+        # Map assistant content blocks into Codex-compatible top-level items.
+        #
+        # - thinking with signature  → parsed JSON reasoning item (the encrypted
+        #                               signature *is* the serialised item)
+        # - tool_use / function_call → top-level function_call item
+        # - text / *_text variants   → output_text inside an assistant content block
+        # - anything else            → delegated to the Responses input mapper
+        def self.map_assistant_content(content, mapper)
+          text_parts = []
+          items      = []
+
+          content.each do |part|
+            next unless part.is_a?(Hash)
+
+            case part[:type]
+            when "tool_use", "function_call"
+              call_id   = part[:id] || part[:call_id]
+              arguments = part[:input] || part[:arguments] || {}
+              arguments = JSON.generate(arguments) unless arguments.is_a?(String)
+
+              items << {
+                type: "function_call",
+                call_id: call_id,
+                name: part[:name],
+                arguments: arguments
+              }.compact
+
+            when "thinking"
+              # Only signed thinking blocks survive strip_reasoning_blocks;
+              # the signature payload is the full reasoning item JSON.
+              signature = part[:signature]
+              if signature
+                begin
+                  items << JSON.parse(signature, symbolize_names: true)
+                rescue JSON::ParserError
+                  # Malformed signature — silently drop.
+                end
+              end
+
+            when "text", "input_text", "output_text"
+              text_parts << { type: "output_text", text: part[:text].to_s }
+
+            else
+              mapped = mapper.map_content(part)
+              text_parts << mapped if mapped
+            end
+          end
+
+          # Text parts form a single assistant message; tool/reasoning items follow.
+          items.unshift({ role: "assistant", content: text_parts }) if text_parts.any?
+          items
+        end
+
+        # Wrap a tool_result part in the Responses wire format, normalising the
+        # nested output content types along the way.
+        def self.map_tool_result_for_responses(part, mapper)
+          return mapper.map_content(part) unless part.is_a?(Hash) && part[:type] == "tool_result"
+
+          mapper.map_content(part.merge(content: normalize_tool_result_output(part[:content])))
+        end
+
+        # Coerce each element of a tool result's output array to a Responses
+        # input type (input_text or input_image).
+        def self.normalize_tool_result_output(output)
+          Array(output).map do |item|
+            case item
+            when String
+              { type: "input_text", text: item }
+            when Hash
+              type = item[:type] || item["type"]
+              case type
+              when "text", "input_text", "output_text"
+                { type: "input_text", text: (item[:text] || item["text"]).to_s }
+              when "image", "input_image"
+                data      = item[:data]      || item["data"]
+                mime      = item[:mimeType]  || item["mimeType"] ||
+                            item[:media_type] || item["media_type"] || "image/png"
+                image_url = item[:image_url] || item["image_url"] ||
+                            "data:#{mime};base64,#{data}"
+                { type: "input_image", image_url: image_url }
+              else
+                item
+              end
+            else
+              { type: "input_text", text: item.to_s }
+            end
+          end
+        end
+
+        private_class_method :strip_reasoning_blocks, :normalize_assistant_content_types,
+                             :tool_result_message?, :map_assistant_content,
+                             :map_tool_result_for_responses, :normalize_tool_result_output
+      end
+    end
+  end
+end

data/lib/llm_gateway/adapters/openai_codex/option_mapper.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "../openai/responses/option_mapper"
+
+module LlmGateway
+  module Adapters
+    module OpenAICodex
+      module OptionMapper
+        module_function
+
+        def map(options)
+          mapped_options = OpenAI::Responses::OptionMapper.map(options)
+
+          # Codex endpoint currently rejects token limit parameters.
+          mapped_options.delete(:max_output_tokens)
+          mapped_options.delete(:max_completion_tokens)
+
+          # Codex transport does not use retention flags in the request body.
+          mapped_options.delete(:prompt_cache_retention)
+          mapped_options.delete(:cacheRetention)
+          mapped_options.delete(:cache_retention)
+
+          mapped_options
+        end
+      end
+    end
+  end
+end