llm_gateway 0.4.0 → 0.6.0

data/lib/llm_gateway/adapters/normalized_stream_accumulator.rb

@@ -0,0 +1,336 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "../utils"
+require_relative "structs"
+
+module LlmGateway
+  module Adapters
+    class NormalizedStreamAccumulator
+      # Contract:
+      #
+      # `push` accepts a single provider-independent, normalized stream event
+      # patch hash. Event patches are never arrays; mappers call `push` once per
+      # patch.
+      #
+      # Provider wire events such as Anthropic `message_start` /
+      # `content_block_start`, OpenAI `response.output_text.delta`, etc. must be
+      # translated by the mapper before calling this accumulator. The normalized
+      # symbol `:message_start` below is allowed; the raw provider event string is
+      # not.
+      #
+      # Accepted event shapes:
+      #
+      #   { type: :message_start, delta: { id: "...", model: "...", role: "assistant", timestamp: 1716650000000 } }
+      #   { type: :message_delta, delta: { stop_reason: "stop" }, usage: { output: 2 } }
+      #   { type: :message_end }
+      #
+      #   { type: :text_start, delta: "hi" }
+      #   { type: :text_delta, delta: " there" }
+      #   { type: :text_end, delta: "" }
+      #
+      #   { type: :reasoning_start, delta: "thinking", signature: "" }
+      #   { type: :reasoning_delta, delta: "...", signature: "" }
+      #   { type: :reasoning_end, delta: "", signature: "" }
+      #
+      #   { type: :tool_start, id: "...", name: "tool_name", delta: "" }
+      #   { type: :tool_delta, delta: "{\"a\":" }
+      #   { type: :tool_end, delta: "" }
+      #
+      # Mappers do not provide `content_index`. The accumulator assigns the next
+      # public content index when a block starts and reuses the active content
+      # index for that block's deltas and end event.
+      #
+      # Without source indexes, the accumulator cannot detect two interleaved
+      # blocks of the same type. Providers that can interleave same-type blocks
+      # must buffer or serialize them in the mapper before pushing normalized
+      # events.
+      #
+      # The accumulator creates the public Assistant* event structs, updates its
+      # accumulated message state, then yields the created event to the callback.
+      attr_accessor :blocks, :message_hash, :usage_hash
+      attr_reader :active_block_type, :final_message
+
+      DEFAULT_USAGE = {
+        input: 0,
+        cache_write: 0,
+        cache_read: 0,
+        output: 0,
+        total: 0,
+        raw: {}
+      }.freeze
+
+      BLOCK_EVENT_TRANSITIONS = {
+        text_start: { block_type: :text, phase: :start },
+        text_delta: { block_type: :text, phase: :delta },
+        text_end: { block_type: :text, phase: :end },
+        tool_start: { block_type: :tool, phase: :start },
+        tool_delta: { block_type: :tool, phase: :delta },
+        tool_end: { block_type: :tool, phase: :end },
+        reasoning_start: { block_type: :reasoning, phase: :start },
+        reasoning_delta: { block_type: :reasoning, phase: :delta },
+        reasoning_end: { block_type: :reasoning, phase: :end }
+      }.freeze
+
+      def initialize(provider: nil, api: nil)
+        @provider = provider
+        @api = api
+        @message_hash = {}
+        @usage_hash = default_usage
+        @blocks = []
+        @next_content_index = 0
+        @active_block_type = nil
+        @active_content_index = nil
+        @timestamp = nil
+      end
+
+      def result
+        ensure_timestamp!
+
+        message_hash.merge(
+          timestamp: @timestamp,
+          usage: usage_hash,
+          content: serialized_blocks
+        )
+      end
+
+      def final_result
+        result.merge(provider: @provider, api: @api)
+      end
+
+      def active_tool?
+        active_block_type == :tool
+      end
+
+      def push(event_patch, &block)
+        raise ArgumentError, "Normalized stream event patch must be a Hash" unless event_patch.is_a?(Hash)
+
+        event_patch = symbolize_keys(event_patch)
+        type = event_patch.fetch(:type).to_sym
+        event_patch = prepare_event_patch(event_patch.merge(type:), type)
+        ensure_timestamp!
+
+        if type == :message_end
+          @final_message = AssistantMessage.new(final_result)
+          block.call(AssistantStreamMessageEndEvent.new(type:, message: final_message)) if block
+          return nil
+        end
+
+        event = build_event(event_patch, partial: empty_partial)
+        accumulate(event)
+        content_index = event.content_index if event.respond_to?(:content_index)
+        commit_block_transition(type, content_index)
+        event = build_event(event_patch, partial: partial_message)
+        block.call(event) if block
+
+        nil
+      end
+
+      private
+
+      def prepare_event_patch(event_patch, type)
+        transition = BLOCK_EVENT_TRANSITIONS[type]
+        return event_patch unless transition
+
+        block_type = transition[:block_type]
+
+        case transition[:phase]
+        when :start
+          validate_start!(block_type)
+          event_patch.merge(content_index: @next_content_index)
+        when :delta
+          validate_delta!(type, block_type)
+          event_patch.merge(content_index: @active_content_index)
+        when :end
+          validate_end!(block_type)
+          event_patch.merge(content_index: @active_content_index)
+        end
+      end
+
+      def validate_start!(block_type)
+        return unless @active_block_type
+
+        raise ArgumentError, "Cannot start #{block_type} block while #{@active_block_type} block is active"
+      end
+
+      def validate_delta!(type, block_type)
+        unless @active_block_type
+          raise ArgumentError, "Cannot apply #{type} without an active #{block_type} block"
+        end
+        return if @active_block_type == block_type
+
+        raise ArgumentError, "Cannot apply #{type} while #{@active_block_type} block is active"
+      end
+
+      def validate_end!(block_type)
+        unless @active_block_type
+          raise ArgumentError, "Cannot end #{block_type} block without an active #{block_type} block"
+        end
+        return if @active_block_type == block_type
+
+        raise ArgumentError, "Cannot end #{block_type} block while #{@active_block_type} block is active"
+      end
+
+      def commit_block_transition(type, content_index)
+        transition = BLOCK_EVENT_TRANSITIONS[type]
+        return unless transition
+
+        case transition[:phase]
+        when :start
+          @active_block_type = transition[:block_type]
+          @active_content_index = content_index
+          @next_content_index += 1
+        when :end
+          @active_block_type = nil
+          @active_content_index = nil
+        end
+      end
+
+      def build_event(event_patch, partial:)
+        event_patch = symbolize_keys(event_patch)
+        type = event_patch.fetch(:type).to_sym
+
+        case type
+        when :message_start, :message_delta
+          delta = symbolize_keys(event_patch[:delta] || {})
+          raw_usage = event_patch[:usage] || delta.delete(:usage) || {}
+          usage = raw_usage.empty? ? {} : normalized_usage(raw_usage)
+
+          AssistantStreamMessageEvent.new(
+            type:,
+            delta:,
+            usage:,
+            partial:
+          )
+        when :tool_start
+          AssistantToolStartEvent.new(
+            type:,
+            content_index: event_patch.fetch(:content_index),
+            delta: string_value(event_patch[:delta]),
+            id: event_patch[:id],
+            name: event_patch[:name],
+            partial:
+          )
+        when :reasoning_start, :reasoning_delta, :reasoning_end
+          AssistantStreamReasoningEvent.new(
+            type:,
+            content_index: event_patch.fetch(:content_index),
+            delta: string_value(event_patch[:delta]),
+            signature: string_value(event_patch[:signature]),
+            partial:
+          )
+        when :text_start, :text_delta, :text_end, :tool_delta, :tool_end
+          AssistantStreamEvent.new(
+            type:,
+            content_index: event_patch.fetch(:content_index),
+            delta: string_value(event_patch[:delta]),
+            partial:
+          )
+        else
+          raise ArgumentError, "Unsupported normalized stream event type: #{type.inspect}"
+        end
+      end
+
+      def accumulate(event)
+        @timestamp = event.delta[:timestamp] if event.respond_to?(:delta) && event.delta.is_a?(Hash) && event.delta[:timestamp]
+
+        case event.type
+        when :text_start
+          blocks[event.content_index] = {
+            type: "text",
+            text: ""
+          }
+          blocks[event.content_index][:text] += event.delta
+        when :text_delta, :text_end
+          blocks[event.content_index][:text] += event.delta
+        when :tool_start
+          blocks[event.content_index] = {
+            type: "tool_use",
+            id: event.id,
+            name: event.name,
+            input: event.delta.to_s
+          }
+        when :tool_delta, :tool_end
+          blocks[event.content_index][:input] += event.delta
+        when :message_start
+          message_hash.merge!(event.delta)
+        when :reasoning_start
+          blocks[event.content_index] = {
+            type: "reasoning",
+            reasoning: "",
+            signature: ""
+          }
+          blocks[event.content_index][:reasoning] += event.delta
+          blocks[event.content_index][:signature] += event.signature
+        when :reasoning_delta, :reasoning_end
+          blocks[event.content_index][:reasoning] += event.delta
+          blocks[event.content_index][:signature] += event.signature
+        when :message_delta
+          message_hash.merge!(event.delta)
+          assign_usage(event.usage) unless event.usage.empty?
+        end
+      end
+
+      def empty_partial
+        PartialAssistantMessage.new(timestamp: @timestamp)
+      end
+
+      def partial_message
+        PartialAssistantMessage.new(partial_result)
+      end
+
+      def partial_result
+        ensure_timestamp!
+
+        message_hash.merge(
+          timestamp: @timestamp,
+          content: serialized_blocks
+        )
+      end
+
+      def assign_usage(usage)
+        @usage_hash = normalized_usage(usage)
+      end
+
+      def normalized_usage(usage)
+        usage = default_usage.merge(symbolize_keys(usage).slice(*DEFAULT_USAGE.keys))
+        usage[:total] = usage[:input] + usage[:cache_write] + usage[:cache_read] + usage[:output]
+        usage[:raw] ||= {}
+        usage
+      end
+
+      def default_usage
+        DEFAULT_USAGE.merge(raw: {})
+      end
+
+      def serialized_blocks
+        blocks.map do |content_block|
+          next content_block unless content_block[:type] == "tool_use"
+
+          content_block.merge(input: LlmGateway::Utils.deep_symbolize_keys(parse_tool_input(content_block[:input])))
+        end
+      end
+
+      def parse_tool_input(input)
+        return {} if input.nil? || input.empty?
+
+        JSON.parse(input)
+      rescue JSON::ParserError
+        {}
+      end
+
+      def symbolize_keys(hash)
+        hash.to_h.transform_keys { |key| key.respond_to?(:to_sym) ? key.to_sym : key }
+      end
+
+      def string_value(value)
+        value.nil? ? "" : value.to_s
+      end
+
+      def ensure_timestamp!
+        @timestamp ||= (Time.now.to_f * 1000).to_i
+      end
+    end
+  end
+end

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

