active_genie 0.30.1 → 0.30.8

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,31 +36,29 @@ module ActiveGenie
         @all.slice(*valid_provider_keys)
       end
 
-      def add(provider_classes)
+      def add(name, provider_configs)
         @all ||= {}
-        Array(provider_classes).each do |provider|
-          name = provider::NAME
+        Array(provider_configs).each do |provider_config|
           remove([name]) if @all.key?(name)
 
-          @all[name] = provider.new
+          @all[name] = provider_config.new
         end
 
         self
       end
 
-      def remove(provider_classes)
-        Array(provider_classes).each do |provider|
+      def remove(provider_configs)
+        Array(provider_configs).each do |provider|
           @all.delete(provider::NAME)
         end
 
         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

data/lib/active_genie/configuration.rb

@@ -1,90 +1,53 @@
 # frozen_string_literal: true
 
-require_relative 'configs/comparator_config'
 require_relative 'configs/extractor_config'
 require_relative 'configs/lister_config'
 require_relative 'configs/llm_config'
 require_relative 'configs/log_config'
 require_relative 'configs/providers_config'
 require_relative 'configs/ranker_config'
-require_relative 'configs/scorer_config'
 
 module ActiveGenie
   class Configuration
-    def log
-      @log ||= Config::LogConfig.new
+    def initialize(initial_config = nil)
+      @initial_config = initial_config || {}
     end
 
     def providers
-      @providers ||= Config::ProvidersConfig.new
-    end
-
-    def ranker
-      @ranker ||= Config::RankerConfig.new
-    end
-
-    def scorer
-      @scorer ||= Config::ScorerConfig.new
+      @providers ||= Config::ProvidersConfig.new(**@initial_config.fetch(:providers, {}))
     end
 
-    def extractor
-      @extractor ||= Config::ExtractorConfig.new
+    def llm
+      @llm ||= Config::LlmConfig.new(**@initial_config.fetch(:llm, {}))
     end
 
-    def comparator
-      @comparator ||= Config::ComparatorConfig.new
+    def log
+      @log ||= Config::LogConfig.new(**@initial_config.fetch(:log, {}))
     end
 
-    def lister
-      @lister ||= Config::ListerConfig.new
-    end
+    # Modules
 
-    def llm
-      @llm ||= Config::LlmConfig.new
+    def ranker
+      @ranker ||= Config::RankerConfig.new(**@initial_config.fetch(:ranker, {}))
     end
 
-    def logger
-      @logger ||= ActiveGenie::Logger.new(log_config: log)
+    def extractor
+      @extractor ||= Config::ExtractorConfig.new(**@initial_config.fetch(:extractor, {}))
     end
 
-    SUB_CONFIGS = %w[log providers llm ranker scorer extractor comparator lister].freeze
-
-    def merge(config_params = {})
-      return config_params if config_params.is_a?(Configuration)
-
-      new_configuration = dup
-
-      SUB_CONFIGS.each do |key|
-        config = new_configuration.send(key)
-
-        next unless config.respond_to?(:merge)
-
-        new_config = sub_config_merge(config, key, config_params)
-
-        new_configuration.send("#{key}=", new_config)
-      end
-      @logger = nil
-
-      new_configuration
+    def lister
+      @lister ||= Config::ListerConfig.new(**@initial_config.fetch(:lister, {}))
     end
 
-    # Merges a sub config with the config_params.
-    # Examples:
-    #   config.merge({ 'log' => { file_path: 'log/active_genie.log' } })
-    #   config.merge({ log: { file_path: 'log/active_genie.log' } })
-    #   config.merge({ file_path: 'log/active_genie.log' })
-    # these are all the same
-
-    def sub_config_merge(config, key, config_params)
-      if config_params&.key?(key.to_s)
-        config.merge(config_params[key.to_s])
-      elsif config_params&.key?(key.to_sym)
-        config.merge(config_params[key.to_sym])
-      else
-        config.merge(config_params || {})
-      end
+    def to_h
+      {
+        providers: providers.to_h,
+        llm: llm.to_h,
+        log: log.to_h,
+        ranker: ranker.to_h,
+        extractor: extractor.to_h,
+        lister: lister.to_h
+      }
     end
-
-    attr_writer(*SUB_CONFIGS, :logger)
   end
 end

data/lib/active_genie/{ranker/entities → entities}/player.rb

@@ -92,6 +92,10 @@ module ActiveGenie
           }
         end
 
+        def to_s
+          content.to_s
+        end
+
         def method_missing(method_name, *args, &)
           if method_name == :[] && args.size == 1
             attr_name = args.first.to_sym

data/lib/active_genie/{ranker/entities → entities}/players.rb

@@ -90,7 +90,7 @@ module ActiveGenie
         def tier_size
           size = (eligible_size / 3).ceil
 
-          if eligible_size < 10
+          if eligible_size < 10 * 2
             (eligible_size / 2).ceil
           else
             size.clamp(10, eligible_size - 10)

