llm.rb 15.0.3 → 15.2.0

data/lib/llm/tools/read_file.rb

@@ -2,37 +2,97 @@
 
 class LLM::Tool
   ##
-  # The {LLM::Tool::ReadFile LLM::Tool::ReadFile} class implements
-  # a tool that can read the contents of a file. The tool accepts
-  # two optional offsets: a start line, and a stop line. Without
-  # either the entire file contents are read into memory.
+  # The {LLM::Tool::ReadFile} class implements a tool that
+  # can read the contents of a file. It returns the content
+  # as structured lines ({lineno:, content:}), so the model can
+  # reference line numbers when requesting a narrower range.
   class ReadFile < self
+    require_relative "utils"
+    include Utils
+
     name "read-file"
     description "read the contents of a file"
     parameter :path, String, "the path to the file"
     parameter :start, Integer, "start line number"
     parameter :stop, Integer, "stop line number"
+    parameter :max_bytes, Integer, "the max number of bytes to return"
     required %i[path]
 
+    ##
+    # Returns (or sets) the advisory maximum number of bytes
+    # this tool returns to the model.
+    # @param [Integer, nil] bytes
+    #  When given, sets the maximum
+    # @return [Integer]
+    def self.max_bytes(bytes = UNDEFINED)
+      if bytes.equal?(UNDEFINED)
+        @max_bytes || 75_000
+      else
+        @max_bytes = bytes
+      end
+    end
+
     ##
     # @param [String] path
     # @param [Integer] start
     # @param [Integer] stop
+    # @param [Integer] max_bytes
     # @return [Hash]
-    def call(path:, start: 1, stop: -1)
-      content, cursor = nil, 1
+    def call(path:, start: 1, stop: -1, max_bytes: self.class.max_bytes)
+      start, stop = swap_if_reversed(start, stop)
+      content = read(path, start, stop)
+      to_lines(content, start:, max_bytes:)
+    end
+
+    private
+
+    ##
+    # When start is greater than stop, swap them so the
+    # range reads in the right direction (e.g. start: 10,
+    # stop: 5 => reads lines 5-10).
+    # @param [Integer] start
+    # @param [Integer] stop
+    # @return [[Integer, Integer]]
+    def swap_if_reversed(start, stop)
+      stop != -1 && start > stop ? [stop, start] : [start, stop]
+    end
+
+    ##
+    # Returns the file content within the start..stop range.
+    # @param [String] path
+    # @param [Integer] start
+    # @param [Integer] stop
+    # @return [String]
+    def read(path, start, stop)
       File.open(path, "r") do |f|
+        cursor = 1
         while cursor < start
           f.gets
           cursor += 1
         end
         if stop == -1
-          content = f.read
+          f.read
         else
-          content = start.upto(stop).map { f.gets }.join
+          start.upto(stop).map { f.gets }.join
         end
       end
-      {ok: true, content:}
+    end
+
+    ##
+    # Builds {lineno:, content:} lines from the content, capped at
+    # max_bytes via the shared truncate!. The truncation marker
+    # is kept out of the lines (it is not a real file line); the
+    # truncated flag communicates that content was cut.
+    # @param [String] content
+    # @param [Integer] start
+    # @param [Integer] max_bytes
+    # @return [Hash]
+    def to_lines(content, start:, max_bytes:)
+      body, truncated = truncate!(content, max_bytes:)
+      lines = body.lines.each_with_index.map do |line, index|
+        {lineno: start + index, content: line}
+      end
+      {ok: true, lines:, truncated:}
     end
   end
 end

data/lib/llm/tools/rg.rb

@@ -7,49 +7,45 @@ class LLM::Tool
   # recursively search the current working directory
   # for one or more patterns.
   class Rg < self
-    require_relative "utils"
-    include Utils
+    require_relative "exec"
 
     name "rg"
-    description "recursively search the current directory for lines matching a pattern"
+    description "Search the current directory for lines matching a pattern\n" \
+                "This command (rg) is spawned without a shell"
     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"
