active_genie 0.0.10 → 0.0.18

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

@@ -0,0 +1,54 @@
+require_relative '../../clients/openai_client'
+require_relative './base_config'
+
+module ActiveGenie
+  module Configuration::Providers
+    # Configuration class for the OpenAI API client.
+    # Manages API keys, organization IDs, URLs, model selections, and client instantiation.
+    class OpenaiConfig < BaseConfig
+      NAME = :openai
+
+      # Retrieves the API key.
+      # Falls back to the OPENAI_API_KEY environment variable if not set.
+      # @return [String, nil] The API key.
+      def api_key
+        @api_key || ENV['OPENAI_API_KEY']
+      end
+
+      # Retrieves the base API URL for OpenAI API.
+      # Defaults to 'https://api.openai.com/v1'.
+      # @return [String] The API base URL.
+      def api_url
+        @api_url || 'https://api.openai.com/v1'
+      end
+
+      # Lazily initializes and returns an instance of the OpenaiClient.
+      # Passes itself (the config object) to the client's constructor.
+      # @return [ActiveGenie::Clients::OpenaiClient] The client instance.
+      def client
+        @client ||= ::ActiveGenie::Clients::OpenaiClient.new(self)
+      end
+
+      # Retrieves the model name designated for the lower tier (e.g., cost-effective, faster).
+      # Defaults to 'gpt-4o-mini'.
+      # @return [String] The lower tier model name.
+      def lower_tier_model
+        @lower_tier_model || 'gpt-4o-mini'
+      end
+
+      # Retrieves the model name designated for the middle tier (e.g., balanced performance).
+      # Defaults to 'gpt-4o'.
+      # @return [String] The middle tier model name.
+      def middle_tier_model
+        @middle_tier_model || 'gpt-4o'
+      end
+
+      # 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 || 'o1-preview'
+      end
+    end
+  end
+end

data/lib/active_genie/configuration/providers_config.rb

@@ -5,8 +5,9 @@ module ActiveGenie::Configuration
       @default = nil
     end
 
-    def register(name, provider_class)
+    def register(provider_class)
       @all ||= {}
+      name = provider_class::NAME
       @all[name] = provider_class.new
       define_singleton_method(name) do
         instance_variable_get("@#{name}") || instance_variable_set("@#{name}", @all[name])
@@ -16,11 +17,12 @@ module ActiveGenie::Configuration
     end
 
     def default
-      @default || @all.values.first
+      @default || @all.values.find { |p| p.api_key }.class::NAME
     end
 
-    def all
-      @all
+    def valid
+      valid_provider_keys = @all.keys.select { |k| @all[k].valid? }
+      @all.slice(*valid_provider_keys)
     end
 
     def to_h(config = {})
@@ -32,6 +34,7 @@ module ActiveGenie::Configuration
     end
 
     private
+
     attr_writer :default
   end
 end

data/lib/active_genie/configuration/runtime_config.rb

@@ -0,0 +1,35 @@
+module ActiveGenie::Configuration
+  class RuntimeConfig
+    attr_writer :max_tokens, :temperature, :model, :provider, :api_key, :max_retries
+
+    def max_tokens
+      @max_tokens ||= 4096
+    end
+
+    def temperature
+      @temperature ||= 0.1
+    end
+
+    def model
+      @model
+    end
+
+    def provider
+      @provider ||= ActiveGenie.configuration.providers.default
+    end
+
+    def api_key
+      @api_key
+    end
+
+    def max_retries
+      @max_retries ||= 3
+    end
+
+    def to_h(config = {})
+      {
+        max_tokens:, temperature:, model:, provider:, api_key:, max_retries:,
+      }.merge(config)
+    end
+  end
+end

data/lib/active_genie/configuration.rb

@@ -1,6 +1,10 @@
 require_relative 'configuration/providers_config'
-require_relative 'configuration/openai_config'
+require_relative 'configuration/providers/openai_config'
+require_relative 'configuration/providers/google_config'
+require_relative 'configuration/providers/anthropic_config'
+require_relative 'configuration/providers/deepseek_config'
 require_relative 'configuration/log_config'
+require_relative 'configuration/runtime_config'
 
 module ActiveGenie
   module Configuration
@@ -9,7 +13,10 @@ module ActiveGenie
     def providers
       @providers ||= begin 
         p = ProvidersConfig.new
