active_genie 0.29.1 → 0.30.1

data/lib/active_genie/lister/juries.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative '../providers/unified_provider'
+
+module ActiveGenie
+  module Lister
+    # The Juries class intelligently suggests appropriate jury roles
+    # for evaluating text content based on specific criteria. It uses AI to analyze
+    # the content and criteria to identify the most suitable subject matter experts.
+    #
+    # The class ensures a balanced and comprehensive review process by recommending
+    # three distinct jury roles with complementary expertise and perspectives.
+    #
+    # @example Getting jury for technical content
+    #   Juries.call("Technical documentation about API design",
+    #                           "Evaluate technical accuracy and clarity")
+    #   # => { jury1: "API Architect", jury2: "Technical Writer",
+    #   #      jury3: "Developer Advocate", reasoning: "..." }
+    #
+    class Juries
+      def self.call(...)
+        new(...).call
+      end
+
+      # Initializes a new jury recommendation instance
+      #
+      # @param text [String] The text content to analyze for jury recommendations
+      # @param criteria [String] The evaluation criteria that will guide jury selection
+      # @param config [Hash] Additional configuration config that modify the recommendation process
+      def initialize(text, criteria, config: {})
+        @text = text
+        @criteria = criteria
+        @config = ActiveGenie.configuration.merge(config)
+      end
+
+      def call
+        messages = [
+          {  role: 'system', content: prompt },
+          {  role: 'user', content: "<criteria> #{@criteria}</criteria>" },
+          {  role: 'user', content: "<text-to-score>#{@text}</text-to-score>" }
+        ]
+
+        function = {
+          name: 'identify_jury',
+          description: 'Discover a list of juries based on the text and given criteria.',
+          parameters: {
+            type: 'object',
+            properties: {
+              reasoning: { type: 'string' },
+              juries: {
+                type: 'array',
+                description: 'The list of best juries',
+                items: {
+                  type: 'string'
+                }
+              }
+            },
+            required: %w[reasoning juries]
+          }
+        }
+
+        result = client.function_calling(
+          messages,
+          function,
+          config: @config
+        )
+
+        result['juries'] || []
+      end
+
+      private
+
+      def client
+        ::ActiveGenie::Providers::UnifiedProvider
+      end
+
+      def prompt
+        @prompt ||= File.read(File.join(__dir__, 'juries.prompt.md'))
+      end
+    end
+  end
+end

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,12 @@
 # frozen_string_literal: true
 
+require 'net/http'
+
 module ActiveGenie
-  module Clients
-    class BaseClient
-      class ClientError < StandardError; end
+  module Providers
+    class BaseProvider
+      class ProviderUnknownError < StandardError; end
+      class ProviderServerError < StandardError; end
 
       DEFAULT_HEADERS = {
         'Content-Type': 'application/json',
@@ -81,7 +84,7 @@ module ActiveGenie
 
         response = http_request(request, uri)
 
-        raise ClientError, "Unexpected response: #{response.code} - #{response.body}" unless response.is_a?(Net::HTTPSuccess)
+        raise ProviderUnknownError, "Unexpected response: #{response.code} - #{response.body}" unless response.is_a?(Net::HTTPSuccess)
 
         parsed_response = parse_response(response)
 
@@ -143,7 +146,7 @@ module ActiveGenie
         begin
           JSON.parse(response.body)
         rescue JSON::ParserError => e
-          raise ClientError, "Failed to parse JSON response: #{e.message}"
+          raise ProviderUnknownError, "Failed to parse JSON response: #{e.message}"
         end
       end
 
@@ -169,8 +172,12 @@ module ActiveGenie
         retries = 0
 
         begin
-          yield
-        rescue Net::OpenTimeout, Net::ReadTimeout, ClientError => e
+          response = yield
+
+          raise ProviderServerError, "Provider server error: #{response.code} - #{response.body}" if !response.is_a?(Net::HTTPSuccess) && response.code.to_i >= 500
+
+          response
+        rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED, ProviderServerError => 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_PROVIDER = {
+          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_PROVIDER[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: }
+
+        ActiveGenie::FiberByBatch.call(matches, config: @config) do |player_a, player_b|
+          winner, loser = debate(player_a, player_b)
 
-        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
       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,43 +89,44 @@ 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,
+          players_in_round: players_in.map(&:id),
           previous_highest_elo: @previous_highest_elo,
           highest_elo:,
           highest_elo_diff: highest_elo - @previous_highest_elo,
           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