class RubyLLM::Configuration
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 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.
Attributes
Whether oversized local attachments are uploaded to provider file storage automatically. Default: true.
The model id used by RubyLLM.embed when no model is given. Default: 'text-embedding-3-small'.
The model id used by RubyLLM.paint when no model is given. Default: 'gpt-image-2'.
The model id used by RubyLLM.chat when no model is given. Default: 'gpt-5.6'.
The model id used by RubyLLM.moderate when no model is given. Default: 'omni-moderation-latest'.
The model id used by RubyLLM.ocr when no model is given. Default: 'mistral-ocr-latest'.
The model id used by RubyLLM.speak when no model is given. Default: 'gpt-4o-mini-tts-2025-12-15'.
The model id used by RubyLLM.transcribe when no model is given. Default: 'gpt-transcribe'.
The model id used by RubyLLM.animate when no model is given. Default: 'grok-imagine-video-1.5'.
How deprecation warnings are handled: :warn, :silence, or :raise. Default: :warn.
Faraday adapter used for HTTP requests. Default: :net_http.
Proxy URL for all requests, such as 'http://proxy.example.com:8080'. HTTP, authenticated, and SOCKS5 proxies are supported. Default: nil.
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.
Destination for the built-in logger, a path or an IO. Defaults to the RUBYLLM_LOG_FILE environment variable when set, $stdout otherwise.
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.
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.
Whether raw streaming chunks are logged. Defaults to true when the RUBYLLM_STREAM_DEBUG environment variable says yes, false otherwise.
Number of times to retry failed requests. Default: 3.
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.
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).
Seconds to wait for a response before timing out. Default: 300.
Multiplier applied to the retry delay after each attempt. Default: 2.
Initial delay in seconds before the first retry. Default: 0.1.
Random jitter factor applied to retry delays. Default: 0.5.
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.
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.
Seconds between status polls while RubyLLM.animate waits for a video job. Default: 5.
Seconds RubyLLM.animate waits for a video job to finish before raising an error. Default: 600.
Public Class Methods
Source
# File lib/ruby_llm/configuration.rb, line 49 def options option_keys.dup end
Returns the names of all declared options as an array of symbols, including options registered by providers.