ruby_llm-agents 0.3.5 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6dbcf1c63db9bd3aad406eaa802c632f932f7dc5ebe0eaf2cbec51c492cf89ed
-  data.tar.gz: 4b6b7d2c440371147c9e754a91f86fb5712aa388584d7f6bef9204f1c10c49b6
+  metadata.gz: 3d8bfa346ee4010060508948c994bc719f5f1ff40dd2eec3aeb04500f2054341
+  data.tar.gz: 5546ca87104e12ba0522c2a6161ed2917355fb6fffcc7cc6dffd9920963b1037
 SHA512:
-  metadata.gz: da89ade6f5a60c77253c7a9647447085632126dfc4d231aa7afec1eca6dc3a82abe5850575db7fb1c23ca71708bf685d74dc138c9b5a277b5f760377e664aec7
-  data.tar.gz: f9551e2dc805d7d76ea42d90098a863bc6abe3451801ab8c893696dd4662c8fc804b4820d3dbb61feb9c90a42d7a0111ab1e2440b94a419df4ef78818ea981a2
+  metadata.gz: 391c1202b7bb677337329b5bd5358e9cb5bc4589d37cf48291bb4ff427d8ba1e3e7db99e8787d079ecd2f08382a4aa9940c573ad33c3be2040aa2e6ec21eb353
+  data.tar.gz: 9b1ae37b9ca74f060377d32232a9c26a33e411d285ac658be9508348d75316582aa47e309b85c3258fcaf33a1d5e103fdef2aa1090569b86140b046ee7e975fc

data/app/controllers/ruby_llm/agents/agents_controller.rb

@@ -58,7 +58,7 @@ module RubyLLM
       #
       # @return [void]
       def show
-        @agent_type = params[:id]
+        @agent_type = CGI.unescape(params[:id])
         @agent_class = AgentRegistry.find(@agent_type)
         @agent_active = @agent_class.present?
 
@@ -215,6 +215,7 @@ module RubyLLM
           model: @agent_class.model,
           temperature: @agent_class.temperature,
           version: @agent_class.version,
+          description: @agent_class.respond_to?(:description) ? @agent_class.description : nil,
           timeout: @agent_class.timeout,
           cache_enabled: @agent_class.cache_enabled?,
           cache_ttl: @agent_class.cache_ttl,

data/app/services/ruby_llm/agents/agent_registry.rb

@@ -140,6 +140,7 @@ module RubyLLM
             workflow_type: workflow_type,
             workflow_children: workflow_children,
             version: safe_call(agent_class, :version) || "N/A",
+            description: safe_call(agent_class, :description),
             model: safe_call(agent_class, :model) || (is_workflow ? "workflow" : "N/A"),
             temperature: safe_call(agent_class, :temperature),
             timeout: safe_call(agent_class, :timeout),

data/app/views/ruby_llm/agents/agents/_agent.html.erb

@@ -1,10 +1,14 @@
-<%= link_to ruby_llm_agents.agent_path(agent[:name]), class: "block bg-white dark:bg-gray-800 rounded-lg shadow hover:shadow-md transition-shadow" do %>
+<%= link_to ruby_llm_agents.agent_path(ERB::Util.url_encode(agent[:name])), class: "block bg-white dark:bg-gray-800 rounded-lg shadow hover:shadow-md transition-shadow" do %>
   <div class="p-4 sm:p-5">
     <!-- Row 1: Agent name + badge + model/timestamp -->
     <div class="flex items-center justify-between gap-2">
       <div class="flex items-center gap-2 min-w-0">
         <h3 class="font-semibold text-gray-900 dark:text-gray-100 truncate">
-          <%= agent[:name].gsub(/Agent$/, '') %>
+          <% name_parts = agent[:name].gsub(/Agent$/, '').split('::') %>
+          <% if name_parts.length > 1 %>
+            <span class="text-gray-400 dark:text-gray-500 font-normal"><%= name_parts[0..-2].join('::') %>::</span>
+          <% end %>
+          <%= name_parts.last %>
         </h3>
         <span class="hidden sm:inline text-sm text-gray-500 dark:text-gray-400">v<%= agent[:version] %></span>
         <% if agent[:active] %>
@@ -25,6 +29,13 @@
       </span>
     </div>
 
+    <!-- Description -->
+    <% if agent[:description].present? %>
+      <p class="mt-1 text-sm text-gray-500 dark:text-gray-400 line-clamp-2">
+        <%= agent[:description] %>
+      </p>
+    <% end %>
+
     <!-- Row 2: Stats -->
     <div class="mt-2 sm:mt-3 sm:border-t sm:border-gray-100 sm:dark:border-gray-700 sm:pt-3">
       <!-- Mobile: compact inline -->

data/app/views/ruby_llm/agents/agents/_workflow.html.erb

