ruby_llm-agents 1.0.0 → 1.1.0

data/lib/ruby_llm/agents/core/configuration.rb

@@ -702,8 +702,8 @@ module RubyLLM
         @default_background_output_format = :png  # Output format for transparency
 
         # Directory structure defaults
-        @root_directory = "llm"  # Root directory under app/
-        @root_namespace = "Llm"  # Root namespace for classes
+        @root_directory = "agents"  # Root directory under app/
+        @root_namespace = nil  # No namespace (top-level classes)
       end
 
       # Returns the configured cache store, falling back to Rails.cache
@@ -744,7 +744,8 @@ module RubyLLM
 
         alerts[:slack_webhook_url].present? ||
           alerts[:webhook_url].present? ||
-          alerts[:custom].present?
+          alerts[:custom].present? ||
+          alerts[:email_recipients].present?
       end
 
       # Returns the list of events to alert on
@@ -822,28 +823,27 @@ module RubyLLM
       #
       # @param category [Symbol, nil] Category (:audio, :image, :text, or nil for root)
       # @return [String, nil] Full namespace string, or nil if no namespace configured
-      # @example With default namespace
+      # @example With root_namespace = "Llm"
       #   namespace_for(:image) #=> "Llm::Image"
       #   namespace_for(nil)    #=> "Llm"
       # @example With no namespace (root_namespace = nil)
       #   namespace_for(:image) #=> "Image"
       #   namespace_for(nil)    #=> nil
       def namespace_for(category = nil)
-        # Handle no namespace configuration
-        if root_namespace.blank?
-          case category
-          when :audio then "Audio"
-          when :image then "Image"
-          when :text then "Text"
-          else nil
-          end
+        category_namespace = case category
+        when :images then "Images"
+        when :audio then "Audio"
+        when :embedders then "Embedders"
+        when :moderators then "Moderators"
+        when :workflows then "Workflows"
+        when :text then "Text"
+        when :image then "Image"
+        end
+
+        if root_namespace
+          category_namespace ? "#{root_namespace}::#{category_namespace}" : root_namespace
         else
-          case category
-          when :audio then "#{root_namespace}::Audio"
-          when :image then "#{root_namespace}::Image"
-          when :text then "#{root_namespace}::Text"
-          else root_namespace
-          end
+          category_namespace
         end
       end
 
@@ -852,15 +852,34 @@ module RubyLLM
       # @param category [Symbol, nil] Category (:audio, :image, :text, or nil)
       # @param type [String] Component type (e.g., "agents", "speakers", "generators")
       # @return [String] Full path relative to Rails.root
-      # @example
+      # @example With root_directory = "llm"
       #   path_for(:image, "generators") #=> "app/llm/image/generators"
       #   path_for(nil, "agents")        #=> "app/llm/agents"
-      def path_for(category, type)
-        case category
-        when :audio then "app/#{root_directory}/audio/#{type}"
-        when :image then "app/#{root_directory}/image/#{type}"
-        when :text then "app/#{root_directory}/text/#{type}"
-        else "app/#{root_directory}/#{type}"
+      # @example With root_directory = "agents" (default)
+      #   path_for(:images)              #=> "app/agents/images"
+      #   path_for(nil, "tools")         #=> "app/agents/tools"
+      def path_for(category, type = nil)
+        root = root_directory || "agents"
+        base = "app/#{root}"
+
+        category_path = case category
+        when :images then "images"
+        when :audio then "audio"
+        when :embedders then "embedders"
+        when :moderators then "moderators"
+        when :workflows then "workflows"
+        when :text then "text"
+        when :image then "image"
+        end
+
+        if category_path && type
+          "#{base}/#{category_path}/#{type}"
+        elsif category_path
+          "#{base}/#{category_path}"
+        elsif type
+          "#{base}/#{type}"
+        else
+          base
         end
       end
 
@@ -868,25 +887,18 @@ module RubyLLM
       #
       # @return [Array<String>] List of paths relative to Rails.root
       def all_autoload_paths
