ruby_llm-agents 0.3.3 → 0.3.5

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Migration to create the tenant_budgets table for multi-tenancy support
+#
+# This table stores per-tenant budget configuration, allowing different
+# tenants to have their own budget limits and enforcement modes.
+#
+# Features:
+# - Per-tenant daily and monthly budget limits
+# - Per-agent budget limits within a tenant
+# - Configurable enforcement mode (none, soft, hard)
+# - Option to inherit global defaults for unset limits
+#
+# Run with: rails db:migrate
+class CreateRubyLLMAgentsTenantBudgets < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :ruby_llm_agents_tenant_budgets do |t|
+      # Unique identifier for the tenant (e.g., organization ID, workspace ID)
+      t.string :tenant_id, null: false
+
+      # Global budget limits for this tenant
+      t.decimal :daily_limit, precision: 12, scale: 6
+      t.decimal :monthly_limit, precision: 12, scale: 6
+
+      # Per-agent budget limits (JSON hash)
+      # Format: { "AgentName" => limit_value }
+      t.json :per_agent_daily, null: false, default: {}
+      t.json :per_agent_monthly, null: false, default: {}
+
+      # Enforcement mode for this tenant: "none", "soft", or "hard"
+      # - none: no enforcement, only tracking
+      # - soft: log warnings when limits exceeded
+      # - hard: block execution when limits exceeded
+      t.string :enforcement, default: "soft"
+
+      # Whether to inherit from global config for unset limits
+      t.boolean :inherit_global_defaults, default: true
+
+      t.timestamps
+    end
+
+    # Ensure unique tenant IDs
+    add_index :ruby_llm_agents_tenant_budgets, :tenant_id, unique: true
+  end
+end

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

@@ -54,10 +54,10 @@ class CreateRubyLLMAgentsExecutions < ActiveRecord::Migration<%= migration_versi
       t.decimal :output_cost, precision: 12, scale: 6
       t.decimal :total_cost, precision: 12, scale: 6
 
-      # Data (JSONB for PostgreSQL, JSON for others)
-      t.jsonb :parameters, null: false, default: {}
-      t.jsonb :response, default: {}
-      t.jsonb :metadata, null: false, default: {}
+      # Data (JSON - works with PostgreSQL, MySQL, SQLite3)
+      t.json :parameters, null: false, default: {}
+      t.json :response, default: {}
+      t.json :metadata, null: false, default: {}
 
       # Error tracking
       t.string :error_class
@@ -68,9 +68,16 @@ class CreateRubyLLMAgentsExecutions < ActiveRecord::Migration<%= migration_versi
       t.text :user_prompt
 
       # Tool calls tracking
-      t.jsonb :tool_calls, null: false, default: []
+      t.json :tool_calls, null: false, default: []
       t.integer :tool_calls_count, null: false, default: 0
 
+      # Workflow orchestration
+      t.string :workflow_id
+      t.string :workflow_type
+      t.string :workflow_step
+      t.string :routed_to
+      t.json :classification_result
+
       t.timestamps
     end
 
@@ -96,6 +103,11 @@ class CreateRubyLLMAgentsExecutions < ActiveRecord::Migration<%= migration_versi
     # Tool calls index
     add_index :ruby_llm_agents_executions, :tool_calls_count
 
+    # Workflow indexes
+    add_index :ruby_llm_agents_executions, :workflow_id
+    add_index :ruby_llm_agents_executions, :workflow_type
+    add_index :ruby_llm_agents_executions, [:workflow_id, :workflow_step]
+
     # Foreign keys for execution hierarchy
     add_foreign_key :ruby_llm_agents_executions, :ruby_llm_agents_executions,
                     column: :parent_execution_id, on_delete: :nullify

data/lib/generators/ruby_llm_agents/upgrade_generator.rb

@@ -120,6 +120,19 @@ module RubyLlmAgents
       )
     end
 
