ruby_llm-agents 0.4.0 → 1.0.0.beta.1

data/lib/ruby_llm/agents/{reliability → infrastructure/reliability}/retry_strategy.rb

@@ -15,19 +15,21 @@ module RubyLLM
       #
       # @api private
       class RetryStrategy
-        attr_reader :max, :backoff, :base, :max_delay, :custom_errors
+        attr_reader :max, :backoff, :base, :max_delay, :custom_errors, :custom_patterns
 
         # @param max [Integer] Maximum retry attempts
         # @param backoff [Symbol] :constant or :exponential
         # @param base [Float] Base delay in seconds
         # @param max_delay [Float] Maximum delay cap
         # @param on [Array<Class>] Additional error classes to retry on
-        def initialize(max: 0, backoff: :exponential, base: 0.4, max_delay: 3.0, on: [])
+        # @param patterns [Array<String>, nil] Additional patterns to match in error messages
+        def initialize(max: 0, backoff: :exponential, base: 0.4, max_delay: 3.0, on: [], patterns: nil)
           @max = max
           @backoff = backoff
           @base = base
           @max_delay = max_delay
           @custom_errors = Array(on)
+          @custom_patterns = patterns
         end
 
         # Determines if retry should occur
@@ -61,7 +63,11 @@ module RubyLLM
         # @param error [Exception] The error to check
         # @return [Boolean] true if retryable
         def retryable?(error)
-          RubyLLM::Agents::Reliability.retryable_error?(error, custom_errors: custom_errors)
+          RubyLLM::Agents::Reliability.retryable_error?(
+            error,
+            custom_errors: custom_errors,
+            custom_patterns: custom_patterns
+          )
         end
 
         # Returns all retryable error classes

data/lib/ruby_llm/agents/{reliability.rb → infrastructure/reliability.rb}

@@ -124,10 +124,12 @@ module RubyLLM
         #
         # @param error [Exception] The error to check
         # @param custom_errors [Array<Class>] Additional error classes to consider retryable
+        # @param custom_patterns [Array<String>, nil] Additional patterns to check in error messages
         # @return [Boolean] true if the error is retryable
-        def retryable_error?(error, custom_errors: [])
+        def retryable_error?(error, custom_errors: [], custom_patterns: nil)
           all_retryable = default_retryable_errors + Array(custom_errors)
-          all_retryable.any? { |klass| error.is_a?(klass) } || retryable_by_message?(error)
+          all_retryable.any? { |klass| error.is_a?(klass) } ||
+            retryable_by_message?(error, custom_patterns: custom_patterns)
         end
 
         # Determines if an error is retryable based on its message content
@@ -136,32 +138,20 @@ module RubyLLM
         # but can be identified by their message.
         #
         # @param error [Exception] The error to check
+        # @param custom_patterns [Array<String>, nil] Additional patterns to check
         # @return [Boolean] true if the error message indicates a retryable condition
-        def retryable_by_message?(error)
+        def retryable_by_message?(error, custom_patterns: nil)
           message = error.message.to_s.downcase
-          retryable_patterns.any? { |pattern| message.include?(pattern) }
+          retryable_patterns(custom_patterns: custom_patterns).any? { |pattern| message.include?(pattern) }
         end
 
         # Patterns in error messages that indicate retryable errors
         #
+        # @param custom_patterns [Array<String>, nil] Additional patterns to include
         # @return [Array<String>] Patterns to match against error messages
-        def retryable_patterns
-          @retryable_patterns ||= [
-            "rate limit",
-            "rate_limit",
-            "too many requests",
-            "429",
-            "500",
-            "502",
-            "503",
-            "504",
-            "service unavailable",
-            "internal server error",
-            "bad gateway",
-            "gateway timeout",
-            "overloaded",
-            "capacity"
-          ].freeze
+        def retryable_patterns(custom_patterns: nil)
+          base = RubyLLM::Agents.configuration.all_retryable_patterns
+          custom_patterns ? (base + Array(custom_patterns)).uniq : base
         end
 
         # Calculates the backoff delay for a retry attempt