@@ -15,13 +15,17 @@
 %>
 
 <div x-data="{ expanded: false }" class="block bg-white dark:bg-gray-800 rounded-lg shadow hover:shadow-md transition-shadow border-l-4 <%= colors[:border] %>">
-  <%= link_to ruby_llm_agents.agent_path(workflow[:name]), class: "block p-4 sm:p-5" do %>
+  <%= link_to ruby_llm_agents.agent_path(ERB::Util.url_encode(workflow[:name])), class: "block p-4 sm:p-5" do %>
     <!-- Header Row -->
     <div class="flex items-center justify-between gap-2">
       <div class="flex items-center gap-2 min-w-0">
         <%= render "ruby_llm/agents/shared/workflow_type_badge", workflow_type: workflow[:workflow_type], size: :sm %>
         <h3 class="font-semibold text-gray-900 dark:text-gray-100 truncate">
-          <%= workflow[:name].gsub(/Workflow$/, '').gsub(/Pipeline$|Parallel$|Router$/, '') %>
+          <% name_parts = workflow[:name].gsub(/Workflow$/, '').gsub(/Pipeline$|Parallel$|Router$/, '').split('::') %>
+          <% if name_parts.length > 1 %>
+            <span class="text-gray-400 dark:text-gray-500 font-normal"><%= name_parts[0..-2].join('::') %>::</span>
+          <% end %>
+          <%= name_parts.last %>
         </h3>
         <span class="hidden sm:inline text-sm text-gray-500 dark:text-gray-400">v<%= workflow[:version] %></span>
         <% if workflow[:active] %>
@@ -35,6 +39,13 @@
       </span>
     </div>
 
+    <!-- Description -->
+    <% if workflow[:description].present? %>
+      <p class="mt-1 text-sm text-gray-500 dark:text-gray-400 line-clamp-2">
+        <%= workflow[:description] %>
+      </p>
+    <% end %>
+
     <!-- Stats Row -->
     <div class="mt-2 sm:mt-3 sm:border-t sm:border-gray-100 sm:dark:border-gray-700 sm:pt-3">
       <% success_rate = workflow[:success_rate] || 0 %>

data/app/views/ruby_llm/agents/agents/show.html.erb

@@ -45,6 +45,11 @@
           <%= @config[:model] %> &middot; temp <%= @config[:temperature] %>
           &middot; timeout <%= @config[:timeout] %>s
         </p>
+        <% if @config[:description].present? %>
+          <p class="text-gray-600 dark:text-gray-300 mt-2">
+            <%= @config[:description] %>
+          </p>
+        <% end %>
       <% end %>
     </div>
 

data/lib/generators/ruby_llm_agents/agent_generator.rb

@@ -29,16 +29,21 @@ module RubyLlmAgents
                  desc: "Cache TTL (e.g., '1.hour', '30.minutes')"
 
     def create_agent_file
-      template "agent.rb.tt", "app/agents/#{file_name}_agent.rb"
+      # Support nested paths: "chat/support" -> "app/agents/chat/support_agent.rb"
+      # Rails' class_name handles namespacing: "chat/support" -> "Chat::Support"
+      agent_path = name.underscore
+      template "agent.rb.tt", "app/agents/#{agent_path}_agent.rb"
     end
 
     def show_usage
+      # Build full class name from path (e.g., "chat/support" -> "Chat::Support")
+      full_class_name = name.split('/').map(&:camelize).join("::")
       say ""
-      say "Agent #{class_name}Agent created!", :green
+      say "Agent #{full_class_name}Agent created!", :green
       say ""
       say "Usage:"
-      say "  #{class_name}Agent.call(#{usage_params})"
-      say "  #{class_name}Agent.call(#{usage_params}, dry_run: true)"
+      say "  #{full_class_name}Agent.call(#{usage_params})"
+      say "  #{full_class_name}Agent.call(#{usage_params}, dry_run: true)"
       say ""
     end
 

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "reliability_dsl"
+
 module RubyLLM
   module Agents
     class Base
@@ -48,6 +50,17 @@ module RubyLLM
           @version || inherited_or_default(:version, VERSION)
         end
 
+        # Sets or returns the description for this agent class
+        #
+        # @param value [String, nil] The description text
+        # @return [String, nil] The current description
+        # @example
+        #   description "Searches the knowledge base for relevant documents"
+        def description(value = nil)
+          @description = value if value
+          @description || inherited_or_default(:description, nil)
+        end
+
         # Sets or returns the timeout in seconds for LLM requests
         #
         # @param value [Integer, nil] Timeout in seconds
@@ -63,6 +76,31 @@ module RubyLLM
 
         # @!group Reliability DSL
 
