ruby_llm-agents 0.4.0 → 1.0.0.beta.1

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

@@ -1,324 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "reliability_dsl"
-
-module RubyLLM
-  module Agents
-    class Base
-      # Class-level DSL for configuring agents
-      #
-      # Provides methods for setting model, temperature, timeout, caching,
-      # reliability, streaming, tools, and parameters.
-      module DSL
-        # @!visibility private
-        VERSION = "1.0"
-        # @!visibility private
-        CACHE_TTL = 1.hour
-
-        # @!group Configuration DSL
-
-        # Sets or returns the LLM model for this agent class
-        #
-        # @param value [String, nil] The model identifier to set
-        # @return [String] The current model setting
-        # @example
-        #   model "gpt-4o"
-        def model(value = nil)
-          @model = value if value
-          @model || inherited_or_default(:model, RubyLLM::Agents.configuration.default_model)
-        end
-
-        # Sets or returns the temperature for LLM responses
-        #
-        # @param value [Float, nil] Temperature value (0.0-2.0)
-        # @return [Float] The current temperature setting
-        # @example
-        #   temperature 0.7
-        def temperature(value = nil)
-          @temperature = value if value
-          @temperature || inherited_or_default(:temperature, RubyLLM::Agents.configuration.default_temperature)
-        end
-
-        # Sets or returns the version string for cache invalidation
-        #
-        # @param value [String, nil] Version string
-        # @return [String] The current version
-        # @example
-        #   version "2.0"
-        def version(value = nil)
-          @version = value if value
-          @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
-        # @return [Integer] The current timeout setting
-        # @example
-        #   timeout 30
-        def timeout(value = nil)
-          @timeout = value if value
-          @timeout || inherited_or_default(:timeout, RubyLLM::Agents.configuration.default_timeout)
-        end
-
-        # @!endgroup
-
-        # @!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)
-        # @param backoff [Symbol] Backoff strategy (:constant or :exponential)
-        # @param base [Float] Base delay in seconds
-        # @param max_delay [Float] Maximum delay between retries
-        # @param on [Array<Class>] Error classes to retry on (extends defaults)
-        # @return [Hash] The current retry configuration
-        # @example
-        #   retries max: 2, backoff: :exponential, base: 0.4, max_delay: 3.0, on: [Timeout::Error]
-        def retries(max: nil, backoff: nil, base: nil, max_delay: nil, on: nil)
-          if max || backoff || base || max_delay || on
-            @retries_config ||= RubyLLM::Agents.configuration.default_retries.dup
-            @retries_config[:max] = max if max
-            @retries_config[:backoff] = backoff if backoff
-            @retries_config[:base] = base if base
-            @retries_config[:max_delay] = max_delay if max_delay
-            @retries_config[:on] = on if on
-          end
-          @retries_config || inherited_or_default(:retries_config, RubyLLM::Agents.configuration.default_retries)
-        end
-
-        # Returns the retry configuration for this agent
-        #
-        # @return [Hash, nil] The retry configuration
-        def retries_config
-          @retries_config || (superclass.respond_to?(:retries_config) ? superclass.retries_config : nil)
-        end
-
-        # Sets or returns fallback models to try when primary model fails
-        #
-        # @param models [Array<String>, nil] Model identifiers to use as fallbacks
-        # @return [Array<String>] The current fallback models
-        # @example
-        #   fallback_models ["gpt-4o-mini", "gpt-4o"]
-        def fallback_models(models = nil)
-          @fallback_models = models if models
-          @fallback_models || inherited_or_default(:fallback_models, RubyLLM::Agents.configuration.default_fallback_models)
-        end
-
-        # Sets or returns the total timeout for all retry/fallback attempts
-        #
-        # @param seconds [Integer, nil] Total timeout in seconds
-        # @return [Integer, nil] The current total timeout
-        # @example
-        #   total_timeout 20
-        def total_timeout(seconds = nil)
-          @total_timeout = seconds if seconds
-          @total_timeout || inherited_or_default(:total_timeout, RubyLLM::Agents.configuration.default_total_timeout)
-        end
-
-        # Configures circuit breaker for this agent
-        #
-        # @param errors [Integer] Number of errors to trigger open state
-        # @param within [Integer] Rolling window in seconds
-        # @param cooldown [Integer] Cooldown period in seconds when open
-        # @return [Hash, nil] The current circuit breaker configuration
-        # @example
-        #   circuit_breaker errors: 10, within: 60, cooldown: 300
-        def circuit_breaker(errors: nil, within: nil, cooldown: nil)
-          if errors || within || cooldown
-            @circuit_breaker_config ||= { errors: 10, within: 60, cooldown: 300 }
-            @circuit_breaker_config[:errors] = errors if errors
-            @circuit_breaker_config[:within] = within if within
-            @circuit_breaker_config[:cooldown] = cooldown if cooldown
-          end
-          @circuit_breaker_config || (superclass.respond_to?(:circuit_breaker_config) ? superclass.circuit_breaker_config : nil)
-        end
-
-        # Returns the circuit breaker configuration for this agent
-        #
-        # @return [Hash, nil] The circuit breaker configuration
-        def circuit_breaker_config
-          @circuit_breaker_config || (superclass.respond_to?(:circuit_breaker_config) ? superclass.circuit_breaker_config : nil)
-        end
-
-        # @!endgroup
-
-        # @!group Parameter DSL
-
-        # Defines a parameter for the agent
-        #
-        # Creates an accessor method for the parameter that retrieves values
-        # from the options hash, falling back to the default value.
-        #
-        # @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 Without type (accepts anything)
-        #   param :query, required: true
-        #   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, type: type }
-          define_method(name) do
-            @options[name] || @options[name.to_s] || self.class.params.dig(name, :default)
-          end
-        end
-
-        # Returns all defined parameters including inherited ones
-        #
-        # @return [Hash{Symbol => Hash}] Parameter definitions
-        def params
-          parent = superclass.respond_to?(:params) ? superclass.params : {}
-          parent.merge(@params || {})
-        end
-
-        # @!endgroup
-
-        # @!group Caching DSL
-
-        # Enables caching for this agent with explicit TTL
-        #
-        # This is the preferred method for enabling caching.
-        #
-        # @param ttl [ActiveSupport::Duration] Time-to-live for cached responses
-        # @return [void]
-        # @example
-        #   cache_for 1.hour
-        #   cache_for 30.minutes
-        def cache_for(ttl)
-          @cache_enabled = true
-          @cache_ttl = ttl
-        end
-
-        # 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
-        def cache_enabled?
-          @cache_enabled || false
-        end
-
-        # Returns the cache TTL for this agent
-        #
-        # @return [ActiveSupport::Duration] The cache TTL
-        def cache_ttl
-          @cache_ttl || CACHE_TTL
-        end
-
-        # @!endgroup
-
-        # @!group Streaming DSL
-
-        # Enables or returns streaming mode for this agent
-        #
-        # When streaming is enabled and a block is passed to call,
-        # chunks will be yielded to the block as they arrive.
-        #
-        # @param value [Boolean, nil] Whether to enable streaming
-        # @return [Boolean] The current streaming setting
-        # @example
-        #   streaming true
-        def streaming(value = nil)
-          @streaming = value unless value.nil?
-          return @streaming unless @streaming.nil?
-
-          inherited_or_default(:streaming, RubyLLM::Agents.configuration.default_streaming)
-        end
-
-        # @!endgroup
-
-        # @!group Tools DSL
-
-        # Sets or returns the tools available to this agent
-        #
-        # Tools are RubyLLM::Tool classes that the model can invoke.
-        # The agent will automatically execute tool calls and continue
-        # until the model produces a final response.
-        #
-        # @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]
-        def tools(tool_classes = nil)
-          if tool_classes
-            @tools = Array(tool_classes)
-          end
-          @tools || inherited_or_default(:tools, RubyLLM::Agents.configuration.default_tools)
-        end
-
-        # @!endgroup
-
-        private
-
-        # Looks up setting from superclass or uses default
-        #
-        # @param method [Symbol] The method to call on superclass
-        # @param default [Object] Default value if not found
-        # @return [Object] The resolved value
-        def inherited_or_default(method, default)
-          superclass.respond_to?(method) ? superclass.send(method) : default
-        end
-      end
-    end
-  end
-end

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

@@ -1,283 +0,0 @@
-# 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 streaming_enabled? && 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 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.)
-        #
-        # @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 and types match
-        #
-        # @raise [ArgumentError] If required parameters are missing or types don't match
-        # @return [void]
-        def validate_required_params!
-          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
-        #
-        # @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.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
-        #
-        # @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_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