active_genie 0.0.8 → 0.0.12

data/lib/active_genie/configuration.rb

@@ -1,33 +1,28 @@
-require 'yaml'
+require_relative 'configuration/providers_config'
+require_relative 'configuration/openai_config'
+require_relative 'configuration/log_config'
 
 module ActiveGenie
-  class Configuration
-    attr_accessor :path_to_config
+  module Configuration
+    module_function
 
-    def initialize
-      @path_to_config = File.join('config', 'active_genie.yml')
-    end
-
-    def values
-      return @values if @values
-
-      @values = load_values.transform_keys(&:to_sym)
-      @values.each do |key, _value|
-        @values[key][:model] = key
-        @values[key] = @values[key].transform_keys(&:to_sym)
+    def providers
+      @providers ||= begin 
+        p = ProvidersConfig.new
+        p.register(:openai, ActiveGenie::Configuration::OpenaiConfig)
+        p
       end
     end
 
-    private
-
-    def load_values
-      return {} unless File.exist?(@path_to_config)
+    def log
+      @log ||= LogConfig.new
+    end
 
-      yaml_content = ERB.new(File.read(@path_to_config)).result
-      YAML.safe_load(yaml_content, aliases: true) || {}
-    rescue Psych::SyntaxError => e
-      warn "ActiveGenie.warning: Config file '#{@path_to_config}' is not a valid YAML file (#{e.message}), using default configuration"
-      {}
+    def to_h(configs = {})
+      {
+        providers: providers.to_h(configs.dig(:providers) || {}),
+        log: log.to_h(configs.dig(:log) || {})
+      }
     end
   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
 
@@ -95,7 +94,7 @@ result = ActiveGenie::DataExtractor.from_informal(text, schema)
 
 ## Interface
 
-### `.call(text, data_to_extract, options = {})`
+### `.call(text, data_to_extract, config = {})`
 Extracts structured data from text based on a predefined schema.
 
 #### Parameters
@@ -103,9 +102,9 @@ Extracts structured data from text based on a predefined schema.
 | --- | --- | --- | --- | --- |
 | `text` | `String` | The text to analyze and extract data from | Yes | "John Doe is 25 years old" |
 | `data_to_extract` | `Hash` | Schema defining the data structure to extract | Yes | `{ name: { type: 'string' } }` |
-| `options` | `Hash` | Additional extraction configuration | No | `{ model: "gpt-4" }` |
+| `config` | `Hash` | Additional extraction configuration | No | `{ model: "gpt-4" }` |
 
-#### Options
+#### config
 | Name | Type | Description |
 | --- | --- | --- |
 | `model` | `String` | The model to use for the extraction |
@@ -117,7 +116,7 @@ Extracts structured data from text based on a predefined schema.
 - Explanation field for each extracted value
 - Additional analysis fields when using `from_informal`
 
-### `.from_informal(text, data_to_extract, options = {})`
+### `.from_informal(text, data_to_extract, config = {})`
 Extends basic extraction with rhetorical analysis, particularly for litotes.
 
 #### Additional Return Fields

data/lib/active_genie/data_extractor/basic.rb

@@ -1,9 +1,10 @@
-require_relative '../clients/router.rb'
+
+require_relative '../clients/unified_client'
 
 module ActiveGenie::DataExtractor
   class Basic
-    def self.call(text, data_to_extract, options: {})
-      new(text, data_to_extract, options:).call
+    def self.call(...)
+      new(...).call
     end
 
     # Extracts structured data from text based on a predefined schema.
@@ -11,9 +12,7 @@ module ActiveGenie::DataExtractor
     # @param text [String] The input text to analyze and extract data from
     # @param data_to_extract [Hash] Schema defining the data structure to extract.
     #   Each key in the hash represents a field to extract, and its value defines the expected type and constraints.
-    # @param options [Hash] Additional options for the extraction process
-    #   @option options [String] :model The model to use for the extraction
-    #   @option options [String] :api_key The API key to use for the extraction
+    # @param config [Hash] Additional config for the extraction process
     #
     # @return [Hash] The extracted data matching the schema structure. Each field will include
     #   both the extracted value and an explanation of how it was derived.
@@ -27,10 +26,10 @@ module ActiveGenie::DataExtractor
     #   DataExtractor.call(text, schema)
     #   # => { name: "John Doe", name_explanation: "Found directly in text",
     #   #      age: 25, age_explanation: "Explicitly stated as 25 years old" }
