ruby_llm-agents 1.3.4 → 2.1.0

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

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

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

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

@@ -1,220 +0,0 @@
-# frozen_string_literal: true
-
-module RubyLLM
-  module Agents
-    # Async/Fiber support for concurrent agent execution
-    #
-    # Provides utilities for running agents concurrently using Ruby's Fiber scheduler.
-    # When used inside an `Async` block, RubyLLM automatically becomes non-blocking
-    # because it uses `Net::HTTP` which cooperates with Ruby's fiber scheduler.
-    #
-    # @example Basic concurrent execution
-    #   require 'async'
-    #
-    #   Async do
-    #     results = RubyLLM::Agents::Async.batch([
-    #       [SentimentAgent, { input: "I love this!" }],
-    #       [SummaryAgent, { input: "Long text..." }],
-    #       [CategoryAgent, { input: "Product review" }]
-    #     ])
-    #   end
-    #
-    # @example With rate limiting
-    #   Async do
-    #     results = RubyLLM::Agents::Async.batch(
-    #       items.map { |item| [ProcessorAgent, { input: item }] },
-    #       max_concurrent: 5
-    #     )
-    #   end
-    #
-    # @example Streaming multiple agents
-    #   Async do
-    #     RubyLLM::Agents::Async.each([AgentA, AgentB]) do |agent|
-    #       agent.call(input: data) { |chunk| stream_chunk(chunk) }
-    #     end
-    #   end
-    #
-    # @see https://rubyllm.com/async/ RubyLLM Async Documentation
-    # @api public
-    module Async
-      class << self
-        # Executes multiple agents concurrently with optional rate limiting
-        #
-        # @param agents_with_params [Array<Array(Class, Hash)>] Array of [AgentClass, params] pairs
-        # @param max_concurrent [Integer, nil] Maximum concurrent executions (nil = use config default)
-        # @yield [result, index] Optional block called for each completed result
-        # @return [Array<Object>] Results in the same order as input
-        #
-        # @example Basic batch
-        #   results = RubyLLM::Agents::Async.batch([
-        #     [AgentA, { input: "text1" }],
-        #     [AgentB, { input: "text2" }]
-        #   ])
-        #
-        # @example With progress callback
-        #   RubyLLM::Agents::Async.batch(agents_with_params) do |result, index|
-        #     puts "Completed #{index + 1}/#{agents_with_params.size}"
-        #   end
-        def batch(agents_with_params, max_concurrent: nil, &block)
-          ensure_async_available!
-
-          max_concurrent ||= RubyLLM::Agents.configuration.async_max_concurrency
-          semaphore = ::Async::Semaphore.new(max_concurrent)
-
-          Kernel.send(:Async) do
-            agents_with_params.each_with_index.map do |(agent_class, params), index|
-              Kernel.send(:Async) do
-                result = semaphore.acquire do
-                  agent_class.call(**(params || {}))
-                end
-                yield(result, index) if block
-                result
-              end
-            end.map(&:wait)
-          end.wait
-        end
-
-        # Executes a block for each item concurrently
-        #
-        # @param items [Array] Items to process
-        # @param max_concurrent [Integer, nil] Maximum concurrent executions
-        # @yield [item] Block to execute for each item
-        # @return [Array<Object>] Results in the same order as input
-        #
-        # @example Process items concurrently
-        #   RubyLLM::Agents::Async.each(texts, max_concurrent: 10) do |text|
-        #     SummaryAgent.call(input: text)
-        #   end
-        def each(items, max_concurrent: nil, &block)
-          ensure_async_available!
-          raise ArgumentError, "Block required" unless block
-
-          max_concurrent ||= RubyLLM::Agents.configuration.async_max_concurrency
-          semaphore = ::Async::Semaphore.new(max_concurrent)
-
-          Kernel.send(:Async) do
-            items.map do |item|
-              Kernel.send(:Async) do
-                semaphore.acquire do
-                  yield(item)
-                end
-              end
-            end.map(&:wait)
-          end.wait
-        end
-
-        # Executes multiple agents and returns results as they complete
-        #
-        # Unlike `batch`, this yields results as soon as they're ready,
-        # not in order. Useful for progress updates.
-        #
-        # @param agents_with_params [Array<Array(Class, Hash)>] Array of [AgentClass, params] pairs
-        # @param max_concurrent [Integer, nil] Maximum concurrent executions
-        # @yield [result, agent_class, index] Block called as each result completes
-        # @return [Hash<Integer, Object>] Results keyed by original index
-        #
-        # @example Stream results as they complete
-        #   RubyLLM::Agents::Async.stream(agents) do |result, agent_class, index|
-        #     puts "#{agent_class.name} finished: #{result.content}"
-        #   end
-        def stream(agents_with_params, max_concurrent: nil, &block)
-          ensure_async_available!
-
-          max_concurrent ||= RubyLLM::Agents.configuration.async_max_concurrency
-          semaphore = ::Async::Semaphore.new(max_concurrent)
-          results = {}
-          mutex = Mutex.new
-
-          Kernel.send(:Async) do |task|
-            agents_with_params.each_with_index.map do |(agent_class, params), index|
-              Kernel.send(:Async) do
-                result = semaphore.acquire do
-                  agent_class.call(**(params || {}))
-                end
-
-                mutex.synchronize { results[index] = result }
-                yield(result, agent_class, index) if block
-              end
-            end.map(&:wait)
-          end.wait
-
-          results
-        end
-
-        # Wraps a synchronous agent call in an async task
-        #
-        # @param agent_class [Class] The agent class to call
-        # @param params [Hash] Parameters to pass to the agent
-        # @yield [chunk] Optional streaming block
-        # @return [Async::Task] The async task (call .wait to get result)
-        #
-        # @example Fire and forget
-        #   task = RubyLLM::Agents::Async.call_async(MyAgent, input: "Hello")
-        #   # ... do other work ...
-        #   result = task.wait
-        def call_async(agent_class, **params, &block)
-          ensure_async_available!
-
-          Kernel.send(:Async) do
-            agent_class.call(**params, &block)
-          end
-        end
-
-        # Sleeps without blocking other fibers
-        #
-        # Automatically uses async sleep when in async context,
-        # falls back to regular sleep otherwise.
-        #
-        # @param seconds [Numeric] Duration to sleep
-        # @return [void]
-        def sleep(seconds)
-          if async_context?
-            ::Async::Task.current.sleep(seconds)
-          else
-            Kernel.sleep(seconds)
-          end
-        end
-
-        # Checks if async gem is available
-        #
-        # @return [Boolean] true if async gem is loaded
-        def available?
-          RubyLLM::Agents.configuration.async_available?
-        end
-
-        # Checks if currently in an async context
-        #
-        # @return [Boolean] true if inside an Async block
-        def async_context?
-          RubyLLM::Agents.configuration.async_context?
-        end
-
-        private
-
-        # Raises an error if async gem is not available
-        #
-        # @raise [RuntimeError] If async gem is not loaded
-        def ensure_async_available!
-          return if available?
-
-          raise <<~ERROR
-            Async gem is required for concurrent agent execution.
-
-            Add to your Gemfile:
-              gem 'async'
-
-            Then:
-              bundle install
-
-            Usage:
-              require 'async'
-
-              Async do
-                RubyLLM::Agents::Async.batch([...])
-              end
-          ERROR
-        end
-      end
-    end
-  end
-end