active_genie 0.29.0 → 0.30.0

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,14 +29,14 @@ 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, reviewers: [], config: {})
+        @players = Players.new(players)
         @criteria = criteria
         @reviewers = Array(reviewers).compact.uniq
         @config = ActiveGenie.configuration.merge(config)
@@ -44,8 +44,7 @@ module ActiveGenie
       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!
@@ -66,15 +65,8 @@ 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,
@@ -83,13 +75,13 @@ module ActiveGenie
       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
@@ -120,17 +112,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 '../clients/unified_client'
+
+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::Clients::UnifiedClient.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.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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'rake/testtask'
+
+namespace :test do
+  Rake::TestTask.new(:unit) do |t|
+    t.pattern = 'test/unit/**/*_test.rb'
+  end
+
+  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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_genie
 version: !ruby/object:Gem::Version
-  version: 0.29.0
+  version: 0.30.0
 platform: ruby
 authors:
 - Radamés Roriz
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-16 00:00:00.000000000 Z
+date: 2025-08-15 00:00:00.000000000 Z
 dependencies: []
 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.
@@ -23,61 +23,62 @@ 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.md
+- lib/active_genie/scorer/jury_bench.rb
 - lib/tasks/benchmark.rake
 - lib/tasks/install.rake
 - lib/tasks/templates/active_genie.rb
+- lib/tasks/test.rake
 homepage: https://github.com/Roriz/active_genie
 licenses:
 - Apache-2.0

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

data/lib/active_genie/clients/unified_client.rb

@@ -1,50 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'providers/openai_client'
-require_relative 'providers/anthropic_client'
-require_relative 'providers/google_client'
-require_relative 'providers/deepseek_client'
-require_relative '../errors/invalid_provider_error'
-
-module ActiveGenie
-  module Clients
-    class UnifiedClient
-      class InvalidProviderError < StandardError; end
-
-      class << self
-        PROVIDER_NAME_TO_CLIENT = {
-          openai: OpenaiClient,
-          anthropic: AnthropicClient,
-          google: GoogleClient,
-          deepseek: DeepseekClient
-        }.freeze
-
-        def function_calling(messages, function, config: {})
-          client = config.llm.client
-
-          unless client
-            provider_name = config.llm.provider || config.providers.default
-            client = PROVIDER_NAME_TO_CLIENT[provider_name.to_sym]
-          end
-
-          raise ActiveGenie::InvalidProviderError, provider_name if client.nil?
-
-          response = client.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/data_extractor.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'data_extractor/generalist'
-require_relative 'data_extractor/from_informal'
-
-module ActiveGenie
-  # See the [DataExtractor README](lib/active_genie/data_extractor/README.md) for more information.
-  module DataExtractor
-    module_function
-
-    def call(...)
-      Generalist.call(...)
-    end
-
-    def generalist(...)
-      Generalist.call(...)
-    end
-
-    def from_informal(...)
-      FromInformal.call(...)
-    end
-  end
-end

data/lib/active_genie/ranking/player.rb

@@ -1,122 +0,0 @@
-# frozen_string_literal: true
-
-require 'digest'
-
-module ActiveGenie
-  module Ranking
-    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 += 1
-      end
-
-      def win!
-        @ffa_win_count += 1
-      end
-
-      def lose!
-        @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