+        # Configures reliability features using a block syntax
+        #
+        # Groups all reliability configuration in a single block for clarity.
+        # Individual methods (retries, fallback_models, etc.) remain available
+        # for backward compatibility.
+        #
+        # @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 = ReliabilityDSL.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?
+          @total_timeout = builder.total_timeout_value if builder.total_timeout_value
+          @circuit_breaker_config = builder.circuit_breaker_config if builder.circuit_breaker_config
+        end
+
         # Configures retry behavior for this agent
         #
         # @param max [Integer] Maximum number of retry attempts (default: 0)
@@ -151,13 +189,18 @@ module RubyLLM
         # @param name [Symbol] The parameter name
         # @param required [Boolean] Whether the parameter is required
         # @param default [Object, nil] Default value if not provided
+        # @param type [Class, nil] Optional type for validation (e.g., String, Integer, Array)
         # @return [void]
-        # @example
+        # @example Without type (accepts anything)
         #   param :query, required: true
-        #   param :limit, default: 10
-        def param(name, required: false, default: nil)
+        #   param :data, default: {}
+        # @example With type validation
+        #   param :limit, default: 10, type: Integer
+        #   param :name, type: String
+        #   param :tags, type: Array
+        def param(name, required: false, default: nil, type: nil)
           @params ||= {}
-          @params[name] = { required: required, default: default }
+          @params[name] = { required: required, default: default, type: type }
           define_method(name) do
             @options[name] || @options[name.to_s] || self.class.params.dig(name, :default)
           end
@@ -175,17 +218,37 @@ module RubyLLM
 
         # @!group Caching DSL
 
-        # Enables caching for this agent with optional TTL
+        # 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 1.hour
-        def cache(ttl = CACHE_TTL)
+        #   cache_for 1.hour
+        #   cache_for 30.minutes
+        def cache_for(ttl)
           @cache_enabled = true
           @cache_ttl = ttl
         end
 
+        # Enables caching for this agent with optional TTL
+        #
+        # @deprecated Use {#cache_for} instead for clarity.
+        #   This method will be removed in version 1.0.
+        # @param ttl [ActiveSupport::Duration] Time-to-live for cached responses
+        # @return [void]
+        # @example
+        #   cache 1.hour  # deprecated
+        #   cache_for 1.hour  # preferred
+        def cache(ttl = CACHE_TTL)
+          RubyLLM::Agents::Deprecations.warn(
+            "cache(ttl) is deprecated. Use cache_for(ttl) instead for clarity.",
+            caller
+          )
+          cache_for(ttl)
+        end
+
         # Returns whether caching is enabled for this agent
         #
         # @return [Boolean] true if caching is enabled
@@ -232,13 +295,13 @@ module RubyLLM
         #
         # @param tool_classes [Array<Class>] Tool classes to make available
         # @return [Array<Class>] The current tools
+        # @example With array (preferred)
+        #   tools [WeatherTool, SearchTool, CalculatorTool]
         # @example Single tool
-        #   tools WeatherTool
-        # @example Multiple tools
-        #   tools WeatherTool, SearchTool, CalculatorTool
-        def tools(*tool_classes)
-          if tool_classes.any?
-            @tools = tool_classes.flatten
+        #   tools [WeatherTool]
+        def tools(tool_classes = nil)
+          if tool_classes
+            @tools = Array(tool_classes)
           end
           @tools || inherited_or_default(:tools, RubyLLM::Agents.configuration.default_tools)
         end

data/lib/ruby_llm/agents/base/execution.rb

@@ -62,7 +62,7 @@ module RubyLLM
           reset_accumulated_tool_calls!
 
           Timeout.timeout(self.class.timeout) do
-            if self.class.streaming && block_given?
+            if streaming_enabled? && block_given?
               execute_with_streaming(current_client, &block)
             else
               response = current_client.ask(user_prompt, **ask_options)
@@ -177,6 +177,16 @@ module RubyLLM
             config[:circuit_breaker].present?
         end
 
+        # Returns whether streaming is enabled for this execution
+        #
+        # Checks both class-level DSL setting and instance-level override
+        # (set by the stream class method).
+        #
+        # @return [Boolean] true if streaming is enabled
+        def streaming_enabled?
+          @force_streaming || self.class.streaming
+        end
+
         # Returns options to pass to the ask method
         #
         # Currently supports :with for attachments (images, PDFs, etc.)
@@ -188,14 +198,28 @@ module RubyLLM
           opts
         end
 
-        # Validates that all required parameters are present
+        # Validates that all required parameters are present and types match
         #
-        # @raise [ArgumentError] If required parameters are missing
+        # @raise [ArgumentError] If required parameters are missing or types don't match
         # @return [void]
         def validate_required_params!
