llm.rb 12.0.0 → 12.1.0

data/lib/llm/tools/git.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# frozen_string_literal
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::Git LLM::Tool::Git} class implements
+  # a tool that can perform a select number of git actions.
+  # The actions it can perform are read-only - at least for
+  # the time being.
+  class Git < self
+    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"
+    required %i[action]
+
+    ##
+    # @param [String] path
+    # @param [Integer] start
+    # @param [Integer] stop
+    # @return [Hash]
+    def call(action:, arguments: nil)
+      command = spawn(action:, arguments:)
+      {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
+    end
+
+    private
+
+    def spawn(action:, arguments:)
+      Command
+        .new("git")
+        .argv(action)
+        .argv(*[*arguments])
+        .spawn
+    end
+
+    LLM.require "test-cmd.rb"
+    Command = Test::Cmd
+  end
+end

data/lib/llm/tools/mkdir.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::Mkdir LLM::Tool::Mkdir} class implements
+  # a tool that can create a tree of new directories.
+  class Mkdir < self
+    name "mkdir"
+    description "create a new directory"
+    parameter :path, String, "the path to the directory"
+
+    ##
+    # @param [String] path
+    # @return [Hash]
+    def call(path:)
+      command = spawn(path:)
+      {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
+    end
+
+    private
+
+    def spawn(path:)
+      Command
+        .new("mkdir")
+        .argv("-p", path)
+        .spawn
+    end
+
+    LLM.require "test-cmd.rb"
+    Command = Test::Cmd
+  end
+end

data/lib/llm/tools/pwd.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# frozen_string_literal
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::Pwd LLM::Tool::Pwd} class implements
+  # a tool that can reveal the current working directory.
+  class Pwd < self
+    name "pwd"
+    description "returns the current working directory"
+
+    ##
+    # @param [String] path
+    # @return [Hash]
+    def call
+      {ok: true, cwd: Dir.getwd}
+    end
+  end
+end

data/lib/llm/tools/read_file.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# frozen_string_literal
+
+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.
+  class ReadFile < self
+    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"
+    required %i[path]
+
+    ##
+    # @param [String] path
+    # @param [Integer] start
+    # @param [Integer] stop
+    # @return [Hash]
+    def call(path:, start: 1, stop: -1)
+      content, cursor = nil, 1
+      File.open(path, "r") do |f|
+        while cursor < start
+          f.gets
+          cursor += 1
+        end
+        if stop == -1
+          content = f.read
+        else
+          content = start.upto(stop).map { f.gets }.join
+        end
+      end
+      {ok: true, content:}
+    end
+  end
+end

data/lib/llm/tools/rg.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# frozen_string_literal
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::Rg LLM::Tool::Rg} class implements
+  # a frontend to the popular 'rg' tool. The tool can
+  # recursively search the current working directory
+  # for one or more patterns.
+  class Rg < self
+    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)"
+    required %i[patterns]
+
+    ##
+    # @param [String] pattern
+    # @return [Hash]
+    def call(patterns:, path: Dir.getwd)
+      validate!(patterns:, path:)
+      command = spawn(patterns:, path:)
+      {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
+    end
+
+    private
+
+    def validate!(patterns:, path:)
+      if 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"
+    Command = Test::Cmd
+  end
+end

data/lib/llm/tools/shell.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# frozen_string_literal
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::Shell} class implements a tool that can
+  # spawn a command. That can be dangerous given a low-quality
+  # model, or a high-quality model that simply makes a bad
+  # decision. The risk can be reduced through a confirmation
+  # step such as {LLM::Agent.confirm LLM::Agent.confirm}, or
+  # by managing the tool loop manually through
+  # {LLM::Context LLM::Context}.
+  class Shell < self
+    name "shell"
+    description "run a shell command"
+    parameter :name, String, "the command name"
+    parameter :arguments, Array[String], "one or more command arguments"
+    required %i[name]
+
+    ##
+    # @param [String] name
+    #  The name of a command
+    # @param [Array<String>] arguments
+    #  One or more command-line arguments
+    # @return [Hash]
+    def call(name:, arguments: nil)
+      command = spawn(name:, arguments:)
+      {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
+    end
+
+    private
+
+    ##
+    # @param [String] name
+    # @param [Array<String>] arguments
+    # @return [Command]
+    def spawn(name:, arguments:)
+      Command
+        .new(name)
+        .argv(*[*arguments])
+        .spawn
+    end
+
+    LLM.require "test-cmd.rb"
+    Command = Test::Cmd
+  end
+end

data/lib/llm/tools/swap_text.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::SwapText LLM::Tool::SwapText} 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"
+    description "Replace an exact snippet in a file"
+    parameter :path, String, "Path to file"
+    parameter :before, String, "Exact text to replace"
+    parameter :after, String, "Replacement text"
+    parameter :expected_count, Integer, "How many matches should be replaced"
+    required %i[path before after]
+
+    def call(path:, before:, after:, expected_count: 1)
+      content = File.read(path)
+      count = content.scan(before).length
+      raise "expected #{expected_count} match(es), found #{count}" unless count == expected_count.to_i
+      File.write(path, content.sub(before, after))
+      {ok: true, replaced: count}
+    end
+  end
+end

