llm.rb 16.0.0 → 17.0.1

data/lib/llm/tracer/telemetry.rb

@@ -139,7 +139,7 @@ module LLM
     ##
     # @param (see LLM::Tracer#on_tool_finish)
     # @return (see LLM::Tracer#on_tool_finish)
-    def on_tool_finish(result:, span:)
+    def on_tool_finish(result:, span:, started_at:, finished_at:)
       return nil unless span
       attributes = {
         "gen_ai.tool.call.id" => result.id,
@@ -154,15 +154,69 @@ module LLM
     ##
     # @param (see LLM::Tracer#on_tool_error)
     # @return (see LLM::Tracer#on_tool_error)
-    def on_tool_error(ex:, span:)
+    def on_tool_error(ex:, span:, started_at:, finished_at:)
       return nil unless span
-      attributes = {"error.type" => ex.class.to_s}.compact
+      attributes = {"error.type" => ex.value[:type]}.compact
       attributes.each { span.set_attribute(_1, _2) }
       span.add_event("gen_ai.tool.finish")
-      span.status = ::OpenTelemetry::Trace::Status.error(ex.message)
+      span.status = ::OpenTelemetry::Trace::Status.error(ex.value[:message].to_s)
+      span.tap(&:finish)
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_interrupt)
+    # @return (see LLM::Tracer#on_tool_interrupt)
+    def on_tool_interrupt(ex:, span:, started_at:, finished_at:)
+      return nil unless span
+      attributes = {"error.type" => "LLM::Interrupt"}
+      attributes.each { span.set_attribute(_1, _2) }
+      span.status = ::OpenTelemetry::Trace::Status.error("tool interrupted")
+      span.add_event("gen_ai.tool.finish")
       span.tap(&:finish)
     end
 
+    ##
+    # @param [Symbol] scope
+    # @param [Object] span
+    # @param [String] request_id
+    # @return [void]
+    def on_interrupt(scope:, span: nil, request_id: nil)
+      case scope
+      when :request
+        ##
+        # This is where we match on_request_start and
+        # close the span it had opened. It is the only
+        # scope where we have a span to close.
+        attributes = {"error.type" => "LLM::Interrupt"}
+        attributes.each { span.set_attribute(_1, _2) }
+        span.status = OpenTelemetry::Trace::Status.error("request interrupted")
+        span.add_event("gen_ai.request.finish")
+        span.tap(&:finish)
+      when :tool
+        ##
+        # This means an interrupt was received when
+        # an agent was running tools and no request
+        # was active at the time.
+        #
+        # There is no span to close, and each tool
+        # call is closed by #{on_tool_interrupt}.
+        # There is seemingly nothing useful to do
+        # here.
+      when :agent
+        ##
+        # This means an interrupt was received when
+        # an agent was between requests and no request
+        # was active at the time.
+        #
+        # There is no span to close, and no tools are
+        # running. There is seemingly nothing useful to
+        # do here.
+      else
+        raise LLM::Error,
+              "scope '#{scope}' is not a valid tracer scope"
+      end
+    end
+
     ##
     # @note
     # This method returns an empty array for exporters that
@@ -188,6 +242,17 @@ module LLM
       nil
     end
 
+    ##
+    # This method is called when the outermost
+    # {LLM::Provider#with_tracer} method has returned
+    # control to the caller. It will flush the queue
+    # of any spans that are not yet exported, and
+    # it is called after a trace has finished.
+    # @return [nil]
+    def on_exit
+      flush!
+    end
+
     private
 
     ##

data/lib/llm/tracer.rb

@@ -9,11 +9,22 @@ module LLM
   # {LLM::Tracer::Logger LLM::Tracer::Logger} for example
   # tracer implementations.
   class Tracer
+    require_relative "tracer/registry"
+    require_relative "tracer/rescue"
+
+    ##
+    # @param [Class] klass
+    #  A subclalss of {LLM::Tracer}
+    # @return [void]
+    def self.inherited(klass)
+      klass.prepend Rescue
+    end
+
     require_relative "tracer/logger"
     require_relative "tracer/telemetry"
     require_relative "tracer/null"
     require_relative "tracer/pretty_logger"
-    require_relative "tracer/registry"
+    require_relative "tracer/multi"
 
     ##
     # Returns the registry that counts the open scopes for each tracer.
@@ -57,6 +68,7 @@ module LLM
     def self.pretty_logger(llm, **options)
       PrettyLogger.new(llm, **options)
     end
