llm_gateway 0.2.0 → 0.4.0

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "base64"
+require_relative "bidirectional_message_mapper"
+
+module LlmGateway
+  module Adapters
+    module OpenAI
+      module Responses
+        class OutputMapper
+          def self.map(data)
+            {
+              id: data[:id],
+              model: data[:model],
+              usage: data[:usage],
+              choices: map_choices(data[:output])
+            }
+          end
+
+          private
+
+          def self.map_choices(choices)
+            return [] unless choices
+            message_mapper = BidirectionalMessageMapper.new(LlmGateway::DIRECTION_OUT)
+            choices.map do |choice|
+              content = if choice[:id].start_with?("fc_")
+                {
+                  id: choice[:id],
+                  role: choice[:role] || "assistant", # tool call doesnt have a role apparently
+                  content: [ message_mapper.map_content(choice) ].flatten
+                }
+              else
+               content = message_mapper.map_content(choice)
+               id = content.delete(:id)
+               {
+                 id: choice[:id] || id,
+                 role: choice[:role],
+                 content: [ content ].flatten
+               }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,340 @@
+# frozen_string_literal: true
+
+require_relative "../../structs"
+
+module LlmGateway
+  module Adapters
+    module OpenAI
+      module Responses
+        class StreamMapper
+          def map(chunk)
+            queued_event = shift_queued_event
+            return queued_event if queued_event
+
+            event_type = chunk[:event]
+            data = chunk[:data] || {}
+            raise_stream_error!(data) if event_type == "error" || data[:error] || data[:type] == "error"
+
+            case event_type
+            when "response.created"
+              stash_response(data[:response])
+              nil
+            when "response.output_item.added"
+              map_output_item_added(data)
+            when "response.output_item.done"
+              map_output_item_done(data)
+            when "response.content_part.added"
+              map_content_part_added(data)
+            when "response.content_part.done", "response.output_text.done"
+              map_text_done(data)
+            when "response.output_text.delta"
+              AssistantStreamEvent.new(
+                type: :text_delta,
+                content_index: content_index_for(data[:output_index] || 0),
+                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] || ""
+              )
+            when "response.function_call_arguments.done"
+              map_tool_done(data)
+            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: ""
+              )
+            when "response.completed"
+              map_response_completed(data[:response])
+            else
+              nil
+            end
+          end
+
+          private
+
+          def map_output_item_added(data)
+            item = data[:item] || {}
+            output_index = data[:output_index] || 0
+
+            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
+          end
+
+          def map_output_item_done(data)
+            item = data[:item] || {}
+            output_index = data[:output_index] || 0
+
+            case item[:type]
+            when "reasoning"
+              map_reasoning_done(output_index, item)
+            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:,
+                  delta: "",
+                  signature: ""
+                )
+              )
+              mark_reasoning_completed(output_index)
+              return AssistantStreamReasoningEvent.new(
+                type: :reasoning_delta,
+                content_index:,
+                delta: summary_text,
+                signature: ""
+              )
+            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: ""
+              )
+            )
+
+            AssistantToolStartEvent.new(
+              type: :tool_start,
+              content_index: register_content_index(output_index),
+              delta: "",
+              id: item[:call_id] || item[:id],
+              name: item[:name]
+            )
+          end
+
+          def map_content_part_added(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
+
+          def map_text_done(data)
+            AssistantStreamEvent.new(
+              type: :text_end,
+              content_index: content_index_for(data[:output_index] || 0),
+              delta: ""
+            )
+          end
+
+          def map_tool_done(data)
+            AssistantStreamEvent.new(
+              type: :tool_end,
+              content_index: content_index_for(data[:output_index] || 0),
+              delta: ""
+            )
+          end
+
+          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
+          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_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
+          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)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# 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/output_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  = message_mapper
+          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 BidirectionalMessageMapper 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 BidirectionalMessageMapper
+        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

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+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"
+require_relative "input_mapper"
+require_relative "../input_message_sanitizer"
+
+module LlmGateway
+  module Adapters
+    module OpenAICodex
+      class ResponsesAdapter < Adapter
+        include ActsLikeOpenAIResponses
+
+        private
+
+        def input_mapper
+          OpenAICodex::InputMapper
+        end
+
+        def option_mapper
+          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
+      end
+    end
+  end
+end

data/lib/llm_gateway/adapters/{open_ai/output_mapper.rb → option_mapper.rb}

@@ -2,8 +2,11 @@
 
 module LlmGateway
   module Adapters
-    module OpenAi
-      class OutputMapper < LlmGateway::Adapters::Groq::OutputMapper
+    module OptionMapper
+      module_function
+
+      def map(options)
+        options
       end
     end
   end