llm.rb 16.0.0 → 17.0.0

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

@@ -35,10 +35,10 @@ module LLM::Function::Ractor
     alias_method :cancel!, :interrupt!
 
     ##
+    # @see LLM::Function::Group#wait
     # @return [Array<LLM::Function::Return>]
     def wait
-      spawn unless @spawned
-      @tasks.map(&:wait)
+      super
     end
     alias_method :value, :wait
   end

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

@@ -14,13 +14,14 @@ class LLM::Function
     # @param [String] name
     # @param [Hash, Array, nil] arguments
     # @return [LLM::Function::Ractor::Job]
-    def initialize(mailbox, result, runner_class, id, name, arguments)
+    def initialize(mailbox, result, runner_class, id, name, arguments, cookie)
       @mailbox = mailbox
       @result = result
       @runner_class = runner_class
       @id = id
       @name = name
       @arguments = arguments
+      @cookie = cookie
     end
 
     ##
@@ -70,7 +71,8 @@ class LLM::Function
     end
 
     def spawn
-      @tool = ::Ractor.new(@mailbox, @runner_class, @id, @name, @arguments) do |mailbox, runner_class, id, name, arguments|
+      @tool = ::Ractor.new(@mailbox, @runner_class, @id, @name, @arguments, @cookie) do |mailbox, runner_class, id, name, arguments, cookie|
+        finished_at = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
         ##
         # Before the watcher exists, because an interrupt can arrive
         # first: it is a message, and it waits in the inbox until the
@@ -88,7 +90,7 @@ class LLM::Function
         runner = runner_class.new
         ::Thread.new do
           ##
-          # Only the receive is guarded: it raises when the ractor this
+          # Only the receive is rescued: it raises when the ractor this
           # one talks to has gone, and nothing else here should be
           # answerable to that rescue. A hook that raises must not be
           # swallowed by it, and must not take the raise with it either -
@@ -127,11 +129,11 @@ class LLM::Function
         # work is done is a no-op rather than a reason to throw the
         # result away.
         window.finished!
-        mailbox.send([:done, id, name, result])
+        mailbox.send([:done, id, name, result, finished_at.()])
       rescue LLM::Interrupt
-        mailbox.send([:done, id, name, {cancelled: true, reason: "interrupted"}])
+        mailbox.send([:done, id, name, {interrupt: true, cookie:}, finished_at.()])
       rescue => ex
-        mailbox.send([:done, id, name, {error: true, type: ex.class.name, message: ex.message}])
+        mailbox.send([:done, id, name, {error: true, type: ex.class.name, message: ex.message}, finished_at.()])
       end
     end
   end

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

@@ -10,6 +10,18 @@ class LLM::Function
     # @return [LLM::Function::Ractor::Mailbox]
     attr_reader :mailbox
 
+    ##
+    # @return [LLM::Tracer, nil]
+    attr_reader :tracer
+
+    ##
+    # @return [String]
+    attr_reader :cookie
+
+    ##
+    # @return [Object]
+    attr_reader :span
+
     ##
     # @param [LLM::Function] fn
     # @param [Hash] options
@@ -27,18 +39,18 @@ class LLM::Function
       @name = options.fetch(:name)
       @arguments = options.fetch(:arguments)
       @model = options.fetch(:model, nil)
-      @tracer = options.fetch(:tracer, nil)
       @cancelled = false
+      @cookie = SecureRandom.hex
     end
 
     ##
     # @return [LLM::Function::Ractor::Task]
     def spawn
-      return if @guarded
       @span = @tracer&.on_tool_start(
         id: @id, name: @name,
         arguments: @arguments, model: @model
       )
+      return if intercepted?
       ##
       # The result is delivered to a ractor of this task's own rather
       # than through its mailbox. The mailbox ractor answers `alive?`
@@ -101,13 +113,15 @@ class LLM::Function
     # {LLM::Function::Thread::Task#wait} answers from the thread's value.
     # @return [LLM::Function::Return]
     def wait
-      return @guarded if @guarded
+      return @intercepted if intercepted?
       @result ||= begin
         spawn unless @mailbox
-        id, name, value = mailbox.wait
-        result = Return.new(id, name, value)
-        @tracer&.on_tool_finish(result:, span: @span)
-        result
+        id, name, value, @finished_at = mailbox.wait
+        if Hash === value and value[:interrupt] and value[:cookie] == @cookie
+          LLM::Interrupt.new
+        else
+          Return.new(id, name, value)
+        end
       end
     end
     alias_method :value, :wait
@@ -121,8 +135,17 @@ class LLM::Function
     private
 
     def build_task(result)
