llm.rb 12.6.0 → 13.1.0

data/lib/llm/repl.rb

@@ -17,15 +17,24 @@ 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, :buffer, :input,
+                :window, :tools, :thread,
+                :name, :path, :width
 
     ##
     # @param [LLM::Agent] agent
+    # @param [String, nil] name
+    #  The agent's name (optional)
     # @param [String, nil] path
     #  The path where to maintain runtime state
     # @param [Array<LLM::Tool>] tools
@@ -33,14 +42,16 @@ module LLM
     # @param [Array<String>] skills
     #  Zero or more skills
     # @return [LLM::Repl]
-    def initialize(agent:, tools: [], skills: [], path: nil)
-      @path  = path
+    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
-      @input = Input.new(@agent, height: 3)
-      @window = Window.new(@status, @transcript, @input)
+      @status = Status.new(self)
+      @buffer = Buffer.new(self)
+      @input = Input.new(self, height: 3)
+      @window = Window.new(self)
       @thread = nil
       @queue = Queue.new
       @stream = Stream.new(self, @queue)
@@ -61,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)
@@ -77,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]
@@ -109,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
@@ -142,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("\nagent: ", Curses::A_BOLD)
+        write_message("user", markdown(text))
         @thread = Thread.new do
           @queue << [:start]
           agent.talk(text, tools:, stream:)
@@ -181,12 +218,14 @@ module LLM
            "command(#{command.name}): ",
            "too few arguments: expected #{reqc} but got #{args.size}\n\n"]
         else
+          parameters = parameters.sort_by(&:index).to_h
+          kwargs = {}
           parameters.each_value do |parameter|
             if args[parameter.index]
-              parameter.value = args[parameter.index]
+              kwargs[parameter.name] = args[parameter.index]
             end
           end
-          [:command, command.new(self), parameters.transform_values(&:value)]
+          [:command, command.new(self), kwargs]
         end
       else
         [:input, text]
@@ -203,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\nagent: ", 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
@@ -246,11 +283,6 @@ module LLM
       File.readable?(path)
     end
 
-    attr_reader :agent, :provider, :stream,
-                :status, :transcript, :input,
-                :window, :tools, :thread,
-                :path
-
     File = ::File
     private_constant :File
   end

data/lib/llm/response.rb

@@ -10,12 +10,22 @@ module LLM
   # handling can share one common surface without flattening away
   # specialized behavior.
   #
+  # @example Accessing response data
+  #   res = agent.talk "Weather in Paris?", schema: Weather
+  #   res.content        # => raw text or structured data
+  #   res.content!       # => parsed JSON as LLM::Object
+  #   res.usage          # => token usage (input, output, cache, etc.)
+  #   res.messages       # => message history from this turn
+  #
   # The normalized response keeps the transport response available
   # through {#res}. When the default net/http transport is in use,
   # {LLM::Transport::Response::HTTP
   # LLM::Transport::Response::HTTP} keeps the
   # original `Net::HTTPResponse` available through
   # its own {LLM::Transport::Response::HTTP#res #res}.
+  #
+  # @see LLM::Context Responses are returned by Context#talk
+  # @see LLM::Agent Responses are returned by Agent#talk
   class Response
     require "json"
 

data/lib/llm/schema/leaf.rb

@@ -8,12 +8,17 @@ class LLM::Schema
   # an example of how to create instances of {LLM::Schema::Leaf LLM::Schema::Leaf}
   # through its subclasses.
   class Leaf
+    ##
+    # @return [Integer, nil]
+    attr_accessor :index
+
     def initialize
       @description = nil
       @default = nil
       @enum = nil
       @required = nil
       @const = nil
+      @index = nil
     end
 
     ##

data/lib/llm/schema/object.rb

@@ -16,21 +16,22 @@ class LLM::Schema
     #  A hash of properties
     # @return [LLM::Schema::Object]
     def initialize(properties)
-      @properties = properties
+      @properties = LLM::Object.new
+      properties.each { set!(_1, _2) }
     end
 
     ##
     # Get a property
     # @return [LLM::Schema::Leaf]
     def [](key)
-      properties[key.to_s]
+      properties[key]
     end
 
     ##
     # Set a property
     # @return [void]
     def []=(key, val)
-      properties[key.to_s] = val
+      set!(key, val)
     end
 
     ##
@@ -46,7 +47,7 @@ class LLM::Schema
     #  Returns self
     def merge!(other)
       raise TypeError, "expected #{self.class} but got #{other.class}" unless self.class === other
-      @properties.merge!(other.properties)
+      other.properties.each { |key, val| self[key] = val }
       self
     end
 
@@ -64,8 +65,13 @@ class LLM::Schema
 
     private
 
+    def set!(key, val)
+      val.index = @properties.size
+      properties[key] = val
+    end
+
     def required_items
-      @properties.filter_map {  _2.required? ? _1 : nil }
+      @properties.filter_map { _2.required? ? _1 : nil }
     end
   end
 end

data/lib/llm/sequel/plugin.rb

@@ -204,17 +204,17 @@ module LLM::Sequel
     end
 
     ##
-    # @see LLM::Context#functions
+    # @see LLM::Context#pending_functions
     # @return [Array<LLM::Function>]
-    def functions
-      ctx.functions
+    def pending_functions
+      ctx.pending_functions
     end
 
     ##
-    # @see LLM::Context#functions?
+    # @see LLM::Context#pending_functions?
     # @return [Boolean]
-    def functions?
-      ctx.functions?
+    def pending_functions?
+      ctx.pending_functions?
     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/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.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/{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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# frozen_string_literal
-
 class LLM::Tool
   ##
   # The {LLM::Tool::Git LLM::Tool::Git} class implements
@@ -9,19 +7,28 @@ 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}
+    rescue LLM::Interrupt
+      command.kill! if command&.running?
+      raise
     end
 
     private
@@ -34,7 +41,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

@@ -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
@@ -26,7 +29,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,20 +7,29 @@ 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}
+    rescue LLM::Interrupt
+      command.kill! if command&.running?
+      raise
     end
 
     private
@@ -41,7 +48,7 @@ class LLM::Tool
         .spawn
     end
 
-    LLM.require "test-cmd.rb"
+    LLM.require "test-cmd.rb", "~> 1.1"
     Command = Test::Cmd
   end
 end