llm-shell 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bad036ff98c154b18cabda0e2b598b40c242907e6eda28b6d2cfaa1fba66a265
-  data.tar.gz: 85d5fbc076495609562221a2296eabb06ec03c422ce1a2ea48661a3cf23213e9
+  metadata.gz: 2dfeeceab3ca11d0c832f8114b903d83791e237fabf4bb2dd0ce4d840be0e1ee
+  data.tar.gz: 119072ae06110415da13cee558ce8cdfe6613b4ad0198e91d207b91235824e5d
 SHA512:
-  metadata.gz: 182781650d0281008f8741ef389b1c7eaaf815191df2a3e8153415d6b65fdf64ce65d5d83ec67debfd05bde2f408f40c9ad79a1f21299dac699ba7c24f580f74
-  data.tar.gz: cebfa126c00d63d9927a9cfd6684f382016bd2c805aadf0da3ae5798d4bc136ccea3682af9c3c4e89236cfcbb7a837891b092a3744e537581eb676de9ecbaa9d
+  metadata.gz: 391dbf0bc2937545a475aaade248ebdfe495fd88c61ecd4691623220276f35dca1d438b55dbaf20826e30e554013493ca98044d40816396a45f9f3d5e89d678a
+  data.tar.gz: 63f8201b0aebd0e260788df46b90e96afdd4442f1b27bf9d4e025a6c6b6c6ca2d2338b6140fd69d616cc121cd8fa91bd1e71b3d9043e143af78a0494041ea563

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,44 +9,54 @@ it in action!
 
 ## Features
 
+#### General
+
 - 🌟 Unified interface for multiple Large Language Models (LLMs)
-- 🤝 Supports Gemini, OpenAI, Anthropic, and Ollama
+- 🤝 Supports Gemini, OpenAI, Anthropic, LlamaCpp and Ollama
+
+#### Customize
+
 - 📤 Attach local files as conversation context
 - 🔧 Extend with your own functions and tool calls
+- 🚀 Extend with your own console commands
+
+#### Shell
+
+- 🤖 Builtin auto-complete powered by Readline
+- 📄 Deploys the less pager for long outputs
 - 📝 Advanced Markdown formatting and output
 
 ## Demos
 
 <details>
-  <summary><b>1. Tool calls</b></summary>
-  <img src="share/llm-shell/examples/example2.gif/">
+  <summary><b>1. Tools: "system" function</b></summary>
+  <img src="share/llm-shell/examples/toolcalls.gif/">
 </details>
 
 <details>
-  <summary><b>2. File discussion</b></summary>
-  <img src="share/llm-shell/examples/example1.gif">
+  <summary><b>2. Files: import at boot time</b></summary>
+  <img src="share/llm-shell/examples/files-boottime.gif">
+</details>
+
+<details>
+<summary><b>3. Files: import at runtime</b></summary>
+  <img src="share/llm-shell/examples/files-runtime.gif">
 </details>
 
 ## Customization
 
 #### 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|
@@ -55,11 +65,30 @@ 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 &ndash;
+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.define do |name|
+    io.rewind.print "Hello #{name}!"
+  end
+end
+```
 ## Settings
 
 #### YAML
@@ -84,6 +113,9 @@ anthropic:
 ollama:
   host: localhost
   model: deepseek-coder:6.7b
+llamacpp:
+  host: localhost
+  model: qwen3
 tools:
   - system
 ```

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class LLM::Shell::Command
+  module Extension
+    ##
+    # @example
+    #   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(name)
+      cmd = LLM::Shell::Command.new
+      cmd.name(name) if name
+      yield cmd
+      commands[cmd.name] = cmd
+    end
+
+    ##
+    # @return [Hash<String, LLM::Shell::Command>]
+    def commands
+      @commands ||= {}
+    end
+  end
+  LLM.extend(Extension)
+end

data/lib/llm/shell/command.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+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
+    def name(name = nil)
+      if name
+        @name = name
+      else
+        @name
+      end
+    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
+    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
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+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
+
+    def initialize(context)
+      @context = context
+    end
+
+    def call(*files)
+      Dir[*files].each { import(_1) }
+    end
+
+    private
+
+    def import(file)
+      bot.chat [
+        "--- START: #{file} ---",
+        File.read(file),
+        "--- END: #{file} ---"
+      ].join("\n")
+    end
+
+    def bot = @context.bot
+    def io = @context.io
+  end
+
+  LLM.command "import-file" do |cmd|
+    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/default.rb

