Class: ActiveAgent::Configuration

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

Overview

Configuration class for ActiveAgent global settings.

Provides configuration options for generation behavior, error handling, and logging. Configuration can be set globally using the configure method or loaded from a YAML file for provider-specific settings.

Global Configuration

Use configure for framework-level settings like logging.

Provider Configuration

Use YAML configuration files to define provider-specific settings like API keys, models, and parameters. This is the recommended approach for managing multiple generation providers across different environments.

Examples:

Basic configuration

ActiveAgent.configure do |config|
  config.logger = Logger.new(STDOUT)
end

YAML configuration file (config/activeagent.yml)

# Define reusable anchors for common settings
openai: &openai
  service: "OpenAI"
  access_token: <%= Rails.application.credentials.dig(:openai, :access_token) %>

anthropic: &anthropic
  service: "Anthropic"
  access_token: <%= Rails.application.credentials.dig(:anthropic, :access_token) %>

development:
  openai:
    <<: *openai
    model: "gpt-4o-mini"
    temperature: 0.7
  anthropic:
    <<: *anthropic
    model: "claude-3-5-sonnet-20241022"

production:
  openai:
    <<: *openai
    model: "gpt-4o"
    temperature: 0.5

Loading provider configuration

# In config/initializers/activeagent.rb
ActiveAgent.configuration_load(Rails.root.join("config/activeagent.yml"))

Using configured providers in agents

class MyAgent < ActiveAgent::Base
  generate_with :openai  # Uses settings from config/activeagent.yml
end

See Also:

Constant Summary collapse

DEFAULTS =

Default configuration values.

Returns:

  • (Hash) —

    Hash of default configuration values

{}.freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(settings = {}) ⇒ Configuration

Initializes a new Configuration instance with default values.

Sets all configuration attributes to their default values as defined in DEFAULTS. Duplicates values where possible to prevent shared state. Custom settings can be passed to override defaults.

When loading from a YAML file via load, all settings from the environment-specific section are passed as the settings hash, including Initializes a new Configuration instance with optional settings.

Settings typically come from a YAML configuration file loaded via load. The configuration object stores provider-specific settings as nested hashes.

Examples:

With default settings

config = ActiveAgent::Configuration.new

With provider configurations (typically from YAML)

config = ActiveAgent::Configuration.new(
  openai: { service: "OpenAI", model: "gpt-4o" },
  anthropic: { service: "Anthropic", model: "claude-3-5-sonnet-20241022" }
)

Parameters:

  • settings (Hash) (defaults to: {}) —

    Optional settings to load



195
196
197
198
199
 
# File 'lib/active_agent/configuration.rb', line 195

def initialize(settings = {})
  (DEFAULTS.merge(settings)).each do |key, value|
    self[key] = value
  end
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method, *args) ⇒ Object?

Delegates method calls to the [] operator for accessing configuration values.

Allows accessing configuration values using method syntax instead of hash-like access. Returns nil for undefined configuration keys.

Examples:

config.retries        # => true (same as config[:retries])
config.retries_count  # => 3 (same as config[:retries_count])

Parameters:

  • method (Symbol) —

    The method name (configuration key)

  • args (Array) —

    Method arguments (not used)

Returns:

  • (Object, nil) —

    The configuration value or nil



315
316
317
 
# File 'lib/active_agent/configuration.rb', line 315

def method_missing(method, *args)
  self[method]
end

Class Method Details

.load(filename) ⇒ Configuration

Note:

ERB templates are evaluated, allowing you to use Rails credentials, environment variables, or any Ruby code within <%= %> tags.

Loads configuration from a YAML file.

Reads a YAML configuration file, evaluates any ERB templates, and extracts environment-specific settings based on RAILS_ENV or ENV environment variables. Falls back to the root level settings if no environment key is found.

The YAML file contains provider-specific configurations (API keys, models, parameters, retry settings). Provider configurations are stored as nested hashes and can be accessed via the [] operator.

Examples:

Provider-specific configuration with YAML anchors

# config/activeagent.yml
openai: &openai
  service: "OpenAI"
  access_token: <%= Rails.application.credentials.dig(:openai, :access_token) %>
  max_retries: 3

anthropic: &anthropic
  service: "Anthropic"
  access_token: <%= Rails.application.credentials.dig(:anthropic, :access_token) %>
  max_retries: 5

open_router: &open_router
  service: "OpenRouter"
  access_token: <%= Rails.application.credentials.dig(:open_router, :access_token) %>

development:
  openai:
    <<: *openai
    model: "gpt-4o-mini"
    temperature: 0.7
  anthropic:
    <<: *anthropic
    model: "claude-3-5-sonnet-20241022"
  open_router:
    <<: *open_router
    model: "qwen/qwen3-30b-a3b:free"

test:
  openai:
    <<: *openai
    model: "gpt-4o-mini"
  anthropic:
    <<: *anthropic

production:
  openai:
    <<: *openai
    model: "gpt-4o"
    temperature: 0.5
  anthropic:
    <<: *anthropic
    model: "claude-3-5-sonnet-20241022"

Loading and accessing provider configuration

config = ActiveAgent::Configuration.load("config/activeagent.yml")
config[:openai]  # => { "service" => "OpenAI", "model" => "gpt-4o-mini", ... }

Parameters:

  • filename (String) —

    Path to the YAML configuration file

Returns:

  • (Configuration) —

    A new Configuration instance with loaded settings