+    (class << self; self; end).alias_method(:pretty, :pretty_logger)
 
     ##
     # Builds a {LLM::Tracer::Logger} for a provider.
@@ -80,6 +92,24 @@ module LLM
       Telemetry.new(llm, **options)
     end
 
+    ##
+    # Builds a {LLM::Tracer::Multi}
+    # @param [LLM::Provider] llm
+    # @param [Array<LLM::Tracer>] tracers
+    #  One or more tracers
+    # @return [LLM::Tracer::Multi]
+    def self.multi(llm, *tracers)
+      Multi.new(
+        *tracers.map do |tracer|
+          if Class === tracer
+            tracer.new(llm)
+          else
+            tracer
+          end
+        end
+      )
+    end
+
     ##
     # @return [LLM::Provider]
     attr_reader :llm
@@ -95,26 +125,25 @@ module LLM
     end
 
     ##
-    # Called when the tracer is no longer in use.
+    # This method is called when a tracer exits a scope that
+    # has been opened by {LLM::Provider#with_tracer}.
     #
-    # A tracer that holds something - a file, a span, a connection pool -
-    # releases it here. The default does nothing, because most tracers hold
-    # nothing that needs releasing.
+    # It is unlikely you will ever use the {LLM::Provider#with_tracer}
+    # method directly but {LLM::Agent} uses it. An agent can have its
+    # own tracer, and it is scoped via {LLM::Provider#with_tracer}. When
+    # the tracer is done and {LLM::Provider#with_tracer} returns, this
+    # method (on_exit) is called.
     #
-    # It is called once, when the last scope that is open for this tracer
-    # ends, and that scope can have been opened by another thread: a tool
-    # runs on a thread of its own and scopes the turn's tracer while it
-    # does. It is called after the scoped lookup is restored, so a tracer
-    # that reads {LLM::Provider#tracer} inside it sees the tracer that the
-    # next request will see.
+    # A tracer that holds something - a file, a span, a connection pool -
+    # can use this method to release it. The {LLM::Tracer::Telemetry}
+    # tracer uses this method to flush its queue of spans for export,
+    # and after the tracer has exited is a good time to do that.
     #
-    # A tracer can be scoped again afterwards, on a later turn, so it has
-    # to stay usable after this call, and it has to tolerate the call
-    # happening more than once over its life.
     # @see LLM::Tracer::Registry
     # @see LLM::Provider#with_tracer
     # @return [void]
     def on_exit
+      raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
     end
 
     ##
@@ -137,10 +166,12 @@ module LLM
     # @param [LLM::Response] res
     # @param [Object, nil] span
     # @param [String] model
-    # @param [Hash, nil] outputs Optional span attributes (e.g. gen_ai.output.messages) from llm.rb or caller.
-    # @param [Hash, nil] metadata Optional metadata from llm.rb or caller.
+    # @param [Hash, nil] outputs
+    #  Optional span attributes (e.g. gen_ai.output.messages) from llm.rb or caller.
+    # @param [Hash, nil] metadata
+    #  Optional metadata from llm.rb or caller.
     # @param [String] request_id
-    #  The id of the request, as passed to {#on_request_start}
+    #  The id of the request that can be matched back to {#on_request_start}
     # @return [void]
     def on_request_finish(operation:, res:, model: nil, span: nil, outputs: nil, metadata: nil, request_id:)
       raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
@@ -173,59 +204,105 @@ module LLM
     end
 
     ##
-    # Called after a local tool/function succeeds.
-    # @param [LLM::Function::Return] result
-    #  The tool return object.
+    # Called when a tool is interrupted.
+    #
+    # This method is called once per tool - in a batch -
+    # and only after all tools have been spawned in parallel
+    # and then waited on sequentially. The `*_at` parameters
+    # let you know when a tool has started and finished (as a
+    # monotonic clock) since it cannot be inferred from the
+    # time the method is called.
+    #
+    # @param [LLM::Interrupt] ex
+    #  An instance of {LLM::Interrupt LLM::Interrupt}
     # @param [Object, nil] span
-    #  The span/context object returned by {#on_tool_start}.
+    #  The span/context object returned by {#on_tool_start}
+    # @param [Float] started_at
+    #  When the call opened
+    # @param [Float] finished_at
+    #  When the call ended
     # @return [void]
