llm.rb 15.4.0 → 15.5.0

data/lib/llm/schema/deferred.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+class LLM::Schema
+  ##
+  # {LLM::Schema::Deferred LLM::Schema::Deferred} is a placeholder for a
+  # leaf that is resolved when the schema is rendered.
+  #
+  # A parameter type that can only be known at runtime - an enum of the
+  # keys a store holds right now, for example - is given as a proc. The
+  # proc is called when the schema is rendered rather than when the class
+  # that declares the parameter is defined, so declaring a tool does not
+  # touch whatever the type depends on:
+  #
+  #   parameter :fruit, proc { Enum[*Fruit.kinds]}, "A fruit", required: true
+  #
+  # Whatever the proc returns is resolved in turn, so it can return a
+  # leaf, a class, or an array of either.
+  #
+  # @api private
+  class Deferred < Leaf
+    ##
+    # @param [Proc] block
+    #  A block that returns the leaf to resolve to
+    # @return [LLM::Schema::Deferred]
+    def initialize(&block)
+      super()
+      @block = block
+    end
+
+    ##
+    # @return [Hash]
+    def to_h
+      resolved_leaf.to_h
+    end
+
+    ##
+    # @param [Hash] options
+    # @return [String]
+    def to_json(options = {})
+      resolved_leaf.to_h.to_json(options)
+    end
+
+    ##
+    # @return [String]
+    def to_s
+      resolved_leaf.to_s
+    end
+
+    private
+
+    ##
+    # Returns the leaf the block resolves to, with the settings that
+    # were given to the placeholder applied to it.
+    #
+    # The settings live on the placeholder, because they are given
+    # before the leaf it stands for exists.
+    # @return [LLM::Schema::Leaf]
+    def resolved_leaf
+      leaf = @block.call
+      leaf.description(@description) if @description
+      leaf.default(@default) unless @default.nil?
+      leaf.enum(*@enum) if @enum
+      leaf.const(@const) unless @const.nil?
+      leaf.required if required?
+      leaf
+    end
+  end
+end

data/lib/llm/schema/leaf.rb

@@ -12,6 +12,9 @@ class LLM::Schema
     # @return [Integer, nil]
     attr_accessor :index
 
+    ##
+    # Returns a leaf.
+    # @return [LLM::Schema::Leaf]
     def initialize
       @description = nil
       @default = nil

data/lib/llm/schema.rb

@@ -36,6 +36,7 @@ class LLM::Schema
   require_relative "schema/parser"
   require_relative "schema/renderer"
   require_relative "schema/leaf"
+  require_relative "schema/deferred"
   require_relative "schema/object"
   require_relative "schema/array"
   require_relative "schema/all_of"
@@ -56,9 +57,21 @@ class LLM::Schema
   module Utils
     extend self
 
+    ##
+    # Resolves a parameter type into a leaf of the schema.
+    #
+    # A proc is called for its type, and whatever it returns is resolved
+    # in turn, so a type that can only be known at runtime - an enum of
+    # the keys a store holds right now - can be declared without being
+    # evaluated when the class that declares it is defined.
+    # @param [LLM::Schema] schema
+    # @param [Object] type
+    # @return [LLM::Schema::Leaf]
     def resolve(schema, type)
       if LLM::Schema::Leaf === type
         type
+      elsif ::Proc === type
+        Deferred.new { resolve(schema, type.call) }
       elsif ::Array === type
         resolve_array(schema, type)
       elsif Class === type && type.respond_to?(:object)

data/lib/llm/tool/param.rb

@@ -22,8 +22,10 @@ class LLM::Tool
     ##
     # @param name [Symbol]
     #   The name of a parameter
-    # @param type [LLM::Schema::Leaf, Class]
-    #   The parameter type (eg String)
+    # @param type [LLM::Schema::Leaf, Class, Proc]
+    #   The parameter type (eg String). A proc is called for the type
+    #   when the parameters are read, so a type that can only be known
+    #   at runtime does not have to be known when the class is defined.
     # @param description [String]
     #   The description of a property
     # @param options [Hash]

data/lib/llm/tools/exec.rb

@@ -54,7 +54,8 @@ class LLM::Tool
     #  the max number of bytes to emit
     # @return [Hash]
     def call(arguments: [], timeout: 60, max_bytes: self.class.max_bytes)
-      name = arguments[0]
+      startat = now
+      name    = arguments[0]
       command = spawn(name:, arguments: arguments[1..], env:, max_bytes:)
       wait(command:, timeout:)
       if command.not_found?
@@ -62,7 +63,8 @@ class LLM::Tool
       else
         {ok: command.success?,
         stdout: truncate(command.stdout, max_bytes:),
-        stderr: truncate(command.stderr, max_bytes:)}
+        stderr: truncate(command.stderr, max_bytes:),
+        duration: "#{(now - startat).round(1)} seconds"}
       end
     rescue LLM::Interrupt
       command.kill! if command&.running?
@@ -72,5 +74,11 @@ class LLM::Tool
     private
 
     attr_reader :env
+
+    ##
+    # @return [Float]
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
   end
 end