data/lib/active_genie/entities/result.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ActiveGenie
+  class Result
+    attr_reader :data, :reasoning, :metadata
+
+    def initialize(data:, metadata:, reasoning: nil)
+      @data = data
+      @reasoning = reasoning
+      @metadata = metadata
+    end
+
+    def explanation
+      @reasoning
+    end
+
+    def to_h
+      { data: @data, reasoning: @reasoning, metadata: @metadata }
+    end
+
+    def to_s
+      to_h.to_s
+    end
+
+    def to_json(...)
+      to_h.to_json(...)
+    end
+  end
+end

data/lib/active_genie/errors/invalid_model_error.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ActiveGenie
+  class InvalidModelError < StandardError
+    TEXT = <<~TEXT
+      Invalid model: %<model>s
+
+      To configure ActiveGenie, you can either:
+      1. Set up global configuration:
+         ```ruby
+         ActiveGenie.configure do |config|
+          config.providers.openai.api_key = 'your_api_key'
+           config.llm.model = 'gpt-5'
+           # ... other configuration options
+         end
+         ```
+
+      2. Or pass configuration directly to the method call:
+         ```ruby
+         ActiveGenie::Extraction.call(
+           arg1,
+           arg2,
+           config: {
+             providers: {
+               openai: {
+                 api_key: 'your_api_key'
+               }
+             },
+             llm: {
+               model: 'gpt-5'
+             }
+           }
+         )
+         ```
+
+    TEXT
+
+    def initialize(model)
+      super(format(TEXT, model:))
+    end
+  end
+end

data/lib/active_genie/errors/invalid_provider_error.rb

@@ -39,7 +39,7 @@ module ActiveGenie
     end
 
     def available_providers
-      ActiveGenie.configuration.providers.all.keys.join(', ')
+      ActiveGenie.configuration.providers.valid.keys.join(', ')
     end
   end
 end

data/lib/active_genie/errors/provider_server_error.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ActiveGenie
+  class ProviderServerError < StandardError
+    TEXT = <<~TEXT
+      Provider server error: %<code>s
+      %<body>s
+
+      Providers errors are common and can occur for various reasons, such as:
+      - Invalid API key
+      - Exceeded usage limits
+      - Temporary server issues
+
+      Be ready to handle these errors gracefully in your application. We recommend implementing retry logic and exponential backoff strategies.
+      Usually async workers layer is the ideal place to handle such errors.
+    TEXT
+
+    def initialize(response)
+      super(format(
+        TEXT,
+        code: response&.code.to_s,
+        body: response&.body.to_s.strip.empty? ? '(no body)' : response&.body.to_s
+      ))
+    end
+  end
+end

data/lib/active_genie/errors/without_available_provider_error.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ActiveGenie
+  class WithoutAvailableProviderError < StandardError
+    TEXT = <<~TEXT
+      Missing at least one credentialed provider to proceed.
+
+      To configure ActiveGenie, you can either:
+      1. Set up global configuration:
+         ```ruby
+         ActiveGenie.configure do |config|
+           config.providers.default = 'openai'
+           config.providers.openai.api_key = 'your_api_key'
+           # ... other configuration options
+         end
+         ```
+
+      2. Or pass configuration directly to the method call:
+         ```ruby
+         ActiveGenie::Extractor.call(
+           arg1,
+           arg2,
+           config: {
+             providers: {
+               default: 'openai',
+               openai: {
+                 api_key: 'your_api_key'
+               }
+             }
+           }
+         )
+         ```
+    TEXT
+
+    def initialize
+      super(TEXT)
+    end
+  end
+end

data/lib/active_genie/extractor/data.json

@@ -0,0 +1,9 @@
+{
+  "name": "data_extractor",
+  "description": "Extract structured and typed data from text",
+  "parameters": {
+    "type": "object",
+    "properties": {},
+    "required": {}
+  }
+}

data/lib/active_genie/extractor/data.prompt.md

@@ -0,0 +1,12 @@
+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.
+
+# 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.

data/lib/active_genie/extractor/data.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative '../providers/unified_provider'
+
+module ActiveGenie
+  module Extractor
+    class Data < ActiveGenie::BaseModule
+      # 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 config [Hash] Additional config for the extraction process
+      #
+      # @return [Hash] The extracted data matching the schema structure. Each field will include
+      #   both the extracted value.
+      #
+      # @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"
+      #   Extractor.with_explanation(text, schema)
+      #   # => { name: "John Doe", age: 25 }
+      def initialize(text, data_to_extract, config: {})
+        @text = text
+        @data_to_extract = data_to_extract
+        super(config:)
+      end
+
+      def call
+        messages = [
+          {  role: 'system', content: prompt },
+          {  role: 'user', content: @text }
+        ]
+
+        function = JSON.parse(File.read(File.join(__dir__, 'data.json')), symbolize_names: true)
+        function[:parameters][:properties] = @data_to_extract
+        function[:parameters][:required] = @data_to_extract.keys
+
+        provider_response = ::ActiveGenie::Providers::UnifiedProvider.function_calling(
+          messages,
+          function,
+          config: config
+        )
+
+        response_formatted(provider_response)
+      end
+
+      private
+
+      def response_formatted(provider_response)
+        data = provider_response.compact
+
+        ActiveGenie::Result.new(
+          data:,
+          metadata: provider_response
+        )
+      end
+
+      def prompt
+        File.read(File.join(__dir__, 'data.prompt.md'))
+      end
+
+      def module_config
+        { llm: { recommended_model: 'deepseek-chat' } }
+      end
+    end
+  end
+end

