llm.rb 13.0.0 → 13.1.0

data/bin/llm.rb

@@ -0,0 +1,124 @@
+#!/usr/bin/env ruby
+
+require "llm"
+require "fileutils"
+
+##
+# utils
+
+def keys
+  @keys ||= Dir[File.join(__dir__, "..", "lib", "llm", "providers", "*")]
+    .select { File.file?(_1) }
+    .map { File.basename(_1, ".rb") }
+    .sort_by { _1 == "deepseek" ? 0 : 1 }
+    .map { "#{_1.upcase}_API_KEY" } - ["BEDROCK_API_KEY"]
+end
+
+def help
+  prog = File.basename($PROGRAM_NAME)
+  warn ""
+  warn "Usage: #{prog} [options]"
+  warn ""
+  warn "Options:"
+  warn "  -p PROVIDER    Choose a provider"
+  warn "  -t             Temporary session that doesn't persist to disk"
+  warn "  -h             Show this help"
+  warn ""
+  warn "Examples:"
+  warn "  #{prog}                     # auto-detect provider from $PROVIDER_API_KEY"
+  warn "  #{prog} -p openai           # use OpenAI"
+  warn "  #{prog} -h                  # this help"
+  warn ""
+end
+
+def loaderror(ex)
+  gem, = ex.message.split(" is an optional runtime dependency")
+  warn ""
+  warn "  ── llm.rb ──────────────────────────────────────────────"
+  warn ""
+  warn "  ✖  Missing dependency: #{gem}"
+  warn ""
+  warn "     The repl needs this gem, but it's not installed."
+  warn ""
+  warn "     Fix:  gem install #{gem}"
+  warn "     Or:   bundle add #{gem}"
+  warn ""
+  warn "     Tip:  If you don't need the repl, you can use the"
+  warn "           library directly with:  require \"llm\""
+  warn ""
+  warn "  ───────────────────────────────────────────────────────"
+  warn ""
+end
+
+##
+# main
+
+def main(argv)
+  ##
+  # Make sure the dependencies are satisified first
+  begin
+    require "llm/tools"
+    require "llm/repl"
+  rescue LLM::LoadError => ex
+    loaderror(ex)
+    exit 1
+  end
+
+  ##
+  # C-Style option parser
+  # No external dep
+  while option = argv.shift
+    case option
+    when '-h'
+      help
+      exit 0
+    when '-t'
+      temp = true
+    when '-p'
+      provider = argv.shift
+    else
+      warn "llm.rb: unknown option #{option}"
+    end
+  end
+
+  ##
+  # Setup the home directory
+  # But only if the `-t` switch has not been provided
+  if temp.nil?
+    home = File.join(Dir.home, ".llm.rb")
+    FileUtils.mkdir_p(File.join(home, Dir.getwd))
+    session = File.join(home, Dir.getwd, "session.json")
+  end
+
+  ##
+  # No provider has been given.
+  # Try to infer one.
+  if provider.nil?
+    key = keys.find { ENV[_1] }
+    if key.nil?
+      warn "llm.rb: provide a provider with the -p switch"
+      exit 1
+    else
+      provider, = key.split("_")
+    end
+  end
+
+  ##
+  # We're ready to start the REPL
+  # This should always succeed unless -p gave garbage
+  provider = provider.downcase
+  if LLM.respond_to?(provider)
+    key ||= "#{provider.upcase}_API_KEY"
+    if ENV[key].nil? || ENV[key].to_s.empty?
+      warn "llm.rb: set #{key} to use #{provider}"
+      exit 1
+    end
+    llm = LLM.method(provider).call(key: ENV[key])
+    agent = LLM::Agent.new(llm, path: temp ? nil : session, tools: LLM::Tool.subclasses)
+    agent.repl
+  else
+    warn "llm.rb: #{provider} was not recognized"
+    exit 1
+  end
+end
+main(ARGV)

data/lib/llm/agent.rb

@@ -11,8 +11,8 @@ module LLM
   # {LLM::Context LLM::Context}: message history, usage, persistence,
   # streaming parameters, and provider-backed requests still flow through
   # an underlying context. The defining behavior of an agent is that it
