ruby_llm-agents 0.3.6 → 0.5.0

data/lib/generators/ruby_llm_agents/templates/create_api_configurations_migration.rb.tt

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# Migration to create the api_configurations table
+#
+# This table stores API key configurations that can be managed via the dashboard.
+# Supports both global settings and per-tenant overrides.
+#
+# Resolution priority: per-tenant DB > global DB > config file (RubyLLM.configure)
+#
+# Features:
+# - Encrypted storage for all API keys (using Rails encrypted attributes)
+# - Support for all major LLM providers
+# - Custom endpoint configuration
+# - Connection settings
+# - Default model configuration
+#
+# Run with: rails db:migrate
+class CreateRubyLLMAgentsApiConfigurations < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :ruby_llm_agents_api_configurations do |t|
+      # Scope type: 'global' or 'tenant'
+      t.string :scope_type, null: false, default: 'global'
+      # Tenant ID when scope_type='tenant'
+      t.string :scope_id
+
+      # === Encrypted API Keys ===
+      # Rails encrypts stores encrypted data in the same-named column
+      # Primary providers
+      t.text :openai_api_key
+      t.text :anthropic_api_key
+      t.text :gemini_api_key
+
+      # Additional providers
+      t.text :deepseek_api_key
+      t.text :mistral_api_key
+      t.text :perplexity_api_key
+      t.text :openrouter_api_key
+      t.text :gpustack_api_key
+      t.text :xai_api_key
+      t.text :ollama_api_key
+
+      # AWS Bedrock
+      t.text :bedrock_api_key
+      t.text :bedrock_secret_key
+      t.text :bedrock_session_token
+      t.string :bedrock_region
+
+      # Google Vertex AI
+      t.text :vertexai_credentials
+      t.string :vertexai_project_id
+      t.string :vertexai_location
+
+      # === Custom Endpoints ===
+      t.string :openai_api_base
+      t.string :gemini_api_base
+      t.string :ollama_api_base
+      t.string :gpustack_api_base
+      t.string :xai_api_base
+
+      # === OpenAI Options ===
+      t.string :openai_organization_id
+      t.string :openai_project_id
+
+      # === Default Models ===
+      t.string :default_model
+      t.string :default_embedding_model
+      t.string :default_image_model
+      t.string :default_moderation_model
+
+      # === Connection Settings ===
+      t.integer :request_timeout
+      t.integer :max_retries
+      t.decimal :retry_interval, precision: 5, scale: 2
+      t.decimal :retry_backoff_factor, precision: 5, scale: 2
+      t.decimal :retry_interval_randomness, precision: 5, scale: 2
+      t.string :http_proxy
+
+      # Whether to inherit from global config for unset values
+      t.boolean :inherit_global_defaults, default: true
+
+      t.timestamps
+    end
+
+    # Ensure unique scope_type + scope_id combinations
+    add_index :ruby_llm_agents_api_configurations, [:scope_type, :scope_id], unique: true, name: 'idx_api_configs_scope'
+
+    # Index for faster tenant lookups
+    add_index :ruby_llm_agents_api_configurations, :scope_id, name: 'idx_api_configs_scope_id'
+  end
+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
@@ -74,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)
@@ -162,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
@@ -186,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
@@ -243,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

@@ -17,6 +17,9 @@ module RubyLLM
         # @yieldparam chunk [RubyLLM::Chunk] A streaming chunk with content
         # @return [Object] The processed LLM response
         def call(&block)
+          # Resolve tenant configuration before execution
+          resolve_tenant_context!
+
           return dry_run_response if @options[:dry_run]
           return uncached_call(&block) if @options[:skip_cache] || !self.class.cache_enabled?
 
@@ -36,6 +39,52 @@ module RubyLLM
           end
         end
 
+        # Resolves tenant context from the :tenant option
+        #
+        # The tenant option can be:
+        # - String: Just the tenant_id (uses resolver or DB for config)
+        # - Hash: Full config { id:, name:, daily_limit:, daily_token_limit:, ... }
+        #
+        # @return [void]
+        def resolve_tenant_context!
+          # Idempotency guard - only resolve once
+          return if defined?(@tenant_context_resolved) && @tenant_context_resolved
+
+          tenant_option = @options[:tenant]
+          return unless tenant_option
+
+          if tenant_option.is_a?(Hash)
+            # Full config passed - extract id and store config
+            @tenant_id = tenant_option[:id]&.to_s
+            @tenant_config = tenant_option.except(:id)
+          else
+            # Just tenant_id passed
+            @tenant_id = tenant_option.to_s
+            @tenant_config = nil
+          end
+
+          @tenant_context_resolved = true
+        end
+
+        # Returns the resolved tenant ID
+        #
+        # @return [String, nil] The tenant identifier
+        def resolved_tenant_id
+          return @tenant_id if defined?(@tenant_id) && @tenant_id.present?
+
+          config = RubyLLM::Agents.configuration
+          return nil unless config.multi_tenancy_enabled?
+
+          config.current_tenant_id
+        end
+
+        # Returns the runtime tenant config (if passed via :tenant option)
+        #
+        # @return [Hash, nil] Runtime tenant configuration
+        def runtime_tenant_config
+          @tenant_config if defined?(@tenant_config)
+        end
+
         # Executes the agent without caching
         #
         # Routes to reliability-enabled execution if configured, otherwise
@@ -62,7 +111,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 +226,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,20 +247,37 @@ 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
         #
         # @return [RubyLLM::Chat] Configured chat client
         def build_client
+          # Apply database-backed API configuration if available
+          apply_api_configuration!
+
           client = RubyLLM.chat
             .with_model(model)
             .with_temperature(temperature)
@@ -212,11 +288,42 @@ module RubyLLM
           client
         end
 
+        # Applies database-backed API configuration to RubyLLM
+        #
+        # Resolution priority: per-tenant DB > global DB > RubyLLM.configure
+        # Only applies if the api_configurations table exists.
+        #
+        # @return [void]
+        def apply_api_configuration!
+          return unless api_configuration_available?
+
+          resolved_config = ApiConfiguration.resolve(tenant_id: resolved_tenant_id)
+          resolved_config.apply_to_ruby_llm!
+        rescue StandardError => e
+          Rails.logger.warn("[RubyLLM::Agents] Failed to apply API config: #{e.message}")
+        end
+
+        # Checks if API configuration table is available
+        #
+        # @return [Boolean] true if table exists and is accessible
+        def api_configuration_available?
+          return @api_config_available if defined?(@api_config_available)
+
+          @api_config_available = begin
+            ApiConfiguration.table_exists?
+          rescue StandardError
+            false
+          end
+        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)
+          # Apply database-backed API configuration if available
+          apply_api_configuration!
+
           client = RubyLLM.chat
             .with_model(model_id)
             .with_temperature(temperature)

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
@@ -109,6 +136,7 @@ module RubyLLM
         @options = options
         @accumulated_tool_calls = []
         validate_required_params!
+        resolve_tenant_context!  # Resolve tenant before building client for API key resolution
         @client = build_client
       end