llm.rb 12.5.1 → 13.0.0

data/lib/llm/stream.rb

@@ -11,6 +11,21 @@ module LLM
   # a small helper for collecting asynchronous tool work started from a
   # callback.
   #
+  # @example Subclass with callbacks
+  #   class MyStream < LLM::Stream
+  #     def on_content(content)
+  #       print content
+  #     end
+  #
+  #     def on_reasoning_content(content)
+  #       warn content
+  #     end
+  #   end
+  #
+  #   llm = LLM.deepseek(key: ENV["KEY"])
+  #   agent = LLM::Agent.new(llm, stream: MyStream.new)
+  #   agent.talk "Explain Ruby fibers."
+  #
   # @note The `on_*` callbacks run inline with the streaming parser. They
   #   therefore block streaming progress and should generally return as
   #   quickly as possible.
@@ -19,6 +34,9 @@ module LLM
   # Providers may also call {#on_reasoning_content} and {#on_tool_call} when
   # that data is available. Runtime features such as context compaction may
   # also emit lifecycle callbacks like {#on_transform} or {#on_compaction}.
+  #
+  # @see LLM::Agent Where streams are typically attached
+  # @see LLM::Context Where streams are bound per-turn
   class Stream
     require_relative "stream/queue"
     require_relative "stream/io"
@@ -109,16 +127,8 @@ module LLM
 
     ##
     # Called when a streamed tool call has been fully constructed.
-    # @note A stream implementation may start tool execution here, for
-    #   example by pushing `ctx.spawn(tool, :thread)`,
-    #   `ctx.spawn(tool, :fiber)`, or `ctx.spawn(tool, :task)` onto {#queue}.
-    #   Mixed strategies can also be selected per tool, such as
-    #   `tool.mcp? ? ctx.spawn(tool, :task) : ctx.spawn(tool, :ractor)`.
-    #   Streamed tool resolution now prefers the current request tools, so
-    #   {LLM.function}, MCP tools, bound tool instances, and normal
-    #   {LLM::Tool LLM::Tool} classes can all resolve through the same
-    #   request-local path. The current `:ractor` mode is for class-based
-    #   tools and does not support MCP tools.
+    # A stream implementation may start tool execution here by pushing
+    # `@queue << tool.task(:thread)` onto {#queue}.
     # @param [LLM::Function] tool
     #  The parsed tool call.
     # @return [nil]
@@ -128,9 +138,8 @@ module LLM
 
     ##
     # Called when queued streamed tool work returns.
-    # @note This callback runs when {#wait} resolves work that was queued from
-    #   {#on_tool_call}, such as values returned by `ctx.spawn(tool, :thread)`,
-    #   `ctx.spawn(tool, :fiber)`, or `ctx.spawn(tool, :task)`.
+    # This callback runs when {#wait} resolves work queued from
+    # {#on_tool_call}.
     # @param [LLM::Function] tool
     #  The tool that returned.
     # @param [LLM::Function::Return] result
@@ -160,19 +169,17 @@ module LLM
 
     ##
     # Called before a context compaction starts.
-    # @param [LLM::Context] ctx
     # @param [LLM::Compactor] compactor
     # @return [nil]
-    def on_compaction(ctx, compactor)
+    def on_compaction(compactor)
       nil
     end
 
     ##
     # Called after a context compaction finishes.
-    # @param [LLM::Context] ctx
     # @param [LLM::Compactor] compactor
     # @return [nil]
-    def on_compaction_finish(ctx, compactor)
+    def on_compaction_finish(compactor)
       nil
     end
 

data/lib/llm/tool/param.rb

@@ -56,6 +56,18 @@ class LLM::Tool
       end
     end
 
+    ##
+    # Set default values for parameters.
+    # @param [Hash] defaults
+    # @return [LLM::Schema::Object]
+    def defaults(defaults)
+      lock do
+        function.params.tap do |schema|
+          defaults.each { Utils.fetch(schema.properties, _1).default(_2) }
+        end
+      end
+    end
+
     ##
     # @api private
     module Utils

data/lib/llm/tool.rb

@@ -5,10 +5,23 @@
 # that can be called by an LLM. Under the hood, it is a wrapper
 # around {LLM::Function LLM::Function} but allows the definition
 # of a function (also known as a tool) as a class.
