active_genie 0.29.0 → 0.30.0

data/lib/active_genie/{factory.rb → lister.rb}

@@ -1,21 +1,22 @@
 # frozen_string_literal: true
 
-require_relative 'factory/feud'
+require_relative 'lister/feud'
+require_relative 'lister/juries'
 
 module ActiveGenie
-  module Factory
+  module Lister
     module_function
 
-    def feud(...)
+    def call(...)
       Feud.call(...)
     end
 
-    def list(...)
+    def with_feud(...)
       Feud.call(...)
     end
 
-    def call(...)
-      Feud.call(...)
+    def with_juries(...)
+      Juries.call(...)
     end
   end
 end

data/lib/active_genie/{clients/providers/anthropic_client.rb → providers/anthropic_provider.rb}

@@ -3,12 +3,12 @@
 require 'json'
 require 'net/http'
 require 'uri'
-require_relative 'base_client'
+require_relative 'base_provider'
 
 module ActiveGenie
-  module Clients
-    # Client for interacting with the Anthropic (Claude) API with json response
-    class AnthropicClient < BaseClient
+  module Providers
+    # Provider for interacting with the Anthropic (Claude) API with json response
+    class AnthropicProvider < BaseProvider
       # Requests structured JSON output from the Anthropic Claude model based on a schema.
       #
       # @param messages [Array<Hash>] A list of messages representing the conversation history.

