active_genie 0.0.24 → 0.0.25

data/lib/active_genie/scoring/generalist.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require_relative '../clients/unified_client'
+
+module ActiveGenie
+  module Scoring
+    # The Generalist class provides a foundation for scoring text content against specified criteria
+    # using AI-powered evaluation. It supports both single and multiple reviewer scenarios,
+    # with the ability to automatically recommend reviewers when none are specified.
+    #
+    # The scoring process evaluates text based on given criteria and returns detailed feedback
+    # including individual reviewer scores, reasoning, and a final aggregated score.
+    #
+    # @example Generalist usage with a single reviewer
+    #   Generalist.call("Sample text", "Evaluate grammar and clarity", ["Grammar Expert"])
+    #
+    # @example Usage with automatic reviewer recommendation
+    #   Generalist.call("Sample text", "Evaluate technical accuracy")
+    #
+    class Generalist
+      # @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,
+      #   reviewers will be automatically recommended based on the content and criteria
+      # @param config [Hash] Additional configuration config that modify the scoring 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 reviewers
+      #   @return [String] :final_reasoning Detailed explanation of why the final score was reached
+      def self.call(...)
+        new(...).call
+      end
+
+      def initialize(text, criteria, reviewers = [], config: {})
+        @text = text
+        @criteria = criteria
+        @param_reviewers = Array(reviewers).compact.uniq
+        @config = ActiveGenie.configuration.merge(config)
+      end
+
+      def call
+        messages = [
+          {  role: 'system', content: PROMPT },
+          {  role: 'user', content: "Scoring criteria: #{@criteria}" },
+          {  role: 'user', content: "Text to score: #{@text}" }
+        ]
+
+        properties = build_properties
+
+        function = {
+          name: 'scoring',
+          description: 'Score the text based on the given criteria.',
+          parameters: {
+            type: 'object',
+            properties:,
+            required: properties.keys
+          }
+        }
+
+        result = ::ActiveGenie::Clients::UnifiedClient.function_calling(
+          messages,
+          function,
+          config: @config
+        )
+
+        result['final_score'] = 0 if result['final_score'].nil?
+
+        ActiveGenie::Logger.call({
+                                   code: :scoring,
+                                   text: @text[0..30],
+                                   criteria: @criteria[0..30],
+                                   reviewers: reviewers,
+                                   score: result['final_score'],
+                                   reasoning: result['final_reasoning']
+                                 })
+
+        result
+      end
+
+      private
+
+      def build_properties
+        properties = {}
+        reviewers.each do |reviewer|
+          properties["#{reviewer}_reasoning"] = {
+            type: 'string',
+            description: "The reasoning of the scoring process by #{reviewer}."
+          }
+          properties["#{reviewer}_score"] = {
+            type: 'number',
+            description: "The score given by #{reviewer}.",
+            min: 0,
+            max: 100
+          }
+        end
+
+        properties[:final_score] = {
+          type: 'number',
+          description: 'The final score based on the previous reviewers'
+        }
+        properties[:final_reasoning] = {
+          type: 'string',
+          description: 'The final reasoning based on the previous reviewers'
+        }
+
+        properties
+      end
+
+      def reviewers
+        @reviewers ||= if @param_reviewers.count.positive?
+                         @param_reviewers
+                       else
+                         result = RecommendedReviewers.call(@text, @criteria, config: @config)
+
+                         [result['reviewer1'], result['reviewer2'], result['reviewer3']]
+                       end
+      end
+
+      PROMPT = <<~PROMPT
+        Evaluate and score the provided text based on predefined criteria, using a scoring range of 0 to 100 with 100 representing the highest possible score.
+
+        Follow the instructions below to ensure a comprehensive and objective assessment.
+
+        # Evaluation Process
+
+        1. **Analysis**:
+          - Thoroughly compare the text against each criterion for a comprehensive evaluation.
+
+        2. **Document Deviations**:
+          - Identify and document areas where the content does not align with the specified criteria.
+
+        3. **Highlight Strengths**:
+          - Note notable features or elements that enhance the quality or effectiveness of the content.
+
+        4. **Identify Weaknesses**:
+          - Specify areas where the content fails to meet the criteria or where improvements could be made.
+
+        # Scoring Fairness
+
+        - Ensure the assigned score reflects both the alignment with the criteria and the content's effectiveness.
+        - Consider if the fulfillment of other criteria compensates for areas lacking extreme details.
+
+        # Scoring Range
+
+        Segment scores into five parts before assigning a final score:
+        - **Terrible**: 0-20 - Content does not meet the criteria.
+        - **Bad**: 21-40 - Content is substandard but meets some criteria.
+        - **Average**: 41-60 - Content meets criteria with room for improvement.
+        - **Good**: 61-80 - Content exceeds criteria and is above average.
+        - **Great**: 81-100 - Content exceeds all expectations.
+
+        # Guidelines
+
+        - Maintain objectivity and avoid biases.
+        - Deconstruct each criterion into actionable components for systematic evaluation.
+        - Apply reasonable judgment in assigning a score, justifying your rationale clearly.
+
+        # Output Format
+
+        - Provide a detailed review including:
+          - A final score (0-100)
+          - Specific reasoning for the assigned score, detailing all evaluated criteria
+          - Include both positive aspects and suggested improvements
+
+        # Notes
+
+        - Consider edge cases where the text may partially align with criteria.
+        - If lacking information, reasonably judge and explain your scoring approach.
+      PROMPT
+    end
+  end
+end