@@ -10,8 +10,6 @@ module LlmGateway
 
       def input_sanitizer = OpenAI::ChatCompletions::InputMessageSanitizer
 
-      def output_mapper = OpenAI::ChatCompletions::OutputMapper
-
       def file_output_mapper = OpenAI::FileOutputMapper
 
       def option_mapper = OpenAI::ChatCompletions::OptionMapper

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

@@ -11,18 +11,12 @@ module LlmGateway
 
       def input_sanitizer = InputMessageSanitizer
 
-      def output_mapper = OpenAI::Responses::OutputMapper
-
       def file_output_mapper = OpenAI::FileOutputMapper
 
       def option_mapper = OpenAI::Responses::OptionMapper
 
       def stream_mapper = OpenAI::Responses::StreamMapper
 
-      def perform_chat(messages, tools:, system:, **options)
-        client.responses(messages, tools: tools, system: system, **options)
-      end
-
       def perform_stream(messages, tools:, system:, **options, &block)
         client.stream_responses(messages, tools: tools, system: system, **options, &block)
       end

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

@@ -1,104 +1,167 @@
 # frozen_string_literal: true
 
 require "base64"
-require_relative "bidirectional_message_mapper"
 
 module LlmGateway
   module Adapters
     module OpenAI
       module ChatCompletions
         class InputMapper