-  # automatically resolves pending tool calls for you during `talk` and
-  # `respond`, instead of leaving tool loops to the caller.
+  # automatically resolves pending tool calls for you during `talk`,
+  # instead of leaving tool loops to the caller.
   #
   # **Notes:**
   # * Instructions are injected once unless a system message is already present.
@@ -24,7 +24,7 @@ module LLM
   #   advisory tool errors back through the model and keeps the loop in-band.
   #   Set `tool_attempts: nil` to disable that advisory behavior.
   # * Tool loop execution can be configured with `concurrency :sequential`,
-  #   `:thread`, `:async`, `:fiber`, or `:ractor`.
+  #   `:thread`, `:async`, `:fiber`, `:fork`, or `:ractor`.
   #
   # @example Subclass with defaults
   #   class SystemAdmin < LLM::Agent
@@ -52,6 +52,16 @@ module LLM
     UNDEFINED = Object.new
     private_constant :UNDEFINED
 
+    ##
+    # @api private
+    CASE_PATTERN = /(?<=[a-z])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/
+    private_constant :CASE_PATTERN
+
+    ##
+    # @api private
+    File = ::File
+    private_constant :File
+
     ##
     # Returns a provider
     # @return [LLM::Provider]
@@ -96,18 +106,44 @@ module LLM
 
     ##
     # Set or get an agent's name
+    # @note
+    #  This method serves as a self-documenting string
+    #  and it is used by {LLM::Repl LLM::Repl}. It is
+    #  optional but recommended.
     # @param [String] name
     #  The agent name
     # @return [String]
     #  Return's the agents name
     def self.name(name = UNDEFINED, &block)
       if name.equal?(UNDEFINED)
-        @name || self.to_s.gsub(/(.)([A-Z])/, '\\1-\\2').downcase
+        if @name.nil?
+          name  = to_s.split("::").last
+          @name = name.gsub(CASE_PATTERN, "-").downcase
+        else
+          @name
+        end
       else
         @name = block || name
       end
     end
 
+    ##
+    # Set or get an agent's description
+    # @note
+    #  This method serves as a self-documenting string.
+    #  It is optional but recommended.
+    # @param [String] desc
+    #  The agent's description
+    # @return [String, nil]
+    #  Returns the agent's description
+    def self.description(desc = UNDEFINED, &block)
+      if desc.equal?(UNDEFINED)
+        @desc
+      else
+        @desc = block || desc
+      end
+    end
+
     ##
     # Set or get the default model
     # @param [String, nil] model
@@ -261,6 +297,20 @@ module LLM
       end
     end
 
+    ##
+    # Set the file path where an agent's memory
+    # can be restored from, and written to.
+    # @param [String] path
+    #  The path to a file
+    # @return [String, nil]
+    def self.path(path = UNDEFINED, &block)
+      if path.equal?(UNDEFINED)
+        @path
+      else
+        @path = path || block
+      end
+    end
+
     ##
     # @param [LLM::Provider] llm
     #  A provider
@@ -277,8 +327,8 @@ module LLM
     # @option params [Symbol, Array<Symbol>, nil] :concurrency Defaults to the agent class concurrency
     def initialize(llm, params = {})
       @llm = llm
-      fields = %i[name model skills schema tracer stream tools concurrency instructions confirm]
-      fields_ivar = %i[name tracer concurrency instructions confirm]
+      fields = %i[name description path model skills schema tracer stream tools concurrency instructions confirm]
+      fields_ivar = %i[name description path tracer concurrency instructions confirm]
       fields.each do |field|
         resolvable = params.key?(field) ? params.delete(field) : self.class.public_send(field)
         resolve_symbol = !%i[concurrency].include?(field)
@@ -293,6 +343,7 @@ module LLM
         end
       end
       @ctx = LLM::Context.new(llm, {guard: true}.merge(params))
+      @path and File.readable?(@path) ? @ctx.restore(path:) : nil
     end
 
     ##
@@ -302,6 +353,21 @@ module LLM
       @name
     end
 
+    ##
+    # Returns a file path where an agent's memory is
+    # restored from, and written to after each turn.
+    # @return [String, nil]
+    def path
+      @path
+    end
+
+    ##
+    # Returns the agent's description
+    # @return [String, nil]
+    def description
+      @description
+    end
+
     ##
     # Maintain a conversation via the chat completions API.
     # This method immediately sends a request to the LLM and returns the response.