data/lib/active_genie/scoring/recommended_reviewers.rb

@@ -2,87 +2,86 @@
 
 require_relative '../clients/unified_client'
 
-module ActiveGenie::Scoring
-  # The RecommendedReviewers class intelligently suggests appropriate reviewer roles
-  # for evaluating text content based on specific criteria. It uses AI to analyze
-  # the content and criteria to identify the most suitable subject matter experts.
-  #
-  # The class ensures a balanced and comprehensive review process by recommending
-  # three distinct reviewer roles with complementary expertise and perspectives.
-  #
-  # @example Getting recommended reviewers for technical content
-  #   RecommendedReviewers.call("Technical documentation about API design", 
-  #                           "Evaluate technical accuracy and clarity")
-  #   # => { reviewer1: "API Architect", reviewer2: "Technical Writer", 
-  #   #      reviewer3: "Developer Advocate", reasoning: "..." }
-  #
-  class RecommendedReviewers
-    def self.call(...)
-      new(...).call
-    end
-
-    # Initializes a new reviewer recommendation instance
+module ActiveGenie
+  module Scoring
+    # The RecommendedReviewers class intelligently suggests appropriate reviewer roles
+    # for evaluating text content based on specific criteria. It uses AI to analyze
+    # the content and criteria to identify the most suitable subject matter experts.
     #
-    # @param text [String] The text content to analyze for reviewer recommendations
-    # @param criteria [String] The evaluation criteria that will guide reviewer selection
-    # @param config [Hash] Additional configuration config that modify the recommendation process
-    def initialize(text, criteria, config: {})
-      @text = text
-      @criteria = criteria
-      @config = ActiveGenie::Configuration.to_h(config)
-    end
+    # The class ensures a balanced and comprehensive review process by recommending
+    # three distinct reviewer roles with complementary expertise and perspectives.
+    #
+    # @example Getting recommended reviewers for technical content
+    #   RecommendedReviewers.call("Technical documentation about API design",
+    #                           "Evaluate technical accuracy and clarity")
+    #   # => { reviewer1: "API Architect", reviewer2: "Technical Writer",
+    #   #      reviewer3: "Developer Advocate", reasoning: "..." }
+    #
+    class RecommendedReviewers
+      def self.call(...)
+        new(...).call
+      end
 
