llm.rb 13.0.0 → 13.1.0

data/lib/llm/repl/stream.rb

@@ -42,9 +42,9 @@ class LLM::Repl
     end
 
     ##
-    # Empty the accumulated buffer
+    # Clear the accumulated buffer
     # @return [void]
-    def empty!
+    def clear
       @buffer.clear
     end
 

data/lib/llm/repl/window.rb

@@ -11,22 +11,21 @@ class LLM::Repl
     attr_reader :status
 
     ##
-    # @return [LLM::Repl::Transcript]
-    attr_reader :transcript
+    # @return [LLM::Repl::Buffer]
+    attr_reader :buffer
 
     ##
     # @return [LLM::Repl::Input]
     attr_reader :input
 
     ##
-    # @param [LLM::Repl::Status] status
-    # @param [LLM::Repl::Transcript] transcript
-    # @param [LLM::Repl::Input] input
+    # @param [LLM::Repl] repl
+    #  A read-eval-print loop.
     # @return [LLM::Repl::Window]
-    def initialize(status, transcript, input)
-      @status = status
-      @transcript = transcript
-      @input = input
+    def initialize(repl)
+      @status = repl.status
+      @buffer = repl.buffer
+      @input  = repl.input
     end
 
     ##
@@ -48,7 +47,7 @@ class LLM::Repl
     def redraw
       draw_status(offset: input.height + 1)
       draw_divider(offset: 5)
-      draw_transcript(offset: 0)
+      draw_buffer(offset: 0)
       draw_input
       Curses.refresh
     end
@@ -86,23 +85,42 @@ class LLM::Repl
     ##
     # @return [void]
     def scroll_up
-      transcript.scroll_up(rows)
+      buffer.scroll_up(rows)
     end
 
     ##
     # @return [void]
     def scroll_down
-      transcript.scroll_down
+      buffer.scroll_down
     end
 
     ##
     # @return [void]
     def scroll_to_bottom
-      transcript.scroll_to_bottom
+      buffer.scroll_to_bottom
     end
 
     private
 
+    def draw_buffer(offset:)
+      rows = buffer.visible(self.rows)
+      rows.each.with_index(offset) do |row, index|
+        Curses.setpos(index, 0)
+        Curses.clrtoeol
+        row.each do |chunk|
+          text, attrs = chunk.text, chunk.attrs
+          Curses.attron(attrs) if attrs
+          Curses.addstr(text)
+          Curses.attroff(attrs) if attrs
+        end
+      end
+      last_drawn = offset + rows.size
+      (last_drawn...self.rows).each do |line|
+        Curses.setpos(line, 0)
+        Curses.clrtoeol
+      end
+    end
+
     def draw_status(offset:)
       Curses.setpos(Curses.lines - offset, 0)
       Curses.clrtoeol
@@ -132,25 +150,6 @@ class LLM::Repl
       Curses.setpos((Curses.lines - input.height) + line, col)
     end
 
-    def draw_transcript(offset:)
-      rows = transcript.visible(self.rows)
-      rows.each.with_index(offset) do |row, index|
-        Curses.setpos(index, 0)
-        Curses.clrtoeol
-        row.each do |chunk|
-          text, attrs = chunk.values_at(:text, :attrs)
-          Curses.attron(attrs) if attrs
-          Curses.addstr(text)
-          Curses.attroff(attrs) if attrs
-        end
-      end
-      last_drawn = offset + rows.size
-      (last_drawn...self.rows).each do |line|
-        Curses.setpos(line, 0)
-        Curses.clrtoeol
-      end
-    end
-
     ##
     # @return [Integer]
     def columns

data/lib/llm/repl.rb

@@ -17,18 +17,19 @@ module LLM
   class Repl
     require_relative "repl/window"
     require_relative "repl/status"
-    require_relative "repl/transcript"
+    require_relative "repl/buffer"
     require_relative "repl/input"
     require_relative "repl/bar"
     require_relative "repl/stream"
