llm.rb 12.6.0 → 13.0.0

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

@@ -54,11 +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
-        Thread.main.raise(LLM::Interrupt)
+        ::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,6 +59,7 @@ 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

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

@@ -39,11 +39,17 @@ class LLM::Function
           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
@@ -52,9 +58,9 @@ class LLM::Function
 
     def spawn
       @tool = ::Ractor.new(@mailbox, @runner_class, @id, @name, @arguments) do |mailbox, runner_class, id, name, arguments|
-        Thread.new do
+        ::Thread.new do
           ::Ractor.receive == :interrupt or next
-          Thread.main.raise(LLM::Interrupt)
+          ::Thread.main.raise(LLM::Interrupt)
         rescue ::Ractor::Error
         end
         kwargs = Hash === arguments ? arguments.transform_keys(&:to_sym) : arguments

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
 
     ##

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,7 +44,7 @@ class LLM::Function
     ##
     # @return [Boolean]
     def alive?
-      mailbox.alive?
+      @mailbox&.alive? || false
     end
 
     ##
@@ -51,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,22 +1,26 @@
 # 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
+
     ##
     # @return [Boolean]
     def alive?

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module LLM::Function::Sequential
+  ##
+  # The {LLM::Function::Sequential::Task} class wraps a single
+  # direct function call behind the same task-like interface
+  # used by spawned concurrency modes.
+  class Task < LLM::Function::Task
+    ##
+    # @param [LLM::Function] fn
+    # @param [Hash] options
+    def initialize(fn, options = {})
+      @function = fn
+    end
+
+    ##
+    # @return [nil]
+    def spawn
+      # no-op — execution happens in wait
+    end
+
+    ##
+    # @return [Boolean]
+    def alive?
+      false
+    end
+
+    ##
+    # @return [nil]
+    def interrupt!
+      function.interrupt!
+      nil
+    end
+    alias_method :cancel!, :interrupt!
+
+    ##
+    # @return [LLM::Function::Return]
+    def wait
+      @result ||= function.call
+    end
+    alias_method :value, :wait
+
+    ##
+    # @return [Class]
+    def group_class
+      LLM::Function::Sequential::Group
+    end
+  end
+end

data/lib/llm/function/task.rb

@@ -2,82 +2,59 @@
 
 class LLM::Function
   ##
-  # The {LLM::Function::Task} class wraps a single concurrent function call and
-  # provides a small, uniform interface across threads, scheduler-backed fibers,
-  # and async tasks.
+  # This class is the superclass that all concurrency
+  # strategies must subclass in order to implement their
+  # own Task class. It provides a common interface that
+  # is the same across all concurrency strategies.
   class Task
     ##
-    # @return [Object]
-    attr_reader :task
+    # @return [LLM::Function]
+    attr_reader :function
 
     ##
-    # @return [LLM::Function, nil]
-    attr_reader :function
+    # @param [LLM::Function] fn
+    # @param [Hash] options
+    #  An optional set of options that are specific
+    #  to a given concurrency strategy.
+    def initialize(fn, options = {})
+      @function = fn
+    end
 
     ##
-    # @param [Thread, Fiber, Async::Task, Ractor, LLM::Function::Ractor::Task] task
-    # @param [LLM::Function, nil] function
-    # @return [LLM::Function::Task]
-    def initialize(task, function = nil)
-      @task = task
-      @function = function
+    # @abstract
+    # @return [nil]
+    def spawn
+      raise NotImplementedError
     end
 
     ##
+    # @abstract
     # @return [Boolean]
     def alive?
-      return task.alive? if task.respond_to?(:alive?)
-      false
+      raise NotImplementedError
     end
 
     ##
+    # @abstract
     # @return [nil]
     def interrupt!
-      case task
-      when Thread
-        task.raise(LLM::Interrupt)
-      when Fiber
-        task.raise(LLM::Interrupt) if task.alive?
-      else
-        if defined?(::Async::Task) and ::Async::Task === task
-          task.fiber&.raise(LLM::Interrupt) if task.alive?
-        elsif task.respond_to?(:interrupt!)
-          task.interrupt!
-        end
-      end
-      function&.interrupt!
-      nil
+      raise NotImplementedError
     end
     alias_method :cancel!, :interrupt!
 
     ##
+    # @abstract
     # @return [LLM::Function::Return]
     def wait
-      if Thread === task
-        task.value
-      elsif Fiber === task
-        fiber.alive? ? scheduler.run : nil
-        task.value
-      else
-        task.wait
-      end
+      raise NotImplementedError
     end
     alias_method :value, :wait
 
     ##
+    # @abstract
     # @return [Class]
     def group_class
-      case task
-      when Thread then LLM::Function::ThreadGroup
-      when Fiber then LLM::Function::FiberGroup
-      else LLM::Function::TaskGroup
-      end
-    end
-
-    private
-
-    def scheduler
-      Fiber.scheduler
+      raise NotImplementedError
     end
   end
 end