ruby_llm-agents 1.3.3 → 2.0.0

data/lib/ruby_llm/agents/image/pipeline/execution.rb

@@ -249,7 +249,6 @@ module RubyLLM
             "ruby_llm_agents",
             "image_pipeline",
             self.class.name,
-            self.class.version,
             Digest::SHA256.hexdigest(cache_key_input)
           ]
           components.join(":")

data/lib/ruby_llm/agents/image/transformer/dsl.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require_relative "../concerns/image_operation_dsl"
-require_relative "../generator/content_policy"
 
 module RubyLLM
   module Agents
@@ -70,18 +69,6 @@ module RubyLLM
           end
         end
 
-        # Set or get the content policy level
-        #
-        # @param level [Symbol, nil] Policy level (:none, :standard, :moderate, :strict)
-        # @return [Symbol] The content policy level
-        def content_policy(level = nil)
-          if level
-            @content_policy = level
-          else
-            @content_policy || inherited_or_default(:content_policy, :standard)
-          end
-        end
-
         # Set a prompt template (use {prompt} as placeholder)
         #
         # @param value [String, nil] Template string

data/lib/ruby_llm/agents/image/transformer/execution.rb

@@ -23,7 +23,6 @@ module RubyLLM
           resolve_tenant_context!
           check_budget! if budget_tracking_enabled?
           validate_inputs!
-          validate_content_policy!
 
           # Check cache
           cached = check_cache(ImageTransformResult) if cache_enabled?
@@ -75,13 +74,6 @@ module RubyLLM
           end
         end
 
-        def validate_content_policy!
-          policy = self.class.content_policy
-          return if policy == :none || policy == :standard
-
-          ImageGenerator::ContentPolicy.validate!(prompt, policy)
-        end
-
         def transform_images
           count = resolve_count
 