+    parameter :max_count, Integer, "the max number of results per file"
+    parameter :max_bytes, Integer, "the max number of bytes to return"
     required %i[patterns]
-    defaults path: Dir.getwd, timeout: 5
+    defaults path: Dir.getwd, timeout: 5, max_count: 10, max_bytes: -> { Exec.max_bytes }
 
     ##
     # @param [Array<String>] patterns
     # @param [String] path
+    # @param [Integer] timeout
+    # @param [Integer] max_count
+    # @param [Integer] max_bytes
     # @return [Hash]
-    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}
-    rescue LLM::Interrupt
-      command.kill! if command&.running?
-      raise
+    def call(patterns:, path: Dir.getwd, timeout: 5, max_count: 10, max_bytes: Exec.max_bytes)
+      validate!(patterns:, path:, max_count:)
+      Exec.new.call(
+        arguments: ["rg", "-m", max_count, *[*patterns].flat_map { ["-e", _1] }, path],
+        timeout:,
+        max_bytes:
+      )
     end
 
     private
 
-    def validate!(patterns:, path:)
-      if path == "/"
+    def validate!(patterns:, path:, max_count:)
+      if !(::Integer === max_count) || max_count.zero? || max_count.negative?
+        raise RuntimeError, "max_count must be a positive integer"
+      elsif path == "/"
         raise RuntimeError, "you can't search from the root of the filesystem"
       elsif patterns == ["."]
         raise RuntimeError, "narrow your search"
       end
     end
-
-    def spawn(patterns:, path:)
-      Command
-        .new("rg")
-        .argv(*[*patterns].flat_map { ["-e", _1] }, path)
-        .spawn
-    end
-
-    LLM.require "test-cmd.rb", "~> 1.1"
-    Command = Test::Cmd
   end
 end

data/lib/llm/tools/ruby.rb

@@ -4,43 +4,35 @@ 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.
+  # and return the result. It routes through {LLM::Tool::Exec}
+  # for process management.
   class Ruby < self
-    require_relative "utils"
-    include Utils
+    require "rbconfig"
+    require_relative "exec"
 
     name "ruby"
-    description "runs a string of ruby code"
+    description "Runs a string of ruby code\n" \
+                "This command (ruby) is spawned without a shell"
     parameter :code, String, "a string of ruby code"
     parameter :timeout, Integer, "maximum runtime before timeout"
+    parameter :max_bytes, Integer, "max number of bytes to emit"
     required %i[code]
-    defaults timeout: 15
+    defaults timeout: 15, max_bytes: -> { Exec.max_bytes }
 
     ##
     # @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)
+    # @param [Integer] max_bytes
+    #  Max bytes to emit
+    # @return [Hash]
+    def call(code:, timeout: 15, max_bytes: Exec.max_bytes)
+      Exec.new.call(
+        arguments: [RbConfig.ruby, "-e", code],
+        timeout:,
+        max_bytes:
+      )
     end
-
-    require "rbconfig"
-    LLM.require "test-cmd.rb", "~> 1.1"
-    Command = Test::Cmd
   end
 end

data/lib/llm/tools/utils.rb

@@ -2,13 +2,53 @@
 
 class LLM::Tool
   ##
-  # Shared utilities for tool implementations.
+  # Tool utils.
   module Utils
