Class: OpenRouter::CompletionOptions

Inherits:
Object
  • Object
show all
Defined in:
lib/open_router/completion_options.rb

Overview

CompletionOptions provides a structured way to configure API requests.

Supports all OpenRouter API parameters plus client-side options. Can be used with complete(), stream_complete(), and responses() methods.

Examples:

Simple usage with kwargs (unchanged)

client.complete(messages, model: "gpt-4")

Using CompletionOptions for complex requests

options = OpenRouter::CompletionOptions.new(
  model: "anthropic/claude-3.5-sonnet",
  temperature: 0.7,
  tools: [weather_tool],
  providers: ["anthropic"]
)
client.complete(messages, options)

Merging options with overrides

base_opts = CompletionOptions.new(model: "gpt-4", temperature: 0.5)
client.complete(messages, base_opts, temperature: 0.9)  # overrides temperature

Constant Summary collapse

DEFAULTS =

All supported parameters with their defaults

{
  # Common
  model: "openrouter/auto",
  tools: [],
  tool_choice: nil,
  extras: {},
  # Sampling
  temperature: nil,
  top_p: nil,
  top_k: nil,
  frequency_penalty: nil,
  presence_penalty: nil,
  repetition_penalty: nil,
  min_p: nil,
  top_a: nil,
  seed: nil,
  # Output
  max_tokens: nil,
  max_completion_tokens: nil,
  stop: nil,
  logprobs: nil,
  top_logprobs: nil,
  logit_bias: nil,
  response_format: nil,
  parallel_tool_calls: nil,
  verbosity: nil,
  # OpenRouter routing
  providers: [],
  provider: nil,
  transforms: [],
  plugins: [],
  prediction: nil,
  route: nil,
  metadata: nil,
  user: nil,
  session_id: nil,
  # Responses API
  reasoning: nil,
  # Client-side
  force_structured_output: nil
}.freeze
CLIENT_SIDE_PARAMS =

Parameters that are client-side only (not sent to API)

%i[force_structured_output extras].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(**attrs) ⇒ CompletionOptions

Initialize with keyword arguments

Parameters:

  • attrs (Hash) —

    Parameter values (see DEFAULTS for available keys)



205
206
207
208
209
210
211
212
 
# File 'lib/open_router/completion_options.rb', line 205

def initialize(**attrs)
  DEFAULTS.each do |key, default|
    value = attrs.key?(key) ? attrs[key] : default
    # Deep dup arrays/hashes to prevent mutation of shared defaults
    value = value.dup if value.is_a?(Array) || value.is_a?(Hash)
    instance_variable_set(:"@#{key}", value)
  end
end

Instance Attribute Details

#extras ⇒ Hash

Returns Pass-through for any additional/future API params.

Returns:

  • (Hash) —

    Pass-through for any additional/future API params



40
41
42
 
# File 'lib/open_router/completion_options.rb', line 40

def extras
  @extras
end

#force_structured_output ⇒ Boolean?

Returns Override forced extraction mode for structured outputs true: Force extraction via system message injection false: Use native structured output nil: Auto-determine based on model capability.

Returns:

  • (Boolean, nil) —

    Override forced extraction mode for structured outputs true: Force extraction via system message injection false: Use native structured output nil: Auto-determine based on model capability



154
155
156
 
# File 'lib/open_router/completion_options.rb', line 154

def force_structured_output
  @force_structured_output
end

#frequency_penalty ⇒ Float?

Returns Frequency penalty (-2.0 to 2.0).

Returns:

  • (Float, nil) —

    Frequency penalty (-2.0 to 2.0)



56
57
58
 
# File 'lib/open_router/completion_options.rb', line 56

def frequency_penalty
  @frequency_penalty
end

#logit_bias ⇒ Hash?

Returns Token ID to bias mapping (-100 to 100).

Returns:

  • (Hash, nil) —

    Token ID to bias mapping (-100 to 100)



93
94
95
 
# File 'lib/open_router/completion_options.rb', line 93

def logit_bias
  @logit_bias
end

#logprobs ⇒ Boolean?

Return log probabilities of output tokens

Returns:

  • (Boolean, nil) —

    Return log probabilities of output tokens



87
88
89
 
# File 'lib/open_router/completion_options.rb', line 87

def logprobs
  @logprobs
end

#max_completion_tokens ⇒ Integer?

Returns Preferred max completion tokens limit.

Returns:

  • (Integer, nil) —

    Preferred max completion tokens limit



81
82
83
 
# File 'lib/open_router/completion_options.rb', line 81

def max_completion_tokens
  @max_completion_tokens
end

#max_tokens ⇒ Integer?

Returns Legacy max tokens limit.

Returns:

  • (Integer, nil) —

    Legacy max tokens limit



78
79
80
 
# File 'lib/open_router/completion_options.rb', line 78

def max_tokens
  @max_tokens
end

