llm.rb 12.6.0 → 13.1.0

data/lib/llm/tools/ruby.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::Ruby LLM::Tool::Ruby} class implements
+  # a tool that can execute an arbitrary string of Ruby code
+  # and return the result. It uses `test-cmd.rb` under the
+  # hood for process management.
+  class Ruby < self
+    require_relative "utils"
+    include Utils
+
+    name "ruby"
+    description "runs a string of ruby code"
+    parameter :code, String, "a string of ruby code"
+    parameter :timeout, Integer, "maximum runtime before timeout"
+    required %i[code]
+    defaults timeout: 15
+
+    ##
+    # @param [String] code
+    #  Ruby code
+    # @param [Integer] timeout
+    #  Runtime timeout
+    def call(code:, timeout: 15)
+      command = spawn(code:)
+      wait(command:, timeout:)
+      {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
+    rescue LLM::Interrupt
+      command.kill! if command&.running?
+      raise
+    end
+
+    private
+
+    def spawn(code:)
+      Command
+        .new(RbConfig.ruby)
+        .argv("-e", code)
+    end
+
+    require "rbconfig"
+    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,9 +27,13 @@ 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}
+    rescue LLM::Interrupt
+      command.kill! if command&.running?
+      raise
     end
 
     private
@@ -42,7 +49,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/tracer/pretty_logger.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # The {LLM::Tracer::PrettyLogger LLM::Tracer::PrettyLogger} class
+  # writes human-readable request and tool call logs to a console
+  # or file. Each event is a single line with the relevant context
+  # inline, no structured JSON.
+  #
+  # @example
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   llm.tracer = LLM::Tracer::PrettyLogger.new(llm)
+  #
+  # @example Writing to a file
+  #   llm.tracer = LLM::Tracer::PrettyLogger.new(llm, io: File.open("log.txt", "a"))
+  class Tracer::PrettyLogger < Tracer
+    ##
+    # @param (see LLM::Tracer#initialize)
+    def initialize(provider, options = {})
+      super
+      setup!(**options)
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_request_start)
+    # @return [void]
+    def on_request_start(operation:, model: nil, **)
+      @start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      name = operation == "chat" ? "chat" : operation
+      @io.puts "#{timestamp} #{provider_name} #{name} (#{model || "default"})"
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_request_finish)
+    # @return [void]
+    def on_request_finish(operation:, res:, model: nil, **)
+      elapsed = @start ? (Process.clock_gettime(Process::CLOCK_MONOTONIC) - @start).round(2) : nil
+      tokens = format_tokens(res)
+      name = operation == "chat" ? "chat" : operation
+      parts = ["#{timestamp} #{provider_name} #{name} done"]
+      parts << tokens if tokens
+      parts << "#{elapsed}s" if elapsed
+      @io.puts parts.join(", ")
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_request_error)
+    # @return [void]
+    def on_request_error(ex:, **)
+      @io.puts "#{timestamp} #{provider_name} error #{ex.class}: #{ex.message}"
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_start)
+    # @return [void]
+    def on_tool_start(id:, name:, arguments:, **)
+      @io.puts "#{timestamp} #{name}(#{format_arguments(arguments)})"
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_finish)
+    # @return [void]
+    def on_tool_finish(result:, **)
+      @io.puts "#{timestamp} #{result.name} -> #{format_value(result.value)}"
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_error)
+    # @return [void]
+    def on_tool_error(ex:, **)
+      @io.puts "#{timestamp} tool error #{ex.class}: #{ex.message}"
+    end
+
+    private
+
+    def setup!(io: $stderr)
+      @io = io
+      @start = nil
+    end
+
+    def timestamp
+      Time.now.strftime("%H:%M:%S")
+    end
+
+    def format_tokens(res)
+      usage = res.usage
+      if usage.input_tokens and usage.output_tokens
+        "in=#{usage.input_tokens} out=#{usage.output_tokens}"
+      elsif usage.input_tokens
+        "in=#{usage.input_tokens}"
+      elsif usage.output_tokens
+        "out=#{usage.output_tokens}"
+      end
+    end
+
+    def format_arguments(args, max: 50)
+      return "" unless args
+      case args
+      when Hash, LLM::Object
+        result = args.map { |k, v| "#{k}: #{format_value(v)}" }.join(", ")
+      when Array
+        result = args.map { |v| format_value(v) }.join(", ")
+      else
+        result = args.inspect
+      end
+      result.size > max ? "#{result[0...max - 1]}..." : result
+    end
+
+    def format_value(value, max: 18)
+      case value
+      when String
+        value.size > max ? "#{value[0...max]}...".inspect : value.inspect
+      when Array
+        items = value.take(2).map { format_value(_1, max: 10) }
+        items << "..." if value.size > 2
+        "[#{items.join(", ")}]"
+      when Hash
+        "{...}"
+      when nil
+        "nil"
+      else
+        str = value.inspect
+        str.size > max ? "#{str[0...max]}..." : str
+      end
+    end
+  end
+end

data/lib/llm/tracer.rb

@@ -12,6 +12,7 @@ module LLM
     require_relative "tracer/logger"
     require_relative "tracer/telemetry"
     require_relative "tracer/null"
+    require_relative "tracer/pretty_logger"
 
     ##
     # @return [LLM::Provider]

data/lib/llm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LLM
-  VERSION = "12.6.0"
+  VERSION = "13.1.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

@@ -12,11 +12,11 @@ Gem::Specification.new do |spec|
   spec.description = <<~DESCRIPTION
 llm.rb is an advanced runtime for building capable AI applications
 on CRuby. By default it has zero runtime dependencies although certain
-functionality &ndash; such as ActiveRecord support &ndash; require
+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/"
@@ -30,15 +30,21 @@ DESCRIPTION
     "lib/*.rb", "lib/**/*.rb",
     "data/*.json", "CHANGELOG.md",
     "resources/deepdive.md",
-    "llm.gemspec"
+    "llm.gemspec", "bin/llm.rb"
   ]
+  spec.executables = ["llm.rb"]
   spec.require_paths = ["lib"]
+  spec.post_install_message = "\n" \
+                              "Learn more about llm.rb by reading the deepdive:" \
+                              "\n" \
+                              "https://r.uby.dev/llm/deepdive" \
+                              "\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"
   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 +56,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