-        def self.map(data)
-          {
-            messages: map_messages(data[:messages]),
-            tools: map_tools(data[:tools]),
-            system: map_system(data[:system])
-          }
-        end
+          def self.map(data)
+            {
+              messages: map_messages(data[:messages]),
+              tools: map_tools(data[:tools]),
+              system: map_system(data[:system])
+            }
+          end
 
-        private
+          def self.map_content(content)
+            content = { type: "text", text: content } unless content.is_a?(Hash)
 
-        def self.map_messages(messages)
-          return messages unless messages
+            case content[:type]
+            when "text"
+              map_text_content(content)
+            when "file"
+              map_file_content(content)
+            when "image"
+              map_image_content(content)
+            when "tool_use", "function"
+              map_tool_use_content(content)
+            when "tool_result"
+              map_tool_result_content(content)
+            else
+              content
+            end
+          end
+
+          class << self
+            private
 
-          message_mapper = BidirectionalMessageMapper.new(LlmGateway::DIRECTION_IN)
+            def map_messages(messages)
+              return messages unless messages
 
-          # First map messages like Claude
-          mapped_messages = messages.map do |msg|
-            msg = msg.merge(role: "user") if msg[:role] == "developer"
+              mapped_messages = messages.map do |msg|
+                msg = msg.merge(role: "user") if msg[:role] == "developer"
 