#metadata ⇒ Hash?

Returns Custom key-value metadata.

Returns:

  • (Hash, nil) —

    Custom key-value metadata



130
131
132
 
# File 'lib/open_router/completion_options.rb', line 130

def metadata
  @metadata
end

#min_p ⇒ Float?

Returns Minimum probability threshold (0.0-1.0).

Returns:

  • (Float, nil) —

    Minimum probability threshold (0.0-1.0)



65
66
67
 
# File 'lib/open_router/completion_options.rb', line 65

def min_p
  @min_p
end

#model ⇒ String+

Returns Model ID or array for fallback routing.

Returns:

  • (String, Array<String>) —

    Model ID or array for fallback routing



31
32
33
 
# File 'lib/open_router/completion_options.rb', line 31

def model
  @model
end

#parallel_tool_calls ⇒ Boolean?

Returns Allow parallel tool calls.

Returns:

  • (Boolean, nil) —

    Allow parallel tool calls



99
100
101
 
# File 'lib/open_router/completion_options.rb', line 99

def parallel_tool_calls
  @parallel_tool_calls
end

#plugins ⇒ Array<Hash>

Returns Plugin configurations.

Returns:

  • (Array<Hash>) —

    Plugin configurations



120
121
122
 
# File 'lib/open_router/completion_options.rb', line 120

def plugins
  @plugins
end

#prediction ⇒ Hash?

Returns Predicted output for latency reduction Format: { type: “content”, content: “predicted text” }.

Returns:

  • (Hash, nil) —

    Predicted output for latency reduction Format: { type: “content”, content: “predicted text” }



124
125
126
 
# File 'lib/open_router/completion_options.rb', line 124

def prediction
  @prediction
end

#presence_penalty ⇒ Float?

Returns Presence penalty (-2.0 to 2.0).

Returns:

  • (Float, nil) —

    Presence penalty (-2.0 to 2.0)



59
60
61
 
# File 'lib/open_router/completion_options.rb', line 59

def presence_penalty
  @presence_penalty
end

#provider ⇒ Hash?

Returns Full provider config (overrides :providers if set) Supports: order, only, ignore, allow_fallbacks, require_parameters, data_collection, zdr, quantizations, sort, max_price, etc.

Returns:

  • (Hash, nil) —

    Full provider config (overrides :providers if set) Supports: order, only, ignore, allow_fallbacks, require_parameters, data_collection, zdr, quantizations, sort, max_price, etc.



114
115
116
 
# File 'lib/open_router/completion_options.rb', line 114

def provider
  @provider
end

#providers ⇒ Array<String>

Returns Simple provider ordering (becomes provider.order).

Returns:

  • (Array<String>) —

    Simple provider ordering (becomes provider.order)



109
110
111
 
# File 'lib/open_router/completion_options.rb', line 109

def providers
  @providers
end

#reasoning ⇒ Hash?

Returns Reasoning configuration for Responses API Format: { effort: “minimal”|“low”|“medium”|“high” }.

Returns:

  • (Hash, nil) —

    Reasoning configuration for Responses API Format: { effort: “minimal”|“low”|“medium”|“high” }



144
145
146
 
# File 'lib/open_router/completion_options.rb', line 144

def reasoning
  @reasoning
end

#repetition_penalty ⇒ Float?

Returns Repetition penalty (0.0-2.0).

Returns:

  • (Float, nil) —

    Repetition penalty (0.0-2.0)



62
63
64
 
# File 'lib/open_router/completion_options.rb', line 62

def repetition_penalty
  @repetition_penalty
end

#response_format ⇒ Hash, ...

Returns Structured output schema/format.

Returns:

  • (Hash, Schema, nil) —

    Structured output schema/format



96
97
98
 
# File 'lib/open_router/completion_options.rb', line 96

def response_format
  @response_format
end

#route ⇒ String?

Returns Routing strategy: “fallback” or “sort”.

Returns:

  • (String, nil) —

    Routing strategy: “fallback” or “sort”



127
128
129
 
# File 'lib/open_router/completion_options.rb', line 127

def route
  @route
end

#seed ⇒ Integer?

Returns Random seed for reproducibility.

Returns:

  • (Integer, nil) —

    Random seed for reproducibility



71
72
73
 
# File 'lib/open_router/completion_options.rb', line 71

def seed
  @seed
end

#session_id ⇒ String?

Returns Session grouping identifier (max 128 chars).

Returns:

  • (String, nil) —

    Session grouping identifier (max 128 chars)



136
137
138
 
# File 'lib/open_router/completion_options.rb', line 136

def session_id
  @session_id
end

#stop ⇒ String, ...

Returns Stop sequences.

Returns:

  • (String, Array<String>, nil) —

    Stop sequences



84
85
86
 
# File 'lib/open_router/completion_options.rb', line 84

def stop
  @stop
end

#temperature ⇒ Float?