-# @example
-#   class System < LLM::Tool
-#     name "system"
-#     description "Runs system commands"
+#
+# @example Declarative form (preferred)
+#   class ReadFile < LLM::Tool
+#     name "read-file"
+#     description "Read a file from disk"
+#     parameter :path, String, "The filename or path"
+#     required %i[path]
+#
+#     def call(path:)
+#       {contents: File.read(path)}
+#     end
+#   end
+#
+# @example Block-form DSL (also supported)
+#   class RunCommand < LLM::Tool
+#     name "run-command"
+#     description "Runs a shell command"
 #     params do |schema|
 #       schema.object(command: schema.string.required)
 #     end
@@ -17,6 +30,9 @@
 #       {success: Kernel.system(command)}
 #     end
 #   end
+#
+# @see LLM::Agent Tools are attached to agents
+# @see LLM::Function The function object that Tool wraps
 class LLM::Tool
   require_relative "tool/param"
   extend LLM::Tool::Param

data/lib/llm/tools/chdir.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# frozen_string_literal
-
 class LLM::Tool
   ##
   # The {LLM::Tool::Chdir LLM::Tool::Chdir} class implements

data/lib/llm/tools/git.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# frozen_string_literal
-
 class LLM::Tool
   ##
   # The {LLM::Tool::Git LLM::Tool::Git} class implements
@@ -9,18 +7,24 @@ class LLM::Tool
   # The actions it can perform are read-only - at least for
   # the time being.
   class Git < self
+    require_relative "utils"
+    include Utils
+
     name "git"
     description "perform an action with git"
     parameter :action, Enum["log", "diff", "commit", "checkout", "branch", "show"], "the git operation to perform"
     parameter :arguments, Array[String], "one or more arguments for the git action"
+    parameter :timeout, Integer, "the maximum time to allow the command to run"
     required %i[action]
+    defaults arguments: [], timeout: 5
 
     ##
     # @param [String] action
     # @param [Array<String>, nil] arguments
     # @return [Hash]
-    def call(action:, arguments: nil)
+    def call(action:, arguments: [], timeout: 5)
       command = spawn(action:, arguments:)