+        root = root_directory || "agents"
+        base = "app/#{root}"
+
         [
-          # Top-level
-          path_for(nil, "agents"),
-          path_for(nil, "workflows"),
-          path_for(nil, "tools"),
-          # Audio
-          path_for(:audio, "speakers"),
-          path_for(:audio, "transcribers"),
-          # Image
-          path_for(:image, "analyzers"),
-          path_for(:image, "background_removers"),
-          path_for(:image, "editors"),
-          path_for(:image, "generators"),
-          path_for(:image, "transformers"),
-          path_for(:image, "upscalers"),
-          path_for(:image, "variators"),
-          # Text
-          path_for(:text, "embedders"),
-          path_for(:text, "moderators")
+          base,
+          "app/workflows",           # Top-level workflows directory
+          "#{base}/images",
+          "#{base}/audio",
+          "#{base}/embedders",
+          "#{base}/moderators",
+          "#{base}/workflows",
+          "#{base}/tools"
         ]
       end
 

data/lib/ruby_llm/agents/core/version.rb

@@ -4,6 +4,6 @@ module RubyLLM
   module Agents
     # Current version of the RubyLLM::Agents gem
     # @return [String] Semantic version string
-    VERSION = "1.0.0"
+    VERSION = "1.1.0"
   end
 end

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

@@ -46,6 +46,14 @@ module RubyLLM
             call_custom_alert(alerts[:custom], event, full_payload)
           end
 
+          # 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
+
           # Emit ActiveSupport::Notification for observability
           emit_notification(event, full_payload)
         rescue StandardError => e
@@ -92,6 +100,24 @@ module RubyLLM
           Rails.logger.warn("[RubyLLM::Agents::AlertManager] Custom alert failed: #{e.message}")
         end
 
+        # 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
+        rescue StandardError => e
+          Rails.logger.warn("[RubyLLM::Agents::AlertManager] Email alert failed: #{e.message}")
+        end
+
         # Emits an ActiveSupport::Notification
         #
         # @param event [Symbol] The event type

data/lib/ruby_llm/agents/pipeline.rb

@@ -40,6 +40,75 @@ require_relative "pipeline/middleware/reliability"
 module RubyLLM
   module Agents
     module Pipeline
