active_genie 0.29.1 → 0.30.1

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 = Entities::Players.new(players)
         @criteria = criteria
         @config = config || ActiveGenie.configuration
         @start_time = Time.now
@@ -19,8 +19,8 @@ module ActiveGenie
         @config.log.add_observer(observers: ->(log) { log_observer(log) })
         @config.log.additional_context = { free_for_all_id: }
 
-        matches.each do |player_a, player_b|
-          winner, loser = battle(player_a, player_b)
+        ActiveGenie::FiberByBatch.call(matches, config: @config) do |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.by_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,68 @@
+# frozen_string_literal: true
+
+require_relative '../utils/fiber_by_batch'
+
+module ActiveGenie
+  module Ranker
+    class Scoring
+      def self.call(...)
+        new(...).call
+      end
+
+      def initialize(players, criteria, juries: [], config: nil)
+        @players = Entities::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: }
+
+        ActiveGenie::FiberByBatch.call(players_without_score, config: @config) 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.by_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

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

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-require_relative 'players_collection'
+require_relative 'entities/players'
 require_relative 'free_for_all'
-require_relative 'elo_round'
-require_relative 'ranking_scoring'
+require_relative 'elo'
+require_relative 'scoring'
 
 # This class orchestrates player ranking through multiple evaluation stages
 # using Elo ranking and free-for-all match simulations.
@@ -13,7 +13,7 @@ require_relative 'ranking_scoring'
 # 4. Conducts free-for-all matches
 #
 # @example Basic usage
-#   Ranking.call(players, criteria)
+#   Ranker.tournament(players, criteria)
 #
 # @param param_players [Array<Hash|String>] Collection of player objects to evaluate
 #   Example: ["Circle", "Triangle", "Square"]
@@ -29,30 +29,28 @@ require_relative 'ranking_scoring'
 #   Example: { model: "gpt-4o", api_key: ENV['OPENAI_API_KEY'] }
 # @return [Hash] Final ranked player results
 module ActiveGenie
-  module Ranking
-    class Ranking
+  module Ranker
+    class Tournament
       def self.call(...)
         new(...).call
       end
 
-      def initialize(param_players, criteria, reviewers: [], config: {})
-        @param_players = param_players
+      def initialize(players, criteria, juries: [], config: {})
+        @players = Entities::Players.new(players)
         @criteria = criteria
-        @reviewers = Array(reviewers).compact.uniq
+        @juries = Array(juries).compact.uniq
         @config = ActiveGenie.configuration.merge(config)
-        @players = nil
       end
 
       def call
-        @players = create_players
-        @config.log.additional_context = { ranking_id: }
+        @config.log.additional_context = { ranker_id: }
 
         set_initial_player_scores!
         eliminate_obvious_bad_players!
 
         while @players.elo_eligible?
           elo_report = run_elo_round!
-          eliminate_relegation_players!
+          eliminate_lower_tier_players!
           rebalance_players!(elo_report)
         end
 
@@ -66,38 +64,31 @@ module ActiveGenie
 
       private
 
-      def create_players
-        players = PlayersCollection.new(@param_players)
-        players.each { |p| @config.logger.call({ code: :new_player, player: p.to_h }) }
-
-        players
-      end
-
       def set_initial_player_scores!
