Class: SwarmSDK::Config

Inherits:
Object
  • Object
show all
Defined in:
lib/swarm_sdk/config.rb

Overview

Centralized configuration for SwarmSDK

Config provides a single entry point for all SwarmSDK configuration, including API keys (proxied to RubyLLM), defaults override, and WebFetch settings.

Priority Order

Configuration values are resolved in this order:

  1. Explicit value (set via SwarmSDK.configure)
  2. Environment variable
  3. Module default (from SwarmSDK::Defaults)

API Key Proxying

API keys are automatically proxied to RubyLLM.config when set, ensuring RubyLLM always has the correct credentials.

Examples:

Basic configuration

SwarmSDK.configure do |config|
  config.openai_api_key = "sk-..."
  config.default_model = "claude-sonnet-4"
  config.agent_request_timeout = 600
end

Testing setup

def setup
  SwarmSDK.reset_config!
end

Constant Summary collapse

API_KEY_MAPPINGS =

API keys that proxy to RubyLLM.config Maps SwarmSDK config key => [RubyLLM config key, ENV variable]

{
  openai_api_key: [:openai_api_key, "OPENAI_API_KEY"],
  openai_api_base: [:openai_api_base, "OPENAI_API_BASE"],
  openai_organization_id: [:openai_organization_id, "OPENAI_ORG_ID"],
  openai_project_id: [:openai_project_id, "OPENAI_PROJECT_ID"],
  anthropic_api_key: [:anthropic_api_key, "ANTHROPIC_API_KEY"],
  gemini_api_key: [:gemini_api_key, "GEMINI_API_KEY"],
  gemini_api_base: [:gemini_api_base, "GEMINI_API_BASE"],
  vertexai_project_id: [:vertexai_project_id, "GOOGLE_CLOUD_PROJECT"],
  vertexai_location: [:vertexai_location, "GOOGLE_CLOUD_LOCATION"],
  deepseek_api_key: [:deepseek_api_key, "DEEPSEEK_API_KEY"],
  mistral_api_key: [:mistral_api_key, "MISTRAL_API_KEY"],
  perplexity_api_key: [:perplexity_api_key, "PERPLEXITY_API_KEY"],
  openrouter_api_key: [:openrouter_api_key, "OPENROUTER_API_KEY"],
  bedrock_api_key: [:bedrock_api_key, "AWS_ACCESS_KEY_ID"],
  bedrock_secret_key: [:bedrock_secret_key, "AWS_SECRET_ACCESS_KEY"],
  bedrock_region: [:bedrock_region, "AWS_REGION"],
  bedrock_session_token: [:bedrock_session_token, "AWS_SESSION_TOKEN"],
  ollama_api_base: [:ollama_api_base, "OLLAMA_API_BASE"],
  gpustack_api_base: [:gpustack_api_base, "GPUSTACK_API_BASE"],
  gpustack_api_key: [:gpustack_api_key, "GPUSTACK_API_KEY"],
}.freeze
RUBYLLM_CONNECTION_MAPPINGS =

RubyLLM connection settings that proxy to RubyLLM.config Maps SwarmSDK config key => [RubyLLM config key, ENV variable, default value]

{
  llm_request_timeout: [:request_timeout, "SWARM_SDK_LLM_REQUEST_TIMEOUT", 300],
  llm_read_timeout: [:read_timeout, "SWARM_SDK_LLM_READ_TIMEOUT", nil], # nil = use request_timeout
  llm_open_timeout: [:open_timeout, "SWARM_SDK_LLM_OPEN_TIMEOUT", 30],
  llm_write_timeout: [:write_timeout, "SWARM_SDK_LLM_WRITE_TIMEOUT", 30],
}.freeze
DEFAULTS_MAPPINGS =

SwarmSDK defaults that can be overridden Maps config key => [ENV variable, default proc]