160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/active_agent/configuration.rb', line 160

def self.load(filename)
  settings = {}

  if File.exist?(filename)
    config_file = YAML.load(ERB.new(File.read(filename)).result, aliases: true)
    env         = ENV["RAILS_ENV"] || ENV["ENV"] || "development"
    settings    = config_file[env] || config_file
  end

  Configuration.new(settings)
end

Instance Method Details

#[](key) ⇒ Object?

Retrieves a configuration value by key.

This method provides hash-like access to provider configurations. Provider configurations are stored as nested hashes.

Examples:

Accessing provider configurations

config[:openai]     # => { "service" => "OpenAI", "model" => "gpt-4o", ... }
config[:anthropic]  # => { "service" => "Anthropic", "model" => "claude-3-5-sonnet-20241022", ... }

Parameters:

  • key (String, Symbol) —

    Configuration key to retrieve

Returns:

  • (Object, nil) —

    The configuration value or nil if not found



212
213
214
 
# File 'lib/active_agent/configuration.rb', line 212

def [](key)
  instance_variable_get("@#{key}")
end

#[]=(key, value) ⇒ Object

Sets a configuration value by key.

Examples:

config[:retries] = false
config["retries_count"] = 5

Parameters:

  • key (String, Symbol) —

    Configuration key to set

  • value (Object) —

    Value to set

Returns:

  • (Object) —

    The value that was set



225
226
227
 
# File 'lib/active_agent/configuration.rb', line 225

def []=(key, value)
  instance_variable_set("@#{key}", convert_to_indifferent_access(value))
end

#deep_dup ⇒ Configuration

Creates a deep duplicate of the configuration.

Recursively duplicates all configuration values to avoid shared state.

Examples:

original = ActiveAgent.configuration
backup = original.deep_dup
backup[:openai] = { service: "OpenAI" }  # doesn't affect original

Returns:

  • (Configuration) —

    A new Configuration instance with duplicated values



266
267
268
269
270
271
272
273
 
# File 'lib/active_agent/configuration.rb', line 266

def deep_dup
  new_config = Configuration.new
  instance_variables.each do |var|
    value = instance_variable_get(var)
    new_config.instance_variable_set(var, deep_dup_value(value))
  end
  new_config
end

#dig(*keys) ⇒ Object?

Extracts nested values using a sequence of keys.

Similar to Hash#dig, traverses nested configuration values safely. Returns nil if any intermediate key doesn’t exist.

Examples:

config.dig(:openai, :model)  # => "gpt-4o"
config.dig("test", "anthropic", "service")  # => "Anthropic"
config.dig(:nonexistent, :key)  # => nil

Parameters:

  • keys (Array<String, Symbol>) —

    Keys to traverse

Returns:

  • (Object, nil) —

    The nested value or nil



241
242
243
244
245
246
247
248
249
250
251
252
253
254
 
# File 'lib/active_agent/configuration.rb', line 241

def dig(*keys)
  keys.reduce(self) do |obj, key|
    break nil unless obj
    if obj.is_a?(Configuration)
      obj[key]
    elsif obj.respond_to?(:dig)
      obj.dig(key)
    elsif obj.respond_to?(:[])
      obj[key]
    else
      nil
    end
  end
end

#logger ⇒ Logger

Gets the logger used by ActiveAgent.

Returns:

  • (Logger) —

    The logger instance

See Also:

  • Base.logger


79
80
81
 
# File 'lib/active_agent/configuration.rb', line 79

def logger
  ActiveAgent::Base.logger
end

#logger=(value) ⇒ Logger

Sets the logger used by ActiveAgent.

Examples:

config.logger = Logger.new(STDOUT)
config.logger.level = Logger::DEBUG

Parameters:

  • value (Logger) —

    The logger instance to use

Returns:

  • (Logger) —

    The logger that was set

See Also:

  • Base.logger=


93
94
95
 
# File 'lib/active_agent/configuration.rb', line 93

def logger=(value)
  ActiveAgent::Base.logger = value
end

#replace(other) ⇒ Configuration

Replaces the current configuration values with those from another configuration.

Copies all instance variables from the source configuration to this one, and removes any instance variables that exist in self but not in other. Useful for restoring configuration state in tests.

Examples:

backup = config.deep_dup
# ... make changes ...
config.replace(backup)  # restore original state

Parameters:

Returns:



288
289
290
291
292
293
294
295
296
297
298
299
300
 
# File 'lib/active_agent/configuration.rb', line 288

def replace(other)
  # Remove variables that exist in self but not in other
  (instance_variables - other.instance_variables).each do |var|
    remove_instance_variable(var)
  end

  # Copy all variables from other to self
  other.instance_variables.each do |var|
    instance_variable_set(var, other.instance_variable_get(var))
  end

  self
end

#respond_to_missing?(method, include_private = false) ⇒ Boolean

Checks if the configuration responds to a method.

Returns true if an instance variable exists for the given method name, allowing proper introspection of dynamically accessible configuration keys.

Parameters:

  • method (Symbol) —

    The method name to check

  • include_private (Boolean) (defaults to: false) —

    Whether to include private methods

Returns:

  • (Boolean) —

    True if the configuration has the key



328
329
330
 
# File 'lib/active_agent/configuration.rb', line 328

def respond_to_missing?(method, include_private = false)
  instance_variable_defined?("@#{method}") || super
end