llm_gateway 0.3.0 → 0.5.0

data/lib/llm_gateway/adapters/groq/chat_completions_adapter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "../adapter"
+require_relative "../openai/acts_like_chat_completions"
+require_relative "../input_message_sanitizer"
+require_relative "../openai/chat_completions/stream_mapper"
+require_relative "input_mapper"
+require_relative "option_mapper"
+
+module LlmGateway
+  module Adapters
+    module Groq
+      class ChatCompletionsAdapter < Adapter
+        include ActsLikeOpenAIChatCompletions
+
+        private
+
+        def file_output_mapper = nil
+        def input_mapper = Groq::InputMapper
+        def option_mapper = Groq::OptionMapper
+
+        def map_input(input)
+          groq_safe_input = input.dup
+          groq_safe_input[:messages] = Array(input[:messages]).map do |msg|
+            next msg unless msg.is_a?(Hash) && msg[:content].is_a?(Array)
+
+            rewritten_content = msg[:content].map do |block|
+              next block unless block.is_a?(Hash) && block[:type] == "file"
+
+              {
+                type: "text",
+                text: block[:text] || "[File: #{block[:name]}]"
+              }
+            end
+
+            msg.merge(content: rewritten_content)
+          end
+
+          mapped = super(groq_safe_input)
+          mapped[:system] = Array(mapped[:system]).map do |msg|
+            msg[:role] == "developer" ? msg.merge(role: "system") : msg
+          end
+          mapped
+        end
+      end
+    end
+  end
+end

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

@@ -1,17 +1,43 @@
 # frozen_string_literal: true
 
-require_relative "bidirectional_message_mapper"
-require_relative "../open_ai/chat_completions/input_mapper"
+require_relative "../openai/chat_completions/input_mapper"
 
 module LlmGateway
   module Adapters
     module Groq
-      class InputMapper < OpenAi::ChatCompletions::InputMapper
-        private
+      class InputMapper < OpenAI::ChatCompletions::InputMapper
+        def self.map(data)
+          mapped = super
+          mapped.merge(messages: map_groq_messages(mapped[:messages]))
+        end
+
+        def self.map_groq_messages(messages)
+          return messages unless messages.is_a?(Array)
+
+          messages.map { |message| map_groq_message(message) }
+        end
+
+        def self.map_groq_message(message)
+          return message unless message.is_a?(Hash) && message[:role] == "assistant"
+          return message unless message[:content].is_a?(Array)
 
-        def self.map_system(system)
-          system
+          reasoning_blocks, content_blocks = message[:content].partition do |block|
+            block.is_a?(Hash) && %w[reasoning thinking].include?(block[:type] || block["type"])
+          end
+
+          return message if reasoning_blocks.empty?
+
+          mapped = message.merge(content: content_blocks.empty? ? nil : content_blocks)
+          reasoning = reasoning_blocks.filter_map { |block| reasoning_text(block) }.join("\n")
+          mapped[:reasoning] = reasoning unless reasoning.empty?
+          mapped
         end
