active_genie 0.30.3 → 0.30.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0305b370de6af340e3ae6d3afa10b67f7be5f68ba20916c2fb3b8c934c40fc3e
-  data.tar.gz: ab3ac5ed4b7bd14c53ceeff02240953b7427260e94630803dffd8669d5a5e051
+  metadata.gz: 02e46bc41ee34451323202588e8018cca0f7497529f9c7f6ce64c0e00e009f7e
+  data.tar.gz: 4a78b8402fee546b0fd6fef3352cd85d476399167edf051798ec71709c46bb7b
 SHA512:
-  metadata.gz: 84c7f399b16c21599e6302aeb8c4243cd833dc7ab554bbc610d400d982e7e9cb48cdc5b626cd74897dfa235a97f4a48115110275e8761bfe2be2a8964b040890
-  data.tar.gz: 705f57b32a5f59b2b8d88650e3b5eb7be657e577b571e74709a53c5b60aee5bf38740621d901fa72342a7d89e113982173d6ab1120ecc76c105b0589bd8910db
+  metadata.gz: 2e606f1827f1b88e67dea196d56173a5dd4c5ff51861a77942faebef38fdd6f252e3077c9ca2bc8585769ab4f873344dea0abebb88d19af1f40493aac9e7374d
+  data.tar.gz: 4beac5e264438b7c9eb692669ff16940e140251cc8e87b35e61fbef8eb3fdf604acc2966ed021705bca63a9ff90cd63312abe25143b68364a67d92becd113d58

data/README.md

@@ -1,12 +1,14 @@
 # ActiveGenie 🧞‍♂️