+    ##
+    # Truncates a string so a tool return stays bounded.
+    # Appends a marker when truncated so the model knows
+    # more content was available. Bounds each individual
+    # component (string field) a tool returns: a tool that
+    # returns multiple strings (eg stdout and stderr) caps
+    # each separately.
+    # @param [String] content
+    # @param [Integer] max_bytes
+    #  The max number of bytes to keep
+    # @return [String]
+    def truncate(content, max_bytes:)
+      body, truncated = truncate!(content, max_bytes:)
+      truncated ? "#{body}\n...\n[truncated: more than #{max_bytes} bytes]" : body
+    end
+
+    ##
+    # Performs the truncation and returns a tuple where the
+    # first element is the content, which can be either
+    # truncated or left intact. The second element is a
+    # boolean that indicates whether truncation took place.
+    #
+    # The difference between {#truncate truncate} and this
+    # method is that {#truncate truncate} appends a marker
+    # to the truncated content that indicates truncation
+    # took place, while this method leaves the content bare
+    # so a caller can structure it itself (eg
+    # {LLM::Tool::ReadFile}) without parsing the marker back
+    # out.
+    # @param [String] content
+    # @param [Integer] max_bytes
+    #  The max number of bytes to keep
+    # @return [[String, Boolean]]
+    #  A tuple of the content and whether truncation took place
+    def truncate!(content, max_bytes:)
+      s = content.to_s
+      return [s, false] if s.bytesize <= max_bytes
+      [s.byteslice(0, max_bytes), true]
+    end
+
     ##
     # Wait for a command to finish, or abort
     # with an error when it exceeds the
     # specified timeout.
-    # @param [Test::Cmd] command
+    # @param [Test::Command] command
     # @param [Integer] timeout
     # @return [void]
     def wait(command:, timeout:)
@@ -22,10 +62,43 @@ class LLM::Tool
       end
     end
 
+    ##
+    # Spawn a command from a name and arguments,
+    # without going through a shell. The command's
+    # stdout and stderr are each capped at `max_bytes`.
+    # @param [String] name
+    #  The command name
+    # @param [Array<String>] arguments
+    #  One or more arguments
+    # @param [Hash] env
+    #  Extra environment variables to set for the command
+    # @param [Integer] max_bytes
+    #  The max number of bytes to keep per stream.
+    #  Defaults to the including tool's `self.class.max_bytes`.
+    # @raise [ArgumentError]
+    #  When `max_bytes` is nil
+    # @return [Test::Command]
+    def spawn(name:, arguments:, env: {}, max_bytes: self.class.max_bytes)
+      if Integer(max_bytes, exception: false).nil?
+        raise ArgumentError, "max_bytes cannot be nil"
+      end
+      Command
+        .new(name)
+        .env(env)
+        .arguments(*[*arguments])
+        .limit(stdout: max_bytes, stderr: max_bytes)
+        .spawn
+    end
+
     ##
     # @return [Numeric]
     def now
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
+
+    ##
+    # requires test-cmd.rb
+    LLM.require "test-cmd.rb", "~> 2.7.1"
+    Command = Test::Command
   end
 end

data/lib/llm/tools/write_file.rb

@@ -10,13 +10,16 @@ class LLM::Tool
     description "write to a file"
     parameter :path, String, "The file path"
     parameter :content, String, "The file content"
+    parameter :newline, Boolean, "insert final newline (yes or no)"
     required %i[path content]
+    defaults newline: true
 
     ##
     # @param [String] path
     # @param [String] content
     # @return [Hash]
-    def call(path:, content:)
+    def call(path:, content:, newline: true)
+      content = content.end_with?("\n") ? content : "#{content}\n" if newline
       File.open(path, "w") { _1.write(content) }
       {ok: true}
     end

data/lib/llm/tracer/logger.rb

@@ -9,9 +9,9 @@ module LLM
   # @example
   #   llm = LLM.openai(key: ENV["KEY"])
   #   # Log to a file
-  #   llm.tracer = LLM::Tracer::Logger.new(llm, path: "/tmp/log.txt")
+  #   llm.tracer = LLM::Tracer.logger(llm, path: "/tmp/log.txt")
   #   # Log to $stdout (default)
-  #   llm.tracer = LLM::Tracer::Logger.new(llm, io: $stdout)
+  #   llm.tracer = LLM::Tracer.logger(llm, io: $stdout)
   class Tracer::Logger < Tracer
     ##
     # @param (see LLM::Tracer#initialize)

data/lib/llm/tracer/pretty_logger.rb

