llm.rb 12.5.1 → 13.0.0

data/lib/llm/function/async/group.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module LLM::Function::Async
+  ##
+  # Wraps an array of {Async::Task} objects running on a shared
+  # {LLM::Function::Async::Reactor}. The reactor is created on
+  # demand if not provided.
+  class Group < LLM::Function::Group
+    ##
+    # @param [Array<Async::Task>] tasks
+    # @param [Hash] options
+    # @option options [LLM::Function::Async::Reactor] :reactor
+    def initialize(tasks, options = {})
+      @tasks = tasks
+      @reactor = options[:reactor] || LLM::Function::Async::Reactor.new
+    end
+
+    ##
+    # @return [nil]
+    def spawn
+      @tasks.each do |task|
+        task.reactor = @reactor
+        task.spawn
+      end
+      nil
+    ensure
+      @spawned = true
+    end
+
+    ##
+    # @return [Boolean]
+    def alive?
+      @tasks.any?(&:alive?)
+    end
+
+    ##
+    # @return [nil]
+    def interrupt!
+      @tasks.each(&:interrupt!)
+      nil
+    end
+    alias_method :cancel!, :interrupt!
+
+    ##
+    # @return [Array<LLM::Function::Return>]
+    def wait
+      spawn unless @spawned
+      @tasks.map(&:wait)
+    ensure
+      @reactor.stop
+    end
+    alias_method :value, :wait
+  end
+end

data/lib/llm/function/async/reactor.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module LLM::Function::Async
+  ##
+  # Manages an {::Async::Reactor} on a background thread. Work
+  # is submitted through a thread-safe queue and run inside the
+  # reactor. The reactor and its fibers stay on one thread.
+  class Reactor
+    ##
+    # @return [Thread]
+    attr_reader :thread
+
+    def initialize
+      @inbox = Queue.new
+      @thread = ::Thread.new { run }
+    end
+
+    ##
+    # Submit a block to run inside the reactor.
+    # @return [nil]
+    def submit(&block)
+      @inbox << block
+      nil
+    end
+
+    ##
+    # Stop the reactor and wait for the thread to finish.
+    def stop
+      @inbox << :stop
+      @thread.join(5)
+      @thread.kill if @thread.alive?
+    end
+
+    private
+
+    def run
+      reactor = ::Async::Reactor.new
+      reactor.async do
+        loop do
+          work = @inbox.pop
+          break if work == :stop
+          reactor.async { work.call }
+        end
+      end
+      reactor.run
+    end
+  end
+end

data/lib/llm/function/async/task.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module LLM::Function::Async
+  ##
+  # {LLM::Function::Async::Task} wraps a function call in an
+  # {Async::Task} running on a shared
+  # {LLM::Function::Async::Reactor}. The task is spawned lazily
+  # in {#wait} or explicitly in {#spawn}.
+  #
+  # Work is submitted to the reactor through its inbox queue.
+  # Results are bridged back through the task's own queue.
+  class Task < LLM::Function::Task
+    ##
+    # @param [LLM::Function] fn
+    # @param [Hash] options
+    # @option options [LLM::Function::Async::Reactor] :reactor
+    def initialize(fn, options = {})
+      super
+      @reactor = options[:reactor]
+    end
+
+    ##
+    # Assign the reactor. Used when a task is created before its
+    # reactor is available.
+    # @param [LLM::Function::Async::Reactor] reactor
+    def reactor=(reactor)
+      @reactor = reactor
+    end
+
+    ##
+    # Submit the function call to the reactor. The result is
+    # pushed to a queue that {#wait} consumes.
+    # @return [nil]
+    def spawn
+      @queue = Queue.new
+      @alive = true
+      @reactor.submit do
+        @queue << function.call
+      rescue LLM::Interrupt => e
+        @queue << e
+        raise
+      end
+      nil
+    end
+
+    ##
+    # @return [Boolean]
+    def alive?
+      @alive || false
+    end
+
+    ##
+    # Push an interrupt sentinel to the result queue. The reactor
+    # thread continues running but the result is discarded.
+    # @return [nil]
+    def interrupt!
+      if @queue
+        @alive = false
+        @queue << LLM::Interrupt.new
+      end
+      nil
+    end
+    alias_method :cancel!, :interrupt!
+
+    ##
+    # Wait for the result queue to contain a value.
+    # @return [LLM::Function::Return]
+    def wait
+      spawn unless @queue
+      result = @queue.pop
+      @alive = false
+      raise result if LLM::Interrupt === result
+      result
+    end
+    alias_method :value, :wait
+
+    ##
+    # @return [Class]
+    def group_class
+      LLM::Function::Async::Group
+    end
+  end
+end

