llm.rb 12.3.1 → 12.5.0

data/lib/llm/tools/which.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::Which LLM::Tool::Which} class implements
+  # a tool that locates an executable on the system PATH.
+  #
+  # This lets an agent discover whether a command it intends
+  # to use is actually available before attempting to run it.
+  # For example, checking `which("rg")` before a search, or
+  # `which("git")` before a version control operation, avoids
+  # a failed subprocess and lets the agent adapt its strategy
+  # when a tool is missing.
+  class Which < self
+    name "which"
+    description "locate an executable on the system PATH"
+    parameter :name, String, "the name of the executable to find"
+    required %i[name]
+
+    ##
+    # @param [String] name
+    # @return [Hash]
+    def call(name:)
+      path = paths.find { File.executable? File.join(_1, name) }
+      {ok: !!path, path:}
+    end
+
+    private
+
+    ##
+    # @return [Array<String>]
+    def paths
+      ENV["PATH"]
+        .to_s
+        .split(File::PATH_SEPARATOR)
+    end
+  end
+end

data/lib/llm/version.rb

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

data/resources/deepdive.md

@@ -92,9 +92,12 @@ features that didn't make it into the homepage documentation.
 <summary>REPL</summary>
 
 - [LLM::Agent](#llmagent)
+- [State](#state)
 - [Tools](#tools)
 - [Skills](#skills-1)
 - [Tracer](#tracer-1)
+- [Input](#input)
+- [Commands](#commands)
 </details>
 
 **Persistence**
@@ -560,7 +563,7 @@ class Stream < LLM::Stream
     puts content
   end
 
-  def on_tool_call(tool, error)
+  def on_tool_call(tool)
     # this callback can be used to either log a tool call,
     # or execute a tool call during a stream.
   end
@@ -894,6 +897,12 @@ you a way to confirm the work was successful, inspect
 anything that went wrong, and keep talking to the same
 agent while its state is still intact.
 
+The REPL is a curses-based TUI with a status line showing
+a context-usage bar and cost counter, a scrollable transcript
+that renders markdown, and a multi-line input area. The UI
+thread stays responsive while a second thread communicates
+with the model.
+
 #### LLM::Agent
 
 The [LLM::Agent#repl](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#repl-instance_method)
@@ -915,6 +924,20 @@ agent = LLM::Agent.new(llm)
 agent.repl
 ```
 
+#### State
+
+The `path:` option accepts a file path where runtime state
+is read from and written to. This lets you resume a
+conversation across REPL sessions. When the file does not
+exist the agent starts fresh; when it does, the agent
+restores its previous state.
+
+```ruby
+llm = LLM.deepseek(key: ENV["KEY"])
+agent = LLM::Agent.new(llm)
+agent.repl(path: "session.json")
+```
+
 #### Tools
 
 The read-eval-print loop accepts a `tools` option that lets
@@ -952,6 +975,49 @@ agent = LLM::Agent.new(llm, tracer: LLM.logger(llm, path: "agent.log"))
 agent.repl(tracer: true, tools: [Debugger])
 ```
 
+#### Input
+
+The input area supports several keyboard shortcuts:
+
+| Key | Action |
+|---|---|
+| `Enter` | Submit the current prompt |
+| `Ctrl+A` | Jump to the start of the line |
+| `Ctrl+E` | Jump to the end of the line |
+| `Ctrl+F` | Move the cursor forward |
+| `Ctrl+K` | Erase from cursor to the end of the line |
+| `Ctrl+Y` | Paste previously killed text |
+| `Ctrl+D` | Delete the character at the cursor |
+| `Left / Right` | Move the cursor |
+| `Up / Down` | Scroll the transcript |
+
+When characters arrive faster than a threshold the REPL
+detects that text is being pasted rather than typed. In
+paste mode pressing `Enter` inserts a newline instead of
+submitting, allowing multi-line prompts.
+
+#### Commands
+
+Commands are recognized by a `/` prefix on the input line.
+The built-in command is `/exit`, which leaves the REPL.
+The [`LLM::Repl::Command`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl/Command.html)
+class can be subclassed to add custom commands &ndash;
+any subclass that defines a `name`, `description`, and
+`call` method is automatically registered and available.
+
+```ruby
+class LLM::Repl::Command
+  class Clear < self
+    name "clear"
+    description "clears the transcript"
+
+    def call
+      system("clear") || system("cls")
+    end
+  end
+end
+```
+
 [Back to top](#table-of-contents)
 
 ## Images

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 12.3.1
+  version: 12.5.0
 platform: ruby
 authors:
 - robert
@@ -468,6 +468,9 @@ files:
 - lib/llm/registry.rb
 - lib/llm/repl.rb
 - lib/llm/repl/bar.rb
+- lib/llm/repl/command.rb
+- lib/llm/repl/commands/exit.rb
+- lib/llm/repl/commands/help.rb
 - lib/llm/repl/input.rb
 - lib/llm/repl/markdown.rb
 - lib/llm/repl/status.rb
@@ -505,12 +508,14 @@ files:
 - lib/llm/tools.rb
 - lib/llm/tools/chdir.rb
 - lib/llm/tools/git.rb
+- lib/llm/tools/ls.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/which.rb
 - lib/llm/tools/write_file.rb
 - lib/llm/tracer.rb
 - lib/llm/tracer/logger.rb