-        RankingScoring.call(
+        Scoring.call(
           @players,
           @criteria,
-          reviewers: @reviewers,
+          juries: @juries,
           config: @config
         )
       end
 
       def eliminate_obvious_bad_players!
-        while @players.coefficient_of_variation >= @config.ranking.score_variation_threshold
+        while @players.coefficient_of_variation >= @config.ranker.score_variation_threshold
           @players.eligible.last.eliminated = ELIMINATION_VARIATION
         end
       end
 
       def run_elo_round!
-        EloRound.call(
+        Elo.call(
           @players,
           @criteria,
           config: @config
         )
       end
 
-      def eliminate_relegation_players!
-        @players.calc_relegation_tier.each { |player| player.eliminated = ELIMINATION_RELEGATION }
+      def eliminate_lower_tier_players!
+        @players.calc_lower_tier.each { |player| player.eliminated = ELIMINATION_RELEGATION }
       end
 
       def rebalance_players!(elo_report)
@@ -120,17 +111,17 @@ module ActiveGenie
 
       def sorted_players
         players = @players.sorted
-        @config.logger.call({ ranking_id:, code: :ranking_final, players: players.map(&:to_h) })
+        @config.logger.call({ ranker_id:, code: :ranker_final, players: players.map(&:to_h) })
 
         players.map(&:to_h)
       end
 
-      def ranking_id
-        @ranking_id ||= begin
+      def ranker_id
+        @ranker_id ||= begin
           player_ids = @players.map(&:id).join(',')
-          ranking_unique_key = [player_ids, @criteria, @config.to_json].join('-')
+          ranker_unique_key = [player_ids, @criteria, @config.to_json].join('-')
 
-          Digest::MD5.hexdigest(ranking_unique_key)
+          Digest::MD5.hexdigest(ranker_unique_key)
         end
       end
     end

data/lib/active_genie/ranker.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'ranker/tournament'
+require_relative 'ranker/free_for_all'
+require_relative 'ranker/elo'
+require_relative 'ranker/scoring'
+
+module ActiveGenie
+  module Ranker
+    module_function
+
+    def call(...)
+      Tournament.call(...)
+    end
+
+    def by_tournament(...)
+      Tournament.call(...)
+    end
+
+    def by_free_for_all(...)
+      FreeForAll.call(...)
+    end
+
+    def by_elo(...)
+      Elo.call(...)
+    end
+
+    def by_scoring(...)
+      Scoring.call(...)
+    end
+  end
+end

data/lib/active_genie/scorer/jury_bench.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative '../providers/unified_provider'
+
+module ActiveGenie
+  module Scorer
+    # The JuryBench class provides a foundation for Scorer text content against specified criteria
+    # using AI-powered evaluation. It supports both single and multiple jury scenarios,
+    # with the ability to automatically recommend juries when none are specified.
+    #
+    # The Scorer process evaluates text based on given criteria and returns detailed feedback
+    # including individual jury scores, reasoning, and a final aggregated score.
+    #
+    # @example JuryBench usage with a single jury
+    #   JuryBench.call("Sample text", "Evaluate grammar and clarity", ["Grammar Expert"])
+    #
+    # @example Usage with automatic jury recommendation
+    #   JuryBench.call("Sample text", "Evaluate technical accuracy")
+    #
+    class JuryBench
+      # @param text [String] The text content to be evaluated
+      # @param criteria [String] The evaluation criteria or rubric to assess against
+      # @param juries [Array<String>] Optional list of specific juries. If empty,
+      #   juries will be automatically recommended based on the content and criteria
+      # @param config [Hash] Additional configuration config that modify the Scorer behavior
+      # @return [Hash] The evaluation result containing the scores and reasoning
+      #   @return [Number] :final_score The final score of the text based on the criteria and juries
+      #   @return [String] :final_reasoning Detailed explanation of why the final score was reached
+      def self.call(...)
+        new(...).call
+      end
+
+      def initialize(text, criteria, juries = [], config: {})
+        @text = text
+        @criteria = criteria
+        @param_juries = Array(juries).compact.uniq
+        @config = ActiveGenie.configuration.merge(config)
+      end
+
+      def call
+        messages = [
+          {  role: 'system', content: PROMPT },
+          {  role: 'user', content: "Scorer criteria: #{@criteria}" },
+          {  role: 'user', content: "Text to score: #{@text}" }
+        ]
+
+        result = ::ActiveGenie::Providers::UnifiedProvider.function_calling(
+          messages,
+          build_function,
+          config: @config
+        )
+
+        result['final_score'] = 0 if result['final_score'].nil?
+
+        @config.logger.call({
+                              code: :Scorer,
+                              text: @text[0..30],
+                              criteria: @criteria[0..30],
+                              juries: juries,
+                              score: result['final_score'],
+                              reasoning: result['final_reasoning']
+                            })
+
+        result
+      end
+
+      PROMPT = File.read(File.join(__dir__, 'jury_bench.prompt.md'))
+
+      private
+
+      def build_function
+        {
+          name: 'scorer',
+          description: 'Score the text based on the given criteria.',
+          parameters: {
+            type: 'object',
+            properties: properties,
+            required: properties.keys
+          }
+        }
+      end
+
+      def properties
+        @properties ||= begin
+          tmp = {}
+          juries.each do |jury|
+            tmp["#{jury}_reasoning"] = {
+              type: 'string',
+              description: "The reasoning of the Scorer process by #{jury}."
+            }
+            tmp["#{jury}_score"] = {
+              type: 'number',
+              description: "The score given by #{jury}.",
+              min: 0,
+              max: 100
+            }
+          end
+
+          tmp[:final_score] = {
+            type: 'number',
+            description: 'The final score based on the previous juries'
+          }
+          tmp[:final_reasoning] = {
+            type: 'string',
+            description: 'The final reasoning based on the previous juries'
+          }
+
+          tmp
+        end
+      end
+
+      def juries
+        @juries ||= if @param_juries.any?
+                      @param_juries
+                    else
+                      ::ActiveGenie::Lister::Juries.call(@text, @criteria, config: @config)
+                    end
+      end
+    end
+  end
+end

data/lib/active_genie/scorer.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'scorer/jury_bench'
+
+module ActiveGenie
+  module Scorer
+    module_function
+
+    def call(...)
+      JuryBench.call(...)
+    end
+
+    def by_jury_bench(...)
+      JuryBench.call(...)
+    end
+  end
+end

data/lib/active_genie/utils/fiber_by_batch.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'async'
+
+module ActiveGenie
+  module FiberByBatch
+    module_function
+
+    def call(items, config:, &block)
+      items.each_slice(config.llm.max_fibers).to_a.each do |batch|
+        Async do
+          tasks = batch.map do |item|
+            Async { block.call(item) }
+          end
+
+          tasks.each(&:wait)
+        end.wait
+      end
+    end
+  end
+end

data/lib/active_genie.rb

@@ -3,17 +3,17 @@
 require_relative 'active_genie/logger'
 require_relative 'active_genie/configuration'
 
-require_relative 'active_genie/config/providers/openai_config'
-require_relative 'active_genie/config/providers/google_config'
-require_relative 'active_genie/config/providers/anthropic_config'
-require_relative 'active_genie/config/providers/deepseek_config'
+require_relative 'active_genie/configs/providers/openai_config'
+require_relative 'active_genie/configs/providers/google_config'
+require_relative 'active_genie/configs/providers/anthropic_config'
+require_relative 'active_genie/configs/providers/deepseek_config'
 
 module ActiveGenie
-  autoload :DataExtractor, File.join(__dir__, 'active_genie/data_extractor')
-  autoload :Battle, File.join(__dir__, 'active_genie/battle')
-  autoload :Scoring, File.join(__dir__, 'active_genie/scoring')
-  autoload :Ranking, File.join(__dir__, 'active_genie/ranking')
-  autoload :Factory, File.join(__dir__, 'active_genie/factory')
+  autoload :Extractor, File.join(__dir__, 'active_genie/extractor')
+  autoload :Comparator, File.join(__dir__, 'active_genie/comparator')
+  autoload :Scorer, File.join(__dir__, 'active_genie/scorer')
+  autoload :Ranker, File.join(__dir__, 'active_genie/ranker')
+  autoload :Lister, File.join(__dir__, 'active_genie/lister')
 
   VERSION = File.read(File.expand_path('../VERSION', __dir__)).strip
 

data/lib/tasks/test.rake

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'rake/testtask'
+
 namespace :test do
   Rake::TestTask.new(:unit) do |t|
     t.pattern = 'test/unit/**/*_test.rb'
@@ -8,4 +10,6 @@ namespace :test do
   Rake::TestTask.new(:integration) do |t|
     t.pattern = 'test/integration/**/*_test.rb' # Or use _spec.rb for RSpec
   end
+
+  task default: %i[unit integration]
 end

metadata

@@ -1,17 +1,31 @@
 --- !ruby/object:Gem::Specification
 name: active_genie
 version: !ruby/object:Gem::Version
-  version: 0.29.1
+  version: 0.30.1
 platform: ruby
 authors:
 - Radamés Roriz
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-05 00:00:00.000000000 Z
-dependencies: []
+date: 2025-08-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
 description: |
-  ActiveGenie is a Ruby gem that helps developers build reliable, future-proof GenAI features without worrying about changing models, prompts, or providers. Like Lodash for GenAI, it offers simple, reusable modules for tasks like data extraction, scoring, and ranking, so you can focus on your app’s logic, not the shifting AI landscape.
+  ActiveGenie is a Ruby gem that helps developers build reliable, future-proof GenAI features without worrying about changing models, prompts, or providers. Like Lodash for GenAI, it offers simple, reusable modules for tasks like extractor, comparator, scorer, and ranker, so you can focus on your app’s logic, not the shifting AI landscape.
   Behind the scenes, a custom benchmarking system keeps everything consistent across LLM vendors and versions, release after release.
 email:
 - radames@roriz.dev
@@ -23,58 +37,59 @@ files:
 - README.md
 - VERSION
 - lib/active_genie.rb
-- lib/active_genie/battle.rb
-- lib/active_genie/battle/fight.json
-- lib/active_genie/battle/fight.prompt.md
-- lib/active_genie/battle/fight.rb
-- lib/active_genie/battle/generalist.json
-- lib/active_genie/battle/generalist.prompt.md
-- lib/active_genie/battle/generalist.rb
-- lib/active_genie/clients/providers/anthropic_client.rb
-- lib/active_genie/clients/providers/base_client.rb
-- lib/active_genie/clients/providers/deepseek_client.rb
-- lib/active_genie/clients/providers/google_client.rb
-- lib/active_genie/clients/providers/openai_client.rb
-- lib/active_genie/clients/unified_client.rb
-- lib/active_genie/config/battle_config.rb
-- lib/active_genie/config/data_extractor_config.rb
-- lib/active_genie/config/factory_config.rb
-- lib/active_genie/config/llm_config.rb
-- lib/active_genie/config/log_config.rb
-- lib/active_genie/config/providers/anthropic_config.rb
-- lib/active_genie/config/providers/deepseek_config.rb
-- lib/active_genie/config/providers/google_config.rb
-- lib/active_genie/config/providers/openai_config.rb
-- lib/active_genie/config/providers/provider_base.rb
-- lib/active_genie/config/providers_config.rb
-- lib/active_genie/config/ranking_config.rb
-- lib/active_genie/config/scoring_config.rb
+- lib/active_genie/comparator.rb
+- lib/active_genie/comparator/debate.json
+- lib/active_genie/comparator/debate.prompt.md
+- lib/active_genie/comparator/debate.rb
+- lib/active_genie/comparator/fight.json
+- lib/active_genie/comparator/fight.prompt.md
+- lib/active_genie/comparator/fight.rb
+- lib/active_genie/configs/comparator_config.rb
+- lib/active_genie/configs/extractor_config.rb
+- lib/active_genie/configs/lister_config.rb
+- lib/active_genie/configs/llm_config.rb
+- lib/active_genie/configs/log_config.rb
+- lib/active_genie/configs/providers/anthropic_config.rb
+- lib/active_genie/configs/providers/deepseek_config.rb
+- lib/active_genie/configs/providers/google_config.rb
+- lib/active_genie/configs/providers/openai_config.rb
+- lib/active_genie/configs/providers/provider_base.rb
+- lib/active_genie/configs/providers_config.rb
+- lib/active_genie/configs/ranker_config.rb
+- lib/active_genie/configs/scorer_config.rb
 - lib/active_genie/configuration.rb
-- lib/active_genie/data_extractor.rb
-- lib/active_genie/data_extractor/from_informal.json
-- lib/active_genie/data_extractor/from_informal.rb
-- lib/active_genie/data_extractor/generalist.json
-- lib/active_genie/data_extractor/generalist.prompt.md
-- lib/active_genie/data_extractor/generalist.rb
 - lib/active_genie/errors/invalid_log_output_error.rb
 - lib/active_genie/errors/invalid_provider_error.rb
-- lib/active_genie/factory.rb
-- lib/active_genie/factory/feud.json
-- lib/active_genie/factory/feud.prompt.md
-- lib/active_genie/factory/feud.rb
+- lib/active_genie/extractor.rb
+- lib/active_genie/extractor/explanation.json
+- lib/active_genie/extractor/explanation.prompt.md
+- lib/active_genie/extractor/explanation.rb
+- lib/active_genie/extractor/litote.json
+- lib/active_genie/extractor/litote.rb
+- lib/active_genie/lister.rb
+- lib/active_genie/lister/feud.json
+- lib/active_genie/lister/feud.prompt.md
+- lib/active_genie/lister/feud.rb
+- lib/active_genie/lister/juries.prompt.md
+- lib/active_genie/lister/juries.rb
 - lib/active_genie/logger.rb
-- lib/active_genie/ranking.rb
-- lib/active_genie/ranking/elo_round.rb
-- lib/active_genie/ranking/free_for_all.rb
-- lib/active_genie/ranking/player.rb
-- lib/active_genie/ranking/players_collection.rb
-- lib/active_genie/ranking/ranking.rb
-- lib/active_genie/ranking/ranking_scoring.rb
-- lib/active_genie/scoring.rb
-- lib/active_genie/scoring/generalist.json
-- lib/active_genie/scoring/generalist.prompt.md
-- lib/active_genie/scoring/generalist.rb
-- lib/active_genie/scoring/recommended_reviewers.rb
+- lib/active_genie/providers/anthropic_provider.rb
+- lib/active_genie/providers/base_provider.rb
+- lib/active_genie/providers/deepseek_provider.rb
+- lib/active_genie/providers/google_provider.rb
+- lib/active_genie/providers/openai_provider.rb
+- lib/active_genie/providers/unified_provider.rb
+- lib/active_genie/ranker.rb
+- lib/active_genie/ranker/elo.rb
+- lib/active_genie/ranker/entities/player.rb
+- lib/active_genie/ranker/entities/players.rb
+- lib/active_genie/ranker/free_for_all.rb
+- lib/active_genie/ranker/scoring.rb
+- lib/active_genie/ranker/tournament.rb
+- lib/active_genie/scorer.rb
+- lib/active_genie/scorer/jury_bench.prompt.md
+- lib/active_genie/scorer/jury_bench.rb
+- lib/active_genie/utils/fiber_by_batch.rb
 - lib/tasks/benchmark.rake
 - lib/tasks/install.rake
 - lib/tasks/templates/active_genie.rb

data/lib/active_genie/battle.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'battle/generalist'
-require_relative 'battle/fight'
-
-module ActiveGenie
-  # See the [Battle README](lib/active_genie/battle/README.md) for more information.
-  module Battle
-    module_function
-
-    def generalist(...)
-      Generalist.call(...)
-    end
-
-    def call(...)
-      Generalist.call(...)
-    end
-
-    def battle(...)
-      Generalist.call(...)
-    end
-
-    def compare(...)
-      Generalist.call(...)
-    end
-
-    def fight(...)
-      Fight.call(...)
-    end
-  end
-end