-        p.register(:openai, ActiveGenie::Configuration::OpenaiConfig)
+        p.register(ActiveGenie::Configuration::Providers::OpenaiConfig)
+        p.register(ActiveGenie::Configuration::Providers::GoogleConfig)
+        p.register(ActiveGenie::Configuration::Providers::AnthropicConfig)
+        p.register(ActiveGenie::Configuration::Providers::DeepseekConfig)
         p
       end
     end
@@ -18,10 +25,17 @@ module ActiveGenie
       @log ||= LogConfig.new
     end
 
+    def runtime
+      @runtime ||= RuntimeConfig.new
+    end
+
     def to_h(configs = {})
+      normalized_configs = configs.dig(:runtime) ? configs : { runtime: configs }
+
       {
-        providers: providers.to_h(configs.dig(:providers) || {}),
-        log: log.to_h(configs.dig(:log) || {})
+        providers: providers.to_h(normalized_configs.dig(:providers) || {}),
+        log: log.to_h(normalized_configs.dig(:log) || {}),
+        runtime: runtime.to_h(normalized_configs.dig(:runtime) || {})
       }
     end
   end

data/lib/active_genie/data_extractor/README.md

@@ -65,7 +65,6 @@ The `from_informal` method extends the basic extraction by analyzing rhetorical
 - Litotes ("not bad", "isn't terrible")
 - Affirmative expressions ("sure", "no problem")
 - Negative expressions ("nah", "not really")
-- Hedging ("maybe", "I guess")
 
 ### Example
 

data/lib/active_genie/data_extractor/basic.rb

@@ -3,8 +3,8 @@ require_relative '../clients/unified_client'
 
 module ActiveGenie::DataExtractor
   class Basic
-    def self.call(text, data_to_extract, config: {})
-      new(text, data_to_extract, config:).call
+    def self.call(...)
+      new(...).call
     end
 
     # Extracts structured data from text based on a predefined schema.
@@ -37,16 +37,34 @@ module ActiveGenie::DataExtractor
         {  role: 'system', content: PROMPT },
         {  role: 'user', content: @text }
       ]
+
+      properties = data_to_extract_with_explaination
+
       function = {
         name: 'data_extractor',
         description: 'Extract structured and typed data from user messages.',
         schema: {
           type: "object",
-          properties: data_to_extract_with_explaination
+          properties:,
+          required: properties.keys
         }
       }
 
-      ::ActiveGenie::Clients::UnifiedClient.function_calling(messages, function, config:)
+      result = ::ActiveGenie::Clients::UnifiedClient.function_calling(
+        messages,
+        function,
+        model_tier: 'lower_tier',
+        config: @config
+      )
+
+      ActiveGenie::Logger.debug({
+        code: :data_extractor,
+        text: @text[0..30],
+        data_to_extract: @data_to_extract,
+        extracted_data: result
+      })
+
+      result
     end
 
     private
@@ -59,10 +77,6 @@ module ActiveGenie::DataExtractor
     1. **Identify Data Types**: Determine the types of data to collect, such as names, dates, email addresses, phone numbers, etc.
     2. **Extract Information**: Use pattern recognition and language understanding to identify and extract the relevant pieces of data from the user message.
     3. **Categorize Data**: Assign the extracted data to the appropriate predefined fields.
-    4. **Structure Data**: Format the extracted and categorized data in a structured format, such as JSON.
-
-    # Output Format
-    The output should be a JSON object containing fields with their corresponding extracted values. If a value is not found, the field should still be included with a null value.
 
     # Notes
     - Handle missing or partial information gracefully.
@@ -83,16 +97,5 @@ module ActiveGenie::DataExtractor
       
       with_explaination
     end
-
-    def config
-      {
-        all_providers: { model_tier: 'lower_tier' },
-        log: {
-          **(@config.dig(:log) || {}),
-          trace: self.class.name,
-        },
-        **@config
-      }
-    end
   end
 end

data/lib/active_genie/data_extractor/from_informal.rb

@@ -1,7 +1,7 @@
 module ActiveGenie::DataExtractor
   class FromInformal
-    def self.call(text, data_to_extract, config: {})
-      new(text, data_to_extract, config:).call()
+    def self.call(...)
+      new(...).call()
     end
 
     # Extracts data from informal text while also detecting litotes and their meanings.
