active_genie 0.0.12 → 0.0.19

data/lib/active_genie/clients/base_client.rb

@@ -0,0 +1,241 @@
+module ActiveGenie
+  module Clients
+    class BaseClient
+      class ClientError < StandardError; end
+      class RateLimitError < ClientError; end
+      class TimeoutError < ClientError; end
+      class NetworkError < ClientError; end
+
+      DEFAULT_HEADERS = {
+        'Content-Type': 'application/json',
+        'Accept': 'application/json',
+        'User-Agent': 'ActiveGenie/1.0',
+      }.freeze
+
+      DEFAULT_TIMEOUT = 60 # seconds
+      DEFAULT_OPEN_TIMEOUT = 10 # seconds
+      DEFAULT_MAX_RETRIES = 3
+      DEFAULT_RETRY_DELAY = 1 # seconds
+
+      attr_reader :app_config
+
+      def initialize(config)
+        @app_config = config
+      end
+
+      # Make a GET request to the specified endpoint
+      #
+      # @param endpoint [String] The API endpoint to call
+      # @param headers [Hash] Additional headers to include in the request
+      # @param params [Hash] Query parameters for the request
+      # @param config [Hash] Configuration options including timeout, retries, etc.
+      # @return [Hash, nil] The parsed JSON response or nil if empty
+      def get(endpoint, params: {}, headers: {}, config: {})
+        uri = build_uri(endpoint, params)
+        request = Net::HTTP::Get.new(uri)
+        execute_request(uri, request, headers, config)
+      end
+
+      # Make a POST request to the specified endpoint
+      #
+      # @param endpoint [String] The API endpoint to call
+      # @param payload [Hash] The request body to send
+      # @param headers [Hash] Additional headers to include in the request
+      # @param config [Hash] Configuration options including timeout, retries, etc.
+      # @return [Hash, nil] The parsed JSON response or nil if empty
+      def post(endpoint, payload, params: {}, headers: {}, config: {})
+        uri = build_uri(endpoint, params)
+        request = Net::HTTP::Post.new(uri)
+        request.body = payload.to_json
+        execute_request(uri, request, headers, config)
+      end
+
+      # Make a PUT request to the specified endpoint
+      #
+      # @param endpoint [String] The API endpoint to call
+      # @param payload [Hash] The request body to send
+      # @param headers [Hash] Additional headers to include in the request
+      # @param config [Hash] Configuration options including timeout, retries, etc.
+      # @return [Hash, nil] The parsed JSON response or nil if empty
+      def put(endpoint, payload, headers: {}, config: {})
+        uri = build_uri(endpoint)
+        request = Net::HTTP::Put.new(uri)
+        request.body = payload.to_json
+        execute_request(uri, request, headers, config)
+      end
+
+      # Make a DELETE request to the specified endpoint
+      #
+      # @param endpoint [String] The API endpoint to call
+      # @param headers [Hash] Additional headers to include in the request
+      # @param params [Hash] Query parameters for the request
+      # @param config [Hash] Configuration options including timeout, retries, etc.
+      # @return [Hash, nil] The parsed JSON response or nil if empty
+      def delete(endpoint, headers: {}, params: {}, config: {})
+        uri = build_uri(endpoint, params)
+        request = Net::HTTP::Delete.new(uri)
+        execute_request(uri, request, headers, config)
+      end
+
+      protected
+
+      # Execute a request with retry logic and proper error handling
+      #
+      # @param uri [URI] The URI for the request
+      # @param request [Net::HTTP::Request] The request object
+      # @param headers [Hash] Additional headers to include
+      # @param config [Hash] Configuration options
+      # @return [Hash, nil] The parsed JSON response or nil if empty
+      def execute_request(uri, request, headers, config)
+        start_time = Time.now
+        
+        # Apply headers
+        apply_headers(request, headers)
+        
+        # Apply retry logic
+        retry_with_backoff(config) do
+          http = create_http_client(uri, config)
+          
+          begin
+            response = http.request(request)
+            
+            # Handle common HTTP errors
+            case response
+            when Net::HTTPSuccess
+              parsed_response = parse_response(response)
+              
+              # Log request details if logging is enabled
+              log_request_details(
+                uri: uri, 
+                method: request.method,
+                status: response.code,
+                duration: Time.now - start_time,
+                response: parsed_response
+              )
+              
+              parsed_response
+            when Net::HTTPTooManyRequests
+              raise RateLimitError, "Rate limit exceeded: #{response.body}"
+            when Net::HTTPClientError, Net::HTTPServerError
+              raise ClientError, "HTTP Error #{response.code}: #{response.body}"
+            else
+              raise ClientError, "Unexpected response: #{response.code} - #{response.body}"
+            end
+          rescue Timeout::Error, Errno::ETIMEDOUT
+            raise TimeoutError, "Request to #{uri} timed out"
+          rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, SocketError => e
+            raise NetworkError, "Network error: #{e.message}"
+          end
+        end
+      end
+
+      # Create and configure an HTTP client
+      #
+      # @param uri [URI] The URI for the request
+      # @param config [Hash] Configuration options
+      # @return [Net::HTTP] Configured HTTP client
+      def create_http_client(uri, config)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == 'https')
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        http.read_timeout = config.dig(:runtime, :timeout) || DEFAULT_TIMEOUT
+        http.open_timeout = config.dig(:runtime, :open_timeout) || DEFAULT_OPEN_TIMEOUT
+        http
+      end
+
+      # Apply headers to the request
+      #
+      # @param request [Net::HTTP::Request] The request object
+      # @param headers [Hash] Additional headers to include
+      def apply_headers(request, headers)
+        DEFAULT_HEADERS.each do |key, value|
+          request[key] = value
+        end
+        
+        headers.each do |key, value|
+          request[key.to_s] = value
+        end
+      end
+
+      # Build a URI for the request
+      #
+      # @param endpoint [String] The API endpoint
+      # @param params [Hash] Query parameters
+      # @return [URI] The constructed URI
+      def build_uri(endpoint, params = {})
+        base_url = @app_config.api_url
+        uri = URI("#{base_url}#{endpoint}")
+        
+        unless params.empty?
+          uri.query = URI.encode_www_form(params)
+        end
+        
+        uri
+      end
+
+      # Parse the response body
+      #
+      # @param response [Net::HTTPResponse] The HTTP response
+      # @return [Hash, nil] Parsed JSON or nil if empty
+      def parse_response(response)
+        return nil if response.body.nil? || response.body.empty?
+        
+        begin
+          JSON.parse(response.body)
+        rescue JSON::ParserError => e
+          raise ClientError, "Failed to parse JSON response: #{e.message}"
+        end
+      end
+
+      # Log request details if logging is enabled
+      #
+      # @param details [Hash] Request and response details
+      def log_request_details(details)
+        return unless defined?(ActiveGenie::Logger)
+        
+        ActiveGenie::Logger.trace({
+          code: :http_request,
+          uri: details[:uri].to_s,
+          method: details[:method],
+          status: details[:status],
+          duration: details[:duration],
+          response_size: details[:response].to_s.bytesize
+        })
+      end
+
+      # Retry a block with exponential backoff
+      #
+      # @param config [Hash] Configuration options
+      # @yield The block to retry
+      # @return [Object] The result of the block
+      def retry_with_backoff(config = {})
+        max_retries = config.dig(:runtime, :max_retries) || DEFAULT_MAX_RETRIES
+        retry_delay = config.dig(:runtime, :retry_delay) || DEFAULT_RETRY_DELAY
+        
+        retries = 0
+        
+        begin
+          yield
+        rescue RateLimitError, NetworkError => e
+          if retries < max_retries
+            sleep_time = retry_delay * (2 ** retries)
+            retries += 1
+            
+            ActiveGenie::Logger.trace({
+              code: :retry_attempt,
+              attempt: retries,
+              max_retries: max_retries,
+              delay: sleep_time,
+              error: e.message
+            }) if defined?(ActiveGenie::Logger)
+            
+            sleep(sleep_time)
+            retry
+          else
+            raise
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_genie/clients/google_client.rb