-            content = if msg[:content].is_a?(Array)
-                msg[:content].map do |content|
-                  message_mapper.map_content(content)
+                content = if msg[:content].is_a?(Array)
+                  msg[:content].map { |content| map_content(content) }
+                else
+                  [ map_content(msg[:content]) ]
                 end
-            else
-              [ message_mapper.map_content(msg[:content]) ]
+
+                {
+                  role: msg[:role],
+                  content: content
+                }
+              end
+
+              mapped_messages.flat_map do |msg|
+                tool_calls = []
+                regular_content = []
+                tool_messages = []
+                msg[:content].each do |content|
+                  case content[:type] || content[:role]
+                  when "tool"
+                    tool_messages << content
+                  when "function"
+                    tool_calls << content
+                  else
+                    regular_content << content
+                  end
+                end
+                result = []
+
+                if tool_calls.any? || regular_content.any?
+                  main_msg = msg.dup
+                  main_msg[:role] = "assistant" if !main_msg[:role]
+                  main_msg[:tool_calls] = tool_calls if tool_calls.any?
+                  main_msg[:content] = regular_content.any? ? regular_content : nil
+                  result << main_msg
+                end
+
+                result + tool_messages
+              end
             end
 
-            {
-              role: msg[:role],
-              content: content
-            }
-          end
-          # Then transform to OpenAI format
-          mapped_messages.flat_map do |msg|
-            # Handle array content with tool calls and tool results
-            tool_calls = []
-            regular_content = []
-            tool_messages = []
-            msg[:content].each do |content|
-              case content[:type] || content[:role]
-              when "tool"
-                tool_messages << content
-              when "function"
-                tool_calls << content
-              else
-                regular_content << content
+            def map_tools(tools)
+              return tools unless tools
+
+              tools.map do |tool|
+                {
+                  type: "function",
+                  function: {
+                    name: tool[:name],
+                    description: tool[:description],
+                    parameters: tool[:input_schema]
+                  }
+                }
               end
             end
-            result = []
-
-            # Add the main message with tool calls if any
-            if tool_calls.any? || regular_content.any?
-              main_msg = msg.dup
-              main_msg[:role] = "assistant" if !main_msg[:role]
-              main_msg[:tool_calls] = tool_calls if tool_calls.any?
-              main_msg[:content] = regular_content.any? ? regular_content : nil
-              result << main_msg
+
+            def map_system(system)
+              if !system || system.empty?
+                []
+              else
+                system.map do |msg|
+                  msg[:role] == "system" ? msg.merge(role: "developer") : msg
+                end
+              end
             end
 
-            # Add separate tool result messages
-            result += tool_messages
+            def map_text_content(content)
+              {
+                type: "text",
+                text: content[:text]
+              }
+            end
 
-            result
-          end
-        end
+            def map_file_content(content)
+              media_type = content[:media_type] == "text/plain" ? "application/pdf" : content[:media_type]
+              {
+                type: "file",
+                file: {
+                  filename: content[:name],
+                  file_data: "data:#{media_type};base64,#{Base64.encode64(content[:data])}"
+                }
+              }
+            end
 
-        def self.map_tools(tools)
-          return tools unless tools
+            def map_image_content(content)
+              {
+                type: "image_url",
+                image_url: {
+                  url: "data:#{content[:media_type]};base64,#{content[:data]}"
+                }
+              }
+            end
 
-          tools.map do |tool|
-            {
-              type: "function",
-              function: {
-                name: tool[:name],
-                description: tool[:description],
-                parameters: tool[:input_schema]
+            def map_tool_use_content(content)
+              {
+                id: content[:id],
+                type: "function",
+                function: {
+                  name: content[:name],
+                  arguments: content[:input].to_json
+                }
               }
-            }
-          end
-        end
+            end
 
-        def self.map_system(system)
-          if !system || system.empty?
-            []
-          else
-            system.map do |msg|
-              msg[:role] == "system" ? msg.merge(role: "developer") : msg
+            def map_tool_result_content(content)
+              mapped_content = content[:content]
+              if mapped_content.is_a?(Array)
+                mapped_content = mapped_content.map do |item|
+                  item.is_a?(Hash) ? map_content(item.transform_keys(&:to_sym)) : item
+                end
+              end
+
+              {
+                role: "tool",
+                tool_call_id: content[:tool_use_id],
+                content: mapped_content
+              }
             end
           end
         end
-        end
       end
     end
   end