llm.rb 12.0.0 → 12.2.0

data/lib/llm/repl/window.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+class LLM::Repl
+  ##
+  # The {LLM::Repl::Window LLM::Repl::Window} class draws the
+  # curses screen for the REPL.
+  # @api private
+  class Window
+    ##
+    # @return [LLM::Repl::Status]
+    attr_reader :status
+
+    ##
+    # @return [LLM::Repl::Transcript]
+    attr_reader :transcript
+
+    ##
+    # @return [LLM::Repl::Input]
+    attr_reader :input
+
+    ##
+    # @param [LLM::Repl::Status] status
+    # @param [LLM::Repl::Transcript] transcript
+    # @param [LLM::Repl::Input] input
+    # @return [LLM::Repl::Window]
+    def initialize(status, transcript, input)
+      @status = status
+      @transcript = transcript
+      @input = input
+    end
+
+    ##
+    # @yield
+    # @return [void]
+    def open
+      Curses.init_screen
+      Curses.cbreak
+      Curses.noecho
+      Curses.stdscr.keypad(true)
+      yield
+    ensure
+      Curses.close_screen
+    end
+
+    ##
+    # @return [void]
+    def redraw
+      Curses.clear
+      draw_status
+      draw_transcript
+      draw_input
+      Curses.refresh
+    end
+
+    ##
+    # @return [Integer]
+    def rows
+      [Curses.lines - 3, 1].max
+    end
+
+    ##
+    # @return [Object]
+    def getch
+      Curses.getch
+    end
+
+    ##
+    # @return [void]
+    def scroll_up
+      transcript.scroll_up(rows)
+    end
+
+    ##
+    # @return [void]
+    def scroll_down
+      transcript.scroll_down
+    end
+
+    private
+
+    def draw_status
+      Curses.setpos(0, 0)
+      Curses.addstr(status.to_s)
+      provider = status.provider.to_s
+      Curses.setpos(0, [columns - provider.length, 0].max)
+      Curses.addstr(provider)
+    end
+
+    def draw_transcript
+      visible = transcript.visible(rows)
+      visible.each_with_index do |row, index|
+        Curses.setpos(index + 2, 0)
+        Curses.addstr(row)
+      end
+    end
+
+    def draw_input
+      Curses.setpos(Curses.lines - 1, 0)
+      Curses.clrtoeol
+      Curses.addstr(input.to_s)
+    end
+
+    def columns
+      Curses.cols
+    end
+  end
+end

data/lib/llm/repl.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+LLM.require "curses"
+
+module LLM
+  ##
+  # The {LLM::Repl LLM::Repl} class provides a small
+  # read-eval-print loop around an instance of
+  # {LLM::Agent LLM::Agent}.
+  #
+  # It can be used to keep talking to an agent after it
+  # has been set up or has performed a task. This can be
+  # useful when you want to confirm the agent handled the
+  # task correctly, or for it to correct course after a
+  # mistake was made.
+  class Repl
+    require_relative "repl/window"
+    require_relative "repl/status"
+    require_relative "repl/transcript"
+    require_relative "repl/input"
+    require_relative "repl/stream"
+
+    ##
+    # @param [LLM::Agent] agent
+    # @return [LLM::Repl]
+    def initialize(agent)
+      @agent = agent
+      @provider = agent.llm.name
+      @status = Status.new(@provider)
+      @transcript = Transcript.new
+      @input = Input.new(@provider)
+      @window = Window.new(@status, @transcript, @input)
+      @stream = Stream.new(self)
+    end
+
+    ##
+    # @return [void]
+    def start
+      window.open do
+        loop do
+          window.redraw
+          text = input.readline(window)
+          break if text.nil?
+          next if text.empty?
+          status.text = "thinking"
+          write("user: #{text}\n")
+          window.redraw
+          write("agent: ")
+          agent.talk(text, stream:)
+          status.text = "idle"
+          write("\n\n")
+        end
+      end
+    end
+
+    ##
+    # @param [String] chars
+    # @return [void]
+    def write(chars)
+      transcript.write(chars)
+      window.redraw
+    end
+
+    ##
+    # @param [String] value
+    # @return [void]
+    def status=(value)
+      status.text = value
+      window.redraw
+    end
+
+    private
+
+    attr_reader :agent, :provider, :stream,
+                :status, :transcript, :input,
+                :window
+  end
+end

data/lib/llm/tools/chdir.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# frozen_string_literal
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::Chdir LLM::Tool::Chdir} class implements
+  # a tool that can change the current working directory.
+  class Chdir < self
+    name "chdir"
+    description "change the current working directory"
+    parameter :path, String, "the new working directory"
+    required %i[path]
+
+    ##
+    # @param [String] path
+    # @return [Hash]
+    def call(path:)
+      Dir.chdir(path)
+      {ok: true, cwd: path}
+    end
+  end
+end

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.2.0"
 end

data/lib/llm.rb

@@ -180,6 +180,15 @@ module LLM
     LLM::XAI.new(**)
   end
 
+  ##
+  # @param key (see LLM::Mistral#initialize)
+  # @param host (see LLM::Mistral#initialize)
+  # @return (see LLM::Mistral#initialize)
+  def mistral(**)
+    lock(:require) { require_relative "llm/providers/mistral" unless defined?(LLM::Mistral) }
+    LLM::Mistral.new(**)
+  end
+
   ##
   # @param key (see LLM::ZAI#initialize)
   # @param host (see LLM::ZAI#initialize)

data/llm.gemspec

@@ -5,7 +5,7 @@ require_relative "lib/llm/version"
 Gem::Specification.new do |spec|
   spec.name = "llm.rb"
   spec.version = LLM::VERSION
-  spec.authors = ["bsdrobert", "Antar Azri", "Rodrigo Serrano"]
+  spec.authors = ["robert", "Antar Azri", "Rodrigo Serrano"]
   spec.email = ["robert@r.uby.dev"]
 
   spec.summary = "Ruby's capable AI runtime"

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,10 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 12.0.0
+  version: 12.2.0
 platform: ruby
 authors:
-- bsdrobert
+- robert
 - Antar Azri
 - Rodrigo Serrano
 bindir: bin
@@ -293,6 +293,7 @@ files:
 - data/deepinfra.json
 - data/deepseek.json
 - data/google.json
+- data/mistral.json
 - data/openai.json
 - data/xai.json
 - data/zai.json
@@ -419,6 +420,9 @@ files:
 - lib/llm/providers/google/stream_parser.rb
 - lib/llm/providers/google/utils.rb
 - lib/llm/providers/llamacpp.rb
+- lib/llm/providers/mistral.rb
+- lib/llm/providers/mistral/request_adapter.rb
+- lib/llm/providers/mistral/request_adapter/completion.rb
 - lib/llm/providers/ollama.rb
 - lib/llm/providers/ollama/error_handler.rb
 - lib/llm/providers/ollama/models.rb
@@ -459,6 +463,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 +495,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