ruby_llm-agents 1.3.3 → 2.0.0

data/lib/ruby_llm/agents/workflow/instrumentation.rb

@@ -1,249 +0,0 @@
-# frozen_string_literal: true
-
-module RubyLLM
-  module Agents
-    class Workflow
-      # Instrumentation concern for workflow execution tracking
-      #
-      # Provides comprehensive workflow tracking including:
-      # - Root execution record creation for the workflow
-      # - Timing metrics (started_at, completed_at, duration_ms)
-      # - Aggregate token usage and cost across all steps/branches
-      # - Workflow-specific metadata (workflow_id, workflow_type)
-      # - Error handling with proper status updates
-      #
-      # @api private
-      module Instrumentation
-        extend ActiveSupport::Concern
-
-        included do
-          # @!attribute [rw] execution_id
-          #   The ID of the workflow's root execution record
-          #   @return [Integer, nil]
-          attr_accessor :execution_id
-        end
-
-        # Wraps workflow execution with comprehensive metrics tracking
-        #
-        # Creates a root execution record for the workflow and tracks
-        # aggregate metrics from all child executions.
-        #
-        # @yield The block containing the workflow execution
-        # @return [WorkflowResult] The workflow result
-        def instrument_workflow(&block)
-          started_at = Time.current
-          @workflow_started_at = started_at
-
-          # Create workflow execution record
-          execution = create_workflow_execution(started_at)
-          @execution_id = execution&.id
-          @root_execution_id = execution&.id
-
-          begin
-            result = if self.class.timeout
-                       Timeout.timeout(self.class.timeout) { yield }
-                     else
-                       yield
-                     end
-
-            complete_workflow_execution(
-              execution,
-              completed_at: Time.current,
-              status: result.status,
-              result: result
-            )
-
-            result
-          rescue Timeout::Error => e
-            complete_workflow_execution(
-              execution,
-              completed_at: Time.current,
-              status: "timeout",
-              error: e
-            )
-            raise
-          rescue WorkflowCostExceededError => e
-            complete_workflow_execution(
-              execution,
-              completed_at: Time.current,
-              status: "error",
-              error: e
-            )
-            raise
-          rescue StandardError => e
-            complete_workflow_execution(
-              execution,
-              completed_at: Time.current,
-              status: "error",
-              error: e
-            )
-            raise
-          end
-        end
-
-        private
-
-        # Creates the initial workflow execution record
-        #
-        # @param started_at [Time] When the workflow started
-        # @return [RubyLLM::Agents::Execution, nil] The created record
-        def create_workflow_execution(started_at)
-          RubyLLM::Agents::Execution.create!(
-            agent_type: self.class.name,
-            agent_version: self.class.version,
-            model_id: "workflow",
-            temperature: nil,
-            started_at: started_at,
-            status: "running",
-            parameters: Redactor.redact(options),
-            metadata: workflow_metadata,
-            workflow_id: workflow_id,
-            workflow_type: workflow_type_name
-          )
-        rescue StandardError => e
-          Rails.logger.error("[RubyLLM::Agents::Workflow] Failed to create workflow execution: #{e.message}")
-          nil
-        end
-
-        # Updates the workflow execution record with completion data
-        #
-        # @param execution [Execution, nil] The execution record
-        # @param completed_at [Time] When the workflow completed
-        # @param status [String] Final status
-        # @param result [WorkflowResult, nil] The workflow result
-        # @param error [Exception, nil] The error if failed
-        def complete_workflow_execution(execution, completed_at:, status:, result: nil, error: nil)
-          return unless execution
-
-          started_at = execution.started_at
-          duration_ms = ((completed_at - started_at) * 1000).round
-
-          update_data = {
-            completed_at: completed_at,
-            duration_ms: duration_ms,
-            status: status
-          }
-
-          # Add aggregate metrics from result
-          if result
-            update_data.merge!(
-              input_tokens: result.input_tokens,
-              output_tokens: result.output_tokens,
-              total_tokens: result.total_tokens,
-              cached_tokens: result.cached_tokens,
-              input_cost: result.input_cost,
-              output_cost: result.output_cost,
-              total_cost: result.total_cost
-            )
-
-            # Store step/branch results summary
-            update_data[:response] = build_response_summary(result)
-          end
-
-          # Add error data if failed
-          if error
-            update_data.merge!(
-              error_class: error.class.name,
-              error_message: error.message.to_s.truncate(65535)
-            )
-          end
-
-          execution.update!(update_data)
-        rescue StandardError => e
-          Rails.logger.error("[RubyLLM::Agents::Workflow] Failed to update workflow execution #{execution&.id}: #{e.message}")
-          mark_workflow_failed!(execution, error: error || e)
-        end
-
-        # Emergency fallback to mark workflow as failed
-        #
-        # @param execution [Execution, nil] The execution record
-        # @param error [Exception, nil] The error
-        def mark_workflow_failed!(execution, error: nil)
-          return unless execution&.id
-
-          update_data = {
-            status: "error",
-            completed_at: Time.current,
-            error_class: error&.class&.name || "UnknownError",
-            error_message: error&.message&.to_s&.truncate(65535) || "Unknown error"
-          }
-
-          execution.class.where(id: execution.id, status: "running").update_all(update_data)
-        rescue StandardError => e
-          Rails.logger.error("[RubyLLM::Agents::Workflow] CRITICAL: Failed to mark workflow #{execution&.id} as failed: #{e.message}")
-        end
-
-        # Builds a summary of step/branch results for storage
-        #
-        # @param result [WorkflowResult] The workflow result
-        # @return [Hash] Summary data
-        def build_response_summary(result)
-          summary = {
-            workflow_type: result.workflow_type,
-            status: result.status
-          }
-
-          if result.steps.any?
-            summary[:steps] = result.steps.transform_values do |r|
-              {
-                status: r.respond_to?(:success?) ? (r.success? ? "success" : "error") : "unknown",
-                total_cost: r.respond_to?(:total_cost) ? r.total_cost : 0,
-                duration_ms: r.respond_to?(:duration_ms) ? r.duration_ms : nil
-              }
-            end
-          end
-
-          if result.branches.any?
-            summary[:branches] = result.branches.transform_values do |r|
-              next { status: "error" } if r.nil?
-
-              {
-                status: r.respond_to?(:success?) ? (r.success? ? "success" : "error") : "unknown",
-                total_cost: r.respond_to?(:total_cost) ? r.total_cost : 0,
-                duration_ms: r.respond_to?(:duration_ms) ? r.duration_ms : nil
-              }
-            end
-          end
-
-          if result.routed_to
-            summary[:routed_to] = result.routed_to
-            summary[:classification_cost] = result.classification_cost
-          end
-
-          summary
-        end
-
-        # Returns workflow-specific metadata
-        #
-        # @return [Hash] Workflow metadata
-        def workflow_metadata
-          base_metadata = {
-            workflow_id: workflow_id,
-            workflow_type: workflow_type_name
-          }
-
-          # Allow subclasses to add custom metadata
-          if respond_to?(:execution_metadata, true)
-            base_metadata.merge(execution_metadata)
-          else
-            base_metadata
-          end
-        end
-
-        # Returns the workflow type name for storage
-        #
-        # @return [String] The workflow type
-        def workflow_type_name
-          "workflow"
-        end
-
-        # Hook for subclasses to add custom metadata
-        #
-        # @return [Hash] Custom metadata
-        def execution_metadata
-          {}
-        end
-      end
-    end
-  end
-end

