active_genie 0.0.12 → 0.0.18

data/lib/active_genie/clients/helpers/retry.rb

@@ -0,0 +1,29 @@
+MAX_RETRIES = 3
+BASE_DELAY = 0.5
+
+def retry_with_backoff(config: {})
+  retries = config[:runtime][:max_retries] || MAX_RETRIES
+
+  begin
+    yield
+  rescue => e
+    if retries > 0
+      ActiveGenie::Logger.warn({ code: :retry_with_backoff, message: "Retrying request after error: #{e.message}. Attempts remaining: #{retries}" })
+
+      retries -= 1
+      backoff_time = calculate_backoff(MAX_RETRIES - retries)
+      sleep(backoff_time)
+      retry
+    else
+      raise
+    end
+  end
+end
+
+def calculate_backoff(retry_count)
+  # Exponential backoff with jitter: 2^retry_count + random jitter
+  # Base delay is 0.5 seconds, doubles each retry, plus up to 0.5 seconds of random jitter
+  # Simplified example: 0.5, 1, 2, 4, 8, 12, 16, 20, 24, 28, 30 seconds
+  jitter = rand * BASE_DELAY
+  [BASE_DELAY * (2 ** retry_count) + jitter, 30].min # Cap at 30 seconds
+end

data/lib/active_genie/clients/openai_client.rb

@@ -1,119 +1,97 @@
 require 'json'
 require 'net/http'
 
+require_relative './helpers/retry'
+
 module ActiveGenie::Clients
-  class OpenaiClient
-    MAX_RETRIES = 3
-    
+  class OpenaiClient    
     class OpenaiError < StandardError; end
     class RateLimitError < OpenaiError; end
+    class InvalidResponseError < StandardError; end
 
     def initialize(config)
       @app_config = config
     end
 
+      # Requests structured JSON output from the Gemini model based on a schema.
+      #
+      # @param messages [Array<Hash>] A list of messages representing the conversation history.
+      #   Each hash should have :role ('user' or 'model') and :content (String).
+      #   Gemini uses 'user' and 'model' roles.
+      # @param function [Hash] A JSON schema definition describing the desired output format.
+      # @param model_tier [Symbol, nil] A symbolic representation of the model quality/size tier.
+      # @param config [Hash] Optional configuration overrides:
+      #   - :api_key [String] Override the default API key.
+      #   - :model [String] Override the model name directly.
+      #   - :max_retries [Integer] Max retries for the request.
+      #   - :retry_delay [Integer] Initial delay for retries.
+      # @return [Hash, nil] The parsed JSON object matching the schema, or nil if parsing fails or content is empty.
     def function_calling(messages, function, model_tier: nil, config: {})
-      model = config[:model] || @app_config.tier_to_model(model_tier)
+      model = config[:runtime][:model] || @app_config.tier_to_model(model_tier)
 
       payload = {
         messages:,
-        response_format: {
-          type: 'json_schema',
-          json_schema: function
-        },
+        tools: [{ type: 'function', function: }],
+        tool_choice: { type: 'function', function: { name: function[:name] } },
+        stream: false,
         model:,
       }
 
-      api_key = config[:api_key] || @app_config.api_key
+      api_key = config[:runtime][:api_key] || @app_config.api_key
       headers = DEFAULT_HEADERS.merge(
         'Authorization': "Bearer #{api_key}"
       ).compact
 
-      response = request(payload, headers, config:)
+      retry_with_backoff(config:) do
+        response = request(payload, headers, config:)
 
-      parsed_response = JSON.parse(response.dig('choices', 0, 'message', 'content'))
-      parsed_response.dig('properties') || parsed_response
-    rescue JSON::ParserError
-      nil
-    end
+        parsed_response = JSON.parse(response.dig('choices', 0, 'message', 'tool_calls', 0, 'function', 'arguments'))
+        parsed_response = parsed_response.dig('message') || parsed_response
 
-    private
+        raise InvalidResponseError, "Invalid response: #{parsed_response}" if parsed_response.nil? || parsed_response.keys.size.zero?
 