+      # Represents an error result from a failed step
+      #
+      # Used to track errors that occurred during step execution while
+      # allowing the workflow to continue (for optional steps).
+      #
+      # @api public
+      class ErrorResult
+        attr_reader :step_name, :error_class, :error_message
+
+        def initialize(step_name:, error_class:, error_message:)
+          @step_name = step_name
+          @error_class = error_class
+          @error_message = error_message
+        end
+
+        def content
+          nil
+        end
+
+        def success?
+          false
+        end
+
+        def error?
+          true
+        end
+
+        def skipped?
+          false
+        end
+
+        def input_tokens
+          0
+        end
+
+        def output_tokens
+          0
+        end
+
+        def total_tokens
+          0
+        end
+
+        def cached_tokens
+          0
+        end
+
+        def input_cost
+          0.0
+        end
+
+        def output_cost
+          0.0
+        end
+
+        def total_cost
+          0.0
+        end
+
+        def to_h
+          {
+            error: true,
+            step_name: step_name,
+            error_class: error_class,
+            error_message: error_message
+          }
+        end
+      end
+
       class << self
         # Build a pipeline for an agent class with default middleware
         #

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

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module RubyLLM
+  module Agents
+    class Workflow
+      # Represents an approval request for human-in-the-loop workflows
+      #
+      # Tracks the state of an approval including who created it, who can approve it,
+      # and the final decision with timestamp and reason.
+      #
+      # @example Creating an approval
+      #   approval = Approval.new(
+      #     workflow_id: "order-123",
+      #     workflow_type: "OrderApprovalWorkflow",
+      #     name: :manager_approval,
+      #     metadata: { order_total: 5000 }
+      #   )
+      #
+      # @example Approving
+      #   approval.approve!("manager@example.com")
+      #
+      # @example Rejecting
+      #   approval.reject!("manager@example.com", reason: "Budget exceeded")
+      #
+      # @api public
+      class Approval
+        STATUSES = %i[pending approved rejected expired].freeze
+
+        attr_reader :id, :workflow_id, :workflow_type, :name, :status,
+                    :created_at, :metadata, :approvers, :expires_at
+        attr_accessor :approved_by, :approved_at, :rejected_by, :rejected_at,
+                      :reason, :reminded_at
+
+        # @param workflow_id [String] The workflow instance ID
+        # @param workflow_type [String] The workflow class name
+        # @param name [Symbol] The approval point name
+        # @param approvers [Array<String>] List of user IDs who can approve
+        # @param expires_at [Time, nil] When the approval expires
+        # @param metadata [Hash] Additional context for the approval
+        def initialize(workflow_id:, workflow_type:, name:, approvers: [], expires_at: nil, metadata: {})
+          @id = SecureRandom.uuid
+          @workflow_id = workflow_id
+          @workflow_type = workflow_type
+          @name = name
+          @status = :pending
+          @approvers = approvers
+          @expires_at = expires_at
+          @metadata = metadata
+          @created_at = Time.now
+        end
+
+        # Approve the request
+        #
+        # @param user_id [String] The user approving
+        # @param comment [String, nil] Optional comment
+        # @return [void]
+        def approve!(user_id, comment: nil)
+          raise InvalidStateError, "Cannot approve: status is #{status}" unless pending?
+
+          @status = :approved
+          @approved_by = user_id
+          @approved_at = Time.now
+          @metadata[:approval_comment] = comment if comment
+        end
+
+        # Reject the request
+        #
+        # @param user_id [String] The user rejecting
+        # @param reason [String, nil] Reason for rejection
+        # @return [void]
+        def reject!(user_id, reason: nil)
+          raise InvalidStateError, "Cannot reject: status is #{status}" unless pending?
+
+          @status = :rejected
+          @rejected_by = user_id
+          @rejected_at = Time.now
+          @reason = reason
+        end
+
+        # Expire the approval request
+        #
+        # @return [void]
+        def expire!
+          raise InvalidStateError, "Cannot expire: status is #{status}" unless pending?
+
+          @status = :expired
+        end
+
+        # Check if approval is still pending
+        #
+        # @return [Boolean]
+        def pending?
+          status == :pending
+        end
+
+        # Check if approval was granted
+        #
+        # @return [Boolean]
+        def approved?
+          status == :approved
+        end
+
+        # Check if approval was rejected
+        #
+        # @return [Boolean]
+        def rejected?
+          status == :rejected
+        end
+
+        # Check if approval has expired
+        #
+        # @return [Boolean]
+        def expired?
+          status == :expired
+        end
+
+        # Check if the approval has timed out
+        #
+        # @return [Boolean]
+        def timed_out?
+          return false unless expires_at
+
+          Time.now > expires_at && pending?
+        end
+
+        # Check if a user can approve this request
+        #
+        # @param user_id [String] The user to check
+        # @return [Boolean]
+        def can_approve?(user_id)
+          return true if approvers.empty? # Anyone can approve if no restrictions
+
+          approvers.include?(user_id)
+        end
+
+        # Duration since creation
+        #
+        # @return [Float] Seconds since creation
+        def age
+          Time.now - created_at
+        end
+
+        # Duration until expiry
+        #
+        # @return [Float, nil] Seconds until expiry, nil if no expiry
+        def time_until_expiry
+          return nil unless expires_at
+
+          expires_at - Time.now
+        end
+
+        # Mark that a reminder was sent
+        #
+        # @return [void]
+        def mark_reminded!
+          @reminded_at = Time.now
+        end
+
+        # Check if a reminder should be sent
+        #
+        # @param reminder_after [Integer] Seconds after creation to send reminder
+        # @param reminder_interval [Integer, nil] Interval between reminders
+        # @return [Boolean]
+        def should_remind?(reminder_after, reminder_interval: nil)
+          return false unless pending?
+          return false if age < reminder_after
+
+          if reminded_at && reminder_interval
+            Time.now - reminded_at >= reminder_interval
+          else
+            reminded_at.nil?
+          end
+        end
+
+        # Convert to hash for serialization
+        #
+        # @return [Hash]
+        def to_h
+          {
+            id: id,
+            workflow_id: workflow_id,
+            workflow_type: workflow_type,
+            name: name,
+            status: status,
+            approvers: approvers,
+            approved_by: approved_by,
+            approved_at: approved_at,
+            rejected_by: rejected_by,
+            rejected_at: rejected_at,
+            reason: reason,
+            expires_at: expires_at,
+            reminded_at: reminded_at,
+            metadata: metadata,
+            created_at: created_at
+          }.compact
+        end
+
+        # Error for invalid state transitions
+        class InvalidStateError < StandardError; end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class Workflow
+      # Abstract base class for approval storage
+      #
+      # Provides a common interface for storing and retrieving approval requests.
+      # Implementations can use in-memory storage, databases, Redis, etc.
+      #
+      # @example Setting a custom store
+      #   RubyLLM::Agents::Workflow::ApprovalStore.store = MyRedisStore.new
+      #
+      # @example Using the default store
+      #   store = RubyLLM::Agents::Workflow::ApprovalStore.store
+      #   store.save(approval)
+      #
+      # @api public
+      class ApprovalStore
+        class << self
+          # Returns the configured store instance
+          #
+          # @return [ApprovalStore]
+          def store
+            @store ||= default_store
+          end
+
+          # Sets the store instance
+          #
+          # @param store [ApprovalStore] The store to use
+          # @return [void]
+          def store=(store)
+            @store = store
+          end
+
+          # Resets to the default store (useful for testing)
+          #
+          # @return [void]
+          def reset!
+            @store = nil
+          end
+
+          private
+
+          def default_store
+            MemoryApprovalStore.new
+          end
+        end
+
+        # Save an approval
+        #
+        # @param approval [Approval] The approval to save
+        # @return [Approval] The saved approval
+        def save(approval)
+          raise NotImplementedError, "#{self.class}#save must be implemented"
+        end
+
+        # Find an approval by ID
+        #
+        # @param id [String] The approval ID
+        # @return [Approval, nil]
+        def find(id)
+          raise NotImplementedError, "#{self.class}#find must be implemented"
+        end
+
+        # Find all approvals for a workflow
+        #
+        # @param workflow_id [String] The workflow ID
+        # @return [Array<Approval>]
+        def find_by_workflow(workflow_id)
+          raise NotImplementedError, "#{self.class}#find_by_workflow must be implemented"
+        end
+
+        # Find pending approvals for a user
+        #
+        # @param user_id [String] The user ID
+        # @return [Array<Approval>]
+        def pending_for_user(user_id)
+          raise NotImplementedError, "#{self.class}#pending_for_user must be implemented"
+        end
+
+        # Find all pending approvals
+        #
+        # @return [Array<Approval>]
+        def all_pending
+          raise NotImplementedError, "#{self.class}#all_pending must be implemented"
+        end
+
+        # Delete an approval
+        #
+        # @param id [String] The approval ID
+        # @return [Boolean] true if deleted
+        def delete(id)
+          raise NotImplementedError, "#{self.class}#delete must be implemented"
+        end
+
+        # Delete all approvals (useful for testing)
+        #
+        # @return [void]
+        def clear!
+          raise NotImplementedError, "#{self.class}#clear! must be implemented"
+        end
+      end
+
+      # In-memory approval store for development and testing
+      #
+      # Thread-safe storage using a Mutex.
+      #
+      # @api public
+      class MemoryApprovalStore < ApprovalStore
+        def initialize
+          @approvals = {}
+          @mutex = Mutex.new
+        end
+
+        # @see ApprovalStore#save
+        def save(approval)
+          @mutex.synchronize do
+            @approvals[approval.id] = approval
+          end
+          approval
+        end
+
+        # @see ApprovalStore#find
+        def find(id)
+          @mutex.synchronize do
+            @approvals[id]
+          end
+        end
+
+        # @see ApprovalStore#find_by_workflow
+        def find_by_workflow(workflow_id)
+          @mutex.synchronize do
+            @approvals.values.select { |a| a.workflow_id == workflow_id }
+          end
+        end
+
+        # @see ApprovalStore#pending_for_user
+        def pending_for_user(user_id)
+          @mutex.synchronize do
+            @approvals.values.select do |a|
+              a.pending? && a.can_approve?(user_id)
+            end
+          end
+        end
+
+        # @see ApprovalStore#all_pending
+        def all_pending
+          @mutex.synchronize do
+            @approvals.values.select(&:pending?)
+          end
+        end
+
+        # @see ApprovalStore#delete
+        def delete(id)
+          @mutex.synchronize do
+            !!@approvals.delete(id)
+          end
+        end
+
+        # @see ApprovalStore#clear!
+        def clear!
+          @mutex.synchronize do
+            @approvals.clear
+          end
+        end
+
+        # Returns the count of stored approvals
+        #
+        # @return [Integer]
+        def count
+          @mutex.synchronize do
+            @approvals.size
+          end
+        end
+      end
+    end
+  end
+end