-    def call
-      messages = [
-        {  role: 'system', content: PROMPT },
-        {  role: 'user', content: "Scoring criteria: #{@criteria}" },
-        {  role: 'user', content: "Text to score: #{@text}" },
-      ]
+      # Initializes a new reviewer recommendation instance
+      #
+      # @param text [String] The text content to analyze for reviewer recommendations
+      # @param criteria [String] The evaluation criteria that will guide reviewer selection
+      # @param config [Hash] Additional configuration config that modify the recommendation process
+      def initialize(text, criteria, config: {})
+        @text = text
+        @criteria = criteria
+        @config = ActiveGenie.configuration.merge(config)
+      end
 
-      function = {
-        name: 'identify_reviewers',
-        description: 'Discover reviewers based on the text and given criteria.',
-        parameters: {
-          type: "object",
-          properties: {
-            reasoning: { type: 'string' },
-            reviewer1: { type: 'string' },
-            reviewer2: { type: 'string' },
-            reviewer3: { type: 'string' },
-          },
-          required: ['reasoning', 'reviewer1', 'reviewer2', 'reviewer3']
-        }
-      }
+      def call
+        messages = [
+          {  role: 'system', content: PROMPT },
+          {  role: 'user', content: "Scoring criteria: #{@criteria}" },
+          {  role: 'user', content: "Text to score: #{@text}" }
+        ]
 
-      result = client.function_calling(
-        messages,
-        function,
-        model_tier: 'lower_tier',
-        config: @config
-      )
+        function = {
+          name: 'identify_reviewers',
+          description: 'Discover reviewers based on the text and given criteria.',
+          parameters: {
+            type: 'object',
+            properties: {
+              reasoning: { type: 'string' },
+              reviewer1: { type: 'string' },
+              reviewer2: { type: 'string' },
+              reviewer3: { type: 'string' }
+            },
+            required: %w[reasoning reviewer1 reviewer2 reviewer3]
+          }
+        }
 
-      result
-    end
+        client.function_calling(
+          messages,
+          function,
+          config: @config
+        )
+      end
 
-    private
+      private
 
-    PROMPT = <<~PROMPT
-    Identify the top 3 suitable reviewer titles or roles based on the provided text and criteria. Selected reviewers must possess subject matter expertise, offer valuable insights, and ensure diverse yet aligned perspectives on the content.
+      PROMPT = <<~PROMPT
+        Identify the top 3 suitable reviewer titles or roles based on the provided text and criteria. Selected reviewers must possess subject matter expertise, offer valuable insights, and ensure diverse yet aligned perspectives on the content.
 
-    # Instructions
-    1. **Analyze the Text and Criteria**: Examine the content and criteria to identify relevant reviewer titles or roles.
-    2. **Determine Subject Matter Expertise**: Select reviewers with substantial knowledge or experience in the subject area.
-    3. **Evaluate Insight Contribution**: Prioritize titles or roles capable of providing meaningful and actionable feedback on the content.
-    4. **Incorporate Perspective Diversity**: Ensure the selection includes reviewers with varied but complementary viewpoints while maintaining alignment with the criteria.
+        # Instructions
+        1. **Analyze the Text and Criteria**: Examine the content and criteria to identify relevant reviewer titles or roles.
+        2. **Determine Subject Matter Expertise**: Select reviewers with substantial knowledge or experience in the subject area.
+        3. **Evaluate Insight Contribution**: Prioritize titles or roles capable of providing meaningful and actionable feedback on the content.
+        4. **Incorporate Perspective Diversity**: Ensure the selection includes reviewers with varied but complementary viewpoints while maintaining alignment with the criteria.
 
-    # Constraints
-    - Selected reviewers must align with the content’s subject matter and criteria.
-    - Include reasoning for how each choice supports a thorough and insightful review.
-    - Avoid redundant or overly similar titles/roles to maintain diversity.
-    PROMPT
+        # Constraints
+        - Selected reviewers must align with the content’s subject matter and criteria.
+        - Include reasoning for how each choice supports a thorough and insightful review.
+        - Avoid redundant or overly similar titles/roles to maintain diversity.
+      PROMPT
 
-    def client
-      ::ActiveGenie::Clients::UnifiedClient
+      def client
+        ::ActiveGenie::Clients::UnifiedClient
+      end
     end
   end
 end

