llm-shell 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 629a62d1b7f2fb7c4de9149c1af8e640c1ff08ccbef3a581d006cd99d331e4e2
-  data.tar.gz: 9e8808cba408a0474a938b7de8df00e1b72032635b00928bdd0a7a78f57d1521
+  metadata.gz: 033fc0fed08fe04d77063406e076a946ca986b700706f7a4e1ee9ed252fd4f48
+  data.tar.gz: 0e1fb76971b1012cf669cef11fc3ede3b1c8ed03e6c99324b296d686782c36de
 SHA512:
-  metadata.gz: 4552e7ef324acf1f800c42cffc5fe7812e581389f1a544a447c6963611011d66c4a3e19ec2fb1d5f142fbf822b8dd8a0264ed8de6a40427113b597541d099170
-  data.tar.gz: 8c453dfd38ff0c2f94707ab460a47afeba52efeccc808ff68c5a9c1007040855104e1954548222367459eca4a6245a174b78cd9f034baa8f301d2451a78b0288
+  metadata.gz: f047af335441b63debb894d1fee2b2eb0dd817fa56b180a6bf1e820d52deeb6093d26b02c98b2997aac80e67f0b2b74dc213f7e26a407399f4832840531c717e
+  data.tar.gz: f0a08f41e54e86e3c838418da505fca61a596f2a242847ccd1547468fecdef33d6674277c5ffa94b959bddce867686ef9e74b735660f68a097992f1ce777095e

data/README.md

@@ -1,7 +1,7 @@
 ## About
 
 llm-shell is an extensible, developer-oriented command-line