@@ -9,10 +9,10 @@ module LLM
   #
   # @example
   #   llm = LLM.openai(key: ENV["KEY"])
-  #   llm.tracer = LLM::Tracer::PrettyLogger.new(llm)
+  #   llm.tracer = LLM::Tracer.pretty_logger(llm)
   #
   # @example Writing to a file
-  #   llm.tracer = LLM::Tracer::PrettyLogger.new(llm, io: File.open("log.txt", "a"))
+  #   llm.tracer = LLM::Tracer.pretty_logger(llm, path: "log.txt")
   class Tracer::PrettyLogger < Tracer
     ##
     # @param (see LLM::Tracer#initialize)
@@ -73,8 +73,8 @@ module LLM
 
     private
 
-    def setup!(io: $stderr)
-      @io = io
+    def setup!(io: $stderr, path: nil)
+      @io = path ? ::File.open(path, "a") : io
       @start = nil
     end
 

data/lib/llm/tracer/telemetry.rb

@@ -18,7 +18,7 @@ module LLM
   #   require "pp"
   #
   #   llm = LLM.openai(key: ENV["KEY"])
-  #   llm.tracer = LLM::Tracer::Telemetry.new(llm)
+  #   llm.tracer = LLM::Tracer.telemetry(llm)
   #
   #   ctx = LLM::Context.new(llm)
   #   ctx.talk "hello"
@@ -33,7 +33,7 @@ module LLM
   #   exporter = OpenTelemetry::Exporter::OTLP::Exporter.new
   #
   #   llm = LLM.openai(key: ENV["KEY"])
-  #   llm.tracer = LLM::Tracer::Telemetry.new(llm, exporter:)
+  #   llm.tracer = LLM::Tracer.telemetry(llm, exporter:)
   #
   #   ctx = LLM::Context.new(llm)
   #   ctx.talk "hello"

data/lib/llm/tracer.rb

@@ -14,6 +14,39 @@ module LLM
     require_relative "tracer/null"
     require_relative "tracer/pretty_logger"
 
+    ##
+    # Builds a {LLM::Tracer::PrettyLogger} for a provider.
+    # @param [LLM::Provider] llm
+    #  A provider
+    # @param [Hash] options
+    #  Forwarded to {LLM::Tracer::PrettyLogger} (eg `io:`)
+    # @return [LLM::Tracer::PrettyLogger]
+    def self.pretty_logger(llm, **options)
+      PrettyLogger.new(llm, **options)
+    end
+
+    ##
+    # Builds a {LLM::Tracer::Logger} for a provider.
+    # @param [LLM::Provider] llm
+    #  A provider
+    # @param [Hash] options
+    #  Forwarded to {LLM::Tracer::Logger} (eg `path:` or `io:`)
+    # @return [LLM::Tracer::Logger]
+    def self.logger(llm, **options)
+      Logger.new(llm, **options)
+    end
+
+    ##
+    # Builds a {LLM::Tracer::Telemetry} for a provider.
+    # @param [LLM::Provider] llm
+    #  A provider
+    # @param [Hash] options
+    #  Forwarded to {LLM::Tracer::Telemetry} (eg `exporter:`)
+    # @return [LLM::Tracer::Telemetry]
+    def self.telemetry(llm, **options)
+      Telemetry.new(llm, **options)
+    end
+
     ##
     # @return [LLM::Provider]
     attr_reader :llm

data/lib/llm/transport/curb.rb

@@ -28,12 +28,14 @@ class LLM::Transport
     # @param [String] host
     # @param [Integer] port
     # @param [Integer] timeout
+    # @param [Integer] connect_timeout
     # @param [Boolean] ssl
     # @return [LLM::Transport::Curb]
-    def initialize(host:, port:, timeout:, ssl:)
+    def initialize(host:, port:, timeout:, connect_timeout:, ssl:)
       @host = host
       @port = port
       @timeout = timeout