-    def initialize(text, data_to_extract, options: {})
+    def initialize(text, data_to_extract, config: {})
       @text = text
       @data_to_extract = data_to_extract
-      @options = options
+      @config = ActiveGenie::Configuration.to_h(config)
     end
 
     def call
@@ -47,7 +46,12 @@ module ActiveGenie::DataExtractor
         }
       }
 
-      ::ActiveGenie::Clients::Router.function_calling(messages, function, options: @options)
+      ::ActiveGenie::Clients::UnifiedClient.function_calling(
+        messages,
+        function,
+        model_tier: 'lower_tier',
+        config: @config
+      )
     end
 
     private
@@ -60,10 +64,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.

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, options: {})
-      new(text, data_to_extract, options:).call()
+    def self.call(...)
+      new(...).call()
     end
 
     # Extracts data from informal text while also detecting litotes and their meanings.
@@ -9,7 +9,7 @@ module ActiveGenie::DataExtractor
     #
     # @param text [String] The informal text to analyze
     # @param data_to_extract [Hash] Schema defining the data structure to extract
-    # @param options [Hash] Additional options for the extraction process
+    # @param config [Hash] Additional config for the extraction process
     #
     # @return [Hash] The extracted data including litote analysis. In addition to the
     #   schema-defined fields, includes:
@@ -23,17 +23,17 @@ module ActiveGenie::DataExtractor
     #   # => { mood: "positive", mood_explanation: "Speaker views weather favorably",
     #   #      message_litote: true,
     #   #      litote_rephrased: "The weather is good today" }
-    def initialize(text, data_to_extract, options: {})
+    def initialize(text, data_to_extract, config: {})
       @text = text
       @data_to_extract = data_to_extract
-      @options = options
+      @config = ActiveGenie::Configuration.to_h(config)
     end
 
     def call
-      response = Basic.call(@text, data_to_extract_with_litote, options: @options)
+      response = Basic.call(@text, data_to_extract_with_litote, config: @config)
 
       if response['message_litote']
-        response = Basic.call(response['litote_rephrased'], @data_to_extract, options: @options)
+        response = Basic.call(response['litote_rephrased'], @data_to_extract, config: @config)
       end
 
       response

data/lib/active_genie/data_extractor.rb

@@ -2,7 +2,7 @@ require_relative 'data_extractor/basic'
 require_relative 'data_extractor/from_informal'
 
 module ActiveGenie
-  # Extract structured data from text using AI-powered analysis, handling informal language and complex expressions.
+  # See the [DataExtractor README](lib/active_genie/data_extractor/README.md) for more information.
   module DataExtractor
     module_function
 

data/lib/active_genie/logger.rb

@@ -0,0 +1,72 @@
+require 'json'
+require 'fileutils'
+
+module ActiveGenie
+  module Logger
+    module_function
+
+    def with_context(context)
+      @context ||= {}
+      begin
+        @context = @context.merge(context)
+        yield if block_given?
+      ensure
+        @context.delete_if { |key, _| context.key?(key) }
+      end
+    end
+
+    def info(log)
+      save(log, level: :info)
+    end
+
+    def error(log)
+      save(log, level: :error)
+    end
+
+    def warn(log)
+      save(log, level: :warn)
+    end
+
+    def debug(log)
+      save(log, level: :debug)
+    end
+
+    def trace(log)
+      save(log, level: :trace)
+    end
+
+    def save(data, level: :info)
+      log = @context.merge(data || {})
+      log[:timestamp] = Time.now
+      log[:level] = level.to_s.upcase
+      log[:process_id] = Process.pid
+      config_log_level = LOG_LEVELS[log.dig(:config, :log_level)] || LOG_LEVELS[:info]
+
+      FileUtils.mkdir_p('logs')
+      File.write('logs/active_genie.log', "#{JSON.generate(log)}\n", mode: 'a')
+      if config_log_level >= LOG_LEVELS[level]
+        $stdout.puts log
+      else
+        $stdout.print '.'
+      end
+
+      log
+    end
+
+    private
+
+    # 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
+  end
+end

data/lib/active_genie/ranking/README.md

