llm_gateway 0.4.0 → 0.5.0

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

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

@@ -1,198 +1,124 @@
 # frozen_string_literal: true
 
-require_relative "../../structs"
+require_relative "../../stream_mapper"
 
 module LlmGateway
   module Adapters
     module OpenAI
       module Responses
-        class StreamMapper
-          def map(chunk)
-            queued_event = shift_queued_event
-            return queued_event if queued_event
-
+        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"
-              stash_response(data[:response])
-              nil
+              response_created_patches(data[:response])
             when "response.output_item.added"
-              map_output_item_added(data)
-            when "response.output_item.done"
-              map_output_item_done(data)
+              output_item_added_patches(data)
             when "response.content_part.added"
-              map_content_part_added(data)
-            when "response.content_part.done", "response.output_text.done"
-              map_text_done(data)
+              content_part_added_patches(data)
+            when "response.content_part.done"
+              content_part_done_patches(data)
             when "response.output_text.delta"
-              AssistantStreamEvent.new(
-                type: :text_delta,
-                content_index: content_index_for(data[:output_index] || 0),
-                delta: data[:delta] || ""
-              )
+              [ { type: :text_delta, delta: data[:delta] || "" } ]
             when "response.function_call_arguments.delta"
-              AssistantStreamEvent.new(
-                type: :tool_delta,
-                content_index: content_index_for(data[:output_index] || 0),
-                delta: data[:delta] || ""
-              )
+              [ { type: :tool_delta, delta: data[:delta] || "" } ]
             when "response.function_call_arguments.done"
-              map_tool_done(data)
+              [ { type: :tool_end, delta: "" } ]
+            when "response.reasoning_summary_part.added"
+              [ { type: :reasoning_start, delta: "", signature: "" } ]
             when "response.reasoning_summary_text.delta"
-              output_index = data[:output_index] || 0
-              mark_reasoning_has_content(output_index)
-              AssistantStreamReasoningEvent.new(
-                type: :reasoning_delta,
-                content_index: content_index_for(output_index),
-                delta: data[:delta] || "",
-                signature: ""
-              )
+              [ { type: :reasoning_delta, delta: data[:delta] || "", signature: "" } ]
+            when "response.reasoning_summary_part.done"
+              [ { type: :reasoning_end, delta: "", signature: "" } ]
             when "response.completed"
-              map_response_completed(data[:response])
+              response_completed_patches(data[:response])
             else
-              nil
+              []
             end
           end
 
-          private
-
-          def map_output_item_added(data)
-            item = data[:item] || {}
-            output_index = data[:output_index] || 0
+          def response_created_patches(response)
+            response ||= {}
 
-            case item[:type]
-            when "reasoning"
-              mark_reasoning_started(output_index)
-              AssistantStreamReasoningEvent.new(
-                type: :reasoning_start,
-                content_index: register_content_index(output_index),
-                delta: "",
-                signature: ""
-              )
-            when "message"
-              register_content_index(output_index)
-              ensure_message_started(role: item[:role] || "assistant")
-            when "function_call"
-              stash_role("assistant")
-              mark_tool_started(output_index)
-              AssistantToolStartEvent.new(
-                type: :tool_start,
-                content_index: register_content_index(output_index),
-                delta: "",
-                id: item[:call_id] || item[:id],
-                name: item[:name]
-              )
-            else
-              nil
-            end
+            [
+              {
+                type: :message_start,
+                delta: {
+                  id: response[:id],
+                  model: response[:model],
+                  role: "assistant"
+                }.compact,
+                usage_increment: {}
+              }
+            ]
           end
 
-          def map_output_item_done(data)
+          def output_item_added_patches(data)
             item = data[:item] || {}
-            output_index = data[:output_index] || 0
 
             case item[:type]
-            when "reasoning"
-              map_reasoning_done(output_index, item)
+            when "message"
+              return [] unless accumulator.message_hash.empty?
+
+              [
+                {
+                  type: :message_start,
+                  delta: { role: item[:role] || "assistant" },
+                  usage_increment: {}
+                }
+              ]
             when "function_call"