-    def request(payload, headers, config:)
-      retries = config[:max_retries] || MAX_RETRIES
-      start_time = Time.now
-      
-      begin
-        response = Net::HTTP.post(
-          URI("#{@app_config.api_url}/chat/completions"),
-          payload.to_json,
-          headers
-        )
-
-        if response.is_a?(Net::HTTPTooManyRequests)
-          raise RateLimitError, "OpenAI API rate limit exceeded: #{response.body}"
-        end
-
-        raise OpenaiError, response.body unless response.is_a?(Net::HTTPSuccess)
-
-        return nil if response.body.empty?
-
-        parsed_body = JSON.parse(response.body)
-        # log_response(start_time, parsed_body, config:)
-
-        parsed_body
-      rescue OpenaiError, Net::HTTPError, JSON::ParserError, Errno::ECONNRESET, Errno::ETIMEDOUT, Net::OpenTimeout, Net::ReadTimeout => e
-        if retries > 0
-          retries -= 1
-          backoff_time = calculate_backoff(MAX_RETRIES - retries)
-          ActiveGenie::Logger.trace(
-            {
-              category: :llm,
-              trace: "#{config.dig(:log, :trace)}/#{self.class.name}",
-              message: "Retrying request after error: #{e.message}. Attempts remaining: #{retries}",
-              backoff_time: backoff_time
-            }
-          )
-          sleep(backoff_time)
-          retry
-        else
-          ActiveGenie::Logger.trace(
-            {
-              category: :llm,
-              trace: "#{config.dig(:log, :trace)}/#{self.class.name}",
-              message: "Max retries reached. Failing with error: #{e.message}"
-            }
-          )
-          raise
-        end
+        ActiveGenie::Logger.trace({code: :function_calling, payload:, parsed_response: })
+
+        parsed_response
       end
     end
 
-    BASE_DELAY = 0.5
-    def calculate_backoff(retry_count)
-      # Exponential backoff with jitter: 2^retry_count + random jitter
-      # Base delay is 0.5 seconds, doubles each retry, plus up to 0.5 seconds of random jitter
-      # Simplified example: 0.5, 1, 2, 4, 8, 12, 16, 20, 24, 28, 30 seconds
-      jitter = rand * BASE_DELAY
-      [BASE_DELAY * (2 ** retry_count) + jitter, 30].min # Cap at 30 seconds
-    end
+    private
 
     DEFAULT_HEADERS = {
       'Content-Type': 'application/json',
     }
 
