active_genie 0.0.2 → 0.0.8

data/lib/active_genie/data_extractor/basic.rb

@@ -0,0 +1,88 @@
+require_relative '../clients/router.rb'
+
+module ActiveGenie::DataExtractor
+  class Basic
+    def self.call(text, data_to_extract, options: {})
+      new(text, data_to_extract, options:).call
+    end
+
+    # Extracts structured data from text based on a predefined schema.
+    #
+    # @param text [String] The input text to analyze and extract data from
+    # @param data_to_extract [Hash] Schema defining the data structure to extract.
+    #   Each key in the hash represents a field to extract, and its value defines the expected type and constraints.
+    # @param options [Hash] Additional options for the extraction process
+    #   @option options [String] :model The model to use for the extraction
+    #   @option options [String] :api_key The API key to use for the extraction
+    #
+    # @return [Hash] The extracted data matching the schema structure. Each field will include
+    #   both the extracted value and an explanation of how it was derived.
+    #
+    # @example Extract a person's details
+    #   schema = {
+    #     name: { type: 'string', description: 'Full name of the person' },
+    #     age: { type: 'integer', description: 'Age in years' }
+    #   }
+    #   text = "John Doe is 25 years old"
+    #   DataExtractor.call(text, schema)
+    #   # => { name: "John Doe", name_explanation: "Found directly in text",
+    #   #      age: 25, age_explanation: "Explicitly stated as 25 years old" }
+    def initialize(text, data_to_extract, options: {})
+      @text = text
+      @data_to_extract = data_to_extract
+      @options = options
+    end
+
+    def call
+      messages = [
+        {  role: 'system', content: PROMPT },
+        {  role: 'user', content: @text }
+      ]
+      function = {
+        name: 'data_extractor',
+        description: 'Extract structured and typed data from user messages.',
+        schema: {
+          type: "object",
+          properties: data_to_extract_with_explaination
+        }
+      }
+
+      ::ActiveGenie::Clients::Router.function_calling(messages, function, options: @options)
+    end
+
+    private
+
+    PROMPT = <<~PROMPT
+    Extract structured and typed data from user messages.
+    Identify relevant information within user messages and categorize it into predefined data fields with specific data types.
+
+    # Steps
+    1. **Identify Data Types**: Determine the types of data to collect, such as names, dates, email addresses, phone numbers, etc.
+    2. **Extract Information**: Use pattern recognition and language understanding to identify and extract the relevant pieces of data from the user message.
+    3. **Categorize Data**: Assign the extracted data to the appropriate predefined fields.
+    4. **Structure Data**: Format the extracted and categorized data in a structured format, such as JSON.
+
+    # Output Format
+    The output should be a JSON object containing fields with their corresponding extracted values. If a value is not found, the field should still be included with a null value.
+
+    # Notes
+    - Handle missing or partial information gracefully.
+    - Manage multiple occurrences of similar data points by prioritizing the first one unless specified otherwise.
+    - Be flexible to handle variations in data format and language clues.
+    PROMPT
+
+    def data_to_extract_with_explaination
+      with_explaination = {}
+  
+      @data_to_extract.each do |key, value|
+        with_explaination[key] = value
+        with_explaination["#{key}_explanation"] = {
+          type: 'string',
+          description: "The chain of thought that led to the conclusion about: #{key}. Can be blank if the user didn't provide any context",
+        }
+      end
+      
+      with_explaination
+    end
+  end
+end

data/lib/active_genie/data_extractor/from_informal.rb