data/lib/ruby_llm/agents/workflow/notifiers/base.rb

@@ -1,117 +0,0 @@
-# frozen_string_literal: true
-
-module RubyLLM
-  module Agents
-    class Workflow
-      module Notifiers
-        # Base class for approval notification adapters
-        #
-        # Subclasses should implement the #notify and optionally #remind methods
-        # to send notifications through their respective channels.
-        #
-        # @example Creating a custom notifier
-        #   class SmsNotifier < Base
-        #     def notify(approval, message)
-        #       # Send SMS via Twilio
-        #     end
-        #   end
-        #
-        # @api public
-        class Base
-          # Send a notification for an approval request
-          #
-          # @param approval [Approval] The approval request
-          # @param message [String] The notification message
-          # @return [Boolean] true if notification was sent successfully
-          def notify(approval, message)
-            raise NotImplementedError, "#{self.class}#notify must be implemented"
-          end
-
-          # Send a reminder for a pending approval
-          #
-          # @param approval [Approval] The approval request
-          # @param message [String] The reminder message
-          # @return [Boolean] true if reminder was sent successfully
-          def remind(approval, message)
-            notify(approval, "[Reminder] #{message}")
-          end
-
-          # Send an escalation notice
-          #
-          # @param approval [Approval] The approval request
-          # @param message [String] The escalation message
-          # @param escalate_to [String] The escalation target
-          # @return [Boolean] true if escalation was sent successfully
-          def escalate(approval, message, escalate_to:)
-            notify(approval, "[Escalation to #{escalate_to}] #{message}")
-          end
-        end
-
-        # Registry for notifier instances
-        #
-        # @api private
-        class Registry
-          class << self
-            # Returns the registered notifiers
-            #
-            # @return [Hash<Symbol, Base>]
-            def notifiers
-              @notifiers ||= {}
-            end
-
-            # Register a notifier
-            #
-            # @param name [Symbol] The notifier name
-            # @param notifier [Base] The notifier instance
-            # @return [void]
-            def register(name, notifier)
-              notifiers[name.to_sym] = notifier
-            end
-
-            # Get a registered notifier
-            #
-            # @param name [Symbol] The notifier name
-            # @return [Base, nil]
-            def get(name)
-              notifiers[name.to_sym]
-            end
-
-            # Check if a notifier is registered
-            #
-            # @param name [Symbol] The notifier name
-            # @return [Boolean]
-            def registered?(name)
-              notifiers.key?(name.to_sym)
-            end
-
-            # Send notification through specified channels
-            #
-            # @param approval [Approval] The approval request
-            # @param message [String] The notification message
-            # @param channels [Array<Symbol>] The notification channels
-            # @return [Hash<Symbol, Boolean>] Results per channel
-            def notify_all(approval, message, channels:)
-              results = {}
-              channels.each do |channel|
-                notifier = get(channel)
-                if notifier
-                  results[channel] = notifier.notify(approval, message)
-                else
-                  results[channel] = false
-                end
-              end
-              results
-            end
-
-            # Reset the registry (useful for testing)
-            #
-            # @return [void]
-            def reset!
-              @notifiers = {}
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/ruby_llm/agents/workflow/notifiers/email.rb