data/lib/active_genie/extractor/explanation.rb

@@ -1,14 +1,11 @@
 # frozen_string_literal: true
 
 require_relative '../providers/unified_provider'
+require_relative '../utils/deep_merge'
 
 module ActiveGenie
   module Extractor
-    class Explanation
-      def self.call(...)
-        new(...).call
-      end
-
+    class Explanation < ActiveGenie::BaseModule
       # Extracts structured data from text based on a predefined schema.
       #
       # @param text [String] The input text to analyze and extract data from
@@ -31,7 +28,7 @@ module ActiveGenie
       def initialize(text, data_to_extract, config: {})
         @text = text
         @data_to_extract = data_to_extract
-        @config = ActiveGenie.configuration.merge(config)
+        super(config:)
       end
 
       def call
@@ -46,16 +43,18 @@ module ActiveGenie
         function[:parameters][:properties] = properties
         function[:parameters][:required] = properties.keys
 
-        response = function_calling(messages, function)
+        provider_response = ::ActiveGenie::Providers::UnifiedProvider.function_calling(
+          messages,
+          function,
+          config: config
+        )
 
-        simplify_response(response)
+        response_formatted(provider_response)
       end
 
       private
 
       def data_to_extract_with_explanation
-        return @data_to_extract unless @config.extractor.with_explanation
-
         with_explanation = {}
 
         @data_to_extract.each do |key, value|
@@ -80,47 +79,29 @@ module ActiveGenie
         with_explanation
       end
 
-      def function_calling(messages, function)
-        response = ::ActiveGenie::Providers::UnifiedProvider.function_calling(
-          messages,
-          function,
-          config: @config
-        )
+      def response_formatted(provider_response)
+        data = provider_response.slice(*@data_to_extract.keys.map(&:to_s)).transform_keys(&:to_sym)
 
-        @config.logger.call(
-          {
-            code: :extractor,
-            text: @text[0..30],
-            data_to_extract: function[:parameters][:properties],
-            extracted_data: response
-          }
-        )
+        first_reasoning_key = provider_response["#{provider_response.keys.first}_explanation"]
 
-        response
-      end
-
-      def simplify_response(response)
-        return response if @config.extractor.verbose
-
-        simplified_response = {}
-
-        @data_to_extract.each_key do |key|
-          next unless response.key?(key.to_s)
-          next if response.key?("#{key}_accuracy") && response["#{key}_accuracy"] < min_accuracy
-
-          simplified_response[key] = response[key.to_s]
-        end
-
-        simplified_response
+        ActiveGenie::Result.new(
+          data:,
+          reasoning: first_reasoning_key,
+          metadata: provider_response
+        )
       end
 
       def min_accuracy
-        @config.extractor.min_accuracy # default 70
+        config.extractor.min_accuracy # default 70
       end
 
       def prompt
         File.read(File.join(__dir__, 'explanation.prompt.md'))
       end
+
+      def module_config
+        { llm: { recommended_model: 'deepseek-chat' } }
+      end
     end
   end
 end

data/lib/active_genie/extractor/litote.rb

@@ -4,11 +4,7 @@ require_relative 'explanation'
 
 module ActiveGenie
   module Extractor
-    class Litote
-      def self.call(...)
-        new(...).call
-      end
-
+    class Litote < ActiveGenie::BaseModule
       # Extracts data from informal text while also detecting litotes and their meanings.
       # This method extends the basic extraction by analyzing rhetorical devices.
       #
@@ -31,14 +27,15 @@ module ActiveGenie
       def initialize(text, data_to_extract, config: {})
         @text = text
         @data_to_extract = data_to_extract
-        @config = ActiveGenie.configuration.merge(config)
+        super(config:)
       end
 
       def call
-        response = Explanation.call(@text, extract_with_litote, config: @config)
+        response = Explanation.call(@text, extract_with_litote, config:)
 
-        if response[:message_litote]
-          response = Explanation.call(response[:litote_rephrased], @data_to_extract, config: @config)
+        if response.data[:message_litote]
+          response = Explanation.call(response.data[:litote_rephrased], @data_to_extract,
+                                      config:)
         end
 
         response
@@ -51,6 +48,10 @@ module ActiveGenie
 
         @data_to_extract.merge(parameters)
       end
+
+      def module_config
+        { llm: { recommended_model: 'deepseek-chat' } }
+      end
     end
   end
 end

data/lib/active_genie/extractor.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'extractor/explanation'
+require_relative 'extractor/data'
 require_relative 'extractor/litote'
 
 module ActiveGenie
@@ -15,6 +16,10 @@ module ActiveGenie
       Explanation.call(...)
     end
 
+    def data(...)
+      Data.call(...)
+    end
+
     def with_litote(...)
       Litote.call(...)
     end