data/lib/llm/function/fiber/group.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module LLM::Function::Fiber
+  ##
+  # Wraps an array of {Fiber::Task} objects for cooperative
+  # concurrent execution. Interrupts all tasks and waits
+  # for them to complete.
+  class Group < LLM::Function::Group
+    ##
+    # @param [Array<LLM::Function::Fiber::Task>] tasks
+    def initialize(tasks)
+      @tasks = tasks
+    end
+
+    ##
+    # @return [nil]
+    def spawn
+      @tasks.each(&:spawn)
+      nil
+    ensure
+      @spawned = true
+    end
+
+    ##
+    # @return [Boolean]
+    def alive?
+      @tasks.any?(&:alive?)
+    end
+
+    ##
+    # @return [nil]
+    def interrupt!
+      @tasks.each(&:interrupt!)
+      nil
+    end
+    alias_method :cancel!, :interrupt!
+
+    ##
+    # @return [Array<LLM::Function::Return>]
+    def wait
+      spawn unless @spawned
+      @tasks.map(&:wait)
+    end
+    alias_method :value, :wait
+  end
+end

data/lib/llm/function/fiber/task.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module LLM::Function::Fiber
+  ##
+  # {LLM::Function::Fiber::Task LLM::Function::Fiber::Task}
+  # wraps a function call in a scheduler-backed fiber for
+  # cooperative concurrent execution. The fiber is created
+  # lazily when {#wait} is called, not at construction time.
+  #
+  # Requires `Fiber.scheduler` — without one, raise early in
+  # {#wait}. Interrupting a running task raises
+  # {LLM::Interrupt} on the fiber, which stops it at the next
+  # yield point.
+  class Task < LLM::Function::Task
+    ##
+    # @param [LLM::Function] fn
+    # @param [Hash] options
+    def initialize(fn, options = {})
+      super
+    end
+
+    ##
+    # @return [nil]
+    def spawn
+      if Fiber.scheduler.nil?
+        raise ArgumentError, "Fiber concurrency requires Fiber.scheduler"
+      else
+        @fiber = Fiber.schedule { function.call }
+        nil
+      end
+    end
+
+    ##
+    # @return [Boolean]
+    def alive?
+      @fiber&.alive? || false
+    end
+
+    ##
+    # @return [nil]
+    def interrupt!
+      @fiber&.raise(LLM::Interrupt) if @fiber&.alive?
+      function.interrupt!
+      nil
+    end
+    alias_method :cancel!, :interrupt!
+
+    ##
+    # @return [LLM::Function::Return]
+    def wait
+      spawn unless @fiber
+      @result ||= @fiber.value
+    end
+    alias_method :value, :wait
+
+    ##
+    # @return [Class]
+    def group_class
+      LLM::Function::Fiber::Group
+    end
+  end
+end

data/lib/llm/function/{fork_group.rb → fork/group.rb}

@@ -1,17 +1,25 @@
 # frozen_string_literal: true
 
-class LLM::Function
+module LLM::Function::Fork
   ##
-  # The {LLM::Function::Fork::Group} class wraps an array of
-  # {LLM::Function::Task} objects that are running in forked child processes.
-  class Fork::Group
+  # Wraps an array of {Fork::Task} objects that are running
+  # in forked child processes.
+  class Group < LLM::Function::Group
     ##
     # @param [Array<LLM::Function::Task>] tasks
