llm-shell 0.9.2 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ec2b8025a69a836d633b92ae23c86e8e6d8c6ce42ed6d2da08194909ade1de8
-  data.tar.gz: 8a29bfddd6bfef7973483d8efca2e182d3aced3b82bf771beb73f673fc7861a2
+  metadata.gz: f967ca0697d19fdbdedad92516bc0ef92da47b29c4170791a8fac55fc5689ecb
+  data.tar.gz: e208bc99728251c53027f74cf7e77aa036ffd4cee0beab530685db262e0f229d
 SHA512:
-  metadata.gz: 6595412e81ab721f64ab2275ed087e8d01321a8d56c5d4b2566d31f1c0fa0a59c01ddd8981c6c4771c0896481586244bffa642ed8275416c8b2e93010a43956c
-  data.tar.gz: 3ad0f23e6fabc847984b750d86e4adcefb46f2f0748416bcabd91ad5664b4745acb04d80e4faf0e63cd7e2b3747d555e0fe921d961ef611f886a6ba0c34bfa0a
+  metadata.gz: 1210291c52e97bc62c00bbc7da2c13bd45c6837c2b2ffc2e6d6764c5599864b75f97e9e0a6ef8ff99999ae59432ce04c00a4f360f54685e453b6ab561448c6f3
+  data.tar.gz: 0306b40c3877bbf7f2203da41a82f20731c8cc4ca863e10582fe2658e6532eb17c5d2031c757b43b28270e61f49c3d9258cbc9e5b2b43c95104d0a896dd0a2f1

data/README.md

@@ -6,6 +6,13 @@ console that can interact with multiple Large Language Models
 library and a tool to help improve the library through real-world
 usage and feedback.
 
+## Demo
+
+<details>
+  <summary>Show</summary>
+  <img src="share/llm-shell/examples/demo.gif/">
+</details>
+
 ## Features
 
 #### General
@@ -26,44 +33,32 @@ usage and feedback.
 - 📄 Deploys the less pager for long outputs
 - 📝 Advanced Markdown formatting and output
 
-## Demo
-
-<details>
-  <summary>Reveal demo</summary>
-  <img src="share/llm-shell/examples/demo.gif/">
-</details>
-
-<details>
-  <summary>Reveal demo</summary>
-  <img src="share/llm-shell/examples/demo.png/">
-</details>
 
 ## Customization
 
-#### Functions
+#### Tools
 
 > For security and safety reasons, a user must confirm the execution of
 > all function calls before they happen
 
-llm-shell can be extended with your own functions (also known as tool calls).
-This can be done by creating a Ruby file in the `~/.llm-shell/functions/`
-directory &ndash; with one file per function.
 
-The functions are loaded at boot time. The functions are shared with
-the LLM and the LLM can request their execution. The LLM is also made
-aware of a function's return value after it has been called.
+Tools are loaded at boot time. Custom tools can be added to the
+`${HOME}/.local/share/llm-shell/tools/` directory. The tools are
+shared with the LLM and the LLM can request their execution.
+The LLM is also made aware of a tool's return value after
+it has been called.
 See the
-[functions/](lib/llm/shell/functions/)
+[tools/](lib/llm/shell/tools/)
 directory for more examples:
 
 
 ```ruby
-LLM.function(:system) do |fn|
-  fn.description "Run a shell command"
-  fn.params do |schema|
-    schema.object(command: schema.string.required)
-  end
-  fn.define do |command:|
+class System < LLM::Tool
+  name "system"
+  description "Run a system command"
+  param :command, String, "The command to execute", required: true
+
+  def call(command:)
     ro, wo = IO.pipe
     re, we = IO.pipe
     Process.wait Process.spawn(command, out: wo, err: we)
@@ -75,18 +70,20 @@ end
 
 #### Commands
 
-llm-shell can be extended with your own console commands. This can be
-done by creating a Ruby file in the `~/.llm-shell/commands/` directory &ndash;
-with one file per command. The commands are loaded at boot time.
+llm-shell can be extended with your own console commands that take
+precendence over messages sent to the LLM. Custom commands can be
+added to the `${HOME}/.local/share/llm-shell/commands/` directory.
 See the
 [commands/](lib/llm/shell/commands/)
 directory for more examples:
 
 ```ruby