data/lib/active_genie/scoring.rb

@@ -1,4 +1,6 @@
-require_relative 'scoring/basic'
+# frozen_string_literal: true
+
+require_relative 'scoring/generalist'
 require_relative 'scoring/recommended_reviewers'
 
 module ActiveGenie
@@ -6,11 +8,12 @@ module ActiveGenie
   module Scoring
     module_function
 
-    def basic(...)
-      Basic.call(...)
-    end
     def call(...)
-      Basic.call(...)
+      Generalist.call(...)
+    end
+
+    def generalist(...)
+      Generalist.call(...)
     end
 
     def recommended_reviewers(...)

data/lib/active_genie.rb

@@ -1,19 +1,28 @@
+# frozen_string_literal: true
+
 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'
+
 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')
 
+  VERSION = File.read(File.expand_path('../VERSION', __dir__)).strip
+
   class << self
     def configure
       yield(configuration) if block_given?
     end
 
     def configuration
-      @configuration ||= Configuration
+      @configuration ||= initialize_configuration
     end
 
     def load_tasks
@@ -22,5 +31,18 @@ module ActiveGenie
       Rake::Task.define_task(:environment)
       Dir.glob(File.join(__dir__, 'tasks', '*.rake')).each { |r| load r }
     end
+
+    private
+
+    def initialize_configuration
+      config = Configuration.new
+
+      config.providers.add(Config::Providers::OpenaiConfig)
+      config.providers.add(Config::Providers::GoogleConfig)
+      config.providers.add(Config::Providers::AnthropicConfig)
+      config.providers.add(Config::Providers::DeepseekConfig)
+
+      config
+    end
   end
 end

data/lib/tasks/benchmark.rake

@@ -1,27 +1,28 @@
+# frozen_string_literal: true
 
 namespace :active_genie do
-  desc "Run benchmarks, optionally for a specific module (e.g., rake active_genie:benchmark[data_extractor])"
+  desc 'Run benchmarks, optionally for a specific module (e.g., rake active_genie:benchmark[data_extractor])'
   task :benchmark, [:module_name] do |_, args|
     Rake::TestTask.new(:run_benchmarks) do |t|
-      t.libs << "benchmark"
-      
+      t.libs << 'benchmark'
+
       if args[:module_name]
         module_name = args[:module_name]
         module_path = "benchmark/test_cases/#{module_name}/"
         t.test_files = FileList["#{module_path}**/*_test.rb"]
         puts "Running benchmarks for module: #{module_name}"
       else
-        t.test_files = FileList["benchmark/test_cases/**/*_test.rb"]
-        puts "Running all benchmarks"
+        t.test_files = FileList['benchmark/test_cases/**/*_test.rb']
+        puts 'Running all benchmarks'
       end
-      
+
       t.warning = false
     end
-    
+
     begin
       Rake::Task[:run_benchmarks].invoke
-    rescue => e
+    rescue StandardError => e
       puts e
     end
   end
-end
+end

data/lib/tasks/install.rake

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fileutils'
 
 namespace :active_genie do
@@ -7,6 +9,6 @@ namespace :active_genie do
     target = File.join('config', 'initializers', 'active_genie.rb')
 
     FileUtils.cp(source, target)
-    puts "Successfully installed active_genie!"
+    puts 'Successfully installed active_genie!'
   end
 end

data/lib/tasks/templates/active_genie.rb

@@ -1,17 +1,22 @@
+# frozen_string_literal: true
 
 ActiveGenie.configure do |config|
   # example with openai and the current default for each config
   # config.providers.openai.api_key = ENV['OPENAI_API_KEY']
   # config.providers.openai.organization = ENV['OPENAI_ORGANIZATION']
   # config.providers.openai.api_url = 'https://api.openai.com/v1'