-    def log_response(start_time, response, config: {})
-      ActiveGenie::Logger.trace(
-        {
-          **config.dig(:log),
-          category: :llm,
-          trace: "#{config.dig(:log, :trace)}/#{self.class.name}",
-          total_tokens: response.dig('usage', 'total_tokens'),
-          model: response.dig('model'),
-          request_duration: Time.now - start_time,
-          openai: response
-        }
+    def request(payload, headers, config:)
+      start_time = Time.now
+
+      response = Net::HTTP.post(
+        URI("#{@app_config.api_url}/chat/completions"),
+        payload.to_json,
+        headers
       )
+
+      if response.is_a?(Net::HTTPTooManyRequests)
+        raise RateLimitError, "OpenAI API rate limit exceeded: #{response.body}"
+      end
+
+      raise OpenaiError, response.body unless response.is_a?(Net::HTTPSuccess)
+
+      return nil if response.body.empty?
+
+      parsed_body = JSON.parse(response.body)
+
+      ActiveGenie::Logger.trace({
+        code: :llm_usage,
+        input_tokens: parsed_body.dig('usage', 'prompt_tokens'),
+        output_tokens: parsed_body.dig('usage', 'completion_tokens'),
+        total_tokens: parsed_body.dig('usage', 'prompt_tokens') + parsed_body.dig('usage', 'completion_tokens'),
+        model: payload[:model],
+        duration: Time.now - start_time,
+        usage: parsed_body.dig('usage')
+      })
+
+      parsed_body
     end
   end
-end
+end

data/lib/active_genie/clients/unified_client.rb

@@ -2,12 +2,12 @@ module ActiveGenie::Clients
   class UnifiedClient
     class << self
       def function_calling(messages, function, model_tier: nil, config: {})
-        provider_name = config[:provider]&.downcase&.strip&.to_sym
-        provider = ActiveGenie.configuration.providers.all[provider_name] || ActiveGenie.configuration.providers.default
+        provider_name = config[:runtime][:provider]&.to_s&.downcase&.strip&.to_sym || ActiveGenie.configuration.providers.default
+        provider_instance = ActiveGenie.configuration.providers.valid[provider_name]
 
-        raise InvalidProviderError if provider.nil? || provider.client.nil?
+        raise InvalidProviderError if provider_instance.nil? || provider_instance.client.nil?
 
-        provider.client.function_calling(messages, function, model_tier:, config:)
+        provider_instance.client.function_calling(messages, function, model_tier:, config:)
       end
 
       private

data/lib/active_genie/concerns/loggable.rb

@@ -0,0 +1,44 @@
+module ActiveGenie
+  module Concerns
+    module Loggable
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def with_logging_context(context_method, observer_proc = nil)
+          original_method = instance_method(:call)
+          
+          define_method(:call) do |*args, **kwargs, &block|
+            context = send(context_method, *args, **kwargs)
+            bound_observer = observer_proc ? ->(log) { instance_exec(log, &observer_proc) } : nil
+            
+            ActiveGenie::Logger.with_context(context, observer: bound_observer) do
+              original_method.bind(self).call(*args, **kwargs, &block)
+            end
+          end
+        end
+      end
+
+      def info(log)
+        ::ActiveGenie::Logger.info(log)
+      end
+
+      def error(log)
+        ::ActiveGenie::Logger.error(log)
+      end
+
+      def warn(log)
+        ::ActiveGenie::Logger.warn(log)
+      end
+
+      def debug(log)
+        ::ActiveGenie::Logger.debug(log)
+      end
+
+      def trace(log)
+        ::ActiveGenie::Logger.trace(log)
+      end
+    end
+  end
+end

data/lib/active_genie/configuration/log_config.rb

@@ -8,7 +8,7 @@ module ActiveGenie::Configuration
     end
 
     def to_h(config = {})
-      { log_level:, **config }
+      { log_level: }.merge(config)
     end
   end
 end

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

@@ -0,0 +1,54 @@
+require_relative '../../clients/anthropic_client'
+require_relative './base_config'
+
+module ActiveGenie
+  module Configuration::Providers
+    # Configuration class for the Anthropic API client.
+    # Manages API keys, URLs, model selections, and client instantiation.
+    class AnthropicConfig < BaseConfig
+      NAME = :anthropic
+
+      # Retrieves the API key.
+      # Falls back to the ANTHROPIC_API_KEY environment variable if not set.
+      # @return [String, nil] The API key.
+      def api_key
+        @api_key || ENV['ANTHROPIC_API_KEY']
+      end
+
+      # Retrieves the base API URL for Anthropic API.
+      # Defaults to 'https://api.anthropic.com'.
+      # @return [String] The API base URL.
+      def api_url
+        @api_url || 'https://api.anthropic.com'
+      end
+
+      # Lazily initializes and returns an instance of the AnthropicClient.
+      # Passes itself (the config object) to the client's constructor.
+      # @return [ActiveGenie::Clients::AnthropicClient] The client instance.
+      def client
+        @client ||= ::ActiveGenie::Clients::AnthropicClient.new(self)
+      end
+
+      # Retrieves the model name designated for the lower tier (e.g., cost-effective, faster).
+      # Defaults to 'claude-3-haiku'.
+      # @return [String] The lower tier model name.
+      def lower_tier_model
+        @lower_tier_model || 'claude-3-5-haiku-20241022'
+      end
+
+      # Retrieves the model name designated for the middle tier (e.g., balanced performance).
+      # Defaults to 'claude-3-sonnet'.
+      # @return [String] The middle tier model name.
+      def middle_tier_model
+        @middle_tier_model || 'claude-3-7-sonnet-20250219'
+      end
+
+      # Retrieves the model name designated for the upper tier (e.g., most capable).
+      # Defaults to 'claude-3-opus'.
+      # @return [String] The upper tier model name.
+      def upper_tier_model
+        @upper_tier_model || 'claude-3-opus-20240229'
+      end
+    end
+  end
+end

data/lib/active_genie/configuration/providers/base_config.rb

@@ -0,0 +1,85 @@
+module ActiveGenie
+  module Configuration::Providers
+    class BaseConfig
+      NAME = :unknown
+
+      attr_writer :api_key, :organization, :api_url, :client,
+        :lower_tier_model, :middle_tier_model, :upper_tier_model
+
+      # Maps a symbolic tier (:lower_tier, :middle_tier, :upper_tier) to a specific model name.
+      # Falls back to the lower_tier_model if the tier is nil or unrecognized.
+      # @param tier [Symbol, String, nil] The symbolic tier name.
+      # @return [String] The corresponding model name.
+      def tier_to_model(tier)
+        {
+          lower_tier: lower_tier_model,
+          middle_tier: middle_tier_model,
+          upper_tier: upper_tier_model
+        }[tier&.to_sym] || lower_tier_model
+      end
+
+      # 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:,
+          lower_tier_model:,
+          middle_tier_model:,
+          upper_tier_model:,
+          **config
+        }
+      end
+
+      # 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"
+      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"
+      end
+
+      # Retrieves the model name designated for the lower tier (e.g., cost-effective, faster).
+      # Defaults to 'gpt-4o-mini'.
+      # @return [String] The lower tier model name.
+      def lower_tier_model
+        raise NotImplementedError, "Subclasses must implement this method"
+      end
+
+      # Retrieves the model name designated for the middle tier (e.g., balanced performance).
+      # Defaults to 'gpt-4o'.
+      # @return [String] The middle tier model name.
+      def middle_tier_model
+        raise NotImplementedError, "Subclasses must implement this method"
+      end
+
+      # Retrieves the model name designated for the upper tier (e.g., most capable).
+      # Defaults to 'o1-preview'.
+      # @return [String] The upper tier model name.
+      def upper_tier_model
+        raise NotImplementedError, "Subclasses must implement this method"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+require_relative '../../clients/openai_client'
+require_relative './base_config'
+
+module ActiveGenie
+  module Configuration::Providers
+    # Configuration class for the DeepSeek API client.
+    # Manages API keys, organization IDs, URLs, model selections, and client instantiation.
+    class DeepseekConfig < BaseConfig
+      NAME = :deepseek
+
+      # Retrieves the API key.
+      # Falls back to the DEEPSEEK_API_KEY environment variable if not set.
+      # @return [String, nil] The API key.
+      def api_key
+        @api_key || ENV['DEEPSEEK_API_KEY']
+      end
+
+      # Retrieves the base API URL for DeepSeek API.
+      # Defaults to 'https://api.deepseek.com/v1'.
+      # @return [String] The API base URL.
+      def api_url
+        @api_url || 'https://api.deepseek.com/v1'
+      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
+        @client ||= ::ActiveGenie::Clients::OpenaiClient.new(self)
+      end
+
+      # Retrieves the model name designated for the lower tier (e.g., cost-effective, faster).
+      # Defaults to 'deepseek-chat'.
+      # @return [String] The lower tier model name.
+      def lower_tier_model
+        @lower_tier_model || 'deepseek-chat'
+      end
+
+      # Retrieves the model name designated for the middle tier (e.g., balanced performance).
+      # Defaults to 'deepseek-chat'.
+      # @return [String] The middle tier model name.
+      def middle_tier_model
+        @middle_tier_model || 'deepseek-chat'
+      end
+
+      # Retrieves the model name designated for the upper tier (e.g., most capable).
+      # Defaults to 'deepseek-reasoner'.
+      # @return [String] The upper tier model name.
+      def upper_tier_model
+        @upper_tier_model || 'deepseek-reasoner'
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+require_relative '../../clients/google_client'
+require_relative './base_config'
+
+module ActiveGenie
+  module Configuration::Providers
+    # Configuration class for the Google Generative Language API client.
+    # Manages API keys, URLs, model selections, and client instantiation.
+    class GoogleConfig < BaseConfig
+      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.
+      def api_key
+        @api_key || ENV['GENERATIVE_LANGUAGE_GOOGLE_API_KEY'] || ENV['GEMINI_API_KEY']
+      end
+
+      # Retrieves the base API URL for Google Generative Language API.
+      # Defaults to 'https://generativelanguage.googleapis.com'.
+      # @return [String] The API base URL.
+      def api_url
+        # Note: Google Generative Language API uses a specific path structure like /v1beta/models/{model}:generateContent
+        # The base URL here should be just the domain part.
+        @api_url || 'https://generativelanguage.googleapis.com'
+      end
+
+      # Lazily initializes and returns an instance of the GoogleClient.
+      # Passes itself (the config object) to the client's constructor.
+      # @return [ActiveGenie::Clients::GoogleClient] The client instance.
+      def client
+        @client ||= ::ActiveGenie::Clients::GoogleClient.new(self)
+      end
+
+      # Retrieves the model name designated for the lower tier (e.g., cost-effective, faster).
+      # Defaults to 'gemini-2.0-flash-lite'.
+      # @return [String] The lower tier model name.
+      def lower_tier_model
+        @lower_tier_model || 'gemini-2.0-flash-lite'
+      end
+
+      # Retrieves the model name designated for the middle tier (e.g., balanced performance).
+      # Defaults to 'gemini-2.0-flash'.
+      # @return [String] The middle tier model name.
+      def middle_tier_model
+        @middle_tier_model || 'gemini-2.0-flash'
+      end
+
+      # Retrieves the model name designated for the upper tier (e.g., most capable).
+      # Defaults to 'gemini-2.5-pro-experimental'.
+      # @return [String] The upper tier model name.
+      def upper_tier_model
+        @upper_tier_model || 'gemini-2.5-pro-experimental'
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+require_relative '../../clients/openai_client'
+require_relative './base_config'
+
+module ActiveGenie
+  module Configuration::Providers
+    # Configuration class for the OpenAI API client.
+    # Manages API keys, organization IDs, URLs, model selections, and client instantiation.
+    class OpenaiConfig < BaseConfig
+      NAME = :openai
+
+      # 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
+        @api_key || ENV['OPENAI_API_KEY']
+      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
+        @api_url || 'https://api.openai.com/v1'
+      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
+        @client ||= ::ActiveGenie::Clients::OpenaiClient.new(self)
+      end
+
+      # Retrieves the model name designated for the lower tier (e.g., cost-effective, faster).
+      # Defaults to 'gpt-4o-mini'.
+      # @return [String] The lower tier model name.
+      def lower_tier_model
+        @lower_tier_model || 'gpt-4o-mini'
+      end
+
+      # Retrieves the model name designated for the middle tier (e.g., balanced performance).
+      # Defaults to 'gpt-4o'.
+      # @return [String] The middle tier model name.
+      def middle_tier_model
+        @middle_tier_model || 'gpt-4o'
+      end
+
+      # Retrieves the model name designated for the upper tier (e.g., most capable).
+      # Defaults to 'o1-preview'.
+      # @return [String] The upper tier model name.
+      def upper_tier_model
+        @upper_tier_model || 'o1-preview'
+      end
+    end
+  end
+end