+    require_relative "repl/node"
     require_relative "repl/markdown"
     require_relative "repl/command"
     require_relative "repl/walker"
 
     attr_reader :agent, :provider, :stream,
-                :status, :transcript, :input,
+                :status, :buffer, :input,
                 :window, :tools, :thread,
-                :name, :path
+                :name, :path, :width
 
     ##
     # @param [LLM::Agent] agent
@@ -42,14 +43,15 @@ module LLM
     #  Zero or more skills
     # @return [LLM::Repl]
     def initialize(agent:, name: nil, tools: [], skills: [], path: nil)
+      @width = 80
       @path = path
       @name = name || "agent"
       @agent = configure(agent:, path:)
       @provider = agent.llm.name
-      @status = Status.new(@agent)
-      @transcript = Transcript.new
+      @status = Status.new(self)
+      @buffer = Buffer.new(self)
       @input = Input.new(self, height: 3)
-      @window = Window.new(@status, @transcript, @input)
+      @window = Window.new(self)
       @thread = nil
       @queue = Queue.new
       @stream = Stream.new(self, @queue)
@@ -70,6 +72,7 @@ module LLM
     def start
       window.open do
         catch(:exit) do
+          write tree(agent.messages)
           loop do
             now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
             case input.on_char(window, input.paste? ? window.read_paste : window.getch, now)
@@ -86,22 +89,32 @@ module LLM
     end
 
     ##
-    # @param [String] chars
+    # @param [String, Array] chars
     # @param [Object] attrs
+    # @param [Symbol] method (:append, :replace)
     # @return [void]
-    def write(chars, attrs = nil)
-      transcript.write(chars, attrs)
+    def write(chars, attrs = nil, method: :append)
+      buffer.write(chars, attrs, method:)
       window.redraw
     end
 
     ##
-    # @param [String] chars
+    # @param [String] user
+    # @param [String] content
     # @return [void]
-    def markdown(chars)
-      transcript.markdown(chars)
+    def write_message(user, content, method: :append)
+      buffer.write_message(user, content, method:)
       window.redraw
     end
 
+    ##
+    # Returns an AST
+    # @param [String] chars
+    # @return [Array<Node>]
+    def markdown(chars)
+      LLM::Repl::Markdown.new(chars, width).ast
+    end
+
     ##
     # @param [String] value
     # @return [void]
@@ -118,6 +131,22 @@ module LLM
 
     private
 
+    ##
+    # @param [LLM::Buffer] messages
+    #  A message buffer
+    # @return [Array<Node>]
+    def tree(messages)
+      messages.flat_map do |message|
+        next if message.tool_call? || message.tool_return?
+        user = message.assistant? ? name : "user"
+        [
+          Node.new("#{user}: ", Curses::A_BOLD),
+          Node.new(message.content),
+          Node.new(user == name ? "\n\n" : "\n")
+        ]
+      end.compact
+    end
+
     ##
     # @param [LLM::Agent] agent
     #  An agent
@@ -151,15 +180,14 @@ module LLM
       case on_text(text)
       in [:command, Command => command, Hash => parameters]
         command.call(**parameters)
-      in [:error, String => who, String => text]
-        write(who, Curses::A_BOLD)
-        write(text)
+        write("\n")
+      in [:error, String => user, String => text]
+        write_message(user, text)
+        write("\n")
       in [:input, String => text]
         window.scroll_to_bottom
         status.text = thinking_text
-        write("user: ", Curses::A_BOLD)
-        markdown(text)
-        write("\n#{name}: ", Curses::A_BOLD)
+        write_message("user", markdown(text))
         @thread = Thread.new do
           @queue << [:start]
           agent.talk(text, tools:, stream:)
@@ -214,29 +242,27 @@ module LLM
         type, value = @queue.pop(true)
         case type
         when :start
-          transcript.start
-          stream.empty!
+          buffer.open
+          stream.clear
         when :stream
-          transcript.markdown(value, method: :replace)
+          write_message name, markdown(value), method: :replace
         when :status
           self.status = value
         when :done
           status.text = "idle"
