ruby_llm-agents 0.5.0 → 1.0.0

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

@@ -1,82 +0,0 @@
-# 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/reliability_execution.rb

@@ -1,136 +0,0 @@
-# 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

@@ -1,86 +0,0 @@
-# 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

@@ -1,57 +0,0 @@
-# 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

data/lib/ruby_llm/agents/base.rb

@@ -1,210 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "base/dsl"
-require_relative "base/caching"
-require_relative "base/cost_calculation"
-require_relative "base/tool_tracking"
-require_relative "base/response_building"
-require_relative "base/execution"
-require_relative "base/reliability_execution"
-
-module RubyLLM
-  module Agents
-    # Base class for LLM-powered agents
-    #
-    # Provides a DSL for configuring and executing agents that interact with
-    # large language models. Includes built-in support for caching, timeouts,
-    # structured output, and execution tracking.
-    #
-    # @example Creating an agent
-    #   class SearchAgent < ApplicationAgent
-    #     model "gpt-4o"
-    #     temperature 0.0
-    #     version "1.0"
-    #     timeout 30
-    #     cache 1.hour
-    #
-    #     param :query, required: true
-    #     param :limit, default: 10
-    #
-    #     def system_prompt
-    #       "You are a search assistant..."
-    #     end
-    #
-    #     def user_prompt
-    #       "Search for: #{query}"
-    #     end
-    #   end
-    #
-    # @example Calling an agent
-    #   SearchAgent.call(query: "red dress")
-    #   SearchAgent.call(query: "red dress", dry_run: true)    # Debug mode
-    #   SearchAgent.call(query: "red dress", skip_cache: true) # Bypass cache
-    #
-    # @see RubyLLM::Agents::Instrumentation
-    # @api public
-    class Base
-      include Instrumentation
-      include Caching
-      include CostCalculation
-      include ToolTracking
-      include ResponseBuilding
-      include Execution
-      include ReliabilityExecution
-
-      extend DSL
-
-      class << self
-        # Factory method to instantiate and execute an agent
-        #
-        # @param args [Array] Positional arguments (reserved for future use)
-        # @param kwargs [Hash] Named parameters for the agent
-        # @option kwargs [Boolean] :dry_run Return prompt info without API call
-        # @option kwargs [Boolean] :skip_cache Bypass caching even if enabled
-        # @option kwargs [String, Array<String>] :with Attachments (files, URLs) to send with the prompt
-        # @yield [chunk] Yields chunks when streaming is enabled
-        # @yieldparam chunk [RubyLLM::Chunk] A streaming chunk with content
-        # @return [Object] The processed response from the agent
-        #
-        # @example Basic usage
-        #   SearchAgent.call(query: "red dress")
-        #
-        # @example Debug mode
-        #   SearchAgent.call(query: "red dress", dry_run: true)
-        #
-        # @example Streaming mode
-        #   ChatAgent.call(message: "Hello") do |chunk|
-        #     print chunk.content
-        #   end
-        #
-        # @example With attachments
-        #   VisionAgent.call(query: "Describe this image", with: "photo.jpg")
-        #   VisionAgent.call(query: "Compare these", with: ["a.png", "b.png"])
-        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
-      #   @return [String] The LLM model being used
-      # @!attribute [r] temperature
-      #   @return [Float] The temperature setting
-      # @!attribute [r] client
-      #   @return [RubyLLM::Chat] The configured RubyLLM client
-      # @!attribute [r] time_to_first_token_ms
-      #   @return [Integer, nil] Time to first token in milliseconds (streaming only)
-      # @!attribute [r] accumulated_tool_calls
-      #   @return [Array<Hash>] Tool calls accumulated during execution
-      attr_reader :model, :temperature, :client, :time_to_first_token_ms, :accumulated_tool_calls
-
-      # Creates a new agent instance
-      #
-      # @param model [String] Override the class-level model setting
-      # @param temperature [Float] Override the class-level temperature
-      # @param options [Hash] Agent parameters defined via the param DSL
-      # @raise [ArgumentError] If required parameters are missing
-      def initialize(model: self.class.model, temperature: self.class.temperature, **options)
-        @model = model
-        @temperature = temperature
-        @options = options
-        @accumulated_tool_calls = []
-        validate_required_params!
-        resolve_tenant_context!  # Resolve tenant before building client for API key resolution
-        @client = build_client
-      end
-
-      # @!group Template Methods (override in subclasses)
-
-      # User prompt to send to the LLM
-      #
-      # @abstract Subclasses must implement this method
-      # @return [String] The user prompt
-      # @raise [NotImplementedError] If not overridden in subclass
-      def user_prompt
-        raise NotImplementedError, "#{self.class} must implement #user_prompt"
-      end
-
-      # System prompt for LLM instructions
-      #
-      # @return [String, nil] System instructions, or nil for none
-      def system_prompt
-        nil
-      end
-
-      # Response schema for structured output
-      #
-      # @return [RubyLLM::Schema, nil] Schema definition, or nil for free-form
-      def schema
-        nil
-      end
-
-      # Conversation history for multi-turn conversations
-      #
-      # Override in subclass to provide conversation history.
-      # Messages will be added to the chat before the user_prompt.
-      #
-      # @return [Array<Hash>] Array of messages with :role and :content keys
-      # @example
-      #   def messages
-      #     [{ role: :user, content: "Hello" }, { role: :assistant, content: "Hi!" }]
-      #   end
-      def messages
-        []
-      end
-
-      # Post-processes the LLM response
-      #
-      # Override to transform the response before returning to the caller.
-      # Default implementation symbolizes hash keys.
-      #
-      # @param response [RubyLLM::Message] The raw response from the LLM
-      # @return [Object] The processed result
-      def process_response(response)
-        content = response.content
-        return content unless content.is_a?(Hash)
-        content.transform_keys(&:to_sym)
-      end
-
-      # @!endgroup
-
-      # Sets conversation history and rebuilds the client
-      #
-      # @param msgs [Array<Hash>] Messages with :role and :content keys
-      # @return [self] Returns self for chaining
-      # @example
-      #   agent.with_messages([{ role: :user, content: "Hi" }]).call
-      def with_messages(msgs)
-        @override_messages = msgs
-        @client = build_client
-        self
-      end
-    end
-  end
-end