@@ -7,18 +7,7 @@ class LLM::Shell
     end
 
     def prompt
-      "You are a helpful assistant." \
-      "Answer the user's questions as best as you can." \
-      "The user's environment is a terminal." \
-      "Provide short and concise answers that are suitable for a terminal." \
-      "Do not provide long answers." \
-      "One or more files might be provided at the start of the conversation. " \
-      "The user might ask you about them, you should try to understand them and what they are. " \
-      "If you don't understand something, say so. " \
-      "Respond in markdown format." \
-      "Each file will be surrounded by the following markers: " \
-      "'# START: /path/to/file'" \
-      "'# END: /path/to/file'"
+      File.read File.join(SHAREDIR, "prompts", "default.txt")
     end
 
     def role
@@ -27,5 +16,8 @@ class LLM::Shell
       else :user
       end
     end
+
+    SHAREDIR = File.join(__dir__, "..", "..", "..", "share", "llm-shell")
+    private_constant :SHAREDIR
   end
 end

data/lib/llm/shell/formatter.rb

@@ -3,6 +3,7 @@
 class LLM::Shell
   class Formatter
     FormatError = Class.new(RuntimeError)
+    FILE_REGEXP = /\A--- START: (.+?) ---/
 
     def initialize(messages)
       @messages = messages.reject(&:tool_call?)
@@ -21,25 +22,26 @@ class LLM::Shell
     attr_reader :messages
 
     def format_user(messages)
-      messages.flat_map do |message|
+      messages.filter_map do |message|
         next unless message.user?
         next unless String === message.content
+        next unless message.content !~ FILE_REGEXP
         role  = Paint[message.role, :bold, :yellow]
         title = "#{role} says: "
         body  = wrap(message.tap(&:read!).content)
-        [title, render(body), ""].join("\n")
-      end.join
+        [title, "\n", render(body), "\n"].join
+      end.join("\n")
     end
 
     def format_assistant(messages)
-      messages.flat_map do |message|
+      messages.filter_map do |message|
         next unless message.assistant?
         next unless String === message.content
         role  = Paint[message.role, :bold, :green]
         title = "#{role} says: "
         body  = wrap(message.tap(&:read!).content)
-        [title, render(body)].join("\n")
-      end.join
+        [title, "\n", render(body)].join
+      end.join("\n")
     end
 
     def render(text)

data/lib/llm/shell/markdown.rb