@@ -30,10 +30,10 @@ module ActiveGenie::DataExtractor
     end
 
     def call
-      response = Basic.call(@text, data_to_extract_with_litote, config:)
+      response = Basic.call(@text, data_to_extract_with_litote, config: @config)
 
       if response['message_litote']
-        response = Basic.call(response['litote_rephrased'], @data_to_extract, config:)
+        response = Basic.call(response['litote_rephrased'], @data_to_extract, config: @config)
       end
 
       response
@@ -54,16 +54,5 @@ module ActiveGenie::DataExtractor
         }
       }
     end
-
-    def config
-      {
-        all_providers: { model_tier: 'lower_tier' },
-        **@config,
-        log: {
-          **@config.dig(:log),
-          trace: self.class.name,
-        },
-      }
-    end
   end
 end

data/lib/active_genie/data_extractor.rb

@@ -10,6 +10,10 @@ module ActiveGenie
       Basic.call(...)
     end
 
+    def call(...)
+      Basic.call(...)
+    end
+
     def from_informal(...)
       FromInformal.call(...)
     end

data/lib/active_genie/logger.rb

@@ -5,41 +5,87 @@ module ActiveGenie
   module Logger
     module_function
 
+    def with_context(context, observer: nil)
+      @context ||= {}
+      @observers ||= []
+      begin
+        @context = @context.merge(context)
+        @observers << observer if observer
+        yield if block_given?
+      ensure
+        @context.delete_if { |key, _| context.key?(key) }
+        @observers.delete(observer)
+      end
+    end
+
     def info(log)
-      save(log, level: :info)
+      call(log, level: :info)
     end
 
     def error(log)
-      save(log, level: :error)
+      call(log, level: :error)
     end
 
     def warn(log)
-      save(log, level: :warn)
+      call(log, level: :warn)
     end
 
     def debug(log)
-      save(log, level: :debug)
+      call(log, level: :debug)
     end
 
     def trace(log)
-      save(log, level: :trace)
+      call(log, level: :trace)
     end
 
-    LOG_LEVELS = { info: 0, error: 1, warn: 2, debug: 3, trace: 4 }.freeze
+    def call(data, level: :info)
+      log = {
+        **(@context || {}),
+        **(data || {}),
+        timestamp: Time.now,
+        level: level.to_s.upcase,
+        process_id: Process.pid
+      }
+
+      append_to_file(log)
+      output(log, level)
+      call_observers(log)
 
-    def save(log, level: :info)
-      return if LOG_LEVELS[log.dig(:log, :log_level)] || -1 < LOG_LEVELS[level]
+      log
+    end
 
-      log[:trace] = log.dig(:trace)&.to_s&.gsub('ActiveGenie::', '')
-      log[:timestamp] = Time.now
-      log[:level] = level.to_s.upcase
-      log[:process_id] = Process.pid
+    # Log Levels
+    # 
+    # LOG_LEVELS defines different levels of logging within the application. 
+    # Each level serves a specific purpose, balancing verbosity and relevance.
+    # 
+    # - :info  -> General log messages providing an overview of application behavior, ensuring readability without excessive detail.
+    # - :warn  -> Indicates unexpected behaviors that do not halt execution but require attention, such as retries, timeouts, or necessary conversions.
+    # - :error -> Represents critical errors that prevent the application from functioning correctly.
+    # - :debug -> Provides detailed logs for debugging, offering the necessary context for audits but with slightly less detail than trace logs.
+    # - :trace -> Logs every external call with the highest level of detail, primarily for auditing or state-saving purposes. These logs do not provide context regarding triggers or reasons.
+    LOG_LEVELS = { info: 0, error: 0, warn: 1, debug: 2, trace: 3 }.freeze
 
+    attr_accessor :context
+    
+    def append_to_file(log)
       FileUtils.mkdir_p('logs')
       File.write('logs/active_genie.log', "#{JSON.generate(log)}\n", mode: 'a')
-      puts log
+    end
 
-      log
+    def output(log, level)
+      config_log_level = LOG_LEVELS[log.dig(:config, :log_level)] || LOG_LEVELS[:info]
+      if config_log_level >= LOG_LEVELS[level]
+        $stdout.puts log
+      else
+        $stdout.print '.'
+      end
+    end
+
+    def call_observers(log)
+      return if @observers.nil? || @observers.size.zero?
+
+      @observers.each { |observer| observer.call(log) }
     end
   end
 end

