llm_gateway 0.4.0 → 0.6.0

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

@@ -5,25 +5,115 @@ module LlmGateway
     module OpenAI
       module ChatCompletions
         module OptionMapper
-          include LlmGateway::Adapters::OpenAI::PromptCacheOptionMapper
-
+          DEFAULT_MAX_COMPLETION_TOKENS = 20_480
           VALID_REASONING_LEVELS = %w[low medium high xhigh].freeze
 
+          # Source: https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create/index.md
+          # API: OpenAI Chat Completions Create; accessed 2026-05-18.
+          # Body parameters listed by the API reference: messages, model, audio,
+          # frequency_penalty, function_call, functions, logit_bias, logprobs,
+          # max_completion_tokens, max_tokens, metadata, modalities, n,
+          # parallel_tool_calls, prediction, presence_penalty, prompt_cache_key,
+          # prompt_cache_retention, reasoning_effort, response_format,
+          # safety_identifier, seed, service_tier, stop, store, stream,
+          # stream_options, temperature, tool_choice, tools, top_logprobs, top_p,
+          # user, verbosity, web_search_options.
+          # This mapper intentionally excludes transcript/tool structural fields
+          # (messages, tools) from option handling.
+
+          VALID_OPTIONS = %i[
+            model
+            audio
+            frequency_penalty
+            function_call
+            functions
+            logit_bias
+            logprobs
+            max_completion_tokens
+            max_tokens
+            metadata
+            modalities
+            n
+            parallel_tool_calls
+            prediction
+            presence_penalty
+            prompt_cache_key
+            prompt_cache_retention
+            reasoning_effort
+            response_format
+            safety_identifier
+            seed
+            service_tier
+            stop
+            store
+            stream
+            stream_options
+            temperature
+            tool_choice
+            top_logprobs
+            top_p
+            user
+            verbosity
+            web_search_options
+          ].freeze
+
+          MANAGED_OPTIONS = %i[
+            reasoning
+            cache_key
+            cache_retention
+          ].freeze
+
           module_function
 
           def map(options)
-            mapped_options = options.dup
-            mapped_options[:max_completion_tokens] ||= 20_480
+            mapped_options = options.reject { |key, _| MANAGED_OPTIONS.include?(key) }
+            mapped_options[:max_completion_tokens] = options[:max_completion_tokens] || DEFAULT_MAX_COMPLETION_TOKENS
+
+            cache_key = options[:cache_key]
+            mapped_options[:prompt_cache_key] = cache_key unless cache_key.nil?
+
+            cache_retention = options[:cache_retention]
+            mapped_options[:prompt_cache_retention] = normalize_cache_retention(cache_retention) \
+              unless cache_retention.nil?
 
-            map_cache_key!(mapped_options)
-            map_prompt_cache_retention!(mapped_options)
+            if mapped_options[:prompt_cache_key] && !mapped_options[:prompt_cache_retention]
+              mapped_options[:prompt_cache_retention] = normalize_cache_retention("short")
+            end
 
-            return mapped_options unless mapped_options.key?(:reasoning)
+            if cache_retention.to_s == "none"
+              mapped_options.delete(:prompt_cache_key)
+              mapped_options.delete(:prompt_cache_retention)
+            end
 
-            reasoning = mapped_options.delete(:reasoning)
-            return mapped_options if reasoning.nil? || reasoning.to_s == "none"
+            reasoning = options[:reasoning]
+            mapped_options[:reasoning_effort] = normalize_reasoning_effort(reasoning) \
+              unless reasoning.nil? || reasoning.to_s == "none"
+
+            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 OpenAI Chat Completions options: #{unknown_options.join(', ')}. " \
+                  "Valid options: #{VALID_OPTIONS.join(', ')}."
+          end
 
-            mapped_options.merge(reasoning_effort: normalize_reasoning_effort(reasoning))
+          def normalize_cache_retention(cache_retention)
+            case cache_retention.to_s
+            when "short"
+              "in_memory"
+            when "long"
+              "24h"
+            when "none"
+              nil
+            else
+              raise ArgumentError,
+                    "Invalid cache_retention '#{cache_retention}'. Use 'short', 'long', or 'none'."
+            end
           end
 
           def normalize_reasoning_effort(reasoning)

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

@@ -1,188 +1,255 @@
 # frozen_string_literal: true
 