data/lib/active_genie/{clients/providers/base_client.rb → providers/base_provider.rb}

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module ActiveGenie
-  module Clients
-    class BaseClient
-      class ClientError < StandardError; end
+  module Providers
+    class BaseProvider
+      class ProviderError < StandardError; end
 
       DEFAULT_HEADERS = {
         'Content-Type': 'application/json',
@@ -81,7 +81,7 @@ module ActiveGenie
 
         response = http_request(request, uri)
 
-        raise ClientError, "Unexpected response: #{response.code} - #{response.body}" unless response.is_a?(Net::HTTPSuccess)
+        raise ProviderError, "Unexpected response: #{response.code} - #{response.body}" unless response.is_a?(Net::HTTPSuccess)
 
         parsed_response = parse_response(response)
 
@@ -143,7 +143,7 @@ module ActiveGenie
         begin
           JSON.parse(response.body)
         rescue JSON::ParserError => e
-          raise ClientError, "Failed to parse JSON response: #{e.message}"
+          raise ProviderError, "Failed to parse JSON response: #{e.message}"
         end
       end
 
@@ -170,7 +170,7 @@ module ActiveGenie
 
         begin
           yield
-        rescue Net::OpenTimeout, Net::ReadTimeout, ClientError => e
+        rescue Net::OpenTimeout, Net::ReadTimeout, ProviderError => e
           raise if retries > max_retries
 
           sleep_time = retry_delay * (2**retries)

data/lib/active_genie/{clients/providers/deepseek_client.rb → providers/deepseek_provider.rb}

@@ -3,11 +3,11 @@
 require 'json'
 require 'net/http'
 
-require_relative 'base_client'
+require_relative 'base_provider'
 
 module ActiveGenie
-  module Clients
-    class DeepseekClient < BaseClient
+  module Providers
+    class DeepseekProvider < BaseProvider
       class InvalidResponseError < StandardError; end
 
       # Requests structured JSON output from the Deepseek model based on a schema.

data/lib/active_genie/{clients/providers/google_client.rb → providers/google_provider.rb}

@@ -3,12 +3,12 @@
 require 'json'
 require 'net/http'
 require 'uri'
-require_relative 'base_client'
+require_relative 'base_provider'
 
 module ActiveGenie
-  module Clients
-    # Client for interacting with the Google Generative Language API.
-    class GoogleClient < BaseClient
+  module Providers
+    # Provider for interacting with the Google Generative Language API.
+    class GoogleProvider < BaseProvider
       # Requests structured JSON output from the Google Generative Language model based on a schema.
       #
       # @param messages [Array<Hash>] A list of messages representing the conversation history.
@@ -94,9 +94,9 @@ module ActiveGenie
         json_instruction = <<~PROMPT
           Generate a JSON object that strictly adheres to the following JSON schema:
 
-          ```json
+          <json_schema>
           #{JSON.pretty_generate(function_schema[:parameters])}
-          ```
+          </json_schema>
 
           IMPORTANT: Only output the raw JSON object. Do not include any other text, explanations, or markdown formatting like ```json ... ``` wrappers around the final output.
         PROMPT

data/lib/active_genie/{clients/providers/openai_client.rb → providers/openai_provider.rb}

@@ -3,11 +3,11 @@
 require 'json'
 require 'net/http'
 
-require_relative 'base_client'
+require_relative 'base_provider'
 
 module ActiveGenie
-  module Clients
-    class OpenaiClient < BaseClient
+  module Providers
+    class OpenaiProvider < BaseProvider
       class InvalidResponseError < StandardError; end
 
       # Requests structured JSON output from the OpenAI model based on a schema.

data/lib/active_genie/providers/unified_provider.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative 'openai_provider'
+require_relative 'anthropic_provider'
+require_relative 'google_provider'
+require_relative 'deepseek_provider'
+require_relative '../errors/invalid_provider_error'
+
+module ActiveGenie
+  module Providers
+    class UnifiedProvider
+      class << self
+        PROVIDER_NAME_TO_CLIENT = {
+          openai: OpenaiProvider,
+          anthropic: AnthropicProvider,
+          google: GoogleProvider,
+          deepseek: DeepseekProvider
+        }.freeze
+
+        def function_calling(messages, function, config: {})
+          provider_name = config.llm.provider_name || config.providers.default
+          provider = PROVIDER_NAME_TO_CLIENT[provider_name.to_sym]
+
+          raise ActiveGenie::InvalidProviderError, provider_name if provider.nil?
+
+          response = provider.new(config).function_calling(messages, function)
+
+          normalize_response(response)
+        end
+
+        private
+
+        def normalize_response(response)
+          response.each do |key, value|
+            response[key] = nil if ['null', 'none', 'undefined', '', 'unknown',
+                                    '<unknown>'].include?(value.to_s.strip.downcase)
+          end
+
+          response
+        end
+      end
+    end
+  end
+end

data/lib/active_genie/{ranking/elo_round.rb → ranker/elo.rb}

@@ -1,38 +1,38 @@
 # frozen_string_literal: true
 
 module ActiveGenie
-  module Ranking
-    class EloRound
+  module Ranker
+    class Elo
       def self.call(...)
         new(...).call
       end
 
       def initialize(players, criteria, config: nil)
         @players = players
-        @relegation_tier = players.calc_relegation_tier
-        @defender_tier = players.calc_defender_tier
+        @higher_tier = players.calc_higher_tier
+        @lower_tier = players.calc_lower_tier
         @criteria = criteria
         @config = ActiveGenie.configuration.merge(config)
-        @tmp_defenders = []
+        @tmp_highers = []
         @total_tokens = 0
         @previous_elo = @players.to_h { |player| [player.id, player.elo] }
-        @previous_highest_elo = @defender_tier.max_by(&:elo).elo
+        @previous_highest_elo = @higher_tier.max_by(&:elo).elo
       end
 
       def call
         @config.log.add_observer(observers: ->(log) { log_observer(log) })
-        @config.log.additional_context = { elo_round_id: }
+        @config.log.additional_context = { elo_id: }
 
         matches.each do |player_a, player_b|
-          # TODO: battle can take a while, can be parallelized
-          winner, loser = battle(player_a, player_b)
+          # TODO: debate can take a while, can be parallelized
+          winner, loser = debate(player_a, player_b)
           update_players_elo(winner, loser)
         end
 
         build_report
       end
 
-      BATTLE_PER_PLAYER = 3
+      DEBATE_PER_PLAYER = 3
       K = 32
 
       private
@@ -40,26 +40,26 @@ module ActiveGenie
       def matches
         match_keys = {}
 
-        @relegation_tier.each_with_object([]) do |attack_player, matches|
-          BATTLE_PER_PLAYER.times do
-            defense_player = next_defense_player
+        @higher_tier.each_with_object([]) do |attack_player, matches|
+          DEBATE_PER_PLAYER.times do
+            higher_player = next_higher_player
 
-            next if match_keys["#{attack_player.id}_#{defense_player.id}"]
+            next if match_keys["#{attack_player.id}_#{higher_player.id}"]
 
-            match_keys["#{attack_player.id}_#{defense_player.id}"] = true
-            matches << [attack_player, defense_player]
+            match_keys["#{attack_player.id}_#{higher_player.id}"] = true
+            matches << [attack_player, higher_player]
           end
         end
       end
 
-      def next_defense_player
-        @tmp_defenders = @defender_tier.shuffle if @tmp_defenders.empty?
+      def next_higher_player
+        @tmp_highers = @higher_tier.shuffle if @tmp_highers.empty?
 
-        @tmp_defenders.pop
+        @tmp_highers.pop
       end
 
-      def battle(player_a, player_b)
-        result = ActiveGenie::Battle.call(
+      def debate(player_a, player_b)
+        result = ActiveGenie::Comparator.by_debate(
           player_a.content,
           player_b.content,
           @criteria,
@@ -89,21 +89,21 @@ module ActiveGenie
         player_rating + (K * (score - expected_score)).round
       end
 
-      def elo_round_id
-        @elo_round_id ||= begin
-          relegation_tier_ids = @relegation_tier.map(&:id).join(',')
-          defender_tier_ids = @defender_tier.map(&:id).join(',')
+      def elo_id
+        @elo_id ||= begin
+          higher_tier_ids = @higher_tier.map(&:id).join(',')
+          lower_tier_ids = @lower_tier.map(&:id).join(',')
 
-          ranking_unique_key = [relegation_tier_ids, defender_tier_ids, @criteria, @config.to_json].join('-')
-          Digest::MD5.hexdigest(ranking_unique_key)
+          ranker_unique_key = [higher_tier_ids, lower_tier_ids, @criteria, @config.to_json].join('-')
+          Digest::MD5.hexdigest(ranker_unique_key)
         end
       end
 
       def build_report
         report = {
-          elo_round_id:,
-          players_in_round: players_in_round.map(&:id),
-          battles_count: matches.size,
+          elo_id:,
+          players_in: players_in.map(&:id),
+          debates_count: matches.size,
           total_tokens: @total_tokens,
           previous_highest_elo: @previous_highest_elo,
           highest_elo:,
@@ -111,21 +111,21 @@ module ActiveGenie
           players_elo_diff:
         }
 
-        @config.logger.call({ elo_round_id:, code: :elo_round_report, **report })
+        @config.logger.call({ elo_id:, code: :elo_report, **report })
 
         report
       end
 
-      def players_in_round
-        @defender_tier + @relegation_tier
+      def players_in
+        @lower_tier + @higher_tier
       end
 
       def highest_elo
-        players_in_round.max_by(&:elo).elo
+        players_in.max_by(&:elo).elo
       end
 
       def players_elo_diff
-        elo_diffs = players_in_round.map do |player|
+        elo_diffs = players_in.map do |player|
           [player.id, player.elo - @previous_elo[player.id]]
         end
         elo_diffs.sort_by { |_, diff| -(diff || 0) }.to_h

data/lib/active_genie/ranker/entities/player.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module ActiveGenie
+  module Ranker
+    module Entities
+      class Player
+        def initialize(params)
+          @params = params.is_a?(String) ? { content: params } : params.dup
+          @params[:content] ||= @params
+        end
+
+        def content
+          @content ||= @params[:content]
+        end
+
+        def name
+          @name ||= @params[:name] || content[0..10]
+        end
+
+        def id
+          @id ||= @params[:id] || Digest::MD5.hexdigest(content.to_s)
+        end
+
+        def score
+          @score ||= @params[:score]
+        end
+
+        def elo
+          @elo = @elo || @params[:elo] || generate_elo_by_score
+        end
+
+        def ffa_win_count
+          @ffa_win_count ||= @params[:ffa_win_count] || 0
+        end
+
+        def ffa_lose_count
+          @ffa_lose_count ||= @params[:ffa_lose_count] || 0
+        end
+
+        def ffa_draw_count
+          @ffa_draw_count ||= @params[:ffa_draw_count] || 0
+        end
+
+        def eliminated
+          @eliminated ||= @params[:eliminated]
+        end
+
+        def score=(value)
+          @score = value
+          @elo = generate_elo_by_score
+        end
+
+        def elo=(value)
+          @elo = value || BASE_ELO
+        end
+
+        attr_writer :eliminated
+
+        def draw!
+          @ffa_draw_count = ffa_draw_count + 1
+        end
+
+        def win!
+          @ffa_win_count = ffa_win_count + 1
+        end
+
+        def lose!
+          @ffa_lose_count = ffa_lose_count + 1
+        end
+
+        def ffa_score
+          (ffa_win_count * 3) + ffa_draw_count
+        end
+
+        def sort_value
+          (ffa_score * 1_000_000) + ((elo || 0) * 100) + (score || 0)
+        end
+
+        def to_json(*_args)
+          to_h.to_json
+        end
+
+        def to_h
+          {
+            id:, name:, content:,
+
+            score:, elo:,
+            ffa_win_count:, ffa_lose_count:, ffa_draw_count:,
+            eliminated:, ffa_score:, sort_value:
+          }
+        end
+
+        def method_missing(method_name, *args, &)
+          if method_name == :[] && args.size == 1
+            attr_name = args.first.to_sym
+
+            return send(attr_name) if respond_to?(attr_name)
+
+            return nil
+
+          end
+
+          super
+        end
+
+        def respond_to_missing?(method_name, include_private = false)
+          method_name == :[] || super
+        end
+
+        BASE_ELO = 1000
+
+        private
+
+        def generate_elo_by_score
+          return BASE_ELO if @score.nil?
+
+          BASE_ELO + (@score - 50)
+        end
+      end
+    end
+  end
+end

data/lib/active_genie/ranker/entities/players.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative 'player'
+
+module ActiveGenie
+  module Ranker
+    module Entities
+      class Players
+        def initialize(players)
+          @players = if players.is_a?(Players)
+                       players.players
+                     else
+                       build(players)
+                     end
+        end
+
+        attr_reader :players
+
+        def coefficient_of_variation
+          mean = score_mean
+
+          return 0 if mean.zero?
+
+          variance = all_scores.map { |num| (num - mean)**2 }.sum / all_scores.size
+          standard_deviation = Math.sqrt(variance)
+
+          (standard_deviation / mean) * 100
+        end
+
+        def all_scores
+          eligible.map(&:score).compact
+        end
+
+        def score_mean
+          return 0 if all_scores.empty?
+
+          all_scores.sum.to_f / all_scores.size
+        end
+
+        def calc_higher_tier
+          eligible[(tier_size * -1)..]
+        end
+
+        def calc_lower_tier
+          eligible[(tier_size * -2)...(tier_size * -1)]
+        end
+
+        def eligible
+          sorted.reject(&:eliminated)
+        end
+
+        def eligible_size
+          @players.reject(&:eliminated).size
+        end
+
+        def elo_eligible?
+          eligible.size > 15
+        end
+
+        def sorted
+          @players.sort_by { |p| -p.sort_value }
+        end
+
+        def to_json(*_args)
+          @players.map(&:to_h).to_json
+        end
+
+        def method_missing(...)
+          @players.send(...)
+        end
+
+        def respond_to_missing?(method_name, include_private = false)
+          @players.respond_to?(method_name, include_private)
+        end
+
+        private
+
+        def build(param_players)
+          param_players.map { |p| Player.new(p) }
+        end
+
+        # Returns the number of players to debate in each round
+        # based on the eligible size, start fast and go slow until top 10
+        # Example:
+        #   - 50 eligible, tier_size: 15
+        #   - 35 eligible, tier_size: 11
+        #   - 24 eligible, tier_size: 10
+        #   - 14 eligible, tier_size: 4
+        #  4 rounds to reach top 10 with 50 players
+        def tier_size
+          size = (eligible_size / 3).ceil
+
+          if eligible_size < 10
+            (eligible_size / 2).ceil
+          else
+            size.clamp(10, eligible_size - 10)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_genie/{ranking → ranker}/free_for_all.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
 module ActiveGenie
-  module Ranking
+  module Ranker
     class FreeForAll
       def self.call(...)
         new(...).call
       end
 
       def initialize(players, criteria, config: nil)
-        @players = players
+        @players = Players.new(players)
         @criteria = criteria
         @config = config || ActiveGenie.configuration
         @start_time = Time.now
@@ -20,7 +20,7 @@ module ActiveGenie
         @config.log.additional_context = { free_for_all_id: }
 
         matches.each do |player_a, player_b|
-          winner, loser = battle(player_a, player_b)
+          winner, loser = debate(player_a, player_b)
 
           update_players_score(winner, loser)
         end
@@ -31,15 +31,15 @@ module ActiveGenie
       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
+      #       For example, if A is better than B, and B is better than C, then debate between A and C should be auto win A
       def matches
         @players.eligible.combination(2).to_a
       end
 
-      def battle(player_a, player_b)
+      def debate(player_a, player_b)
         log_context = { player_a_id: player_a.id, player_b_id: player_b.id }
 
-        result = ActiveGenie::Battle.call(
+        result = ActiveGenie::Comparator.debate(
           player_a.content,
           player_b.content,
           @criteria,
@@ -55,7 +55,7 @@ module ActiveGenie
         @config.logger.call(
           {
             **log_context,
-            code: :free_for_all_battle,
+            code: :free_for_all,
             winner_id: winner&.id,
             loser_id: loser&.id,
             reasoning: result['reasoning']
@@ -88,7 +88,7 @@ module ActiveGenie
       def build_report
         report = {
           free_for_all_id:,
-          battles_count: matches.size,
+          debates_count: matches.size,
           duration_seconds: Time.now - @start_time,
           total_tokens: @total_tokens
         }

data/lib/active_genie/ranker/scoring.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module ActiveGenie
+  module Ranker
+    class Scoring
+      def self.call(...)
+        new(...).call
+      end
+
+      def initialize(players, criteria, juries: [], config: nil)
+        @players = Players.new(players)
+        @criteria = criteria
+        @config = ActiveGenie.configuration.merge(config)
+        @juries = Array(juries).compact.uniq
+      end
+
+      def call
+        @config.log.additional_context = { ranker_scoring_id: }
+
+        players_without_score.each do |player|
+          player.score = generate_score(player)
+        end
+      end
+
+      private
+
+      def players_without_score
+        @players_without_score ||= @players.select { |player| player.score.nil? }
+      end
+
+      def generate_score(player)
+        score, reasoning = ActiveGenie::Scorer.jury_bench(
+          player.content,
+          @criteria,
+          @juries,
+          config: @config
+        ).values_at('final_score', 'final_reasoning')
+
+        @config.logger.call({ code: :new_score, player_id: player.id, score:, reasoning: })
+
+        score
+      end
+
+      def juries
+        @juries ||= begin
+          response = ActiveGenie::Lister.juries(
+            [@players.sample.content, @players.sample.content].join("\n\n"),
+            @criteria,
+            config: @config
+          )
+          @config.logger.call({ code: :new_juries, juries: response })
+          response
+        end
+      end
+
+      def ranker_scoring_id
+        @ranker_scoring_id ||= begin
+          player_ids = players_without_score.map(&:id).join(',')
+          ranker_unique_key = [player_ids, @criteria, @config.to_json].join('-')
+
+          "#{Digest::MD5.hexdigest(ranker_unique_key)}-scoring"
+        end
+      end
+    end
+  end
+end