-    # @return [LLM::Function::Fork::Group]
     def initialize(tasks)
       @tasks = tasks
     end
 
+    ##
+    # @return [nil]
+    def spawn
+      @tasks.each(&:spawn)
+      nil
+    ensure
+      @spawned = true
+    end
+
     ##
     # @return [Boolean]
     def alive?
@@ -29,6 +37,7 @@ class LLM::Function
     ##
     # @return [Array<LLM::Function::Return>]
     def wait
+      spawn unless @spawned
       @tasks.map(&:wait)
     end
     alias_method :value, :wait

data/lib/llm/function/fork/job.rb

@@ -24,6 +24,8 @@ class LLM::Function
       runner = @function.runner
       controller = setup(runner)
       @ch.result.write([:result, call!(runner)])
+    rescue LLM::Interrupt
+      @ch.result.write([:interrupt])
     rescue => ex
       @ch.result.write([:result, error(ex)])
     ensure
@@ -52,12 +54,11 @@ class LLM::Function
 
     def setup(runner)
       ready = Queue.new
-      thread = Thread.new do
+      thread = ::Thread.new do
         ready << true
         kind = @ch.control.recv
         next unless kind == :interrupt
-        hook = %i[on_cancel on_interrupt].find { runner.respond_to?(_1) }
-        runner.public_send(hook) if hook
+        ::Thread.main.raise(LLM::Interrupt)
       rescue IOError, ArgumentError
       end
       ready.pop

data/lib/llm/function/fork/task.rb

@@ -4,31 +4,39 @@ class LLM::Function
   ##
   # The {LLM::Function::Fork::Task} class wraps a fork-backed function call
   # and exchanges control and result messages with the child process.
-  class Fork::Task
+  class Fork::Task < LLM::Function::Task
     ##
-    # @param [LLM::Function] function
-    # @param [LLM::Tracer, nil] tracer
-    # @param [Object, nil] span
+    # @param [LLM::Function] fn
+    # @param [Hash] options
+    # @option options [LLM::Tracer, nil] :tracer
     # @return [LLM::Function::Fork::Task]
-    def initialize(function, tracer: nil, span: nil)
-      @function = function
-      @tracer = tracer
-      @span = span
+    def initialize(fn, options = {})
+      super
+      @tracer = options.fetch(:tracer, nil)
+      @spawned = false
       @waited = false
     end
 
     ##
     # @return [LLM::Function::Fork::Task]
     def spawn
-      @ch = LLM::Object.from(control: xchan(:marshal), result: xchan(:marshal))
+      @span = @tracer&.on_tool_start(
+        id: @function.id, name: @function.name,
+        arguments: @function.arguments, model: @function.model
+      )
+      @ch = LLM::Object.from(
+        control: xchan(:marshal),
+        result: xchan(:marshal, sock: Socket::SOCK_STREAM)
+      )
       @pid = Kernel.fork { Fork::Job.new(@function, @ch).call }
+      @spawned = true
       self
     end
 
     ##
     # @return [Boolean]
     def alive?
-      return false if @waited
+      return false if @waited || !@pid
       result = ::Process.waitpid(@pid, ::Process::WNOHANG)
       @waited = !result.nil?
       !@waited
@@ -51,7 +59,9 @@ class LLM::Function
     ##
     # @return [LLM::Function::Return]
     def wait
+      spawn unless @spawned
       kind, data = @ch.result.recv
+      raise LLM::Interrupt if kind == :interrupt
       raise ArgumentError, "Unknown fork message: #{kind.inspect}" unless kind == :result
       result = Return.new(data[:id], data[:name], data[:value])
       reap