@@ -0,0 +1,135 @@
+require 'json'
+require 'net/http'
+require 'uri'
+require_relative './helpers/retry'
+require_relative './base_client'
+
+module ActiveGenie::Clients
+  # Client for interacting with the Google Generative Language API.
+  class GoogleClient < BaseClient
+    class GoogleError < ClientError; end
+    class RateLimitError < GoogleError; end
+
+    API_VERSION_PATH = '/v1beta/models'.freeze
+
+    def initialize(config)
+      super(config)
+    end
+
+    # Requests structured JSON output from the Google Generative Language 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).
+    #   Google Generative Language 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[:runtime][:model] || @app_config.tier_to_model(model_tier)
+      api_key = config[:runtime][:api_key] || @app_config.api_key
+
+      contents = convert_messages_to_contents(messages, function)
+      contents << output_as_json_schema(function)
+
+      payload = {
+        contents: contents,
+        generationConfig: {
+          response_mime_type: "application/json",
+          temperature: 0.1
+        }
+      }
+
+      endpoint = "#{API_VERSION_PATH}/#{model}:generateContent"
+      params = { key: api_key }
+      headers = DEFAULT_HEADERS
+
+      retry_with_backoff(config:) do
+        start_time = Time.now
+        
+        response = post(endpoint, payload, headers:, params:, config: config)
+        
+        json_string = response&.dig('candidates', 0, 'content', 'parts', 0, 'text')
+        return nil if json_string.nil? || json_string.empty?
+
+        begin
+          parsed_response = JSON.parse(json_string)
+          
+          # Log usage metrics
+          usage_metadata = response['usageMetadata'] || {}
+          prompt_tokens = usage_metadata['promptTokenCount'] || 0
+          candidates_tokens = usage_metadata['candidatesTokenCount'] || 0
+          total_tokens = usage_metadata['totalTokenCount'] || (prompt_tokens + candidates_tokens)
+
+          ActiveGenie::Logger.trace({
+            code: :llm_usage,
+            input_tokens: prompt_tokens,
+            output_tokens: candidates_tokens,
+            total_tokens: total_tokens,
+            model: model,
+            duration: Time.now - start_time,
+            usage: usage_metadata
+          })
+          
+          ActiveGenie::Logger.trace({ code: :function_calling, payload:, parsed_response: })
+          
+          normalize_function_output(parsed_response)
+        rescue JSON::ParserError => e
+          raise GoogleError, "Failed to parse Google API response: #{e.message} - Content: #{json_string}"
+        end
+      end
+    end
+
+    private
+
+    def normalize_function_output(output)
+      output = if output.is_a?(Array)
+        output.dig(0, 'properties') || output.dig(0)
+      else
+        output
+      end
+
+      output.dig('input_schema', 'properties') || output
+    end
+
+    ROLE_TO_GOOGLE_ROLE = {
+      user: 'user',
+      assistant: 'model',
+    }.freeze
+
+    # Converts standard message format to Google's 'contents' format
+    # and injects JSON schema instructions.
+    # @param messages [Array<Hash>] Array of { role: 'user'/'assistant'/'system', content: '...' }
+    # @param function_schema [Hash] The JSON schema for the desired output.
+    # @return [Array<Hash>] Array formatted for Google's 'contents' field.
+    def convert_messages_to_contents(messages, function_schema)
+      messages.map do |message|
+        {
+          role: ROLE_TO_GOOGLE_ROLE[message[:role].to_sym] || 'user',
+          parts: [{ text: message[:content] }]
+        }
+      end
+    end
+
+    def output_as_json_schema(function_schema)
+      json_instruction = <<~PROMPT
+        Generate a JSON object that strictly adheres to the following JSON schema:
+
+        ```json
+        #{JSON.pretty_generate(function_schema[:parameters])}
+        ```
+
+        IMPORTANT: Only output the raw JSON object. Do not include any other text, explanations, or markdown formatting like ```json ... ``` wrappers around the final output.
+      PROMPT
+
+      {
+        role: 'user',
+        parts: [{ text: json_instruction }]
+      }
+    end
+  end
+end

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,98 @@
 require 'json'
 require 'net/http'
 