-              map_function_call_done(output_index, item)
-            else
-              nil
-            end
-          end
-
-          def map_reasoning_done(output_index, item)
-            content_index = content_index_for(output_index)
-            summary_text = extract_reasoning_summary_text(item)
-
-            if reasoning_started_without_content?(output_index) && !summary_text.empty?
-              queue_event(
-                AssistantStreamReasoningEvent.new(
-                  type: :reasoning_end,
-                  content_index:,
+              [
+                {
+                  type: :tool_start,
                   delta: "",
-                  signature: ""
-                )
-              )
-              mark_reasoning_completed(output_index)
-              return AssistantStreamReasoningEvent.new(
-                type: :reasoning_delta,
-                content_index:,
-                delta: summary_text,
-                signature: ""
-              )
+                  id: item[:call_id] || item[:id],
+                  name: item[:name]
+                }
+              ]
+            else
+              []
             end
-
-            mark_reasoning_completed(output_index)
-            AssistantStreamReasoningEvent.new(
-              type: :reasoning_end,
-              content_index:,
-              delta: "",
-              signature: ""
-            )
           end
 
-          def map_function_call_done(output_index, item)
-            return nil if tool_started?(output_index)
-
-            mark_tool_started(output_index)
-            queue_event(
-              AssistantStreamEvent.new(
-                type: :tool_end,
-                content_index: content_index_for(output_index),
-                delta: ""
-              )
-            )
+          def content_part_added_patches(data)
+            part = data[:part] || {}
+            return [] unless part[:type] == "output_text"
 
-            AssistantToolStartEvent.new(
-              type: :tool_start,
-              content_index: register_content_index(output_index),
-              delta: "",
-              id: item[:call_id] || item[:id],
-              name: item[:name]
-            )
+            [ { type: :text_start, delta: "" } ]
           end
 
-          def map_content_part_added(data)
+          def content_part_done_patches(data)
             part = data[:part] || {}
-            return nil unless part[:type] == "output_text"
-
-            AssistantStreamEvent.new(
-              type: :text_start,
-              content_index: content_index_for(data[:output_index] || 0),
-              delta: ""
-            )
-          end
+            return [] unless part.empty? || part[:type] == "output_text"
 
-          def map_text_done(data)
-            AssistantStreamEvent.new(
-              type: :text_end,
-              content_index: content_index_for(data[:output_index] || 0),
-              delta: ""
-            )
+            [ { type: :text_end, delta: "" } ]
           end
 
-          def map_tool_done(data)
-            AssistantStreamEvent.new(
-              type: :tool_end,
-              content_index: content_index_for(data[:output_index] || 0),
-              delta: ""
-            )
-          end
+          def response_completed_patches(response)
+            response ||= {}
 
-          def map_response_completed(response)
-            stash_response(response)
-            AssistantStreamMessageEvent.new(
-              type: message_started? ? :message_delta : :message_start,
-              delta: pending_message_attributes.merge(role: pending_message_attributes[:role] || "assistant", stop_reason: stop_reason_for(response)),
-              usage_increment: usage_increment(response)
-            ).tap do
-              @message_started = true
-              clear_pending_message_attributes
-            end
+            [
+              {
+                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)
@@ -211,127 +137,11 @@ module LlmGateway
             output = response[:output] || []
             last_item = output.last || {}
 
-            tool_state.any? || last_item[:type] == "function_call" ? "tool_use" : "stop"
-          end
-
-          def ensure_message_started(role: "assistant")
-            return nil if message_started?
-
-            @message_started = true
-            AssistantStreamMessageEvent.new(
-              type: :message_start,
-              delta: pending_message_attributes.merge(role: role).compact,
-              usage_increment: {}
-            ).tap do
-              clear_pending_message_attributes
-            end
-          end
-
-          def extract_reasoning_summary_text(item)
-            Array(item[:summary]).filter_map do |summary|
-              next summary[:text] if summary.is_a?(Hash) && summary[:text]
-              next summary[:summary] if summary.is_a?(Hash) && summary[:summary]
-              next summary if summary.is_a?(String)
-            end.join
+            tool_seen? || last_item[:type] == "function_call" ? "tool_use" : "stop"
           end
 
-          def mark_reasoning_started(output_index)
-            reasoning_state[output_index] = :started
-          end
-
-          def mark_reasoning_has_content(output_index)
-            reasoning_state[output_index] = :has_content
-          end
-
-          def mark_reasoning_completed(output_index)
-            reasoning_state[output_index] = :completed
-          end
-
-          def reasoning_started_without_content?(output_index)
-            reasoning_state[output_index] == :started
-          end
-
-          def reasoning_state
-            @reasoning_state ||= {}
-          end
-
-          def mark_tool_started(output_index)
-            tool_state[output_index] = :started
-          end
-
-          def tool_started?(output_index)
-            tool_state[output_index] == :started
-          end
-
-          def tool_state
-            @tool_state ||= {}
-          end
-
-          def stash_response(response)
-            response ||= {}
-            @pending_message_attributes = pending_message_attributes.merge(
-              id: response[:id],
-              model: response[:model]
-            ).compact
-          end
-
-          def stash_role(role)
-            @pending_message_attributes = pending_message_attributes.merge(role:)
-          end
-
-          def pending_message_attributes
-            @pending_message_attributes ||= {}
-          end
-
-          def clear_pending_message_attributes
-            @pending_message_attributes = {}
-          end
-
-          def register_content_index(output_index)
-            content_index_map[output_index] ||= next_content_index!
-          end
-
-          def content_index_for(output_index)
-            content_index_map.fetch(output_index) { register_content_index(output_index) }
-          end
-
-          def next_content_index!
-            @next_content_index ||= 0
-            current = @next_content_index
-            @next_content_index += 1
-            current
-          end
-
-          def content_index_map
-            @content_index_map ||= {}
-          end
-
-          def message_started?
-            @message_started ||= false
-          end
-
-          def queue_event(event)
-            queued_events << event
-          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)
+          def tool_seen?
+            accumulator.blocks.any? { |content_block| content_block && content_block[:type] == "tool_use" }
           end
         end
       end

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