@@ -1,117 +0,0 @@
-# frozen_string_literal: true
-
-module RubyLLM
-  module Agents
-    class Workflow
-      module Notifiers
-        # Email notification adapter for approval requests
-        #
-        # Uses ActionMailer if available, or a configured mailer class.
-        # Can be configured with custom templates and delivery options.
-        #
-        # @example Configuration
-        #   RubyLLM::Agents::Workflow::Notifiers::Email.configure do |config|
-        #     config.mailer_class = ApprovalMailer
-        #     config.from = "approvals@example.com"
-        #   end
-        #
-        # @api public
-        class Email < Base
-          class << self
-            attr_accessor :mailer_class, :from_address, :subject_prefix
-
-            # Configure the email notifier
-            #
-            # @yield [self] The email notifier class
-            # @return [void]
-            def configure
-              yield self
-            end
-
-            # Reset configuration to defaults
-            #
-            # @return [void]
-            def reset!
-              @mailer_class = nil
-              @from_address = nil
-              @subject_prefix = nil
-            end
-          end
-
-          # @param mailer_class [Class, nil] Custom mailer class
-          # @param from [String, nil] From address
-          # @param subject_prefix [String, nil] Subject line prefix
-          def initialize(mailer_class: nil, from: nil, subject_prefix: nil)
-            @mailer_class = mailer_class || self.class.mailer_class
-            @from_address = from || self.class.from_address || "noreply@example.com"
-            @subject_prefix = subject_prefix || self.class.subject_prefix || "[Approval Required]"
-          end
-
-          # Send an email notification
-          #
-          # @param approval [Approval] The approval request
-          # @param message [String] The notification message
-          # @return [Boolean] true if email was queued
-          def notify(approval, message)
-            if @mailer_class
-              send_via_mailer(approval, message)
-            elsif defined?(ActionMailer)
-              send_via_action_mailer(approval, message)
-            else
-              log_notification(approval, message)
-              false
-            end
-          rescue StandardError => e
-            handle_error(e, approval)
-            false
-          end
-
-          private
-
-          def send_via_mailer(approval, message)
-            if @mailer_class.respond_to?(:approval_request)
-              mail = @mailer_class.approval_request(approval, message)
-              deliver_mail(mail)
-              true
-            else
-              false
-            end
-          end
-
-          def send_via_action_mailer(approval, message)
-            # Generic ActionMailer support if no custom mailer is configured
-            # Applications should configure a mailer_class for production use
-            log_notification(approval, message)
-            false
-          end
-
-          def deliver_mail(mail)
-            if mail.respond_to?(:deliver_later)
-              mail.deliver_later
-            elsif mail.respond_to?(:deliver_now)
-              mail.deliver_now
-            elsif mail.respond_to?(:deliver)
-              mail.deliver
-            end
-          end
-
-          def log_notification(approval, message)
-            if defined?(Rails) && Rails.logger
-              Rails.logger.info(
-                "[RubyLLM::Agents] Email notification for approval #{approval.id}: #{message}"
-              )
-            end
-          end
-
-          def handle_error(error, approval)
-            if defined?(Rails) && Rails.logger
-              Rails.logger.error(
-                "[RubyLLM::Agents] Failed to send email for approval #{approval.id}: #{error.message}"
-              )
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/ruby_llm/agents/workflow/notifiers/slack.rb