data/lib/llm/tracer/registry.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+class LLM::Tracer
+  ##
+  # {LLM::Tracer::Registry LLM::Tracer::Registry} counts the scopes that
+  # are open for each tracer.
+  #
+  # The count belongs to the tracer, not to the thread that opened a
+  # scope. A tool runs on a thread of its own and opens a scope there for
+  # the turn's tracer, and a count kept per thread would let that scope
+  # look like the outermost one: it would end the tracer while the turn
+  # is still running, and every write after it would fail.
+  #
+  # @api private
+  class Registry
+    ##
+    # @return [LLM::Tracer::Registry]
+    def initialize
+      @counts = ObjectSpace::WeakMap.new
+      @mutex  = Mutex.new
+    end
+
+    ##
+    # Records that a scope was opened for a tracer.
+    # @param [LLM::Tracer] tracer
+    # @return [LLM::Tracer::Registry]
+    #  Returns self, so a caller can tell the scope was recorded
+    def enter(tracer)
+      @mutex.synchronize do
+        @counts[tracer] = count(tracer) + 1
+      end
+      self
+    end
+
+    ##
+    # Records that a scope was closed, and tells the tracer it is
+    # finished when it was the last one that was open.
+    #
+    # The count is brought up to date under the lock, and the tracer is
+    # told after the lock is released: a tracer that calls back into the
+    # provider from `on_exit` would otherwise deadlock against itself.
+    #
+    # An `exit` without a matching `enter` is ignored: no scope is open,
+    # so there is nothing to end, and the tracer is not told it is
+    # finished when no scope was holding it.
+    # @param [LLM::Tracer] tracer
+    # @return [void]
+    def exit(tracer)
+      last = @mutex.synchronize do
+        open = count(tracer)
+        if open.zero?
+          false
+        elsif open == 1
+          forget(tracer)
+          true
+        else
+          @counts[tracer] = open - 1
+          false
+        end
+      end
+      tracer.on_exit if last
+    end
+
+    private
+
+    ##
+    # Drops a tracer that has no open scopes left.
+    # @param [LLM::Tracer] tracer
+    # @return [Boolean]
+    def forget(tracer)
+      if @counts.respond_to?(:delete)
+        @counts.delete(tracer)
+      else
+        @counts[tracer] = 0
+      end
+      true
+    end
+
+    ##
+    # @param [LLM::Tracer] tracer
+    # @return [Integer]
+    def count(tracer)
+      @counts[tracer] || 0
+    end
+  end
+end

data/lib/llm/tracer.rb

@@ -13,6 +13,39 @@ module LLM
     require_relative "tracer/telemetry"
     require_relative "tracer/null"
     require_relative "tracer/pretty_logger"
+    require_relative "tracer/registry"
+
+    ##
+    # Returns the registry that counts the open scopes for each tracer.
+    # @api private
+    # @return [LLM::Tracer::Registry]
+    def self.registry
+      LLM.lock(:registry) do
+        @registry ||= Registry.new
+      end
+    end
+
+    ##
+    # Records that a scope was opened for a tracer.
+    # @api private
+    # @see LLM::Tracer::Registry#enter
+    # @param [LLM::Tracer] tracer
+    # @return [LLM::Tracer::Registry]
+    #  Returns the registry, so a caller can tell the scope was recorded
+    def self.enter(tracer)
+      registry.enter(tracer)
+    end
+
+    ##
+    # Records that a scope was closed for a tracer, and tells the tracer
+    # it is finished when it was the last one that was open.
+    # @api private
+    # @see LLM::Tracer::Registry#exit
+    # @param [LLM::Tracer] tracer
+    # @return [void]
+    def self.exit(tracer)
+      registry.exit(tracer)
+    end
 
     ##
     # Builds a {LLM::Tracer::PrettyLogger} for a provider.
@@ -61,6 +94,29 @@ module LLM
       @options = {}
     end
 
+    ##
+    # Called when the tracer is no longer in use.
+    #
+    # 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 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 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
+    end
+
     ##
     # Called before an LLM provider request is executed.
     # @param [String] operation

data/lib/llm/version.rb

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

data/llm.gemspec

@@ -34,12 +34,6 @@ DESCRIPTION
   ]
   spec.executables = ["llm.rb"]
   spec.require_paths = ["lib"]
-  spec.post_install_message = "\n" \
-                              "Want to see what I'm building with llm.rb? " \
-                              "\n" \
-                              "Checkout the https://r.uby.dev website." \
-                              "\n\n"
-
   spec.add_development_dependency "webmock", "~> 3.24.0"
   spec.add_development_dependency "yard", "~> 0.9.37"
   spec.add_development_dependency "redcarpet", "~> 3.6"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 15.4.0
+  version: 15.5.0
 platform: ruby
 authors:
 - Robert Gleeson
@@ -624,6 +624,7 @@ files:
 - lib/llm/schema/any_of.rb
 - lib/llm/schema/array.rb
 - lib/llm/schema/boolean.rb
+- lib/llm/schema/deferred.rb
 - lib/llm/schema/enum.rb
 - lib/llm/schema/integer.rb
 - lib/llm/schema/leaf.rb
@@ -665,6 +666,7 @@ files:
 - lib/llm/tracer/logger.rb
 - lib/llm/tracer/null.rb
 - lib/llm/tracer/pretty_logger.rb
+- lib/llm/tracer/registry.rb
 - lib/llm/tracer/telemetry.rb
 - lib/llm/transformer.rb
 - lib/llm/transformer/null.rb
@@ -695,8 +697,6 @@ metadata:
   source_code_uri: https://github.com/r-uby-dev/llm
   documentation_uri: https://r.uby.dev
   changelog_uri: https://github.com/r-uby-dev/llm/blob/main/CHANGELOG.md
-post_install_message: "\nWant to see what I'm building with llm.rb? \nCheckout the
-  https://r.uby.dev website.\n\n"
 rdoc_options: []
 require_paths:
 - lib