{
  default_model: ["SWARM_SDK_DEFAULT_MODEL", -> { Defaults::Agent::MODEL }],
  default_provider: ["SWARM_SDK_DEFAULT_PROVIDER", -> { Defaults::Agent::PROVIDER }],
  agent_request_timeout: ["SWARM_SDK_AGENT_REQUEST_TIMEOUT", -> { Defaults::Timeouts::AGENT_REQUEST_SECONDS }],
  bash_command_timeout: ["SWARM_SDK_BASH_COMMAND_TIMEOUT", -> { Defaults::Timeouts::BASH_COMMAND_MS }],
  bash_command_max_timeout: ["SWARM_SDK_BASH_COMMAND_MAX_TIMEOUT", -> { Defaults::Timeouts::BASH_COMMAND_MAX_MS }],
  web_fetch_timeout: ["SWARM_SDK_WEB_FETCH_TIMEOUT", -> { Defaults::Timeouts::WEB_FETCH_SECONDS }],
  hook_shell_timeout: ["SWARM_SDK_HOOK_SHELL_TIMEOUT", -> { Defaults::Timeouts::HOOK_SHELL_SECONDS }],
  transformer_command_timeout: ["SWARM_SDK_TRANSFORMER_COMMAND_TIMEOUT", -> { Defaults::Timeouts::TRANSFORMER_COMMAND_SECONDS }],
  global_concurrency_limit: ["SWARM_SDK_GLOBAL_CONCURRENCY_LIMIT", -> { Defaults::Concurrency::GLOBAL_LIMIT }],
  local_concurrency_limit: ["SWARM_SDK_LOCAL_CONCURRENCY_LIMIT", -> { Defaults::Concurrency::LOCAL_LIMIT }],
  output_character_limit: ["SWARM_SDK_OUTPUT_CHARACTER_LIMIT", -> { Defaults::Limits::OUTPUT_CHARACTERS }],
  read_line_limit: ["SWARM_SDK_READ_LINE_LIMIT", -> { Defaults::Limits::READ_LINES }],
  line_character_limit: ["SWARM_SDK_LINE_CHARACTER_LIMIT", -> { Defaults::Limits::LINE_CHARACTERS }],
  web_fetch_character_limit: ["SWARM_SDK_WEB_FETCH_CHARACTER_LIMIT", -> { Defaults::Limits::WEB_FETCH_CHARACTERS }],
  glob_result_limit: ["SWARM_SDK_GLOB_RESULT_LIMIT", -> { Defaults::Limits::GLOB_RESULTS }],
  scratchpad_entry_size_limit: ["SWARM_SDK_SCRATCHPAD_ENTRY_SIZE_LIMIT", -> { Defaults::Storage::ENTRY_SIZE_BYTES }],
  scratchpad_total_size_limit: ["SWARM_SDK_SCRATCHPAD_TOTAL_SIZE_LIMIT", -> { Defaults::Storage::TOTAL_SIZE_BYTES }],
  context_compression_threshold: ["SWARM_SDK_CONTEXT_COMPRESSION_THRESHOLD", -> { Defaults::Context::COMPRESSION_THRESHOLD_PERCENT }],
  todowrite_reminder_interval: ["SWARM_SDK_TODOWRITE_REMINDER_INTERVAL", -> { Defaults::Context::TODOWRITE_REMINDER_INTERVAL }],
  chars_per_token_prose: ["SWARM_SDK_CHARS_PER_TOKEN_PROSE", -> { Defaults::TokenEstimation::CHARS_PER_TOKEN_PROSE }],
  chars_per_token_code: ["SWARM_SDK_CHARS_PER_TOKEN_CODE", -> { Defaults::TokenEstimation::CHARS_PER_TOKEN_CODE }],
  mcp_log_level: ["SWARM_SDK_MCP_LOG_LEVEL", -> { Defaults::Logging::MCP_LOG_LEVEL }],
  default_execution_timeout: ["SWARM_SDK_DEFAULT_EXECUTION_TIMEOUT", -> { Defaults::Timeouts::EXECUTION_TIMEOUT_SECONDS }],
  default_turn_timeout: ["SWARM_SDK_DEFAULT_TURN_TIMEOUT", -> { Defaults::Timeouts::TURN_TIMEOUT_SECONDS }],
  mcp_request_timeout: ["SWARM_SDK_MCP_REQUEST_TIMEOUT", -> { Defaults::Timeouts::MCP_REQUEST_SECONDS }],
}.freeze
SETTINGS_MAPPINGS =

WebFetch and control settings Maps config key => [ENV variable, default value]

{
  webfetch_provider: ["SWARM_SDK_WEBFETCH_PROVIDER", nil],
  webfetch_model: ["SWARM_SDK_WEBFETCH_MODEL", nil],
  webfetch_base_url: ["SWARM_SDK_WEBFETCH_BASE_URL", nil],
  webfetch_max_tokens: ["SWARM_SDK_WEBFETCH_MAX_TOKENS", 4096],
  allow_filesystem_tools: ["SWARM_SDK_ALLOW_FILESYSTEM_TOOLS", true],
  env_interpolation: ["SWARM_SDK_ENV_INTERPOLATION", true],
  streaming: ["SWARM_SDK_STREAMING", true],
  mcp_ssl_verify: ["SWARM_SDK_MCP_SSL_VERIFY", true],
}.freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Config