data/lib/llm/function/group.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+class LLM::Function
+  ##
+  # Abstract base class for all concurrency strategy groups.
+  # Each strategy (sequential, thread, fiber, async, fork, ractor)
+  # subclasses this and implements {#alive?}, {#interrupt!}, and
+  # {#wait}.
+  class Group
+    ##
+    # @abstract
+    # @return [nil]
+    def spawn
+      raise NotImplementedError
+    end
+
+    ##
+    # @abstract
+    # @return [Boolean]
+    def alive?
+      raise NotImplementedError
+    end
+
+    ##
+    # @abstract
+    # @return [nil]
+    def interrupt!
+      raise NotImplementedError
+    end
+    alias_method :cancel!, :interrupt!
+
+    ##
+    # @abstract
+    # @return [Array<LLM::Function::Return>]
+    def wait
+      raise NotImplementedError
+    end
+    alias_method :value, :wait
+  end
+end

data/lib/llm/function/{ractor_group.rb → ractor/group.rb}

@@ -1,18 +1,25 @@
 # frozen_string_literal: true
 
-class LLM::Function
+module LLM::Function::Ractor
   ##
-  # The {LLM::Function::Ractor::Group} class wraps an array of
-  # {LLM::Function::Ractor::Task} objects that are running
+  # Wraps an array of {Ractor::Task} objects that are running
   # {LLM::Function} calls concurrently.
-  class Ractor::Group
+  class Group < LLM::Function::Group
     ##
     # @param [Array<LLM::Function::Task>] tasks
-    # @return [LLM::Function::Ractor::Group]
     def initialize(tasks)
       @tasks = tasks
     end
 
+    ##
+    # @return [nil]
+    def spawn
+      @tasks.each(&:spawn)
+      nil
+    ensure
+      @spawned = true
+    end
+
     ##
     # @return [Boolean]
     def alive?
@@ -30,6 +37,7 @@ class LLM::Function
     ##
     # @return [Array<LLM::Function::Return>]
     def wait
+      spawn unless @spawned
       @tasks.map(&:wait)
     end
     alias_method :value, :wait

data/lib/llm/function/ractor/job.rb

@@ -35,22 +35,38 @@ class LLM::Function
       waiters = []
       loop do
         case ::Ractor.receive
-        in [:done, *result]
+        in [:done, *data]
+          result ||= data
           done = true
           waiters.each { _1.send(result) }
+          break unless waiters.empty?
           waiters.clear
         in [:alive?, reply]
           reply.send(!done)
         in [:wait, reply]
-          done ? reply.send(result) : waiters << reply
+          if done
+            reply.send(result)
+            break
+          else
+            waiters << reply
+          end
+        in [:interrupt]
+          @tool&.send(:interrupt)
         end
       end
     end
 
     def spawn
-      ::Ractor.new(@mailbox, @runner_class, @id, @name, @arguments) do |mailbox, runner_class, id, name, arguments|
+      @tool = ::Ractor.new(@mailbox, @runner_class, @id, @name, @arguments) do |mailbox, runner_class, id, name, arguments|
+        ::Thread.new do
+          ::Ractor.receive == :interrupt or next
+          ::Thread.main.raise(LLM::Interrupt)
+        rescue ::Ractor::Error
+        end
         kwargs = Hash === arguments ? arguments.transform_keys(&:to_sym) : arguments
         mailbox.send([:done, id, name, runner_class.new.call(**kwargs)])
+      rescue LLM::Interrupt
+        mailbox.send([:done, id, name, {cancelled: true, reason: "interrupted"}])
       rescue => ex
         mailbox.send([:done, id, name, {error: true, type: ex.class.name, message: ex.message}])
       end

data/lib/llm/function/ractor/mailbox.rb

@@ -20,6 +20,8 @@ class LLM::Function
     # @return [Boolean]
     def alive?
       request(:alive?)
+    rescue ::Ractor::ClosedError
+      false
     end
 
     ##
@@ -28,6 +30,13 @@ class LLM::Function
       request(:wait)
     end
 
+    ##
+    # @return [nil]
+    def interrupt!
+      task.send([:interrupt])
+      nil
+    end
+
     private
 
     def request(type)

data/lib/llm/function/ractor/task.rb