@@ -4,7 +4,6 @@ require_relative "../adapter"
 require_relative "acts_like_responses"
 require_relative "../input_message_sanitizer"
 require_relative "responses/input_mapper"
-require_relative "responses/output_mapper"
 require_relative "responses/option_mapper"
 require_relative "file_output_mapper"
 require_relative "responses/stream_mapper"

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

@@ -26,7 +26,7 @@ module LlmGateway
         def self.map_messages(messages)
           return messages unless messages.is_a?(Array)
 
-          mapper  = message_mapper
+          mapper = self
           stripped = strip_reasoning_blocks(messages)
 
           mapped = stripped.each_with_object([]) do |msg, acc|
@@ -85,7 +85,7 @@ module LlmGateway
         end
 
         # Ensure assistant messages carry "output_text" rather than "input_text".
-        # The BidirectionalMessageMapper maps plain text blocks to "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)
@@ -114,7 +114,7 @@ module LlmGateway
         #                               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 BidirectionalMessageMapper
+        # - anything else            → delegated to the Responses input mapper
         def self.map_assistant_content(content, mapper)
           text_parts = []
           items      = []

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

@@ -2,7 +2,6 @@
 
 require_relative "../adapter"
 require_relative "../openai/acts_like_responses"
-require_relative "../openai/responses/output_mapper"
 require_relative "option_mapper"
 require_relative "../openai/responses/stream_mapper"
 require_relative "../openai/file_output_mapper"
@@ -25,10 +24,6 @@ module LlmGateway
           OptionMapper
         end
 
-        def perform_chat(messages, tools:, system:, **options)
-          client.chat_codex(messages, tools: tools, system: system, **options)
-        end
-
         def perform_stream(messages, tools:, system:, **options, &block)
           client.stream_codex(messages, tools: tools, system: system, **options, &block)
         end

data/lib/llm_gateway/adapters/stream_mapper.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "normalized_stream_accumulator"
+
+module LlmGateway
+  module Adapters
+    class StreamMapper
+      def result
+        accumulator.result
+      end
+
+      private
+
+      def accumulator
+        @accumulator ||= LlmGateway::Adapters::NormalizedStreamAccumulator.new
+      end
+
+      def push_patches(patches, &block)
+        patches.each do |patch|
+          accumulator.push(patch, &block)
+        end
+
+        nil
+      end
+
+      def raise_stream_error!(data, overload_codes: [])
+        error = stream_error_payload(data)
+        message = error[:message] || error["message"] || "Stream error"
+        code = error[:code] || error["code"] || error[:type] || error["type"]
+
+        if LlmGateway::Errors.context_overflow_message?(message)
+          raise LlmGateway::Errors::PromptTooLong.new(message, code)
+        end
+
+        if Array(overload_codes).any? { |overload_code| overload_code.to_s == code.to_s }
+          raise LlmGateway::Errors::OverloadError.new(message, code)
+        end
+
+        raise LlmGateway::Errors::APIStatusError.new(message, code)
+      end
+
+      def stream_error_payload(data)
+        data ||= {}
+        error = data[:error] || data["error"]
+
+        error.is_a?(Hash) ? error : data
+      end
+    end
+  end
+end