active_genie 0.0.3 → 0.0.10

data/lib/active_genie/configuration.rb

@@ -1,32 +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(__dir__, 'config', 'gen_ai.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.load_file(@path_to_config) || {}
-    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

@@ -95,7 +95,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 +103,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 +117,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(text, data_to_extract, config: {})
+      new(text, data_to_extract, config:).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,7 @@ module ActiveGenie::DataExtractor
         }
       }
 
-      ::ActiveGenie::Clients::Router.function_calling(messages, function, options: @options)
+      ::ActiveGenie::Clients::UnifiedClient.function_calling(messages, function, config:)
     end
 
     private
@@ -84,5 +83,16 @@ 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, options: {})
-      new(text, data_to_extract, options:).call()
+    def self.call(text, data_to_extract, config: {})
+      new(text, data_to_extract, config:).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:)
 
       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:)
       end
 
       response
@@ -54,5 +54,16 @@ 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

@@ -2,16 +2,16 @@ 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
 
-    def basic(text, data_to_extract, options: {})
-      Basic.call(text, data_to_extract, options:)
+    def basic(...)
+      Basic.call(...)
     end
 
-    def from_informal(text, data_to_extract, options: {})
-      FromInformal.call(text, data_to_extract, options:)
+    def from_informal(...)
+      FromInformal.call(...)
     end
   end
 end

data/lib/active_genie/league/README.md