-      ::Ractor.new(result, @runner_class, @id, @name, @arguments) do |result, runner_class, id, name, arguments|
-        LLM::Function::Ractor::Job.new(::Ractor.current, result, runner_class, id, name, arguments).call
+      @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      ::Ractor.new(result, @runner_class, @id, @name, @arguments, @cookie) do |result, runner_class, id, name, arguments, cookie|
+        LLM::Function::Ractor::Job.new(
+          ::Ractor.current,
+          result,
+          runner_class,
+          id,
+          name,
+          arguments,
+          cookie
+        ).call
       end
     end
   end

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

@@ -51,10 +51,11 @@ module LLM::Function::Sequential
     alias_method :cancel!, :interrupt!
 
     ##
+    # @see LLM::Function::Group#wait
     # @return [Array<LLM::Function::Return>]
     def wait
       @owner = Thread.current
-      @tasks.map(&:wait)
+      super
     ensure
       @owner = nil
     end

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

@@ -29,7 +29,14 @@ module LLM::Function::Sequential
     ##
     # @return [LLM::Function::Return]
     def wait
-      @result ||= @guarded || function.call
+      return @intercepted if intercepted?
+      @result = @result ? @result : begin
+        @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @result = LLM::Object.from(unbox: function.call)
+        @finished_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @result
+      end
+      @result&.unbox
     end
     alias_method :value, :wait
 

data/lib/llm/function/task.rb

@@ -11,18 +11,48 @@ class LLM::Function
     # @return [LLM::Function]
     attr_reader :function
 
+    ##
+    # The tracer for the task
+    # @return [LLM::Tracer, nil]
+    attr_reader :tracer
+
+    ##
+    # The span returned by {LLM::Tracer#on_tool_start}
+    # @return [Object]
+    attr_reader :span
+
+    ##
+    # Returns when a task started, or nil
+    # @note
+    #  This method captures a monotonic clock
+    #  time (Process::CLOCK_MONOTONIC) rather
+    #  than a Time object.
+    # @return [Float, nil]
+    attr_reader :started_at
+
+    ##
+    # Returns when a task finished, or nil
+    # @note
+    #  This method captures a monotonic clock
+    #  time (Process::CLOCK_MONOTONIC) rather
+    #  than a Time object.
+    # @return [Float, nil]
+    attr_reader :finished_at
+
     ##
     # @param [LLM::Function] fn
     # @param [Hash] options
     #  An optional set of options that are specific
     #  to a given concurrency strategy.
-    # @option options [LLM::Function::Return, nil] :guarded
-    #  A blocked return produced by the function's guard, or the in-band
+    # @option options [LLM::Function::Return, nil] :intercepted
+    #  A blocked return produced by the function's intercept, or the in-band
     #  error for a tool that cannot be built. When set, the task yields it
     #  without running the tool.
     def initialize(fn, options = {})
       @function = fn
-      @guarded = options[:guarded]
+      @intercepted = options[:intercepted]
+      @tracer = options[:tracer]
+      @finished_at = nil
     end
 
     ##
@@ -48,8 +78,18 @@ class LLM::Function
     alias_method :cancel!, :interrupt!
 
     ##
+    # This method returns an instance of
+    # {LLM::Function::Return} or {LLM::Interrupt}
+    # when the task has received an interrupt.
+    #
+    # An exception that occurs inside a tool is
+    # rescued, and returned by this method as a
+    # {LLM::Function::Return} object. It can be
+    # distinguished from other returns through
+    # the {LLM::Function::Return#error?} method.
+    #
     # @abstract
-    # @return [LLM::Function::Return]
+    # @return [LLM::Function::Return, LLM::Interrupt]
     def wait
       raise NotImplementedError
     end
@@ -61,5 +101,13 @@ class LLM::Function
     def group_class
       raise NotImplementedError
     end
+
+    ##
+    # Returns true when an intercept has
+    # returned {LLM::Function::Return}.
+    # @return [Boolean]
+    def intercepted?
+      LLM::Function::Return === @intercepted
+    end
   end
 end

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

@@ -36,10 +36,10 @@ module LLM::Function::Thread
     alias_method :cancel!, :interrupt!
 
     ##
+    # @see LLM::Function::Group#wait
     # @return [Array<LLM::Function::Return>]
     def wait
-      spawn unless @spawned
-      @tasks.map(&:wait)
+      super
     end
     alias_method :value, :wait
   end

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

@@ -31,7 +31,13 @@ module LLM::Function::Thread
     ##
     # @return [nil]
     def spawn