-utility that can interact with multiple Large Language Models
+console that can interact with multiple Large Language Models
 (LLMs). It serves as both a demo of the [llmrb/llm](https://github.com/llmrb/llm)
 library and a tool to help improve the library through real-world
 usage and feedback. Jump to the [Demos](#demos) section to see
@@ -9,12 +9,23 @@ it in action!
 
 ## Features
 
+#### General
+
 - 🌟 Unified interface for multiple Large Language Models (LLMs)
 - 🤝 Supports Gemini, OpenAI, Anthropic, LlamaCpp and Ollama
+
+#### Customize
+
 - 📤 Attach local files as conversation context
 - 🔧 Extend with your own functions and tool calls
-- 📝 Advanced Markdown formatting and output
+- 🚀 Extend with your own console commands
+
+#### Shell
+
+- 🤖 Builtin auto-complete powered by Readline
+- 🎨 Builtin syntax highlighting powered by Coderay
 - 📄 Deploys the less pager for long outputs
+- 📝 Advanced Markdown formatting and output
 
 ## Demos
 
@@ -37,22 +48,16 @@ it in action!
 
 #### Functions
 
+> For security and safety reasons, a user must confirm the execution of
+> all function calls before they happen and also add the function to
+> an allowlist before it will be loaded by llm-shell automatically
+> at boot time.
+
 The `~/.llm-shell/tools/` directory can contain one or more
 [llmrb/llm](https://github.com/llmrb/llm) functions that the
 LLM can call once you confirm you are okay with executing the
 code locally (along with any arguments it provides). See the
-earlier demo for an example.
-
-For security and safety reasons, a user must confirm the execution of
-all function calls before they happen and also add the function to
-an allowlist before it will be loaded by llm-shell automatically
-at boot time. See below for more details on how this can be done.
-
-An LLM function generally looks like this, and it can be dropped
-into the `~/.llm-shell/tools/` directory. This function is the one
-from the demo earlier, and I saved it as `~/.llm-shell/tools/system.rb`.
-The function's return value is relayed back to the LLM.
-
+earlier demo for an example:
 
 ```ruby
 LLM.function(:system) do |fn|
@@ -61,11 +66,31 @@ LLM.function(:system) do |fn|
     schema.object(command: schema.string.required)
   end
   fn.define do |params|
-    `#{params.command}`
+    ro, wo = IO.pipe
+    re, we = IO.pipe
+    Process.wait Process.spawn(params.command, out: wo, err: we)
+    [wo,we].each(&:close)
+    {stderr: re.read, stdout: ro.read}
   end
 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 –
+with one file per command. The commands are loaded at boot time. See the
+[import-file](lib/llm/shell/commands/import_file.rb)
+command for a realistic example:
+
+```ruby
+LLM.command "say-hello" do |cmd|
+  cmd.description "Say hello to somebody"
+  cmd.define do |name|
+    io.rewind.print "Hello #{name}!"
+  end
+end
+```
 ## Settings
 
 #### YAML
@@ -103,13 +128,13 @@ tools:
 
 ```bash
 Usage: llm-shell [OPTIONS]
-    -p, --provider NAME              Required. Options: gemini, openai, anthropic, or ollama.
-    -k, --key [KEY]                  Optional. Required by gemini, openai, and anthropic.
-    -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.
-    -t, --tools [TOOLS]              Optional. One or more tool names to load automatically.
+    -p, --provider NAME      Required. Options: gemini, openai, anthropic, ollama or llamacpp.
+    -k, --key [KEY]          Optional. Required by gemini, openai, and anthropic.
+    -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.
+    -t, --tools [TOOLS]      Optional. One or more tool names to load automatically.
 ```
 
 ## Install

data/lib/llm/shell/command/extension.rb

@@ -4,17 +4,19 @@ class LLM::Shell::Command
   module Extension
     ##
     # @example
-    #   LLM.command do |cmd|
-    #     cmd.name "hello"
+    #   LLM.command(:hello) do |cmd|
     #     cmd.define do |name|
     #       io.rewind.print("Hello #{name}")
     #     end
     #   end
+    # @param [String] name
+    #  The name of the command
     # @yieldparam [LLM::Shell::Command] cmd
     #  Yields an instance of LLM::Shell::Command
     # @return [void]
-    def command
+    def command(name)
       cmd = LLM::Shell::Command.new
+      cmd.name(name) if name
       yield cmd
       commands[cmd.name] = cmd
     end

data/lib/llm/shell/command.rb

@@ -4,10 +4,16 @@ class LLM::Shell
   class Command
     Context = Struct.new(:bot, :io)
 
+    ##
+    # Returns the underlying command object
+    # @return [Class, #call]
+    attr_reader :object
+
     ##
     # Set or get the command name
     # @param [String, nil] name
     #  The name of the command
+    # @return [String]
     def name(name = nil)
       if name
         @name = name
@@ -16,6 +22,19 @@ class LLM::Shell
       end
     end
 
+    ##
+    # Set or get the command description
+    # @param [String, nil] desc
+    #  The description of the command
+    # @return [String]
+    def description(desc = nil)
+      if desc
+        @description = desc
+      else
+        @description
+      end
+    end
+
     ##
     # Setup the command context
     # @return [void]
@@ -27,7 +46,7 @@ class LLM::Shell
     # Define the command
     # @return [void]
     def define(klass = nil, &b)
-      @runner = klass || b
+      @object = klass || b
     end
     alias_method :register, :define
 
@@ -37,10 +56,10 @@ class LLM::Shell
     def call(*argv)
       if @context.nil?
         raise "context has not been setup"
-      elsif Class === @runner
-        @runner.new(@context).call(*argv)
+      elsif Class === @object
+        @object.new(@context).call(*argv)
       else
-        @context.instance_exec(*argv, &@runner)
+        @context.instance_exec(*argv, &@object)
       end
     end
   end

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

@@ -2,6 +2,20 @@
 
 class LLM::Shell::Command
   class ImportFile
+    ##
+    # Completes a path with a wildcard.
+    # @param path [String]
+    #  The path to complete.
+    # @return [Array<String>]
+    #  Returns the completed path(s)
+    def self.complete(path)
+      Dir["#{path}*"]
+    end
+
+    ##
+    # @param [LLM::Shell::Context] context
+    #  The context of the command
+    # @return [LLM::Shell::Command::ImportFile]
     def initialize(context)
       @context = context
     end
@@ -24,8 +38,8 @@ class LLM::Shell::Command
     def io = @context.io
   end
 
-  LLM.command do |command|
-    command.name "import-file"
-    command.register ImportFile
+  LLM.command "import-file" do |cmd|
+    cmd.description "Share one or more files with the LLM"
+    cmd.register ImportFile
   end
 end

data/lib/llm/shell/completion.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+class LLM::Shell
+  class Completion
+    ##
+    # Returns a proc suitable for Readline completion.
+    # @return [Proc]
+    def self.to_proc
+      new.to_proc
+    end
+
+    ##
+    # @return [LLM::Shell::Completion]
+    def initialize
+      @commands = LLM.commands
+    end
+
+    ##
+    # Returns a proc suitable for Readline completion.
+    # @return [Proc]
+    def to_proc
+      method(:complete).to_proc
+    end
+
+    private
+
+    def complete(input)
+      words = Readline.line_buffer.split(" ")
+      command = words[0]
+      if commands[command]
+        object = commands[command].object
+        object.respond_to?(:complete) ? object.complete(input) : []
+      else
+        commands.keys.grep(/\A#{command}/)
+      end
+    end
+
+    attr_reader :commands
+  end
+end

data/lib/llm/shell/markdown.rb

@@ -3,6 +3,7 @@
 class LLM::Shell
   class Markdown
     require "kramdown"
+    require "coderay"
 
     ##
     # @param [String] text
@@ -37,7 +38,14 @@ class LLM::Shell
         Paint[node.children.map { visit(_1) }.join, :bold]
       when :br
         "\n"
-      when :text, :codespan
+      when :codespan, :codeblock
+        lines = node.value.each_line.to_a
+        lang  = lines[0].strip
+        code  = lines[1..].join
+        ["\n", Paint[">>> #{lang}", :blue, :bold],
+         "\n\n", coderay(code, lang),
+         "\n", Paint["<<< #{lang}", :blue, :bold]].join
+      when :text
         node.value
       else
         node.children.map { visit(_1) }.join
@@ -58,5 +66,12 @@ class LLM::Shell
         .gsub(/\A<think>[\n]*<\/think>(?:\n)/, "")
         .gsub(/\A\n{2,}/, "")
     end
+
+    def coderay(code, lang)
+      CodeRay.scan(code, lang).terminal
+    rescue ArgumentError
+      lang = "text"
+      retry
+    end
   end
 end

data/lib/llm/shell/repl.rb

@@ -21,6 +21,8 @@ class LLM::Shell
     # Performs initial setup
     # @return [void]
     def setup
+      LLM::Shell.commands.each { |file| require file }
+      Readline.completion_proc = Completion.to_proc
       chat options.prompt, role: options.default.role
       files.each { bot.chat ["--- START: #{_1} ---", File.read(_1), "--- END: #{_1} ---"].join("\n") }
       bot.messages.each(&:read!)

data/lib/llm/shell/version.rb

@@ -4,5 +4,5 @@ module LLM
 end unless defined?(LLM)
 
 class LLM::Shell
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/llm/shell.rb

@@ -16,6 +16,7 @@ class LLM::Shell
   require_relative "shell/options"
   require_relative "shell/repl"
   require_relative "shell/config"
+  require_relative "shell/completion"
   require_relative "shell/version"
 
   ##
@@ -34,6 +35,12 @@ class LLM::Shell
     Dir[File.join(home, "tools", "*.rb")]
   end
 
+  ##
+  # @return [Array<String>]
+  def self.commands
+    Dir[File.join(home, "commands", "*.rb")]
+  end
+
   ##
   # @param [Hash] options
   # @return [LLM::Shell]

data/libexec/llm-shell/shell

@@ -17,7 +17,7 @@ end
 def option_parser
   OptionParser.new do |o|
     o.banner = "Usage: llm-shell [OPTIONS]"
-    o.on("-p PROVIDER", "--provider NAME", "Required. Options: gemini, openai, anthropic, or ollama.", String)
+    o.on("-p PROVIDER", "--provider NAME", "Required. Options: gemini, openai, anthropic, ollama or llamacpp.", String)
     o.on("-k [KEY]", "--key [KEY]", "Optional. Required by gemini, openai, and anthropic.", String)
     o.on("-m [MODEL]", "--model [MODEL]", "Optional. The name of a model.", Array)
     o.on("-h [HOST]", "--host [HOST]", "Optional. Sometimes required by ollama.", String)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm-shell
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Antar Azri
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-09 00:00:00.000000000 Z
+date: 2025-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: llm.rb
@@ -53,6 +53,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: coderay
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
@@ -193,7 +207,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.8'
-description: llm-shell is an extensible, developer-oriented command-line utility that
+description: llm-shell is an extensible, developer-oriented command-line console that
   can interact with multiple Large Language Models (LLMs).
 email:
 - azantar@proton.me
@@ -211,6 +225,7 @@ files:
 - lib/llm/shell/command.rb
 - lib/llm/shell/command/extension.rb
 - lib/llm/shell/commands/import_file.rb
+- lib/llm/shell/completion.rb
 - lib/llm/shell/config.rb
 - lib/llm/shell/default.rb
 - lib/llm/shell/formatter.rb
@@ -244,6 +259,6 @@ requirements: []
 rubygems_version: 3.5.23
 signing_key:
 specification_version: 4
-summary: llm-shell is an extensible, developer-oriented command-line utility that
+summary: llm-shell is an extensible, developer-oriented command-line console that
   can interact with multiple Large Language Models (LLMs).
 test_files: []