-  # config.providers.openai.lower_tier_model = 'gpt-4o-mini'
-  # config.providers.openai.middle_tier_model = 'gpt-4o'
-  # config.providers.openai.upper_tier_model = 'o1-preview'
+  # config.providers.openai.lower_tier_model = 'gpt-4.1-mini'
+  # config.providers.openai.middle_tier_model = 'gpt-4.1'
+  # config.providers.openai.upper_tier_model = 'o3-mini'
   # config.providers.openai.client = ActiveGenie::Providers::Openai::Client.new(config)
 
   # example how add a new provider
-  # config.providers.register(InternalCompanyApi::Configuration)
+  # config.providers.add(InternalCompanyApi::Configuration)
 
   # Logs configuration
-  # config.log_level = :debug # default is :info
-end
+  # config.log.log_level = :debug # default is :info
+  # config.log.add_observer(GlobalLogObserver.new)
+  # config.log.add_observer(PersistUsageObserver.new, scope: { code: 'llm_usage' })
+  # config.log.remove_observer(PersistUsageObserver.new)
+  # config.log.clear_observers
+end

metadata

@@ -1,17 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: active_genie
 version: !ruby/object:Gem::Version
-  version: 0.0.24
+  version: 0.0.25
 platform: ruby
 authors:
 - Radamés Roriz
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2025-05-19 00:00:00.000000000 Z
 dependencies: []
 description: |
   The lodash for GenAI, stop reinventing the wheel
-  ActiveGenie is a Ruby gem that provides valuable solutions powered by Generative AI (GenAI) models. Just like Lodash or ActiveStorage, ActiveGenie brings a set of Modules to reach real value fast and reliably. ActiveGenie is backed by a custom benchmarking system that ensures consistent quality and performance across different models and providers in every release.
+
+  ActiveGenie is a Ruby gem that provides valuable solutions using GenAI. Just like Lodash or ActiveStorage, ActiveGenie brings a set of Modules to reach real value fast and reliably. Backed by a custom benchmarking system that ensures consistent quality and performance across different models and providers in every release.
 email:
 - radames@roriz.dev
 executables: []
@@ -24,28 +26,33 @@ files:
 - 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/anthropic_client.rb
-- lib/active_genie/clients/base_client.rb
-- lib/active_genie/clients/google_client.rb
-- lib/active_genie/clients/helpers/retry.rb
-- lib/active_genie/clients/openai_client.rb
+- 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/concerns/loggable.rb
+- lib/active_genie/config/battle_config.rb
+- lib/active_genie/config/data_extractor_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/configuration.rb
-- lib/active_genie/configuration/log_config.rb
-- lib/active_genie/configuration/providers/anthropic_config.rb
-- lib/active_genie/configuration/providers/base_config.rb
-- lib/active_genie/configuration/providers/deepseek_config.rb
-- lib/active_genie/configuration/providers/google_config.rb
-- lib/active_genie/configuration/providers/internal_company_api_config.rb
-- lib/active_genie/configuration/providers/openai_config.rb
-- lib/active_genie/configuration/providers_config.rb
-- lib/active_genie/configuration/runtime_config.rb
 - lib/active_genie/data_extractor.rb
 - 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/data_extractor/generalist.md
+- lib/active_genie/data_extractor/generalist.rb
+- lib/active_genie/errors/invalid_provider_error.rb
 - lib/active_genie/logger.rb
 - lib/active_genie/ranking.rb
 - lib/active_genie/ranking/README.md
@@ -57,7 +64,7 @@ files:
 - lib/active_genie/ranking/ranking_scoring.rb
 - lib/active_genie/scoring.rb
 - lib/active_genie/scoring/README.md
-- lib/active_genie/scoring/basic.rb
+- lib/active_genie/scoring/generalist.rb
 - lib/active_genie/scoring/recommended_reviewers.rb
 - lib/tasks/benchmark.rake
 - lib/tasks/install.rake
@@ -71,6 +78,7 @@ metadata:
   changelog_uri: https://github.com/Roriz/active_genie/blob/master/CHANGELOG.md
   bug_tracker_uri: https://github.com/Roriz/active_genie/issues
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -78,14 +86,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.4.20
+signing_key:
 specification_version: 4
 summary: Transform your Ruby application with powerful, production-ready GenAI features
 test_files: []