ruby_llm-agents 0.5.0 → 1.0.0

data/lib/ruby_llm/agents/dsl/caching.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module DSL
+      # Caching DSL for agent response caching.
+      #
+      # This module provides configuration methods for caching features
+      # that can be mixed into any agent class.
+      #
+      # @example Basic usage
+      #   class MyAgent < RubyLLM::Agents::BaseAgent
+      #     extend DSL::Caching
+      #
+      #     cache_for 1.hour
+      #   end
+      #
+      # @example With conditional caching
+      #   class MyAgent < RubyLLM::Agents::BaseAgent
+      #     extend DSL::Caching
+      #
+      #     cache_for 30.minutes
+      #     cache_key_includes :user_id, :query
+      #   end
+      #
+      module Caching
+        # Default cache TTL when none specified
+        DEFAULT_CACHE_TTL = 1.hour
+
+        # @!group Caching DSL
+
+        # Enables caching for this agent with explicit TTL
+        #
+        # This is the preferred method for enabling caching.
+        #
+        # @param ttl [ActiveSupport::Duration] Time-to-live for cached responses
+        # @return [void]
+        # @example
+        #   cache_for 1.hour
+        #   cache_for 30.minutes
+        def cache_for(ttl)
+          @cache_enabled = true
+          @cache_ttl = ttl
+        end
+
+        # Alias for cache_for (for backward compatibility)
+        alias cache cache_for
+
+        # Returns whether caching is enabled for this agent
+        #
+        # Caching IS inherited from parent classes following Ruby patterns.
+        #
+        # @return [Boolean] true if caching is enabled
+        def cache_enabled?
+          return @cache_enabled if defined?(@cache_enabled)
+
+          inherited_cache_enabled
+        end
+
+        # Returns the cache TTL for this agent
+        #
+        # @return [ActiveSupport::Duration] The cache TTL
+        def cache_ttl
+          @cache_ttl || inherited_cache_ttl || DEFAULT_CACHE_TTL
+        end
+
+        # Specifies which parameters should be included in the cache key
+        #
+        # By default, all options except :skip_cache and :dry_run are included.
+        # Use this to explicitly define which parameters affect caching.
+        #
+        # @param keys [Array<Symbol>] Parameter keys to include in cache key
+        # @return [Array<Symbol>, nil] The current cache key includes
+        # @example
+        #   cache_key_includes :user_id, :query, :context
+        def cache_key_includes(*keys)
+          @cache_key_includes = keys.flatten if keys.any?
+          @cache_key_includes || inherited_cache_key_includes
+        end
+
+        # Specifies which parameters should be excluded from the cache key
+        #
+        # @param keys [Array<Symbol>] Parameter keys to exclude from cache key
+        # @return [Array<Symbol>] The current cache key excludes
+        # @example
+        #   cache_key_excludes :timestamp, :request_id
+        def cache_key_excludes(*keys)
+          @cache_key_excludes = keys.flatten if keys.any?
+          @cache_key_excludes || inherited_cache_key_excludes || default_cache_key_excludes
+        end
+
+        # Returns the complete caching configuration hash
+        #
+        # Used by the Cache middleware to get all settings.
+        #
+        # @return [Hash, nil] The caching configuration
+        def caching_config
+          return nil unless cache_enabled?
+
+          {
+            enabled: true,
+            ttl: cache_ttl,
+            key_includes: cache_key_includes,
+            key_excludes: cache_key_excludes
+          }.compact
+        end
+
+        # @!endgroup
+
+        private
+
+        def inherited_cache_enabled
+          return false unless superclass.respond_to?(:cache_enabled?)
+
+          superclass.cache_enabled?
+        end
+
+        def inherited_cache_ttl
+          return nil unless superclass.respond_to?(:cache_ttl)
+
+          superclass.cache_ttl
+        end
+
+        def inherited_cache_key_includes
+          return nil unless superclass.respond_to?(:cache_key_includes)
+
+          superclass.cache_key_includes
+        end
+
+        def inherited_cache_key_excludes
+          return nil unless superclass.respond_to?(:cache_key_excludes)
+
+          superclass.cache_key_excludes
+        end
+
+        def default_cache_key_excludes
+          %i[skip_cache dry_run with]
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/dsl/reliability.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module DSL
+      # Reliability DSL for retries, fallbacks, and circuit breakers.
+      #
+      # This module provides configuration methods for reliability features
+      # that can be mixed into any agent class.
+      #
+      # @example Block-style configuration
+      #   class MyAgent < RubyLLM::Agents::BaseAgent
+      #     extend DSL::Reliability
+      #
+      #     reliability do
+      #       retries max: 3, backoff: :exponential
+      #       fallback_models "gpt-4o-mini"
+      #       total_timeout 30
+      #       circuit_breaker errors: 5, within: 60
+      #     end
+      #   end
+      #
+      # @example Individual method configuration
+      #   class MyAgent < RubyLLM::Agents::BaseAgent
+      #     extend DSL::Reliability
+      #
+      #     retries max: 3
+      #     fallback_models "gpt-4o-mini", "gpt-3.5-turbo"
+      #   end
+      #
+      module Reliability
+        # @!group Reliability DSL
+
+        # Configures reliability features using a block syntax
+        #
+        # Groups all reliability configuration in a single block for clarity.
+        #
+        # @yield Block containing reliability configuration
+        # @return [void]
+        # @example
+        #   reliability do
+        #     retries max: 3, backoff: :exponential
+        #     fallback_models "gpt-4o-mini"
+        #     total_timeout 30
+        #     circuit_breaker errors: 5
+        #   end
+        def reliability(&block)
+          builder = ReliabilityBuilder.new
+          builder.instance_eval(&block)
+
+          @retries_config = builder.retries_config if builder.retries_config
+          @fallback_models = builder.fallback_models_list if builder.fallback_models_list.any?
+          @fallback_providers = builder.fallback_providers_list if builder.fallback_providers_list.any?
+          @total_timeout = builder.total_timeout_value if builder.total_timeout_value
+          @circuit_breaker_config = builder.circuit_breaker_config if builder.circuit_breaker_config
+          @retryable_patterns = builder.retryable_patterns_list if builder.retryable_patterns_list
+        end
+
+        # Returns the complete reliability configuration hash
+        #
+        # Used by the Reliability middleware to get all settings.
+        #
+        # @return [Hash, nil] The reliability configuration
+        def reliability_config
+          return nil unless reliability_configured?
+
+          {
+            retries: retries_config,
+            fallback_models: fallback_models,
+            fallback_providers: fallback_providers,
+            total_timeout: total_timeout,
+            circuit_breaker: circuit_breaker_config,
+            retryable_patterns: retryable_patterns
+          }.compact
+        end
+
+        # Checks if any reliability features are configured
+        #
+        # @return [Boolean] true if reliability is configured
+        def reliability_configured?
+          (retries_config && retries_config[:max]&.positive?) ||
+            fallback_models.any? ||
+            fallback_providers.any? ||
+            circuit_breaker_config.present?
+        end
+
+        # Configures retry behavior for this agent
+        #
+        # @param max [Integer] Maximum number of retry attempts (default: 0)
+        # @param backoff [Symbol] Backoff strategy (:constant or :exponential)
+        # @param base [Float] Base delay in seconds
+        # @param max_delay [Float] Maximum delay between retries
+        # @param on [Array<Class>] Error classes to retry on (extends defaults)
+        # @return [Hash] The current retry configuration
+        # @example
+        #   retries max: 2, backoff: :exponential
+        def retries(max: nil, backoff: nil, base: nil, max_delay: nil, on: nil)
+          if max || backoff || base || max_delay || on
+            @retries_config ||= default_retries_config.dup
+            @retries_config[:max] = max if max
+            @retries_config[:backoff] = backoff if backoff
+            @retries_config[:base] = base if base
+            @retries_config[:max_delay] = max_delay if max_delay
+            @retries_config[:on] = on if on
+          end
+          @retries_config || inherited_retry_config || default_retries_config
+        end
+
+        # Returns the retry configuration
+        #
+        # @return [Hash, nil] The retry configuration
+        def retries_config
+          @retries_config || inherited_retry_config
+        end
+
+        # Sets or returns fallback models to try when primary model fails
+        #
+        # @param models [Array<String>] Model identifiers to use as fallbacks
+        # @return [Array<String>] The current fallback models
+        # @example
+        #   fallback_models "gpt-4o-mini", "gpt-3.5-turbo"
+        def fallback_models(*models)
+          @fallback_models = models.flatten if models.any?
+          @fallback_models || inherited_fallback_models || []
+        end
+
+        # Sets or returns fallback providers to try when primary provider fails
+        #
+        # Used primarily by audio agents (Speaker, Transcriber) that may need
+        # to fall back to a different provider entirely.
+        #
+        # @param provider [Symbol] The provider to fall back to
+        # @param options [Hash] Provider-specific options (e.g., voice:, model:)
+        # @return [Array<Hash>] The current fallback providers
+        # @example
+        #   fallback_provider :openai, voice: "nova"
+        def fallback_provider(provider = nil, **options)
+          if provider
+            @fallback_providers ||= []
+            @fallback_providers << { provider: provider, **options }
+          end
+          @fallback_providers || inherited_fallback_providers || []
+        end
+
+        # Returns the fallback providers list
+        #
+        # @return [Array<Hash>] The fallback providers
+        def fallback_providers
+          @fallback_providers || inherited_fallback_providers || []
+        end
+
+        # Sets or returns the total timeout for all retry/fallback attempts
+        #
+        # @param seconds [Integer, nil] Total timeout in seconds
+        # @return [Integer, nil] The current total timeout
+        # @example
+        #   total_timeout 30
+        def total_timeout(seconds = nil)
+          @total_timeout = seconds if seconds
+          @total_timeout || inherited_total_timeout
+        end
+
+        # Configures circuit breaker for this agent
+        #
+        # @param errors [Integer] Number of errors to trigger open state
+        # @param within [Integer] Rolling window in seconds
+        # @param cooldown [Integer] Cooldown period in seconds when open
+        # @return [Hash, nil] The current circuit breaker configuration
+        # @example
+        #   circuit_breaker errors: 10, within: 60, cooldown: 300
+        def circuit_breaker(errors: nil, within: nil, cooldown: nil)
+          if errors || within || cooldown
+            @circuit_breaker_config ||= { errors: 10, within: 60, cooldown: 300 }
+            @circuit_breaker_config[:errors] = errors if errors
+            @circuit_breaker_config[:within] = within if within
+            @circuit_breaker_config[:cooldown] = cooldown if cooldown
+          end
+          @circuit_breaker_config || inherited_circuit_breaker_config
+        end
+
+        # Returns the circuit breaker configuration
+        #
+        # @return [Hash, nil] The circuit breaker configuration
+        def circuit_breaker_config
+          @circuit_breaker_config || inherited_circuit_breaker_config
+        end
+
+        # Sets or returns additional retryable patterns for error message matching
+        #
+        # @param patterns [Array<String>] Pattern strings to match in error messages
+        # @return [Array<String>, nil] The current retryable patterns
+        # @example
+        #   retryable_patterns "custom_error", "another_pattern"
+        def retryable_patterns(*patterns)
+          @retryable_patterns = patterns.flatten if patterns.any?
+          @retryable_patterns || inherited_retryable_patterns
+        end
+
+        # @!endgroup
+
+        private
+
+        def inherited_retry_config
+          return nil unless superclass.respond_to?(:retries_config)
+
+          superclass.retries_config
+        end
+
+        def inherited_fallback_models
+          return nil unless superclass.respond_to?(:fallback_models)
+
+          superclass.fallback_models
+        end
+
+        def inherited_fallback_providers
+          return nil unless superclass.respond_to?(:fallback_providers)
+
+          superclass.fallback_providers
+        end
+
+        def inherited_total_timeout
+          return nil unless superclass.respond_to?(:total_timeout)
+
+          superclass.total_timeout
+        end
+
+        def inherited_circuit_breaker_config
+          return nil unless superclass.respond_to?(:circuit_breaker_config)
+
+          superclass.circuit_breaker_config
+        end
+
+        def inherited_retryable_patterns
+          return nil unless superclass.respond_to?(:retryable_patterns)
+
+          superclass.retryable_patterns
+        end
+
+        def default_retries_config
+          {
+            max: 0,
+            backoff: :exponential,
+            base: 0.4,
+            max_delay: 3.0,
+            on: []
+          }
+        end
+
+        # Inner builder class for block-style configuration
+        class ReliabilityBuilder
+          attr_reader :retries_config, :fallback_models_list, :total_timeout_value,
+                      :circuit_breaker_config, :retryable_patterns_list, :fallback_providers_list
+
+          def initialize
+            @retries_config = nil
+            @fallback_models_list = []
+            @total_timeout_value = nil
+            @circuit_breaker_config = nil
+            @retryable_patterns_list = nil
+            @fallback_providers_list = []
+          end
+
+          def retries(max: 0, backoff: :exponential, base: 0.4, max_delay: 3.0, on: [])
+            @retries_config = {
+              max: max,
+              backoff: backoff,
+              base: base,
+              max_delay: max_delay,
+              on: on
+            }
+          end
+
+          def fallback_models(*models)
+            @fallback_models_list = models.flatten
+          end
+
+          # Configures a fallback provider with optional settings
+          #
+          # @param provider [Symbol] The provider to fall back to (e.g., :openai, :elevenlabs)
+          # @param options [Hash] Provider-specific options (e.g., voice:, model:)
+          # @example
+          #   fallback_provider :openai, voice: "nova"
+          #   fallback_provider :elevenlabs, voice: "Rachel", model: "eleven_multilingual_v2"
+          def fallback_provider(provider, **options)
+            @fallback_providers_list << { provider: provider, **options }
+          end
+
+          def total_timeout(seconds)
+            @total_timeout_value = seconds
+          end
+
+          def circuit_breaker(errors: 10, within: 60, cooldown: 300)
+            @circuit_breaker_config = {
+              errors: errors,
+              within: within,
+              cooldown: cooldown
+            }
+          end
+
+          def retryable_patterns(*patterns)
+            @retryable_patterns_list = patterns.flatten
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/dsl.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "dsl/base"
+require_relative "dsl/reliability"
+require_relative "dsl/caching"
+
+module RubyLLM
+  module Agents
+    # Domain-Specific Language modules for agent configuration.
+    #
+    # The DSL modules provide a clean, declarative way to configure agents
+    # at the class level. Each module focuses on a specific concern:
+    #
+    # - {DSL::Base} - Core settings (model, version, description, timeout)
+    # - {DSL::Reliability} - Retries, fallbacks, circuit breakers
+    # - {DSL::Caching} - Response caching configuration
+    #
+    # @example Using all DSL modules
+    #   class MyAgent < RubyLLM::Agents::BaseAgent
+    #     extend DSL::Base
+    #     extend DSL::Reliability
+    #     extend DSL::Caching
+    #
+    #     model "gpt-4o"
+    #     version "2.0"
+    #     description "A helpful agent"
+    #     timeout 30
+    #
+    #     reliability do
+    #       retries max: 3, backoff: :exponential
+    #       fallback_models "gpt-4o-mini"
+    #       circuit_breaker errors: 5, within: 60
+    #     end
+    #
+    #     cache_for 1.hour
+    #   end
+    #
+    module DSL
+    end
+  end
+end