data/lib/active_genie/{league → ranking}/README.md

@@ -1,22 +1,22 @@
-# league
+# Ranking
 
-The `ActiveGenie::League` module organizes players based on scores derived from textual evaluations and then ranks them using a multi-stage process. It leverages the scoring system from the `ActiveGenie::Scoring` module to assign initial scores, and then applies advanced ranking methods to produce a competitive league.
+The `ActiveGenie::Ranking` module organizes players based on scores derived from textual evaluations and then ranks them using a multi-stage process. It leverages the scoring system from the `ActiveGenie::Scoring` module to assign initial scores, and then applies advanced ranking methods to produce a competitive ranking.
 
 ## Overview
 
-The league system performs the following steps:
+The ranking system performs the following steps:
 
 1. **Initial Scoring**: Each player’s textual content is evaluated using `ActiveGenie::Scoring`. This produces a `score` based on multiple expert reviews.
 
 2. **Elimination of Poor Performers**: Players whose scores show a high coefficient of variation (indicating inconsistency) are progressively eliminated. This ensures that only competitive candidates continue in the ranking process.
 
-3. **ELO Ranking**: If there are more than 10 eligible players, an ELO-based ranking is applied. Battles between players are simulated via `ActiveGenie::Battle`, and scores are updated using an ELO algorithm tailored to the league.
+3. **ELO Ranking**: If there are more than 10 eligible players, an ELO-based ranking is applied. Battles between players are simulated via `ActiveGenie::Battle`, and scores are updated using an ELO algorithm tailored to the ranking.
 
 4. **Free for all Matches**: Finally, the remaining players engage in head-to-head matches where each unique pair competes. Match outcomes (wins, losses, draws) are recorded to finalize the rankings.
 
 ## Components
 
-- **league**: Orchestrates the entire ranking process. Initializes player scores, eliminates outliers, and coordinates ranking rounds.
+- **ranking**: Orchestrates the entire ranking process. Initializes player scores, eliminates outliers, and coordinates ranking rounds.
 
 - **EloRanking**: Applies an ELO-based system to rank players through simulated battles. It updates players’ ELO scores based on match outcomes and predefined rules (including penalties for losses).
 
@@ -24,10 +24,10 @@ The league system performs the following steps:
 
 ## Usage
 
-Call the league using:
+Call the ranking using:
 
 ```ruby
-result = ActiveGenie::League::league.call(players, criteria, config: {})
+result = ActiveGenie::Ranking.call(players, criteria, config: {})
 ```
 
 - `players`: A collection of player instances, each containing textual content to be scored.

data/lib/active_genie/ranking/elo_round.rb

