ruby_llm-agents 0.4.0 → 1.0.0.beta.1

data/lib/ruby_llm/agents/core/resolved_config.rb

@@ -0,0 +1,348 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Resolves API configuration with priority chain
+    #
+    # Resolution order:
+    # 1. Tenant-specific database config (if tenant_id provided)
+    # 2. Global database config
+    # 3. RubyLLM.configuration (set via initializer or environment)
+    #
+    # This class provides a unified interface for accessing configuration
+    # values regardless of their source, and can apply the resolved
+    # configuration to RubyLLM.
+    #
+    # @example Basic resolution
+    #   resolved = ResolvedConfig.new(
+    #     tenant_config: ApiConfiguration.for_tenant("acme"),
+    #     global_config: ApiConfiguration.global,
+    #     ruby_llm_config: RubyLLM.configuration
+    #   )
+    #
+    #   resolved.openai_api_key     # => Returns from highest priority source
+    #   resolved.source_for(:openai_api_key)  # => "tenant:acme"
+    #
+    # @example Applying to RubyLLM
+    #   resolved.apply_to_ruby_llm!  # Applies all resolved values
+    #
+    # @see ApiConfiguration
+    # @api public
+    class ResolvedConfig
+      # Returns all resolvable attributes (API keys + settings)
+      # Lazy-loaded to avoid circular dependency with ApiConfiguration
+      #
+      # @return [Array<Symbol>]
+      def self.resolvable_attributes
+        @resolvable_attributes ||= (
+          ApiConfiguration::API_KEY_ATTRIBUTES +
+          ApiConfiguration::NON_KEY_ATTRIBUTES
+        ).freeze
+      end
+
+      # @return [ApiConfiguration, nil] Tenant-specific configuration
+      attr_reader :tenant_config
+
+      # @return [ApiConfiguration, nil] Global database configuration
+      attr_reader :global_config
+
+      # @return [Object] RubyLLM configuration object
+      attr_reader :ruby_llm_config
+
+      # Creates a new resolved configuration
+      #
+      # @param tenant_config [ApiConfiguration, nil] Tenant-specific config
+      # @param global_config [ApiConfiguration, nil] Global database config
+      # @param ruby_llm_config [Object] RubyLLM.configuration
+      def initialize(tenant_config:, global_config:, ruby_llm_config:)
+        @tenant_config = tenant_config
+        @global_config = global_config
+        @ruby_llm_config = ruby_llm_config
+        @resolved_cache = {}
+      end
+
+      # Resolves a specific attribute value using the priority chain
+      #
+      # @param attr_name [Symbol, String] The attribute name
+      # @return [Object, nil] The resolved value
+      def resolve(attr_name)
+        attr_sym = attr_name.to_sym
+        return @resolved_cache[attr_sym] if @resolved_cache.key?(attr_sym)
+
+        @resolved_cache[attr_sym] = resolve_attribute(attr_sym)
+      end
+
+      # Returns the source of a resolved attribute value
+      #
+      # @param attr_name [Symbol, String] The attribute name
+      # @return [String] Source label: "tenant:ID", "global_db", "ruby_llm_config", or "not_set"
+      def source_for(attr_name)
+        attr_sym = attr_name.to_sym
+
+        # Check tenant config first (if present and inherits or has value)
+        if tenant_config&.has_value?(attr_sym)
+          return "tenant:#{tenant_config.scope_id}"
+        end
+
+        # Check global DB config (only if tenant inherits or no tenant)
+        if should_check_global?(attr_sym) && global_config&.has_value?(attr_sym)
+          return "global_db"
+        end
+
+        # Check RubyLLM config
+        if ruby_llm_value_present?(attr_sym)
+          return "ruby_llm_config"
+        end
+
+        "not_set"
+      end
+
+      # Returns all resolved values as a hash
+      #
+      # @return [Hash] All resolved configuration values
+      def to_hash
+        self.class.resolvable_attributes.each_with_object({}) do |attr, hash|
+          value = resolve(attr)
+          hash[attr] = value if value.present?
+        end
+      end
+
+      # Returns a hash suitable for RubyLLM configuration
+      #
+      # Only includes values that differ from or override the current
+      # RubyLLM configuration.
+      #
+      # @return [Hash] Configuration hash for RubyLLM
+      def to_ruby_llm_options
+        to_hash.slice(*ruby_llm_configurable_attributes)
+      end
+
+      # Applies the resolved configuration to RubyLLM
+      #
+      # This temporarily overrides RubyLLM.configuration with the
+      # resolved values. Useful for per-request configuration.
+      #
+      # @return [void]
+      def apply_to_ruby_llm!
+        options = to_ruby_llm_options
+        return if options.empty?
+
+        RubyLLM.configure do |config|
+          options.each do |key, value|
+            setter = "#{key}="
+            config.public_send(setter, value) if config.respond_to?(setter)
+          end
+        end
+      end
+
+      # Dynamic accessor for resolvable attributes
+      # Uses method_missing to provide accessors without eager loading constants
+      #
+      # @param method_name [Symbol] The method being called
+      # @param args [Array] Method arguments
+      # @return [Object] The resolved value for the attribute
+      def method_missing(method_name, *args)
+        if self.class.resolvable_attributes.include?(method_name)
+          resolve(method_name)
+        else
+          super
+        end
+      end
+
+      # Indicates which dynamic methods are supported
+      #
+      # @param method_name [Symbol] The method name to check
+      # @param include_private [Boolean] Whether to include private methods
+      # @return [Boolean] True if the method is a resolvable attribute
+      def respond_to_missing?(method_name, include_private = false)
+        self.class.resolvable_attributes.include?(method_name) || super
+      end
+
+      # Returns provider status with source information
+      #
+      # @return [Array<Hash>] Provider status with source info
+      def provider_statuses_with_source
+        ApiConfiguration::PROVIDERS.map do |key, info|
+          key_attr = info[:key_attr]
+          value = resolve(key_attr)
+
+          {
+            key: key,
+            name: info[:name],
+            configured: value.present?,
+            masked_key: value.present? ? mask_string(value) : nil,
+            source: source_for(key_attr),
+            capabilities: info[:capabilities]
+          }
+        end
+      end
+
+      # Checks if any database configuration exists
+      #
+      # @return [Boolean]
+      def has_db_config?
+        tenant_config.present? || global_config.present?
+      end
+
+      # Returns summary of configuration sources
+      #
+      # @return [Hash] Summary with counts per source
+      def source_summary
+        summary = Hash.new(0)
+
+        self.class.resolvable_attributes.each do |attr|
+          source = source_for(attr)
+          summary[source] += 1 if resolve(attr).present?
+        end
+
+        summary
+      end
+
+      # Public method to get raw RubyLLM config value for an attribute
+      # This returns the value from RubyLLM.configuration (initializer/ENV)
+      # regardless of any database overrides.
+      #
+      # @param attr_name [Symbol, String] The attribute name
+      # @return [Object, nil] The RubyLLM config value
+      def ruby_llm_value_for(attr_name)
+        ruby_llm_value(attr_name.to_sym)
+      end
+
+      # Masks a string for display (public wrapper)
+      #
+      # @param value [String] The string to mask
+      # @return [String] Masked string
+      def mask_string(value)
+        return nil if value.blank?
+        return "****" if value.length <= 8
+
+        "#{value[0..1]}****#{value[-4..]}"
+      end
+
+      private
+
+      # Resolves a single attribute using the priority chain
+      #
+      # @param attr_sym [Symbol] The attribute name
+      # @return [Object, nil] The resolved value
+      def resolve_attribute(attr_sym)
+        # 1. Check tenant config
+        if tenant_config&.has_value?(attr_sym)
+          return tenant_config.send(attr_sym)
+        end
+
+        # 2. Check global DB config (if tenant allows inheritance or no tenant)
+        if should_check_global?(attr_sym)
+          if global_config&.has_value?(attr_sym)
+            return global_config.send(attr_sym)
+          end
+        end
+
+        # 3. Fall back to RubyLLM config
+        ruby_llm_value(attr_sym)
+      end
+
+      # Determines if we should check global config
+      #
+      # @param attr_sym [Symbol] The attribute name
+      # @return [Boolean]
+      def should_check_global?(attr_sym)
+        return true unless tenant_config
+
+        # If tenant has inherit_global_defaults enabled, check global
+        tenant_config.inherit_global_defaults != false
+      end
+
+      # Gets a value from RubyLLM configuration
+      #
+      # @param attr_sym [Symbol] The attribute name
+      # @return [Object, nil]
+      def ruby_llm_value(attr_sym)
+        return nil unless ruby_llm_config
+
+        # Map our attribute names to RubyLLM config method names
+        method_name = ruby_llm_config_mapping(attr_sym)
+        return nil unless method_name
+
+        if ruby_llm_config.respond_to?(method_name)
+          ruby_llm_config.send(method_name)
+        end
+      rescue StandardError
+        nil
+      end
+
+      # Checks if a RubyLLM config value is present
+      #
+      # @param attr_sym [Symbol] The attribute name
+      # @return [Boolean]
+      def ruby_llm_value_present?(attr_sym)
+        value = ruby_llm_value(attr_sym)
+        value.present?
+      end
+
+      # Maps our attribute names to RubyLLM configuration method names
+      #
+      # @param attr_sym [Symbol] Our attribute name
+      # @return [Symbol, nil] RubyLLM config method name
+      def ruby_llm_config_mapping(attr_sym)
+        # Most attributes map directly
+        mapping = {
+          openai_api_key: :openai_api_key,
+          anthropic_api_key: :anthropic_api_key,
+          gemini_api_key: :gemini_api_key,
+          deepseek_api_key: :deepseek_api_key,
+          mistral_api_key: :mistral_api_key,
+          perplexity_api_key: :perplexity_api_key,
+          openrouter_api_key: :openrouter_api_key,
+          gpustack_api_key: :gpustack_api_key,
+          xai_api_key: :xai_api_key,
+          ollama_api_key: :ollama_api_key,
+          bedrock_api_key: :bedrock_api_key,
+          bedrock_secret_key: :bedrock_secret_key,
+          bedrock_session_token: :bedrock_session_token,
+          bedrock_region: :bedrock_region,
+          vertexai_credentials: :vertexai_credentials,
+          vertexai_project_id: :vertexai_project_id,
+          vertexai_location: :vertexai_location,
+          openai_api_base: :openai_api_base,
+          gemini_api_base: :gemini_api_base,
+          ollama_api_base: :ollama_api_base,
+          gpustack_api_base: :gpustack_api_base,
+          xai_api_base: :xai_api_base,
+          openai_organization_id: :openai_organization_id,
+          openai_project_id: :openai_project_id,
+          default_model: :default_model,
+          default_embedding_model: :default_embedding_model,
+          default_image_model: :default_image_model,
+          default_moderation_model: :default_moderation_model,
+          request_timeout: :request_timeout,
+          max_retries: :max_retries,
+          retry_interval: :retry_interval,
+          retry_backoff_factor: :retry_backoff_factor,
+          retry_interval_randomness: :retry_interval_randomness,
+          http_proxy: :http_proxy
+        }
+
+        mapping[attr_sym]
+      end
+
+      # Returns attributes that can be set on RubyLLM configuration
+      #
+      # @return [Array<Symbol>]
+      def ruby_llm_configurable_attributes
+        ApiConfiguration::API_KEY_ATTRIBUTES +
+          ApiConfiguration::ENDPOINT_ATTRIBUTES +
+          ApiConfiguration::MODEL_ATTRIBUTES +
+          ApiConfiguration::CONNECTION_ATTRIBUTES +
+          %i[
+            openai_organization_id
+            openai_project_id
+            bedrock_region
+            vertexai_project_id
+            vertexai_location
+          ]
+      end
+
+    end
+  end
+end

