Class: RubyLLM::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/ruby_llm/configuration.rb

Overview

A Configuration holds every RubyLLM setting: provider credentials, default models, timeouts, retries, logging, and the model registry. The global instance is yielded by RubyLLM.configure and available as RubyLLM.config.

RubyLLM.configure do |config|
config.openai_api_key = ENV['OPENAI_API_KEY']
config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']
end

RubyLLM.context yields an isolated copy for per-request or per-tenant overrides.

Provider credentials such as openai_api_key are declared by each provider. See https://rubyllm.com/next/configuration-providers/ for provider credentials and endpoint settings.

Assigning an empty or whitespace-only string to any option stores nil, so unset environment variables behave as if the option was never set.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

:nodoc:



295
296
297
298
299
300
 
# File 'lib/ruby_llm/configuration.rb', line 295

def initialize # :nodoc:
  self.class.send(:defaults).each do |key, default|
    value = default.respond_to?(:call) ? instance_exec(&default) : default
    public_send("#{key}=", value)
  end
end

Class Method Details

.option(key, default = nil) ⇒ Object

:nodoc:



28
29
30
31
32
33
34
35
36
37
38
39
40
41
 
# File 'lib/ruby_llm/configuration.rb', line 28

def option(key, default = nil) # :nodoc:
  key = key.to_sym
  return if options.include?(key)

  attr_reader key

  define_method("#{key}=") do |value|
    value = nil if value.is_a?(String) && value.strip.empty?
    instance_variable_set(:"@#{key}", value)
  end

  option_keys << key
  defaults[key] = default
end

.options ⇒ Object

Returns the names of all declared options as an array of symbols, including options registered by providers.



49
50
51
 
# File 'lib/ruby_llm/configuration.rb', line 49

def options
  option_keys.dup
end

.register_provider_options(options) ⇒ Object

:nodoc:



43
44
45
 
# File 'lib/ruby_llm/configuration.rb', line 43

def register_provider_options(options) # :nodoc:
  Array(options).each { |key| option(key, nil) }
end

Instance Method Details

#auto_upload_large_files ⇒ Object

:attr_accessor: auto_upload_large_files

Whether oversized local attachments are uploaded to provider file storage automatically. Default: true.



230
 
# File 'lib/ruby_llm/configuration.rb', line 230

option :auto_upload_large_files, true

#default_embedding_model ⇒ Object

:attr_accessor: default_embedding_model

The model id used by RubyLLM.embed when no model is given. Default: 'text-embedding-3-small'.



76
 
# File 'lib/ruby_llm/configuration.rb', line 76

option :default_embedding_model, 'text-embedding-3-small'

#default_image_model ⇒ Object

:attr_accessor: default_image_model

The model id used by RubyLLM.paint when no model is given. Default: 'gpt-image-2'.



90
 
# File 'lib/ruby_llm/configuration.rb', line 90

option :default_image_model, 'gpt-image-2'

#default_model ⇒ Object

:attr_accessor: default_model

The model id used by RubyLLM.chat when no model is given. Default: 'gpt-5.6'.



69
 
# File 'lib/ruby_llm/configuration.rb', line 69

option :default_model, 'gpt-5.6'

#default_moderation_model ⇒ Object

:attr_accessor: default_moderation_model

The model id used by RubyLLM.moderate when no model is given. Default: 'omni-moderation-latest'.



83
 
# File 'lib/ruby_llm/configuration.rb', line 83

option :default_moderation_model, 'omni-moderation-latest'

#default_ocr_model ⇒ Object

:attr_accessor: default_ocr_model

The model id used by RubyLLM.ocr when no model is given. Default: 'mistral-ocr-latest'.



111
 
# File 'lib/ruby_llm/configuration.rb', line 111

option :default_ocr_model, 'mistral-ocr-latest'

#default_speech_model ⇒ Object

:attr_accessor: default_speech_model

The model id used by RubyLLM.speak when no model is given. Default: 'gpt-4o-mini-tts-2025-12-15'.



97
 
# File 'lib/ruby_llm/configuration.rb', line 97

option :default_speech_model, 'gpt-4o-mini-tts-2025-12-15'

#default_transcription_model ⇒ Object

:attr_accessor: default_transcription_model

The model id used by RubyLLM.transcribe when no model is given. Default: 'gpt-transcribe'.



104
 
# File 'lib/ruby_llm/configuration.rb', line 104