-> The Lodash for GenAI: Real Value + Consistent + Model-Agnostic
+> The Lodash for GenAI: Consistent + Model-Agnostic
 
 [![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/benchmark.yml/badge.svg)](https://github.com/roriz/active_genie/actions/workflows/benchmark.yml)
 
-ActiveGenie is a developer-first library for GenAI workflows, designed to help you extract, compare, score, and rank with consistency and model-agnostic. Think of it as the Lodash for GenAI: built for real value, consistent results, and freedom from vendor lock-in. It solves the biggest pain in GenAI today: getting predictable, trustworthy answers across use cases, models, and providers.
-
-Behind the scenes, a custom benchmarking system keeps everything consistent across LLM vendors and versions, release after release.
+**ActiveGenie** is an **enabler for creating reliable GenAI features**, offering powerful, **model-agnostic tools** across any provider. It allows you to settle subjective comparisons with a `ActibeGenie::Comparator` module that stages a political debate, get accurate scores from an **AI jury** using `ActiveGenie::Scorer`, and **rank large datasets** using `ActiveGenie::Ranker`'s tournament-style system.
+This reliability is built on three core pillars:
+* **Custom Benchmarking:** Testing for consistency with every new version and model update.
+* **Reasoning Prompting:** Utilizing human reasoning techniques (like debate and jury review) to control a model's reasoning.
+* **Overfitting Prompts:** Highly specialized, and potentially model-specific, prompt for each module's purpose.
 
 For full documentation, visit [activegenie.ai](https://activegenie.ai).
 
@@ -57,7 +59,7 @@ schema = {
   }
 }
 
-result = ActiveGenie::DataExtractor.call(
+result = ActiveGenie::Extractor.call(
   text,
   schema,
   config: { provider_name: :openai, model: 'gpt-4.1-mini' } # optional

data/VERSION

@@ -1 +1 @@
-0.30.3
+0.30.8

data/lib/active_genie/comparator/debate.rb

@@ -14,11 +14,7 @@ module ActiveGenie
     # @example Debate usage with two players and criteria
     #   Debate.call("Player A content", "Player B content", "Evaluate keyword usage and pattern matching")
     #
-    class Debate
-      def self.call(...)
-        new(...).call
-      end
-
+    class Debate < ActiveGenie::BaseModule
       # @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
@@ -31,7 +27,7 @@ module ActiveGenie
         @player_a = player_a
         @player_b = player_b
         @criteria = criteria
-        @initial_config = config
+        super(config:)
       end
 
       # @return [ComparatorResponse] The evaluation result containing the winner and reasoning
@@ -43,9 +39,9 @@ module ActiveGenie
           {  role: 'user', content: "criteria: #{@criteria}" }
         ]
 
-        response = ::ActiveGenie::Providers::UnifiedProvider.function_calling(messages, FUNCTION, config:)
+        provider_response = ::ActiveGenie::Providers::UnifiedProvider.function_calling(messages, FUNCTION, config:)
 
-        response_formatted(response)
+        response_formatted(provider_response)
       end
 
       PROMPT = File.read(File.join(__dir__, 'debate.prompt.md'))
@@ -53,37 +49,18 @@ module ActiveGenie
 
       private
 
-      def response_formatted(response)
-        winner, loser = case response['impartial_judge_winner']
-                        when 'player_a' then [@player_a, @player_b]
-                        when 'player_b' then [@player_b, @player_a]
-                        end
-        reasoning = response['impartial_judge_winner_reasoning']
-
-        comparator_response = ActiveGenie::Comparator::ComparatorResponse.new(winner:, loser:, reasoning:,
-                                                                              raw: response)
-        log_comparator(comparator_response)
+      def response_formatted(provider_response)
+        winner, = case provider_response['impartial_judge_winner']
+                  when 'player_a' then [@player_a, @player_b]
+                  when 'player_b' then [@player_b, @player_a]
+                  end
+        reasoning = provider_response['impartial_judge_winner_reasoning']
 
-        comparator_response
+        ActiveGenie::Result.new(data: winner, reasoning:, metadata: provider_response)
       end
 
-      def log_comparator(comparator_response)
-        config.logger.call(
-          code: :comparator,
-          player_a: @player_a[0..30],
-          player_b: @player_b[0..30],
-          criteria: @criteria[0..30],
-          **comparator_response.to_h
-        )
-      end
-
-      def config
-        @config ||= begin
-          c = ActiveGenie.configuration.merge(@initial_config)
-          c.llm.recommended_model = 'deepseek-chat' unless c.llm.recommended_model
-
-          c
-        end
+      def module_config
+        { llm: { recommended_model: 'claude-haiku-4-5' } }
       end
     end
   end

data/lib/active_genie/comparator/fight.rb

@@ -21,13 +21,13 @@ module ActiveGenie
           {  role: 'user', content: "criteria: #{@criteria}" }
         ]
 
-        response = ::ActiveGenie::Providers::UnifiedProvider.function_calling(
+        provider_response = ::ActiveGenie::Providers::UnifiedProvider.function_calling(
           messages,
           FUNCTION,
-          config: @config
+          config:
         )
 
-        response_formatted(response)
+        response_formatted(provider_response)
       end
 
       PROMPT = File.read(File.join(__dir__, 'fight.prompt.md'))

data/lib/active_genie/comparator.rb

@@ -7,8 +7,6 @@ module ActiveGenie
   module Comparator
     module_function
 
-    ComparatorResponse = Struct.new(:winner, :loser, :reasoning, :raw, keyword_init: true)
-
     def call(...)
       Debate.call(...)
     end

data/lib/active_genie/configs/base_config.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ActiveGenie
+  module Config
+    class BaseConfig
+      def initialize(**args)
+        attributes.each do |var|
+          send("#{var}=", args[var] || args[var.to_s])
+        end
+      end
+
+      def attributes
+        public_methods(false).grep(/=$/).map { |m| m.to_s.delete('=').to_sym }
+      end
+
+      def to_h
+        h = {}
+        attributes.each do |var|
+          h[var.to_sym] = send(var)
+        end
+        h
+      end
+    end
+  end
+end

data/lib/active_genie/configs/extractor_config.rb

@@ -1,22 +1,14 @@
 # frozen_string_literal: true
 
+require_relative 'base_config'
+
 module ActiveGenie
   module Config
-    class ExtractorConfig
-      attr_accessor :with_explanation, :min_accuracy, :verbose
-
-      def initialize
-        @with_explanation = true
-        @min_accuracy = 70
-        @verbose = false
-      end
+    class ExtractorConfig < BaseConfig
+      attr_writer :min_accuracy
 
-      def merge(config_params = {})
-        dup.tap do |config|
-          config.with_explanation = config_params[:with_explanation] if config_params.key?(:with_explanation)
-          config.min_accuracy = config_params[:min_accuracy] if config_params.key?(:min_accuracy)
-          config.verbose = config_params[:verbose] if config_params.key?(:verbose)
-        end
+      def min_accuracy
+        @min_accuracy ||= 70
       end
     end
   end

data/lib/active_genie/configs/lister_config.rb

@@ -1,18 +1,14 @@
 # frozen_string_literal: true
 
+require_relative 'base_config'
+
 module ActiveGenie
   module Config
-    class ListerConfig
-      attr_accessor :number_of_items
-
-      def initialize
-        @number_of_items = 5
-      end
+    class ListerConfig < BaseConfig
+      attr_writer :number_of_items
 
-      def merge(config_params = {})
-        dup.tap do |config|
-          config.number_of_items = config_params[:number_of_items] if config_params.key?(:number_of_items)
-        end
+      def number_of_items
+        @number_of_items ||= 5
       end
     end
   end

data/lib/active_genie/configs/llm_config.rb

@@ -1,39 +1,25 @@
 # frozen_string_literal: true
 
+require_relative 'base_config'
+
 module ActiveGenie
   module Config
-    class LlmConfig
-      attr_accessor :model, :recommended_model, :temperature, :max_tokens, :max_retries, :retry_delay,
-                    :model_tier, :read_timeout, :open_timeout, :provider, :max_fibers
+    class LlmConfig < BaseConfig
+      attr_accessor :model, :recommended_model, :max_retries, :retry_delay,
+                    :read_timeout, :open_timeout
+      attr_writer :temperature, :max_fibers, :max_tokens
       attr_reader :provider_name
 
-      def initialize
-        set_defaults
+      def temperature
+        @temperature ||= 0
       end
 
-      def provider_name=(provider_name)
-        return if provider_name.nil? || provider_name.empty?
-
-        @provider_name = provider_name.to_s.downcase.strip.to_sym
+      def max_fibers
+        @max_fibers ||= 10
       end
 
-      def merge(config_params = {})
-        dup.tap do |config|
-          config_params.each do |key, value|
-            config.send("#{key}=", value) if config.respond_to?("#{key}=")
-          end
-        end
-      end
-
-      private
-
-      def set_defaults
-        @model = @recommended_model = @provider_name = @provider = nil
-        @max_retries = @retry_delay = @read_timeout = @open_timeout = nil
-        @temperature = 0
-        @max_tokens = 4096
-        @model_tier = 'lower_tier'
-        @max_fibers = 10
+      def max_tokens
+        @max_tokens ||= 4096
       end
     end
   end

data/lib/active_genie/configs/log_config.rb

@@ -1,28 +1,41 @@
 # frozen_string_literal: true
 
+require_relative 'base_config'
+
 module ActiveGenie
   module Config
-    class LogConfig
+    class LogConfig < BaseConfig
+      attr_reader :output
       attr_writer :file_path, :fine_tune_file_path
-      attr_reader :output, :observers
 
       def file_path
-        @file_path || 'log/active_genie.log'
+        @file_path ||= 'log/active_genie.log'
       end
 
       def fine_tune_file_path
-        @fine_tune_file_path || 'log/active_genie_fine_tune.log'
+        @fine_tune_file_path ||= 'log/active_genie_fine_tune.log'
+      end
+
+      def observers=(observers)
+        Array(observers).each do |observer|
+          add_observer(observers: [observer[:observer]], scope: observer[:scope] || {})
+        end
+      end
+
+      def observers
+        @observers ||= []
       end
 
       def additional_context
-        @additional_context || {}
+        @additional_context ||= {}
       end
 
       def additional_context=(context)
-        @additional_context = additional_context.merge(context).compact
+        @additional_context = additional_context.merge(context || {}).compact
       end
 
       def output=(output)
+        return if output.nil?
         raise InvalidLogOutputError, output unless output.respond_to?(:call)
 
         @output = output
@@ -50,16 +63,6 @@ module ActiveGenie
       def clear_observers
         @observers = []
       end
-
-      def merge(config_params = {})
-        dup.tap do |config|
-          config_params.compact.each do |key, value|
-            config.send("#{key}=", value) if config.respond_to?("#{key}=")
-          end
-
-          config.add_observer(config_params[:observers]) if config_params[:observers]
-        end
-      end
     end
   end
 end

data/lib/active_genie/configs/providers/anthropic_config.rb

@@ -8,7 +8,10 @@ module ActiveGenie
       # Configuration class for the Anthropic API client.
       # Manages API keys, URLs, model selections, and client instantiation.
       class AnthropicConfig < ProviderBase
-        NAME = :anthropic
+        def initialize(anthropic_version: nil, **args)
+          @anthropic_version = anthropic_version
+          super(**args)
+        end
 
         # Retrieves the API key.
         # Falls back to the ANTHROPIC_API_KEY environment variable if not set.
@@ -30,6 +33,18 @@ module ActiveGenie
         def anthropic_version
           @anthropic_version || '2023-06-01'
         end
+
+        def default_model
+          @default_model || 'claude-3-5-haiku-20241022'
+        end
+
+        def valid_model?(model)
+          model.include?('claude')
+        end
+
+        def to_h
+          super.merge({ anthropic_version: })
+        end
       end
     end
   end

data/lib/active_genie/configs/providers/deepseek_config.rb

@@ -8,8 +8,6 @@ module ActiveGenie
       # Configuration class for the DeepSeek API client.
       # Manages API keys, organization IDs, URLs, model selections, and client instantiation.
       class DeepseekConfig < ProviderBase
-        NAME = :deepseek
-
         # Retrieves the API key.
         # Falls back to the DEEPSEEK_API_KEY environment variable if not set.
         # @return [String, nil] The API key.
@@ -23,6 +21,14 @@ module ActiveGenie
         def api_url
           @api_url || 'https://api.deepseek.com/v1'
         end
+
+        def default_model
+          @default_model || 'deepseek-chat'
+        end
+
+        def valid_model?(model)
+          model.include?('deepseek')
+        end
       end
     end
   end

data/lib/active_genie/configs/providers/google_config.rb

@@ -8,8 +8,6 @@ module ActiveGenie
       # Configuration class for the Google Generative Language API client.
       # Manages API keys, URLs, model selections, and client instantiation.
       class GoogleConfig < ProviderBase
-        NAME = :google
-
         # Retrieves the API key.
         # Falls back to the GENERATIVE_LANGUAGE_GOOGLE_API_KEY environment variable if not set.
         # @return [String, nil] The API key.
@@ -25,6 +23,14 @@ module ActiveGenie
           # The base URL here should be just the domain part.
           @api_url || 'https://generativelanguage.googleapis.com'
         end
+
+        def default_model
+          @default_model || 'gemini-2.5-flash'
+        end
+
+        def valid_model?(model)
+          model.include?('gemini')
+        end
       end
     end
   end

data/lib/active_genie/configs/providers/openai_config.rb

@@ -8,8 +8,6 @@ module ActiveGenie
       # Configuration class for the OpenAI API client.
       # Manages API keys, organization IDs, URLs, model selections, and client instantiation.
       class OpenaiConfig < ProviderBase
-        NAME = :openai
-
         # Retrieves the API key.
         # Falls back to the OPENAI_API_KEY environment variable if not set.
         # @return [String, nil] The API key.
@@ -23,6 +21,14 @@ module ActiveGenie
         def api_url
           @api_url || 'https://api.openai.com/v1'
         end
+
+        def default_model
+          @default_model || 'gpt-5-mini'
+        end
+
+        def valid_model?(model)
+          model.include?('gpt')
+        end
       end
     end
   end

data/lib/active_genie/configs/providers/provider_base.rb

@@ -4,47 +4,38 @@ module ActiveGenie
   module Config
     module Providers
       class ProviderBase
-        NAME = :unknown
-
-        attr_writer :api_key, :organization, :api_url, :client
-
-        # Returns a hash representation of the configuration.
-        # @param config [Hash] Additional key-value pairs to merge into the hash.
-        # @return [Hash] The configuration settings as a hash.
-        def to_h(config = {})
-          {
-            name: NAME,
-            api_key:,
-            api_url:,
-            **config
-          }
+        def initialize(api_key: nil, organization: nil, api_url: nil, default_model: nil)
+          @api_key = api_key
+          @organization = organization
+          @api_url = api_url
+          @default_model = default_model
         end
 
+        attr_writer :api_key, :organization, :api_url, :default_model
+
         # Validates the configuration.
         # @return [Boolean] True if the configuration is valid, false otherwise.
         def valid?
           api_key && api_url
         end
 
-        # Retrieves the API key.
-        # Falls back to the OPENAI_API_KEY environment variable if not set.
-        # @return [String, nil] The API key.
-        def api_key
-          raise NotImplementedError, 'Subclasses must implement this method'
+        # Checks if the given model is valid for this provider. Example provider.valid_model?('gpt-4') => true
+        # @param model [String, nil] The model name to validate.
+        # @return [Boolean] True if the model is valid, false otherwise.
+        def valid_model?(_model)
+          false
         end
 
-        # Retrieves the base API URL for OpenAI API.
-        # Defaults to 'https://api.openai.com/v1'.
-        # @return [String] The API base URL.
-        def api_url
-          raise NotImplementedError, 'Subclasses must implement this method'
-        end
-
-        # Lazily initializes and returns an instance of the OpenaiClient.
-        # Passes itself (the config object) to the client's constructor.
-        # @return [ActiveGenie::Clients::OpenaiClient] The client instance.
-        def client
-          raise NotImplementedError, 'Subclasses must implement this method'
+        # Returns a hash representation of the configuration.
+        # @param config [Hash] Additional key-value pairs to merge into the hash.
+        # @return [Hash] The configuration settings as a hash.
+        def to_h
+          {
+            api_key: @api_key,
+            api_url: @api_url,
+            organization: @organization,
+            default_model: @default_model
+          }
         end
       end
     end

data/lib/active_genie/configs/providers_config.rb

@@ -1,22 +1,34 @@
 # frozen_string_literal: true
 
+require_relative 'base_config'
+require_relative 'providers/openai_config'
+require_relative 'providers/google_config'
+require_relative 'providers/anthropic_config'
+require_relative 'providers/deepseek_config'
+
 module ActiveGenie
   module Config
-    class ProvidersConfig
-      def initialize
-        @all = {}
-        @default = nil
+    class ProvidersConfig < BaseConfig
+      def initialize(**args)
+        @all = {
+          openai: Providers::OpenaiConfig.new(**args.fetch(:openai, {})),
+          google: Providers::GoogleConfig.new(**args.fetch(:google, {})),
+          anthropic: Providers::AnthropicConfig.new(**args.fetch(:anthropic, {})),
+          deepseek: Providers::DeepseekConfig.new(**args.fetch(:deepseek, {}))
+        }
+        super
       end
 
-      attr_reader :all
-
       def default
-        @default || ENV.fetch('PROVIDER_NAME', nil) || valid.keys.first
+        @default ||= ENV.fetch('PROVIDER_NAME', nil)&.to_s&.downcase&.strip
       end
 
       def default=(provider)
-        normalized_provider = provider.to_s.downcase.strip
-        @default = normalized_provider.size.positive? ? normalized_provider : valid.keys.first
+        @default = provider&.to_s&.downcase&.strip
+      end
+
+      def all
+        @all ||= {}
       end
 
       def valid
@@ -24,10 +36,9 @@ module ActiveGenie
         @all.slice(*valid_provider_keys)
       end
 
-      def add(provider_configs)
+      def add(name, provider_configs)
         @all ||= {}
         Array(provider_configs).each do |provider_config|
-          name = provider_config::NAME
           remove([name]) if @all.key?(name)
 
           @all[name] = provider_config.new
@@ -44,11 +55,10 @@ module ActiveGenie
         self
       end
 
-      def merge(config_params = {})
-        dup.tap do |config|
-          config.add(config_params[:providers]) if config_params[:providers]
-          config.default = config_params[:default] if config_params[:default]
-        end
+      def provider_name_by_model(model)
+        return nil if model.nil?
+
+        valid.find { |_, config| config.valid_model?(model) }&.first
       end
 
       def method_missing(method_name, *args, &)
@@ -58,6 +68,15 @@ module ActiveGenie
       def respond_to_missing?(method_name, include_private = false)
         @all.key?(method_name) || super
       end
+
+      def to_h
+        h = {}
+        @all.each do |key, config|
+          h[key] = config.to_h
+        end
+
+        super.merge(h)
+      end
     end
   end
 end

data/lib/active_genie/configs/ranker_config.rb

@@ -1,20 +1,14 @@
 # frozen_string_literal: true
 
+require_relative 'base_config'
+
 module ActiveGenie
   module Config
-    class RankerConfig
-      attr_accessor :score_variation_threshold
-
-      def initialize
-        @score_variation_threshold = 30
-      end
+    class RankerConfig < BaseConfig
+      attr_writer :score_variation_threshold
 
-      def merge(config_params = {})
-        dup.tap do |config|
-          if config_params[:score_variation_threshold]
-            config.score_variation_threshold = config_params[:score_variation_threshold]
-          end
-        end
+      def score_variation_threshold
+        @score_variation_threshold ||= 30
       end
     end
   end