Module: LlmGateway::Adapters::OpenAI::ChatCompletions::OptionMapper

Defined in:
lib/llm_gateway/adapters/openai/chat_completions/option_mapper.rb

Constant Summary collapse

DEFAULT_MAX_COMPLETION_TOKENS = 
20_480
VALID_REASONING_LEVELS = 
%w[low medium high xhigh].freeze
VALID_OPTIONS =

Source: 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.

%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

Class Method Summary collapse

Class Method Details

.map(options) ⇒ Object 



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/llm_gateway/adapters/openai/chat_completions/option_mapper.rb', line 68

def map(options)
  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?

  if mapped_options[:prompt_cache_key] && !mapped_options[:prompt_cache_retention]
    mapped_options[:prompt_cache_retention] = normalize_cache_retention("short")
  end

  if cache_retention.to_s == "none"
    mapped_options.delete(:prompt_cache_key)
    mapped_options.delete(:prompt_cache_retention)
  end

  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

.normalize_cache_retention(cache_retention) ⇒ Object 



105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/llm_gateway/adapters/openai/chat_completions/option_mapper.rb', line 105

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

.normalize_reasoning_effort(reasoning) ⇒ Object

Raises:

  • (ArgumentError) 


119
120
121
122
123
124
 
# File 'lib/llm_gateway/adapters/openai/chat_completions/option_mapper.rb', line 119

def normalize_reasoning_effort(reasoning)
  effort = reasoning.to_s
  return effort if VALID_REASONING_LEVELS.include?(effort)

  raise ArgumentError, "Invalid reasoning '#{reasoning}'. Use 'none', 'low', 'medium', 'high', or 'xhigh'."
end

.validate_options!(mapped_options) ⇒ Object

Raises:

  • (ArgumentError) 


96
97
98
99
100
101
102
103
 
# File 'lib/llm_gateway/adapters/openai/chat_completions/option_mapper.rb', line 96

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