data/lib/ruby_llm/agents/pipeline/builder.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Pipeline
+      # Builds the middleware pipeline from agent DSL configuration.
+      #
+      # The builder allows both manual pipeline construction and automatic
+      # construction based on agent DSL settings.
+      #
+      # @example Manual pipeline construction
+      #   builder = Builder.new(MyEmbedder)
+      #   builder.use(Middleware::Tenant)
+      #   builder.use(Middleware::Cache)
+      #   builder.use(Middleware::Instrumentation)
+      #   pipeline = builder.build(core_executor)
+      #
+      # @example Automatic construction from DSL
+      #   pipeline = Builder.for(MyEmbedder).build(core_executor)
+      #
+      # @example With custom middleware insertion
+      #   builder = Builder.for(MyEmbedder)
+      #   builder.insert_before(Middleware::Instrumentation, MyLoggingMiddleware)
+      #   pipeline = builder.build(core_executor)
+      #
+      class Builder
+        # @return [Class] The agent class this builder is for
+        attr_reader :agent_class
+
+        # @return [Array<Class>] The middleware stack (in execution order)
+        attr_reader :stack
+
+        # Creates a new builder for an agent class
+        #
+        # @param agent_class [Class] The agent class
+        def initialize(agent_class)
+          @agent_class = agent_class
+          @stack = []
+        end
+
+        # Add middleware to the end of the stack
+        #
+        # @param middleware_class [Class] Middleware class to add
+        # @return [self] For method chaining
+        def use(middleware_class)
+          @stack << middleware_class
+          self
+        end
+
+        # Insert middleware before another middleware
+        #
+        # @param existing [Class] The middleware to insert before
+        # @param new_middleware [Class] The middleware to insert
+        # @return [self] For method chaining
+        # @raise [ArgumentError] If existing middleware not found
+        def insert_before(existing, new_middleware)
+          index = @stack.index(existing)
+          raise ArgumentError, "#{existing} not found in stack" unless index
+
+          @stack.insert(index, new_middleware)
+          self
+        end
+
+        # Insert middleware after another middleware
+        #
+        # @param existing [Class] The middleware to insert after
+        # @param new_middleware [Class] The middleware to insert
+        # @return [self] For method chaining
+        # @raise [ArgumentError] If existing middleware not found
+        def insert_after(existing, new_middleware)
+          index = @stack.index(existing)
+          raise ArgumentError, "#{existing} not found in stack" unless index
+
+          @stack.insert(index + 1, new_middleware)
+          self
+        end
+
+        # Remove a middleware from the stack
+        #
+        # @param middleware_class [Class] The middleware to remove
+        # @return [self] For method chaining
+        def delete(middleware_class)
+          @stack.delete(middleware_class)
+          self
+        end
+
+        # Build the pipeline, wrapping the core executor
+        #
+        # Middleware is wrapped in reverse order so that the first
+        # middleware in the stack is the outermost wrapper.
+        #
+        # @param core [#call] The core execution logic (usually an Executor)
+        # @return [#call] The complete pipeline
+        def build(core)
+          @stack.reverse.reduce(core) do |app, middleware_class|
+            middleware_class.new(app, @agent_class)
+          end
+        end
+
+        # Returns whether the stack includes a middleware
+        #
+        # @param middleware_class [Class] The middleware class to check
+        # @return [Boolean]
+        def include?(middleware_class)
+          @stack.include?(middleware_class)
+        end
+
+        # Returns the stack as an array (copy)
+        #
+        # @return [Array<Class>]
+        def to_a
+          @stack.dup
+        end
+
+        class << self
+          # Build default pipeline for an agent class
+          #
+          # Reads DSL configuration to determine which middleware to include.
+          # The order is:
+          # 1. Tenant (always - resolves tenant context)
+          # 2. Budget (if enabled - checks budget before execution)
+          # 3. Instrumentation (always - tracks execution, including cache hits)
+          # 4. Cache (if enabled - returns cached results)
+          # 5. Reliability (if enabled - retries and fallbacks)
+          #
+          # Note: Instrumentation must come BEFORE Cache so it can track cache hits.
+          # When Cache returns early on a hit, Instrumentation still sees it.
+          #
+          # @param agent_class [Class] The agent class
+          # @return [Builder] A configured builder
+          def for(agent_class)
+            new(agent_class).tap do |builder|
+              # Always included - tenant resolution
+              builder.use(Middleware::Tenant)
+
+              # Budget checking (if enabled globally)
+              builder.use(Middleware::Budget) if budgets_enabled?
+
+              # Instrumentation (always - for tracking, must be before Cache)
+              builder.use(Middleware::Instrumentation)
+
+              # Caching (if enabled on the agent)
+              builder.use(Middleware::Cache) if cache_enabled?(agent_class)
+
+              # Reliability (if agent has retries or fallbacks configured)
+              builder.use(Middleware::Reliability) if reliability_enabled?(agent_class)
+            end
+          end
+
+          # Returns an empty builder (no middleware)
+          #
+          # Useful for testing or when you want full control.
+          #
+          # @param agent_class [Class] The agent class
+          # @return [Builder] An empty builder
+          def empty(agent_class)
+            new(agent_class)
+          end
+
+          private
+
+          # Check if budgets are enabled globally
+          #
+          # @return [Boolean]
+          def budgets_enabled?
+            RubyLLM::Agents.configuration.budgets_enabled?
+          rescue StandardError
+            false
+          end
+
+          # Check if caching is enabled for an agent
+          #
+          # @param agent_class [Class] The agent class
+          # @return [Boolean]
+          def cache_enabled?(agent_class)
+            return false unless agent_class
+
+            agent_class.respond_to?(:cache_enabled?) && agent_class.cache_enabled?
+          rescue StandardError
+            false
+          end
+
+          # Check if reliability features are enabled for an agent
+          #
+          # An agent has reliability enabled if it has:
+          # - retries > 0, OR
+          # - fallback_models configured
+          #
+          # @param agent_class [Class] The agent class
+          # @return [Boolean]
+          def reliability_enabled?(agent_class)
+            return false unless agent_class
+
+            retries = if agent_class.respond_to?(:retries)
+                        agent_class.retries
+                      else
+                        0
+                      end
+
+            fallbacks = if agent_class.respond_to?(:fallback_models)
+                          agent_class.fallback_models
+                        else
+                          []
+                        end
+
+            (retries.is_a?(Integer) && retries.positive?) ||
+              (fallbacks.is_a?(Array) && fallbacks.any?)
+          rescue StandardError
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/pipeline/context.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Pipeline
+      # Carries request/response data through the middleware pipeline.
+      #
+      # All data flows explicitly through this object - no hidden
+      # instance variables or implicit state. This makes the data flow
+      # visible and testable.
+      #
+      # @example Creating a context
+      #   context = Context.new(
+      #     input: "Hello world",
+      #     agent_class: MyEmbedder,
+      #     model: "text-embedding-3-small"
+      #   )
+      #
+      # @example Accessing data set by middleware
+      #   context.tenant_id          # Set by Tenant middleware
+      #   context.cached?            # Set by Cache middleware
+      #   context.duration_ms        # Computed from timestamps
+      #
+      class Context
+        # Request data
+        attr_accessor :input, :model, :options
+
+        # Agent reference (for execution)
+        attr_accessor :agent_instance
+
+        # Tenant data (set by Tenant middleware, or passed in)
+        attr_accessor :tenant_id, :tenant_object, :tenant_config
+
+        # Execution tracking (set by Instrumentation middleware)
+        attr_accessor :started_at, :completed_at, :attempt, :attempts_made, :execution_id
+
+        # Result data (set by core execute method)
+        attr_accessor :output, :error, :cached
+
+        # Cost tracking
+        attr_accessor :input_tokens, :output_tokens, :input_cost, :output_cost, :total_cost
+
+        # Response metadata
+        attr_accessor :model_used, :finish_reason, :time_to_first_token_ms
+
+        # Streaming support
+        attr_accessor :stream_block, :skip_cache
+
+        # Agent metadata
+        attr_reader :agent_class, :agent_type
+
+        # Creates a new pipeline context
+        #
+        # @param input [Object] The input data for the agent
+        # @param agent_class [Class] The agent class being executed
+        # @param agent_instance [Object, nil] The agent instance
+        # @param model [String, nil] Override model (defaults to agent_class.model)
+        # @param tenant [Hash, Object, nil] Raw tenant (resolved by Tenant middleware)
+        # @param skip_cache [Boolean] Whether to skip caching
+        # @param stream_block [Proc, nil] Block for streaming
+        # @param options [Hash] Additional options passed to the agent
+        def initialize(input:, agent_class:, agent_instance: nil, model: nil, tenant: nil, skip_cache: false, stream_block: nil, **options)
+          @input = input
+          @agent_class = agent_class
+          @agent_instance = agent_instance
+          @agent_type = extract_agent_type(agent_class)
+          @model = model || extract_model(agent_class)
+
+          # Store tenant in options for middleware to resolve
+          @options = options.merge(tenant: tenant).compact
+
+          # Tenant fields (set by Tenant middleware)
+          @tenant_id = nil
+          @tenant_object = nil
+          @tenant_config = nil
+
+          # Execution options
+          @skip_cache = skip_cache
+          @stream_block = stream_block
+
+          # Initialize tracking fields
+          @attempt = 0
+          @attempts_made = 0
+          @cached = false
+          @metadata = {}
+
+          # Initialize cost fields
+          @input_tokens = 0
+          @output_tokens = 0
+          @input_cost = 0.0
+          @output_cost = 0.0
+          @total_cost = 0.0
+        end
+
+        # Duration in milliseconds
+        #
+        # @return [Integer, nil] Duration in ms, or nil if not yet completed
+        def duration_ms
+          return nil unless @started_at && @completed_at
+
+          ((@completed_at - @started_at) * 1000).to_i
+        end
+
+        # Was the result served from cache?
+        #
+        # @return [Boolean]
+        def cached?
+          @cached == true
+        end
+
+        # Did execution succeed?
+        #
+        # @return [Boolean]
+        def success?
+          @error.nil? && !@output.nil?
+        end
+
+        # Did execution fail?
+        #
+        # @return [Boolean]
+        def failed?
+          !@error.nil?
+        end
+
+        # Total tokens used (input + output)
+        #
+        # @return [Integer]
+        def total_tokens
+          (@input_tokens || 0) + (@output_tokens || 0)
+        end
+
+        # Custom metadata storage - read
+        #
+        # @param key [Symbol, String] The metadata key
+        # @return [Object] The stored value
+        def [](key)
+          @metadata[key]
+        end
+
+        # Custom metadata storage - write
+        #
+        # @param key [Symbol, String] The metadata key
+        # @param value [Object] The value to store
+        def []=(key, value)
+          @metadata[key] = value
+        end
+
+        # Returns all custom metadata
+        #
+        # @return [Hash] The metadata hash
+        def metadata
+          @metadata.dup
+        end
+
+        # Convert to hash for logging/recording
+        #
+        # @return [Hash] Hash representation of the context
+        def to_h
+          {
+            agent_class: @agent_class&.name,
+            agent_type: @agent_type,
+            model: @model,
+            model_used: @model_used,
+            tenant_id: @tenant_id,
+            duration_ms: duration_ms,
+            cached: cached?,
+            success: success?,
+            input_tokens: @input_tokens,
+            output_tokens: @output_tokens,
+            total_tokens: total_tokens,
+            input_cost: @input_cost,
+            output_cost: @output_cost,
+            total_cost: @total_cost,
+            finish_reason: @finish_reason,
+            time_to_first_token_ms: @time_to_first_token_ms,
+            attempts_made: @attempts_made,
+            error_class: @error&.class&.name,
+            error_message: @error&.message
+          }.compact
+        end
+
+        # Creates a duplicate context for retry attempts
+        #
+        # @return [Context] A new context with the same input but reset state
+        def dup_for_retry
+          # Extract tenant from options since dup_for_retry is called after middleware
+          # has already resolved it - we want to preserve the resolved state
+          opts_without_tenant = @options.except(:tenant)
+
+          new_ctx = self.class.new(
+            input: @input,
+            agent_class: @agent_class,
+            agent_instance: @agent_instance,
+            model: @model,
+            skip_cache: @skip_cache,
+            stream_block: @stream_block,
+            **opts_without_tenant
+          )
+          # Preserve resolved tenant state
+          new_ctx.tenant_id = @tenant_id
+          new_ctx.tenant_object = @tenant_object
+          new_ctx.tenant_config = @tenant_config
+          new_ctx.started_at = @started_at
+          new_ctx.attempts_made = @attempts_made
+          new_ctx
+        end
+
+        private
+
+        # Extracts agent_type from the agent class
+        #
+        # @param agent_class [Class] The agent class
+        # @return [Symbol, nil] The agent type
+        def extract_agent_type(agent_class)
+          return nil unless agent_class
+
+          if agent_class.respond_to?(:agent_type)
+            agent_class.agent_type
+          else
+            # Infer from class name as fallback
+            infer_agent_type(agent_class)
+          end
+        end
+
+        # Infers agent type from class name
+        #
+        # @param agent_class [Class] The agent class
+        # @return [Symbol] The inferred agent type
+        def infer_agent_type(agent_class)
+          name = agent_class.name.to_s.split("::").last.to_s.downcase
+
+          case name
+          when /embed/ then :embedding
+          when /image/, /generator/, /analyzer/, /editor/, /transform/, /upscale/, /variat/, /background/
+            :image
+          when /transcrib/, /speak/ then :audio
+          when /moderat/ then :moderation
+          else :conversation
+          end
+        end
+
+        # Extracts model from agent class
+        #
+        # @param agent_class [Class] The agent class
+        # @return [String, nil] The model identifier
+        def extract_model(agent_class)
+          return nil unless agent_class
+          return agent_class.model if agent_class.respond_to?(:model)
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/pipeline/executor.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Pipeline
+      # Wraps an agent's execute method to work with the pipeline.
+      #
+      # This is the "core" that middleware wraps around. It's the final
+      # handler in the chain that actually performs the agent's work.
+      #
+      # The Executor adapts the agent's #execute method to the middleware
+      # interface (call(context) -> context).
+      #
+      # @example Basic usage
+      #   executor = Executor.new(agent)
+      #   context = Context.new(input: "hello", agent_class: MyAgent)
+      #   result_context = executor.call(context)
+      #
+      # @example With pipeline
+      #   pipeline = Builder.for(MyAgent).build(Executor.new(agent))
+      #   result = pipeline.call(context)
+      #
+      # @example Convenience class method
+      #   result_context = Executor.execute(context)
+      #
+      class Executor
+        # Execute a context through the full pipeline
+        #
+        # Builds the middleware stack based on the agent's configuration,
+        # then executes the context through it.
+        #
+        # @param context [Context] The execution context
+        # @return [Context] The context with output set
+        def self.execute(context)
+          agent_instance = context.agent_instance
+          core = new(agent_instance)
+          pipeline = Builder.for(context.agent_class).build(core)
+          pipeline.call(context)
+        end
+
+        # @param agent [Object] The agent instance with an #execute method
+        def initialize(agent)
+          @agent = agent
+        end
+
+        # Execute the agent's core logic
+        #
+        # Calls the agent's #execute method with the context.
+        # The agent is expected to set context.output with the result.
+        #
+        # @param context [Context] The execution context
+        # @return [Context] The context with output set
+        def call(context)
+          @agent.execute(context)
+          context
+        end
+      end
+
+      # Lambda-based executor for simple cases
+      #
+      # Allows wrapping a lambda/proc as the core executor,
+      # useful for testing or simple agents.
+      #
+      # @example
+      #   executor = LambdaExecutor.new(->(ctx) {
+      #     ctx.output = "Hello, #{ctx.input}!"
+      #   })
+      #
+      class LambdaExecutor
+        # @param callable [#call] A lambda/proc that takes a context
+        def initialize(callable)
+          @callable = callable
+        end
+
+        # Execute the lambda with the context
+        #
+        # @param context [Context] The execution context
+        # @return [Context] The context (possibly modified by the lambda)
+        def call(context)
+          @callable.call(context)
+          context
+        end
+      end
+    end
+  end
+end