llm_gateway 0.4.0 → 0.5.0

data/lib/llm_gateway/adapters/anthropic/stream_mapper.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-require_relative "../structs.rb"
+require_relative "../stream_mapper"
 
 module LlmGateway
   module Adapters
     module Anthropic
-      class StreamMapper
-        def map(chunk)
+      class StreamMapper < LlmGateway::Adapters::StreamMapper
+        def map(chunk, &block)
           case chunk[:event]
           when "message_start"
             delta = {
@@ -16,81 +16,66 @@ module LlmGateway
             }
             usage_increment = chunk.dig(:data, :message, :usage) || {}
 
-            AssistantStreamMessageEvent.new(type: :message_start, usage_increment:, delta:)
+            accumulator.push({ type: :message_start, usage_increment:, delta: }, &block)
           when "content_block_start"
-            content_index = chunk.dig(:data, :index)
-            delta = chunk.dig(:data, :content_block, :text)
-            current_type = chunk.dig(:data, :content_block, :type)
-            content_block_types[content_index] = current_type
+            content_block = chunk.dig(:data, :content_block) || {}
+            @current_content_block_type = content_block[:type]
 
-            case current_type
+            case @current_content_block_type
             when "thinking"
-              AssistantStreamEvent.new(type: :reasoning_start, content_index:, delta:)
+              accumulator.push({ type: :reasoning_start, delta: content_block[:thinking], signature: "" }, &block)
             when "text"
-              AssistantStreamEvent.new(type: :text_start, content_index:, delta:)
+              accumulator.push({ type: :text_start, delta: content_block[:text] }, &block)
             when "tool_use"
-              id = chunk.dig(:data, :content_block, :id)
-              name = chunk.dig(:data, :content_block, :name)
-              AssistantToolStartEvent.new(type: :tool_start, content_index:, delta:, id:, name:)
+              accumulator.push(
+                {
+                  type: :tool_start,
+                  delta: "",
+                  id: content_block[:id],
+                  name: content_block[:name]
+                },
+                &block
+              )
             end
           when "content_block_delta"
-            content_index = chunk.dig(:data, :index)
-
-            case content_block_types[content_index]
+            case @current_content_block_type
             when "thinking"
               delta = chunk.dig(:data, :delta, :thinking)
-              signature = chunk.dig(:data, :delta, :signature)
-              AssistantStreamReasoningEvent.new(type: :reasoning_delta, signature:, delta:, content_index:)
+              signature = chunk.dig(:data, :delta, :signature) || ""
+              accumulator.push({ type: :reasoning_delta, signature:, delta: }, &block)
             when "text"
               delta = chunk.dig(:data, :delta, :text)
-              AssistantStreamEvent.new(type: :text_delta, content_index:, delta:)
+              accumulator.push({ type: :text_delta, delta: }, &block)
             when "tool_use"
               delta = chunk.dig(:data, :delta, :partial_json)
-              AssistantStreamEvent.new(type: :tool_delta, content_index:, delta:)
+              accumulator.push({ type: :tool_delta, delta: }, &block)
             end
           when "content_block_stop"
-            content_index = chunk.dig(:data, :index)
-            type = case content_block_types[content_index]
+            case @current_content_block_type
             when "thinking"
-              :reasoning_end
+              accumulator.push({ type: :reasoning_end, delta: "", signature: "" }, &block)
             when "text"
-              :text_end
+              accumulator.push({ type: :text_end, delta: "" }, &block)
             when "tool_use"
-              :tool_end
+              accumulator.push({ type: :tool_end, delta: "" }, &block)
             end
-            AssistantStreamEvent.new(type: type, content_index:, delta: "")
+            @current_content_block_type = nil
           when "message_delta"
             delta = normalize_message_delta(chunk.dig(:data, :delta) || {})
             usage_increment = chunk.dig(:data, :usage) || {}
 
-            AssistantStreamMessageEvent.new(type: :message_delta, usage_increment:, delta:)
+            accumulator.push({ type: :message_delta, usage_increment:, delta: }, &block)
           when "message_stop"
-            AssistantStreamMessageEvent.new(type: :message_end, usage_increment: {}, delta: {})
+            accumulator.push({ type: :message_end }, &block)
           when "ping"
             nil
           when "error"
