llm_gateway 0.4.0 → 0.6.0

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

@@ -1,103 +1,163 @@
 # 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)
+          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
 
-          def self.map_tools(tools)
-            return tools unless tools
-            mapper = message_mapper
+          class << self
+            private
 
-            tools.map do |tool|
-              mapped_tool = {
-                type: "function",
-                name: tool[:name],
-                description: tool[:description],
-                parameters: tool[:input_schema]
-              }
+            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)
+                [ :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
+                  mapped_tool[key] = tool[key].map do |entry|
+                    entry.is_a?(Hash) ? map_content(entry.transform_keys(&:to_sym)) : entry
+                  end
                 end
-              end
 
-              mapped_tool
+                mapped_tool
+              end
             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
+            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
-                  {
-                    role: msg[:role],
-                    content: content
-                  }
+                  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
-          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) }
+            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
 
-            text_blocks     = blocks.select { |b| b[:type] == "text" }
-            tool_use_blocks = blocks.select { |b| b[:type] == "tool_use" }
+              {
+                type: "function_call_output",
+                call_id: content[:tool_use_id],
+                output: output
+              }
+            end
 
-            result = []
+            def map_tool_use_content(content)
+              { id: content[:id] }
+            end
 
-            if text_blocks.any?
-              result << {
-                role: "assistant",
-                content: text_blocks.map { |b| { type: "output_text", text: b[:text] } }
+            def map_output_text_content(content)
+              {
+                type: "input_text",
+                text: content[: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
+            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
 
-            result
+            def map_text_content(content)
+              {
+                type: "input_text",
+                text: content[:text]
+              }
+            end
           end
         end
       end

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

@@ -5,27 +5,110 @@ module LlmGateway
     module OpenAI
       module Responses
         module OptionMapper
-          include LlmGateway::Adapters::OpenAI::PromptCacheOptionMapper
-
+          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.dup
+            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
 
-            max_completion_tokens = mapped_options.delete(:max_completion_tokens)
-            mapped_options[:max_output_tokens] = max_completion_tokens || mapped_options[:max_output_tokens] || 20_480
+            cache_key = options[:cache_key]
+            mapped_options[:prompt_cache_key] = cache_key unless cache_key.nil?
 
-            map_cache_key!(mapped_options)
-            map_prompt_cache_retention!(mapped_options)
+            cache_retention = options[:cache_retention]
+            mapped_options[:prompt_cache_retention] = normalize_cache_retention(cache_retention) \
+              unless cache_retention.nil?
 
-            return mapped_options unless mapped_options.key?(:reasoning)
+            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)
-            return mapped_options if reasoning.nil? || reasoning.to_s == "none"
+            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
 
-            mapped_options.merge(reasoning: normalize_reasoning(reasoning))
+          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)
@@ -34,6 +117,12 @@ module LlmGateway
 
             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