@@ -0,0 +1,134 @@
+require_relative '../battle/basic'
+
+module ActiveGenie::Ranking
+  class EloRound
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(players, criteria, config: {})
+      @players = players
+      @relegation_tier = players.calc_relegation_tier
+      @defender_tier = players.calc_defender_tier
+      @criteria = criteria
+      @config = config
+      @tmp_defenders = []
+      @start_time = Time.now
+      @total_tokens = 0
+      @previous_elo = {}
+      @previous_highest_elo = @defender_tier.max_by(&:elo).elo
+    end
+
+    def call
+      ActiveGenie::Logger.with_context(log_context) do
+        save_previous_elo
+        matches.each do |player_1, player_2|
+          # TODO: battle can take a while, can be parallelized
+          winner, loser = battle(player_1, player_2)
+          next if winner.nil? || loser.nil?
+
+          winner.elo = calculate_new_elo(winner.elo, loser.elo, 1)
+          loser.elo = calculate_new_elo(loser.elo, winner.elo, 0)
+        end
+      end
+
+      ActiveGenie::Logger.info({ code: :elo_round_report, **report })
+
+      report
+    end
+
+    private
+
+    BATTLE_PER_PLAYER = 3
+    K = 32
+
+    def save_previous_elo
+      @previous_elo = @players.map { |player| [player.id, player.elo] }.to_h
+    end
+
+    def matches
+      @relegation_tier.reduce([]) do |matches, attack_player|
+        BATTLE_PER_PLAYER.times do
+          matches << [attack_player, next_defense_player].shuffle
+        end
+        matches
+      end
+    end
+
+    def next_defense_player
+      @tmp_defenders = @defender_tier.shuffle if @tmp_defenders.size.zero?
+
+      @tmp_defenders.pop
+    end
+
+    def battle(player_1, player_2)
+      ActiveGenie::Logger.with_context({ player_1_id: player_1.id, player_2_id: player_2.id }) do
+        result = ActiveGenie::Battle.basic(
+          player_1.content,
+          player_2.content,
+          @criteria,
+          config: @config
+        )
+
+        winner, loser = case result['winner']
+          when 'player_1' then [player_1, player_2]
+          when 'player_2' then [player_2, player_1]
+          when 'draw' then [nil, nil]
+        end
+
+        [winner, loser]
+      end
+    end
+
+    # INFO: Read more about the Elo rating system on https://en.wikipedia.org/wiki/Elo_rating_system
+    def calculate_new_elo(player_rating, opponent_rating, score)
+      expected_score = 1.0 / (1.0 + 10.0 ** ((opponent_rating - player_rating) / 400.0))
+      
+      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(',')
+
+      ranking_unique_key = [relegation_tier_ids, defender_tier_ids, @criteria, @config.to_json].join('-')
+      Digest::MD5.hexdigest(ranking_unique_key)
+    end
+
+    def report
+      {
+        elo_round_id:,
+        players_in_round: players_in_round.map(&:id),
+        battles_count: matches.size,
+        duration_seconds: Time.now - @start_time,
+        total_tokens: @total_tokens,
+        previous_highest_elo: @previous_highest_elo,
+        highest_elo:,
+        highest_elo_diff: highest_elo - @previous_highest_elo,
+        players_elo_diff:,
+      }
+    end
+
+    def players_in_round
+      @defender_tier + @relegation_tier
+    end
+
+    def highest_elo
+      players_in_round.max_by(&:elo).elo
+    end
+
+    def players_elo_diff
+      players_in_round.map do |player|
+        [player.id, player.elo - @previous_elo[player.id]]
+      end.sort_by { |_, diff| -diff }.to_h
+    end
+
+    def log_observer(log)
+      @total_tokens += log[:total_tokens] if log[:code] == :llm_usage
+    end
+  end
+end

data/lib/active_genie/ranking/free_for_all.rb

@@ -0,0 +1,93 @@
+require_relative '../battle/basic'
+
+module ActiveGenie::Ranking
+  class FreeForAll
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(players, criteria, config: {})
+      @players = players
+      @criteria = criteria
+      @config = config
+      @start_time = Time.now
+      @total_tokens = 0
+    end
+
+    def call
+      ActiveGenie::Logger.with_context(log_context, observer: method(:log_observer)) do
+        matches.each do |player_1, player_2|
+          winner, loser = battle(player_1, player_2)
+          
+          if winner.nil? || loser.nil?
+            player_1.draw!
+            player_2.draw!
+          else
+            winner.win!
+            loser.lose!
+          end
+        end
+      end
+
+      ActiveGenie::Logger.info({ code: :free_for_all_report, **report })
+
+      report
+    end
+
+    private
+
+    # TODO: reduce the number of matches based on transitivity.
+    #       For example, if A is better than B, and B is better than C, then battle between A and C should be auto win A
+    def matches
+      @players.eligible.combination(2).to_a
+    end
+
+    def battle(player_1, player_2)
+      result = ActiveGenie::Battle.basic(
+        player_1.content,
+        player_2.content,
+        @criteria,
+        config: @config
+      )
+
+      winner, loser = case result['winner']
+        when 'player_1' then [player_1, player_2, result['reasoning']]
+        when 'player_2' then [player_2, player_1, result['reasoning']]
+        when 'draw' then [nil, nil, result['reasoning']]
+      end
+
+      ActiveGenie::Logger.debug({
+        code: :free_for_all_battle,
+        player_ids: [player_1.id, player_2.id],
+        winner_id: winner&.id,
+        loser_id: loser&.id,
+        reasoning: result['reasoning']
+      })
+
+      [winner, loser]
+    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)
+    end
+
+    def report
+      {
+        free_for_all_id:,
+        battles_count: matches.size,
+        duration_seconds: Time.now - @start_time,
+        total_tokens: @total_tokens,
+      }
+    end
+
+    def log_observer(log)
+      @total_tokens += log[:total_tokens] if log[:code] == :llm_usage
+    end
+  end
+end