+      @connect_timeout = connect_timeout
       @ssl = ssl
       @base_uri = URI("#{ssl ? "https" : "http"}://#{host}:#{port}/")
       @monitor = Monitor.new
@@ -112,13 +114,13 @@ class LLM::Transport
 
     private
 
-    attr_reader :host, :port, :timeout, :ssl, :base_uri
+    attr_reader :host, :port, :timeout, :connect_timeout, :ssl, :base_uri
 
     def build_easy(request)
       LLM.require "curb" unless defined?(::Curl)
       easy = ::Curl::Easy.new(request_url(request))
       easy.timeout = timeout
-      easy.connect_timeout = timeout
+      easy.connect_timeout = connect_timeout
       request.headers.each { |k, v| easy.headers[k] = v }
       easy.follow_location = true
       easy.ssl_verify_peer = false if !ssl

data/lib/llm/transport/http.rb

@@ -20,12 +20,14 @@ class LLM::Transport
     # @param [String] host
     # @param [Integer] port
     # @param [Integer] timeout
+    # @param [Integer] connect_timeout
     # @param [Boolean] ssl
     # @return [LLM::Transport::HTTP]
-    def initialize(host:, port:, timeout:, ssl:)
+    def initialize(host:, port:, timeout:, connect_timeout:, ssl:)
       @host = host
       @port = port
       @timeout = timeout
+      @connect_timeout = connect_timeout
       @ssl = ssl
       @base_uri = URI("#{ssl ? "https" : "http"}://#{host}:#{port}/")
       @monitor = Monitor.new
@@ -93,10 +95,11 @@ class LLM::Transport
 
     private
 
-    attr_reader :host, :port, :timeout, :ssl, :base_uri
+    attr_reader :host, :port, :timeout, :connect_timeout, :ssl, :base_uri
 
     def client
       client = Net::HTTP.new(host, port)
+      client.open_timeout = connect_timeout
       client.read_timeout = timeout
       client.use_ssl = ssl
       client

data/lib/llm/transport/persistent_http.rb

@@ -32,12 +32,14 @@ class LLM::Transport
     # @param [String] host
     # @param [Integer] port
     # @param [Integer] timeout
+    # @param [Integer] connect_timeout
     # @param [Boolean] ssl
     # @return [LLM::Transport::PersistentHTTP]
-    def initialize(host:, port:, timeout:, ssl:)
+    def initialize(host:, port:, timeout:, connect_timeout:, ssl:)
       @host = host
       @port = port
       @timeout = timeout
+      @connect_timeout = connect_timeout
       @ssl = ssl
       @base_uri = URI("#{ssl ? "https" : "http"}://#{host}:#{port}/")
       @monitor = Monitor.new
@@ -100,7 +102,7 @@ class LLM::Transport
 
     private
 
-    attr_reader :host, :port, :timeout, :ssl, :base_uri
+    attr_reader :host, :port, :timeout, :connect_timeout, :ssl, :base_uri
 
     def client
       self.class.lock do
@@ -110,14 +112,14 @@ class LLM::Transport
           LLM.require "net/http/persistent" unless defined?(Net::HTTP::Persistent)
           client = Net::HTTP::Persistent.new(name: self.class.name)
           client.read_timeout = timeout
-          client.open_timeout = timeout
+          client.open_timeout = connect_timeout
           self.class.registry[client_id] = client
         end
       end
     end
 
     def client_id
-      "#{host}:#{port}:#{timeout}:#{ssl}"
+      "#{host}:#{port}:#{timeout}:#{connect_timeout}:#{ssl}"
     end
 
     def close_socket(http)

data/lib/llm/transport/utils.rb

@@ -24,18 +24,19 @@ class LLM::Transport
     # @param [String] host
     # @param [Integer] port
     # @param [Integer, nil] timeout
+    # @param [Integer] connect_timeout
     # @param [Boolean] ssl
     # @param [Boolean] persistent
     # @param [LLM::Transport, Class, Symbol, nil] transport
     # @return [LLM::Transport]
