ruby_llm-agents 0.5.0 → 1.0.0.beta.1

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

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

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

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class Workflow
+      # Fiber-based concurrent executor for parallel workflows
+      #
+      # Provides an alternative to ThreadPool that uses Ruby's Fiber scheduler
+      # for lightweight concurrency. Automatically used when the async gem is
+      # available and we're inside an async context.
+      #
+      # @example Basic usage
+      #   executor = AsyncExecutor.new(max_concurrent: 4)
+      #   executor.post { perform_task_1 }
+      #   executor.post { perform_task_2 }
+      #   executor.wait_for_completion
+      #
+      # @example With fail-fast
+      #   executor = AsyncExecutor.new(max_concurrent: 4)
+      #   executor.post { risky_task }
+      #   executor.abort! if something_failed
+      #   executor.wait_for_completion
+      #
+      # @api private
+      class AsyncExecutor
+        attr_reader :max_concurrent
+
+        # Creates a new async executor
+        #
+        # @param max_concurrent [Integer] Maximum concurrent fibers (default: 10)
+        def initialize(max_concurrent: 10)
+          @max_concurrent = max_concurrent
+          @tasks = []
+          @results = []
+          @mutex = Mutex.new
+          @aborted = false
+          @semaphore = nil
+        end
+
+        # Submits a task for execution
+        #
+        # @yield Block to execute
+        # @return [void]
+        def post(&block)
+          @mutex.synchronize do
+            @tasks << block
+          end
+        end
+
+        # Signals that remaining tasks should be skipped
+        #
+        # Currently running tasks will complete, but pending tasks will be skipped.
+        #
+        # @return [void]
+        def abort!
+          @mutex.synchronize do
+            @aborted = true
+          end
+        end
+
+        # Returns whether the executor has been aborted
+        #
+        # @return [Boolean] true if abort! was called
+        def aborted?
+          @mutex.synchronize { @aborted }
+        end
+
+        # Executes all submitted tasks and waits for completion
+        #
+        # @param timeout [Integer, nil] Maximum seconds to wait (nil = indefinite)
+        # @return [Boolean] true if all tasks completed, false if timeout
+        def wait_for_completion(timeout: nil)
+          return true if @tasks.empty?
+
+          ensure_async_available!
+
+          @semaphore = ::Async::Semaphore.new(@max_concurrent)
+
+          if timeout
+            execute_with_timeout(timeout)
+          else
+            execute_all
+            true
+          end
+        end
+
+        # Shuts down the executor
+        #
+        # For AsyncExecutor this is a no-op since fibers are garbage collected.
+        #
+        # @param timeout [Integer] Ignored for async executor
+        # @return [void]
+        def shutdown(timeout: 5)
+          # No-op for fiber-based executor
+          # Fibers are lightweight and garbage collected
+        end
+
+        # Waits for termination (compatibility with ThreadPool)
+        #
+        # @param timeout [Integer] Ignored for async executor
+        # @return [void]
+        def wait_for_termination(timeout: 5)
+          # No-op for fiber-based executor
+        end
+
+        private
+
+        # Executes all tasks with async
+        #
+        # @return [void]
+        def execute_all
+          Kernel.send(:Async) do
+            @tasks.map do |task|
+              Kernel.send(:Async) do
+                next if aborted?
+
+                @semaphore.acquire do
+                  next if aborted?
+                  task.call
+                end
+              end
+            end.map(&:wait)
+          end.wait
+        end
+
+        # Executes all tasks with a timeout
+        #
+        # @param timeout [Integer] Maximum seconds to wait
+        # @return [Boolean] true if completed, false if timeout
+        def execute_with_timeout(timeout)
+          completed = false
+
+          Kernel.send(:Async) do |task|
+            task.with_timeout(timeout) do
+              execute_all
+              completed = true
+            rescue ::Async::TimeoutError
+              completed = false
+            end
+          end.wait
+
+          completed
+        end
+
+        # Ensures async gem is available
+        #
+        # @raise [RuntimeError] If async gem is not loaded
+        def ensure_async_available!
+          return if defined?(::Async) && defined?(::Async::Semaphore)
+
+          raise "AsyncExecutor requires the 'async' gem. Add gem 'async' to your Gemfile."
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/{workflow.rb → workflow/orchestrator.rb}

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
-require_relative "workflow/result"
-require_relative "workflow/instrumentation"
-require_relative "workflow/pipeline"
-require_relative "workflow/parallel"
-require_relative "workflow/router"
+require_relative "result"
+require_relative "instrumentation"
+require_relative "thread_pool"
+require_relative "pipeline"
+require_relative "parallel"
+require_relative "router"
 
 module RubyLLM
   module Agents

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