+    def create_add_workflow_migration
+      # Check if columns already exist
+      if column_exists?(:ruby_llm_agents_executions, :workflow_id)
+        say_status :skip, "workflow_id column already exists", :yellow
+        return
+      end
+
+      migration_template(
+        "add_workflow_migration.rb.tt",
+        File.join(db_migrate_path, "add_workflow_to_ruby_llm_agents_executions.rb")
+      )
+    end
+
     def show_post_upgrade_message
       say ""
       say "RubyLLM::Agents upgrade migration created!", :green

data/lib/ruby_llm/agents/alert_manager.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "net/http"
+require "faraday"
 require "json"
 
 module RubyLLM
@@ -177,30 +177,34 @@ module RubyLLM
           end
         end
 
-        # Posts JSON to a URL
+        # Posts JSON to a URL using Faraday
         #
         # @param url [String] The URL
         # @param payload [Hash] The payload
-        # @return [Net::HTTPResponse]
+        # @return [Faraday::Response]
         def post_json(url, payload)
-          uri = URI.parse(url)
-          http = Net::HTTP.new(uri.host, uri.port)
-          http.use_ssl = uri.scheme == "https"
-          http.open_timeout = 5
-          http.read_timeout = 10
-
-          request = Net::HTTP::Post.new(uri.request_uri)
-          request["Content-Type"] = "application/json"
-          request.body = payload.to_json
-
-          response = http.request(request)
+          response = http_client.post(url) do |req|
+            req.headers["Content-Type"] = "application/json"
+            req.body = payload.to_json
+          end
 
-          unless response.is_a?(Net::HTTPSuccess)
-            Rails.logger.warn("[RubyLLM::Agents::AlertManager] Webhook returned #{response.code}: #{response.body}")
+          unless response.success?
+            Rails.logger.warn("[RubyLLM::Agents::AlertManager] Webhook returned #{response.status}: #{response.body}")
           end
 
           response
         end
+
+        # Returns a configured Faraday HTTP client
+        #
+        # @return [Faraday::Connection]
+        def http_client
+          @http_client ||= Faraday.new do |conn|
+            conn.options.open_timeout = 5
+            conn.options.timeout = 10
+            conn.adapter Faraday.default_adapter
+          end
+        end
       end
     end
   end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "../cache_helper"