@@ -0,0 +1,43 @@
+# league
+
+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.
+
+## Overview
+
+The league 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.
+
+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.
+
+- **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 league using:
+
+```ruby
+result = ActiveGenie::League::league.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/league/elo_ranking.rb

@@ -0,0 +1,121 @@
+require_relative '../battle/basic'
+
+module ActiveGenie::Leaderboard
+  class EloRanking
+    def self.call(players, criteria, config: {})
+      new(players, criteria, config:).call
+    end
+
+    def initialize(players, criteria, config: {})
+      @players = players
+      @criteria = criteria
+      @config = config
+      @start_time = Time.now
+    end
+
+    def call
+      @players.each(&:generate_elo_by_score)
+
+      round_count = 0
+      while @players.eligible_size > MINIMAL_PLAYERS_TO_BATTLE
+        round = create_round(@players.tier_relegation, @players.tier_defense)
+
+        round.each do |player_a, player_b|
+          winner, loser = battle(player_a, player_b) # This can take a while, can be parallelized
+          update_elo(winner, loser)
+          ActiveGenie::Logger.trace({ **log, step: :elo_battle, winner_id: winner.id, loser_id: loser.id, winner_elo: winner.elo, loser_elo: loser.elo })
+        end
+
+        eliminate_all_relegation_players
+        round_count += 1
+      end
+
+      ActiveGenie::Logger.info({ **log, step: :elo_end, round_count:, eligible_size: @players.eligible_size })
+      @players
+    end
+
+    private
+
+    MATCHS_PER_PLAYER = 3
+    LOSE_PENALTY = 15
+    MINIMAL_PLAYERS_TO_BATTLE = 10
+    K = 32
+
+    # Create a round of matches
+    # each round is exactly 1 regation player vs 3 defense players for all regation players
+    # each match is unique (player vs player)
+    # each defense player is battle exactly 3 times
+    def create_round(relegation_players, defense_players)
+      matches = []
+
+      relegation_players.each do |player_a|
+        player_enemies = []
+        MATCHS_PER_PLAYER.times do
+          defender = nil
+          while defender.nil? || player_enemies.include?(defender.id)
+            defender = defense_players.sample
+          end
+
+          matches << [player_a, defender].shuffle
+          player_enemies << defender.id
+        end
+      end
+
+      matches
+    end
+
+    def battle(player_a, player_b)
+      ActiveGenie::Battle.basic(
+        player_a,
+        player_b,
+        @criteria,
+        config:
+      ).values_at('winner', 'loser')
+    end
+
+    def update_elo(winner, loser)
+      return if winner.nil? || loser.nil?
+
+      new_winner_elo, new_loser_elo = calculate_new_elo(winner.elo, loser.elo)
+
+      winner.elo = [new_winner_elo, max_defense_elo].min
+      loser.elo = [new_loser_elo - LOSE_PENALTY, min_relegation_elo].max
+    end
+
+    def max_defense_elo
+      @players.tier_defense.max_by(&:elo).elo
+    end
+
+    def min_relegation_elo
+      @players.tier_relegation.min_by(&:elo).elo
+    end
+
+    # Read more about the formula 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_elo_winner = winner_elo + K * (1 - expected_score_a)
+      new_elo_loser = loser_elo + K * (1 - expected_score_b)
+
+      [new_elo_winner, new_elo_loser]
+    end
+
+    def eliminate_all_relegation_players
+      eliminations = @players.tier_relegation.size
+      @players.tier_relegation.each { |player| player.eliminated = 'tier_relegation' }
+      ActiveGenie::Logger.trace({ **log, step: :elo_round, eligible_size: @players.eligible_size, eliminations: })
+    end
+
+    def config
+      { **@config }
+    end
+
+    def log
+      {
+        **(@config.dig(:log) || {}),
+        duration: Time.now - @start_time
+      }
+    end
+  end
+end

data/lib/active_genie/league/free_for_all.rb

@@ -0,0 +1,62 @@
+require_relative '../battle/basic'
+
+module ActiveGenie::Leaderboard
+  class FreeForAll
+    def self.call(players, criteria, config: {})
+      new(players, criteria, config:).call
+    end
+
+    def initialize(players, criteria, config: {})
+      @players = players
+      @criteria = criteria
+      @config = config
+      @start_time = Time.now
+    end
+
+    def call
+      matches.each do |player_a, player_b|
+        winner, loser = battle(player_a, player_b)
+
+        if winner.nil? || loser.nil?
+          player_a.free_for_all[:draw] += 1
+          player_b.free_for_all[:draw] += 1
+        else
+          winner.free_for_all[:win] += 1
+          loser.free_for_all[:lose] += 1
+        end
+
+        ActiveGenie::Logger.trace({**log, step: :free_for_all_battle, winner_id: winner&.id, player_a_id: player_a.id, player_a_free_for_all_score: player_a.free_for_all_score, player_b_id: player_b.id, player_b_free_for_all_score: player_b.free_for_all_score })
+      end
+
+      @players
+    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 A should clearly be better than C
+    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:
+      )
+
+
+      result.values_at('winner', 'loser')
+    end
+
+    def config
+      { **@config }
+    end
+
+    def log
+      { **(@config.dig(:log) || {}), duration: Time.now - @start_time }
+    end
+  end
+end

data/lib/active_genie/league/league.rb

@@ -0,0 +1,120 @@
+require 'securerandom'
+
+require_relative './players_collection'
+require_relative './free_for_all'
+require_relative './elo_ranking'
+require_relative '../scoring/recommended_reviews'
+
+# This class orchestrates player ranking through multiple evaluation stages
+# using Elo ranking and free-for-all match simulations.
+# 1. Sets initial scores
+# 2. Eliminates low performers
+# 3. Runs Elo ranking (for large groups)
+# 4. Conducts free-for-all matches
+#
+# @example Basic usage
+#   League.call(players, criteria)
+#
+# @param param_players [Array] Collection of player objects to evaluate
+#   Example: ["Circle", "Triangle", "Square"]
+#            or
+#   [
+#     { content: "Circle", score: 10 },
+#     { content: "Triangle", score: 7 },
+#     { content: "Square", score: 5 }
+#   ]
+# @param criteria [String] Evaluation criteria configuration
+#   Example: "What is more similar to the letter 'O'?"
+# @param config [Hash] Additional configuration config
+#   Example: { model: "gpt-4o", api_key: ENV['OPENAI_API_KEY'] }
+# @return [Hash] Final ranked player results
+module ActiveGenie::League
+  class League
+    def self.call(param_players, criteria, config: {})
+      new(param_players, criteria, config:).call
+    end
+
+    def initialize(param_players, criteria, config: {})
+      @param_players = param_players
+      @criteria = criteria
+      @config = config
+      @league_id = SecureRandom.uuid
+      @start_time = Time.now
+    end
+
+    def call
+      set_initial_score_players
+      eliminate_obvious_bad_players
+      run_elo_ranking if players.eligible_size > 10
+      run_free_for_all
+
+      ActiveGenie::Logger.info({ **log, step: :league_end, top5: players.first(5).map(&:id) })
+      players.to_h
+    end
+
+    private
+
+    SCORE_VARIATION_THRESHOLD = 10
+
+    def set_initial_score_players
+      players_without_score = players.reject { |player| player.score }
+      players_without_score.each do |player|
+        player.score = generate_score(player.content) # This can take a while, can be parallelized
+        ActiveGenie::Logger.trace({ **log, step: :player_score, player_id: player.id, score: player.score })
+      end
+
+      ActiveGenie::Logger.info({ **log, step: :initial_score, evaluated_players: players_without_score.size })
+    end
+
+    def generate_score(content)
+      ActiveGenie::Scoring::Basic.call(content, @criteria, reviewers, config:)['final_score']
+    end
+
+    def eliminate_obvious_bad_players
+      eliminated_count = 0
+      while players.coefficient_of_variation >= SCORE_VARIATION_THRESHOLD
+        players.eligible.last.eliminated = 'variation_too_high'
+        eliminated_count += 1
+      end
+
+      ActiveGenie::Logger.info({ **log, step: :eliminate_obvious_bad_players, eliminated_count: })
+    end
+
+    def run_elo_ranking
+      EloRanking.call(players, @criteria, config:)
+    end
+
+    def run_free_for_all
+      FreeForAll.call(players, @criteria, config:)
+    end
+
+    def reviewers
+      [recommended_reviews['reviewer1'], recommended_reviews['reviewer2'], recommended_reviews['reviewer3']]
+    end
+
+    def recommended_reviews
+      @recommended_reviews ||= ActiveGenie::Scoring::RecommendedReviews.call(
+        [players.sample.content, players.sample.content].join("\n\n"),
+        @criteria,
+        config:
+      )
+    end
+
+    def players
+      @players ||= PlayersCollection.new(@param_players)
+    end
+
+    def config
+      { log:, **@config }
+    end
+
+    def log
+      {
+        **(@config.dig(:log) || {}),
+        league_id: @league_id,
+        league_start_time: @start_time,
+        duration: Time.now - @start_time
+      }
+    end
+  end
+end

data/lib/active_genie/league/player.rb

@@ -0,0 +1,59 @@
+require 'securerandom'
+
+module ActiveGenie::Leaderboard
+  class Player
+    def initialize(params)
+      params = { content: params } if params.is_a?(String)
+
+      @id = params.dig(:id) || SecureRandom.uuid
+      @content = params.dig(:content) || params
+      @score = params.dig(:score) || nil
+      @elo = params.dig(:elo) || nil
+      @free_for_all = {
+        win: params.dig(:free_for_all, :win) || 0,
+        lose: params.dig(:free_for_all, :lose) || 0,
+        draw: params.dig(:free_for_all, :draw) || 0
+      }
+      @eliminated = params.dig(:eliminated) || nil
+    end
+
+    attr_reader :id, :content, :score, :elo, :free_for_all, :eliminated
+
+    def generate_elo_by_score
+      return if !@elo.nil?
+
+      if @score.nil?
+        @elo = BASE_ELO
+      else
+        @elo = BASE_ELO + (@score - 50)
+      end
+    end
+
+    def score=(value)
+      @score = value
+    end
+
+    def elo=(value)
+      @elo = value
+    end
+
+    def eliminated=(value)
+      @eliminated = value
+    end
+
+    def free_for_all_score
+      @free_for_all[:win] * 3 + @free_for_all[:draw]
+    end
+
+    def to_h
+      {
+        id:, content:, score:, elo:,
+        eliminated:, free_for_all:, free_for_all_score:
+      }
+    end
+
+    private
+    
+    BASE_ELO = 1000
+  end
+end