+
+        def self.reasoning_text(block)
+          block[:reasoning] || block["reasoning"] || block[:thinking] || block["thinking"]
+        end
+
+        private_class_method :map_groq_messages, :map_groq_message, :reasoning_text
       end
     end
   end

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module LlmGateway
+  module Adapters
+    module Groq
+      module OptionMapper
+        DEFAULT_TEMPERATURE = 0
+        DEFAULT_MAX_COMPLETION_TOKENS = 20_480
+        VALID_REASONING_LEVELS = %w[default low medium high].freeze
+
+        # Source: https://console.groq.com/docs/text-chat.md and
+        # https://console.groq.com/docs/api-reference.md#chat-create
+        # API: Groq Chat Completions Create; accessed 2026-05-19.
+        # Body parameters listed by the API reference: messages, model,
+        # citation_options, compound_custom, disable_tool_validation, documents,
+        # exclude_domains, frequency_penalty, function_call, functions,
+        # include_domains, include_reasoning, logit_bias, logprobs,
+        # max_completion_tokens, max_tokens, metadata, n, parallel_tool_calls,
+        # presence_penalty, reasoning_effort, reasoning_format, response_format,
+        # search_settings, seed, service_tier, stop, store, stream,
+        # stream_options, temperature, tool_choice, tools, top_logprobs, top_p,
+        # user.
+        # This mapper intentionally excludes transcript/tool structural fields
+        # (messages, tools) from option handling.
+        VALID_OPTIONS = %i[
+          model
+          citation_options
+          compound_custom
+          disable_tool_validation
+          documents
+          exclude_domains
+          frequency_penalty
+          function_call
+          functions
+          include_domains
+          include_reasoning
+          logit_bias
+          logprobs
+          max_completion_tokens
+          max_tokens
+          metadata
+          n
+          parallel_tool_calls
+          presence_penalty
+          reasoning_effort
+          reasoning_format
+          response_format
+          search_settings
+          seed
+          service_tier
+          stop
+          store
+          stream
+          stream_options
+          temperature
+          tool_choice
+          top_logprobs
+          top_p
+          user
+        ].freeze
+
+        MANAGED_OPTIONS = %i[
+          reasoning
+          cache_key
+          cache_retention
+        ].freeze
+
+        module_function
+
+        def map(options)
+          mapped_options = options.reject { |key, _| MANAGED_OPTIONS.include?(key) }
+          mapped_options[:temperature] = options.key?(:temperature) ? options[:temperature] : DEFAULT_TEMPERATURE
+          mapped_options[:max_completion_tokens] = options[:max_completion_tokens] || DEFAULT_MAX_COMPLETION_TOKENS
+          mapped_options[:response_format] = normalize_response_format(options[:response_format] || "text")
+
+          reasoning = options[:reasoning]
+          unless reasoning.nil? || reasoning.to_s == "none"
+            mapped_options[:reasoning_effort] = normalize_reasoning_effort(reasoning)
+            mapped_options[:reasoning_format] = "parsed"
+          end
+
+          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 Groq Chat Completions options: #{unknown_options.join(', ')}. " \
+                "Valid options: #{VALID_OPTIONS.join(', ')}."
+        end
+
+        def normalize_response_format(response_format)
+          if response_format.is_a?(String)
+            { type: response_format }
+          else
+            response_format
+          end
+        end
+
+        def normalize_reasoning_effort(reasoning)
+          effort = reasoning.to_s
+          return effort if VALID_REASONING_LEVELS.include?(effort)
+
+          raise ArgumentError, "Invalid reasoning '#{reasoning}'. Use 'none', 'default', 'low', 'medium', or 'high'."
+        end
+      end
+    end
+  end
+end

data/lib/llm_gateway/adapters/input_message_sanitizer.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module LlmGateway
+  module Adapters
+    class InputMessageSanitizer
+      def self.sanitize(messages, target_provider:, target_api:, target_model:)
+        return messages unless messages.is_a?(Array)
+
+        messages.map do |message|
+          sanitize_message(
+            message,
+            target_provider: target_provider,
+            target_api: target_api,
+            target_model: target_model
+          )
+        end
+      end
+
+      def self.sanitize_message(message, target_provider:, target_api:, target_model:)
+        return message unless message.is_a?(Hash)
+
+        role = message[:role] || message["role"]
+        content = message[:content] || message["content"]
+        return message unless role == "assistant" && content.is_a?(Array)
+        return message unless message_metadata_present?(message)
+
+        same_model_replay = same_model_replay?(message, target_provider:, target_api:, target_model:)
+
+        sanitized_content = content.each_with_object([]) do |block, acc|
+          sanitized = sanitize_content_block(block, same_model_replay: same_model_replay)
+          next if sanitized.nil?
+
+          if sanitized.is_a?(Array)
+            acc.concat(sanitized)
+          else
+            acc << sanitized
+          end
+        end
+
+        message.merge(content: sanitized_content)
+      end
+
+      def self.sanitize_content_block(block, same_model_replay:)
+        return block unless block.is_a?(Hash)
+
+        type = block[:type] || block["type"]
+        return block unless %w[thinking reasoning].include?(type)
+        return block if same_model_replay
+
+        text = extract_reasoning_text(block)
+        return nil if text.nil? || text.strip.empty?
+
+        { type: "text", text: text }
+      end
+
+      def self.extract_reasoning_text(block)
+        return block[:thinking] if block[:thinking].is_a?(String)
+        return block[:reasoning] if block[:reasoning].is_a?(String)
+
+        summary = block[:summary]
+        if summary.is_a?(Array)
+          text = summary.filter_map do |item|
+            next item if item.is_a?(String)
+            next unless item.is_a?(Hash)
+
+            item[:text] || item[:summary_text] || item[:reasoning]
+          end.join("\n")
+          return text unless text.empty?
+        end
+
+        nil
+      end
+
+      def self.same_model_replay?(message, target_provider:, target_api:, target_model:)
+        provider = message[:provider] || message["provider"]
+        api = message[:api] || message["api"]
+        model = message[:model] || message["model"]
+
+        provider == target_provider && api == target_api && model == target_model
+      end
+
+      def self.message_metadata_present?(message)
+        provider = message[:provider] || message["provider"]
+        api = message[:api] || message["api"]
+        model = message[:model] || message["model"]
+
+        !provider.nil? && !api.nil? && !model.nil?
+      end
+
+      private_class_method :sanitize_message, :sanitize_content_block, :extract_reasoning_text, :same_model_replay?, :message_metadata_present?
+    end
+  end
+end