option :default_transcription_model, 'gpt-transcribe'

#default_video_model ⇒ Object

:attr_accessor: default_video_model

The model id used by RubyLLM.animate when no model is given. Default: 'grok-imagine-video-1.5'.



118
 
# File 'lib/ruby_llm/configuration.rb', line 118

option :default_video_model, 'grok-imagine-video-1.5'

#deprecation_behavior ⇒ Object

:attr_accessor: deprecation_behavior

How deprecation warnings are handled: :warn, :silence, or :raise. Default: :warn.



253
 
# File 'lib/ruby_llm/configuration.rb', line 253

option :deprecation_behavior, :warn

#faraday_adapter ⇒ Object

:attr_accessor: faraday_adapter

Faraday adapter used for HTTP requests. Default: :net_http.



259
 
# File 'lib/ruby_llm/configuration.rb', line 259

option :faraday_adapter, :net_http

#http_proxy ⇒ Object

:attr_accessor: http_proxy

Proxy URL for all requests, such as 'http://proxy.example.com:8080'. HTTP, authenticated, and SOCKS5 proxies are supported. Default: nil.



215
 
# File 'lib/ruby_llm/configuration.rb', line 215

option :http_proxy, nil

#inspect ⇒ Object

Object#inspect reads the instance variable table directly, so credentials only stay out of console and log output when #inspect is built from the redacted #instance_variables.



309
310
311
312
 
# File 'lib/ruby_llm/configuration.rb', line 309

def inspect # :nodoc:
  attributes = instance_variables.map { |ivar| "#{ivar}=#{instance_variable_get(ivar).inspect}" }
  "#<#{self.class.name} #{attributes.join(', ')}>"
end

#instance_variables ⇒ Object

:nodoc:



302
303
304
 
# File 'lib/ruby_llm/configuration.rb', line 302

def instance_variables # :nodoc:
  super.reject { |ivar| ivar.to_s.match?(/(_id|_key|_secret|_token|_credential_provider)$/) }
end

#instrumenter ⇒ Object

:attr_accessor: instrumenter

Object receiving instrumentation events. It must respond to instrument(name, payload) and accept an optional block, like ActiveSupport::Notifications, which Rails apps use automatically. Default: nil.



246
 
# File 'lib/ruby_llm/configuration.rb', line 246

option :instrumenter, nil

#log_file ⇒ Object

:attr_accessor: log_file

Destination for the built-in logger, a path or an IO. Defaults to the RUBYLLM_LOG_FILE environment variable when set, $stdout otherwise.



267
 
# File 'lib/ruby_llm/configuration.rb', line 267

option :log_file, -> { ENV.fetch('RUBYLLM_LOG_FILE', nil) || $stdout }

#log_level ⇒ Object

:attr_accessor: log_level

Severity of the built-in logger. Defaults to Logger::DEBUG when the RUBYLLM_DEBUG environment variable says yes (true, 1, yes, or on), Logger::INFO otherwise.



276
 
# File 'lib/ruby_llm/configuration.rb', line 276

option :log_level, -> { env_says_yes?('RUBYLLM_DEBUG') ? Logger::DEBUG : Logger::INFO }

#log_regexp_timeout ⇒ Object

:attr_accessor: log_regexp_timeout

Timeout in seconds for the regular expressions that scrub logged payloads. Defaults to the global Regexp.timeout, or 1.0 when none is set. Requires Ruby 3.2 or later; on older Rubies setting a value logs a warning.



293
 
# File 'lib/ruby_llm/configuration.rb', line 293

option :log_regexp_timeout, -> { Regexp.respond_to?(:timeout) ? (Regexp.timeout || 1.0) : nil }

#log_regexp_timeout=(value) ⇒ Object

:nodoc:



315
316
317
318
319
320
 
# File 'lib/ruby_llm/configuration.rb', line 315

def log_regexp_timeout=(value) # :nodoc:
  if value && !Regexp.respond_to?(:timeout)
    RubyLLM.logger.warn("log_regexp_timeout is not supported on Ruby #{RUBY_VERSION}")
  end
  @log_regexp_timeout = value
end

#log_stream_debug ⇒ Object

:attr_accessor: log_stream_debug

Whether raw streaming chunks are logged. Defaults to true when the RUBYLLM_STREAM_DEBUG environment variable says yes, false otherwise.



284
 
# File 'lib/ruby_llm/configuration.rb', line 284