data/lib/active_genie/configuration/providers_config.rb

@@ -5,8 +5,9 @@ module ActiveGenie::Configuration
       @default = nil
     end
 
-    def register(name, provider_class)
+    def register(provider_class)
       @all ||= {}
+      name = provider_class::NAME
       @all[name] = provider_class.new
       define_singleton_method(name) do
         instance_variable_get("@#{name}") || instance_variable_set("@#{name}", @all[name])
@@ -16,11 +17,12 @@ module ActiveGenie::Configuration
     end
 
     def default
-      @default || @all.values.first
+      @default || @all.values.find { |p| p.api_key }.class::NAME
     end
 
-    def all
-      @all
+    def valid
+      valid_provider_keys = @all.keys.select { |k| @all[k].valid? }
+      @all.slice(*valid_provider_keys)
     end
 
     def to_h(config = {})
@@ -32,6 +34,7 @@ module ActiveGenie::Configuration
     end
 
     private
+
     attr_writer :default
   end
 end

data/lib/active_genie/configuration/runtime_config.rb

@@ -0,0 +1,35 @@
+module ActiveGenie::Configuration
+  class RuntimeConfig
+    attr_writer :max_tokens, :temperature, :model, :provider, :api_key, :max_retries
+
+    def max_tokens
+      @max_tokens ||= 4096
+    end
+
+    def temperature
+      @temperature ||= 0.1
+    end
+
+    def model
+      @model
+    end
+
+    def provider
+      @provider ||= ActiveGenie.configuration.providers.default
+    end
+
+    def api_key
+      @api_key
+    end
+
+    def max_retries
+      @max_retries ||= 3
+    end
+
+    def to_h(config = {})
+      {
+        max_tokens:, temperature:, model:, provider:, api_key:, max_retries:,
+      }.merge(config)
+    end
+  end
+end