-          required = self.class.params.select { |_, v| v[:required] }.keys
-          missing = required.reject { |p| @options.key?(p) || @options.key?(p.to_s) }
-          raise ArgumentError, "#{self.class} missing required params: #{missing.join(', ')}" if missing.any?
+          self.class.params.each do |name, config|
+            value = @options[name] || @options[name.to_s]
+            has_value = @options.key?(name) || @options.key?(name.to_s)
+
+            # Check required
+            if config[:required] && !has_value
+              raise ArgumentError, "#{self.class} missing required param: #{name}"
+            end
+
+            # Check type if specified and value is present (not nil)
+            if config[:type] && has_value && !value.nil?
+              unless value.is_a?(config[:type])
+                raise ArgumentError,
+                  "#{self.class} expected #{config[:type]} for :#{name}, got #{value.class}"
+              end
+            end
+          end
         end
 
         # Builds and configures the RubyLLM client
@@ -233,9 +257,10 @@ module RubyLLM
         # @param msgs [Array<Hash>] Messages with :role and :content keys
         # @return [RubyLLM::Chat] Client with messages applied
         def apply_messages(client, msgs)
-          msgs.reduce(client) do |c, message|
-            c.with_message(message[:role].to_s, message[:content])
+          msgs.each do |message|
+            client.add_message(role: message[:role].to_sym, content: message[:content])
           end
+          client
         end
 
         # Builds a client with pre-populated conversation history

data/lib/ruby_llm/agents/base/reliability_dsl.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class Base
+      # DSL builder for reliability configuration
+      #
+      # Provides a block-based configuration syntax for grouping
+      # all reliability settings together.
+      #
+      # @example Basic usage
+      #   class MyAgent < ApplicationAgent
+      #     reliability do
+      #       retries max: 3, backoff: :exponential
+      #       fallback_models "gpt-4o-mini"
+      #       total_timeout 30
+      #       circuit_breaker errors: 5, within: 60
+      #     end
+      #   end
+      #
+      # @api public
+      class ReliabilityDSL
+        attr_reader :retries_config, :fallback_models_list, :total_timeout_value, :circuit_breaker_config
+
+        def initialize
+          @retries_config = nil
+          @fallback_models_list = []
+          @total_timeout_value = nil
+          @circuit_breaker_config = nil
+        end
+
+        # Configures retry behavior
+        #
+        # @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 between retries
+        # @param on [Array<Class>] Additional error classes to retry on
+        # @return [void]
+        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
+
+        # Sets fallback models
+        #
+        # @param models [Array<String>] Model identifiers
+        # @return [void]
+        def fallback_models(*models)
+          @fallback_models_list = models.flatten
+        end
+
+        # Sets total timeout across all retry/fallback attempts
+        #
+        # @param seconds [Integer] Total timeout in seconds
+        # @return [void]
+        def total_timeout(seconds)
+          @total_timeout_value = seconds
+        end
+
+        # Configures circuit breaker
+        #
+        # @param errors [Integer] Failure threshold
+        # @param within [Integer] Rolling window in seconds
+        # @param cooldown [Integer] Cooldown period in seconds
+        # @return [void]
+        def circuit_breaker(errors: 10, within: 60, cooldown: 300)
+          @circuit_breaker_config = {
+            errors: errors,
+            within: within,
+            cooldown: cooldown
+          }
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/base.rb

@@ -83,6 +83,33 @@ module RubyLLM
         def call(*args, **kwargs, &block)
           new(*args, **kwargs).call(&block)
         end
+
+        # Streams agent execution, yielding chunks as they arrive
+        #
+        # A more explicit alternative to passing a block to call.
+        # Forces streaming mode for this invocation regardless of class setting.
+        #
+        # @param kwargs [Hash] Agent parameters
+        # @yield [chunk] Yields each chunk as it arrives
+        # @yieldparam chunk [RubyLLM::Chunk] Streaming chunk with content
+        # @return [Result] The final result after streaming completes
+        # @raise [ArgumentError] If no block is provided
+        #
+        # @example Basic streaming
+        #   MyAgent.stream(query: "test") do |chunk|
+        #     print chunk.content
+        #   end
+        #
+        # @example With result metadata
+        #   result = MyAgent.stream(query: "test") { |c| print c.content }
+        #   puts "\nTokens: #{result.total_tokens}"
+        def stream(**kwargs, &block)
+          raise ArgumentError, "Block required for streaming" unless block_given?
+
+          instance = new(**kwargs)
+          instance.instance_variable_set(:@force_streaming, true)
+          instance.call(&block)
+        end
       end
 
       # @!attribute [r] model