-      return if @guarded
+      @span = @tracer&.on_tool_start(
+        id: @function.id,
+        name: @function.name,
+        arguments: @function.arguments,
+        model: @function.model
+      )
+      return if intercepted?
       @ready = Queue.new
       @thread = ::Thread.new do
         ##
@@ -58,8 +64,10 @@ module LLM::Function::Thread
         # instead, and opens on the call.
         ::Thread.new { @window.interrupt! } if @cancelled
         @window.running!
+        @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         function.call
       ensure
+        @finished_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         ##
         # The window closes before the hook runs, so a cancel that arrives
         # once the call has returned finds nothing to interrupt - which is
@@ -70,13 +78,25 @@ module LLM::Function::Thread
         # cancelled, because a tool's state belongs to the thread its call
         # runs on, and the caller's thread is not that thread.
         #
-        # It runs for a call that was interrupted and not for a call that
-        # was asked about: the window is the frame that decides whether a
-        # raise is issued, so it is the frame that knows, and
-        # `Window#interrupted?` is true only where the raise was. A cancel
-        # that arrives while the call is returning, and a held cancel whose
-        # tool finished before the watcher was scheduled, are both cancels
-        # that interrupted nothing - and neither tells the tool.
+        # It runs where an ask was taken up for this call, and not for a
+        # cancel the window never asked about: the window is the frame that
+        # decides whether a raise is issued, so it is the frame that knows,
+        # and `Window#interrupted?` is true where one was issued.
+        #
+        # **Issued is not delivered, and this strategy is the one where the
+        # two come apart least.** The raise here is a `Thread#raise`, and a
+        # thread can be interrupted where it stands, so a cancel that the
+        # window asks about lands on the call. `:fiber` and `:async` ask a
+        # scheduler instead, which places the raise at the tool's next
+        # suspension - so there a tool that never suspends is asked about
+        # and never reached, and the hook runs for it all the same.
+        #
+        # That is the side to be on, and a tool whose own rescue answers the
+        # interrupt rather than raising is why: it was interrupted, and its
+        # hook is the only thing left that can say so on its own thread.
+        # What does not tell the tool is a cancel the window never asked
+        # about - one that arrives once the call has returned - which is the
+        # no-op {LLM::Function::Return#interrupt!} already says one is.
         #
         # On the job's own thread the hook can only run after the call's
         # frame has ended - you cannot run code on a thread blocked inside
@@ -127,9 +147,15 @@ module LLM::Function::Thread
     ##
     # @return [LLM::Function::Return]
     def wait
-      return @guarded if @guarded
+      return @intercepted if intercepted?
+      return @result.unbox if @result
       spawn unless @thread
-      @thread.value
+      begin
+        @result = LLM::Object.from(unbox: @thread.value)
+      rescue LLM::Interrupt => ex
+        @result = LLM::Object.from(unbox: ex)
+      end
+      @result.unbox
     end
     alias_method :value, :wait
 

data/lib/llm/function/window.rb

@@ -23,6 +23,22 @@ class LLM::Function
   # are one call here, and everything else - the three states, and what
   # "this call was interrupted" means - is this object's, so the strategies
   # agree about where a call begins and ends.
+  #
+  # **A raise a call cannot take is not delivered outside the call.** The
+  # scheduler places a scheduled raise, and a tool that never suspends
+  # gives it no suspension inside the call to be placed at - so one is left
+  # over. What is asserted is the half anything outside the call could
+  # notice, and it is the caller's frame rather than the tool's: the frame
+  # that waits on the task ends cleanly, and a sibling task on the same
+  # reactor runs.
+  #
+  # **Where the leftover goes is reasoned, not observed.** The raise is
+  # aimed at the fibre the tool runs in, and the frame those examples watch
+  # is a different fibre - a raise in one is not the other's exception, so
+  # they cannot see it either way. That it is discarded rather than
+  # delivered follows from what the scheduler can place: a raise scheduled
+  # for a fibre is placed when that fibre resumes, and a fibre whose tool
+  # never suspends does not resume before it ends.
   class Window
     ##
     # @param [Thread, nil] thread

data/lib/llm/function.rb

@@ -31,7 +31,6 @@
 #   end
 class LLM::Function
   require_relative "function/registry"
-  require_relative "function/tracing"
   require_relative "function/array"
   require_relative "function/group"
   require_relative "function/sequential/group"
@@ -51,7 +50,6 @@ class LLM::Function
   require_relative "function/ractor/group"
 
   extend LLM::Function::Registry
-  prepend LLM::Function::Tracing
 
   ##
   # Returns strategies that execute in an isolated environment.
@@ -183,11 +181,11 @@ class LLM::Function
   attr_accessor :model
 
   ##