@@ -188,7 +180,6 @@ module RubyLLM
           [
             "image_transformer",
             self.class.name,
-            self.class.version,
             resolve_model,
             resolve_size,
             resolve_strength.to_s,
@@ -209,7 +200,7 @@ module RubyLLM
           end
         end
 
-        def build_execution_metadata(result)
+        def build_metadata(result)
           {
             count: result.count,
             size: result.size,

data/lib/ruby_llm/agents/image/transformer.rb

@@ -57,7 +57,6 @@ module RubyLLM
           subclass.instance_variable_set(:@version, @version)
           subclass.instance_variable_set(:@description, @description)
           subclass.instance_variable_set(:@cache_ttl, @cache_ttl)
-          subclass.instance_variable_set(:@content_policy, @content_policy)
           subclass.instance_variable_set(:@template_string, @template_string)
           subclass.instance_variable_set(:@negative_prompt, @negative_prompt)
           subclass.instance_variable_set(:@guidance_scale, @guidance_scale)

data/lib/ruby_llm/agents/image/upscaler/execution.rb

@@ -186,7 +186,6 @@ module RubyLLM
           [
             "image_upscaler",
             self.class.name,
-            self.class.version,
             resolve_model,
             resolve_scale.to_s,
             resolve_face_enhance.to_s,
@@ -206,7 +205,7 @@ module RubyLLM
           end
         end
 
-        def build_execution_metadata(result)
+        def build_metadata(result)
           {
             scale: result.scale,
             output_size: result.output_size,

data/lib/ruby_llm/agents/image/variator/execution.rb

@@ -156,7 +156,6 @@ module RubyLLM
           [
             "image_variator",
             self.class.name,
-            self.class.version,
             resolve_model,
             resolve_size,
             resolve_variation_strength.to_s,
@@ -176,7 +175,7 @@ module RubyLLM
           end
         end
 
-        def build_execution_metadata(result)
+        def build_metadata(result)
           {
             count: result.count,
             size: result.size,

data/lib/ruby_llm/agents/infrastructure/alert_manager.rb

@@ -1,127 +1,85 @@
 # frozen_string_literal: true
 
-require "net/http"
-require "uri"
-require "json"
-
 module RubyLLM
   module Agents
     # Alert notification dispatcher for governance events
     #
-    # Sends notifications to configured destinations (Slack, webhooks, custom procs)
+    # Sends notifications via user-provided handler and ActiveSupport::Notifications
     # when important events occur like budget exceedance or circuit breaker activation.
     #
-    # @example Sending an alert
-    #   AlertManager.notify(:budget_soft_cap, { limit: 25.0, total: 27.5 })
+    # @example Configure an alert handler
+    #   RubyLLM::Agents.configure do |config|
+    #     config.on_alert = ->(event, payload) {
+    #       case event
+    #       when :budget_hard_cap
+    #         Slack::Notifier.new(ENV["SLACK_WEBHOOK"]).ping("Budget exceeded")
+    #       end
+    #     }
+    #   end
+    #
+    # @example Subscribe via ActiveSupport::Notifications
+    #   ActiveSupport::Notifications.subscribe(/^ruby_llm_agents\.alert\./) do |name, _, _, _, payload|
+    #     event = name.sub("ruby_llm_agents.alert.", "").to_sym
+    #     MyAlertService.handle(event, payload)
+    #   end
     #
-    # @see RubyLLM::Agents::Configuration
+    # @see RubyLLM::Agents::Configuration#on_alert
     # @api public
     module AlertManager
       class << self
-        # Sends a notification to all configured destinations
+        # Sends a notification to the configured handler and emits AS::N
         #
         # @param event [Symbol] The event type (e.g., :budget_soft_cap, :breaker_open)
         # @param payload [Hash] Event-specific data
         # @return [void]
         def notify(event, payload)
-          config = RubyLLM::Agents.configuration
-          return unless config.alerts_enabled?
-          return unless config.alert_events.include?(event)
-
-          alerts = config.alerts
-          full_payload = payload.merge(event: event)
-
-          # Send to Slack
-          if alerts[:slack_webhook_url].present?
-            send_slack_alert(alerts[:slack_webhook_url], event, full_payload)
-          end
-
-          # Send to generic webhook
-          if alerts[:webhook_url].present?
-            send_webhook_alert(alerts[:webhook_url], full_payload)
-          end
-
-          # Call custom proc
-          if alerts[:custom].respond_to?(:call)
-            call_custom_alert(alerts[:custom], event, full_payload)
-          end
+          full_payload = build_payload(event, payload)
 
-          # Send email alerts
-          if alerts[:email_recipients].present?
-            email_events = alerts[:email_events] || config.alert_events
-            if email_events.include?(event)
-              send_email_alerts(event, full_payload, alerts[:email_recipients])
-            end
-          end
+          # Call user-provided handler (if set)
+          call_handler(event, full_payload)
 
-          # Emit ActiveSupport::Notification for observability
+          # Always emit ActiveSupport::Notification
           emit_notification(event, full_payload)
+
+          # Store in cache for dashboard display
+          store_for_dashboard(event, full_payload)
         rescue StandardError => e
-          # Don't let alert failures break the application
-          Rails.logger.error("[RubyLLM::Agents::AlertManager] Failed to send alert: #{e.message}")
+          Rails.logger.error("[RubyLLM::Agents::AlertManager] Failed: #{e.message}")
         end
 
         private
 
-        # Sends a Slack webhook alert
+        # Builds the full payload with standard fields
         #
-        # @param webhook_url [String] The Slack webhook URL
         # @param event [Symbol] The event type
-        # @param payload [Hash] The payload
-        # @return [void]
-        def send_slack_alert(webhook_url, event, payload)
-          message = format_slack_message(event, payload)
-
-          post_json(webhook_url, message)
-        rescue StandardError => e
-          Rails.logger.warn("[RubyLLM::Agents::AlertManager] Slack alert failed: #{e.message}")
-        end
-
-        # Sends a generic webhook alert
-        #
-        # @param webhook_url [String] The webhook URL
-        # @param payload [Hash] The payload
-        # @return [void]
-        def send_webhook_alert(webhook_url, payload)
-          post_json(webhook_url, payload)
-        rescue StandardError => e
-          Rails.logger.warn("[RubyLLM::Agents::AlertManager] Webhook alert failed: #{e.message}")
+        # @param payload [Hash] The original payload
+        # @return [Hash] Payload with event, timestamp, and tenant_id added
+        def build_payload(event, payload)
+          payload.merge(
+            event: event,
+            timestamp: Time.current,
+            tenant_id: RubyLLM::Agents.configuration.current_tenant_id
+          )
         end
 
-        # Calls a custom alert proc
+        # Calls the user-provided alert handler
         #
-        # @param custom_proc [Proc] The custom handler
         # @param event [Symbol] The event type
-        # @param payload [Hash] The payload
+        # @param payload [Hash] The full payload
         # @return [void]
-        def call_custom_alert(custom_proc, event, payload)
-          custom_proc.call(event, payload)
-        rescue StandardError => e
-          Rails.logger.warn("[RubyLLM::Agents::AlertManager] Custom alert failed: #{e.message}")
-        end
+        def call_handler(event, payload)
+          handler = RubyLLM::Agents.configuration.on_alert
+          return unless handler.respond_to?(:call)
 
-        # Sends email alerts to configured recipients
-        #
-        # @param event [Symbol] The event type
-        # @param payload [Hash] The payload
-        # @param recipients [Array<String>] Email addresses
-        # @return [void]
-        def send_email_alerts(event, payload, recipients)
-          Array(recipients).each do |recipient|
-            AlertMailer.alert_notification(
-              event: event,
-              payload: payload,
-              recipient: recipient
-            ).deliver_later
-          end
+          handler.call(event, payload)
         rescue StandardError => e
-          Rails.logger.warn("[RubyLLM::Agents::AlertManager] Email alert failed: #{e.message}")
+          Rails.logger.warn("[RubyLLM::Agents::AlertManager] Handler failed: #{e.message}")
         end
 
         # Emits an ActiveSupport::Notification
         #
         # @param event [Symbol] The event type
-        # @param payload [Hash] The payload
+        # @param payload [Hash] The full payload
         # @return [void]
         def emit_notification(event, payload)
           ActiveSupport::Notifications.instrument("ruby_llm_agents.alert.#{event}", payload)
@@ -129,102 +87,49 @@ module RubyLLM
           # Ignore notification failures
         end
 
-        # Formats a Slack message for the event
-        #
-        # @param event [Symbol] The event type
-        # @param payload [Hash] The payload
-        # @return [Hash] Slack message payload
-        def format_slack_message(event, payload)
-          emoji = event_emoji(event)
-          title = event_title(event)
-          color = event_color(event)
-
-          fields = payload.except(:event).map do |key, value|
-            {
-              title: key.to_s.titleize,
-              value: value.to_s,
-              short: true
-            }
-          end
-
-          {
-            attachments: [
-              {
-                fallback: "#{title}: #{payload.except(:event).to_json}",
-                color: color,
-                pretext: "#{emoji} *RubyLLM::Agents Alert*",
-                title: title,
-                fields: fields,
-                footer: "RubyLLM::Agents",
-                ts: Time.current.to_i
-              }
-            ]
-          }
-        end
-
-        # Returns emoji for event type
-        #
-        # @param event [Symbol] The event type
-        # @return [String] Emoji
-        def event_emoji(event)
-          case event
-          when :budget_soft_cap then ":warning:"
-          when :budget_hard_cap then ":no_entry:"
-          when :breaker_open then ":rotating_light:"
-          when :agent_anomaly then ":mag:"
-          else ":bell:"
-          end
-        end
-
-        # Returns title for event type
+        # Stores the alert in cache for dashboard display
         #
         # @param event [Symbol] The event type
-        # @return [String] Human-readable title
-        def event_title(event)
-          case event
-          when :budget_soft_cap then "Budget Soft Cap Reached"
-          when :budget_hard_cap then "Budget Hard Cap Exceeded"
-          when :breaker_open then "Circuit Breaker Opened"
-          when :agent_anomaly then "Agent Anomaly Detected"
-          else event.to_s.titleize
-          end
+        # @param payload [Hash] The full payload
+        # @return [void]
+        def store_for_dashboard(event, payload)
+          cache = RubyLLM::Agents.configuration.cache_store
+          key = "ruby_llm_agents:alerts:recent"
+
+          alerts = cache.read(key) || []
+          alerts.unshift(
+            type: event,
+            message: format_message(event, payload),
+            agent_type: payload[:agent_type],
+            timestamp: payload[:timestamp]
+          )
+          alerts = alerts.first(50)
+
+          cache.write(key, alerts, expires_in: 24.hours)
+        rescue StandardError
+          # Ignore cache failures
         end
 
-        # Returns color for event type
+        # Formats a human-readable message for the event
         #
         # @param event [Symbol] The event type
-        # @return [String] Hex color code
-        def event_color(event)
+        # @param payload [Hash] The full payload
+        # @return [String] Human-readable message
+        def format_message(event, payload)
           case event
-          when :budget_soft_cap then "#FFA500"  # Orange
-          when :budget_hard_cap then "#FF0000"  # Red
-          when :breaker_open then "#FF0000"     # Red
-          when :agent_anomaly then "#FFA500"    # Orange
-          else "#0000FF"                        # Blue
-          end
-        end
-
-        # Posts JSON to a URL using Net::HTTP
-        #
-        # @param url [String] The URL
-        # @param payload [Hash] The payload
-        # @return [Net::HTTPResponse]
-        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)
-          unless response.is_a?(Net::HTTPSuccess)
-            Rails.logger.warn("[RubyLLM::Agents::AlertManager] Webhook returned #{response.code}: #{response.body}")
+          when :budget_soft_cap
+            "Budget soft cap reached: $#{payload[:total_cost]&.round(2)} / $#{payload[:limit]&.round(2)}"
+          when :budget_hard_cap
+            "Budget hard cap exceeded: $#{payload[:total_cost]&.round(2)} / $#{payload[:limit]&.round(2)}"
+          when :breaker_open
+            "Circuit breaker opened for #{payload[:agent_type]}"
+          when :breaker_closed
+            "Circuit breaker closed for #{payload[:agent_type]}"
+          when :agent_anomaly
+            "Anomaly detected: #{payload[:threshold_type]} threshold exceeded"
+          else
+            event.to_s.humanize
           end
-          response
         end
       end
     end

data/lib/ruby_llm/agents/infrastructure/attempt_tracker.rb

@@ -73,6 +73,7 @@ module RubyLLM
         if error
           attempt[:error_class] = error.class.name
           attempt[:error_message] = error.message.to_s.truncate(1000)
+          attempt[:error_backtrace] = error.backtrace&.first(20)
         end
 
         @attempts << attempt

data/lib/ruby_llm/agents/infrastructure/budget/budget_query.rb

@@ -21,7 +21,16 @@ module RubyLLM
           # @return [Float] Current spend in USD
           def current_spend(scope, period, agent_type: nil, tenant_id: nil)
             key = SpendRecorder.budget_cache_key(scope, period, agent_type: agent_type, tenant_id: tenant_id)
-            (BudgetQuery.cache_read(key) || 0).to_f
+            cached = BudgetQuery.cache_read(key)
+            return cached.to_f if cached.present?
+
+            # Cache miss — rebuild from executions table for global scope
+            if scope == :global && tenant_id.nil?
+              total = current_global_spend(period)
+              return total.to_f
+            end
+
+            0.to_f
           end
 
           # Returns the current token usage for a period (global only)
@@ -31,9 +40,64 @@ module RubyLLM
           # @return [Integer] Current token usage
           def current_tokens(period, tenant_id: nil)
             key = SpendRecorder.token_cache_key(period, tenant_id: tenant_id)
-            (BudgetQuery.cache_read(key) || 0).to_i
+            cached = BudgetQuery.cache_read(key)
+            return cached.to_i if cached.present?
+
+            # Cache miss — rebuild from executions table
+            if tenant_id.nil?
+              total = current_global_tokens(period)
+              return total.to_i
+            end
+
+            0
+          end
+
+          # Rebuilds global spend from executions table on cache miss
+          #
+          # @param period [Symbol] :daily or :monthly
+          # @return [Float] Total spend in USD
+          def current_global_spend(period)
+            total = RubyLLM::Agents::Execution
+                      .where("created_at >= ?", period_start(period))
+                      .where(tenant_id: nil)
+                      .sum(:total_cost)
+            key = SpendRecorder.budget_cache_key(:global, period)
+            BudgetQuery.cache_write(key, total, expires_in: period_ttl(period))
+            total
+          end
+
+          # Rebuilds global token usage from executions table on cache miss
+          #
+          # @param period [Symbol] :daily or :monthly
+          # @return [Integer] Total tokens used
+          def current_global_tokens(period)
+            total = RubyLLM::Agents::Execution
+                      .where("created_at >= ?", period_start(period))
+                      .where(tenant_id: nil)
+                      .sum(:total_tokens)
+            key = SpendRecorder.token_cache_key(period)
+            BudgetQuery.cache_write(key, total, expires_in: period_ttl(period))
+            total
           end
 
+          private
+
+          def period_start(period)
+            case period
+            when :daily then Date.current.beginning_of_day
+            when :monthly then Date.current.beginning_of_month.beginning_of_day
+            end
+          end
+
+          def period_ttl(period)
+            case period
+            when :daily then 1.day
+            when :monthly then 31.days
+            end
+          end
+
+          public
+
           # Returns the remaining budget for a scope and period
           #
           # @param scope [Symbol] :global or :agent

data/lib/ruby_llm/agents/infrastructure/budget/spend_recorder.rb

@@ -154,10 +154,6 @@ module RubyLLM
           # @param budget_config [Hash] Budget configuration
           # @return [void]
           def check_soft_cap_alerts(agent_type, tenant_id, budget_config)
-            config = RubyLLM::Agents.configuration
-            return unless config.alerts_enabled?
-            return unless config.alert_events.include?(:budget_soft_cap) || config.alert_events.include?(:budget_hard_cap)
-
             # Check global daily
             check_budget_alert(:global_daily, budget_config[:global_daily],
                               BudgetQuery.current_spend(:global, :daily, tenant_id: tenant_id),
@@ -199,8 +195,6 @@ module RubyLLM
             return if current <= limit
 
             event = budget_config[:enforcement] == :hard ? :budget_hard_cap : :budget_soft_cap
-            config = RubyLLM::Agents.configuration
-            return unless config.alert_events.include?(event)
 
             # Prevent duplicate alerts by using a cache key (include tenant for isolation)
             key = alert_cache_key("budget_alert", scope, tenant_id)
@@ -225,10 +219,6 @@ module RubyLLM
           # @param budget_config [Hash] Budget configuration
           # @return [void]
           def check_soft_token_alerts(agent_type, tenant_id, budget_config)
-            config = RubyLLM::Agents.configuration
-            return unless config.alerts_enabled?
-            return unless config.alert_events.include?(:token_soft_cap) || config.alert_events.include?(:token_hard_cap)
-
             # Check global daily tokens
             check_token_alert(:global_daily_tokens, budget_config[:global_daily_tokens],
                              BudgetQuery.current_tokens(:daily, tenant_id: tenant_id),
@@ -254,8 +244,6 @@ module RubyLLM
             return if current <= limit
 
             event = budget_config[:enforcement] == :hard ? :token_hard_cap : :token_soft_cap
-            config = RubyLLM::Agents.configuration
-            return unless config.alert_events.include?(event)
 
             # Prevent duplicate alerts
             key = alert_cache_key("token_alert", scope, tenant_id)

data/lib/ruby_llm/agents/infrastructure/circuit_breaker.rb

@@ -174,19 +174,16 @@ module RubyLLM
       def open_breaker!
         cache_write(open_key, Time.current.to_s, expires_in: cooldown_seconds)
 
-        # Fire alert if configured
-        if RubyLLM::Agents.configuration.alerts_enabled? &&
-           RubyLLM::Agents.configuration.alert_events.include?(:breaker_open)
-          AlertManager.notify(:breaker_open, {
-            agent_type: agent_type,
-            model_id: model_id,
-            tenant_id: tenant_id,
-            errors: errors_threshold,
-            within: window_seconds,
-            cooldown: cooldown_seconds,
-            timestamp: Time.current.iso8601
-          })
-        end
+        # Fire alert
+        AlertManager.notify(:breaker_open, {
+          agent_type: agent_type,
+          model_id: model_id,
+          tenant_id: tenant_id,
+          errors: errors_threshold,
+          within: window_seconds,
+          cooldown: cooldown_seconds,
+          timestamp: Time.current.iso8601
+        })
       end
 
       # Returns the cache key for the failure counter

data/lib/ruby_llm/agents/infrastructure/reliability.rb

@@ -88,7 +88,7 @@ module RubyLLM
       #
       # @api public
       class AllModelsExhaustedError < Error
-        attr_reader :models_tried, :last_error, :attempts
+        attr_reader :models_tried, :last_error, :attempts, :errors
 
         # @param models_tried [Array<String>] List of models that were attempted
         # @param last_error [Exception] The last error that occurred
@@ -97,7 +97,42 @@ module RubyLLM
           @models_tried = models_tried
           @last_error = last_error
           @attempts = attempts
-          super("All models exhausted: #{models_tried.join(', ')}. Last error: #{last_error.message}")
+          @errors = build_errors
+          super(build_message)
+        end
+
+        private
+
+        def build_errors
+          return [] unless @attempts&.any?
+
+          @attempts.filter_map do |attempt|
+            if attempt["short_circuited"]
+              { model: attempt["model_id"], error_class: "CircuitBreakerOpen", error_message: "circuit breaker open",
+                error_backtrace: nil }
+            elsif attempt["error_class"]
+              { model: attempt["model_id"], error_class: attempt["error_class"], error_message: attempt["error_message"],
+                error_backtrace: attempt["error_backtrace"] }
+            end
+          end
+        end
+
+        def build_message
+          parts = ["All models exhausted:"]
+          if @attempts&.any?
+            @attempts.each do |attempt|
+              model = attempt["model_id"]
+              if attempt["short_circuited"]
+                parts << "  #{model}: circuit breaker open"
+              elsif attempt["error_class"]
+                parts << "  #{model}: #{attempt['error_class']} - #{attempt['error_message']}"
+              end
+            end
+          else
+            parts << "  Models: #{@models_tried.join(', ')}"
+            parts << "  Last error: #{@last_error.message}"
+          end
+          parts.join("\n")
         end
       end
 

data/lib/ruby_llm/agents/pipeline/context.rb

@@ -234,7 +234,6 @@ module RubyLLM
           when /image/, /generator/, /analyzer/, /editor/, /transform/, /upscale/, /variat/, /background/
             :image
           when /transcrib/, /speak/ then :audio
-          when /moderat/ then :moderation
           else :conversation
           end
         end