data/lib/ruby_llm/agents/deprecations.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Manages deprecation warnings with configurable behavior
+    #
+    # Provides a centralized mechanism for deprecation warnings that can be
+    # configured to raise exceptions in test environments or emit warnings
+    # in production.
+    #
+    # @example Emitting a deprecation warning
+    #   Deprecations.warn("cache(ttl) is deprecated, use cache_for(ttl) instead")
+    #
+    # @example Enabling strict mode in tests
+    #   RubyLLM::Agents::Deprecations.raise_on_deprecation = true
+    #
+    # @api public
+    module Deprecations
+      # Error raised when deprecation warnings are configured to raise
+      #
+      # @api public
+      class DeprecationError < StandardError; end
+
+      class << self
+        # @!attribute [rw] raise_on_deprecation
+        #   @return [Boolean] Whether to raise exceptions instead of warnings
+        attr_accessor :raise_on_deprecation
+
+        # @!attribute [rw] silenced
+        #   @return [Boolean] Whether to silence all deprecation warnings
+        attr_accessor :silenced
+
+        # Emits a deprecation warning or raises an error
+        #
+        # @param message [String] The deprecation message
+        # @param callstack [Array<String>] The call stack (defaults to caller)
+        # @return [void]
+        # @raise [DeprecationError] If raise_on_deprecation is true
+        def warn(message, callstack = caller)
+          return if silenced
+
+          full_message = "[RubyLLM::Agents DEPRECATION] #{message}"
+
+          if raise_on_deprecation
+            raise DeprecationError, full_message
+          elsif defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+            # Use Rails deprecator if available (Rails 7.1+)
+            if Rails.application.respond_to?(:deprecators)
+              Rails.application.deprecators[:ruby_llm_agents]&.warn(full_message, callstack) ||
+                ::Kernel.warn("#{full_message}\n  #{callstack.first}")
+            else
+              ::Kernel.warn("#{full_message}\n  #{callstack.first}")
+            end
+          else
+            ::Kernel.warn("#{full_message}\n  #{callstack.first}")
+          end
+        end
+
+        # Temporarily silence deprecation warnings within a block
+        #
+        # @yield Block to execute with silenced warnings
+        # @return [Object] The return value of the block
+        def silence
+          old_silenced = silenced
+          self.silenced = true
+          yield
+        ensure
+          self.silenced = old_silenced
+        end
+      end
+
+      # Reset to defaults
+      self.raise_on_deprecation = false
+      self.silenced = false
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Reliability
+      # Manages circuit breakers for multiple models
+      #
+      # Provides centralized access to circuit breakers with
+      # multi-tenant support and caching.
+      #
+      # @example
+      #   manager = BreakerManager.new("MyAgent", config: { errors: 5, within: 60 })
+      #   manager.open?("gpt-4o")        # => false
+      #   manager.record_failure!("gpt-4o")
+      #   manager.record_success!("gpt-4o")
+      #
+      # @api private
+      class BreakerManager
+        # @param agent_type [String] The agent class name
+        # @param config [Hash, nil] Circuit breaker configuration
+        # @param tenant_id [String, nil] Optional tenant identifier
+        def initialize(agent_type, config:, tenant_id: nil)
+          @agent_type = agent_type
+          @config = config
+          @tenant_id = tenant_id
+          @breakers = {}
+        end
+
+        # Gets or creates a circuit breaker for a model
+        #
+        # @param model_id [String] Model identifier
+        # @return [CircuitBreaker, nil] The circuit breaker or nil if not configured
+        def for_model(model_id)
+          return nil unless @config
+
+          @breakers[model_id] ||= CircuitBreaker.from_config(
+            @agent_type,
+            model_id,
+            @config,
+            tenant_id: @tenant_id
+          )
+        end
+
+        # Checks if a model's circuit breaker is open
+        #
+        # @param model_id [String] Model identifier
+        # @return [Boolean] true if breaker is open
+        def open?(model_id)
+          breaker = for_model(model_id)
+          breaker&.open? || false
+        end
+
+        # Records a success for a model
+        #
+        # @param model_id [String] Model identifier
+        # @return [void]
+        def record_success!(model_id)
+          for_model(model_id)&.record_success!
+        end
+
+        # Records a failure for a model
+        #
+        # @param model_id [String] Model identifier
+        # @return [Boolean] true if breaker is now open
+        def record_failure!(model_id)
+          breaker = for_model(model_id)
+          breaker&.record_failure!
+          breaker&.open? || false
+        end
+
+        # Checks if circuit breaker is configured
+        #
+        # @return [Boolean] true if config present
+        def enabled?
+          @config.present?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Reliability
+      # Manages execution constraints like total timeout and budget
+      #
+      # Tracks elapsed time and enforces timeout limits across
+      # all retry and fallback attempts.
+      #
+      # @example
+      #   constraints = ExecutionConstraints.new(total_timeout: 30)
+      #   constraints.timeout_exceeded?  # => false
+      #   constraints.enforce_timeout!   # raises if exceeded
+      #   constraints.elapsed            # => 5.2
+      #
+      # @api private
+      class ExecutionConstraints
+        attr_reader :total_timeout, :started_at, :deadline
+
+        # @param total_timeout [Integer, nil] Total timeout in seconds
+        def initialize(total_timeout: nil)
+          @total_timeout = total_timeout
+          @started_at = Time.current
+          @deadline = total_timeout ? @started_at + total_timeout : nil
+        end
+
+        # Checks if total timeout has been exceeded
+        #
+        # @return [Boolean] true if past deadline
+        def timeout_exceeded?
+          deadline && Time.current > deadline
+        end
+
+        # Returns elapsed time since start
+        #
+        # @return [Float] Elapsed seconds
+        def elapsed
+          Time.current - started_at
+        end
+
+        # Raises TotalTimeoutError if timeout exceeded
+        #
+        # @raise [TotalTimeoutError] If timeout exceeded
+        # @return [void]
+        def enforce_timeout!
+          if timeout_exceeded?
+            raise TotalTimeoutError.new(total_timeout, elapsed)
+          end
+        end
+
+        # Returns remaining time until deadline
+        #
+        # @return [Float, nil] Remaining seconds or nil if no timeout
+        def remaining
+          return nil unless deadline
+          [deadline - Time.current, 0].max
+        end
+
+        # Checks if there's a timeout configured
+        #
+        # @return [Boolean] true if timeout is set
+        def has_timeout?
+          total_timeout.present?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Reliability
+      # Coordinates reliability features during agent execution
+      #
+      # Orchestrates retry strategy, fallback routing, circuit breakers,
+      # and execution constraints into a cohesive execution flow.
+      #
+      # @example
+      #   executor = Executor.new(
+      #     config: { retries: { max: 3 }, fallback_models: ["gpt-4o-mini"] },
+      #     primary_model: "gpt-4o",
+      #     agent_type: "MyAgent"
+      #   )
+      #   executor.execute { |model| call_llm(model) }
+      #
+      # @api private
+      class Executor
+        attr_reader :retry_strategy, :fallback_routing, :breaker_manager, :constraints
+
+        # @param config [Hash] Reliability configuration
+        # @param primary_model [String] Primary model identifier
+        # @param agent_type [String] Agent class name
+        # @param tenant_id [String, nil] Optional tenant identifier
+        def initialize(config:, primary_model:, agent_type:, tenant_id: nil)
+          retries_config = config[:retries] || {}
+
+          @retry_strategy = RetryStrategy.new(
+            max: retries_config[:max] || 0,
+            backoff: retries_config[:backoff] || :exponential,
+            base: retries_config[:base] || 0.4,
+            max_delay: retries_config[:max_delay] || 3.0,
+            on: retries_config[:on] || []
+          )
+
+          @fallback_routing = FallbackRouting.new(
+            primary_model,
+            fallback_models: config[:fallback_models] || []
+          )
+
+          @breaker_manager = BreakerManager.new(
+            agent_type,
+            config: config[:circuit_breaker],
+            tenant_id: tenant_id
+          )
+
+          @constraints = ExecutionConstraints.new(
+            total_timeout: config[:total_timeout]
+          )
+
+          @last_error = nil
+        end
+
+        # Returns all models that will be tried
+        #
+        # @return [Array<String>] Model identifiers
+        def models_to_try
+          fallback_routing.models
+        end
+
+        # Executes with full reliability support
+        #
+        # Iterates through models with retries, respecting circuit breakers
+        # and timeout constraints.
+        #
+        # @yield [model] Block to execute with the current model
+        # @yieldparam model [String] The model to use for this attempt
+        # @return [Object] Result of successful execution
+        # @raise [AllModelsExhaustedError] If all models fail
+        # @raise [TotalTimeoutError] If total timeout exceeded
+        def execute
+          until fallback_routing.exhausted?
+            model = fallback_routing.current_model
+
+            # Check circuit breaker
+            if breaker_manager.open?(model)
+              fallback_routing.advance!
+              next
+            end
+
+            # Try with retries
+            result = execute_with_retries(model) { |m| yield(m) }
+            return result if result
+
+            fallback_routing.advance!
+          end
+
+          raise AllModelsExhaustedError.new(
+            fallback_routing.models,
+            @last_error || StandardError.new("All models failed")
+          )
+        end
+
+        private
+
+        def execute_with_retries(model)
+          attempt_index = 0
+
+          loop do
+            constraints.enforce_timeout!
+
+            begin
+              result = yield(model)
+              breaker_manager.record_success!(model)
+              return result
+            rescue => e
+              @last_error = e
+              breaker_manager.record_failure!(model)
+
+              if retry_strategy.retryable?(e) && retry_strategy.should_retry?(attempt_index)
+                attempt_index += 1
+                sleep(retry_strategy.delay_for(attempt_index))
+              else
+                return nil # Move to next model
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Reliability
+      # Routes execution through fallback models when primary fails
+      #
+      # Manages the model fallback chain and tracks which models have been tried.
+      #
+      # @example
+      #   routing = FallbackRouting.new("gpt-4o", fallback_models: ["gpt-4o-mini"])
+      #   routing.current_model  # => "gpt-4o"
+      #   routing.advance!       # => "gpt-4o-mini"
+      #   routing.exhausted?     # => false
+      #
+      # @api private
+      class FallbackRouting
+        attr_reader :models
+
+        # @param primary_model [String] The primary model identifier
+        # @param fallback_models [Array<String>] Fallback model identifiers
+        def initialize(primary_model, fallback_models: [])
+          @models = [primary_model, *fallback_models].uniq
+          @current_index = 0
+        end
+
+        # Returns the current model to try
+        #
+        # @return [String, nil] Model identifier or nil if exhausted
+        def current_model
+          models[@current_index]
+        end
+
+        # Advances to the next fallback model
+        #
+        # @return [String, nil] Next model or nil if exhausted
+        def advance!
+          @current_index += 1
+          current_model
+        end
+
+        # Checks if more models are available after current
+        #
+        # @return [Boolean] true if more models to try
+        def has_more?
+          @current_index < models.length - 1
+        end
+
+        # Checks if all models have been exhausted
+        #
+        # @return [Boolean] true if no more models
+        def exhausted?
+          @current_index >= models.length
+        end
+
+        # Resets to the first model
+        #
+        # @return [void]
+        def reset!
+          @current_index = 0
+        end
+
+        # Returns models that have been tried so far
+        #
+        # @return [Array<String>] Models already attempted
+        def tried_models
+          models[0..@current_index]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Reliability
+      # Handles retry logic with configurable backoff strategies
+      #
+      # Provides exponential and constant backoff with jitter,
+      # retry counting, and delay calculation.
+      #
+      # @example
+      #   strategy = RetryStrategy.new(max: 3, backoff: :exponential, base: 0.4)
+      #   strategy.should_retry?(attempt_index) # => true/false
+      #   strategy.delay_for(attempt_index)     # => 0.6 (with jitter)
+      #
+      # @api private
+      class RetryStrategy
+        attr_reader :max, :backoff, :base, :max_delay, :custom_errors
+
+        # @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: [])
+          @max = max
+          @backoff = backoff
+          @base = base
+          @max_delay = max_delay
+          @custom_errors = Array(on)
+        end
+
+        # Determines if retry should occur
+        #
+        # @param attempt_index [Integer] Current attempt number (0-indexed)
+        # @return [Boolean] true if should retry
+        def should_retry?(attempt_index)
+          attempt_index < max
+        end
+
+        # Calculates delay before next retry
+        #
+        # @param attempt_index [Integer] Current attempt number
+        # @return [Float] Delay in seconds (includes jitter)
+        def delay_for(attempt_index)
+          base_delay = case backoff
+          when :constant
+            base
+          when :exponential
+            [base * (2**attempt_index), max_delay].min
+          else
+            base
+          end
+
+          # Add jitter (0-50% of base delay)
+          base_delay + (rand * base_delay * 0.5)
+        end
+
+        # Checks if an error is retryable
+        #
+        # @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)
+        end
+
+        # Returns all retryable error classes
+        #
+        # @return [Array<Class>] Error classes to retry on
+        def retryable_errors
+          RubyLLM::Agents::Reliability.default_retryable_errors + custom_errors
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/result.rb