@@ -0,0 +1,58 @@
+module ActiveGenie::DataExtractor
+  class FromInformal
+    def self.call(text, data_to_extract, options: {})
+      new(text, data_to_extract, options:).call()
+    end
+
+    # Extracts data from informal text while also detecting litotes and their meanings.
+    # This method extends the basic extraction by analyzing rhetorical devices.
+    #
+    # @param text [String] The informal text to analyze
+    # @param data_to_extract [Hash] Schema defining the data structure to extract
+    # @param options [Hash] Additional options for the extraction process
+    #
+    # @return [Hash] The extracted data including litote analysis. In addition to the
+    #   schema-defined fields, includes:
+    #   - message_litote: Whether the text contains a litote
+    #   - litote_rephrased: The positive rephrasing of any detected litote
+    #
+    # @example Analyze text with litote
+    #   text = "The weather isn't bad today"
+    #   schema = { mood: { type: 'string', description: 'The mood of the message' } }
+    #   DataExtractor.from_informal(text, schema)
+    #   # => { mood: "positive", mood_explanation: "Speaker views weather favorably",
+    #   #      message_litote: true,
+    #   #      litote_rephrased: "The weather is good today" }
+    def initialize(text, data_to_extract, options: {})
+      @text = text
+      @data_to_extract = data_to_extract
+      @options = options
+    end
+
+    def call
+      response = Basic.call(@text, data_to_extract_with_litote, options: @options)
+
+      if response['message_litote']
+        response = Basic.call(response['litote_rephrased'], @data_to_extract, options: @options)
+      end
+
+      response
+    end
+
+    private
+
+    def data_to_extract_with_litote
+      {
+        **@data_to_extract,
+        message_litote: {
+          type: 'boolean',
+          description: 'Return true if the message is a litote. A litote is a figure of speech that uses understatement to emphasize a point by stating a negative to further affirm a positive, often incorporating double negatives for effect.'
+        },
+        litote_rephrased: {
+          type: 'string',
+          description: 'The true meaning of the litote. Rephrase the message to a positive and active statement.'
+        }
+      }
+    end
+  end
+end

data/lib/active_genie/data_extractor.rb

@@ -0,0 +1,17 @@
+require_relative 'data_extractor/basic'
+require_relative 'data_extractor/from_informal'
+
+module ActiveGenie
+  # Extract structured data from text using AI-powered analysis, handling informal language and complex expressions.
+  module DataExtractor
+    module_function
+
+    def basic(...)
+      Basic.call(...)
+    end
+
+    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/README.md

@@ -0,0 +1,80 @@
+# Scoring
+Text evaluation system that provides detailed scoring and feedback using multiple expert reviewers.
+
+## Features
+- Multi-reviewer evaluation - Get scores and feedback from multiple AI-powered expert reviewers
+- Automatic reviewer selection - Smart recommendation of reviewers based on content and criteria
+- Detailed feedback - Comprehensive reasoning for each reviewer's score
+- Customizable weights - Adjust the importance of different reviewers' scores
+- Flexible criteria - Score text against any specified evaluation criteria
+
+## Basic Usage
+
+Score text using predefined reviewers:
+
+```ruby
+text = "The code implements a binary search algorithm with O(log n) complexity"
+criteria = "Evaluate technical accuracy and clarity"
+reviewers = ["Algorithm Expert", "Technical Writer"]
+
+result = ActiveGenie::Scoring::Basic.call(text, criteria, reviewers)
+# => {
+#      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
+#    }
+```
+
+## Automatic Reviewer Selection
+
+When no reviewers are specified, the system automatically recommends appropriate reviewers:
+
+```ruby
+text = "The patient shows signs of improved cardiac function"
+criteria = "Evaluate medical accuracy and clarity"
+
+result = ActiveGenie::Scoring::Basic.call(text, criteria)
+# => {
+#      cardiologist_score: 88,
+#      cardiologist_reasoning: "Accurate assessment of cardiac improvement",
+#      medical_writer_score: 85,
+#      medical_writer_reasoning: "Clear communication of medical findings",
+#      general_practitioner_score: 90,
+#      general_practitioner_reasoning: "Well-structured medical observation",
+#      final_score: 87.7
+#    }
+```
+
+## Interface
+
+### `Basic.call(text, criteria, reviewers = [], options: {})`
+Main interface for scoring text content.
+
+#### Parameters
+- `text` [String] - The text content to be evaluated
+- `criteria` [String] - The evaluation criteria or rubric to assess against
+- `reviewers` [Array<String>] - Optional list of specific reviewers
+- `options` [Hash] - Additional configuration options
+  - `:detailed_feedback` [Boolean] - Request more detailed feedback (WIP)
+  - `:reviewer_weights` [Hash] - Custom weights for different reviewers (WIP)
+
+### `RecommendedReviews.call(text, criteria, options: {})`
+Recommends appropriate reviewers based on content and criteria.
+
+#### Parameters
+- `text` [String] - The text content to analyze
+- `criteria` [String] - The evaluation criteria
+- `options` [Hash] - Additional configuration options
+  - `:prefer_technical` [Boolean] - Favor technical expertise (WIP)
+  - `:prefer_domain` [Boolean] - Favor domain expertise (WIP)
+
+### Usage Notes
+- Best suited for objective evaluation of text content
+- Provides balanced scoring through multiple reviewers
+- Automatically handles reviewer selection when needed
+- Supports custom weighting of reviewer scores
+- Returns detailed reasoning for each score
+
+Performance Impact: Using multiple reviewers or requesting detailed feedback may increase processing time.