-    def on_tool_finish(result:, span:)
+    def on_tool_interrupt(ex:, span:, started_at:, finished_at:)
+      raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
+    end
+
+    ##
+    # Called after a tool/function succeeds.
+    #
+    # This method is called once per tool - in a batch -
+    # and only after all tools have been spawned in parallel
+    # and then waited on sequentially. The `*_at` parameters
+    # let you know when a tool has started and finished (as a
+    # monotonic clock) since it cannot be inferred from the
+    # time the method is called.
+    #
+    # @param [LLM::Function::Return] result
+    #  An {LLM::Function::Return}
+    # @param [Object] span
+    #  The span/context object returned by {#on_tool_start}
+    # @param [Float] started_at
+    #  When the call opened
+    # @param [Float] finished_at
+    #  When the call ended
+    # @return [void]
+    def on_tool_finish(result:, span:, started_at:, finished_at:)
       raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
     end
 
     ##
     # Called when a local tool/function raises.
-    # @param [Exception] ex
-    #  The raised error.
+    #
+    # This method is called once per tool - in a batch -
+    # and only after all tools have been spawned in parallel
+    # and then waited on sequentially. The `*_at` parameters
+    # let you know when a tool has started and finished (as a
+    # monotonic clock) since it cannot be inferred from the
+    # time the method is called.
+    #
+    # @note
+    #  This method provides the callback with
+    #  an {LLM::Function::Return} object that
+    #  encapsulates the exception a tool failed
+    #  with. It does _not_ provide an Exception
+    #  object.
+    #
+    # @param [LLM::Function::Return] ex
+    #  An {LLM::Function::Return} that holds the error
     # @param [Object, nil] span
     #  The span/context object returned by {#on_tool_start}.
+    # @param [Float] started_at
+    #  When the call opened
+    # @param [Float] finished_at
+    #  When the call ended
     # @return [void]
-    def on_tool_error(ex:, span:)
+    def on_tool_error(ex:, span:, started_at:, finished_at:)
       raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
     end
 
     ##
-    # Called when a request, a tool, or a turn is interrupted.
+    # This method is called when an agent receives
+    # an interrupt. An interrupt can occur in different
+    # scopes: `:request`, `:agent`, or `:tool`.
     #
-    # An interrupt is not a failure, so this is not {#on_request_error} or
-    # {#on_tool_error} under another name: it is the third ending either
-    # scope can have, and it is called before {LLM::Interrupt} reaches the
-    # caller, so a tracer that has to record what happened to a turn does it
-    # while the work is still the work in flight.
+    # The `:request` scope provides a span and request ID,
+    # and it can be used to close a request that was
+    # interrupted. The other scopes (`:tool`, `:agent`)
+    # occur in a context where there is no span or
+    # request ID available.
     #
-    # A request is announced once, by the transport. A tool is announced
-    # once for the phase rather than once per tool: a cancel reaches every
-    # tool that is running and the caller hears one exception, so there is
-    # no one tool the announcement belongs to. A turn is announced as
-    # `:agent` when the interrupt lands between two of its requests, which
-    # is the one point of a turn that has no span of its own.
+    # @note
+    #  This is the last and final callback that is received
+    #  as part of the interrupt process.
     #
-    # The default does nothing, which is the difference from the rest of the
-    # lifecycle. Every other hook raises, because a tracer that means to draw
-    # a request has to answer for it - but an interrupt is delivered to
-    # whatever tracer happens to be bound, and a hook that raised here would
-    # replace the interrupt every caller is written against.
     # @param [Symbol] scope
-    #  :request for a request, :tool for a tool, :agent for a turn that is
-    #  between its requests
+    #  :request, :agent, or :tool
     # @param [Object, nil] span
-    #  The span that {#on_request_start} returned. A tool pass has none:
-    #  a tool's span belongs to the call, and the announcement is not one
-    #  tool's to make.
+    #  The span that {#on_request_start} returned
     # @param [String, nil] request_id
-    #  The id, as passed to {#on_request_start}, when the scope is a request
+    #  The id, as passed to {#on_request_start}
     # @return [void]
     def on_interrupt(scope:, span: nil, request_id: nil)
+      raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
     end
 
     ##

data/lib/llm/utils.rb

@@ -48,16 +48,26 @@ module LLM
       (defined?(::Sequel::Model) and ::Sequel::Model === obj)
     end
 