Note:

Use Config.instance instead of new for the singleton pattern

Initialize a new Config instance



133
134
135
136
137
138
 
# File 'lib/swarm_sdk/config.rb', line 133

def initialize
  @explicit_values = {}
  @env_values = {}
  @env_loaded = false
  @env_mutex = Mutex.new
end

Class Method Details

.instance ⇒ Config

Get the singleton Config instance

Returns:

  • (Config) —

    The singleton instance



115
116
117
 
# File 'lib/swarm_sdk/config.rb', line 115

def instance
  @instance ||= new
end

.reset! ⇒ void

This method returns an undefined value.

Reset the Config instance

Clears all configuration including explicit values and cached ENV values. Use in tests to ensure clean state.



125
126
127
 
# File 'lib/swarm_sdk/config.rb', line 125

def reset!
  @instance = nil
end

Instance Method Details

#allow_filesystem_tools ⇒ Boolean

Get whether filesystem tools are allowed

Returns:

  • (Boolean) —

    true if allowed



241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/swarm_sdk/config.rb', line 241

SETTINGS_MAPPINGS.each_key do |config_key|
  _env_key, default_value = SETTINGS_MAPPINGS[config_key]

  # Getter with default fallback
  define_method(config_key) do
    ensure_env_loaded!
    if @explicit_values.key?(config_key)
      @explicit_values[config_key]
    elsif @env_values.key?(config_key)
      @env_values[config_key]
    else
      default_value
    end
  end

  # Setter
  define_method("#{config_key}=") do |value|
    @explicit_values[config_key] = value
  end
end

#default_model ⇒ String

Get the default model

Returns:

  • (String) —

    The default model (falls back to Defaults::Agent::MODEL)



216
217
218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/swarm_sdk/config.rb', line 216

DEFAULTS_MAPPINGS.each_key do |config_key|
  _env_key, default_proc = DEFAULTS_MAPPINGS[config_key]

  # Getter with default fallback
  define_method(config_key) do
    ensure_env_loaded!
    @explicit_values[config_key] || @env_values[config_key] || default_proc.call
  end

  # Setter
  define_method("#{config_key}=") do |value|
    @explicit_values[config_key] = value
  end
end

#default_model=(value) ⇒ Object

Set the default model

Parameters:

  • value (String) —

    The default model



216
217
218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/swarm_sdk/config.rb', line 216

DEFAULTS_MAPPINGS.each_key do |config_key|
  _env_key, default_proc = DEFAULTS_MAPPINGS[config_key]

  # Getter with default fallback
  define_method(config_key) do
    ensure_env_loaded!
    @explicit_values[config_key] || @env_values[config_key] || default_proc.call
  end

  # Setter
  define_method("#{config_key}=") do |value|
    @explicit_values[config_key] = value
  end
end

#llm_open_timeout ⇒ Integer

Get the LLM connection open timeout (seconds)

Returns:

  • (Integer) —

    The timeout (default: 30)



184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/swarm_sdk/config.rb', line 184

RUBYLLM_CONNECTION_MAPPINGS.each_key do |config_key|
  ruby_llm_key, _env_key, default_value = RUBYLLM_CONNECTION_MAPPINGS[config_key]

  # Getter with default fallback
  define_method(config_key) do
    ensure_env_loaded!
    if @explicit_values.key?(config_key)
      @explicit_values[config_key]
    elsif @env_values.key?(config_key)
      @env_values[config_key]
    else
      default_value
    end
  end

  # Setter with RubyLLM proxying
  define_method("#{config_key}=") do |value|
    @explicit_values[config_key] = value
    RubyLLM.config.public_send("#{ruby_llm_key}=", value)
  end
end

#llm_read_timeout ⇒ Integer?

Get the LLM read timeout (seconds) - time to wait between chunks

Returns:

  • (Integer, nil) —

    The timeout (nil = use request_timeout)



184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/swarm_sdk/config.rb', line 184

RUBYLLM_CONNECTION_MAPPINGS.each_key do |config_key|
  ruby_llm_key, _env_key, default_value = RUBYLLM_CONNECTION_MAPPINGS[config_key]

  # Getter with default fallback
  define_method(config_key) do
    ensure_env_loaded!
    if @explicit_values.key?(config_key)
      @explicit_values[config_key]
    elsif @env_values.key?(config_key)
      @env_values[config_key]
    else
      default_value
    end
  end

  # Setter with RubyLLM proxying
  define_method("#{config_key}=") do |value|
    @explicit_values[config_key] = value
    RubyLLM.config.public_send("#{ruby_llm_key}=", value)
  end