data/lib/llm/tools/write_file.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::WriteFile LLM::Tool::WriteFile} class
+  # implements a tool that can write a given string to a
+  # given file path.
+  class WriteFile < self
+    name "write-file"
+    description "write to a file"
+    parameter :path, String, "The file path"
+    parameter :content, String, "The file content"
+    required %i[path content]
+
+    ##
+    # @param [String] path
+    # @param [String] content
+    # @return [Hash]
+    def call(path:, content:)
+      File.open(path, "w") { _1.write(content) }
+      {ok: true}
+    end
+  end
+end

data/lib/llm/tools.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+Dir[File.join(__dir__, "tools", "*.rb")].each do
+  require(_1)
+end

data/lib/llm/version.rb

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

data/resources/deepdive.md

@@ -54,6 +54,8 @@ features that didn't make it into the homepage documentation.
 - [Tracer](#tracer)
   - [Provider-wide tracer](#provider-wide-tracer)
   - [Agent-local tracer](#agent-local-tracer)
+- [REPL](#repl)
+  - [LLM::Agent](#llmagent)
 - [Images](#images)
   - [Generation](#generation)
   - [Edits](#edits)
@@ -802,6 +804,36 @@ agent = LLM::Agent.new(llm, tracer: LLM::Tracer::Logger.new(llm, path: "deepseek
 
 [Back to top](#table-of-contents)
 
+## REPL
+
+During the development and operation of agents it can often
+be helpful to drop into a read-eval-print loop. This gives
+you a simple way to confirm the work was successful, inspect
+anything that went wrong (for example, tool call errors), and
+keep talking to the same agent so you can learn about its
+decision-making process and make improvements for future runs.
+It can also be used to ask the agent to correct any errors
+that might have made.
+
+##### LLM::Agent
+
+The [LLM::Agent#repl](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#repl-instance_method)
+method requires the [curses](https://github.com/ruby/curses)
+gem to be installed and available for require. It is an
+optional dependency that only becomes required when you
+call the [LLM::Agent#repl](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#repl-instance_method)
+method.
+
+```ruby
+require "llm"
+
+llm = LLM.deepseek(key: ENV["KEY"])
+agent = LLM::Agent.new(llm)
+agent.repl
+```
+
+[Back to top](#table-of-contents)
+
 ## Images
 
 The OpenAI, Google, xAI, DeepInfra, and DeepSeek providers have

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 12.0.0
+  version: 12.1.0
 platform: ruby
 authors:
 - bsdrobert
@@ -459,6 +459,12 @@ files:
 - lib/llm/providers/xai/images.rb
 - lib/llm/providers/zai.rb
 - lib/llm/registry.rb
+- lib/llm/repl.rb
+- lib/llm/repl/input.rb
+- lib/llm/repl/status.rb
+- lib/llm/repl/stream.rb
+- lib/llm/repl/transcript.rb
+- lib/llm/repl/window.rb
 - lib/llm/response.rb
 - lib/llm/schema.rb
 - lib/llm/schema/all_of.rb
@@ -485,6 +491,16 @@ files:
 - lib/llm/stream/queue.rb
 - lib/llm/tool.rb
 - lib/llm/tool/param.rb
+- lib/llm/tools.rb
+- lib/llm/tools/chdir.rb
+- lib/llm/tools/git.rb
+- lib/llm/tools/mkdir.rb
+- lib/llm/tools/pwd.rb
+- lib/llm/tools/read_file.rb
+- lib/llm/tools/rg.rb
+- lib/llm/tools/shell.rb
+- lib/llm/tools/swap_text.rb
+- lib/llm/tools/write_file.rb
 - lib/llm/tracer.rb
 - lib/llm/tracer/logger.rb
 - lib/llm/tracer/null.rb