ace-llm 0.30.0

data/lib/ace/llm/atoms/env_reader.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Ace
+  module LLM
+    module Atoms
+      # EnvReader provides environment variable reading utilities
+      # This is an atom - it has no dependencies on other parts of this gem
+      class EnvReader
+        # [DEPRECATED] Use Ace::Core.get_env instead
+        # Load .env files from .ace cascade
+        # @deprecated Use Ace::Core.get_env for individual keys
+        # @param set_env [Boolean] Whether to set loaded vars to ENV
+        # @return [Hash] All loaded environment variables
+        def self.load_env_cascade(set_env: false)
+          return {} unless defined?(Ace::Core)
+
+          warn "[DEPRECATION] EnvReader.load_env_cascade is deprecated. Use Ace::Core.get_env instead" if ENV["DEBUG"]
+
+          # Delegate to ace-core
+          loaded_vars = Ace::Core::Molecules::EnvLoader.load_cascade
+
+          if set_env
+            Ace::Core::Molecules::EnvLoader.set_environment(loaded_vars, overwrite: true)
+          end
+
+          loaded_vars
+        end
+
+        # Get an environment variable value
+        # @param key [String] Environment variable name
+        # @param default [String, nil] Default value if not found
+        # @return [String, nil] The environment variable value or default
+        def self.get(key, default = nil)
+          ENV.fetch(key, default)
+        end
+
+        # Get an environment variable value, raising if not found
+        # @param key [String] Environment variable name
+        # @return [String] The environment variable value
+        # @raise [KeyError] If the environment variable is not set
+        def self.get!(key)
+          ENV.fetch(key)
+        rescue KeyError
+          raise KeyError, "Environment variable '#{key}' is not set"
+        end
+
+        # Check if an environment variable is set
+        # @param key [String] Environment variable name
+        # @return [Boolean] True if the variable is set, false otherwise
+        def self.set?(key)
+          ENV.key?(key)
+        end
+
+        # Check if an environment variable is set and not empty
+        # @param key [String] Environment variable name
+        # @return [Boolean] True if the variable is set and not empty
+        def self.present?(key)
+          value = ENV[key]
+          !value.nil? && !value.strip.empty?
+        end
+
+        # Get multiple environment variables as a hash
+        # @param keys [Array<String>] List of environment variable names
+        # @param prefix [String, nil] Optional prefix to prepend to each key
+        # @return [Hash<String, String>] Hash of key-value pairs (only includes set variables)
+        def self.get_multiple(keys, prefix: nil)
+          keys.each_with_object({}) do |key, hash|
+            full_key = prefix ? "#{prefix}#{key}" : key
+            value = ENV[full_key]
+            hash[key] = value if value
+          end
+        end
+
+        # Get all environment variables matching a pattern
+        # @param pattern [Regexp, String] Pattern to match (String will be used as prefix)
+        # @return [Hash<String, String>] Matching environment variables
+        def self.get_matching(pattern)
+          pattern = /^#{Regexp.escape(pattern)}/ if pattern.is_a?(String)
+
+          ENV.select { |key, _| key =~ pattern }
+        end
+
+        # Temporarily set environment variables for a block
+        # @param vars [Hash<String, String>] Variables to set temporarily
+        # @yield Block to execute with temporary variables
+        # @return [Object] The return value of the block
+        def self.with_env(vars)
+          original_values = {}
+
+          # Store original values and set new ones
+          vars.each do |key, value|
+            original_values[key] = ENV[key]
+            if value.nil?
+              ENV.delete(key)
+            else
+              ENV[key] = value.to_s
+            end
+          end
+
+          yield
+        ensure
+          # Restore original values
+          original_values.each do |key, value|
+            if value.nil?
+              ENV.delete(key)
+            else
+              ENV[key] = value
+            end
+          end
+        end
+
+        # Get API key for a provider from environment
+        # Uses ace-core to check ENV and .ace/.env cascade
+        # @param provider [String] Provider name (e.g., "google", "openai")
+        # @return [String, nil] API key if found
+        def self.get_api_key(provider)
+          # Determine which keys to look for based on provider
+          key_names = case provider.downcase
+          when "google", "gemini"
+            ["GEMINI_API_KEY", "GOOGLE_API_KEY"]
+          when "groq"
+            ["GROQ_API_KEY"]
+          when "openai"
+            ["OPENAI_API_KEY"]
+          when "anthropic"
+            ["ANTHROPIC_API_KEY"]
+          when "mistral"
+            ["MISTRAL_API_KEY"]
+          when "together", "togetherai"
+            ["TOGETHER_API_KEY", "TOGETHERAI_API_KEY"]
+          when "lmstudio"
+            return nil # No API key needed for local
+          when "xai"
+            ["XAI_API_KEY"]
+          when "openrouter"
+            ["OPENROUTER_API_KEY"]
+          else
+            # Try generic pattern
+            ["#{provider.upcase}_API_KEY"]
+          end
+
+          # Use ace-core to check each key (it checks ENV first, then cascade)
+          return nil unless defined?(Ace::Core)
+
+          key_names.each do |key_name|
+            value = Ace::Core.get_env(key_name)
+            return value if value && !value.strip.empty?
+          end
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ace/llm/atoms/error_classifier.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Ace
+  module LLM
+    module Atoms
+      # ErrorClassifier categorizes errors to determine retry and fallback strategies
+      # This is an atom - it has no dependencies on other parts of this gem
+      class ErrorClassifier
+        # Error classification types
+        RETRYABLE_WITH_BACKOFF = :retryable_with_backoff
+        FALLBACK_IMMEDIATELY = :fallback_immediately
+        SKIP_TO_NEXT = :skip_to_next
+        TERMINAL = :terminal
+
+        # Map HTTP status codes to classification
+        STATUS_CLASSIFICATIONS = {
+          401 => SKIP_TO_NEXT,      # Unauthorized - skip to next provider
+          403 => SKIP_TO_NEXT,      # Forbidden - skip to next provider
+          404 => SKIP_TO_NEXT,      # Not Found - skip to next provider
+          429 => RETRYABLE_WITH_BACKOFF, # Rate Limited - retry with backoff
+          500 => RETRYABLE_WITH_BACKOFF, # Internal Server Error - retry
+          502 => RETRYABLE_WITH_BACKOFF, # Bad Gateway - retry
+          503 => RETRYABLE_WITH_BACKOFF, # Service Unavailable - retry
+          504 => RETRYABLE_WITH_BACKOFF  # Gateway Timeout - retry
+        }.freeze
+
+        QUOTA_LIMIT_PATTERNS = [
+          "insufficient_quota",
+          "insufficient quota",
+          "quota exceeded",
+          "quota has been exceeded",
+          "quota limit",
+          "quota exhausted",
+          "out of credit",
+          "credits exhausted",
+          "insufficient credit",
+          "billing hard limit",
+          "spending limit",
+          "usage limit reached",
+          "rate window limit",
+          "window limit reached"
+        ].freeze
+
+        # Classify an error for retry/fallback decisions
+        # @param error [Exception] The error to classify
+        # @return [Symbol] Classification type (RETRYABLE_WITH_BACKOFF, FALLBACK_IMMEDIATELY, SKIP_TO_NEXT, TERMINAL)
+        def self.classify(error)
+          case error
+          when Ace::LLM::AuthenticationError
+            SKIP_TO_NEXT
+          when Ace::LLM::ProviderError
+            # Check if we can extract HTTP status from the error message
+            classify_provider_error(error)
+          when Faraday::TimeoutError
+            FALLBACK_IMMEDIATELY
+          when Faraday::ConnectionFailed
+            RETRYABLE_WITH_BACKOFF
+          when Faraday::ClientError
+            classify_faraday_error(error)
+          when Faraday::ServerError
+            RETRYABLE_WITH_BACKOFF
+          else
+            TERMINAL
+          end
+        end
+
+        # Determine if an error is retryable
+        # @param error [Exception] The error to check
+        # @return [Boolean] True if error should be retried
+        def self.retryable?(error)
+          classification = classify(error)
+          classification == RETRYABLE_WITH_BACKOFF
+        end
+
+        # Determine if an error should trigger immediate fallback
+        # @param error [Exception] The error to check
+        # @return [Boolean] True if should fallback immediately
+        def self.fallback_immediately?(error)
+          classification = classify(error)
+          classification == FALLBACK_IMMEDIATELY
+        end
+
+        # Determine if an error should skip to next provider without retry
+        # @param error [Exception] The error to check
+        # @return [Boolean] True if should skip to next provider
+        def self.skip_to_next?(error)
+          classification = classify(error)
+          classification == SKIP_TO_NEXT
+        end
+
+        # Determine if an error indicates quota/credit/window exhaustion
+        # and should move immediately to the next provider.
+        # @param error [Exception] The error to check
+        # @return [Boolean] True if this is a quota/credit/window-limit condition
+        def self.quota_or_credit_limited?(error)
+          quota_like_message?(error.message.to_s)
+        end
+
+        # Extract HTTP status code from various error types
+        # @param error [Exception] The error
+        # @return [Integer, nil] HTTP status code if available
+        def self.extract_status_code(error)
+          if error.respond_to?(:response) && error.response
+            error.response[:status]
+          elsif error.respond_to?(:http_status)
+            error.http_status
+          elsif error.is_a?(Ace::LLM::ProviderError)
+            # Try to parse status from error message like "error (503):"
+            match = error.message.match(/\((\d{3})\)/)
+            match[1].to_i if match
+          end
+        end
+
+        # Get retry delay for an error based on retry-after header or default
+        # @param error [Exception] The error
+        # @param attempt [Integer] Current retry attempt number
+        # @param base_delay [Float] Base delay in seconds
+        # @return [Float] Delay in seconds with jitter
+        def self.retry_delay(error, attempt: 1, base_delay: 1.0)
+          # Check for retry-after header (for 429 rate limits)
+          if error.respond_to?(:response) && error.response
+            headers = error.response[:headers]
+            if headers && headers["retry-after"]
+              return parse_retry_after(headers["retry-after"])
+            end
+          end
+
+          # Exponential backoff with jitter: base_delay * 2^(attempt - 1) * (1 + jitter)
+          # Jitter is 10-30% to prevent thundering herd
+          exponential_delay = base_delay * (2**(attempt - 1))
+          jitter = rand(0.1..0.3)
+          exponential_delay * (1 + jitter)
+        end
+
+        # Classify a Faraday::ClientError based on status code
+        # @param error [Faraday::ClientError] The error
+        # @return [Symbol] Classification type
+        def self.classify_faraday_error(error)
+          status = extract_status_code(error)
+          if status == 429 && quota_like_message?(error.message.to_s)
+            return FALLBACK_IMMEDIATELY
+          end
+
+          STATUS_CLASSIFICATIONS.fetch(status, TERMINAL)
+        end
+        private_class_method :classify_faraday_error
+
+        # Classify a ProviderError based on its message/attributes
+        # @param error [Ace::LLM::ProviderError] The error
+        # @return [Symbol] Classification type
+        def self.classify_provider_error(error)
+          message = error.message.downcase
+          return FALLBACK_IMMEDIATELY if quota_like_message?(message)
+
+          status = extract_status_code(error)
+          return STATUS_CLASSIFICATIONS.fetch(status, TERMINAL) if status
+
+          # Check error message patterns
+          if message.include?("timeout")
+            FALLBACK_IMMEDIATELY
+          elsif message.include?("rate limit")
+            RETRYABLE_WITH_BACKOFF
+          elsif message.include?("connection failed")
+            RETRYABLE_WITH_BACKOFF
+          elsif message.include?("unavailable") || message.include?("overloaded")
+            RETRYABLE_WITH_BACKOFF
+          else
+            TERMINAL
+          end
+        end
+        private_class_method :classify_provider_error
+
+        def self.quota_like_message?(message)
+          normalized = message.to_s.downcase
+          QUOTA_LIMIT_PATTERNS.any? { |pattern| normalized.include?(pattern) }
+        end
+        private_class_method :quota_like_message?
+
+        # Parse retry-after header value
+        # @param value [String] Header value (seconds or HTTP date)
+        # @return [Float] Delay in seconds
+        def self.parse_retry_after(value)
+          # Try to parse as integer (seconds)
+          Integer(value).to_f
+        rescue ArgumentError
+          # Try to parse as HTTP date
+          begin
+            retry_time = Time.httpdate(value)
+            delay = retry_time - Time.now
+            [delay, 0].max # Don't return negative delays
+          rescue ArgumentError
+            # Default fallback if parsing fails
+            1.0
+          end
+        end
+        private_class_method :parse_retry_after
+      end
+    end
+  end
+end