-          write("\n\n")
-          transcript.finish
+          buffer.close
           @thread = nil
+          write("\n")
         when :cancel
+          buffer.close
           status.text = "Idle"
-          write("\n\n#{name}: ", Curses::A_BOLD)
-          write("request cancelled!")
-          write("\n\n")
-          transcript.finish
+          write_message(name, "Request cancelled")
           @thread = nil
+          write("\n")
         when :error
-          # Do this better
           status.text = "error"
-          write("\nerror: #{value.message}\n", Curses::A_BOLD)
-          transcript.finish
+          write_message(name, "(#{value.class}): #{value.message}")
+          buffer.close
           @thread = nil
         end
       end

data/lib/llm/skill.rb

@@ -7,6 +7,11 @@ module LLM
   # Skills can expose themselves as normal {LLM::Tool LLM::Tool} classes through
   # {#to_tool}. This keeps skills on the same execution path as local tools.
   class Skill
+    ##
+    # @api private
+    File = ::File
+    private_constant :File
+
     ##
     # Load a skill from a directory.
     # @param [String, Pathname] path
@@ -63,8 +68,14 @@ module LLM
     # Load and parse the skill.
     # @return [LLM::Skill]
     def load!
-      path = ::File.join(@path, "SKILL.md")
-      parse(::File.read(path))
+      if File.file?(@path)
+        parse(File.read(@path))
+      elsif File.directory?(@path)
+        path = File.join(@path, "SKILL.md")
+        parse(File.read(path))
+      else
+        raise LLM::Error, "'#{@path}' is neither a file or directory"
+      end
       self
     end
 
@@ -103,7 +114,8 @@ module LLM
     end
 
     ##
-    # Returns true when a skill should inherit tools from its parent
+    # Returns true when a skill should inherit tools
+    # from its parent
     # @return [Boolean]
     def inherit_tools?
       @inherit_tools
@@ -138,7 +150,11 @@ module LLM
     def parse_tools(tools)
       case tools
       when String
-        tools == "inherit" ? [true, []] : raise_invalid_error!(tools)
+        case tools
+        when "inherit" then [true, []]
+        when "all", "*" then [false, LLM::Tool.registry]
+        else raise_invalid_error!(tools)
+        end
       when Array
         [false, [*@frontmatter.tools].map { LLM::Tool.find_by_name!(_1) }]
       when NilClass

data/lib/llm/tools/{swap_text.rb → edit-file.rb}

@@ -2,11 +2,11 @@
 
 class LLM::Tool
   ##
-  # The {LLM::Tool::SwapText LLM::Tool::SwapText} class
+  # The {LLM::Tool::EditFile LLM::Tool::EditFile} class
   # implements a tool that can substitute one piece of
   # text for another piece of text in a given file.
-  class SwapText < self
-    name "swap-text"
+  class EditFile < self
+    name "edit-file"
     description "Replace an exact snippet in a file"
     parameter :path, String, "Path to file"
     parameter :before, String, "Exact text to replace"

data/lib/llm/tools/git.rb

@@ -26,6 +26,9 @@ class LLM::Tool
       command = spawn(action:, arguments:)
       wait(command:, timeout:)
       {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
+    rescue LLM::Interrupt
+      command.kill! if command&.running?
+      raise
     end
 
     private

data/lib/llm/tools/mkdir.rb

@@ -15,6 +15,9 @@ class LLM::Tool
     def call(path:)
       command = spawn(path:)
       {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
+    rescue LLM::Interrupt
+      command.kill! if command&.running?
+      raise
     end
 
     private

data/lib/llm/tools/rg.rb

@@ -27,6 +27,9 @@ class LLM::Tool
       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
     end
 
     private

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

@@ -31,6 +31,9 @@ class LLM::Tool
       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

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 = "13.0.0"
+  VERSION = "13.1.0"
 end

data/llm.gemspec

@@ -12,7 +12,7 @@ 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
 
@@ -30,9 +30,15 @@ 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"