ruby_llm-agents 1.0.0 → 1.2.0

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

@@ -0,0 +1,117 @@
+# 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

@@ -0,0 +1,180 @@
+# 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

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module RubyLLM
+  module Agents
+    class Workflow
+      module Notifiers
+        # Generic webhook notification adapter for approval requests
+        #
+        # Posts approval notifications to any HTTP endpoint.
+        # Supports custom headers for authentication and content negotiation.
+        #
+        # @example Basic usage
+        #   notifier = Webhook.new(url: "https://api.example.com/approvals")
+        #   notifier.notify(approval, "Please review")
+        #
+        # @example With authentication
+        #   notifier = Webhook.new(
+        #     url: "https://api.example.com/approvals",
+        #     headers: { "Authorization" => "Bearer token123" }
+        #   )
+        #
+        # @api public
+        class Webhook < Base
+          class << self
+            attr_accessor :default_url, :default_headers, :timeout
+
+            # Configure the webhook notifier
+            #
+            # @yield [self] The webhook notifier class
+            # @return [void]
+            def configure
+              yield self
+            end
+
+            # Reset configuration to defaults
+            #
+            # @return [void]
+            def reset!
+              @default_url = nil
+              @default_headers = nil
+              @timeout = nil
+            end
+          end
+
+          # @param url [String] The webhook URL
+          # @param headers [Hash] Additional HTTP headers
+          # @param timeout [Integer] Request timeout in seconds
+          def initialize(url: nil, headers: {}, timeout: nil)
+            @url = url || self.class.default_url
+            @headers = (self.class.default_headers || {}).merge(headers)
+            @timeout = timeout || self.class.timeout || 10
+          end
+
+          # Send a webhook notification
+          #
+          # @param approval [Approval] The approval request
+          # @param message [String] The notification message
+          # @return [Boolean] true if webhook returned 2xx status
+          def notify(approval, message)
+            return false unless @url
+
+            payload = build_payload(approval, message)
+            send_request(payload)
+          rescue StandardError => e
+            handle_error(e, approval)
+            false
+          end
+
+          private
+
+          def build_payload(approval, message)
+            {
+              event: "approval_requested",
+              approval: {
+                id: approval.id,
+                workflow_id: approval.workflow_id,
+                workflow_type: approval.workflow_type,
+                name: approval.name,
+                status: approval.status,
+                approvers: approval.approvers,
+                expires_at: approval.expires_at&.iso8601,
+                created_at: approval.created_at.iso8601,
+                metadata: approval.metadata
+              },
+              message: message,
+              timestamp: Time.now.iso8601
+            }
+          end
+
+          def send_request(payload)
+            uri = URI.parse(@url)
+            http = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl = uri.scheme == "https"
+            http.open_timeout = @timeout
+            http.read_timeout = @timeout
+
+            request = Net::HTTP::Post.new(uri.request_uri)
+            request["Content-Type"] = "application/json"
+            @headers.each { |key, value| request[key] = value }
+            request.body = payload.to_json
+
+            response = http.request(request)
+            response.code.to_i.between?(200, 299)
+          end
+
+          def handle_error(error, approval)
+            if defined?(Rails) && Rails.logger
+              Rails.logger.error(
+                "[RubyLLM::Agents] Webhook notification failed for approval #{approval.id}: #{error.message}"
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "notifiers/base"
+require_relative "notifiers/email"
+require_relative "notifiers/slack"
+require_relative "notifiers/webhook"
+
+module RubyLLM
+  module Agents
+    class Workflow
+      module Notifiers
+        # Configure and register default notifiers
+        #
+        # @example Register notifiers
+        #   RubyLLM::Agents::Workflow::Notifiers.setup do |config|
+        #     config.register :email, Email.new
+        #     config.register :slack, Slack.new(webhook_url: "...")
+        #   end
+        #
+        # @api public
+        class << self
+          # Setup notifiers with configuration
+          #
+          # @yield [Registry] The notifier registry
+          # @return [void]
+          def setup
+            yield Registry
+          end
+
+          # Register a notifier
+          #
+          # @param name [Symbol] The notifier name
+          # @param notifier [Base] The notifier instance
+          # @return [void]
+          def register(name, notifier)
+            Registry.register(name, notifier)
+          end
+
+          # Get a notifier
+          #
+          # @param name [Symbol] The notifier name
+          # @return [Base, nil]
+          def [](name)
+            Registry.get(name)
+          end
+
+          # Send notifications through multiple channels
+          #
+          # @param approval [Approval] The approval request
+          # @param message [String] The notification message
+          # @param channels [Array<Symbol>] The channels to notify
+          # @return [Hash<Symbol, Boolean>] Results per channel
+          def notify(approval, message, channels:)
+            Registry.notify_all(approval, message, channels: channels)
+          end
+
+          # Reset all notifier configuration
+          #
+          # @return [void]
+          def reset!
+            Registry.reset!
+            Email.reset!
+            Slack.reset!
+            Webhook.reset!
+          end
+        end
+      end
+    end
+  end
+end