+require_relative './helpers/retry'
+require_relative './base_client'
+
 module ActiveGenie::Clients
-  class OpenaiClient
-    MAX_RETRIES = 3
-    
-    class OpenaiError < StandardError; end
+  class OpenaiClient < BaseClient
+    class OpenaiError < ClientError; end
     class RateLimitError < OpenaiError; end
+    class InvalidResponseError < StandardError; end
 
     def initialize(config)
-      @app_config = config
+      super(config)
     end
 
+    # Requests structured JSON output from the OpenAI model based on a schema.
+    #
+    # @param messages [Array<Hash>] A list of messages representing the conversation history.
+    #   Each hash should have :role ('user', 'assistant', or 'system') and :content (String).
+    # @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: {
+            **function,
+            parameters: {
+              **function[:parameters],
+              additionalProperties: false
+            },
+            strict: true
+          }.compact
+        }],
+        tool_choice: { type: 'function', function: { name: function[:name] } },
+        stream: false,
         model:,
       }
 
-      api_key = config[:api_key] || @app_config.api_key
-      headers = DEFAULT_HEADERS.merge(
+      api_key = config[:runtime][:api_key] || @app_config.api_key
+      headers = {
         'Authorization': "Bearer #{api_key}"
-      ).compact
+      }.compact
+
+      retry_with_backoff(config:) do
+        response = request_openai(payload, headers, config:)
+
+        parsed_response = JSON.parse(response.dig('choices', 0, 'message', 'tool_calls', 0, 'function', 'arguments'))
+        parsed_response = parsed_response.dig('message') || parsed_response
 
-      response = request(payload, headers, config:)
+        raise InvalidResponseError, "Invalid response: #{parsed_response}" if parsed_response.nil? || parsed_response.keys.size.zero?
 
-      parsed_response = JSON.parse(response.dig('choices', 0, 'message', 'content'))
-      parsed_response.dig('properties') || parsed_response
-    rescue JSON::ParserError
-      nil
+        ActiveGenie::Logger.trace({code: :function_calling, payload:, parsed_response: })
+
+        parsed_response
+      end
     end
 
+
     private
 
-    def request(payload, headers, config:)
-      retries = config[:max_retries] || MAX_RETRIES
+    # Make a request to the OpenAI API
+    #
+    # @param payload [Hash] The request payload
+    # @param headers [Hash] Additional headers
+    # @param config [Hash] Configuration options
+    # @return [Hash] The parsed response
+    def request_openai(payload, headers, config:)
       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
-      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
+      response = post("/chat/completions", payload, headers: headers, config: config)
+
+      return nil if response.nil?
+
+      ActiveGenie::Logger.trace({
+        code: :llm_usage,
+        input_tokens: response.dig('usage', 'prompt_tokens'),
+        output_tokens: response.dig('usage', 'completion_tokens'),
+        total_tokens: response.dig('usage', 'total_tokens'),
+        model: payload[:model],
+        duration: Time.now - start_time,
+        usage: response.dig('usage')
+      })
 
-    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
-        }
-      )
+      response
     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