@@ -319,13 +385,17 @@ module LLM
     #   response = agent.talk("Hello, what is your name?")
     #   puts response.choices[0].content
     def talk(prompt, params = {})
-      run_loop(prompt, params, :talk)
+      res = run_loop(prompt, params, :talk)
+      path ? @ctx.save(path:) : nil
+      res
     end
 
     ##
     # @see LLM::Context#ask
     def ask(prompt, params = {})
-      run_loop(prompt, params, :ask)
+      res = run_loop(prompt, params, :ask)
+      path ? @ctx.save(path:) : nil
+      res
     end
 
     ##

data/lib/llm/function/array.rb

@@ -3,7 +3,7 @@
 class LLM::Function
   ##
   # The {LLM::Function::Array} module extends the array
-  # returned by {LLM::Context#functions} with methods
+  # returned by {LLM::Context#pending_functions} with methods
   # that can call all pending functions sequentially or
   # concurrently. The return values can be reported back
   # to the LLM on the next turn.
@@ -57,9 +57,9 @@ class LLM::Function
     #
     # @param [Symbol] strategy
     #   Controls concurrency strategy:
-    #   - `:call`: Call each function sequentially through a call group
+    #   - `:sequential`: Call functions sequentially without spawning
     #   - `:thread`: Use threads
-    #   - `:task`: Use async tasks (requires async gem)
+    #   - `:async`: Use async tasks (requires async gem)
     #   - `:fiber`: Use scheduler-backed fibers (requires Fiber.scheduler)
     #   - `:fork`: Use forked child processes
     #   - `:ractor`: Use Ruby ractors (class-based tools only; MCP tools are not supported)

data/lib/llm/function.rb

@@ -204,7 +204,7 @@ class LLM::Function
         @params = params
       end
     else
-      @params
+      @params || LLM::Schema::Object.new({})
     end
   end
 
@@ -227,7 +227,6 @@ class LLM::Function
     @called = true
   end
 
-
   ##
   # Returns a function as a {LLM::Function::Task LLM::Function::Task}.
   #

data/lib/llm/providers/anthropic.rb

@@ -88,7 +88,7 @@ module LLM
       {
         name: fn.name,
         description: fn.description,
-        input_schema: fn.params || {type: "object", properties: {}}
+        input_schema: fn.params.to_h
       }.compact
     end
 

data/lib/llm/providers/bedrock/request_adapter.rb

@@ -74,7 +74,7 @@ class LLM::Bedrock
           name: function.name,
           description: function.description,
           inputSchema: {
-            json: function.params || default_input_schema
+            json: function.params.to_h
           }
         }
       }

data/lib/llm/providers/mistral.rb

@@ -123,7 +123,7 @@ module LLM
     # @param [LLM::Function] fn
     # @return [Hash]
     def adapt_function(fn)