-LLM.command "say-hello" do |cmd|
-  cmd.description "Say hello to somebody"
-  cmd.define do |name|
-    io.rewind.print "Hello #{name}!"
+class SayHello < LLM::Command
+  name "say-hello"
+  description "Say hello to somebody"
+
+  def call(name)
+    io.rewind.print "Hello, #{name}!"
   end
 end
 ```
@@ -97,47 +94,46 @@ end
 > otherwise you might see unexpected results because llm-shell assumes the LLM
 > will emit markdown.
 
-The first message in a conversation is sometimes known as a "system prompt",
-and it defines the expectations and rules to be followed by an LLM throughout
-a conversation. The default prompt used by llm-shell can be found at
-[default.txt](share/llm-shell/prompts/default.txt).
-
-The prompt can be changed by adding a file to the `~/.llm-shell/prompts/` directory,
-and then choosing it at boot time with the `-r PROMPT`, `--prompt PROMPT` options.
-Generally you probably want to fork [default.txt](share/llm-shell/prompts/default.txt)
+The prompt can be changed by adding a file to the `${HOME}/.local/share/llm-shell/prompts/`
+directory, and then choosing it at boot time with the `-r PROMPT`, `--prompt PROMPT`
+options. Generally you probably want to fork [default.txt](share/llm-shell/prompts/default.txt)
 to conserve the original prompt rules around markdown and files, then modify it to
 suit your own needs and preferences.
 
 ## Settings
 
-#### YAML
 
 The console client can be configured at the command line through option switches,
-or through a YAML file. The YAML file can contain the same options that could be
+or through a TOML file. The TOML file can contain the same options that could be
 specified at the command line. For cloud providers the key option is the only
-required parameter, everything else has defaults. The YAML file is read from the
-path `${HOME}/.llm-shell/config.yml` and it has the following format:
-
-```yaml
-# ~/.config/llm-shell.yml
-openai:
-  key: YOURKEY
-gemini:
-  key: YOURKEY
-anthropic:
-  key: YOURKEY
-xai:
-  key: YOURKEY
-deepseek:
-  key: YOURKEY
-ollama:
-  host: localhost
-  model: deepseek-coder:6.7b
-llamacpp:
-  host: localhost
-  model: qwen3
-tools:
-  - system
+required parameter, everything else has defaults. The TOML file is read from the
+path `${HOME}/.llm-shell/config.toml` and it has the following format:
+
+```toml
+# ~/.config/llm-shell.toml
+
+[openai]
+key = "YOURKEY"
+
+[gemini]
+key = "YOURKEY"
+
+[anthropic]
+key = "YOURKEY"
+
+[xai]
+key = "YOURKEY"
+
+[deepseek]
+key = "YOURKEY"
+
+[ollama]
+host = "localhost"
+model = "deepseek-coder:6.7b"
+
+[llamacpp]
+host = "localhost"
+model = "qwen3"
 ```
 
 ## Usage
@@ -151,7 +147,6 @@ Usage: llm-shell [OPTIONS]
     -m, --model [MODEL]      Optional. The name of a model.
     -h, --host [HOST]        Optional. Sometimes required by ollama.
     -o, --port [PORT]        Optional. Sometimes required by ollama.