@@ -55,6 +55,8 @@ class LLM::Shell
       text
         .gsub(/([^\n])\n(#+ )/, "\\1\n\n\\2")
         .gsub(/(#+ .+?)\n(?!\n)/, "\\1\n\n")
+        .gsub(/\A<think>[\n]*<\/think>(?:\n)/, "")
+        .gsub(/\A\n{2,}/, "")
     end
   end
 end

data/lib/llm/shell/options.rb

@@ -26,5 +26,6 @@ class LLM::Shell
     def llm = @options
     def chat = @chat_options
     def default = @default
+    def prompt = default.prompt
   end
 end

data/lib/llm/shell/repl.rb

@@ -14,15 +14,17 @@ class LLM::Shell
       @bot = bot
       @console = IO.console
       @options = options
-      @line = IO::Line.new($stdout)
+      @io = IO::Line.new($stdout)
     end
 
     ##
     # Performs initial setup
     # @return [void]
     def setup
-      chat options.default.prompt, role: options.default.role
-      files.each { bot.chat ["# START: #{_1}", File.read(_1), "# END: #{_1}"].join("\n") }
+      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!)
       clear_screen
     end
@@ -50,7 +52,7 @@ class LLM::Shell
     private
 
     attr_reader :bot, :console,
-                :line, :default,
+                :io, :default,
                 :options
 
     def formatter(messages) = Formatter.new(messages)
@@ -61,9 +63,17 @@ class LLM::Shell
 
     def read
       input = Readline.readline("llm> ", true) || throw(:exit, 0)
-      chat input.tap { clear_screen }
-      line.rewind.print(Paint["Thinking", :bold])
-      unread.tap { line.rewind }
+      words = input.split(" ")
+      if LLM.commands[words[0]]
+        cmd  = LLM.commands[words[0]]
+        argv = words[1..]
+        cmd.setup(bot, io)
+        cmd.call(*argv)
+      else
+        chat input.tap { clear_screen }
+        io.rewind.print(Paint["Thinking", :bold])
+        unread.tap { io.rewind }
+      end
     end
 
     def eval
@@ -74,18 +84,21 @@ class LLM::Shell
         print "Do you want to call it? "
         input = $stdin.gets.chomp.downcase
         puts
-        if %w(y yes yeah ok).include?(input)
+        if %w(y yes yep yeah ok).include?(input)
           bot.chat function.call
-          unread.tap { line.rewind }
+          unread.tap { io.rewind }
         else
-          print "Skipping function call", "\n"
+          bot.chat function.cancel
+          bot.chat "I decided to not run the function this time. Maybe next time."
         end
       end
     end
 
     def emit
-      print formatter(unread).format!(:user), "\n"
-      print formatter(unread).format!(:assistant), "\n"
+      IO.popen("less -FRX", "w") do
+        _1.write formatter(unread).format!(:user), "\n"
+        _1.write formatter(unread).format!(:assistant), "\n"
+      end
     end
 
     def chat(...)

data/lib/llm/shell/version.rb

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

data/lib/llm/shell.rb

@@ -8,14 +8,21 @@ require "paint"
 
 class LLM::Shell
   require_relative "../io/line"
+  require_relative "shell/command"
+  require_relative "shell/command/extension"
   require_relative "shell/markdown"
   require_relative "shell/formatter"
   require_relative "shell/default"
   require_relative "shell/options"
   require_relative "shell/repl"
   require_relative "shell/config"
+  require_relative "shell/completion"
   require_relative "shell/version"
 
+  ##
+  # Load all commands
+  Dir[File.join(__dir__, "shell", "commands", "*.rb")].each { require(_1) }
+
   ##
   # @return [String]
   def self.home
@@ -28,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]
@@ -55,7 +68,7 @@ class LLM::Shell
         print Paint["llm-shell: ", :green], "load #{name} tool", "\n"
         eval File.read(path), TOPLEVEL_BINDING, path, 1
       else
-        print Paint["llm-shell:: ", :yellow], "skip #{name} tool", "\n"
+        print Paint["llm-shell: ", :yellow], "skip #{name} tool", "\n"
       end
     end.grep(LLM::Function)
   end

data/lib/llm-shell.rb

@@ -1 +1,3 @@
+# frozen_string_literal: true
+
 require_relative "llm/shell"

data/share/llm-shell/prompts/default.txt

@@ -0,0 +1,27 @@
+/no_think
+
+## General
+
+You are a helpful assistant.
+Answer the user's questions as best as you can.
+
+The user's environment is a terminal.
+Provide short and concise answers that are suitable for a terminal.
+Do not provide long answers.
+
+## Files
+
+One or more files *MIGHT* be provided at the start of the conversation.
+One file will be provided per message, *IF* any files are provided at all.
+*IF* a file is provided, it will be in this format:
+
+--- START: /path/to/file ---
+<contents>
+--- END: /path/to/file ---
+
+Otherwise, no files will be provided and you shouldn't mention them.
+On receipt of one or more files, you will respond with: Got it. And with nothing else.
+
+## Format
+
+Respond in markdown.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm-shell
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Antar Azri
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-06 00:00:00.000000000 Z
+date: 2025-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: llm.rb
@@ -17,14 +17,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: paint
   requirement: !ruby/object:Gem::Requirement
@@ -193,7 +193,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
@@ -208,6 +208,10 @@ files:
 - lib/io/line.rb
 - lib/llm-shell.rb
 - lib/llm/shell.rb
+- 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
@@ -216,6 +220,7 @@ files:
 - lib/llm/shell/repl.rb
 - lib/llm/shell/version.rb
 - libexec/llm-shell/shell
+- share/llm-shell/prompts/default.txt
 homepage: https://github.com/llmrb/llm-shell
 licenses:
 - 0BSD
@@ -240,6 +245,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: []