-  # Returns the guard class that protects this function, or nil.
-  # The context stamps the guard onto the functions it binds, so any task
-  # built from this function checks it before the tool runs.
-  # @return [Class<LLM::Guard>, nil]
-  attr_accessor :guard
+  # Returns the intercept class that supervises this function, or nil.
+  # The context stamps the intercept onto the functions it binds, so any
+  # task built from this function checks it before the tool runs.
+  # @return [Class<LLM::Intercept>, nil]
+  attr_accessor :intercept
 
   ##
   # @param [String] name The function name
@@ -278,49 +276,22 @@ class LLM::Function
   #   task = tool.task(:thread)
   #   result = task.value
   #
-  # @note
-  #   An in-process strategy resolves the tool here, so a task that has
-  #   not been spawned already holds a live instance, and
-  #   {LLM::Function::Array#task} builds one for every pending function at
-  #   once. A tool that cannot be built carries the same in-band error the
-  #   guard produces rather than raising, so a constructor's failure
-  #   answers the model on every strategy.
   # @param [Symbol] strategy
   #   Controls concurrency strategy:
   #   - `:sequential`: Call the function sequentially
   #   - `:thread`: Use threads
   #   - `:async`: Use async tasks (requires async gem)
-  #   - `:fork`: Use a forked child process (requires xchan.rb support)
+  #   - `:fork`: Use a forked child process (requires xchan.rb gem)
   #   - `:fiber`: Use scheduler-backed fibers (requires Fiber.scheduler)
-  #   - `:ractor`: Use Ruby ractors (class-based tools only; MCP tools are not supported)
+  #   - `:ractor`: Use Ruby ractors
   #
   # @return [LLM::Function::Task]
   #   Returns a task whose `#value` is an {LLM::Function::Return}.
   def task(strategy, options = {})
-    ##
-    # Check the function's guard on the calling thread before handing
-    # the tool to the strategy. The task carries the blocked result and
-    # returns it without running if the guard intervenes.
-    options = options.merge(guarded: @guard&.call(function: self))
-    ##
-    # Resolve the runner here, on the calling thread, before the task
-    # returned below exists for another thread to interrupt.
-    #
-    # `#interrupt!` resolves the same instance, and `@_runner ||=` is a
-    # check-then-create: reached from two threads at once it builds two,
-    # runs the call on one and tells the hook on the other.
-    #
-    # `:async` is in the list because its reactor runs on a background
-    # thread, which is the exposure `:thread` has. The cost is that the
-    # tool is built on the calling thread rather than inside the reactor,
-    # so a tool whose `initialize` wants a current `Async::Task` or a
-    # scheduler-installed fiber does not get one.
-    #
-    # A guarded task runs nothing, so it resolves nothing. A strategy in
-    # {LLM::Function.isolated} stays lazy on purpose, because there the
-    # tool is built in the child process or the ractor and this instance
-    # is not the one that runs.
-    options = options.merge(guarded: options[:guarded] || resolve(strategy))
+    ioptions = @intercept&.options
+    options  = options.merge(intercepted: @intercept&.call(function: self, **ioptions))
+    options  = options.merge(tracer:, intercepted: options[:intercepted] || resolve(strategy))
+
     case strategy
     when :sequential
       Sequential::Task.new(self, options)
@@ -333,13 +304,13 @@ class LLM::Function
       Fiber::Task.new(self, options)
     when :fork
       LLM.require "xchan", "~> 0.24" unless defined?(::Chan::UNIXSocket)
-      Fork::Task.new(self, options.merge(tracer: @tracer))
+      Fork::Task.new(self, options)
     when :ractor
       raise LLM::RactorError, "Ractor concurrency only supports class-based tools" unless Class === @runner
       if @runner.respond_to?(:skill?) && @runner.skill?
         raise LLM::RactorError, "Ractor concurrency does not support skill-backed tools"
       end
-      Ractor::Task.new(self, options.merge(runner_class: @runner, id:, name:, arguments:, tracer: @tracer, model:))
+      Ractor::Task.new(self, options.merge(runner_class: @runner, id:, name:, arguments:, model:))
     else
       raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :sequential, :thread, :fiber, :async, :fork, or :ractor"
     end
@@ -507,7 +478,7 @@ class LLM::Function
   #
   # {#call_function} resolves inside its own rescue, and that rescue is what
   # answers the model with an error rather than raising into the turn.
-  # Resolving earlier keeps that promise by producing the return the guard
+  # Resolving earlier keeps that promise by producing the return the intercept
   # would have produced.
   #
   # An interrupt is re-raised rather than answered, which is what

