active_genie 0.0.3 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7f834cd4da9f695c2a3f69b1d7d5516831afaa2d6830f89527b46e7e19bc6f9
-  data.tar.gz: 8e14a0011c2551b975105d2120506461fb5f0e9e33206a6960a9de544148016b
+  metadata.gz: 834787b505134623a3f6c4995c9dec8a0ce89a1a014600c4d676d8801bf541cd
+  data.tar.gz: 16ae75ffa3926ecd87052d72ca3f5434be80327b712bb2dba54e55c46fa5ff8d
 SHA512:
-  metadata.gz: ed3662a287028dacf2f60bda458d0de38ad16d4666421e3b836780d9f2dbb469be935e0b6c3d1fff851f82282c4c4564bebc725354f2f213d0cf21e30ce5ce93
-  data.tar.gz: 50b0d666a061361322ec2bfb38ef0e49110d6b31be3c3b55e3873f6ca5389003d739f209c7a9e1b695e3901de703effe02344863fed80495c104e886b1d1fa3f
+  metadata.gz: 1772fbfa59891e7a3673b50a54bd90914007917854e78fb5f0458db681bf89bd1ec118600d23ab98d6255e1b063b5d582d3b73dc738e66aeadc7f4f0bee75af8
+  data.tar.gz: bb6a0ea9ef737f7a2ed3ec558dcea5c67bcc2f90a155828e1e25a5a7a3ebd9d0fe6c5422dd9f3d9ff6fb667b63822e3bc86627cdb3e40a3c72c4ef50cee32c68

data/README.md