+      wait(command:, timeout:)
       {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
     end
 
@@ -34,7 +38,7 @@ class LLM::Tool
         .spawn
     end
 
-    LLM.require "test-cmd.rb"
+    LLM.require "test-cmd.rb",  "~> 1.1"
     Command = Test::Cmd
   end
 end

data/lib/llm/tools/mkdir.rb

@@ -26,7 +26,7 @@ class LLM::Tool
         .spawn
     end
 
-    LLM.require "test-cmd.rb"
+    LLM.require "test-cmd.rb", "~> 1.1"
     Command = Test::Cmd
   end
 end

data/lib/llm/tools/pwd.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# frozen_string_literal
-
 class LLM::Tool
   ##
   # The {LLM::Tool::Pwd LLM::Tool::Pwd} class implements

data/lib/llm/tools/read_file.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# frozen_string_literal
-
 class LLM::Tool
   ##
   # The {LLM::Tool::ReadFile LLM::Tool::ReadFile} class implements

data/lib/llm/tools/rg.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# frozen_string_literal
-
 class LLM::Tool
   ##
   # The {LLM::Tool::Rg LLM::Tool::Rg} class implements
@@ -9,19 +7,25 @@ class LLM::Tool
   # recursively search the current working directory
   # for one or more patterns.
   class Rg < self
+    require_relative "utils"
+    include Utils
+
     name "rg"
     description "recursively search the current directory for lines matching a pattern"
     parameter :patterns, Array[String], "one or more search patterns"
     parameter :path, String, "the path where the search is performed (default is cwd)"
+    parameter :timeout, Integer, "the number of seconds to wait before cancelling the action"
     required %i[patterns]
+    defaults path: Dir.getwd, timeout: 5
 
     ##
     # @param [Array<String>] patterns
     # @param [String] path
     # @return [Hash]
-    def call(patterns:, path: Dir.getwd)
+    def call(patterns:, path: Dir.getwd, timeout: 5)
       validate!(patterns:, path:)
       command = spawn(patterns:, path:)
+      wait(command:, timeout:)
       {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
     end
 
@@ -41,7 +45,7 @@ class LLM::Tool
         .spawn
     end
 
-    LLM.require "test-cmd.rb"
+    LLM.require "test-cmd.rb", "~> 1.1"
     Command = Test::Cmd
   end
 end

data/lib/llm/tools/shell.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# frozen_string_literal
-
 class LLM::Tool
   ##
   # The {LLM::Tool::Shell} class implements a tool that can
@@ -12,11 +10,16 @@ class LLM::Tool
   # by managing the tool loop manually through
   # {LLM::Context LLM::Context}.
   class Shell < self
+    require_relative "utils"
+    include Utils
+
     name "shell"
     description "run a shell command"
     parameter :name, String, "the command name"
     parameter :arguments, Array[String], "one or more command arguments"
+    parameter :timeout, Integer, "the maximum allowed time for the command to run (in seconds)"
     required %i[name]
+    defaults arguments: [], timeout: 60
 
     ##
     # @param [String] name
@@ -24,8 +27,9 @@ class LLM::Tool
     # @param [Array<String>] arguments
     #  One or more command-line arguments
     # @return [Hash]
-    def call(name:, arguments: nil)
+    def call(name:, arguments: [], timeout: 60)
       command = spawn(name:, arguments:)
+      wait(command:, timeout:)
       {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
     end
 
@@ -42,7 +46,7 @@ class LLM::Tool
         .spawn
     end
 
-    LLM.require "test-cmd.rb"
+    LLM.require "test-cmd.rb", "~> 1.1"
     Command = Test::Cmd
   end
 end

data/lib/llm/tools/utils.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class LLM::Tool
+  ##
+  # Shared utilities for tool implementations.
+  module Utils
+    ##
+    # Wait for a command to finish, or abort
+    # with an error when it exceeds the
+    # specified timeout.
+    # @param [Test::Cmd] command
+    # @param [Integer] timeout
+    # @return [void]
+    def wait(command:, timeout:)
+      start = now
+      while command.running?
+        if now - start > timeout
+          command.kill!
+          raise "command timed out after #{timeout}s"
+        end
+        sleep 0.01
+      end
+    end
+
+    ##
+    # @return [Numeric]
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/llm/version.rb

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

data/lib/llm.rb

@@ -1,8 +1,22 @@
 # frozen_string_literal: true
 
+##
+# llm.rb is a zero-dependency AI runtime for Ruby. Twelve providers, six
+# concurrency strategies, MCP and A2A, streaming tool calls with
+# cancellation, context compaction, and ORM persistence.
+#
+# @example The three-step workflow
+#   require "llm"
+#   llm = LLM.deepseek(key: ENV["KEY"])           # 1. pick a provider
+#   agent = LLM::Agent.new(llm, stream: $stdout)   # 2. create an agent
+#   agent.talk "Hello world"                       # 3. talk to it
+#
+# @see LLM::Agent The recommended high-level interface
+# @see LLM::Context The low-level stateful runtime (advanced)
 module LLM
   require "stringio"
   require "securerandom"
+  require_relative "llm/compactor"
   require_relative "llm/json_adapter"
   require_relative "llm/tracer"
   require_relative "llm/error"
@@ -49,15 +63,21 @@ module LLM
 
   ##
   # Requires an optional runtime dependency
-  # @raise [LLM::DependencyError]
+  # @param [String] name
+  #  The name of a gem
+  # @param [String, nil] version
+  #  Optional gem version
+  # @raise [LLM::LoadError]
   #  When the dependency cannot be loaded
-  def self.require(name)
-    super
-  rescue ::LoadError
+  def self.require(name, version = nil)
     names = {"xchan" => "xchan.rb", "net/http/persistent" => "net-http-persistent"}
+    gem(names[name] || name, version) if version
+    super(name)
+  rescue ::LoadError
     name = names[name] || name
     raise LLM::LoadError,
-      "#{name} is an optional runtime dependency but it does not appear to be installed. " \
+      "#{name}#{version ? " #{version}" : ""} is an optional " \
+      "runtime dependency but it does not appear to be installed. " \
       "Consider 'gem install #{name}', adding '#{name}' to your Gemfile or " \
       "opting out of the functionality provided by '#{name}'"
   end

data/llm.gemspec

@@ -16,7 +16,7 @@ functionality – such as ActiveRecord support – require
 optional dependencies that are opt-in.
 DESCRIPTION
 
-  spec.license = "BUSL-1.1"
+  spec.license = "MIT"
   spec.required_ruby_version = ">= 3.3.0"
 
   spec.homepage = "https://r.uby.dev/llm/"
@@ -38,7 +38,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", "~> 0.12.0"
+  spec.add_development_dependency "test-cmd.rb", "~> 1.1.0"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "standard", "~> 1.50"
@@ -50,7 +50,7 @@ DESCRIPTION
   spec.add_development_dependency "activerecord", "~> 8.0"
   spec.add_development_dependency "sequel", "~> 5.0"
   spec.add_development_dependency "sqlite3", "~> 2.0"
-  spec.add_development_dependency "xchan.rb", "~> 0.20"
+  spec.add_development_dependency "xchan.rb", "~> 0.22"
   spec.add_development_dependency "pg", "~> 1.5"
   spec.add_development_dependency "irb", "~> 1.18"
 end