-      params = fn.params || {type: "object", properties: {}}
+      params = fn.params.to_h
       {
         type: "function",
         function: {name: fn.name, description: fn.description, parameters: params}

data/lib/llm/providers/ollama.rb

@@ -102,7 +102,7 @@ module LLM
     # @param [LLM::Function] fn
     # @return [Hash]
     def adapt_function(fn)
-      params = fn.params || {type: "object", properties: {}}
+      params = fn.params.to_h
       {
         type: "function", name: fn.name,
         function: {name: fn.name, description: fn.description, parameters: params}

data/lib/llm/providers/openai/responses.rb

@@ -92,7 +92,7 @@ class LLM::OpenAI
     def adapt_function(fn)
       {
         type: "function", name: fn.name, description: fn.description,
-        parameters: (fn.params || {type: "object", properties: {}}).to_h.merge(additionalProperties: false), strict: false
+        parameters: fn.params.to_h.merge(additionalProperties: false), strict: false
       }.compact
     end
 

data/lib/llm/providers/openai.rb

@@ -156,7 +156,7 @@ module LLM
     # @param [LLM::Function] fn
     # @return [Hash]
     def adapt_function(fn)
-      params = fn.params || {type: "object", properties: {}}
+      params = fn.params.to_h
       {
         type: "function", name: fn.name,
         function: {name: fn.name, description: fn.description, parameters: params}

data/lib/llm/repl/{transcript.rb → buffer.rb}

@@ -14,12 +14,13 @@ class LLM::Repl
   # It also maintains a cursor that tracks the active row
   # by its index number. The streaming path reuses a single
   # row by overwriting its contents repeatedly.
-  class Transcript
-    WIDTH = 80
-
+  class Buffer
     ##
-    # @return [LLM::Repl::Transcript]
-    def initialize
+    # @param [LLM::Repl] repl
+    #  An instance of {LLM::Repl LLM::Repl}.
+    # @return [LLM::Repl::Buffer]
+    def initialize(repl)
+      @repl = repl
       @rows = [[]]
       @cursor = nil
       @snapshot = nil
@@ -27,37 +28,45 @@ class LLM::Repl
     end
 
     ##
-    # @param [String] chars
+    # @param [String, Array] chars
     # @param [Object] attrs
     # @param [Symbol] method
     # @return [void]
     def write(chars, attrs = nil, method: :append)
-      chunks = [{text: chars.to_s, attrs:}.compact]
+      case chars
+      when Array then chunks = chars
+      else chunks = [Node.new(chars.to_s, attrs)]
+      end
       self.method(method).call(chunks)
     end
 
     ##
-    # Appends Markdown to the transcript.
-    # @param [String] chars
+    # @param [String] user
+    # @param [String, Array] content
     # @param [Symbol] method
     # @return [void]
-    def markdown(chars, method: :append)
-      chunks = LLM::Repl::Markdown.new(chars, WIDTH).ast
-      self.method(method).call(chunks)
+    def write_message(user, content, method: :append)
+      chunks = [Node.new("#{user}: ", Curses::A_BOLD)]
+      case content
+      when Array then chunks.concat(content)
+      else chunks.push(Node.new(content))
+      end
+      chunks.push(Node.new("\n"))
+      write(chunks, method:)
     end
 
     ##
-    # Start the transcript.
+    # Open the buffer.
     # @return [void]
-    def start
+    def open
       @cursor = @rows.size - 1
       @snapshot = @rows.map(&:dup)
     end
 
     ##
-    # Finish the transcript.
+    # Close the buffer.
     # @return [void]
-    def finish
+    def close
       @cursor = nil
       @snapshot = nil
     end
@@ -93,9 +102,13 @@ class LLM::Repl
 
     private
 
+    ##
+    # @return [LLM::Repl]
+    attr_reader :repl
+
     ##
     # Appends a new row
-    # @param [Array<{text: String, attrs?: Integer}>] chunks
+    # @param [Array<Node>] chunks
     #  One or more chunks.
     # @return [void]
     def append(chunks)
@@ -104,12 +117,12 @@ class LLM::Repl
 
     ##
     # Replaces the content of the active row
-    # @param [Array<{text: String, attrs?: Integer}>] chunks
+    # @param [Array<Node>] chunks
     #  One or more chunks.
     # @return [void]
     def replace(chunks)
       @rows = @snapshot.map(&:dup)
-      append(chunks)
+      chunks.each { wrap(_1, @rows) }
     end
 
     ##
@@ -123,10 +136,10 @@ class LLM::Repl
       chunk[:text].to_s.each_char do |char|
         if char == "\n"
           rows << []
-        elsif char == " " and sum(rows.last) >= WIDTH
+        elsif char == " " and sum(rows.last) >= repl.width
           rows << []
         else
-          rows.last << {text: char, attrs:}.compact
+          rows.last << Node.new(char, attrs)
         end
       end
     end

data/lib/llm/repl/command.rb

@@ -176,12 +176,19 @@ class LLM::Repl
     end
 
     ##
-    # Write a string to the transcript
-    # @param [String] str
+    # Write a string to the buffer
+    # @param [String] content
+    # @return [void]
+    def write(content)
+      write_message "command(#{self.class.name})", content
+    end
+
+    ##
+    # @param [String] user
+    # @param [String] content
     # @return [void]
-    def write(str, who: "command(#{self.class.name}): ")
-      @repl.write(who, Curses::A_BOLD)
-      @repl.write(str)
+    def write_message(user, content)
+      @repl.write_message(user, content)
     end
 
     ##

data/lib/llm/repl/commands/compact.rb

@@ -17,9 +17,9 @@ class LLM::Repl
     ##
     # @return [void]
     def call(n: 128)
-      write("compact in progress\n")
+      write "compact in progress"
       compactor.call(keep: n)
-      write("compact complete\n\n")
+      write "compact complete"
     end
 
     private

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

@@ -11,13 +11,11 @@ class LLM::Repl
     # @return [void]
     def call(name: nil)
       if name.nil?
-        write("\n#{self.class.help}\n\n")
+        write(self.class.help)
       elsif command = LLM::Command.find_by(name:)
-        write("\n#{command.help}\n\n")
+        write(command.help)
       else
-        write "\nNo help for #{name} was found" \
-              "\nThat command doesn't exist." \
-              "\n\n"
+        write "no help for #{name} was found"
       end
     end
   end

data/lib/llm/repl/markdown/table.rb

@@ -4,6 +4,11 @@ class LLM::Repl::Markdown
   ##
   # Renders Kramdown `:table` nodes as aligned columns.
   module Table
+    ##
+    # @api private
+    Node = LLM::Repl::Node
+    private_constant :Node
+
     ##
     # Renders a table node by collecting all cells first to
     # compute column widths, then emitting each row with
@@ -15,7 +20,6 @@ class LLM::Repl::Markdown
       rows.each do |row|
         emit("| ", attrs)
         row.each_with_index do |chunks, i|
-          text = chunks.map { _1[:text] }.join
           width = widths[i]
           chunks.each { |c| emit(c[:text].ljust(width), c[:attrs]) }
           emit(" | ", attrs) unless i == row.size - 1
@@ -51,13 +55,13 @@ class LLM::Repl::Markdown
     def walk_collect(node, attrs, chunks)
       case node.type
       when :text
-        chunks << {text: node.value.to_s, attrs:}
+        chunks << Node.new(node.value.to_s, attrs)
       when :strong
         node.children.each { walk_collect(_1, Curses::A_BOLD, chunks) }
       when :em
         node.children.each { walk_collect(_1, Curses::A_UNDERLINE, chunks) }
       when :codespan
-        chunks << {text: node.value, attrs: Curses::A_REVERSE}
+        chunks << Node.new(node.value, Curses::A_REVERSE)
       when :a
         node.children.each { walk_collect(_1, Curses::A_UNDERLINE, chunks) }
       else

data/lib/llm/repl/markdown.rb

@@ -22,7 +22,7 @@ class LLM::Repl
     end
 
     ##
-    # @return [Array<Hash>]
+    # @return [Array<Node>]
     def ast
       @ast.tap do
         ##
@@ -102,14 +102,14 @@ class LLM::Repl
       when :a
         node.children.each { walk(_1, Curses::A_UNDERLINE) }
       when :img
-        emit("[image: #{node.attr['alt']}]", attrs)
+        emit("[image: #{node.attr["alt"]}]", attrs)
       else
         node.children.each { walk(_1, attrs) }
       end
     end
 
     def emit(text, attrs)
-      @ast.push({text: text.to_s, attrs:}.compact)
+      @ast.push(Node.new(text.to_s, attrs))
     end
   end
 end

data/lib/llm/repl/node.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+class LLM::Repl
+  ##
+  # The {LLM::Repl::Node LLM::Repl::Node} class wraps a piece
+  # of text and optional curses attributes.
+  # @api private
+  class Node
+    ##
+    # @return [String]
+    attr_reader :text
+
+    ##
+    # @return [Integer, nil]
+    attr_reader :attrs
+
+    ##
+    # @param [String] text
+    # @param [Integer, nil] attrs
+    # @return [LLM::Repl::Node]
+    def initialize(text, attrs = nil)
+      @text = text.to_s
+      @attrs = attrs
+    end
+
+    ##
+    # Hash-like lookup.
+    # @param [Symbol] key
+    # @return [String, Integer, nil]
+    def [](key)
+      case key
+      when :text then @text
+      when :attrs then @attrs
+      end
+    end
+  end
+end

data/lib/llm/repl/status.rb

@@ -7,11 +7,11 @@ class LLM::Repl
   # @api private
   class Status
     ##
-    # @param [LLM::Agent] agent
+    # @param [LLM::Repl] repl
     # @return [LLM::Repl::Status]
-    def initialize(agent)
-      @agent = agent
-      @provider = agent.llm.name
+    def initialize(repl)
+      @agent = repl.agent
+      @provider = @agent.llm.name
       @text = "idle"
     end