@@ -1,86 +1,154 @@
-# ActiveGenie
-Ruby gem for out of the box AI features. LLMs are just a raw tools that need to be polished and refined to be useful. This gem is a collection of tools that can be used to make LLMs more useful and easier to use.
-Think this gem is like ActiveStorage but for LLMs.
+# ActiveGenie 🧞‍♂️
+> Transform your Ruby application with powerful, production-ready GenAI features
 
 [![Gem Version](https://badge.fury.io/rb/active_genie.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/active_genie)
+[![Ruby](https://github.com/roriz/active_genie/actions/workflows/ruby.yml/badge.svg)](https://github.com/roriz/active_genie/actions/workflows/ruby.yml)
+
+ActiveGenie is a Ruby gem that provides a polished, production-ready interface for working with Generative AI (GenAI) models. Just like ActiveStorage simplifies file handling in Rails, ActiveGenie makes it effortless to integrate GenAI capabilities into your Ruby applications.
+
+## Features
+
+- 🎯 **Data Extraction**: Extract structured data from unstructured text with type validation
+- 📊 **Smart Scoring**: Multi-reviewer evaluation system with automatic expert selection
+- 💭 **Sentiment Analysis**: Advanced sentiment analysis with customizable rules
+- 🔒 **Safe & Secure**: Built-in validation and sanitization
+- 🛠️ **Configurable**: Supports multiple GenAI providers and models
 
 ## Installation
-Add this line to your application's Gemfile:
 
-1. Add the gem to your Gemfile
+1. Add to your Gemfile:
 ```ruby
 gem 'active_genie'
 ```
-2. install the gem
+
+2. Install the gem:
 ```shell
 bundle install
 ```
-3. call the initializer to create default configurations
+
+3. Generate the configuration:
 ```shell
+echo "ActiveGenie.load_tasks" >> Rakefile
 rails g active_genie:install
 ```
-4. Add the right credentials to the `config/active_genie.yml` file
+
+4. [Optional] Configure your credentials in `config/active_genie.yml`:
 ```yaml
 GPT-4o-mini:
   api_key: <%= ENV['OPENAI_API_KEY'] %>
   provider: "openai"
+
+claude-3-5-sonnet:
+  api_key: <%= ENV['ANTHROPIC_API_KEY'] %>
+  provider: "anthropic"
 ```
 
-## Quick Example
-```ruby
-require 'active_genie'
+> The first key will be used as default in all modules, in this example `GPT-4o-mini`
 
-puts ActiveGenie::DataExtractor.call(
-  "Hello, my name is Radamés Roriz",
-  { full_name: { type: 'string' } },
-  options: { model: 'gpt-4o-mini', api_key: 'your-api-key', provider: 'openai' } # Optional if has config/active_genie.yml
-) # => { full_name: "Radamés Roriz" }
-```
+## Quick Start
 
 ### Data Extractor
-Extract structured data from text using LLM-powered analysis, handling informal language and complex expressions.
+Extract structured data from text using AI-powered analysis, handling informal language and complex expressions.
 
 ```ruby
-require 'active_genie'
-
-text = "iPhone 14 Pro Max"
+text = "Nike Air Max 90 - Size 42 - $199.99"
 schema = {
-  brand: { type: 'string' },
-  model: { type: 'string' }
+  brand: { 
+    type: 'string',
+    enum: ["Nike", "Adidas", "Puma"]
+  },
+  price: { 
+    type: 'number',
+    minimum: 0
+  },
+  size: {
+    type: 'integer',
+    minimum: 35,
+    maximum: 46
+  }
 }
-result = ActiveGenie::DataExtractor.call(
-  text,
-  schema,
-  options: { model: 'GPT-4o-mini', api_key: 'your-api-key', provider: 'openai' } # Optional if 
-)
-# => { brand: "iPhone", model: "14 Pro Max" }
+
+result = ActiveGenie::DataExtractor.call(text, schema)
+# => { 
+#      brand: "Nike", 
+#      brand_explanation: "Brand name found at start of text",
+#      price: 199.99,
+#      price_explanation: "Price found in USD format at end",
+#      size: 42,
+#      size_explanation: "Size explicitly stated in the middle"
+#    }
 ```
 
-- More examples in the [Data Extractor README](lib/data_extractor/README.md)
-- Extract from ambiguous [from_informal](lib/data_extractor/README.md#extract-from-informal-text)
-- Interface details in the [Interface](lib/data_extractor/README.md#interface)
+Features:
+- Structured data extraction with type validation
+- Schema-based extraction with custom constraints
+- Informal text analysis (litotes, hedging)
+- Detailed explanations for extracted values
 
-### Summarizer (WIP)
-The summarizer is a tool that can be used to summarize a given text. It uses a set of rules to summarize the text out of the box. Uses the best practices of prompt engineering and engineering to make the summarization as accurate as possible.
+See the [Data Extractor README](lib/active_genie/data_extractor/README.md) for informal text processing, advanced schemas, and detailed interface documentation.
+
+### Scoring
+Text evaluation system that provides detailed scoring and feedback using multiple expert reviewers. Get balanced scoring through AI-powered expert reviewers that automatically adapt to your content.
+
+```ruby
+text = "The code implements a binary search algorithm with O(log n) complexity"
+criteria = "Evaluate technical accuracy and clarity"
+
+result = ActiveGenie::Scoring::Basic.call(text, criteria)
+# => {
+#      algorithm_expert_score: 95,
+#      algorithm_expert_reasoning: "Accurately describes binary search and its complexity",
+#      technical_writer_score: 90,
+#      technical_writer_reasoning: "Clear and concise explanation of the algorithm",
+#      final_score: 92.5
+#    }
+```
+
+Features:
+- Multi-reviewer evaluation with automatic expert selection
+- Detailed feedback with scoring reasoning
+- Customizable reviewer weights
+- Flexible evaluation criteria
+
+See the [Scoring README](lib/active_genie/scoring/README.md) for advanced usage, custom reviewers, and detailed interface documentation.
+
+### Battle
+AI-powered battle evaluation system that determines winners between two players based on specified criteria.
 
 ```ruby
 require 'active_genie'
 
-text = "Example text to be summarized. The fox jumps over the dog"
-summarized_text = ActiveGenie::Summarizer.call(text)
-puts summarized_text # => "The fox jumps over the dog"
+player_a = "Implementation uses dependency injection for better testability"
+player_b = "Code has high test coverage but tightly coupled components"
+criteria = "Evaluate code quality and maintainability"
+
+result = ActiveGenie::Battle::Basic.call(player_a, player_b, criteria)
+# => {
+#      winner_player: "Implementation uses dependency injection for better testability",
+#      reasoning: "Player A's implementation demonstrates better maintainability through dependency injection, 
+#                 which allows for easier testing and component replacement. While Player B has good test coverage, 
+#                 the tight coupling makes the code harder to maintain and modify.",
+#      what_could_be_changed_to_avoid_draw: "Focus on specific architectural patterns and design principles"
+#    }
 ```
 
-### Scorer (WIP)
-The scorer is a tool that can be used to score a given text. It uses a set of rules to score the text out of the box. Uses the best practices of prompt engineering and engineering to make the scoring as accurate as possible.
+Features:
+- Multi-reviewer evaluation with automatic expert selection
+- Detailed feedback with scoring reasoning
+- Customizable reviewer weights
+- Flexible evaluation criteria
+
+See the [Battle README](lib/active_genie/battle/README.md) for advanced usage, custom reviewers, and detailed interface documentation.
+
+### Summarizer (WIP)
+The summarizer is a tool that can be used to summarize a given text. It uses a set of rules to summarize the text out of the box. Uses the best practices of prompt engineering and engineering to make the summarization as accurate as possible.
 
 ```ruby
 require 'active_genie'
 
-text = "Example text to be scored. The fox jumps over the dog"
-criterias = 'Grammar, Relevance'
-score = ActiveGenie::Scorer.call(text, criterias)
-puts score # => { 'Grammar' => 0.8, 'Relevance' => 1.0, total: 0.9 }
+text = "Example text to be summarized. The fox jumps over the dog"
+summarized_text = ActiveGenie::Summarizer.call(text)
+puts summarized_text # => "The fox jumps over the dog"
 ```
 
 ### Language detector (WIP)
@@ -128,9 +196,27 @@ ranked_items = ActiveGenie::EloRanking.call(items, criterias, rounds: 10)
 puts ranked_items # => [{ name: "Circle", score: 1500 }, { name: "Square", score: 800 }, { name: "Triangle", score: 800 }]
 ```
 
-## Good practices
-- LLMs can take a long time to respond, so avoid putting them in the main thread
-- Do not use the LLMs to extract sensitive or personal data
 
+## Configuration Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `provider` | LLM provider (openai, anthropic, etc) | `nil` |
+| `model` | Model to use | `nil` |
+| `api_key` | Provider API key | `nil` |
+| `timeout` | Request timeout in seconds | `5` |
+| `max_retries` | Maximum retry attempts | `3` |
+
+> **Note:** Each module can append its own set of configuration options, see the individual module documentation for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
 ## License
-See the [LICENSE](LICENSE)
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+

data/VERSION

@@ -1 +1 @@
-0.0.3
+0.0.8

data/lib/active_genie/battle/README.md

@@ -0,0 +1,39 @@
+# Battle
+AI-powered battle evaluation system that determines winners between two players based on specified criteria.
+
+## Features
+- Content comparison - Evaluate submissions from two players against defined criteria
+- Objective analysis - AI-powered assessment of how well each player meets requirements
+- Detailed reasoning - Comprehensive explanation of why a winner was chosen
+- Draw avoidance - Suggestions on how to modify content to avoid draws
+- Flexible input - Support for both string content and structured data with content field
+
+## Basic Usage
+Evaluate a battle between two players with simple text content:
+
+```ruby
+player_a = "Implementation uses dependency injection for better testability"
+player_b = "Code has high test coverage but tightly coupled components"
+criteria = "Evaluate code quality and maintainability"
+
+result = ActiveGenie::Battle::Basic.call(player_a, player_b, criteria)
+# => {
+#      winner_player: "Implementation uses dependency injection for better testability",
+#      reasoning: "Player A's implementation demonstrates better maintainability through dependency injection, 
+#                 which allows for easier testing and component replacement. While Player B has good test coverage, 
+#                 the tight coupling makes the code harder to maintain and modify.",
+#      what_could_be_changed_to_avoid_draw: "Focus on specific architectural patterns and design principles"
+#    }
+```
+
+## Interface
+### Basic.call(player_a, player_b, criteria, options: {})
+- `player_a` [String, Hash] - The content or submission from the first player
+- `player_b` [String, Hash] - The content or submission from the second player
+- `criteria` [String] - The evaluation criteria or rules to assess against
+- `options` [Hash] - Additional configuration options that modify the battle evaluation behavior
+
+Returns a Hash containing:
+- `winner_player` [String, Hash] - The winning player's content (either player_a or player_b)
+- `reasoning` [String] - Detailed explanation of why the winner was chosen
+- `what_could_be_changed_to_avoid_draw` [String] - A suggestion on how to avoid a draw

data/lib/active_genie/battle/basic.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative '../clients/router'
+
+module ActiveGenie::Battle
+  # The Basic class provides a foundation for evaluating battles between two players
+  # using AI-powered evaluation. It determines a winner based on specified criteria,
+  # analyzing how well each player meets the requirements.
+  #
+  # The battle evaluation process compares two players' content against given criteria
+  # and returns detailed feedback including the winner and reasoning for the decision.
+  #
+  # @example Basic usage with two players and criteria
+  #   Basic.call("Player A content", "Player B content", "Evaluate keyword usage and pattern matching")
+  #
+  class Basic
+    def self.call(player_a, player_b, criteria, options: {})
+      new(player_a, player_b, criteria, options:).call
+    end
+
+    # @param player_a [String] The content or submission from the first player
+    # @param player_b [String] The content or submission from the second player
+    # @param criteria [String] The evaluation criteria or rules to assess against
+    # @param options [Hash] Additional configuration options that modify the battle evaluation behavior
+    # @return [Hash] The evaluation result containing the winner and reasoning
+    #   @return [String] :winner The @param player_a or player_b
+    #   @return [String] :reasoning Detailed explanation of why the winner was chosen
+    #   @return [String] :what_could_be_changed_to_avoid_draw A suggestion on how to avoid a draw
+    def initialize(player_a, player_b, criteria, options: {})
+      @player_a = player_a
+      @player_b = player_b
+      @criteria = criteria
+      @options = options
+      @response = nil
+    end
+
+    def call
+      messages = [
+        {  role: 'system', content: PROMPT },
+        {  role: 'user', content: "criteria: #{@criteria}" },
+        {  role: 'user', content: "player_a: #{player_content(@player_a)}" },
+        {  role: 'user', content: "player_b: #{player_content(@player_b)}" },
+      ]
+
+      @response = ::ActiveGenie::Clients::Router.function_calling(messages, FUNCTION, options: @options)
+
+      response_formatted
+    end
+
+    private
+
+    def player_content(player)
+      return player.dig('content') if player.is_a?(Hash)
+
+      player
+    end
+
+    def response_formatted
+      if @response['winner'] == 'player_a'
+        @response['winner'] = @player_a
+        @response['loser'] = @player_b
+      elsif @response['winner'] == 'player_b'
+        @response['winner'] = @player_b
+        @response['loser'] = @player_a
+      else
+        @response['winner'] = nil
+        @response['loser'] = nil
+      end
+
+      @response
+    end
+
+    PROMPT = <<~PROMPT
+    Evaluate a battle between player_a and player_b using predefined criteria and identify the winner.
+
+    Consider rules, keywords, and patterns as the criteria for evaluation. Analyze the content from both players objectively, focusing on who meets the criteria most effectively. Explain your decision clearly, with specific reasoning on how the chosen player fulfilled the criteria better than the other. Avoid selecting a draw unless absolutely necessary.
+
+    # Steps
+    1. **Review Predefined Criteria**: Understand the specific rules, keywords, and patterns that serve as the basis for evaluation.
+    2. **Analyze Content**: Examine the contributions of both player_a and player_b. Look for how each player meets or fails to meet the criteria.
+    3. **Comparison**: Compare both players against each criterion to determine who aligns better with the standards set.
+    4. **Decision-Making**: Based on the analysis, determine the player who meets the most or all criteria effectively.
+    5. **Provide Justification**: Offer a clear and concise reason for your choice detailing how the winner outperformed the other.
+
+    # Examples
+    - **Example 1**:
+      - Input: Player A uses keyword X, follows rule Y, Player B uses keyword Z, breaks rule Y.
+      - Output: winner: player_a
+        - Justification: Player A successfully used keyword X and followed rule Y, whereas Player B broke rule Y.
+
+    - **Example 2**:
+      - Input: Player A matches pattern P, Player B matches pattern P, uses keyword Q.
+      - Output: winner: player_b
+        - Justification: Both matched pattern P, but Player B also used keyword Q, meeting more criteria.
+
+    # Notes
+    - Avoid drawing if a clear winner can be discerned.
+    - Critically assess each player's adherence to the criteria.
+    - Clearly communicate the reasoning behind your decision.
+    PROMPT
+
+    FUNCTION =  {
+      name: 'battle_evaluation',
+      description: 'Evaluate a battle between player_a and player_b using predefined criteria and identify the winner.',
+      schema: {
+        type: "object",
+        properties: {
+          winner: {
+            type: 'string',
+            description: 'The player who won the battle based on the criteria.',
+            enum: ['player_a', 'player_b', 'draw']
+          },
+          reasoning_of_winner: {
+            type: 'string',
+            description: 'The detailed reasoning about why the winner won based on the criteria.',
+          },
+          what_could_be_changed_to_avoid_draw: {
+            type: 'string',
+            description: 'Suggestions on how to avoid a draw based on the criteria. Be as objective and short as possible. Can be empty.',
+          }
+        }
+      }
+    }
+  end
+end

data/lib/active_genie/battle.rb

@@ -0,0 +1,13 @@
+
+require_relative 'battle/basic'
+
+module ActiveGenie
+  # Battle module
+  module Battle
+    module_function
+
+    def basic(...)
+      Basic.call(...)
+    end
+  end
+end

data/lib/active_genie/clients/openai.rb

@@ -28,7 +28,9 @@ module ActiveGenie::Clients
 
         response = request(payload, headers)
 
-        JSON.parse(response.dig('choices', 0, 'message', 'content'))
+        parsed_response = JSON.parse(response.dig('choices', 0, 'message', 'content'))
+        
+        parsed_response.dig('properties') || parsed_response
       rescue JSON::ParserError
         nil
       end

data/lib/active_genie/configuration.rb

@@ -5,7 +5,7 @@ module ActiveGenie
     attr_accessor :path_to_config
 
     def initialize
-      @path_to_config = File.join(__dir__, 'config', 'gen_ai.yml')
+      @path_to_config = File.join('config', 'active_genie.yml')
     end
 
     def values
@@ -23,7 +23,8 @@ module ActiveGenie
     def load_values
       return {} unless File.exist?(@path_to_config)
 
-      YAML.load_file(@path_to_config) || {}
+      yaml_content = ERB.new(File.read(@path_to_config)).result
+      YAML.safe_load(yaml_content, aliases: true) || {}
     rescue Psych::SyntaxError => e
       warn "ActiveGenie.warning: Config file '#{@path_to_config}' is not a valid YAML file (#{e.message}), using default configuration"
       {}

data/lib/active_genie/data_extractor.rb

@@ -6,12 +6,12 @@ module ActiveGenie
   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/leaderboard/elo_ranking.rb

@@ -0,0 +1,88 @@
+require_relative '../battle/basic'
+require_relative '../utils/math'
+
+module ActiveGenie::Leaderboard
+  class EloRanking
+    def self.call(players, criteria, options: {})
+      new(players, criteria, options:).call
+    end
+
+    def initialize(players, criteria, options: {})
+      @players = players
+      @criteria = criteria
+      @options = options
+    end
+
+    def call
+      @players.each(&:generate_elo_by_score)
+
+      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)
+        end
+
+        @players.tier_relegation.each { |player| player.eliminated = "relegation/#{@players.eligible_size}" }
+      end
+
+      @players
+    end
+
+    private
+
+    MATCHS_PER_PLAYER = 3
+    LOSE_PENALTY = 15
+    MINIMAL_PLAYERS_TO_BATTLE = 10
+
+    # 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,
+        options: @options
+      ).values_at('winner', 'loser')
+    end
+
+    def update_elo(winner, loser)
+      return if winner.nil? || loser.nil?
+
+      new_winner_elo, new_loser_elo = ActiveGenie::Utils::Math.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
+  end
+end

data/lib/active_genie/leaderboard/leaderboard.rb

@@ -0,0 +1,72 @@
+require_relative './players_collection'
+require_relative './league'
+require_relative './elo_ranking'
+require_relative '../scoring/recommended_reviews'
+
+module ActiveGenie::Leaderboard
+  class Leaderboard
+    def self.call(param_players, criteria, options: {})
+      new(param_players, criteria, options:).call
+    end
+
+    def initialize(param_players, criteria, options: {})
+      @param_players = param_players
+      @criteria = criteria
+      @options = options
+    end
+
+    def call
+      set_initial_score_players
+      eliminate_obvious_bad_players
+      run_elo_ranking if players.eligible_size > 10
+      run_league
+
+      players.to_h
+    end
+
+    private
+
+    SCORE_VARIATION_THRESHOLD = 10
+    MATCHS_PER_PLAYER = 3
+
+    def set_initial_score_players
+      players.each do |player|
+        player.score = generate_score(player.content) # This can take a while, can be parallelized
+      end
+    end
+
+    def generate_score(content)
+      ActiveGenie::Scoring::Basic.call(content, @criteria, reviewers, options: @options)['final_score']
+    end
+
+    def eliminate_obvious_bad_players
+      while players.coefficient_of_variation >= SCORE_VARIATION_THRESHOLD
+        players.eligible.last.eliminated = 'too_low_score'
+      end
+    end
+
+    def run_elo_ranking
+      EloRanking.call(players, @criteria, options: @options)
+    end
+
+    def run_league
+      League.call(players, @criteria, options: @options)
+    end
+
+    def reviewers
+      [recommended_reviews['reviewer1'], recommended_reviews['reviewer2'], recommended_reviews['reviewer3']]
+    end
+
+    def recommended_reviews
+      @recommended_reviews ||= ActiveGenie::Scoring::RecommendedReviews.call(
+        players.sample,
+        @criteria,
+        options: @options
+      )
+    end
+
+    def players
+      @players ||= PlayersCollection.new(@param_players)
+    end
+  end
+end

data/lib/active_genie/leaderboard/league.rb

@@ -0,0 +1,48 @@
+require_relative '../battle/basic'
+
+module ActiveGenie::Leaderboard
+  class League
+    def self.call(players, criteria, options: {})
+      new(players, criteria, options:).call
+    end
+
+    def initialize(players, criteria, options: {})
+      @players = players
+      @criteria = criteria
+      @options = options
+    end
+
+    def call
+      matches.each do |player_a, player_b|
+        winner, loser = battle(player_a, player_b)
+
+        if winner.nil? || loser.nil?
+          player_a.league[:draw] += 1
+          player_b.league[:draw] += 1
+        else
+          winner.league[:win] += 1
+          loser.league[:lose] += 1
+        end
+      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)
+      ActiveGenie::Battle.basic(
+        player_a,
+        player_b,
+        @criteria,
+        options: @options
+      ).values_at('winner', 'loser')
+    end
+  end
+end

data/lib/active_genie/leaderboard/player.rb

@@ -0,0 +1,52 @@
+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
+      @league = {
+        win: params.dig(:league, :win) || 0,
+        lose: params.dig(:league, :lose) || 0,
+        draw: params.dig(:league, :draw) || 0
+      }
+      @eliminated = params.dig(:eliminated) || nil
+    end
+
+    attr_reader :id, :content, :score, :elo, :league, :eliminated
+
+    def generate_elo_by_score
+      return if !@elo.nil? || @score.nil?
+
+      @elo = BASE_ELO + (@score - 50)
+    end
+
+    def score=(value)
+      @score = value
+    end
+
+    def elo=(value)
+      @elo = value
+    end
+
+    def eliminated=(value)
+      @eliminated = value
+    end
+
+    def league_score
+      @league[:win] * 3 + @league[:draw]
+    end
+
+    def to_h
+      { id:, content:, score:, elo:, eliminated:, league: }
+    end
+
+    private
+    
+    BASE_ELO = 1000
+  end
+end

data/lib/active_genie/leaderboard/players_collection.rb

@@ -0,0 +1,68 @@
+require_relative '../utils/math'
+require_relative './player'
+
+module ActiveGenie::Leaderboard
+  class PlayersCollection
+    def initialize(param_players)
+      @players = build(param_players)
+    end
+    attr_reader :players
+
+    def coefficient_of_variation
+      score_list = eligible.map(&:score)
+      mean = score_list.sum.to_f / score_list.size
+      return nil if mean == 0  # To avoid division by zero
+
+      variance = score_list.map { |num| (num - mean) ** 2 }.sum / score_list.size
+      standard_deviation = Math.sqrt(variance)
+
+      (standard_deviation / mean) * 100
+    end
+
+    def tier_relegation
+      eligible[(tier_size*-1)..-1]
+    end
+
+    def tier_defense
+      eligible[(tier_size*-2)...(tier_size*-1)]
+    end
+
+    def eligible
+      sorted.reject(&:eliminated)
+    end
+
+    def eligible_size
+      @players.reject(&:eliminated).size
+    end
+
+    def to_h
+      sorted.map(&:to_h)
+    end
+
+    def method_missing(...)
+      @players.send(...)
+    end
+
+    def sorted
+      @players.sort_by { |p| [-p.league_score, -(p.elo || 0), -p.score] }
+    end
+
+    private
+
+    def build(param_players)
+      param_players.map { |player| Player.new(player) }
+    end
+
+    # Returns the number of players to battle 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
+      [[(eligible_size / 3).ceil, 10].max, eligible_size - 10].min
+    end
+  end
+end

data/lib/active_genie/leaderboard.rb

@@ -0,0 +1,11 @@
+require_relative 'leaderboard/leaderboard'
+
+module ActiveGenie
+  module Leaderboard
+    module_function
+
+    def call(...)
+      Leaderboard.call(...)
+    end
+  end
+end

data/lib/active_genie/scoring/basic.rb

@@ -17,12 +17,6 @@ module ActiveGenie::Scoring
   #   Basic.call("Sample text", "Evaluate technical accuracy")
   #
   class Basic
-    def self.call(text, criteria, reviewers = [], options: {})
-      new(text, criteria, reviewers, options:).call
-    end
-
-    # Initializes a new scoring evaluation instance
-    #
     # @param text [String] The text content to be evaluated
     # @param criteria [String] The evaluation criteria or rubric to assess against
     # @param reviewers [Array<String>] Optional list of specific reviewers. If empty,
@@ -30,6 +24,13 @@ module ActiveGenie::Scoring
     # @param options [Hash] Additional configuration options that modify the scoring behavior
     # @option options [Boolean] :detailed_feedback Request more detailed feedback in the reasoning
     # @option options [Hash] :reviewer_weights Custom weights for different reviewers
+    # @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 reviewers
+    #   @return [String] :final_reasoning Detailed explanation of why the final score was reached
+    def self.call(text, criteria, reviewers = [], options: {})
+      new(text, criteria, reviewers, options:).call
+    end
+
     def initialize(text, criteria, reviewers = [], options: {})
       @text = text
       @criteria = criteria

data/lib/active_genie/scoring/recommended_reviews.rb

@@ -55,7 +55,7 @@ module ActiveGenie::Scoring
         }
       }
 
-      ::ActiveGenie::Clients::Router.function_calling(messages, function, options:)
+      ::ActiveGenie::Clients::Router.function_calling(messages, function, options: @options)
     end
 
     private

data/lib/active_genie/scoring.rb

@@ -6,12 +6,12 @@ module ActiveGenie
   module Scoring
     module_function
 
-    def basic(text, criteria, reviewers = [], options: {})
-      Basic.call(text, criteria, reviewers, options:)
+    def basic(...)
+      Basic.call(...)
     end
 
-    def recommended_reviews(text, criteria, options: {})
-      RecommendedReviews.call(text, criteria, options:)
+    def recommended_reviews(...)
+      RecommendedReviews.call(...)
     end
   end
 end

data/lib/active_genie/utils/math.rb

@@ -0,0 +1,15 @@
+module ActiveGenie::Utils
+  module Math
+    module_function
+
+    def self.calculate_new_elo(winner, loser, k: 32)
+      expected_score_a = 1 / (1 + 10**((loser - winner) / 400))
+      expected_score_b = 1 - expected_score_a
+
+      new_elo_winner = winner + k * (1 - expected_score_a)
+      new_elo_loser = loser + k * (1 - expected_score_b)
+
+      [new_elo_winner, new_elo_loser]
+    end
+  end
+end

data/lib/active_genie.rb

@@ -1,22 +1,33 @@
 module ActiveGenie
+  autoload :Configuration, File.join(__dir__, 'active_genie/configuration')
+
+  # Modules
   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 :Configuration, File.join(__dir__, 'active_genie/configuration')
+  autoload :Leaderboard, File.join(__dir__, 'active_genie/leaderboard')
+
+  class << self    
+    def configure
+      yield(config) if block_given?
+    end
+
+    def load_tasks
+      return unless defined?(Rake)
+
+      Rake::Task.define_task(:environment)
+      Dir.glob(File.join(__dir__, 'tasks', '*.rake')).each { |r| load r }
+    end
 
-  class << self
     def config
       @config ||= Configuration.new
     end
 
-    def configure
-      yield(config) if block_given?
-    end
-    
     def [](key)
       config.values[key.to_s]
     end
 
-    def config_by_model(model)
+    def config_by_model(model = nil)
       config.values[model&.to_s&.downcase&.strip] || config.values.values.first || {}
     end
   end

data/lib/tasks/install.rake

@@ -3,7 +3,7 @@ require 'fileutils'
 namespace :active_genie do
   desc 'Install active_genie configuration file'
   task :install do
-    source = File.join('lib', 'tasks', 'templates', 'active_genie.yml')
+    source = File.join(__dir__, 'templates', 'active_genie.yml')
     target = File.join('config', 'active_genie.yml')
 
     FileUtils.cp(source, target)

data/lib/tasks/templates/{active_ai.yml → active_genie.yml}

@@ -1,4 +1,4 @@
-# GPT-4o-mini:
+# gpt-4o-mini:
 #   api_key: <%= ENV['OPENAI_API_KEY'] %>
 #   provider: 'openai'
 # 

metadata

@@ -1,22 +1,113 @@
 --- !ruby/object:Gem::Specification
 name: active_genie
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.8
 platform: ruby
 authors:
 - Radamés Roriz
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-01-25 00:00:00.000000000 Z
+date: 2025-02-06 00:00:00.000000000 Z
 dependencies: []
-description: |2
-      ActiveGenie provides a robust toolkit for integrating AI capabilities into Ruby applications.
-      Features include:
-      * Structured data extraction from text
-      * Smart text summarization
-      * Content scoring and ranking
-      * AI-powered classification
+description: "# ActiveGenie \U0001F9DE‍♂️\n> Transform your Ruby application with
+  powerful, production-ready GenAI features\n\n[![Gem Version](https://badge.fury.io/rb/active_genie.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/active_genie)\n[![Ruby](https://github.com/roriz/active_genie/actions/workflows/ruby.yml/badge.svg)](https://github.com/roriz/active_genie/actions/workflows/ruby.yml)\n\nActiveGenie
+  is a Ruby gem that provides a polished, production-ready interface for working with
+  Generative AI (GenAI) models. Just like ActiveStorage simplifies file handling in
+  Rails, ActiveGenie makes it effortless to integrate GenAI capabilities into your
+  Ruby applications.\n\n## Features\n\n- \U0001F3AF **Data Extraction**: Extract structured
+  data from unstructured text with type validation\n- \U0001F4CA **Smart Scoring**:
+  Multi-reviewer evaluation system with automatic expert selection\n- \U0001F4AD **Sentiment
+  Analysis**: Advanced sentiment analysis with customizable rules\n- \U0001F512 **Safe
+  & Secure**: Built-in validation and sanitization\n- \U0001F6E0️ **Configurable**:
+  Supports multiple GenAI providers and models\n\n## Installation\n\n1. Add to your
+  Gemfile:\n```ruby\ngem 'active_genie'\n```\n\n2. Install the gem:\n```shell\nbundle
+  install\n```\n\n3. Generate the configuration:\n```shell\necho \"ActiveGenie.load_tasks\"
+  >> Rakefile\nrails g active_genie:install\n```\n\n4. [Optional] Configure your credentials
+  in `config/active_genie.yml`:\n```yaml\nGPT-4o-mini:\n  api_key: <%= ENV['OPENAI_API_KEY']
+  %>\n  provider: \"openai\"\n\nclaude-3-5-sonnet:\n  api_key: <%= ENV['ANTHROPIC_API_KEY']
+  %>\n  provider: \"anthropic\"\n```\n\n> The first key will be used as default in
+  all modules, in this example `GPT-4o-mini`\n\n## Quick Start\n\n### Data Extractor\nExtract
+  structured data from text using AI-powered analysis, handling informal language
+  and complex expressions.\n\n```ruby\ntext = \"Nike Air Max 90 - Size 42 - $199.99\"\nschema
+  = {\n  brand: { \n    type: 'string',\n    enum: [\"Nike\", \"Adidas\", \"Puma\"]\n
+  \ },\n  price: { \n    type: 'number',\n    minimum: 0\n  },\n  size: {\n    type:
+  'integer',\n    minimum: 35,\n    maximum: 46\n  }\n}\n\nresult = ActiveGenie::DataExtractor.call(text,
+  schema)\n# => { \n#      brand: \"Nike\", \n#      brand_explanation: \"Brand name
+  found at start of text\",\n#      price: 199.99,\n#      price_explanation: \"Price
+  found in USD format at end\",\n#      size: 42,\n#      size_explanation: \"Size
+  explicitly stated in the middle\"\n#    }\n```\n\nFeatures:\n- Structured data extraction
+  with type validation\n- Schema-based extraction with custom constraints\n- Informal
+  text analysis (litotes, hedging)\n- Detailed explanations for extracted values\n\nSee
+  the [Data Extractor README](lib/active_genie/data_extractor/README.md) for informal
+  text processing, advanced schemas, and detailed interface documentation.\n\n###
+  Scoring\nText evaluation system that provides detailed scoring and feedback using
+  multiple expert reviewers. Get balanced scoring through AI-powered expert reviewers
+  that automatically adapt to your content.\n\n```ruby\ntext = \"The code implements
+  a binary search algorithm with O(log n) complexity\"\ncriteria = \"Evaluate technical
+  accuracy and clarity\"\n\nresult = ActiveGenie::Scoring::Basic.call(text, criteria)\n#
+  => {\n#      algorithm_expert_score: 95,\n#      algorithm_expert_reasoning: \"Accurately
+  describes binary search and its complexity\",\n#      technical_writer_score: 90,\n#
+  \     technical_writer_reasoning: \"Clear and concise explanation of the algorithm\",\n#
+  \     final_score: 92.5\n#    }\n```\n\nFeatures:\n- Multi-reviewer evaluation with
+  automatic expert selection\n- Detailed feedback with scoring reasoning\n- Customizable
+  reviewer weights\n- Flexible evaluation criteria\n\nSee the [Scoring README](lib/active_genie/scoring/README.md)
+  for advanced usage, custom reviewers, and detailed interface documentation.\n\n###
+  Battle\nAI-powered battle evaluation system that determines winners between two
+  players based on specified criteria.\n\n```ruby\nrequire 'active_genie'\n\nplayer_a
+  = \"Implementation uses dependency injection for better testability\"\nplayer_b
+  = \"Code has high test coverage but tightly coupled components\"\ncriteria = \"Evaluate
+  code quality and maintainability\"\n\nresult = ActiveGenie::Battle::Basic.call(player_a,
+  player_b, criteria)\n# => {\n#      winner_player: \"Implementation uses dependency
+  injection for better testability\",\n#      reasoning: \"Player A's implementation
+  demonstrates better maintainability through dependency injection, \n#                 which
+  allows for easier testing and component replacement. While Player B has good test
+  coverage, \n#                 the tight coupling makes the code harder to maintain
+  and modify.\",\n#      what_could_be_changed_to_avoid_draw: \"Focus on specific
+  architectural patterns and design principles\"\n#    }\n```\n\nFeatures:\n- Multi-reviewer
+  evaluation with automatic expert selection\n- Detailed feedback with scoring reasoning\n-
+  Customizable reviewer weights\n- Flexible evaluation criteria\n\nSee the [Battle
+  README](lib/active_genie/battle/README.md) for advanced usage, custom reviewers,
+  and detailed interface documentation.\n\n### Summarizer (WIP)\nThe summarizer is
+  a tool that can be used to summarize a given text. It uses a set of rules to summarize
+  the text out of the box. Uses the best practices of prompt engineering and engineering
+  to make the summarization as accurate as possible.\n\n```ruby\nrequire 'active_genie'\n\ntext
+  = \"Example text to be summarized. The fox jumps over the dog\"\nsummarized_text
+  = ActiveGenie::Summarizer.call(text)\nputs summarized_text # => \"The fox jumps
+  over the dog\"\n```\n\n### Language detector (WIP)\nThe language detector is a tool
+  that can be used to detect the language of a given text. It uses a set of rules
+  to detect the language of the text out of the box. Uses the best practices of prompt
+  engineering and engineering to make the language detection as accurate as possible.\n\n```ruby\nrequire
+  'active_genie'\n\ntext = \"Example text to be detected\"\nlanguage = ActiveGenie::LanguageDetector.call(text)\nputs
+  language # => \"en\"\n```\n\n### Translator (WIP)\nThe translator is a tool that
+  can be used to translate a given text. It uses a set of rules to translate the text
+  out of the box. Uses the best practices of prompt engineering and engineering to
+  make the translation as accurate as possible.\n\n```ruby\nrequire 'active_genie'\n\ntext
+  = \"Example text to be translated\"\ntranslated_text = ActiveGenie::Translator.call(text,
+  from: 'en', to: 'pt')\nputs translated_text # => \"Exemplo de texto a ser traduzido\"\n```\n\n###
+  Sentiment analyzer (WIP)\nThe sentiment analyzer is a tool that can be used to analyze
+  the sentiment of a given text. It uses a set of rules to analyze the sentiment of
+  the text out of the box. Uses the best practices of prompt engineering and engineering
+  to make the sentiment analysis as accurate as possible.\n\n```ruby\nrequire 'active_genie'\n\ntext
+  = \"Example text to be analyzed\"\nsentiment = ActiveGenie::SentimentAnalyzer.call(text)\nputs
+  sentiment # => \"positive\"\n```\n\n### Elo ranking (WIP)\nThe Elo ranking is a
+  tool that can be used to rank a set of items. It uses a set of rules to rank the
+  items out of the box. Uses the best practices of prompt engineering and engineering
+  to make the ranking as accurate as possible.\n\n```ruby\nrequire 'active_genie'\n\nitems
+  = ['Square', 'Circle', 'Triangle']\ncriterias = 'items that look rounded'\nranked_items
+  = ActiveGenie::EloRanking.call(items, criterias, rounds: 10)\nputs ranked_items
+  # => [{ name: \"Circle\", score: 1500 }, { name: \"Square\", score: 800 }, { name:
+  \"Triangle\", score: 800 }]\n```\n\n\n## Configuration Options\n\n| Option | Description
+  | Default |\n|--------|-------------|---------|\n| `provider` | LLM provider (openai,
+  anthropic, etc) | `nil` |\n| `model` | Model to use | `nil` |\n| `api_key` | Provider
+  API key | `nil` |\n| `timeout` | Request timeout in seconds | `5` |\n| `max_retries`
+  | Maximum retry attempts | `3` |\n\n> **Note:** Each module can append its own set
+  of configuration options, see the individual module documentation for details.\n\n##
+  Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout
+  -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing
+  feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5.
+  Open a Pull Request\n## License\n\nThis project is licensed under the MIT License
+  - see the [LICENSE](LICENSE) file for details.\n\n"
 email:
 - radames@roriz.dev
 executables: []
@@ -27,6 +118,9 @@ files:
 - README.md
 - VERSION
 - lib/active_genie.rb
+- lib/active_genie/battle.rb
+- lib/active_genie/battle/README.md
+- lib/active_genie/battle/basic.rb
 - lib/active_genie/clients/openai.rb
 - lib/active_genie/clients/router.rb
 - lib/active_genie/configuration.rb
@@ -34,12 +128,19 @@ files:
 - lib/active_genie/data_extractor/README.md
 - lib/active_genie/data_extractor/basic.rb
 - lib/active_genie/data_extractor/from_informal.rb
+- lib/active_genie/leaderboard.rb
+- lib/active_genie/leaderboard/elo_ranking.rb
+- lib/active_genie/leaderboard/leaderboard.rb
+- lib/active_genie/leaderboard/league.rb
+- lib/active_genie/leaderboard/player.rb
+- lib/active_genie/leaderboard/players_collection.rb
 - lib/active_genie/scoring.rb
 - lib/active_genie/scoring/README.md
 - lib/active_genie/scoring/basic.rb
 - lib/active_genie/scoring/recommended_reviews.rb
+- lib/active_genie/utils/math.rb
 - lib/tasks/install.rake
-- lib/tasks/templates/active_ai.yml
+- lib/tasks/templates/active_genie.yml
 homepage: https://github.com/Roriz/active_genie
 licenses:
 - Apache-2.0
@@ -67,6 +168,5 @@ requirements: []
 rubygems_version: 3.5.3
 signing_key: 
 specification_version: 4
-summary: Modules and classes to help you build AI features, like data extraction,
-  summarization, scoring, and ranking.
+summary: Transform your Ruby application with powerful, production-ready GenAI features
 test_files: []