+    ##
+    # Returns true when a value is a UUIDv7 string: 32 hexadecimal
+    # digits, with or without hyphens, whose version nibble is a 7.
+    # @param [Object] id
+    # @return [Boolean]
+    def uuidv7?(id)
+      hex = id.to_s.delete("-")
+      hex.match?(/\A\h{32}\z/) && hex[12] == "7"
+    end
+
     ##
     # Returns the UTC time encoded in a UUIDv7, or nil when the
     # given value is not a UUIDv7. The first 48 bits of a UUIDv7
     # are a Unix millisecond timestamp.
+    # @see #uuidv7?
     # @param [Object] id
     # @return [Time, nil]
     def timestamp(id)
+      return nil unless uuidv7?(id)
       hex = id.to_s.delete("-")
-      return nil unless hex.match?(/\A\h{32}\z/)
-      return nil unless hex[12] == "7"
       Time.at(hex[0, 12].to_i(16) / 1000.0).utc
     end
 

data/lib/llm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LLM
-  VERSION = "16.0.0"
+  VERSION = "17.0.1"
 end

data/lib/llm.rb

@@ -44,7 +44,7 @@ module LLM
   require_relative "llm/stream"
   require_relative "llm/provider"
   require_relative "llm/context"
-  require_relative "llm/guard"
+  require_relative "llm/intercept"
   require_relative "llm/agent"
   require_relative "llm/buffer"
   require_relative "llm/function"
@@ -362,6 +362,41 @@ module LLM
     LLM::Function.new(key, &b)
   end
 
+  ##
+  # Interrupts the turn running under this identity, in this process.
+  #
+  # Named by the agent or by the id, and not by both: a canceller has one of
+  # the two in hand, never the pair. `false` means nothing was registered
+  # under it - the ordinary race, a turn that finished first, and not a
+  # failure.
+  #
+  # It reaches the agents *this process* is running. A cancel that lands in
+  # another worker finds nothing here and must not be told otherwise; an
+  # application that needs a guarantee keeps one of its own, and what this is
+  # for is the fast path.
+  # @see LLM::Agent::Registry
+  # @param [LLM::Agent, nil] agent
+  # @param [String, Integer, nil] id
+  # @param [Integer] attempts
+  # @param [Numeric] interval
+  # @return [Boolean]
+  #  Whether anything was reached
+  def interrupt(agent: nil, id: nil, attempts: 1, interval: 0.1)
+    result = false
+    attempts.times do |count|
+      record = LLM::Agent.registry.find(agent:, id:)
+      if record
+        record.interrupt!
+        result = true
+        break
+      else
+        break if (count+1) == attempts
+        sleep(interval)
+      end
+    end
+    result
+  end
+
   ##
   # Provides a thread-safe lock
   # @param [Symbol] name The name of the lock

data/llm.gemspec

@@ -5,7 +5,14 @@ require_relative "lib/llm/version"
 Gem::Specification.new do |spec|
   spec.name = "llm.rb"
   spec.version = LLM::VERSION
-  spec.authors = ["Robert Gleeson", "Antar Azri", "Rodrigo Serrano"]
+  spec.authors = ["Robert Gleeson",
+                  "Antar Azri",
+                  "Rodrigo Serrano",
+                  "Azmi Muwahid",
+                  "George Pickett",
+                  "Mika Mikasuki",
+                  "Nikulin Nikita",
+                  "pttydou"]
   spec.email = ["robert@r.uby.dev"]
 
   spec.summary = "An agentic runtime for Ruby"
@@ -40,7 +47,7 @@ DESCRIPTION
   spec.add_development_dependency "yard", "~> 0.9.37"
   spec.add_development_dependency "redcarpet", "~> 3.6"
   spec.add_development_dependency "webrick", "~> 1.8"
-  spec.add_development_dependency "test-cmd.rb", "~> 2.7.1"
+  spec.add_development_dependency "test-cmd.rb", "~> 2.7.3"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "standard", "= 1.54.0"
@@ -56,8 +63,6 @@ DESCRIPTION
   spec.add_development_dependency "xchan.rb", "~> 0.24"
   spec.add_development_dependency "pg", "~> 1.5"
   spec.add_development_dependency "irb", "~> 1.18"
-  spec.add_development_dependency "curb", "~> 1.3"
-  spec.add_development_dependency "curses", "~> 1.6"
   spec.add_development_dependency "kramdown", "~> 2.5"
   spec.add_development_dependency "unicode-display_width", "~> 3.2"
   spec.add_development_dependency "async", "~> 2.45"

