llm_gateway 0.4.0 → 0.6.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 = {
@@ -14,81 +14,93 @@ module LlmGateway
               model: chunk.dig(:data, :message, :model),
               role: chunk.dig(:data, :message, :role)
             }
-            usage_increment = chunk.dig(:data, :message, :usage) || {}
-
-            AssistantStreamMessageEvent.new(type: :message_start, usage_increment:, delta:)
+            accumulator.push({ type: :message_start, 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) || {}
+            data = chunk[:data] || {}
+            delta = normalize_message_delta(data[:delta] || {})
+            patch = { type: :message_delta, delta: }
+            patch[:usage] = normalized_usage(data[:usage]) if data.key?(:usage)
 
-            AssistantStreamMessageEvent.new(type: :message_delta, usage_increment:, delta:)
+            accumulator.push(patch, &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]
+            raise_stream_error!(chunk.dig(:data, :error) || {}, overload_codes: [ "overloaded_error" ])
+          end
+        end
 
-            if LlmGateway::Errors.context_overflow_message?(message)
-              raise LlmGateway::Errors::PromptTooLong.new(message, code)
-            end
+        private
 
-            if code == "overloaded_error"
-              raise LlmGateway::Errors::OverloadError.new(message, code)
-            end
+        def normalized_usage(usage)
+          usage = symbolize_keys(usage)
 
-            raise LlmGateway::Errors::APIStatusError.new(message, code)
-          end
+          input = token_count(usage[:input_tokens])
+          cache_write = token_count(usage[:cache_creation_input_tokens])
+          cache_read = token_count(usage[:cache_read_input_tokens])
+          output = token_count(usage[:output_tokens])
+
+          {
+            input:,
+            cache_write:,
+            cache_read:,
+            output:,
+            total: input + cache_write + cache_read + output,
+            raw: usage
+          }
         end
 
-        private
+        def token_count(value)
+          value.to_i
+        end
 
-        def content_block_types
-          @content_block_types ||= {}
+        def symbolize_keys(hash)
+          hash.to_h.transform_keys { |key| key.respond_to?(:to_sym) ? key.to_sym : key }
         end
 
         def normalize_message_delta(delta)

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