end

#llm_request_timeout ⇒ Integer

Get the LLM request timeout (seconds)

Returns:

  • (Integer) —

    The timeout (default: 300)



184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/swarm_sdk/config.rb', line 184

RUBYLLM_CONNECTION_MAPPINGS.each_key do |config_key|
  ruby_llm_key, _env_key, default_value = RUBYLLM_CONNECTION_MAPPINGS[config_key]

  # Getter with default fallback
  define_method(config_key) do
    ensure_env_loaded!
    if @explicit_values.key?(config_key)
      @explicit_values[config_key]
    elsif @env_values.key?(config_key)
      @env_values[config_key]
    else
      default_value
    end
  end

  # Setter with RubyLLM proxying
  define_method("#{config_key}=") do |value|
    @explicit_values[config_key] = value
    RubyLLM.config.public_send("#{ruby_llm_key}=", value)
  end
end

#llm_write_timeout ⇒ Integer

Get the LLM write timeout (seconds)

Returns:

  • (Integer) —

    The timeout (default: 30)



184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/swarm_sdk/config.rb', line 184

RUBYLLM_CONNECTION_MAPPINGS.each_key do |config_key|
  ruby_llm_key, _env_key, default_value = RUBYLLM_CONNECTION_MAPPINGS[config_key]

  # Getter with default fallback
  define_method(config_key) do
    ensure_env_loaded!
    if @explicit_values.key?(config_key)
      @explicit_values[config_key]
    elsif @env_values.key?(config_key)
      @env_values[config_key]
    else
      default_value
    end
  end

  # Setter with RubyLLM proxying
  define_method("#{config_key}=") do |value|
    @explicit_values[config_key] = value
    RubyLLM.config.public_send("#{ruby_llm_key}=", value)
  end
end

#openai_api_key ⇒ String?

Get the OpenAI API key

Returns:

  • (String, nil) —

    The API key



150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/swarm_sdk/config.rb', line 150

API_KEY_MAPPINGS.each_key do |config_key|
  ruby_llm_key, _ = API_KEY_MAPPINGS[config_key]

  # Getter
  define_method(config_key) do
    ensure_env_loaded!
    @explicit_values[config_key] || @env_values[config_key]
  end

  # Setter with RubyLLM proxying
  define_method("#{config_key}=") do |value|
    @explicit_values[config_key] = value
    RubyLLM.config.public_send("#{ruby_llm_key}=", value) if value
  end
end

#openai_api_key=(value) ⇒ Object

Set the OpenAI API key (proxied to RubyLLM)

Parameters:

  • value (String) —

    The API key



150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/swarm_sdk/config.rb', line 150

API_KEY_MAPPINGS.each_key do |config_key|
  ruby_llm_key, _ = API_KEY_MAPPINGS[config_key]

  # Getter
  define_method(config_key) do
    ensure_env_loaded!
    @explicit_values[config_key] || @env_values[config_key]
  end

  # Setter with RubyLLM proxying
  define_method("#{config_key}=") do |value|
    @explicit_values[config_key] = value
    RubyLLM.config.public_send("#{ruby_llm_key}=", value) if value
  end
end

#webfetch_llm_enabled? ⇒ Boolean

Check if WebFetch LLM processing is enabled

WebFetch uses LLM processing when both provider and model are configured.

Returns:

  • (Boolean) —

    true if WebFetch LLM is configured



269
270
271
 
# File 'lib/swarm_sdk/config.rb', line 269

def webfetch_llm_enabled?
  !webfetch_provider.nil? && !webfetch_model.nil?
end

#webfetch_provider ⇒ String?

Get the WebFetch LLM provider

Returns:

  • (String, nil) —

    The provider



241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/swarm_sdk/config.rb', line 241

SETTINGS_MAPPINGS.each_key do |config_key|
  _env_key, default_value = SETTINGS_MAPPINGS[config_key]

  # Getter with default fallback
  define_method(config_key) do
    ensure_env_loaded!
    if @explicit_values.key?(config_key)
      @explicit_values[config_key]
    elsif @env_values.key?(config_key)
      @env_values[config_key]
    else
      default_value
    end
  end

  # Setter
  define_method("#{config_key}=") do |value|
    @explicit_values[config_key] = value
  end
end