data/lib/ace/llm/atoms/http_client.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Ace
+  module LLM
+    module Atoms
+      # HTTPClient provides basic HTTP operations using Faraday
+      # This is an atom - it has no dependencies on other parts of this gem
+      class HTTPClient
+        # @param options [Hash] Configuration options
+        # @option options [Integer] :timeout (30) Request timeout in seconds
+        # @option options [Integer] :open_timeout (10) Connection open timeout in seconds
+        # @option options [Integer] :max_retries (3) Maximum number of retries
+        # @option options [Array<Integer>] :retry_statuses ([429, 500, 502, 503, 504]) Status codes to retry
+        # @option options [Float] :retry_delay (1.0) Initial retry delay in seconds
+        def initialize(options = {})
+          @timeout = options.fetch(:timeout, 30).to_i
+          @open_timeout = options.fetch(:open_timeout, 10).to_i
+          @max_retries = options.fetch(:max_retries, 3).to_i
+          @retry_statuses = options.fetch(:retry_statuses, [429, 500, 502, 503, 504])
+          @retry_delay = options.fetch(:retry_delay, 1.0).to_f
+        end
+
+        # Perform a GET request
+        # @param url [String] The URL to request
+        # @param options [Hash] Options hash
+        # @option options [Hash] :params ({}) Query parameters
+        # @option options [Hash] :headers ({}) Request headers
+        # @return [Faraday::Response] The response object
+        def get(url, **options)
+          params = options.fetch(:params, {})
+          headers = options.fetch(:headers, {})
+
+          execute_with_retry do
+            connection(url).get do |req|
+              req.params = params unless params.empty?
+              req.headers.merge!(headers) unless headers.empty?
+            end
+          end
+        end
+
+        # Perform a POST request
+        # @param url [String] The URL to request
+        # @param body [String, Hash, nil] Request body (Hash will be JSON-encoded)
+        # @param options [Hash] Options hash
+        # @option options [Hash] :headers ({}) Request headers
+        # @return [Faraday::Response] The response object
+        def post(url, body = nil, **options)
+          headers = options.fetch(:headers, {})
+
+          execute_with_retry do
+            connection(url).post do |req|
+              req.body = body
+              req.headers.merge!(headers) unless headers.empty?
+            end
+          end
+        end
+
+        # Perform a PUT request
+        # @param url [String] The URL to request
+        # @param body [String, Hash, nil] Request body
+        # @param options [Hash] Options hash
+        # @option options [Hash] :headers ({}) Request headers
+        # @return [Faraday::Response] The response object
+        def put(url, body = nil, **options)
+          headers = options.fetch(:headers, {})
+
+          execute_with_retry do
+            connection(url).put do |req|
+              req.body = body
+              req.headers.merge!(headers) unless headers.empty?
+            end
+          end
+        end
+
+        # Perform a DELETE request
+        # @param url [String] The URL to request
+        # @param options [Hash] Options hash
+        # @option options [Hash] :params ({}) Query parameters
+        # @option options [Hash] :headers ({}) Request headers
+        # @return [Faraday::Response] The response object
+        def delete(url, **options)
+          params = options.fetch(:params, {})
+          headers = options.fetch(:headers, {})
+
+          execute_with_retry do
+            connection(url).delete do |req|
+              req.params = params unless params.empty?
+              req.headers.merge!(headers) unless headers.empty?
+            end
+          end
+        end
+
+        private
+
+        # Create a Faraday connection for the given URL
+        # @param url [String] The base URL
+        # @return [Faraday::Connection] Configured connection
+        def connection(url)
+          Faraday.new(url: url) do |faraday|
+            faraday.options.timeout = @timeout
+            faraday.options.open_timeout = @open_timeout
+
+            # Middleware to automatically encode request bodies as JSON
+            faraday.request :json
+
+            # Middleware to automatically parse JSON responses
+            # Pattern matches: application/json, application/json; charset=utf-8, text/json, etc.
+            faraday.response :json, content_type: /\bjson\b/
+
+            # Use the default adapter
+            faraday.adapter Faraday.default_adapter
+          end
+        end
+
+        # Execute a block with retry logic
+        # @yield The block to execute
+        # @return The result of the block
+        def execute_with_retry
+          retries = 0
+          delay = @retry_delay
+
+          begin
+            yield
+          rescue Faraday::Error => e
+            if should_retry?(e, retries)
+              retries += 1
+              sleep(delay)
+              delay *= 2 # Exponential backoff
+              retry
+            else
+              raise
+            end
+          end
+        end
+
+        # Determine if a request should be retried
+        # @param error [Faraday::Error] The error that occurred
+        # @param retries [Integer] Number of retries so far
+        # @return [Boolean] Whether to retry
+        def should_retry?(error, retries)
+          return false if retries >= @max_retries
+
+          # Check if it's a timeout error
+          return true if error.is_a?(Faraday::TimeoutError)
+
+          # Check if it's a connection error
+          return true if error.is_a?(Faraday::ConnectionFailed)
+
+          # Check if it's a retriable status code
+          if error.respond_to?(:response) && error.response
+            status = error.response[:status]
+            return @retry_statuses.include?(status)
+          end
+
+          false
+        end
+      end
+    end
+  end
+end