ruby_llm-agents 0.3.3 → 0.3.5

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

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class Base
+      # Main execution flow for agents
+      #
+      # Handles the core execution logic including caching, streaming,
+      # client building, and parameter validation.
+      module Execution
+        # Executes the agent and returns the processed response
+        #
+        # Handles caching, dry-run mode, and delegates to uncached_call
+        # for actual LLM execution.
+        #
+        # @yield [chunk] Yields chunks when streaming is enabled
+        # @yieldparam chunk [RubyLLM::Chunk] A streaming chunk with content
+        # @return [Object] The processed LLM response
+        def call(&block)
+          return dry_run_response if @options[:dry_run]
+          return uncached_call(&block) if @options[:skip_cache] || !self.class.cache_enabled?
+
+          cache_key = agent_cache_key
+
+          # Check for cache hit BEFORE fetch to record it
+          if cache_store.exist?(cache_key)
+            started_at = Time.current
+            cached_result = cache_store.read(cache_key)
+            record_cache_hit_execution(cache_key, cached_result, started_at) if cached_result
+            return cached_result
+          end
+
+          # Cache miss - execute and store
+          cache_store.fetch(cache_key, expires_in: self.class.cache_ttl) do
+            uncached_call(&block)
+          end
+        end
+
+        # Executes the agent without caching
+        #
+        # Routes to reliability-enabled execution if configured, otherwise
+        # uses simple single-attempt execution.
+        #
+        # @yield [chunk] Yields chunks when streaming is enabled
+        # @return [Object] The processed response
+        def uncached_call(&block)
+          if reliability_enabled?
+            execute_with_reliability(&block)
+          else
+            instrument_execution { execute_single_attempt(&block) }
+          end
+        end
+
+        # Executes a single LLM attempt with timeout
+        #
+        # @param model_override [String, nil] Optional model to use instead of default
+        # @yield [chunk] Yields chunks when streaming is enabled
+        # @return [Result] A Result object with processed content and metadata
+        def execute_single_attempt(model_override: nil, &block)
+          current_client = model_override ? build_client_with_model(model_override) : client
+          @execution_started_at ||= Time.current
+          reset_accumulated_tool_calls!
+
+          Timeout.timeout(self.class.timeout) do
+            if self.class.streaming && block_given?
+              execute_with_streaming(current_client, &block)
+            else
+              response = current_client.ask(user_prompt, **ask_options)
+              extract_tool_calls_from_client(current_client)
+              capture_response(response)
+              build_result(process_response(response), response)
+            end
+          end
+        end
+
+        # Executes an LLM request with streaming enabled
+        #
+        # Yields chunks to the provided block as they arrive and tracks
+        # time to first token for latency analysis.
+        #
+        # @param current_client [RubyLLM::Chat] The configured client
+        # @yield [chunk] Yields each chunk as it arrives
+        # @yieldparam chunk [RubyLLM::Chunk] A streaming chunk
+        # @return [Result] A Result object with processed content and metadata
+        def execute_with_streaming(current_client, &block)
+          first_chunk_at = nil
+
+          response = current_client.ask(user_prompt, **ask_options) do |chunk|
+            first_chunk_at ||= Time.current
+            yield chunk if block_given?
+          end
+
+          if first_chunk_at && @execution_started_at
+            @time_to_first_token_ms = ((first_chunk_at - @execution_started_at) * 1000).to_i
+          end
+
+          extract_tool_calls_from_client(current_client)
+          capture_response(response)
+          build_result(process_response(response), response)
+        end
+
+        # Returns prompt info without making an API call (debug mode)
+        #
+        # @return [Result] A Result with dry run configuration info
+        def dry_run_response
+          Result.new(
+            content: {
+              dry_run: true,
+              agent: self.class.name,
+              model: model,
+              temperature: temperature,
+              timeout: self.class.timeout,
+              system_prompt: system_prompt,
+              user_prompt: user_prompt,
+              attachments: @options[:with],
+              schema: schema&.class&.name,
+              streaming: self.class.streaming,
+              tools: resolved_tools.map { |t| t.respond_to?(:name) ? t.name : t.to_s }
+            },
+            model_id: model,
+            temperature: temperature,
+            streaming: self.class.streaming
+          )
+        end
+
+        # Resolves tools for this execution
+        #
+        # Checks for instance method override first (for dynamic tools),
+        # then falls back to class-level DSL configuration. This allows
+        # agents to define tools dynamically based on runtime context.
+        #
+        # @return [Array<Class>] Tool classes to use
+        def resolved_tools
+          # Check if instance defines tools method (not inherited from class singleton)
+          if self.class.instance_methods(false).include?(:tools)
+            tools
+          else
+            self.class.tools
+          end
+        end
+
+        # Resolves messages for this execution
+        #
+        # Priority order:
+        # 1. @override_messages (set via with_messages)
+        # 2. :messages option passed at call time
+        # 3. messages template method defined in subclass
+        #
+        # @return [Array<Hash>] Messages to apply to conversation
+        def resolved_messages
+          return @override_messages if @override_messages&.any?
+          return @options[:messages] if @options[:messages]&.any?
+
+          messages
+        end
+
+        # Returns the consolidated reliability configuration for this agent instance
+        #
+        # @return [Hash] Reliability config with :retries, :fallback_models, :total_timeout, :circuit_breaker
+        def reliability_config
+          default_retries = RubyLLM::Agents.configuration.default_retries
+          {
+            retries: self.class.retries || default_retries,
+            fallback_models: self.class.fallback_models,
+            total_timeout: self.class.total_timeout,
+            circuit_breaker: self.class.circuit_breaker_config
+          }
+        end
+
+        # Returns whether any reliability features are enabled for this agent
+        #
+        # @return [Boolean] true if retries, fallbacks, or circuit breaker is configured
+        def reliability_enabled?
+          config = reliability_config
+          (config[:retries]&.dig(:max) || 0) > 0 ||
+            config[:fallback_models]&.any? ||
+            config[:circuit_breaker].present?
+        end
+
+        # Returns options to pass to the ask method
+        #
+        # Currently supports :with for attachments (images, PDFs, etc.)
+        #
+        # @return [Hash] Options for the ask call
+        def ask_options
+          opts = {}
+          opts[:with] = @options[:with] if @options[:with]
+          opts
+        end
+
+        # Validates that all required parameters are present
+        #
+        # @raise [ArgumentError] If required parameters are missing
+        # @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?
+        end
+
+        # Builds and configures the RubyLLM client
+        #
+        # @return [RubyLLM::Chat] Configured chat client
+        def build_client
+          client = RubyLLM.chat
+            .with_model(model)
+            .with_temperature(temperature)
+          client = client.with_instructions(system_prompt) if system_prompt
+          client = client.with_schema(schema) if schema
+          client = client.with_tools(*resolved_tools) if resolved_tools.any?
+          client = apply_messages(client, resolved_messages) if resolved_messages.any?
+          client
+        end
+
+        # Builds a client with a specific model
+        #
+        # @param model_id [String] The model identifier
+        # @return [RubyLLM::Chat] Configured chat client
+        def build_client_with_model(model_id)
+          client = RubyLLM.chat
+            .with_model(model_id)
+            .with_temperature(temperature)
+          client = client.with_instructions(system_prompt) if system_prompt
+          client = client.with_schema(schema) if schema
+          client = client.with_tools(*resolved_tools) if resolved_tools.any?
+          client = apply_messages(client, resolved_messages) if resolved_messages.any?
+          client
+        end
+
+        # Applies conversation history to the client
+        #
+        # @param client [RubyLLM::Chat] The chat client
+        # @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])
+          end
+        end
+
+        # Builds a client with pre-populated conversation history
+        #
+        # @deprecated Use resolved_messages and apply_messages instead.
+        #   Override the messages template method or pass messages: option to call.
+        # @param messages [Array<Hash>] Messages with :role and :content keys
+        # @return [RubyLLM::Chat] Client with messages added
+        # @example
+        #   build_client_with_messages([
+        #     { role: "user", content: "Hello" },
+        #     { role: "assistant", content: "Hi there!" }
+        #   ])
+        def build_client_with_messages(messages)
+          apply_messages(build_client, messages)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class Base
+      # Reliability execution with retry/fallback/circuit breaker support
+      #
+      # Handles executing agents with automatic retries, model fallbacks,
+      # circuit breaker protection, and budget enforcement.
+      module ReliabilityExecution
+        # Executes the agent with retry/fallback/circuit breaker support
+        #
+        # @yield [chunk] Yields chunks when streaming is enabled
+        # @return [Object] The processed response
+        # @raise [Reliability::AllModelsExhaustedError] If all models fail
+        # @raise [Reliability::BudgetExceededError] If budget limits exceeded
+        # @raise [Reliability::TotalTimeoutError] If total timeout exceeded
+        def execute_with_reliability(&block)
+          config = reliability_config
+          models_to_try = [model, *config[:fallback_models]].uniq
+          total_deadline = config[:total_timeout] ? Time.current + config[:total_timeout] : nil
+          started_at = Time.current
+
+          # Get current tenant_id for multi-tenancy support
+          global_config = RubyLLM::Agents.configuration
+          tenant_id = global_config.multi_tenancy_enabled? ? global_config.current_tenant_id : nil
+
+          # Pre-check budget (tenant_id is resolved automatically if not passed)
+          BudgetTracker.check_budget!(self.class.name, tenant_id: tenant_id) if global_config.budgets_enabled?
+
+          instrument_execution_with_attempts(models_to_try: models_to_try) do |attempt_tracker|
+            last_error = nil
+
+            models_to_try.each do |current_model|
+              # Check circuit breaker (with tenant isolation if enabled)
+              breaker = get_circuit_breaker(current_model, tenant_id: tenant_id)
+              if breaker&.open?
+                attempt_tracker.record_short_circuit(current_model)
+                next
+              end
+
+              retries_remaining = config[:retries]&.dig(:max) || 0
+              attempt_index = 0
+
+              loop do
+                # Check total timeout
+                if total_deadline && Time.current > total_deadline
+                  elapsed = Time.current - started_at
+                  raise Reliability::TotalTimeoutError.new(config[:total_timeout], elapsed)
+                end
+
+                attempt = attempt_tracker.start_attempt(current_model)
+
+                begin
+                  result = execute_single_attempt(model_override: current_model, &block)
+                  attempt_tracker.complete_attempt(attempt, success: true, response: @last_response)
+
+                  # Record success in circuit breaker
+                  breaker&.record_success!
+
+                  # Record budget spend (with tenant isolation if enabled)
+                  if @last_response && global_config.budgets_enabled?
+                    record_attempt_cost(attempt_tracker, tenant_id: tenant_id)
+                  end
+
+                  # Use throw instead of return to allow instrument_execution_with_attempts
+                  # to properly complete the execution record before returning
+                  throw :execution_success, result
+
+                rescue *retryable_errors(config) => e
+                  last_error = e
+                  attempt_tracker.complete_attempt(attempt, success: false, error: e)
+                  breaker&.record_failure!
+
+                  if retries_remaining > 0 && !past_deadline?(total_deadline)
+                    retries_remaining -= 1
+                    attempt_index += 1
+                    retries_config = config[:retries] || {}
+                    delay = Reliability.calculate_backoff(
+                      strategy: retries_config[:backoff] || :exponential,
+                      base: retries_config[:base] || 0.4,
+                      max_delay: retries_config[:max_delay] || 3.0,
+                      attempt: attempt_index
+                    )
+                    sleep(delay)
+                  else
+                    break # Move to next model
+                  end
+
+                rescue StandardError => e
+                  # Non-retryable error - record and move to next model
+                  last_error = e
+                  attempt_tracker.complete_attempt(attempt, success: false, error: e)
+                  breaker&.record_failure!
+                  break
+                end
+              end
+            end
+
+            # All models exhausted
+            raise Reliability::AllModelsExhaustedError.new(models_to_try, last_error)
+          end
+        end
+
+        # Returns the list of retryable error classes
+        #
+        # @param config [Hash] Reliability configuration
+        # @return [Array<Class>] Error classes to retry on
+        def retryable_errors(config)
+          custom_errors = config[:retries]&.dig(:on) || []
+          Reliability.default_retryable_errors + custom_errors
+        end
+
+        # Checks if the total deadline has passed
+        #
+        # @param deadline [Time, nil] The deadline
+        # @return [Boolean] true if past deadline
+        def past_deadline?(deadline)
+          deadline && Time.current > deadline
+        end
+
+        # Gets or creates a circuit breaker for a model
+        #
+        # @param model_id [String] The model identifier
+        # @param tenant_id [String, nil] Optional tenant identifier for multi-tenant isolation
+        # @return [CircuitBreaker, nil] The circuit breaker or nil if not configured
+        def get_circuit_breaker(model_id, tenant_id: nil)
+          config = reliability_config[:circuit_breaker]
+          return nil unless config
+
+          CircuitBreaker.from_config(self.class.name, model_id, config, tenant_id: tenant_id)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class Base
+      # Result object construction from LLM responses
+      #
+      # Handles building Result objects with full execution metadata
+      # including tokens, costs, timing, and tool calls.
+      module ResponseBuilding
+        # Builds a Result object from processed content and response metadata
+        #
+        # @param content [Hash, String] The processed response content
+        # @param response [RubyLLM::Message] The raw LLM response
+        # @return [Result] A Result object with full execution metadata
+        def build_result(content, response)
+          completed_at = Time.current
+          input_tokens = result_response_value(response, :input_tokens)
+          output_tokens = result_response_value(response, :output_tokens)
+          response_model_id = result_response_value(response, :model_id)
+
+          Result.new(
+            content: content,
+            input_tokens: input_tokens,
+            output_tokens: output_tokens,
+            cached_tokens: result_response_value(response, :cached_tokens, 0),
+            cache_creation_tokens: result_response_value(response, :cache_creation_tokens, 0),
+            model_id: model,
+            chosen_model_id: response_model_id || model,
+            temperature: temperature,
+            started_at: @execution_started_at,
+            completed_at: completed_at,
+            duration_ms: result_duration_ms(completed_at),
+            time_to_first_token_ms: @time_to_first_token_ms,
+            finish_reason: result_finish_reason(response),
+            streaming: self.class.streaming,
+            input_cost: result_input_cost(input_tokens, response_model_id),
+            output_cost: result_output_cost(output_tokens, response_model_id),
+            total_cost: result_total_cost(input_tokens, output_tokens, response_model_id),
+            tool_calls: @accumulated_tool_calls,
+            tool_calls_count: @accumulated_tool_calls.size
+          )
+        end
+
+        # Safely extracts a value from the response object
+        #
+        # @param response [Object] The response object
+        # @param method [Symbol] The method to call
+        # @param default [Object] Default value if method doesn't exist
+        # @return [Object] The extracted value or default
+        def result_response_value(response, method, default = nil)
+          return default unless response.respond_to?(method)
+          response.send(method) || default
+        end
+
+        # Calculates execution duration in milliseconds
+        #
+        # @param completed_at [Time] When execution completed
+        # @return [Integer, nil] Duration in ms or nil
+        def result_duration_ms(completed_at)
+          return nil unless @execution_started_at
+          ((completed_at - @execution_started_at) * 1000).to_i
+        end
+
+        # Extracts finish reason from response
+        #
+        # @param response [Object] The response object
+        # @return [String, nil] Normalized finish reason
+        def result_finish_reason(response)
+          reason = result_response_value(response, :finish_reason) ||
+                   result_response_value(response, :stop_reason)
+          return nil unless reason
+
+          # Normalize to standard values
+          case reason.to_s.downcase
+          when "stop", "end_turn" then "stop"
+          when "length", "max_tokens" then "length"
+          when "content_filter", "safety" then "content_filter"
+          when "tool_calls", "tool_use" then "tool_calls"
+          else "other"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class Base
+      # Tool call tracking for agent executions
+      #
+      # Handles accumulating and serializing tool calls made during
+      # an agent's execution cycle.
+      module ToolTracking
+        # Resets accumulated tool calls for a new execution
+        #
+        # @return [void]
+        def reset_accumulated_tool_calls!
+          @accumulated_tool_calls = []
+        end
+
+        # Extracts tool calls from all assistant messages in the conversation
+        #
+        # RubyLLM handles tool call loops internally. After ask() completes,
+        # the conversation history contains all intermediate assistant messages
+        # that had tool_calls. This method extracts those tool calls.
+        #
+        # @param client [RubyLLM::Chat] The chat client with conversation history
+        # @return [void]
+        def extract_tool_calls_from_client(client)
+          return unless client.respond_to?(:messages)
+
+          client.messages.each do |message|
+            next unless message.role == :assistant
+            next unless message.respond_to?(:tool_calls) && message.tool_calls.present?
+
+            message.tool_calls.each_value do |tool_call|
+              @accumulated_tool_calls << serialize_tool_call(tool_call)
+            end
+          end
+        end
+
+        # Serializes a single tool call to a hash
+        #
+        # @param tool_call [Object] The tool call object
+        # @return [Hash] Serialized tool call
+        def serialize_tool_call(tool_call)
+          if tool_call.respond_to?(:to_h)
+            tool_call.to_h.transform_keys(&:to_s)
+          else
+            {
+              "id" => tool_call.id,
+              "name" => tool_call.name,
+              "arguments" => tool_call.arguments
+            }
+          end
+        end
+      end
+    end
+  end
+end