+
+module RubyLLM
+  module Agents
+    class Base
+      # Cache management for agent responses
+      #
+      # Handles cache key generation and store access for
+      # caching agent execution results.
+      module Caching
+        include CacheHelper
+
+        # Generates the full cache key for this agent invocation
+        #
+        # @return [String] Cache key in format "ruby_llm_agent/ClassName/version/hash"
+        def agent_cache_key
+          ["ruby_llm_agent", self.class.name, self.class.version, cache_key_hash].join("/")
+        end
+
+        # Generates a hash of the cache key data
+        #
+        # @return [String] SHA256 hex digest of the cache key data
+        def cache_key_hash
+          Digest::SHA256.hexdigest(cache_key_data.to_json)
+        end
+
+        # Returns data to include in cache key generation
+        #
+        # Override to customize what parameters affect cache invalidation.
+        #
+        # @return [Hash] Data to hash for cache key
+        def cache_key_data
+          @options.except(:skip_cache, :dry_run, :with)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class Base
+      # Cost calculation methods for token and pricing calculations
+      #
+      # Handles input/output cost calculations, model info resolution,
+      # and budget tracking for agent executions.
+      module CostCalculation
+        # Calculates input cost from tokens
+        #
+        # @param input_tokens [Integer, nil] Number of input tokens
+        # @param response_model_id [String, nil] Model that responded
+        # @return [Float, nil] Input cost in USD
+        def result_input_cost(input_tokens, response_model_id)
+          return nil unless input_tokens
+          model_info = result_model_info(response_model_id)
+          return nil unless model_info&.pricing
+          price = model_info.pricing.text_tokens&.input || 0
+          (input_tokens / 1_000_000.0 * price).round(6)
+        end
+
+        # Calculates output cost from tokens
+        #
+        # @param output_tokens [Integer, nil] Number of output tokens
+        # @param response_model_id [String, nil] Model that responded
+        # @return [Float, nil] Output cost in USD
+        def result_output_cost(output_tokens, response_model_id)
+          return nil unless output_tokens
+          model_info = result_model_info(response_model_id)
+          return nil unless model_info&.pricing
+          price = model_info.pricing.text_tokens&.output || 0
+          (output_tokens / 1_000_000.0 * price).round(6)
+        end
+
+        # Calculates total cost from tokens
+        #
+        # @param input_tokens [Integer, nil] Number of input tokens
+        # @param output_tokens [Integer, nil] Number of output tokens
+        # @param response_model_id [String, nil] Model that responded
+        # @return [Float, nil] Total cost in USD
+        def result_total_cost(input_tokens, output_tokens, response_model_id)
+          input_cost = result_input_cost(input_tokens, response_model_id)
+          output_cost = result_output_cost(output_tokens, response_model_id)
+          return nil unless input_cost || output_cost
+          ((input_cost || 0) + (output_cost || 0)).round(6)
+        end
+
+        # Resolves model info for cost calculation
+        #
+        # @param response_model_id [String, nil] Model ID from response
+        # @return [Object, nil] Model info or nil
+        def result_model_info(response_model_id)
+          lookup_id = response_model_id || model
+          return nil unless lookup_id
+          model_obj, _provider = RubyLLM::Models.resolve(lookup_id)
+          model_obj
+        rescue StandardError
+          nil
+        end
+
+        # Resolves model info for cost calculation (alternate method)
+        #
+        # @param model_id [String] The model identifier
+        # @return [Object, nil] Model info or nil
+        def resolve_model_info(model_id)
+          model_obj, _provider = RubyLLM::Models.resolve(model_id)
+          model_obj
+        rescue StandardError
+          nil
+        end
+
+        # Records cost from an attempt to the budget tracker
+        #
+        # @param attempt_tracker [AttemptTracker] The attempt tracker
+        # @param tenant_id [String, nil] Optional tenant identifier for multi-tenant tracking
+        # @return [void]
+        def record_attempt_cost(attempt_tracker, tenant_id: nil)
+          successful = attempt_tracker.successful_attempt
+          return unless successful
+
+          # Calculate cost for this execution
+          # Note: Full cost calculation happens in instrumentation, but we
+          # record the spend here for budget tracking
+          model_info = resolve_model_info(successful[:model_id])
+          return unless model_info&.pricing
+
+          input_tokens = successful[:input_tokens] || 0
+          output_tokens = successful[:output_tokens] || 0
+
+          input_price = model_info.pricing.text_tokens&.input || 0
+          output_price = model_info.pricing.text_tokens&.output || 0
+
+          total_cost = (input_tokens / 1_000_000.0 * input_price) +
+                       (output_tokens / 1_000_000.0 * output_price)
+
+          BudgetTracker.record_spend!(self.class.name, total_cost, tenant_id: tenant_id)
+        rescue StandardError => e
+          Rails.logger.warn("[RubyLLM::Agents] Failed to record budget spend: #{e.message}")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+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 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 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
+        # @return [void]
+        # @example
+        #   param :query, required: true
+        #   param :limit, default: 10
+        def param(name, required: false, default: nil)
+          @params ||= {}
+          @params[name] = { required: required, default: default }
+          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 optional TTL
+        #
+        # @param ttl [ActiveSupport::Duration] Time-to-live for cached responses
+        # @return [void]
+        # @example
+        #   cache 1.hour
+        def cache(ttl = CACHE_TTL)
+          @cache_enabled = true
+          @cache_ttl = 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 Single tool
+        #   tools WeatherTool
+        # @example Multiple tools
+        #   tools WeatherTool, SearchTool, CalculatorTool
+        def tools(*tool_classes)
+          if tool_classes.any?
+            @tools = tool_classes.flatten
+          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