@@ -149,17 +149,22 @@ module RubyLLM
           results = {}
           errors = {}
           mutex = Mutex.new
-          should_abort = false
 
-          # Create thread pool based on concurrency setting
-          threads = self.class.branches.map do |name, config|
-            Thread.new do
+          # Determine pool size based on concurrency setting
+          pool_size = self.class.concurrency || self.class.branches.size
+
+          # Use async executor when in async context, otherwise use thread pool
+          pool = create_executor(pool_size)
+
+          # Submit all branches to the pool
+          self.class.branches.each do |name, config|
+            pool.post do
               Thread.current.name = "parallel-#{name}"
               Thread.current[:branch_name] = name
 
               begin
-                # Check if we should abort early
-                if self.class.fail_fast? && should_abort
+                # Check if pool was aborted (fail-fast triggered)
+                if pool.aborted?
                   mutex.synchronize { results[name] = nil }
                   next
                 end
@@ -178,29 +183,24 @@ module RubyLLM
                 mutex.synchronize do
                   results[name] = result
 
-                  # Check for failure
+                  # Check for failure and trigger fail-fast if needed
                   if result.respond_to?(:error?) && result.error? && !config[:optional]
-                    should_abort = true if self.class.fail_fast?
+                    pool.abort! if self.class.fail_fast?
                   end
                 end
               rescue StandardError => e
                 mutex.synchronize do
                   errors[name] = e
                   results[name] = nil
-                  should_abort = true if self.class.fail_fast? && !config[:optional]
+                  pool.abort! if self.class.fail_fast? && !config[:optional]
                 end
               end
             end
           end
 
-          # Apply concurrency limit if set
-          if self.class.concurrency
-            threads.each_slice(self.class.concurrency) do |thread_batch|
-              thread_batch.each(&:join)
-            end
-          else
-            threads.each(&:join)
-          end
+          # Wait for all branches to complete
+          pool.wait_for_completion
+          pool.shutdown
 
           # Determine overall status
           status = determine_parallel_status(results, errors)
@@ -276,6 +276,23 @@ module RubyLLM
             duration_ms: (((Time.current - @workflow_started_at) * 1000).round if @workflow_started_at)
           )
         end