-    def resolve_transport(host:, port:, timeout:, ssl:, persistent:, transport:)
+    def resolve_transport(host:, port:, timeout:, ssl:, persistent:, transport:, connect_timeout: 5)
       if transport.nil?
-        default_transport(host:, port:, timeout:, ssl:, persistent:)
+        default_transport(host:, port:, timeout:, connect_timeout:, ssl:, persistent:)
       elsif Class === transport && transport <= LLM::Transport
-        transport.new(host:, port:, timeout:, ssl:)
+        transport.new(host:, port:, timeout:, connect_timeout:, ssl:)
       elsif Symbol === transport
         transport = LLM::Transport.public_send(transport)
-        transport.new(host:, port:, timeout:, ssl:)
+        transport.new(host:, port:, timeout:, connect_timeout:, ssl:)
       else
         transport
       end
@@ -49,12 +50,13 @@ class LLM::Transport
     # @param [String] host
     # @param [Integer] port
     # @param [Integer, nil] timeout
+    # @param [Integer] connect_timeout
     # @param [Boolean] ssl
     # @param [Boolean] persistent
     # @return [LLM::Transport]
-    def default_transport(host:, port:, timeout:, ssl:, persistent:)
+    def default_transport(host:, port:, timeout:, connect_timeout:, ssl:, persistent:)
       target = persistent ? LLM::Transport::PersistentHTTP : LLM::Transport::HTTP
-      target.new(host:, port:, timeout:, ssl:)
+      target.new(host:, port:, timeout:, connect_timeout:, ssl:)
     end
   end
 end

data/lib/llm/version.rb

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

data/lib/llm.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 ##
-# llm.rb is a zero-dependency AI runtime for Ruby. Thirteen providers, six
+# llm.rb is a zero-dependency AI runtime for Ruby. Fourteen providers, six
 # concurrency strategies, MCP and A2A, streaming tool calls with
 # cancellation, context compaction, and ORM persistence.
 #
@@ -18,6 +18,7 @@ module LLM
 
   require "stringio"
   require "securerandom"
+  require "time"
   require_relative "llm/compactor"
   require_relative "llm/transformer"
   require_relative "llm/json_adapter"
@@ -77,7 +78,9 @@ module LLM
   # @raise [LLM::LoadError]
   #  When the dependency cannot be loaded
   def self.require(name, version = nil)
-    names = {"xchan" => "xchan.rb", "net/http/persistent" => "net-http-persistent"}
+    names = {"xchan" => "xchan.rb",
+              "net/http/persistent" => "net-http-persistent",
+              "unicode/display_width" => "unicode-display_width"}
     gem(names[name] || name, version) if version
     super(name)
   rescue ::LoadError
@@ -260,6 +263,19 @@ module LLM
     end
   end
 
+  ##
+  # @param key (see LLM::OpenRouter#initialize)
+  # @param host (see LLM::OpenRouter#initialize)
+  # @return (see LLM::OpenRouter#initialize)
+  def openrouter(key: UNDEFINED, **)
+    lock(:require) { require_relative "llm/providers/openrouter" unless defined?(LLM::OpenRouter) }
+    if key == UNDEFINED
+      LLM::OpenRouter.new(key: key(name: __method__), **)
+    else
+      LLM::OpenRouter.new(key:, **)
+    end
+  end
+
   ##
   # @param key (see LLM::Alibaba#initialize)
   # @param host (see LLM::Alibaba#initialize)
@@ -346,16 +362,6 @@ module LLM
     LLM::Function.new(key, &b)
   end
 
-  ##
-  # @param [LLM::Provider] llm
-  #  A provider
-  # @param [Hash] params
-  #  Forwarded to LLM::Tracer::Logger
-  # @return [LLM::Tracer::Logger]
-  def logger(llm, **params)
-    LLM::Tracer::Logger.new(llm, params)
-  end
-
   ##
   # Provides a thread-safe lock
   # @param [Symbol] name The name of the lock