-require_relative "../../structs"
+require_relative "../../stream_mapper"
 
 module LlmGateway
   module Adapters
     module OpenAI
       module ChatCompletions
-        class StreamMapper
-          def map(chunk)
-            queued_event = shift_queued_event
-            return queued_event if queued_event
-
+        class StreamMapper < LlmGateway::Adapters::StreamMapper
+          def map(chunk, &block)
             data = chunk[:data] || {}
             raise_stream_error!(data) if chunk[:event] == "error" || data[:error] || data[:type] == "error"
 
-            choices = data[:choices] || []
+            push_patches(patches_for(data), &block)
+          end
 
-            if choices.empty?
-              return message_event(
-                delta: pending_finish_delta,
-                usage_increment: usage_increment(data)
-              )
-            end
+          private
+
+          def patches_for(data)
+            choices = data[:choices] || []
+            return final_usage_patches(data) if choices.empty?
 
             choice = choices.first || {}
             delta = choice[:delta] || {}
-            finish_reason = choice[:finish_reason]
+            patches = []
+            active_block_type = accumulator.active_block_type
+            active_tool = active_tool_block
+
+            append_patches(patches, message_start_patches(data, delta))
+
+            active_block_type, active_tool = append_patches(
+              patches,
+              reasoning_patches(delta[:reasoning], active_block_type:),
+              active_block_type,
+              active_tool
+            )
+            active_block_type, active_tool = append_patches(
+              patches,
+              text_patches(delta[:content], active_block_type:),
+              active_block_type,
+              active_tool
+            )
+            delta.fetch(:tool_calls, []).each do |tool_call|
+              active_block_type, active_tool = append_patches(
+                patches,
+                patches_for_tool_call(tool_call, active_block_type:, active_tool:),
+                active_block_type,
+                active_tool
+              )
+            end
+            append_patches(patches, finish_patches(choice[:finish_reason], active_block_type:))
 
-            event = map_choice_delta(data, choice, delta)
-            return event if event
+            patches
+          end
 
-            return finish_event_for(finish_reason) if finish_reason
+          def append_patches(patches, new_patches, active_block_type = nil, active_tool = nil)
+            patches.concat(new_patches)
+
+            new_patches.each do |patch|
+              case patch[:type]
+              when :text_start
+                active_block_type = :text
+                active_tool = nil
+              when :reasoning_start
+                active_block_type = :reasoning
+                active_tool = nil
+              when :tool_start
+                active_block_type = :tool
+                active_tool = { id: patch[:id], name: patch[:name] }
+              when :text_end, :reasoning_end, :tool_end
+                active_block_type = nil
+                active_tool = nil
+              end
+            end
 
-            nil
+            [ active_block_type, active_tool ]
           end
 
-          private
+          def message_start_patches(data, delta)
+            return [] unless accumulator.message_hash.empty?
 
-          def map_choice_delta(data, choice, delta)
-            if !message_started? && delta[:tool_calls]&.any?
-              @message_started = true
-              stash_message_attributes(data, delta)
-              return tool_event(delta[:tool_calls].first)
-            end
+            return [] unless delta.key?(:role) ||
+                             data[:id] ||
+                             data[:model] ||
+                             delta[:content] ||
+                             delta[:reasoning] ||
+                             delta[:tool_calls]&.any?
 
-            if !message_started? && (delta.key?(:role) || data[:id] || data[:model])
-              @message_started = true
-              return AssistantStreamMessageEvent.new(
+            [
+              {
                 type: :message_start,
                 delta: {
                   id: data[:id],
                   model: data[:model],
-                  role: delta[:role]
-                }.compact,
-                usage_increment: {}
-              )
-            end
-
-            if (content = delta[:content]) && !content.empty?
-              return text_event(content, choice[:index] || 0)
-            end
-
-            return tool_event(delta[:tool_calls].first) if delta[:tool_calls]&.any?
+                  role: delta[:role] || "assistant",
+                  timestamp: timestamp_milliseconds(data[:created])
+                }.compact
+              }
+            ]
+          end
 
-            nil
+          # Groq exposes OpenAI-compatible chat completion chunks, but may include
+          # `delta.reasoning` before normal `delta.content`.
+          def reasoning_patches(reasoning, active_block_type: accumulator.active_block_type)
+            return [] if reasoning.to_s.empty?
+
+            [
+              *close_active_non_reasoning_patches(active_block_type:),
+              {
+                type: active_block_type == :reasoning ? :reasoning_delta : :reasoning_start,
+                delta: reasoning,
+                signature: ""
+              }
+            ]
           end
 
