active_genie 0.26.5 → 0.26.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad223ae84ac62d9375af07ba18dca9152296cac5e7c432a6fd07118107c4ab6e
-  data.tar.gz: 5faa2d7ad89cf2200296f94892470248a544d86cd37880191777226f121d9cf4
+  metadata.gz: 47ad459a3acb6b1e37b8cc9d30e072fb1a699177a628212a2b33406c7d019ace
+  data.tar.gz: 9ce87f41aa773aae74fa0a822e492263e95d7c4f63aac26eb77a8385351eaa6b
 SHA512:
-  metadata.gz: 2a6bd702967d5948e37fed48a9b92d0c2061b4893579e67d526cb3bf9b71b44889b7a5a457d5c78a768f74d6cc650beb17a52c1ce00bf1a5c7d2dc553d88b866
-  data.tar.gz: 845fecdb4f036ce4a97b99ea54d0f5600544d6ce0b052da99e4533e4555d774ce09bff1dc037d3752f30aabe69acc5b9362ab77eaf17c62b8ebb5244e02b5df8
+  metadata.gz: 3a15a6742977c8f1a38f1eab5e5d9a5ef30d79cfd9db8ba630775f7629cd25486e00b63a2122a01281a303e396a0d5faefdcb4b399a65b4eaaf9aeb50ddac116
+  data.tar.gz: 4f24bee6532d2251e9051067582bc4bcd1e9ef685996ff34eff15416976774387731917f66482c62efc9d205c552fcd3aacb8b73f869005585fd66fd86b89d12

data/README.md

@@ -204,18 +204,22 @@ bundle exec rake active_genie:benchmark[data_extractor]
 
 See the [Benchmark README](benchmark/README.md) for detailed results, methodology, and how to contribute to our test suite.
 
-## Configuration
-
-| Config | Description | Default |
-|--------|-------------|---------|
-| `provider` | LLM provider (openai, anthropic, etc) | `nil` |
-| `model` | Model to use | `nil` |
-| `api_key` | Provider API key | `nil` |
-| `timeout` | Request timeout in seconds | `5` |
-| `max_retries` | Maximum retry attempts | `3` |
+## Basic Configuration
+
+| Config | Type | Description | Default |
+|--------|------|-------------|---------|
+| `llm.provider` | Symbol | LLM provider (openai, anthropic, etc) | `nil` |
+| `llm.model` | String | Model to use | `nil` |
+| `llm.temperature` | Float | Temperature to use | `0` |
+| `llm.max_tokens` | Integer | Maximum tokens to use | `4096` |
+| `llm.max_retries` | Integer | Maximum retry attempts | `3` |
+| `log.output` | Proc | Log output | `->(log) { $stdout.puts log }` |
+| `ranking.score_variation_threshold` | Integer | Score variation threshold | `30` |
 
 > **Note:** Each module can append its own set of configuration, see the individual module documentation for details.
 
+Read all [configuration](lib/active_genie/config/README.md) for all available options.
+
 ## How to create a new provider
 
 ActiveGenie supports adding custom providers to integrate with different LLM services. To create a new provider:

data/VERSION

@@ -1 +1 @@
-0.26.5
+0.26.6

data/lib/active_genie/battle/generalist.rb

@@ -48,14 +48,14 @@ module ActiveGenie
           config: @config
         )
 
-        ActiveGenie::Logger.call({
-                                   code: :battle,
-                                   player_a: @player_a[0..30],
-                                   player_b: @player_b[0..30],
-                                   criteria: @criteria[0..30],
-                                   winner: response['impartial_judge_winner'],
-                                   reasoning: response['impartial_judge_winner_reasoning']
-                                 })
+        @config.logger.call({
+                              code: :battle,
+                              player_a: @player_a[0..30],
+                              player_b: @player_b[0..30],
+                              criteria: @criteria[0..30],
+                              winner: response['impartial_judge_winner'],
+                              reasoning: response['impartial_judge_winner_reasoning']
+                            })
 
         response_formatted(response)
       end

data/lib/active_genie/clients/providers/anthropic_client.rb

@@ -55,7 +55,7 @@ module ActiveGenie
       def request(payload)
         response = post(url, payload, headers:)
 