-            error = chunk.dig(:data, :error) || {}
-            message = error[:message] || "Stream error"
-            code = error[:type]
-
-            if LlmGateway::Errors.context_overflow_message?(message)
-              raise LlmGateway::Errors::PromptTooLong.new(message, code)
-            end
-
-            if code == "overloaded_error"
-              raise LlmGateway::Errors::OverloadError.new(message, code)
-            end
-
-            raise LlmGateway::Errors::APIStatusError.new(message, code)
+            raise_stream_error!(chunk.dig(:data, :error) || {}, overload_codes: [ "overloaded_error" ])
           end
         end
 
         private
 
-        def content_block_types
-          @content_block_types ||= {}
-        end
-
         def normalize_message_delta(delta)
           return delta unless delta[:stop_reason] || delta["stop_reason"]
 

data/lib/llm_gateway/adapters/anthropic_option_mapper.rb

@@ -11,25 +11,67 @@ module LlmGateway
         "xhigh" => 20 * 1024
       }.freeze
 
+      # Source: https://platform.claude.com/docs/en/api/messages/create.md
+      # API: Anthropic Messages Create; accessed 2026-05-18.
+      # Body parameters listed by the API reference: max_tokens, messages, model,
+      # cache_control, container, inference_geo, metadata, output_config,
+      # service_tier, stop_sequences, stream, system, temperature, thinking,
+      # tool_choice, tools, top_k, top_p.
+      # This mapper intentionally excludes transcript/tool/system structural fields
+      # (messages, system, tool_choice, tools) from option handling.
+
+      VALID_OPTIONS = %i[
+        max_tokens
+        model
+        cache_control
+        cache_retention
+        container
+        inference_geo
+        metadata
+        output_config
+        service_tier
+        stop_sequences
+        stream
+        temperature
+        thinking
+        top_k
+        top_p
+      ].freeze
+
+      MANAGED_OPTIONS = %i[
+        reasoning
+        max_completion_tokens
+        response_format
+        cache_key
+        prompt_cache_key
+        prompt_cache_retention
+      ].freeze
+
       module_function
 
       def map(options)
-        mapped_options = options.reject { |key, _| %i[reasoning max_completion_tokens response_format prompt_cache_retention cache_key prompt_cache_key].include?(key) }
+        mapped_options = options.reject { |key, _| MANAGED_OPTIONS.include?(key) }
         mapped_options[:max_tokens] = options[:max_completion_tokens] || DEFAULT_MAX_TOKENS
 
-        retention = options[:cache_retention]
-        mapped_options[:cache_retention] = retention unless retention.nil?
-
         response_format = options[:response_format]
         mapped_options[:output_config] = normalize_output_config(response_format) unless response_format.nil?
 
         reasoning = options[:reasoning]
-        return mapped_options if reasoning.nil? || reasoning.to_s == "none"
+        mapped_options[:thinking] = normalize_reasoning(reasoning) unless reasoning.nil? || reasoning.to_s == "none"
 
-        mapped_options[:thinking] = normalize_reasoning(reasoning)
+        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 Anthropic Messages options: #{unknown_options.join(', ')}. " \
+              "Valid options: #{VALID_OPTIONS.join(', ')}."
+      end
+
       def normalize_output_config(response_format)
         format_type = response_format.is_a?(Hash) ? response_format[:type] || response_format["type"] : response_format
 

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

@@ -3,7 +3,8 @@
 require_relative "../adapter"
 require_relative "../openai/acts_like_chat_completions"
 require_relative "../input_message_sanitizer"
-require_relative "../openai/chat_completions/input_mapper"
+require_relative "../openai/chat_completions/stream_mapper"
+require_relative "input_mapper"
 require_relative "option_mapper"
 
 module LlmGateway
@@ -15,7 +16,7 @@ module LlmGateway
         private
 
         def file_output_mapper = nil
-        def stream_mapper = nil
+        def input_mapper = Groq::InputMapper
         def option_mapper = Groq::OptionMapper
 
         def map_input(input)

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "../openai/chat_completions/input_mapper"
+
+module LlmGateway
+  module Adapters
+    module Groq
+      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)
+
+          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
+end

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

@@ -4,16 +4,94 @@ 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.dup
-          mapped_options[:temperature] ||= 0
-          mapped_options[:max_completion_tokens] ||= 20480
-          mapped_options[:response_format] = normalize_response_format(mapped_options[:response_format] || "text")
+          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 }
@@ -21,6 +99,13 @@ module LlmGateway
             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

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

@@ -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