@@ -0,0 +1,43 @@
+# Ranking
+
+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 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 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
+
+- **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).
+
+- **Free for all**: Conducts complete pairwise matches among eligible players to record win/loss/draw statistics and refine the final standings.
+
+## Usage
+
+Call the ranking using:
+
+```ruby
+result = ActiveGenie::Ranking.call(players, criteria, config: {})
+```
+
+- `players`: A collection of player instances, each containing textual content to be scored.
+- `criteria`: A string defining the evaluation criteria used by the scoring system.
+- `config`: A hash of additional parameters for customization (e.g., model, api_key).
+
+The method processes the players through scoring, elimination, and ranking phases, then returns a hash containing the player statistics and rankings.
+
+## Possible improvements
+- Adjust initial criteria to ensure consistency
+- Adjust each player's content to ensure consistency
+- Support players with images or audio
+- Parallelize processing battles and scoring

data/lib/active_genie/ranking/elo_round.rb

@@ -0,0 +1,113 @@
+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 = []
+    end
+
+    def call
+      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)
+
+          next if winner.nil? || loser.nil?
+
+          new_winner_elo, new_loser_elo = calculate_new_elo(winner.elo, loser.elo)
+
+          winner.elo = new_winner_elo
+          loser.elo = new_loser_elo
+        end
+
+        # TODO: add a round report. Duration, Elo changes, etc.
+      end
+    end
+
+    private
+
+    BATTLE_PER_PLAYER = 3
+    LOSE_PENALTY = 15
+    K = 32
+
+    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 if @tmp_defenders.size.zero?
+
+      @tmp_defenders.shuffle.pop!
+    end
+
+    def battle(player_a, player_b)
+      result = ActiveGenie::Battle.basic(
+        player_a,
+        player_b,
+        @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
+
+      ActiveGenie::Logger.debug({
+        step: :elo_round_battle,
+        player_ids: [player_a.id, player_b.id],
+        winner_id: winner&.id,
+        loser_id: loser&.id,
+        reasoning: result['reasoning']
+      })
+
+      [winner, loser]
+    end
+
+    # INFO: Read more about the Elo rating system on https://en.wikipedia.org/wiki/Elo_rating_system
+    def calculate_new_elo(winner_elo, loser_elo)
+      expected_score_a = 1 / (1 + 10**((loser_elo - winner_elo) / 400))
+      expected_score_b = 1 - expected_score_a
+
+      new_winner_elo = [winner_elo + K * (1 - expected_score_a), max_defense_elo].min
+      new_loser_elo = [loser_elo + K * (1 - expected_score_b) - LOSE_PENALTY, min_relegation_elo].max
+
+      [new_winner_elo, new_loser_elo]
+    end
+
+    def max_defense_elo
+      @defender_tier.max_by(&:elo).elo
+    end
+
+    def min_relegation_elo
+      @relegation_tier.min_by(&:elo).elo
+    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
+  end
+end

data/lib/active_genie/ranking/free_for_all.rb

@@ -0,0 +1,76 @@
+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
+    end
+
+    def call
+      ActiveGenie::Logger.with_context(log_context) do
+        matches.each do |player_a, player_b|
+          winner, loser = battle(player_a, player_b)
+          
+          if winner.nil? || loser.nil?
+            player_a.draw!
+            player_b.draw!
+          else
+            winner.win!
+            loser.lose!
+          end
+        end
+
+        # TODO: add a freeForAll report. Duration, Elo changes, etc.
+      end
+    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_a, player_b)
+      result = ActiveGenie::Battle.basic(
+        player_a,
+        player_b,
+        @criteria,
+        config: @config
+      )
+
+      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']]
+      end
+
+      ActiveGenie::Logger.debug({
+        step: :free_for_all_battle,
+        player_ids: [player_a.id, player_b.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
+  end
+end

data/lib/active_genie/ranking/player.rb

@@ -0,0 +1,97 @@
+require 'digest'
+
+module ActiveGenie::Ranking
+  class Player
+    def initialize(params)
+      params = { content: params } if params.is_a?(String)
+
+      @content = params.dig(:content) || params
+      @id = params.dig(:id) || Digest::MD5.hexdigest(@content)
+      @score = params.dig(:score) || nil
+      @elo = params.dig(:elo) || nil
+      @ffa_win_count = params.dig(:ffa_win_count) || 0
+      @ffa_lose_count = params.dig(:ffa_lose_count) || 0
+      @ffa_draw_count = params.dig(:ffa_draw_count) || 0
+      @eliminated = params.dig(:eliminated) || nil
+    end
+
+    attr_reader :id, :content, :score, :elo, 
+      :ffa_win_count, :ffa_lose_count, :ffa_draw_count,
+      :eliminated
+    attr_accessor :rank
+
+    def score=(value)
+      @score = value
+      ActiveGenie::Logger.debug({ step: :new_score, player_id: id, score: value })
+    end
+
+    def elo
+      generate_elo_by_score if @elo.nil?
+
+      @elo
+    end
+
+    def elo=(value)
+      @elo = value
+      ActiveGenie::Logger.debug({ step: :new_elo, player_id: id, elo: value })
+    end
+
+    def eliminated=(value)
+      @eliminated = value
+      ActiveGenie::Logger.debug({ step: :new_eliminated, player_id: id, eliminated: value })
+    end
+
+    def draw!
+      @ffa_draw_count += 1
+      ActiveGenie::Logger.debug({ step: :new_ffa_score, player_id: id, result: 'draw', ffa_score: })
+    end
+
+    def win!
+      @ffa_win_count += 1
+      ActiveGenie::Logger.debug({ step: :new_ffa_score, player_id: id, result: 'win', ffa_score: })
+    end
+
+    def lose!
+      @ffa_lose_count += 1
+      ActiveGenie::Logger.debug({ step: :new_ffa_score, player_id: id, result: 'lose', ffa_score: })
+    end
+
+    def ffa_score
+      @ffa_win_count * 3 + @ffa_draw_count
+    end
+
+    def to_h
+      {
+        id:, content:, score:, elo:,
+        ffa_win_count:, ffa_lose_count:, ffa_draw_count:,
+        eliminated:, ffa_score:
+      }
+    end
+
+    def method_missing(method_name, *args, &block)
+      if method_name == :[] && args.size == 1
+        attr_name = args.first.to_sym
+
+        if respond_to?(attr_name) 
+          return send(attr_name)
+        else
+          return nil
+        end
+      end
+
+      super
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      method_name == :[] || super
+    end
+
+    private
+    
+    BASE_ELO = 1000
+
+    def generate_elo_by_score
+      @elo = BASE_ELO + ((@score || 0) - 50)
+    end
+  end
+end

data/lib/active_genie/{leaderboard → ranking}/players_collection.rb

@@ -1,7 +1,6 @@
-require_relative '../utils/math'
 require_relative './player'
 
-module ActiveGenie::Leaderboard
+module ActiveGenie::Ranking
   class PlayersCollection
     def initialize(param_players)
       @players = build(param_players)
@@ -9,9 +8,11 @@ module ActiveGenie::Leaderboard
     attr_reader :players
 
     def coefficient_of_variation
-      score_list = eligible.map(&:score)
+      score_list = eligible.map(&:score).compact
+      return nil if score_list.empty?
+
       mean = score_list.sum.to_f / score_list.size
-      return nil if mean == 0  # To avoid division by zero
+      return nil if mean == 0
 
       variance = score_list.map { |num| (num - mean) ** 2 }.sum / score_list.size
       standard_deviation = Math.sqrt(variance)
@@ -19,11 +20,11 @@ module ActiveGenie::Leaderboard
       (standard_deviation / mean) * 100
     end
 
-    def tier_relegation
+    def calc_relegation_tier
       eligible[(tier_size*-1)..-1]
     end
 
-    def tier_defense
+    def calc_defender_tier
       eligible[(tier_size*-2)...(tier_size*-1)]
     end
 
@@ -35,18 +36,24 @@ module ActiveGenie::Leaderboard
       @players.reject(&:eliminated).size
     end
 
+    def elo_eligible?
+      eligible.size > 15
+    end
+
+    def sorted
+      @players.sort_by { |p| [-p.ffa_score, -(p.elo || 0), -(p.score || 0)] }
+      @players.each_with_index { |p, i| p.rank = i + 1 }
+      @players
+    end
+
     def to_h
-      sorted.map(&:to_h)
+      sorted.map { |p| p.to_h }
     end
 
     def method_missing(...)
       @players.send(...)
     end
 
-    def sorted
-      @players.sort_by { |p| [-p.league_score, -(p.elo || 0), -p.score] }
-    end
-
     private
 
     def build(param_players)