@@ -220,8 +220,78 @@ module RubyLLM
         }
       end
 
-      # Delegate hash methods to content for backward compatibility
-      delegate :[], :dig, :keys, :values, :each, :map, to: :content, allow_nil: true
+      # @!group Deprecated Hash Delegation
+      #
+      # These methods delegate to content for backward compatibility but are deprecated.
+      # Use result.content directly instead.
+      #
+      # @deprecated Access content directly via {#content} instead.
+      #   These methods will be removed in version 1.0.
+      #
+      # @example Migration
+      #   # Before (deprecated)
+      #   result[:key]
+      #   result.dig(:nested, :key)
+      #
+      #   # After (recommended)
+      #   result.content[:key]
+      #   result.content.dig(:nested, :key)
+
+      # @deprecated Use result.content[:key] instead
+      def [](key)
+        RubyLLM::Agents::Deprecations.warn(
+          "Result#[] is deprecated. Use result.content[:key] instead.",
+          caller
+        )
+        content&.[](key)
+      end
+
+      # @deprecated Use result.content.dig(...) instead
+      def dig(*keys)
+        RubyLLM::Agents::Deprecations.warn(
+          "Result#dig is deprecated. Use result.content.dig(...) instead.",
+          caller
+        )
+        content&.dig(*keys)
+      end
+
+      # @deprecated Use result.content.keys instead
+      def keys
+        RubyLLM::Agents::Deprecations.warn(
+          "Result#keys is deprecated. Use result.content.keys instead.",
+          caller
+        )
+        content&.keys
+      end
+
+      # @deprecated Use result.content.values instead
+      def values
+        RubyLLM::Agents::Deprecations.warn(
+          "Result#values is deprecated. Use result.content.values instead.",
+          caller
+        )
+        content&.values
+      end
+
+      # @deprecated Use result.content.each instead
+      def each(&block)
+        RubyLLM::Agents::Deprecations.warn(
+          "Result#each is deprecated. Use result.content.each instead.",
+          caller
+        )
+        content&.each(&block)
+      end
+
+      # @deprecated Use result.content.map instead
+      def map(&block)
+        RubyLLM::Agents::Deprecations.warn(
+          "Result#map is deprecated. Use result.content.map instead.",
+          caller
+        )
+        content&.map(&block)
+      end
+
+      # @!endgroup
 
       # Custom to_json that returns content as JSON for backward compatibility
       #