@@ -5,31 +5,38 @@ class LLM::Function
   # The {LLM::Function::Ractor::Task} class wraps a ractor-backed function
   # call and delegates mailbox coordination to
   # {LLM::Function::Ractor::Mailbox}.
-  class Ractor::Task
+  class Ractor::Task < LLM::Function::Task
     ##
     # @return [LLM::Function::Ractor::Mailbox]
     attr_reader :mailbox
 
     ##
-    # @param [Class] runner_class
-    # @param [String, nil] id
-    # @param [String] name
-    # @param [Hash, Array, nil] arguments
-    # @param [LLM::Tracer, nil] tracer
-    # @param [Object, nil] span
+    # @param [LLM::Function] fn
+    # @param [Hash] options
+    # @option options [LLM::Tracer, nil] :tracer
+    # @option options [Class] :runner_class
+    # @option options [String, nil] :id
+    # @option options [String] :name
+    # @option options [Hash, Array, nil] :arguments
+    # @option options [String, nil] :model
     # @return [LLM::Function::Ractor::Task]
-    def initialize(runner_class, id, name, arguments, tracer: nil, span: nil)
-      @runner_class = runner_class
-      @id = id
-      @name = name
-      @arguments = arguments
-      @tracer = tracer
-      @span = span
+    def initialize(fn, options = {})
+      super
+      @runner_class = options.fetch(:runner_class)
+      @id = options.fetch(:id)
+      @name = options.fetch(:name)
+      @arguments = options.fetch(:arguments)
+      @model = options.fetch(:model, nil)
+      @tracer = options.fetch(:tracer, nil)
     end
 
     ##
     # @return [LLM::Function::Ractor::Task]
     def spawn
+      @span = @tracer&.on_tool_start(
+        id: @id, name: @name,
+        arguments: @arguments, model: @model
+      )
       @mailbox = Ractor::Mailbox.new(build_task)
       self
     end
@@ -37,12 +44,13 @@ class LLM::Function
     ##
     # @return [Boolean]
     def alive?
-      mailbox.alive?
+      @mailbox&.alive? || false
     end
 
     ##
     # @return [nil]
     def interrupt!
+      mailbox&.interrupt!
       nil
     end
     alias_method :cancel!, :interrupt!
@@ -50,6 +58,7 @@ class LLM::Function
     ##
     # @return [LLM::Function::Return]
     def wait
+      spawn unless @mailbox
       id, name, value = mailbox.wait
       result = Return.new(id, name, value)
       @tracer&.on_tool_finish(result:, span: @span)

data/lib/llm/function/{call_group.rb → sequential/group.rb}

@@ -1,19 +1,24 @@
 # frozen_string_literal: true
 
-class LLM::Function
+module LLM::Function::Sequential
   ##
-  # The {LLM::Function::CallGroup} class wraps an array of
-  # {LLM::Function} objects for sequential execution.
-  #
-  # It provides the same basic interface as the concurrent group
+  # Wraps an array of {LLM::Function} objects for sequential
+  # execution. Provides the same interface as concurrent group
   # wrappers so callers can flow through `spawn(strategy).wait`
-  # uniformly, even when the selected strategy is direct calls.
-  class CallGroup
+  # uniformly.
+  class Group < LLM::Function::Group
     ##
     # @param [Array<LLM::Function>] functions
-    # @return [LLM::Function::CallGroup]
     def initialize(functions)
       @functions = functions
+      @owner = nil
+    end
+
+    ##
+    # @return [nil]
+    def spawn
+      # no-op — execution happens in wait
+      nil
     end
 
     ##
@@ -25,6 +30,7 @@ class LLM::Function
     ##
     # @return [nil]
     def interrupt!
+      @owner&.raise(LLM::Interrupt)
       nil
     end
     alias_method :cancel!, :interrupt!
@@ -32,7 +38,10 @@ class LLM::Function
     ##
     # @return [Array<LLM::Function::Return>]
     def wait
+      @owner = Thread.current
       @functions.map(&:call)
+    ensure
+      @owner = nil
     end
     alias_method :value, :wait
   end