data/lib/llm/intercept/multi.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+class LLM::Intercept
+  ##
+  # The {LLM::Intercept::Multi LLM::Intercept::Multi}
+  # class combines multiple intercepts into a single
+  # intercept.
+  #
+  # The first intercept that returns an instance of
+  # {LLM::Function::Return LLM::Function::Return}
+  # stops all other intercepts from running, and when
+  # an intercept returns `nil` the next one in the list
+  # is called. When all intercepts return nil, the tool
+  # is called.
+  #
+  # @see LLM::Intercept
+  class Multi < self
+    ##
+    # @param [LLM::Provider] llm
+    #  An {LLM::Provider LLM::Provider}.
+    # @param [Array<LLM::Intercept>] intercepts
+    #  One or more subclasses of {LLM::Intercept LLM::Intercept}.
+    def initialize(llm, *intercepts)
+      @llm = llm
+      @intercepts = intercepts
+    end
+
+    ##
+    # @param (see LLM::Intercept#call)
+    # @return (see LLM::Intercept#call)
+    def call(function:, **opts)
+      @intercepts.each do |intercept|
+        intercept = intercept.new(llm).tap { _1.instance_variable_set(:@context, context) }
+        result = intercept.call(function:, **opts)
+        return result if LLM::Function::Return === result
+      end
+      nil
+    end
+  end
+end

data/lib/llm/intercept/null.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class LLM::Intercept
+  ##
+  # The {LLM::Intercept::Null LLM::Intercept::Null} class
+  # is the default intercept, and it does nothing but allow
+  # the tool call through.
+  #
+  # @see LLM::Intercept
+  class Null < self
+    ##
+    # @param (see LLM::Intercept#call)
+    # @return (see LLM::Intercept#call)
+    def call(function:, **opts)
+      nil
+    end
+  end
+end

data/lib/llm/intercept.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # When a model requests a tool call the
+  # runtime represents it as an {LLM::Function}
+  # that an intercept can see before it is
+  # called. An intercept can return its own
+  # {LLM::Function::Return} object that acts
+  # as the response to the tool call, or it
+  # can return `nil` to let the tool call
+  # execute as normal.
+  #
+  # An intercept can also see the parameters
+  # a model has requested to send to a tool,
+  # and it can modify them in-place before the
+  # tool is called.
+  #
+  # The default intercept is
+  # {LLM::Intercept::Null LLM::Intercept::Null}
+  # and it is a noop.
+  class Intercept
+    require_relative "intercept/null"
+    require_relative "intercept/multi"
+
+    ##
+    # @param [LLM::Provider] llm
+    #  An {LLM::Provider LLM::Provider}.
+    # @param [Array<LLM::Intercept>] intercepts
+    #  One or more subclasses of {LLM::Intercept LLM::Intercept}
+    # @return [LLM::Intercept::Multi]
+    def self.multi(llm, *intercepts)
+      Multi.new(
+        llm,
+        *intercepts
+      )
+    end
+
+    ##
+    # @return [LLM::Provider]
+    attr_reader :llm
+
+    ##
+    # @param [LLM::Provider] llm
+    # @return [LLM::Intercept]
+    def initialize(llm)
+      @llm = llm
+    end
+
+    ##
+    # @abstract
+    # @param [LLM::Function] function
+    #  A pending function
+    # @param opts [Hash]
+    #  The contents of `intercept_options:`
+    # @return [LLM::Function::Return, Object]
+    #  When this method returns a
+    #  {LLM::Function::Return LLM::Function::Return},
+    #  object it stops a tool call
+    #  in its tracks and the Return
+    #  object is the answer we give
+    #  to the model for the tool call
+    #  that was stopped. Any other return
+    #  value lets the tool call through.
+    def call(function:, **opts)
+      raise NotImplementedError
+    end
+
+    ##
+    # Returns the options the context passed to `intercept_options:`.
+    # @return [Hash]
+    def options
+      @options || {}
+    end
+
+    private
+
+    ##
+    # @return [LLM::Context]
+    def context
+      @context
+    end
+
+    ##
+    # @return [LLM::Stream]
+    def stream
+      context.params[:stream]
+    end
+
+    ##
+    # @return [LLM::Buffer]
+    def messages
+      context.messages
+    end
+  end
+end

data/lib/llm/message.rb

@@ -256,7 +256,7 @@ module LLM
 
     def function_missing(name)
       LLM.function(name) do |fn|
-        fn.define { raise LLM::NoSuchToolError, "tool not found" }
+        fn.define { raise LLM::NoSuchToolError, "tool '#{name}' not found" }
       end
     end