-    -f, --files [GLOB]       Optional. Glob pattern(s) separated by a comma.
     -r, --prompt [PROMPT]    Optional. The prompt to use.
     -v, --version            Optional. Print the version and exit
 ```

data/lib/llm/shell/command.rb

@@ -2,27 +2,35 @@
 
 class LLM::Shell
   class Command
-    require_relative "commands/utils"
+    ##
+    # Returns true for builtin commands
+    # @return [Boolean]
+    def self.builtin?
+      path, _ = instance_method(:call).source_location
+      path&.include?(LLM::Shell.root)
+    end
 
     ##
-    # @api private
-    class Context < Struct.new(:bot, :io)
-      def pager(...)
-        LLM::Shell.pager(...)
-      end
+    # Always returns true
+    # @return [Boolean]
+    def self.enabled?
+      true
     end
 
     ##
-    # Returns the underlying command object
-    # @return [Class, #call]
-    attr_reader :object
+    # @param [Class] klass
+    #  A subclass
+    # @return [void]
+    def self.inherited(klass)
+      LLM::Shell.commands << klass
+    end
 
     ##
     # Set or get the command name
     # @param [String, nil] name
     #  The name of the command
     # @return [String]
-    def name(name = nil)
+    def self.name(name = nil)
       if name
         @name = name
       else
@@ -35,7 +43,7 @@ class LLM::Shell
     # @param [String, nil] desc
     #  The description of the command
     # @return [String]
-    def description(desc = nil)
+    def self.description(desc = nil)
       if desc
         @description = desc
       else
@@ -44,45 +52,37 @@ class LLM::Shell
     end
 
     ##
-    # Setup the command context
-    # @return [void]
-    def setup(bot, io)
-      @context = Context.new(bot, io)
-    end
-
-    ##
-    # Define the command
-    # @return [void]
-    def define(klass = nil, &b)
-      @object = klass || b
+    # @param [LLM::Bot] bot
+    #  An instance of {LLM::Bot LLM::Bot}
+    # @param [IO::Line] io
+    #  An IO object
+    def initialize(bot, io)
+      @bot = bot
+      @io = io
     end
-    alias_method :register, :define
 
     ##
     # Call the command
     # @reurn [void]
     def call(*argv)
-      if @context.nil?
-        raise "context has not been setup"
-      elsif Class === @object
-        @object.new(@context).call(*argv)
-      else
-        @context.instance_exec(*argv, &@object)
-      end
+      raise NotImplementedError
     end
 
-    ##
-    # @return [Boolean]
-    #  Returns true if this is a builtin command
-    def builtin?
-      @builtin
+    private
+
+    attr_reader :bot, :io
+
+    def import(file)
+      return unless File.file?(file)
+      bot.chat [
+        "<file path=\"#{file}\">",
+        File.read(file),
+        "</file>"
+      ].join("\n")
     end
 
-    ##
-    # Mark this command as builtin command
-    # @return [void]
-    def builtin!
-      @builtin = true
+    def pager(...)
+      LLM::Shell.pager(...)
     end
   end
 end

data/lib/llm/shell/commands/clear_screen.rb

@@ -1,17 +1,9 @@
 # frozen_string_literal: true
 
-class LLM::Shell::Command
-  class ClearScreen
-    require_relative "utils"
-    include Utils
-
-    ##
-    # @param [LLM::Shell::Context] context
-    #  The context of the command
-    # @return [LLM::Shell::Command::ClearScreen]
-    def initialize(context)
-      @context = context
-    end
+class LLM::Shell
+  class Command::ClearScreen < Command
+    name "clear-screen"
+    description "Clears the screen"
 
     ##
     # Clears the screen
@@ -22,11 +14,5 @@ class LLM::Shell::Command
 
     def console = IO.console
     def clear_screen = console.clear_screen
-
-    LLM.command "clear-screen" do |cmd|
-      cmd.description "Clear the screen"
-      cmd.register(self)
-      cmd.builtin!
-    end
   end
 end

data/lib/llm/shell/commands/debug_mode.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class LLM::Shell
+  class Command::DebugMode < Command
+    name 'debug-mode'
+    description 'Enter into debug mode'
+
+    def call
+      binding.irb
+    end
+  end
+end

data/lib/llm/shell/commands/dir_import.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-class LLM::Shell::Command
-  class DirImport
-    require_relative "utils"
-    include Utils
+class LLM::Shell
+  class Command::DirImport < Command
+    name "dir-import"
+    description "Import the contents of a directory"
 
     ##
     # Completes a path with a wildcard.
@@ -15,14 +15,6 @@ class LLM::Shell::Command
       Dir["#{path}*"]
     end
 
-    ##
-    # @param [LLM::Shell::Context] context
-    #  The context of the command
-    # @return [LLM::Shell::Command::DirImport]
-    def initialize(context)
-      @context = context
-    end
-
     ##
     # Recursively imports all files in a directory.
     # @return [void]
@@ -37,13 +29,5 @@ class LLM::Shell::Command
         end
       end
     end
-
-    private
-
-    LLM.command "dir-import" do |cmd|
-      cmd.description "Share a directory with the LLM"
-      cmd.register(self)
-      cmd.builtin!
-    end
   end
 end

data/lib/llm/shell/commands/disable_tool.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class LLM::Shell
+  class Command::DisableTool < Command
+    Error = Class.new(RuntimeError)
+
+    name "disable-tool"
+    description "Disable a tool"
+
+    ##
+    # Completes a tool name.
+    # @param name [String]
+    #  The tool name to complete.
+    # @return [Array<String>]
+    #  Returns the completed tool name(s)
+    def self.complete(name)
+      LLM::Shell.tools.map(&:name).select { _1.start_with?(name) }
+    end
+
+    ##
+    # Disables the given tool.
+    # @return [void]
+    def call(name)
+      tool = LLM::Shell.tools.find { _1.name == name }
+      if tool
+        tool.disable!
+        io.rewind.print("tool disabled").end
+      else
+        raise Error, "unknown tool: #{name}"
+      end
+    end
+  end
+end

data/lib/llm/shell/commands/enable_tool.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class LLM::Shell
+  class Command::EnableTool < Command
+    Error = Class.new(RuntimeError)
+
+    name "enable-tool"
+    description "Enable a tool"
+
+    ##
+    # Completes a tool name.
+    # @param name [String]
+    #  The tool name to complete.
+    # @return [Array<String>]
+    #  Returns the completed tool name(s)
+    def self.complete(name)
+      LLM::Shell.tools.map(&:name).select { _1.start_with?(name) }
+    end
+
+    ##
+    # Enables the given tool.
+    # @return [void]
+    def call(name)
+      tool = LLM::Shell.tools.find { _1.name == name }
+      if tool
+        tool.enable!
+        io.rewind.print("tool enabled").end
+      else
+        raise Error, "unknown tool: #{name}"
+      end
+    end
+  end
+end

data/lib/llm/shell/commands/file_import.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-class LLM::Shell::Command
-  class FileImport
-    require_relative "utils"
-    include Utils
+class LLM::Shell
+  class Command::FileImport < Command
+    name "file-import"
+    description "Import a file"
 
     ##
     # Completes a path with a wildcard.
@@ -15,27 +15,11 @@ class LLM::Shell::Command
       Dir["#{path}*"]
     end
 
-    ##
-    # @param [LLM::Shell::Context] context
-    #  The context of the command
-    # @return [LLM::Shell::Command::FileImport]
-    def initialize(context)
-      @context = context
-    end
-
     ##
     # Imports one or more globbed files.
     # @return [void]
     def call(*files)
       Dir[*files].each { import(_1) }
     end
-
-    private
-
-    LLM.command "file-import" do |cmd|
-      cmd.description "Share a file with the LLM"
-      cmd.register(self)
-      cmd.builtin!
-    end
   end
 end

data/lib/llm/shell/commands/help.rb

@@ -1,24 +1,18 @@
 # frozen_string_literal: true
 
-class LLM::Shell::Command
-  class Help
-    require_relative "utils"
-    include Utils
-
-    ##
-    # @param [LLM::Shell::Context] context
-    #  The context of the command
-    # @return [LLM::Shell::Command::Help]
-    def initialize(context)
-      @context = context
-    end
+class LLM::Shell
+  class Command::Help < Command
+    name "help"
+    description "Show help"
 
     ##
     # Prints help
     # @return [void]
     def call
       pager do |io|
+        io.print(Paint["Help", :bold, :underline], "\n\n")
         render_commands(io)
+        io.print("\n")
         render_functions(io)
       end
     end
@@ -27,40 +21,33 @@ class LLM::Shell::Command
 
     def render_commands(io)
       io.print(Paint["Commands", :bold, :underline], "\n\n")
-      io.print(Paint["Builtin", :bold], "\n\n")
-      render_group commands.select(&:builtin?), io, :cyan
-      io.print(Paint["User", :bold], "\n\n")
-      render_group commands.reject(&:builtin?), io, :cyan
+      render_group(io, "Builtin", commands.select(&:builtin?), :cyan)
+      io.print("\n")
+      render_group(io, "User", commands.reject(&:builtin?), :cyan)
     end
 
     def render_functions(io)
       io.print(Paint["Functions", :bold, :underline], "\n\n")
-      io.print(Paint["Builtin", :bold], "\n\n")
-      render_group functions.select(&:builtin?), io, :blue
-      io.print(Paint["User", :bold], "\n\n")
-      render_group functions.reject(&:builtin?), io, :blue
+      render_group(io, "Builtin (Enabled)", functions.select { |f|  f.builtin? && f.enabled? }, :blue)
+      render_group(io, "Builtin (Disabled)", functions.select { |f|  f.builtin? && !f.enabled? }, :blue)
+      io.print("\n")
+      render_group(io, "User (Enabled)", functions.select { |f| !f.builtin? && f.enabled? }, :blue)
+      render_group(io, "User (Disabled)", functions.select { |f| !f.builtin? && !f.enabled? }, :blue)
     end
 
-    def render_group(commands, io, bgcolor)
-      if commands.empty?
-        io.print(Paint["None available", :yellow], "\n\n")
+    def render_group(io, title, items, color)
+      io.print(Paint[title, :bold], "\n")
+      if items.empty?
+        io.print(Paint["  None available", :yellow], "\n")
       else
-        commands.each.with_index(1) do |command, index|
-          io.print(name(command, index, bgcolor), "\n")
-          io.print(desc(command), "\n\n")
+        items.each do |item|
+          status = item.enabled? ? Paint["enabled", :green] : Paint["disabled", :red]
+          io.print("  ", Paint[item.name, color, :bold], " - ", item.description || "No description", " (", status, ")\n")
         end
       end
     end
 
-    def commands = LLM.commands.values.sort_by(&:name)
-    def functions = LLM.functions.values.sort_by(&:name)
-    def name(command, index, bgcolor) = [Paint[" #{index} ", :white, bgcolor, :bold], " ", Paint[command.name, :bold]].join
-    def desc(command) = command.description || "No description"
-
-    LLM.command "help" do |cmd|
-      cmd.description "Show the help menu"
-      cmd.register(self)
-      cmd.builtin!
-    end
+    def commands = LLM::Shell.commands.sort_by(&:name)
+    def functions = LLM::Shell.tools.sort_by(&:name)
   end
 end

data/lib/llm/shell/commands/show_chat.rb

@@ -1,17 +1,9 @@
 # frozen_string_literal: true
 
-class LLM::Shell::Command
-  class ShowChat
-    require_relative "utils"
-    include Utils
-
-    ##
-    # @param [LLM::Shell::Context] context
-    #  The context of the command
-    # @return [LLM::Shell::Command::ShowChat]
-    def initialize(context)
-      @context = context
-    end
+class LLM::Shell
+  class Command::ShowChat < Command
+    name "show-chat"
+    description "Show the chat"
 
     ##
     # Emits the full chat history to standard output
@@ -26,7 +18,6 @@ class LLM::Shell::Command
     def emit
       pager do |io|
         messages.each.with_index do |message, index|
-          next if index <= 1
           io << render(message) << "\n"
         end
       end
@@ -36,11 +27,5 @@ class LLM::Shell::Command
     def clear_screen = console.clear_screen
     def messages = bot.messages
     def render(message) = LLM::Shell::Renderer.new(message).render
-
-    LLM.command "show-chat" do |cmd|
-      cmd.description "Show the chat"
-      cmd.register(self)
-      cmd.builtin!
-    end
   end
 end