-        ActiveGenie::Logger.call(
+        @config.logger.call(
           {
             code: :llm_usage,
             input_tokens: response.dig('usage', 'input_tokens'),
@@ -67,7 +67,7 @@ module ActiveGenie
             usage: response['usage']
           }
         )
-        ActiveGenie::Logger.call(
+        @config.logger.call(
           {
             code: :function_calling,
             fine_tune: true,

data/lib/active_genie/clients/providers/base_client.rb

@@ -151,7 +151,7 @@ module ActiveGenie
       #
       # @param details [Hash] Request and response details
       def log_request_details(uri:, request:, response:, start_time:, parsed_response:)
-        ActiveGenie::Logger.call(
+        @config.logger.call(
           {
             code: :http_request,
             uri: uri.to_s,
@@ -176,7 +176,7 @@ module ActiveGenie
           sleep_time = retry_delay * (2**retries)
           retries += 1
 
-          ActiveGenie::Logger.call(
+          @config.logger.call(
             code: :retry_attempt,
             attempt: retries,
             max_retries: max_retries,

data/lib/active_genie/clients/providers/deepseek_client.rb

@@ -32,7 +32,7 @@ module ActiveGenie
                 "Invalid response: #{response}"
         end
 
-        ActiveGenie::Logger.call({ code: :function_calling, fine_tune: true, payload:, response: })
+        @config.logger.call({ code: :function_calling, fine_tune: true, payload:, response: })
 
         response
       end
@@ -44,7 +44,7 @@ module ActiveGenie
 
         return nil if response.nil?
 
-        ActiveGenie::Logger.call(
+        @config.logger.call(
           {
             code: :llm_usage,
             input_tokens: response.dig('usage', 'prompt_tokens'),

data/lib/active_genie/clients/providers/google_client.rb

@@ -34,6 +34,8 @@ module ActiveGenie
         json_string = response&.dig('candidates', 0, 'content', 'parts', 0, 'text')
         return nil if json_string.nil? || json_string.empty?
 
+        @config.logger.call({ code: :function_calling, fine_tune: true, payload:, parsed_response: json_string })
+
         normalize_response(json_string)
       end
 
@@ -48,7 +50,7 @@ module ActiveGenie
       def request(payload, params)
         response = post(url, payload, headers: DEFAULT_HEADERS, params:)
 
-        ActiveGenie::Logger.call(
+        @config.logger.call(
           {
             code: :llm_usage,
             input_tokens: response['usageMetadata']['promptTokenCount'] || 0,
@@ -59,15 +61,6 @@ module ActiveGenie
           }
         )
 
-        ActiveGenie::Logger.call(
-          {
-            code: :function_calling,
-            fine_tune: true,
-            payload:,
-            parsed_response: response&.dig('candidates', 0, 'content', 'parts', 0, 'text')
-          }
-        )
-
         response
       end
 

data/lib/active_genie/clients/providers/openai_client.rb

@@ -29,7 +29,7 @@ module ActiveGenie
 
         raise InvalidResponseError, "Invalid response: #{response}" if response.nil? || response.keys.empty?
 
-        ActiveGenie::Logger.call({ code: :function_calling, fine_tune: true, payload:, response: })
+        @config.logger.call({ code: :function_calling, fine_tune: true, payload:, response: })
 
         response
       end
@@ -41,7 +41,7 @@ module ActiveGenie
 
         return nil if response.nil?
 
-        ActiveGenie::Logger.call(
+        @config.logger.call(
           {
             code: :llm_usage,
             input_tokens: response.dig('usage', 'prompt_tokens'),

data/lib/active_genie/config/README.md

@@ -0,0 +1,235 @@
+# ActiveGenie Configuration
+
+ActiveGenie provides a flexible configuration system that can be customized to suit your needs. This document details all available configuration options.
+
+## Initial Configuration
+
+To configure ActiveGenie, use the `ActiveGenie.configure` block in your application's initialization:
+
+```ruby
+ActiveGenie.configure do |config|
+  # Provider configurations
+  config.providers.openai.api_key = ENV['OPENAI_API_KEY']
+
+  # Log configurations
+  config.log.file_path = 'log/custom_genie.log'
+  config.log.fine_tune_file_path = 'log/fine_tune_genie.log'
+
+  # Other configurations can be added here
+end
+```
+
+## Configuration Sections
+
+### 1. Log Configuration (`config.log`)
+
+The log configuration controls how ActiveGenie handles logging of its operations.
+
+#### Available Settings:
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `file_path` | String | `'log/active_genie.log'` | Path to the main log file where all logs will be written. |
+| `fine_tune_file_path` | String | `'log/active_genie_fine_tune.log'` | Path to the fine-tuning specific log file. |
+| `output` | Proc | `->(log) { $stdout.puts log }` | Custom output handler for logs. Must respond to `call`. |
+| `additional_context` | Hash | `{}` | Additional context to be added to each log entry. |
+
+#### Methods:
+
+- `add_observer(observers: [], scope: {}, &block)`
+  - Adds log observers that will be notified of log events.
+  - `observers`: An array of callable objects or a single callable object.
+  - `scope`: A hash to filter which logs the observer receives.
+  - `block`: A block that will be called for matching logs.
+
+- `remove_observer(observers)`
+  - Removes the specified observers.
+
+#### Example:
+
+```ruby
+ActiveGenie.configure do |config|
+  config.log.file_path = 'log/my_app/genie.log'
+  config.log.fine_tune_file_path = 'log/my_app/fine_tune.log'
+
+  # Add a custom output handler
+  config.log.output = ->(log) { MyLogger.info(log) }
+
+  # Add an observer for specific log events
+  config.log.add_observer(scope: { event: :api_call }) do |log|
+    StatsD.increment("genie.api_calls")
+  end
+end
+```
+
+### 2. LLM Configuration (`config.llm`)
+
+The LLM configuration is used to define settings for interacting with Large Language Models.
+
+#### Available Settings:
+
+| Setting         | Type                | Default                      | Description                                                                                                |
+|-----------------|---------------------|------------------------------|------------------------------------------------------------------------------------------------------------|
+| `model`         | String / nil        | `nil`                        | The specific LLM model to use (e.g., 'gpt-4', 'claude-2').                                                 |
+| `provider`      | Symbol / nil        | `nil`                        | The LLM provider (e.g., `:openai`, `:anthropic`). Set as a string, stored as a symbol.                       |
+| `client`        | Object / nil        | `nil`                        | A pre-configured client instance for the LLM provider. If set, other settings might be ignored.            |
+| `temperature`   | Numeric             | `0`                          | Controls randomness. Higher values (e.g., 0.8) = more random, lower (e.g., 0.2) = more deterministic.        |
+| `max_tokens`    | Integer             | `4096`                       | Maximum number of tokens to generate in the LLM response.                                                  |
+| `max_retries`   | Integer / nil       | `nil`                        | Maximum number of times to retry a failed API call to the LLM.                                             |
+| `retry_delay`   | Numeric / nil       | `nil`                        | Delay (in seconds) between retries for failed API calls.                                                   |
+| `model_tier`    | Enum [lower_tier, middle_tier, higher_tier]              | `'lower_tier'`               | Specifies the model tier, potentially affecting cost/performance. Will be used if `model` is not set.       |
+| `read_timeout`  | Numeric / nil       | `nil`                        | Timeout (in seconds) for reading data from the LLM API.                                                    |
+| `open_timeout`  | Numeric / nil       | `nil`                        | Timeout (in seconds) for establishing a connection to the LLM API.                                         |
+
+#### Example:
+
+```ruby
+ActiveGenie.configure do |config|
+  config.llm.provider = :openai
+  config.llm.model = 'gpt-999'
+  config.llm.temperature = 0.1
+  config.llm.max_tokens = 8000
+  config.llm.max_retries = 1
+  config.llm.retry_delay = 5 # seconds
+  config.llm.model_tier = 'higher_tier' # If model is not set, will use the model tier to select a model
+end
+```
+
+### 4. Providers Configuration (`config.providers`)
+
+The Providers configuration (`config.providers`) manages settings for various Large Language Model (LLM) providers. It allows you to configure multiple providers, set a default, and access individual provider settings. Active Genie automatically loads configurations for supported providers (OpenAI, Anthropic, DeepSeek, Google).
+
+#### Main Provider Settings:
+
+| Setting   | Type                | Default                        | Description                                                                 |
+|-----------|---------------------|--------------------------------|-----------------------------------------------------------------------------|
+| `default` | String / Symbol     | First validly configured provider (often `:openai` if its API key is set) | The name of the default LLM provider to use (e.g., `:openai`, `:anthropic`). You can set this to your preferred provider. |
+
+#### Methods for `config.providers`:
+
+-   `add(provider_classes)`
+    -   Adds one or more custom provider configuration classes. `provider_classes` can be a single class or an array of classes. (Typically not needed for built-in providers).
+-   `remove(provider_classes)`
+    -   Removes one or more provider configurations based on their classes.
+
+#### Example for Main Provider Settings:
+
+```ruby
+ActiveGenie.configure do |config|
+  # Set the default provider to use if not specifying one explicitly in operations
+  config.providers.default = :anthropic
+
+  # Configure individual providers (API keys are often set via ENV variables)
+  config.providers.openai.api_key = ENV['OPENAI_API_KEY']
+  config.providers.anthropic.api_key = ENV['ANTHROPIC_API_KEY']
+  # config.providers.deepseek.api_key = ENV['DEEPSEEK_API_KEY']
+  # config.providers.google.api_key = ENV['GEMINI_API_KEY']
+end
+```
+
+#### Individual Provider Configurations:
+
+The following subsections detail the configurations for each supported LLM provider. Each provider configuration (e.g., `config.providers.openai`) allows setting an `api_key`, `api_url`, and specific model names for `lower_tier_model`, `middle_tier_model`, and `higher_tier_model`.
+
+##### a. OpenAI (`config.providers.openai`)
+
+Internal Name: `:openai`
+
+| Setting             | Type   | Default                               | Description                                                                 |
+|---------------------|--------|---------------------------------------|-----------------------------------------------------------------------------|
+| `api_key`           | String | `ENV['OPENAI_API_KEY']`               | Your OpenAI API key.                                                        |
+| `api_url`           | String | `'https://api.openai.com/v1'`         | Base URL for the OpenAI API.                                                |
+| `lower_tier_model`  | String | `'gpt-4.1-mini'`                      | Model for lower-tier usage (cost-effective, faster).                        |
+| `middle_tier_model` | String | `'gpt-4.1'`                           | Model for middle-tier usage (balanced performance).                         |
+| `higher_tier_model` | String | `'o3-mini'`                           | Model for higher-tier usage (most capable).                                 |
+
+##### b. Anthropic (`config.providers.anthropic`)
+
+Internal Name: `:anthropic`
+
+| Setting             | Type   | Default                                  | Description                                                                 |
+|---------------------|--------|------------------------------------------|-----------------------------------------------------------------------------|
+| `api_key`           | String | `ENV['ANTHROPIC_API_KEY']`               | Your Anthropic API key.                                                     |
+| `api_url`           | String | `'https://api.anthropic.com'`            | Base URL for the Anthropic API.                                             |
+| `anthropic_version` | String | `'2023-06-01'`                           | The API version for Anthropic.                                              |
+| `lower_tier_model`  | String | `'claude-3-5-haiku-20241022'`            | Model for lower-tier usage.                                                 |
+| `middle_tier_model` | String | `'claude-3-7-sonnet-20250219'`           | Model for middle-tier usage.                                                |
+| `higher_tier_model` | String | `'claude-3-opus-20240229'`               | Model for higher-tier usage.                                                |
+
+##### c. DeepSeek (`config.providers.deepseek`)
+
+Internal Name: `:deepseek`
+
+| Setting             | Type   | Default                               | Description                                                                 |
+|---------------------|--------|---------------------------------------|-----------------------------------------------------------------------------|
+| `api_key`           | String | `ENV['DEEPSEEK_API_KEY']`             | Your DeepSeek API key.                                                      |
+| `api_url`           | String | `'https://api.deepseek.com/v1'`       | Base URL for the DeepSeek API.                                              |
+| `lower_tier_model`  | String | `'deepseek-chat'`                     | Model for lower-tier usage.                                                 |
+| `middle_tier_model` | String | `'deepseek-chat'`                     | Model for middle-tier usage.                                                |
+| `higher_tier_model` | String | `'deepseek-reasoner'`                 | Model for higher-tier usage.                                                |
+
+##### d. Google (`config.providers.google`)
+
+Internal Name: `:google`
+
+| Setting             | Type   | Default                                                       | Description                                                                 |
+|---------------------|--------|---------------------------------------------------------------|-----------------------------------------------------------------------------|
+| `api_key`           | String | `ENV['GENERATIVE_LANGUAGE_GOOGLE_API_KEY']` or `ENV['GEMINI_API_KEY']` | Your Google API key for Gemini.                                           |
+| `api_url`           | String | `'https://generativelanguage.googleapis.com'`                 | Base URL for the Google Generative Language API.                            |
+| `lower_tier_model`  | String | `'gemini-2.0-flash-lite'`                                     | Model for lower-tier usage.                                                 |
+| `middle_tier_model` | String | `'gemini-2.0-flash'`                                          | Model for middle-tier usage.                                                |
+| `higher_tier_model` | String | `'gemini-2.5-pro-experimental'`                               | Model for higher-tier usage.                                                |
+
+#### Example for Overriding Individual Provider Settings:
+
+```ruby
+ActiveGenie.configure do |config|
+  config.providers.openai.api_key = 'sk-yourOpenAiKey...'
+  config.providers.openai.middle_tier_model = 'gpt-4o' # Override default middle tier for OpenAI
+
+  config.providers.anthropic.api_key = 'sk-ant-yourAnthropicKey...'
+  config.providers.anthropic.anthropic_version = '2024-02-15' # Override Anthropic API version
+
+  config.providers.google.higher_tier_model = 'gemini-1.5-pro-latest' # Use a specific Google model
+end
+```
+
+### 5. Ranking Configuration (`config.ranking`)
+
+The Ranking configuration (`config.ranking`) deals with settings related to how results or items are ranked.
+
+#### Available Settings:
+
+| Setting                     | Type    | Default | Description                                                                                                |
+|-----------------------------|---------|---------|------------------------------------------------------------------------------------------------------------|
+| `score_variation_threshold` | Integer | `30`    | A threshold (percentage) used to determine significant variations in scores when ranking or comparing items. |
+
+#### Example:
+
+```ruby
+ActiveGenie.configure do |config|
+  config.ranking.score_variation_threshold = 25 # Set to 25%
+end
+```
+
+### 6. Data Extractor Configuration (`config.data_extractor`)
+
+The Data Extractor configuration (`config.data_extractor`) provides settings for how data is extracted and processed, likely from text or other sources using LLMs.
+
+#### Available Settings:
+
+| Setting            | Type    | Default | Description                                                                                             |
+|--------------------|---------|---------|---------------------------------------------------------------------------------------------------------|
+| `with_explanation` | Boolean | `true`  | Whether the data extraction process should also attempt to provide an explanation for the extracted data. |
+| `min_accuracy`     | Integer | `70`    | The minimum accuracy (percentage) required for extracted data to be considered valid or useful.         |
+| `verbose`          | Boolean | `false` | If true, enables more detailed logging or output from the data extraction process.                      |
+
+#### Example:
+
+```ruby
+ActiveGenie.configure do |config|
+  config.data_extractor.with_explanation = false
+  config.data_extractor.min_accuracy = 85
+  config.data_extractor.verbose = true
+end
+```

data/lib/active_genie/config/log_config.rb

@@ -4,6 +4,7 @@ module ActiveGenie
   module Config
     class LogConfig
       attr_writer :file_path, :fine_tune_file_path
+      attr_reader :output, :observers
 
       def file_path
         @file_path || 'log/active_genie.log'
@@ -13,8 +14,12 @@ module ActiveGenie
         @fine_tune_file_path || 'log/active_genie_fine_tune.log'
       end
 
-      def output
-        @output || ->(log) { $stdout.puts log }
+      def additional_context
+        @additional_context || {}
+      end
+
+      def additional_context=(context)
+        @additional_context = additional_context.merge(context).compact
       end
 
       def output=(output)
@@ -23,29 +28,17 @@ module ActiveGenie
         @output = output
       end
 
-      def output_call(log)
-        output&.call(log)
-
-        Array(@observers).each do |obs|
-          next unless obs[:scope].all? { |key, value| log[key.to_sym] == value }
-
-          obs[:observer]&.call(log)
-        rescue StandardError => e
-          ActiveGenie::Logger.call(code: :observer_error, **obs, error: e.message)
-        end
-      end
-
       def add_observer(observers: [], scope: {}, &block)
         @observers ||= []
 
         raise ArgumentError, 'Scope must be a hash' if scope && !scope.is_a?(Hash)
 
-        @observers << { observer: block, scope: } if block_given?
         Array(observers).each do |observer|
           next unless observer.respond_to?(:call)
 
           @observers << { observer:, scope: }
         end
+        @observers << { observer: block, scope: } if block_given?
       end
 
       def remove_observer(observers)
@@ -60,6 +53,10 @@ module ActiveGenie
 
       def merge(config_params = {})
         dup.tap do |config|
+          config_params.compact.each do |key, value|
+            config.send("#{key}=", value) if config.respond_to?("#{key}=")
+          end
+
           config.add_observer(config_params[:observers]) if config_params[:observers]
         end
       end

data/lib/active_genie/config/providers/anthropic_config.rb

@@ -48,8 +48,8 @@ module ActiveGenie
         # Retrieves the model name designated for the upper tier (e.g., most capable).
         # Defaults to 'claude-3-opus'.
         # @return [String] The upper tier model name.
-        def upper_tier_model
-          @upper_tier_model || 'claude-3-opus-20240229'
+        def higher_tier_model
+          @higher_tier_model || 'claude-3-opus-20240229'
         end
       end
     end

data/lib/active_genie/config/providers/deepseek_config.rb

@@ -41,8 +41,8 @@ module ActiveGenie
         # Retrieves the model name designated for the upper tier (e.g., most capable).
         # Defaults to 'deepseek-reasoner'.
         # @return [String] The upper tier model name.
-        def upper_tier_model
-          @upper_tier_model || 'deepseek-reasoner'
+        def higher_tier_model
+          @higher_tier_model || 'deepseek-reasoner'
         end
       end
     end

data/lib/active_genie/config/providers/google_config.rb

@@ -43,8 +43,8 @@ module ActiveGenie
         # Retrieves the model name designated for the upper tier (e.g., most capable).
         # Defaults to 'gemini-2.5-pro-experimental'.
         # @return [String] The upper tier model name.
-        def upper_tier_model
-          @upper_tier_model || 'gemini-2.5-pro-experimental'
+        def higher_tier_model
+          @higher_tier_model || 'gemini-2.5-pro-experimental'
         end
       end
     end

data/lib/active_genie/config/providers/openai_config.rb

@@ -41,8 +41,8 @@ module ActiveGenie
         # Retrieves the model name designated for the upper tier (e.g., most capable).
         # Defaults to 'o1-preview'.
         # @return [String] The upper tier model name.
-        def upper_tier_model
-          @upper_tier_model || 'o3-mini'
+        def higher_tier_model
+          @higher_tier_model || 'o3-mini'
         end
       end
     end

data/lib/active_genie/config/providers/provider_base.rb

@@ -7,7 +7,7 @@ module ActiveGenie
         NAME = :unknown
 
         attr_writer :api_key, :organization, :api_url, :client,
-                    :lower_tier_model, :middle_tier_model, :upper_tier_model
+                    :lower_tier_model, :middle_tier_model, :higher_tier_model
 
         # Maps a symbolic tier (:lower_tier, :middle_tier, :upper_tier) to a specific model name.
         # Falls back to the lower_tier_model if the tier is nil or unrecognized.
@@ -17,7 +17,7 @@ module ActiveGenie
           {
             lower_tier: lower_tier_model,
             middle_tier: middle_tier_model,
-            upper_tier: upper_tier_model
+            upper_tier: higher_tier_model
           }[tier&.to_sym] || lower_tier_model
         end
 
@@ -31,7 +31,7 @@ module ActiveGenie
             api_url:,
             lower_tier_model:,
             middle_tier_model:,
-            upper_tier_model:,
+            higher_tier_model:,
             **config
           }
         end
@@ -80,7 +80,7 @@ module ActiveGenie
         # Retrieves the model name designated for the upper tier (e.g., most capable).
         # Defaults to 'o1-preview'.
         # @return [String] The upper tier model name.
-        def upper_tier_model
+        def higher_tier_model
           raise NotImplementedError, 'Subclasses must implement this method'
         end
       end

data/lib/active_genie/configuration.rb

@@ -38,6 +38,10 @@ module ActiveGenie
       @llm ||= Config::LlmConfig.new
     end
 
+    def logger
+      @logger ||= ActiveGenie::Logger.new(log_config: log)
+    end
+
     SUB_CONFIGS = %w[log providers llm ranking scoring data_extractor battle].freeze
 
     def merge(config_params = {})
@@ -54,20 +58,28 @@ module ActiveGenie
 
         new_configuration.send("#{key}=", new_config)
       end
+      @logger = nil
 
       new_configuration
     end
 
+    # Merges a sub config with the config_params.
+    # Examples:
+    #   config.merge({ 'log' => { file_path: 'log/active_genie.log' } })
+    #   config.merge({ log: { file_path: 'log/active_genie.log' } })
+    #   config.merge({ file_path: 'log/active_genie.log' })
+    # these are all the same
+
     def sub_config_merge(config, key, config_params)
-      if config_params.key?(key.to_s)
+      if config_params&.key?(key.to_s)
         config.merge(config_params[key.to_s])
-      elsif config_params.key?(key.to_sym)
+      elsif config_params&.key?(key.to_sym)
         config.merge(config_params[key.to_sym])
       else
-        config.merge(config_params)
+        config.merge(config_params || {})
       end
     end
 
-    attr_writer :log, :providers, :ranking, :scoring, :data_extractor, :battle, :llm
+    attr_writer :log, :providers, :ranking, :scoring, :data_extractor, :battle, :llm, :logger
   end
 end

data/lib/active_genie/data_extractor/generalist.rb

@@ -87,7 +87,7 @@ module ActiveGenie
           config: @config
         )
 
-        ActiveGenie::Logger.call(
+        @config.logger.call(
           {
             code: :data_extractor,
             text: @text[0..30],

data/lib/active_genie/logger.rb

@@ -4,47 +4,65 @@ require 'json'
 require 'fileutils'
 
 module ActiveGenie
-  module Logger
-    module_function
+  class Logger
+    def initialize(log_config: nil)
+      @log_config = log_config || ActiveGenie.configuration.log
+    end
 
     def call(data)
-      log = {
-        **(@context || {}),
-        **(data || {}),
-        timestamp: Time.now,
-        process_id: Process.pid
-      }
+      log = data.merge(@log_config.additional_context)
+                .merge(
+                  timestamp: Time.now,
+                  process_id: Process.pid
+                )
 
       persist!(log)
-      config.output_call(log)
+      output_call(log)
+      call_observers(log)
 
       log
     end
 
-    def with_context(context, observer: nil)
-      @context ||= {}
-      begin
-        @context = @context.merge(context)
-        config.add_observer(observers: [observer])
-        yield if block_given?
-      ensure
-        @context.delete_if { |key, _| context.key?(key) }
-        config.remove_observer([observer])
+    def merge(log_config = nil)
+      new(log_config:)
+    end
+
+    private
+
+    def call_observers(log)
+      Array(@log_config.observers).each do |observer|
+        next unless observer[:scope].all? { |key, value| log[key.to_sym] == value }
+
+        observer[:observer]&.call(log)
+      rescue StandardError => e
+        call(code: :observer_error, **observer, error: e.message)
       end
     end
 
-    attr_accessor :context
+    def output_call(log)
+      if @log_config.output
+        @log_config.output&.call(log)
+      else
+        $stdout.puts log
+      end
+    rescue StandardError => e
+      call(code: :output_error, error: e.message)
+    end
 
     def persist!(log)
-      file_path = log.key?(:fine_tune) && log[:fine_tune] ? config.fine_tune_file_path : config.file_path
+      file_path = log_to_file_path(log)
       folder_path = File.dirname(file_path)
 
       FileUtils.mkdir_p(folder_path)
       File.write(file_path, "#{JSON.generate(log)}\n", mode: 'a')
     end
 
-    def config
-      ActiveGenie.configuration.log
+    def log_to_file_path(log)
+      if log.key?(:fine_tune) && log[:fine_tune]
+        @log_config.fine_tune_file_path
+      else
+        @log_config.file_path
+      end
     end
   end
 end

data/lib/active_genie/ranking/elo_round.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative '../battle/generalist'
-
 module ActiveGenie
   module Ranking
     class EloRound
@@ -9,27 +7,26 @@ module ActiveGenie
         new(...).call
       end
 
-      def initialize(players, criteria, config: {})
+      def initialize(players, criteria, config: nil)
         @players = players
         @relegation_tier = players.calc_relegation_tier
         @defender_tier = players.calc_defender_tier
         @criteria = criteria
-        @config = config
+        @config = ActiveGenie.configuration.merge(config)
         @tmp_defenders = []
         @total_tokens = 0
-        @previous_elo = {}
+        @previous_elo = @players.to_h { |player| [player.id, player.elo] }
         @previous_highest_elo = @defender_tier.max_by(&:elo).elo
       end
 
       def call
-        @previous_elo = @players.to_h { |player| [player.id, player.elo] }
+        @config.log.add_observer(observers: ->(log) { log_observer(log) })
+        @config.log.additional_context = { elo_round_id: }
 
-        ActiveGenie::Logger.with_context(log_context) do
-          matches.each do |player_a, player_b|
-            # TODO: battle can take a while, can be parallelized
-            winner, loser = battle(player_a, player_b)
-            update_players_elo(winner, loser)
-          end
+        matches.each do |player_a, player_b|
+          # TODO: battle can take a while, can be parallelized
+          winner, loser = battle(player_a, player_b)
+          update_players_elo(winner, loser)
         end
 
         build_report
@@ -62,22 +59,20 @@ module ActiveGenie
       end
 
       def battle(player_a, player_b)
-        ActiveGenie::Logger.with_context({ player_a_id: player_a.id, player_b_id: player_b.id }) do
-          result = ActiveGenie::Battle.call(
-            player_a.content,
-            player_b.content,
-            @criteria,
-            config: @config
-          )
-
-          winner, loser = case result['winner']
-                          when 'player_a' then [player_a, player_b]
-                          when 'player_b' then [player_b, player_a]
-                          when 'draw' then [nil, nil]
-                          end
-
-          [winner, loser]
-        end
+        result = ActiveGenie::Battle.call(
+          player_a.content,
+          player_b.content,
+          @criteria,
+          config: @config.merge(additional_context: { player_a_id: player_a.id, player_b_id: player_b.id })
+        )
+
+        winner, loser = case result['winner']
+                        when 'player_a' then [player_a, player_b]
+                        when 'player_b' then [player_b, player_a]
+                        when 'draw' then [nil, nil]
+                        end
+
+        [winner, loser]
       end
 
       def update_players_elo(winner, loser)
@@ -94,16 +89,14 @@ module ActiveGenie
         player_rating + (K * (score - expected_score)).round
       end
 
-      def log_context
-        { elo_round_id: }
-      end
-
       def elo_round_id
-        relegation_tier_ids = @relegation_tier.map(&:id).join(',')
-        defender_tier_ids = @defender_tier.map(&:id).join(',')
+        @elo_round_id ||= begin
+          relegation_tier_ids = @relegation_tier.map(&:id).join(',')
+          defender_tier_ids = @defender_tier.map(&:id).join(',')
 
-        ranking_unique_key = [relegation_tier_ids, defender_tier_ids, @criteria, @config.to_json].join('-')
-        Digest::MD5.hexdigest(ranking_unique_key)
+          ranking_unique_key = [relegation_tier_ids, defender_tier_ids, @criteria, @config.to_json].join('-')
+          Digest::MD5.hexdigest(ranking_unique_key)
+        end
       end
 
       def build_report
@@ -118,7 +111,7 @@ module ActiveGenie
           players_elo_diff:
         }
 
-        ActiveGenie::Logger.call({ code: :elo_round_report, **report })
+        @config.logger.call({ elo_round_id:, code: :elo_round_report, **report })
 
         report
       end

data/lib/active_genie/ranking/free_for_all.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative '../battle/generalist'
-
 module ActiveGenie
   module Ranking
     class FreeForAll
@@ -9,21 +7,22 @@ module ActiveGenie
         new(...).call
       end
 
-      def initialize(players, criteria, config: {})
+      def initialize(players, criteria, config: nil)
         @players = players
         @criteria = criteria
-        @config = config
+        @config = config || ActiveGenie.configuration
         @start_time = Time.now
         @total_tokens = 0
       end
 
       def call
-        ActiveGenie::Logger.with_context(log_context, observer: ->(log) { log_observer(log) }) do
-          matches.each do |player_a, player_b|
-            winner, loser = battle(player_a, player_b)
+        @config.log.add_observer(observers: ->(log) { log_observer(log) })
+        @config.log.additional_context = { free_for_all_id: }
+
+        matches.each do |player_a, player_b|
+          winner, loser = battle(player_a, player_b)
 
-            update_players_score(winner, loser)
-          end
+          update_players_score(winner, loser)
         end
 
         build_report
@@ -38,26 +37,30 @@ module ActiveGenie
       end
 
       def battle(player_a, player_b)
+        log_context = { player_a_id: player_a.id, player_b_id: player_b.id }
+
         result = ActiveGenie::Battle.call(
           player_a.content,
           player_b.content,
           @criteria,
-          config: @config
+          config: @config.merge(additional_context: log_context)
         )
 
         winner, loser = case result['winner']
-                        when 'player_a' then [player_a, player_b, result['reasoning']]
-                        when 'player_b' then [player_b, player_a, result['reasoning']]
-                        when 'draw' then [nil, nil, result['reasoning']]
+                        when 'player_a' then [player_a, player_b]
+                        when 'player_b' then [player_b, player_a]
+                        when 'draw' then [nil, nil]
                         end
 
-        ActiveGenie::Logger.call({
-                                   code: :free_for_all_battle,
-                                   player_ids: [player_a.id, player_b.id],
-                                   winner_id: winner&.id,
-                                   loser_id: loser&.id,
-                                   reasoning: result['reasoning']
-                                 })
+        @config.logger.call(
+          {
+            **log_context,
+            code: :free_for_all_battle,
+            winner_id: winner&.id,
+            loser_id: loser&.id,
+            reasoning: result['reasoning']
+          }
+        )
 
         [winner, loser]
       end
@@ -74,14 +77,12 @@ module ActiveGenie
         end
       end
 
-      def log_context
-        { free_for_all_id: }
-      end
-
       def free_for_all_id
-        eligible_ids = @players.eligible.map(&:id).join(',')
-        ranking_unique_key = [eligible_ids, @criteria, @config.to_json].join('-')
-        Digest::MD5.hexdigest(ranking_unique_key)
+        @free_for_all_id ||= begin
+          eligible_ids = @players.eligible.map(&:id).join(',')
+          ranking_unique_key = [eligible_ids, @criteria, @config.to_json].join('-')
+          Digest::MD5.hexdigest(ranking_unique_key)
+        end
       end
 
       def build_report
@@ -92,7 +93,7 @@ module ActiveGenie
           total_tokens: @total_tokens
         }
 
-        ActiveGenie::Logger.call({ code: :free_for_all_report, **report })
+        @config.logger.call({ code: :free_for_all_report, **report })
 
         report
       end

data/lib/active_genie/ranking/player.rb

@@ -47,34 +47,26 @@ module ActiveGenie
       end
 
       def score=(value)
-        ActiveGenie::Logger.call({ code: :new_score, player_id: id, score: value }) if value != @score
         @score = value
         @elo = generate_elo_by_score
       end
 
       def elo=(value)
-        ActiveGenie::Logger.call({ code: :new_elo, player_id: id, elo: value }) if value != @elo
         @elo = value || BASE_ELO
       end
 
-      def eliminated=(value)
-        ActiveGenie::Logger.call({ code: :new_eliminated, player_id: id, eliminated: value }) if value != @eliminated
-        @eliminated = value
-      end
+      attr_writer :eliminated
 
       def draw!
         @ffa_draw_count += 1
-        ActiveGenie::Logger.call({ code: :new_ffa_score, player_id: id, result: 'draw', ffa_score: })
       end
 
       def win!
         @ffa_win_count += 1
-        ActiveGenie::Logger.call({ code: :new_ffa_score, player_id: id, result: 'win', ffa_score: })
       end
 
       def lose!
         @ffa_lose_count += 1
-        ActiveGenie::Logger.call({ code: :new_ffa_score, player_id: id, result: 'lose', ffa_score: })
       end
 
       def ffa_score

data/lib/active_genie/ranking/ranking.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'concerns/loggable'
 require_relative 'players_collection'
 require_relative 'free_for_all'
 require_relative 'elo_round'
@@ -32,8 +31,6 @@ require_relative 'ranking_scoring'
 module ActiveGenie
   module Ranking
     class Ranking
-      include ActiveGenie::Concerns::Loggable
-
       def self.call(...)
         new(...).call
       end
@@ -48,20 +45,19 @@ module ActiveGenie
 
       def call
         @players = create_players
+        @config.log.additional_context = { ranking_id: }
 
-        ActiveGenie::Logger.with_context(log_context) do
-          set_initial_player_scores!
-          eliminate_obvious_bad_players!
-
-          while @players.elo_eligible?
-            elo_report = run_elo_round!
-            eliminate_relegation_players!
-            rebalance_players!(elo_report)
-          end
+        set_initial_player_scores!
+        eliminate_obvious_bad_players!
 
-          run_free_for_all!
+        while @players.elo_eligible?
+          elo_report = run_elo_round!
+          eliminate_relegation_players!
+          rebalance_players!(elo_report)
         end
 
+        run_free_for_all!
+
         sorted_players
       end
 
@@ -72,13 +68,18 @@ module ActiveGenie
 
       def create_players
         players = PlayersCollection.new(@param_players)
-        players.each { |p| ActiveGenie::Logger.call({ code: :new_player, player: p.to_h }) }
+        players.each { |p| @config.logger.call({ code: :new_player, player: p.to_h }) }
 
         players
       end
 
       def set_initial_player_scores!
-        RankingScoring.call(@players, @criteria, reviewers: @reviewers, config: @config)
+        RankingScoring.call(
+          @players,
+          @criteria,
+          reviewers: @reviewers,
+          config: @config
+        )
       end
 
       def eliminate_obvious_bad_players!
@@ -88,7 +89,11 @@ module ActiveGenie
       end
 
       def run_elo_round!
-        EloRound.call(@players, @criteria, config: @config)
+        EloRound.call(
+          @players,
+          @criteria,
+          config: @config
+        )
       end
 
       def eliminate_relegation_players!
@@ -106,25 +111,27 @@ module ActiveGenie
       end
 
       def run_free_for_all!
-        FreeForAll.call(@players, @criteria, config: @config)
+        FreeForAll.call(
+          @players,
+          @criteria,
+          config: @config
+        )
       end
 
       def sorted_players
         players = @players.sorted
-        ActiveGenie::Logger.call({ code: :ranking_final, players: players.map(&:to_h) })
+        @config.logger.call({ ranking_id:, code: :ranking_final, players: players.map(&:to_h) })
 
         players.map(&:to_h)
       end
 
-      def log_context
-        { ranking_id: }
-      end
-
       def ranking_id
-        player_ids = @players.map(&:id).join(',')
-        ranking_unique_key = [player_ids, @criteria, @config.to_json].join('-')
+        @ranking_id ||= begin
+          player_ids = @players.map(&:id).join(',')
+          ranking_unique_key = [player_ids, @criteria, @config.to_json].join('-')
 
-        Digest::MD5.hexdigest(ranking_unique_key)
+          Digest::MD5.hexdigest(ranking_unique_key)
+        end
       end
     end
   end

data/lib/active_genie/ranking/ranking_scoring.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative '../scoring/recommended_reviewers'
-
 module ActiveGenie
   module Ranking
     class RankingScoring
@@ -9,7 +7,7 @@ module ActiveGenie
         new(...).call
       end
 
-      def initialize(players, criteria, reviewers: [], config: {})
+      def initialize(players, criteria, reviewers: [], config: nil)
         @players = players
         @criteria = criteria
         @config = ActiveGenie.configuration.merge(config)
@@ -17,12 +15,11 @@ module ActiveGenie
       end
 
       def call
-        ActiveGenie::Logger.with_context(log_context) do
-          @reviewers = generate_reviewers
+        @config.log.additional_context = { ranking_scoring_id: }
+        @reviewers = generate_reviewers
 
-          players_without_score.each do |player|
-            player.score = generate_score(player)
-          end
+        players_without_score.each do |player|
+          player.score = generate_score(player)
         end
       end
 
@@ -40,7 +37,7 @@ module ActiveGenie
           config: @config
         ).values_at('final_score', 'final_reasoning')
 
-        ActiveGenie::Logger.call({ code: :new_score, player_id: player.id, score:, reasoning: })
+        @config.logger.call({ code: :new_score, player_id: player.id, score:, reasoning: })
 
         score
       end
@@ -54,20 +51,18 @@ module ActiveGenie
           config: @config
         ).values_at('reviewer1', 'reviewer2', 'reviewer3')
 
-        ActiveGenie::Logger.call({ code: :new_reviewers, reviewers: [reviewer1, reviewer2, reviewer3] })
+        @config.logger.call({ code: :new_reviewers, reviewers: [reviewer1, reviewer2, reviewer3] })
 
         [reviewer1, reviewer2, reviewer3]
       end
 
-      def log_context
-        { ranking_scoring_id: }
-      end
-
       def ranking_scoring_id
-        player_ids = players_without_score.map(&:id).join(',')
-        ranking_unique_key = [player_ids, @criteria, @config.to_json].join('-')
+        @ranking_scoring_id ||= begin
+          player_ids = players_without_score.map(&:id).join(',')
+          ranking_unique_key = [player_ids, @criteria, @config.to_json].join('-')
 
-        "#{Digest::MD5.hexdigest(ranking_unique_key)}-scoring"
+          "#{Digest::MD5.hexdigest(ranking_unique_key)}-scoring"
+        end
       end
     end
   end

data/lib/active_genie/scoring/generalist.rb

@@ -52,14 +52,14 @@ module ActiveGenie
 
         result['final_score'] = 0 if result['final_score'].nil?
 
-        ActiveGenie::Logger.call({
-                                   code: :scoring,
-                                   text: @text[0..30],
-                                   criteria: @criteria[0..30],
-                                   reviewers: reviewers,
-                                   score: result['final_score'],
-                                   reasoning: result['final_reasoning']
-                                 })
+        @config.logger.call({
+                              code: :scoring,
+                              text: @text[0..30],
+                              criteria: @criteria[0..30],
+                              reviewers: reviewers,
+                              score: result['final_score'],
+                              reasoning: result['final_reasoning']
+                            })
 
         result
       end

data/lib/tasks/templates/active_genie.rb

@@ -7,7 +7,7 @@ ActiveGenie.configure do |config|
   # config.providers.openai.api_url = 'https://api.openai.com/v1'
   # config.providers.openai.lower_tier_model = 'gpt-4.1-mini'
   # config.providers.openai.middle_tier_model = 'gpt-4.1'
-  # config.providers.openai.upper_tier_model = 'o3-mini'
+  # config.providers.openai.higher_tier_model = 'o3-mini'
   # config.providers.openai.client = ActiveGenie::Providers::Openai::Client.new(config)
 
   # example how add a new provider

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_genie
 version: !ruby/object:Gem::Version
-  version: 0.26.5
+  version: 0.26.6
 platform: ruby
 authors:
 - Radamés Roriz
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-03 00:00:00.000000000 Z
+date: 2025-06-09 00:00:00.000000000 Z
 dependencies: []
 description: |
   The lodash for GenAI, stop reinventing the wheel
@@ -35,6 +35,7 @@ files:
 - lib/active_genie/clients/providers/google_client.rb
 - lib/active_genie/clients/providers/openai_client.rb
 - lib/active_genie/clients/unified_client.rb
+- lib/active_genie/config/README.md
 - lib/active_genie/config/battle_config.rb
 - lib/active_genie/config/data_extractor_config.rb
 - lib/active_genie/config/llm_config.rb
@@ -60,7 +61,6 @@ files:
 - lib/active_genie/logger.rb
 - lib/active_genie/ranking.rb
 - lib/active_genie/ranking/README.md
-- lib/active_genie/ranking/concerns/loggable.rb
 - lib/active_genie/ranking/elo_round.rb
 - lib/active_genie/ranking/free_for_all.rb
 - lib/active_genie/ranking/player.rb

data/lib/active_genie/ranking/concerns/loggable.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-module ActiveGenie
-  module Concerns
-    module Loggable
-      def self.included(base)
-        base.extend(ClassMethods)
-      end
-
-      module ClassMethods
-        def call_with_log_context(context_method)
-          original_method = instance_method(:call)
-
-          define_method(:call) do |*args, **kwargs, &block|
-            context = send(context_method, *args, **kwargs)
-
-            ActiveGenie::Logger.with_context(context) do
-              original_method.bind(self).call(*args, **kwargs, &block)
-            end
-          end
-        end
-
-        def logger(...)
-          ActiveGenie::Logger.call(...)
-        end
-      end
-    end
-  end
-end