metadata

@@ -1,12 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 16.0.0
+  version: 17.0.1
 platform: ruby
 authors:
 - Robert Gleeson
 - Antar Azri
 - Rodrigo Serrano
+- Azmi Muwahid
+- George Pickett
+- Mika Mikasuki
+- Nikulin Nikita
+- pttydou
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
@@ -73,14 +78,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.7.1
+        version: 2.7.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.7.1
+        version: 2.7.3
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -291,34 +296,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.18'
-- !ruby/object:Gem::Dependency
-  name: curb
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.3'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.3'
-- !ruby/object:Gem::Dependency
-  name: curses
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.6'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.6'
 - !ruby/object:Gem::Dependency
   name: kramdown
   requirement: !ruby/object:Gem::Requirement
@@ -394,7 +371,7 @@ files:
 - docs/deepdive/advanced/cancellation.md
 - docs/deepdive/advanced/compaction.md
 - docs/deepdive/advanced/context.md
-- docs/deepdive/advanced/guard.md
+- docs/deepdive/advanced/intercept.md
 - docs/deepdive/advanced/transformer.md
 - docs/deepdive/advanced/transports.md
 - docs/deepdive/features/builtin_tools.md
@@ -438,6 +415,7 @@ files:
 - lib/llm/active_record/message.rb
 - lib/llm/agent.rb
 - lib/llm/agent/interrupt.rb
+- lib/llm/agent/registry.rb
 - lib/llm/buffer.rb
 - lib/llm/compactor.rb
 - lib/llm/compactor/null.rb
@@ -498,10 +476,10 @@ files:
 - lib/llm/function/task.rb
 - lib/llm/function/thread/group.rb
 - lib/llm/function/thread/task.rb
-- lib/llm/function/tracing.rb
 - lib/llm/function/window.rb
-- lib/llm/guard.rb
-- lib/llm/guard/null.rb
+- lib/llm/intercept.rb
+- lib/llm/intercept/multi.rb
+- lib/llm/intercept/null.rb
 - lib/llm/json_adapter.rb
 - lib/llm/mcp.rb
 - lib/llm/mcp/command.rb
@@ -555,6 +533,7 @@ files:
 - lib/llm/providers/deepinfra/images.rb
 - lib/llm/providers/deepinfra/response_adapter.rb
 - lib/llm/providers/deepseek.rb
+- lib/llm/providers/deepseek/files.rb
 - lib/llm/providers/deepseek/images.rb
 - lib/llm/providers/deepseek/request_adapter.rb
 - lib/llm/providers/deepseek/request_adapter/completion.rb
@@ -673,9 +652,11 @@ files:
 - lib/llm/tools/write_file.rb
 - lib/llm/tracer.rb
 - lib/llm/tracer/logger.rb
+- lib/llm/tracer/multi.rb
 - lib/llm/tracer/null.rb
 - lib/llm/tracer/pretty_logger.rb
 - lib/llm/tracer/registry.rb
+- lib/llm/tracer/rescue.rb
 - lib/llm/tracer/telemetry.rb
 - lib/llm/transformer.rb
 - lib/llm/transformer/null.rb

data/lib/llm/function/tracing.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-class LLM::Function
-  ##
-  # The {LLM::Function::Tracing LLM::Function::Tracing} module patches
-  # an LLM function (or tool) in order to add tracing support.
-  module Tracing
-    def call(...)
-      return super unless @tracer
-      span = @tracer.on_tool_start(id:, name:, arguments:, model:)
-      result = super
-      @tracer.on_tool_finish(result:, span:)
-      result
-    rescue LLM::Interrupt
-      raise
-    rescue => ex
-      @tracer.on_tool_error(ex:, span:)
-      raise(ex)
-    end
-  end
-end

data/lib/llm/guard/null.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-class LLM::Guard
-  ##
-  # {LLM::Guard::Null LLM::Guard::Null} is a no-op guard. It never blocks
-  # pending tool work and is the default guard used by
-  # {LLM::Context LLM::Context}.
-  class Null < self
-    ##
-    # @param [LLM::Function] function
-    #  The pending function (ignored)
-    # @param [Hash] opts
-    #  Per-call options (ignored)
-    # @return [nil]
-    def call(function:, **opts)
-      nil
-    end
-  end
-end