data/lib/ruby_llm/agents/version.rb

@@ -4,6 +4,6 @@ module RubyLLM
   module Agents
     # Current version of the RubyLLM::Agents gem
     # @return [String] Semantic version string
-    VERSION = "0.3.5"
+    VERSION = "0.4.0"
   end
 end

data/lib/ruby_llm/agents/workflow.rb

@@ -42,6 +42,10 @@ module RubyLLM
         #   @return [Float, nil] Maximum cost threshold for the workflow
         attr_accessor :_max_cost
 
+        # @!attribute [rw] description
+        #   @return [String, nil] Description of the workflow
+        attr_accessor :_description
+
         # Sets or returns the workflow version
         #
         # @param value [String, nil] Version string to set
@@ -78,6 +82,18 @@ module RubyLLM
           end
         end
 
+        # Sets or returns the workflow description
+        #
+        # @param value [String, nil] Description text to set
+        # @return [String, nil] The current description
+        def description(value = nil)
+          if value
+            self._description = value
+          else
+            _description
+          end
+        end
+
         # Factory method to instantiate and execute a workflow
         #
         # @param kwargs [Hash] Parameters to pass to the workflow

data/lib/ruby_llm/agents.rb

@@ -5,7 +5,13 @@ require "ruby_llm"
 
 require_relative "agents/version"
 require_relative "agents/configuration"