data/lib/ruby_llm/agents/image/analyzer/dsl.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative "../concerns/image_operation_dsl"
+
+module RubyLLM
+  module Agents
+    class ImageAnalyzer
+      # DSL for configuring image analyzers
+      #
+      # Provides class-level methods to configure model, analysis type,
+      # and feature extraction options.
+      #
+      # @example
+      #   class ProductAnalyzer < RubyLLM::Agents::ImageAnalyzer
+      #     model "gpt-4o"
+      #     analysis_type :detailed
+      #     extract_colors true
+      #     detect_objects true
+      #     max_tags 20
+      #   end
+      #
+      module DSL
+        include Concerns::ImageOperationDSL
+
+        VALID_ANALYSIS_TYPES = %i[caption detailed tags objects colors all].freeze
+
+        # Set or get the analysis type
+        #
+        # @param value [Symbol, nil] Analysis type (:caption, :detailed, :tags, :objects, :colors, :all)
+        # @return [Symbol] The analysis type
+        def analysis_type(value = nil)
+          if value
+            unless VALID_ANALYSIS_TYPES.include?(value)
+              raise ArgumentError, "Analysis type must be one of: #{VALID_ANALYSIS_TYPES.join(', ')}"
+            end
+            @analysis_type = value
+          else
+            @analysis_type || inherited_or_default(:analysis_type, :detailed)
+          end
+        end
+
+        # Set or get whether to extract colors
+        #
+        # When enabled, extracts dominant colors from the image with
+        # hex values, names, and percentages.
+        #
+        # @param value [Boolean, nil] Enable color extraction
+        # @return [Boolean] Whether color extraction is enabled
+        def extract_colors(value = nil)
+          if value.nil?
+            result = @extract_colors
+            result = inherited_or_default(:extract_colors, false) if result.nil?
+            result
+          else
+            @extract_colors = value
+          end
+        end
+
+        # Set or get whether to detect objects
+        #
+        # When enabled, detects and identifies objects in the image
+        # with bounding boxes and confidence scores.
+        #
+        # @param value [Boolean, nil] Enable object detection
+        # @return [Boolean] Whether object detection is enabled
+        def detect_objects(value = nil)
+          if value.nil?
+            result = @detect_objects
+            result = inherited_or_default(:detect_objects, false) if result.nil?
+            result
+          else
+            @detect_objects = value
+          end
+        end
+
+        # Set or get whether to extract text (OCR)
+        #
+        # When enabled, extracts text visible in the image using OCR.
+        #
+        # @param value [Boolean, nil] Enable text extraction
+        # @return [Boolean] Whether text extraction is enabled
+        def extract_text(value = nil)
+          if value.nil?
+            result = @extract_text
+            result = inherited_or_default(:extract_text, false) if result.nil?
+            result
+          else
+            @extract_text = value
+          end
+        end
+
+        # Set or get a custom analysis prompt
+        #
+        # Allows specifying a custom prompt for the vision model
+        # to customize what information is extracted.
+        #
+        # @param value [String, nil] Custom prompt
+        # @return [String, nil] The custom prompt
+        def custom_prompt(value = nil)
+          if value
+            @custom_prompt = value
+          else
+            @custom_prompt || inherited_or_default(:custom_prompt, nil)
+          end
+        end
+
+        # Set or get maximum number of tags
+        #
+        # @param value [Integer, nil] Maximum tags to return
+        # @return [Integer] The maximum number of tags
+        def max_tags(value = nil)
+          if value
+            unless value.is_a?(Integer) && value > 0
+              raise ArgumentError, "Max tags must be a positive integer"
+            end
+            @max_tags = value
+          else
+            @max_tags || inherited_or_default(:max_tags, 10)
+          end
+        end
+
+        private
+
+        def default_model
+          config.default_analyzer_model || "gpt-4o"
+        end
+      end
+    end
+  end
+end