-          def finish_event_for(finish_reason)
-            normalized = normalize_stop_reason(finish_reason)
-            stash_pending_finish_delta(stop_reason: normalized)
+          def text_patches(content, active_block_type: accumulator.active_block_type)
+            return [] if content.to_s.empty?
 
-            case normalized
-            when "tool_use"
-              AssistantStreamEvent.new(type: :tool_end, content_index: last_started_tool_index || 0, delta: "")
-            else
-              AssistantStreamEvent.new(type: :text_end, content_index: last_started_text_index || 0, delta: "")
-            end
+            [
+              *close_active_non_text_patches(active_block_type:),
+              {
+                type: active_block_type == :text ? :text_delta : :text_start,
+                delta: content
+              }
+            ]
           end
 
-          def message_event(delta:, usage_increment: {})
-            AssistantStreamMessageEvent.new(
-              type: pending_message_attributes.empty? ? :message_delta : :message_start,
-              delta: pending_message_attributes.merge(delta),
-              usage_increment:
-            ).tap do
-              clear_pending_message_attributes
-              clear_pending_finish_delta
+          def patches_for_tool_call(tool_call, active_block_type: accumulator.active_block_type, active_tool: active_tool_block)
+            id = tool_call[:id]
+            name = tool_call.dig(:function, :name)
+            arguments = tool_call.dig(:function, :arguments).to_s
+
+            patches = []
+
+            if id || name
+              if active_block_type == :tool
+                patches.concat(close_active_block_patches(active_block_type:)) if new_active_tool?(id, name, active_tool:)
+              else
+                patches.concat(close_active_non_tool_patches(active_block_type:))
+              end
+
+              unless active_block_type == :tool && patches.empty?
+                patches << {
+                  type: :tool_start,
+                  delta: "",
+                  id: id,
+                  name: name
+                }
+              end
             end
-          end
 
-          def usage_increment(data)
-            usage = data[:usage] || {}
-
-            {
-              input_tokens: usage[:prompt_tokens] || 0,
-              cache_creation_input_tokens: 0,
-              cache_read_input_tokens: usage.dig(:prompt_tokens_details, :cached_tokens) || 0,
-              output_tokens: usage[:completion_tokens] || 0,
-              reasoning_tokens: usage.dig(:completion_tokens_details, :reasoning_tokens) || 0
-            }
+            patches << { type: :tool_delta, delta: arguments } unless arguments.empty?
+            patches
           end
 
-          def text_event(content, content_index)
-            @last_started_text_index = content_index
+          def new_active_tool?(id, name, active_tool: active_tool_block)
+            return true unless active_tool
 
-            if started_text_blocks.include?(content_index)
-              AssistantStreamEvent.new(type: :text_delta, content_index:, delta: content)
-            else
-              started_text_blocks << content_index
-              AssistantStreamEvent.new(type: :text_start, content_index:, delta: content)
-            end
+            (id && active_tool[:id] != id) || (name && active_tool[:name] != name)
           end
 
-          def tool_event(tool_call)
-            tool_index = tool_call[:index] || 0
-            @last_started_tool_index = tool_index
-            function = tool_call[:function] || {}
-            arguments = function[:arguments] || ""
-
-            unless started_tool_blocks.include?(tool_index)
-              pending_tool_calls[tool_index] = merge_tool_call(pending_tool_calls[tool_index], tool_call)
-              pending = pending_tool_calls[tool_index]
+          def active_tool_block
+            return nil unless accumulator.active_tool?
 
-              return nil unless pending[:id] && pending.dig(:function, :name)
+            accumulator.blocks.reverse.find { |block| block&.fetch(:type, nil) == "tool_use" }
+          end
 
-              started_tool_blocks << tool_index
-              return AssistantToolStartEvent.new(
-                type: :tool_start,
-                content_index: tool_index,
-                delta: "",
-                id: pending[:id],
-                name: pending.dig(:function, :name)
-              )
+          def close_active_block_patches(active_block_type: accumulator.active_block_type)
+            case active_block_type
+            when :text
+              [ { type: :text_end, delta: "" } ]
+            when :reasoning
+              [ { type: :reasoning_end, delta: "", signature: "" } ]
+            when :tool
+              [ { type: :tool_end, delta: "" } ]
+            else
+              []
             end