+
+        # Creates the appropriate executor based on context
+        #
+        # Uses AsyncExecutor when in async context for fiber-based concurrency,
+        # otherwise falls back to ThreadPool for traditional thread-based execution.
+        #
+        # @param size [Integer] Number of concurrent workers/fibers
+        # @return [ThreadPool, AsyncExecutor] The executor instance
+        def create_executor(size)
+          config = RubyLLM::Agents.configuration
+
+          if config.async_context?
+            AsyncExecutor.new(max_concurrent: size)
+          else
+            ThreadPool.new(size: size)
+          end
+        end
       end
     end
   end

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

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class Workflow
+      # Simple bounded thread pool for parallel workflow execution
+      #
+      # Provides a fixed-size pool of worker threads that process submitted tasks.
+      # Supports fail-fast abort and graceful shutdown.
+      #
+      # @example Basic usage
+      #   pool = ThreadPool.new(size: 4)
+      #   pool.post { perform_task_1 }
+      #   pool.post { perform_task_2 }
+      #   pool.wait_for_completion
+      #   pool.shutdown
+      #
+      # @example With fail-fast
+      #   pool = ThreadPool.new(size: 4)
+      #   begin
+      #     pool.post { risky_task }
+      #   rescue => e
+      #     pool.abort!  # Signal workers to stop
+      #   end
+      #   pool.shutdown
+      #
+      # @api private
+      class ThreadPool
+        attr_reader :size
+
+        # Creates a new thread pool
+        #
+        # @param size [Integer] Number of worker threads (default: 4)
+        def initialize(size: 4)
+          @size = size
+          @queue = Queue.new
+          @workers = []
+          @mutex = Mutex.new
+          @completion_condition = ConditionVariable.new
+          @pending_count = 0
+          @completed_count = 0
+          @aborted = false
+          @shutdown = false
+
+          spawn_workers
+        end
+
+        # Submits a task to the pool
+        #
+        # @yield Block to execute in a worker thread
+        # @return [void]
+        # @raise [RuntimeError] If pool has been shutdown
+        def post(&block)
+          raise "ThreadPool has been shutdown" if @shutdown
+
+          @mutex.synchronize do
+            @pending_count += 1
+          end
+
+          @queue.push(block)
+        end
+
+        # Signals workers to abort remaining tasks
+        #
+        # Currently running tasks will complete, but pending tasks will be skipped.
+        #
+        # @return [void]
+        def abort!
+          @mutex.synchronize do
+            @aborted = true
+          end
+        end
+
+        # Returns whether the pool has been aborted
+        #
+        # @return [Boolean] true if abort! was called
+        def aborted?
+          @mutex.synchronize { @aborted }
+        end
+
+        # Waits for all submitted tasks to complete
+        #
+        # @param timeout [Integer, nil] Maximum seconds to wait (nil = indefinite)
+        # @return [Boolean] true if all tasks completed, false if timeout
+        def wait_for_completion(timeout: nil)
+          deadline = timeout ? Time.current + timeout : nil
+
+          @mutex.synchronize do
+            loop do
+              return true if @pending_count == @completed_count
+
+              if deadline
+                remaining = deadline - Time.current
+                return false if remaining <= 0
+
+                @completion_condition.wait(@mutex, remaining)
+              else
+                @completion_condition.wait(@mutex)
+              end
+            end
+          end
+        end
+
+        # Shuts down the pool and waits for workers to terminate
+        #
+        # @param timeout [Integer] Maximum seconds to wait for termination
+        # @return [void]
+        def shutdown(timeout: 5)
+          @shutdown = true
+
+          # Send poison pills to stop workers
+          @size.times { @queue.push(nil) }
+
+          wait_for_termination(timeout: timeout)
+        end
+
+        # Waits for all worker threads to terminate
+        #
+        # @param timeout [Integer] Maximum seconds to wait
+        # @return [void]
+        def wait_for_termination(timeout: 5)
+          deadline = Time.current + timeout
+
+          @workers.each do |worker|
+            remaining = deadline - Time.current
+            break if remaining <= 0
+
+            worker.join(remaining)
+          end
+        end
+
+        private
+
+        # Spawns the worker threads
+        #
+        # @return [void]
+        def spawn_workers
+          @size.times do |i|
+            @workers << Thread.new do
+              Thread.current.name = "pool-worker-#{i}"
+              worker_loop
+            end
+          end
+        end
+
+        # Main worker loop - processes tasks from the queue
+        #
+        # @return [void]
+        def worker_loop
+          loop do
+            task = @queue.pop
+
+            # nil is the poison pill - time to exit
+            break if task.nil?
+
+            # Skip if aborted
+            if aborted?
+              mark_completed
+              next
+            end
+
+            begin
+              task.call
+            rescue StandardError
+              # Errors are handled by the task itself (via rescue in the block)
+              # We just need to ensure we mark completion
+            ensure
+              mark_completed
+            end
+          end
+        end
+
+        # Marks a task as completed and signals waiters
+        #
+        # @return [void]
+        def mark_completed
+          @mutex.synchronize do
+            @completed_count += 1
+            @completion_condition.broadcast
+          end
+        end
+      end
+    end
+  end
+end