Returns Sampling temperature (0.0-2.0, default 1.0).

Returns:

  • (Float, nil) —

    Sampling temperature (0.0-2.0, default 1.0)



47
48
49
 
# File 'lib/open_router/completion_options.rb', line 47

def temperature
  @temperature
end

#tool_choice ⇒ String, ...

Returns Tool selection: “auto”, “none”, “required”, or specific.

Returns:

  • (String, Hash, nil) —

    Tool selection: “auto”, “none”, “required”, or specific



37
38
39
 
# File 'lib/open_router/completion_options.rb', line 37

def tool_choice
  @tool_choice
end

#tools ⇒ Array<Tool, Hash>

Returns Tool/function definitions for function calling.

Returns:

  • (Array<Tool, Hash>) —

    Tool/function definitions for function calling



34
35
36
 
# File 'lib/open_router/completion_options.rb', line 34

def tools
  @tools
end

#top_a ⇒ Float?

Returns Dynamic filtering based on confidence (0.0-1.0).

Returns:

  • (Float, nil) —

    Dynamic filtering based on confidence (0.0-1.0)



68
69
70
 
# File 'lib/open_router/completion_options.rb', line 68

def top_a
  @top_a
end

#top_k ⇒ Integer?

Returns Limits token selection to top K options.

Returns:

  • (Integer, nil) —

    Limits token selection to top K options



53
54
55
 
# File 'lib/open_router/completion_options.rb', line 53

def top_k
  @top_k
end

#top_logprobs ⇒ Integer?

Returns Number of top logprobs to return (0-20).

Returns:

  • (Integer, nil) —

    Number of top logprobs to return (0-20)



90
91
92
 
# File 'lib/open_router/completion_options.rb', line 90

def top_logprobs
  @top_logprobs
end

#top_p ⇒ Float?

Returns Nucleus sampling (0.0-1.0).

Returns:

  • (Float, nil) —

    Nucleus sampling (0.0-1.0)



50
51
52
 
# File 'lib/open_router/completion_options.rb', line 50

def top_p
  @top_p
end

#transforms ⇒ Array<String>

Returns Transform identifiers (e.g., [“middle-out”]).

Returns:

  • (Array<String>) —

    Transform identifiers (e.g., [“middle-out”])



117
118
119
 
# File 'lib/open_router/completion_options.rb', line 117

def transforms
  @transforms
end

#user ⇒ String?

Returns End-user identifier for tracking.

Returns:

  • (String, nil) —

    End-user identifier for tracking



133
134
135
 
# File 'lib/open_router/completion_options.rb', line 133

def user
  @user
end

#verbosity ⇒ Symbol, ...

Returns Output verbosity (:low, :medium, :high).

Returns:

  • (Symbol, String, nil) —

    Output verbosity (:low, :medium, :high)



102
103
104
 
# File 'lib/open_router/completion_options.rb', line 102

def verbosity
  @verbosity
end

Instance Method Details

#fallback_models? ⇒ Boolean

Check if using model fallback (array of models)

Returns:

  • (Boolean) 


261
262
263
 
# File 'lib/open_router/completion_options.rb', line 261

def fallback_models?
  model.is_a?(Array)
end

#merge(**overrides) ⇒ CompletionOptions

Create a new CompletionOptions with merged overrides

Parameters:

  • overrides (Hash) —

    Values to override

Returns:



231
232
233
 
# File 'lib/open_router/completion_options.rb', line 231

def merge(**overrides)
  self.class.new(**to_h.merge(overrides))
end

#response_format? ⇒ Boolean

Check if response format is configured

Returns:

  • (Boolean) 


254
255
256
 
# File 'lib/open_router/completion_options.rb', line 254

def response_format?
  !response_format.nil?
end

#to_api_params ⇒ Hash

Build API request parameters hash Excludes client-side-only options and merges extras

Returns:

  • (Hash) —

    Parameters ready for API request



239
240
241
242
 
# File 'lib/open_router/completion_options.rb', line 239

def to_api_params
  api_params = to_h.reject { |key, _| CLIENT_SIDE_PARAMS.include?(key) }
  api_params.merge(extras || {})
end

#to_h ⇒ Hash

Convert to hash, excluding nil values and empty collections

Returns:

  • (Hash) —

    Non-empty parameter values



217
218
219
220
221
222
223
224
225
 
# File 'lib/open_router/completion_options.rb', line 217

def to_h
  DEFAULTS.keys.each_with_object({}) do |key, hash|
    value = instance_variable_get(:"@#{key}")
    next if value.nil?
    next if value.respond_to?(:empty?) && value.empty?

    hash[key] = value
  end
end

#tools? ⇒ Boolean

Check if this options object has any tools defined

Returns:

  • (Boolean) 


247
248
249
 
# File 'lib/open_router/completion_options.rb', line 247

def tools?
  tools.is_a?(Array) && !tools.empty?
end