+require_relative "agents/deprecations"
 require_relative "agents/reliability"
+require_relative "agents/reliability/retry_strategy"
+require_relative "agents/reliability/fallback_routing"
+require_relative "agents/reliability/breaker_manager"
+require_relative "agents/reliability/execution_constraints"
+require_relative "agents/reliability/executor"
 require_relative "agents/redactor"
 require_relative "agents/circuit_breaker"
 require_relative "agents/budget_tracker"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-agents
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.4.0
 platform: ruby
 authors:
 - adham90
@@ -140,6 +140,7 @@ files:
 - lib/ruby_llm/agents/base/cost_calculation.rb
 - lib/ruby_llm/agents/base/dsl.rb
 - lib/ruby_llm/agents/base/execution.rb
+- lib/ruby_llm/agents/base/reliability_dsl.rb
 - lib/ruby_llm/agents/base/reliability_execution.rb
 - lib/ruby_llm/agents/base/response_building.rb
 - lib/ruby_llm/agents/base/tool_tracking.rb
@@ -147,12 +148,18 @@ files:
 - lib/ruby_llm/agents/cache_helper.rb
 - lib/ruby_llm/agents/circuit_breaker.rb
 - lib/ruby_llm/agents/configuration.rb
+- lib/ruby_llm/agents/deprecations.rb
 - lib/ruby_llm/agents/engine.rb
 - lib/ruby_llm/agents/execution_logger_job.rb
 - lib/ruby_llm/agents/inflections.rb
 - lib/ruby_llm/agents/instrumentation.rb
 - lib/ruby_llm/agents/redactor.rb
 - lib/ruby_llm/agents/reliability.rb
+- lib/ruby_llm/agents/reliability/breaker_manager.rb
+- lib/ruby_llm/agents/reliability/execution_constraints.rb
+- lib/ruby_llm/agents/reliability/executor.rb
+- lib/ruby_llm/agents/reliability/fallback_routing.rb
+- lib/ruby_llm/agents/reliability/retry_strategy.rb
 - lib/ruby_llm/agents/result.rb
 - lib/ruby_llm/agents/version.rb
 - lib/ruby_llm/agents/workflow.rb