data/lib/ruby_llm/agents/{version.rb → core/version.rb}

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

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

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module DSL
+      # Base DSL available to all agents.
+      #
+      # Provides common configuration methods that every agent type needs:
+      # - model: The LLM model to use
+      # - version: Cache invalidation version
+      # - description: Human-readable description
+      # - timeout: Request timeout
+      #
+      # @example Basic usage
+      #   class MyAgent < RubyLLM::Agents::BaseAgent
+      #     extend DSL::Base
+      #
+      #     model "gpt-4o"
+      #     version "2.0"
+      #     description "A helpful agent"
+      #   end
+      #
+      module Base
+        # @!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, default_model)
+        end
+
+        # Sets or returns the version string for cache invalidation
+        #
+        # Change this when you want to invalidate cached results
+        # (e.g., after changing prompts or behavior).
+        #
+        # @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, "1.0")
+        end
+
+        # Sets or returns the description for this agent class
+        #
+        # Useful for documentation and tool registration.
+        #
+        # @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, default_timeout)
+        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)
+          return default unless superclass.respond_to?(method)
+
+          superclass.send(method)
+        end
+
+        # Returns the default model from configuration
+        #
+        # @return [String] The default model
+        def default_model
+          RubyLLM::Agents.configuration.default_model
+        rescue StandardError
+          "gpt-4o"
+        end
+
+        # Returns the default timeout from configuration
+        #
+        # @return [Integer] The default timeout
+        def default_timeout
+          RubyLLM::Agents.configuration.default_timeout
+        rescue StandardError
+          120
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module DSL
+      # Caching DSL for agent response caching.
+      #
+      # This module provides configuration methods for caching features
+      # that can be mixed into any agent class.
+      #
+      # @example Basic usage
+      #   class MyAgent < RubyLLM::Agents::BaseAgent
+      #     extend DSL::Caching
+      #
+      #     cache_for 1.hour
+      #   end
+      #
+      # @example With conditional caching
+      #   class MyAgent < RubyLLM::Agents::BaseAgent
+      #     extend DSL::Caching
+      #
+      #     cache_for 30.minutes
+      #     cache_key_includes :user_id, :query
+      #   end
+      #
+      module Caching
+        # Default cache TTL when none specified
+        DEFAULT_CACHE_TTL = 1.hour
+
+        # @!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
+
+        # Alias for cache_for (for backward compatibility)
+        alias cache cache_for
+
+        # Returns whether caching is enabled for this agent
+        #
+        # Caching IS inherited from parent classes following Ruby patterns.
+        #
+        # @return [Boolean] true if caching is enabled
+        def cache_enabled?
+          return @cache_enabled if defined?(@cache_enabled)
+
+          inherited_cache_enabled
+        end
+
+        # Returns the cache TTL for this agent
+        #
+        # @return [ActiveSupport::Duration] The cache TTL
+        def cache_ttl
+          @cache_ttl || inherited_cache_ttl || DEFAULT_CACHE_TTL
+        end
+
+        # Specifies which parameters should be included in the cache key
+        #
+        # By default, all options except :skip_cache and :dry_run are included.
+        # Use this to explicitly define which parameters affect caching.
+        #
+        # @param keys [Array<Symbol>] Parameter keys to include in cache key
+        # @return [Array<Symbol>, nil] The current cache key includes
+        # @example
+        #   cache_key_includes :user_id, :query, :context
+        def cache_key_includes(*keys)
+          @cache_key_includes = keys.flatten if keys.any?
+          @cache_key_includes || inherited_cache_key_includes
+        end
+
+        # Specifies which parameters should be excluded from the cache key
+        #
+        # @param keys [Array<Symbol>] Parameter keys to exclude from cache key
+        # @return [Array<Symbol>] The current cache key excludes
+        # @example
+        #   cache_key_excludes :timestamp, :request_id
+        def cache_key_excludes(*keys)
+          @cache_key_excludes = keys.flatten if keys.any?
+          @cache_key_excludes || inherited_cache_key_excludes || default_cache_key_excludes
+        end
+
+        # Returns the complete caching configuration hash
+        #
+        # Used by the Cache middleware to get all settings.
+        #
+        # @return [Hash, nil] The caching configuration
+        def caching_config
+          return nil unless cache_enabled?
+
+          {
+            enabled: true,
+            ttl: cache_ttl,
+            key_includes: cache_key_includes,
+            key_excludes: cache_key_excludes
+          }.compact
+        end
+
+        # @!endgroup
+
+        private
+
+        def inherited_cache_enabled
+          return false unless superclass.respond_to?(:cache_enabled?)
+
+          superclass.cache_enabled?
+        end
+
+        def inherited_cache_ttl
+          return nil unless superclass.respond_to?(:cache_ttl)
+
+          superclass.cache_ttl
+        end
+
+        def inherited_cache_key_includes
+          return nil unless superclass.respond_to?(:cache_key_includes)
+
+          superclass.cache_key_includes
+        end
+
+        def inherited_cache_key_excludes
+          return nil unless superclass.respond_to?(:cache_key_excludes)
+
+          superclass.cache_key_excludes
+        end
+
+        def default_cache_key_excludes
+          %i[skip_cache dry_run with]
+        end
+      end
+    end
+  end
+end