option :log_stream_debug, -> { env_says_yes?('RUBYLLM_STREAM_DEBUG') }

#logger ⇒ Object

:attr_accessor: logger

Logger receiving RubyLLM output. When set, it overrides #log_file and #log_level. Default: nil.



237
 
# File 'lib/ruby_llm/configuration.rb', line 237

option :logger, nil

#max_retries ⇒ Object

:attr_accessor: max_retries

Number of times to retry failed requests. Default: 3.



179
 
# File 'lib/ruby_llm/configuration.rb', line 179

option :max_retries, 3

#model_registry_class=(_value) ⇒ Object

Keeps custom 1.x initializers bootable long enough to run the 2.0 upgrade generator. The registry is always RubyLLM-owned in 2.0.



157
158
159
160
161
 
# File 'lib/ruby_llm/configuration.rb', line 157

def model_registry_class=(_value) # :nodoc:
  RubyLLM.deprecator.warn(
    'config.model_registry_class is ignored in RubyLLM 2.0; remove it from your initializer'
  )
end

#model_registry_file ⇒ Object

:attr_accessor: model_registry_file

Path of the writable JSON cache holding the model registry. Defaults to the operating system's user cache directory. The copy bundled with the gem is used until this file exists.



140
 
# File 'lib/ruby_llm/configuration.rb', line 140

option :model_registry_file, -> { Models::Registry.cache_path }

#model_registry_store ⇒ Object

:attr_accessor: model_registry_store

Store object the model registry reads from and persists to. Rails apps using the acts_as helpers set this to the database store automatically. A store must respond to read, returning an array of Model entries, and may respond to write(registry) to let Models#refresh persist. Default: nil (use model_registry_file).



150
 
# File 'lib/ruby_llm/configuration.rb', line 150

option :model_registry_store, nil

#request_timeout ⇒ Object

:attr_accessor: request_timeout

Seconds to wait for a response before timing out. Default: 300.



173
 
# File 'lib/ruby_llm/configuration.rb', line 173

option :request_timeout, 300

#retry_backoff_factor ⇒ Object

:attr_accessor: retry_backoff_factor

Multiplier applied to the retry delay after each attempt. Default: 2.



192
 
# File 'lib/ruby_llm/configuration.rb', line 192

option :retry_backoff_factor, 2

#retry_interval ⇒ Object

:attr_accessor: retry_interval

Initial delay in seconds before the first retry. Default: 0.1.



185
 
# File 'lib/ruby_llm/configuration.rb', line 185

option :retry_interval, 0.1

#retry_interval_randomness ⇒ Object

:attr_accessor: retry_interval_randomness

Random jitter factor applied to retry delays. Default: 0.5.



198
 
# File 'lib/ruby_llm/configuration.rb', line 198

option :retry_interval_randomness, 0.5

#retry_max_interval ⇒ Object

:attr_accessor: retry_max_interval

Longest delay in seconds to wait between retries, including delays requested by the provider through rate-limit headers. When a provider asks for a longer wait, the request fails immediately instead of sleeping. Default: 30.



207
 
# File 'lib/ruby_llm/configuration.rb', line 207

option :retry_max_interval, 30

#tool_concurrency ⇒ Object

:attr_accessor: tool_concurrency

How chats run multiple tool calls from one response: false for sequential execution, true or :threads for threads, :fibers for fibers via the async gem. Default: false.



223
 
# File 'lib/ruby_llm/configuration.rb', line 223

option :tool_concurrency, false

#use_new_acts_as=(_value) ⇒ Object

:nodoc:



163
164
165
166
167
 
# File 'lib/ruby_llm/configuration.rb', line 163

def use_new_acts_as=(_value) # :nodoc:
  RubyLLM.deprecator.warn(
    'config.use_new_acts_as is ignored in RubyLLM 2.0; remove it from your initializer'
  )
end

#video_generation_poll_interval ⇒ Object

:attr_accessor: video_generation_poll_interval

Seconds between status polls while RubyLLM.animate waits for a video job. Default: 5.



132
 
# File 'lib/ruby_llm/configuration.rb', line 132

option :video_generation_poll_interval, 5

#video_generation_timeout ⇒ Object

:attr_accessor: video_generation_timeout

Seconds RubyLLM.animate waits for a video job to finish before raising an error. Default: 600.



125
 
# File 'lib/ruby_llm/configuration.rb', line 125

option :video_generation_timeout, 600