-
-            AssistantStreamEvent.new(type: :tool_delta, content_index: tool_index, delta: arguments)
           end
 
-          def stash_message_attributes(data, delta)
-            @pending_message_attributes = {
-              id: data[:id],
-              model: data[:model],
-              role: delta[:role]
-            }.compact
+          def close_active_non_text_patches(active_block_type: accumulator.active_block_type)
+            active_block_type == :text ? [] : close_active_block_patches(active_block_type:)
           end
 
-          def pending_message_attributes
-            @pending_message_attributes ||= {}
+          def close_active_non_reasoning_patches(active_block_type: accumulator.active_block_type)
+            active_block_type == :reasoning ? [] : close_active_block_patches(active_block_type:)
           end
 
-          def clear_pending_message_attributes
-            @pending_message_attributes = {}
+          def close_active_non_tool_patches(active_block_type: accumulator.active_block_type)
+            active_block_type == :tool ? [] : close_active_block_patches(active_block_type:)
           end
 
-          def stash_pending_finish_delta(delta)
-            @pending_finish_delta = pending_finish_delta.merge(delta)
-          end
+          def finish_patches(finish_reason, active_block_type: accumulator.active_block_type)
+            return [] unless finish_reason
 
-          def pending_finish_delta
-            @pending_finish_delta ||= {}
+            [
+              *close_active_block_patches(active_block_type:),
+              {
+                type: :message_delta,
+                delta: { stop_reason: normalize_stop_reason(finish_reason) }
+              }
+            ]
           end
 
-          def clear_pending_finish_delta
-            @pending_finish_delta = {}
-          end
+          def final_usage_patches(data)
+            patch = {
+              type: :message_delta,
+              delta: {}
+            }
+            patch[:usage] = usage(data) if data.key?(:usage)
 
-          def merge_tool_call(existing, incoming)
-            existing ||= {}
-            incoming ||= {}
+            [
+              patch,
+              { type: :message_end }
+            ]
+          end
 
-            existing_function = existing[:function] || {}
-            incoming_function = incoming[:function] || {}
+          def usage(data)
+            usage = data[:usage] || {}
+            cache_read = token_count(
+              usage.dig(:prompt_tokens_details, :cached_tokens),
+              usage[:prompt_cache_hit_tokens]
+            )
+            cache_write = token_count(
+              usage.dig(:prompt_tokens_details, :cache_write_tokens),
+              usage[:cache_write_tokens]
+            )
+            prompt_tokens = token_count(usage[:prompt_tokens])
+            input = [ prompt_tokens - cache_read - cache_write, 0 ].max
+            output = token_count(usage[:completion_tokens])
 
             {
-              index: incoming[:index] || existing[:index],
-              id: incoming[:id] || existing[:id],
-              type: incoming[:type] || existing[:type],
-              function: {
-                name: incoming_function[:name] || existing_function[:name],
-                arguments: "#{existing_function[:arguments]}#{incoming_function[:arguments]}"
-              }
+              input:,
+              cache_write:,
+              cache_read:,
+              output:,
+              total: input + cache_write + cache_read + output,
+              raw: usage
             }
           end
 
+          def token_count(*values)
+            values.compact.first.to_i
+          end
+
+          def timestamp_milliseconds(unix_seconds)
+            return nil if unix_seconds.nil?
+
+            (unix_seconds.to_f * 1000).to_i
+          end
+
           def normalize_stop_reason(finish_reason)
             case finish_reason
             when "tool_calls"
@@ -191,50 +258,6 @@ module LlmGateway
               finish_reason
             end
           end
-
-          def message_started?
-            @message_started ||= false
-          end
-
-          def started_text_blocks
-            @started_text_blocks ||= []
-          end
-
-          def started_tool_blocks
-            @started_tool_blocks ||= []
-          end
-
-          def pending_tool_calls
-            @pending_tool_calls ||= {}
-          end
-
-          def last_started_text_index
-            @last_started_text_index
-          end
-
-          def last_started_tool_index
-            @last_started_tool_index
-          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

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

@@ -4,7 +4,6 @@ require_relative "../adapter"
 require_relative "acts_like_chat_completions"
 require_relative "chat_completions/input_mapper"
 require_relative "chat_completions/input_message_sanitizer"
-require_relative "chat_completions/output_mapper"
 require_relative "chat_completions/option_mapper"
 require_relative "file_output_mapper"
 require_relative "chat_completions/stream_mapper"