@@ -1,180 +0,0 @@
-# frozen_string_literal: true
-
-require "net/http"
-require "uri"
-require "json"
-
-module RubyLLM
-  module Agents
-    class Workflow
-      module Notifiers
-        # Slack notification adapter for approval requests
-        #
-        # Sends notifications via Slack webhooks or the Slack API.
-        # Supports rich message formatting with blocks.
-        #
-        # @example Using a webhook
-        #   notifier = Slack.new(webhook_url: "https://hooks.slack.com/...")
-        #   notifier.notify(approval, "Please review this request")
-        #
-        # @example Using the API
-        #   notifier = Slack.new(api_token: "xoxb-...", channel: "#approvals")
-        #
-        # @api public
-        class Slack < Base
-          class << self
-            attr_accessor :webhook_url, :api_token, :default_channel
-
-            # Configure the Slack notifier
-            #
-            # @yield [self] The Slack notifier class
-            # @return [void]
-            def configure
-              yield self
-            end
-
-            # Reset configuration to defaults
-            #
-            # @return [void]
-            def reset!
-              @webhook_url = nil
-              @api_token = nil
-              @default_channel = nil
-            end
-          end
-
-          # @param webhook_url [String, nil] Slack webhook URL
-          # @param api_token [String, nil] Slack API token (for posting via API)
-          # @param channel [String, nil] Default channel for messages
-          def initialize(webhook_url: nil, api_token: nil, channel: nil)
-            @webhook_url = webhook_url || self.class.webhook_url
-            @api_token = api_token || self.class.api_token
-            @channel = channel || self.class.default_channel
-          end
-
-          # Send a Slack notification
-          #
-          # @param approval [Approval] The approval request
-          # @param message [String] The notification message
-          # @return [Boolean] true if notification was sent
-          def notify(approval, message)
-            payload = build_payload(approval, message)
-
-            if @webhook_url
-              send_webhook(payload)
-            elsif @api_token
-              send_api(payload)
-            else
-              log_notification(approval, message)
-              false
-            end
-          rescue StandardError => e
-            handle_error(e, approval)
-            false
-          end
-
-          private
-
-          def build_payload(approval, message)
-            {
-              text: message,
-              blocks: build_blocks(approval, message)
-            }.tap do |payload|
-              payload[:channel] = @channel if @channel && @api_token
-            end
-          end
-
-          def build_blocks(approval, message)
-            [
-              {
-                type: "header",
-                text: {
-                  type: "plain_text",
-                  text: "Approval Required: #{approval.name}",
-                  emoji: true
-                }
-              },
-              {
-                type: "section",
-                text: {
-                  type: "mrkdwn",
-                  text: message
-                }
-              },
-              {
-                type: "section",
-                fields: [
-                  {
-                    type: "mrkdwn",
-                    text: "*Workflow:*\n#{approval.workflow_type}"
-                  },
-                  {
-                    type: "mrkdwn",
-                    text: "*Workflow ID:*\n#{approval.workflow_id}"
-                  }
-                ]
-              },
-              {
-                type: "context",
-                elements: [
-                  {
-                    type: "mrkdwn",
-                    text: "Approval ID: `#{approval.id}`"
-                  }
-                ]
-              }
-            ]
-          end
-
-          def send_webhook(payload)
-            uri = URI.parse(@webhook_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.path)
-            request["Content-Type"] = "application/json"
-            request.body = payload.to_json
-
-            response = http.request(request)
-            response.code.to_i == 200
-          end
-
-          def send_api(payload)
-            uri = URI.parse("https://slack.com/api/chat.postMessage")
-            http = Net::HTTP.new(uri.host, uri.port)
-            http.use_ssl = true
-            http.open_timeout = 5
-            http.read_timeout = 10
-
-            request = Net::HTTP::Post.new(uri.path)
-            request["Content-Type"] = "application/json"
-            request["Authorization"] = "Bearer #{@api_token}"
-            request.body = payload.to_json
-
-            response = http.request(request)
-            result = JSON.parse(response.body)
-            result["ok"] == true
-          end
-
-          def log_notification(approval, message)
-            if defined?(Rails) && Rails.logger
-              Rails.logger.info(
-                "[RubyLLM::Agents] Slack notification for approval #{approval.id}: #{message}"
-              )
-            end
-          end
-
-          def handle_error(error, approval)
-            if defined?(Rails) && Rails.logger
-              Rails.logger.error(
-                "[RubyLLM::Agents] Failed to send Slack message for approval #{approval.id}: #{error.message}"
-              )
-            end
-          end
-        end
-      end
-    end
-  end
-end