data/lib/llm_gateway/adapters/normalized_stream_accumulator.rb

@@ -0,0 +1,275 @@
+# 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" }, usage_increment: { ... } }
+      #   { type: :message_delta, delta: { stop_reason: "stop" }, usage_increment: { ... } }
+      #   { 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
+
+      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
+        @message_hash = {}
+        @usage_hash = {
+          input_tokens: 0,
+          cache_creation_input_tokens: 0,
+          cache_read_input_tokens: 0,
+          output_tokens: 0,
+          reasoning_tokens: 0
+        }
+        @blocks = []
+        @next_content_index = 0
+        @active_block_type = nil
+        @active_content_index = nil
+      end
+
+      def result
+        message_hash.merge(
+          usage: usage_hash,
+          content: serialized_blocks
+        )
+      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)
+
+        event = build_event(event_patch)
+        accumulate(event)
+        content_index = event.content_index if event.respond_to?(:content_index)
+        commit_block_transition(type, content_index)
+        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)
+        event_patch = symbolize_keys(event_patch)
+        type = event_patch.fetch(:type).to_sym
+
+        case type
+        when :message_start, :message_delta, :message_end
+          AssistantStreamMessageEvent.new(
+            type:,
+            delta: symbolize_keys(event_patch[:delta] || {}),
+            usage_increment: symbolize_keys(event_patch[:usage_increment] || {})
+          )
+        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]
+          )
+        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])
+          )
+        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])
+          )
+        else
+          raise ArgumentError, "Unsupported normalized stream event type: #{type.inspect}"
+        end
+      end
+
+      def accumulate(event)
+        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)
+          usage_hash.each_key do |key|
+            usage_hash[key] += event.usage_increment.fetch(key, 0)
+          end
+        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)
+          usage_hash.each_key do |key|
+            usage_hash[key] += event.usage_increment.fetch(key, 0)
+          end
+        when :message_end
+        end
+      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
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module LlmGateway
+  module Adapters
+    module ActsLikeOpenAIChatCompletions
+      private
+      def api_name = "completions"
+
+      def input_mapper = OpenAI::ChatCompletions::InputMapper
+
+      def input_sanitizer = OpenAI::ChatCompletions::InputMessageSanitizer
+
+      def file_output_mapper = OpenAI::FileOutputMapper
+
+      def option_mapper = OpenAI::ChatCompletions::OptionMapper
+
+      def stream_mapper = OpenAI::ChatCompletions::StreamMapper
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module LlmGateway
+  module Adapters
+    module ActsLikeOpenAIResponses
+      private
+
+      def api_name = "responses"
+
+      def input_mapper = OpenAI::Responses::InputMapper
+
+      def input_sanitizer = InputMessageSanitizer
+
+      def file_output_mapper = OpenAI::FileOutputMapper
+
+      def option_mapper = OpenAI::Responses::OptionMapper
+
+      def stream_mapper = OpenAI::Responses::StreamMapper
+
+      def perform_stream(messages, tools:, system:, **options, &block)
+        client.stream_responses(messages, tools: tools, system: system, **options, &block)
+      end
+    end
+  end
+end