llm.rb 12.2.0 → 12.3.1

data/lib/llm/repl/transcript.rb

@@ -2,30 +2,70 @@
 
 class LLM::Repl
   ##
-  # The {LLM::Repl::Transcript LLM::Repl::Transcript} class
-  # stores streamed output for the REPL.
-  # @api private
+  # This class maintains conversation state that includes
+  # the conversation itself, and metadata associated with
+  # the conversation.
+  #
+  # Internally it maintains an array where each element
+  # represents a row, and each element in a row is a Hash
+  # that describes a piece of text and any styles that might
+  # be applied to it by the UI thread.
+  #
+  # 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
 
     ##
     # @return [LLM::Repl::Transcript]
     def initialize
-      @lines = [+""]
+      @rows = [[]]
+      @cursor = nil
+      @snapshot = nil
       @offset = 0
     end
 
     ##
     # @param [String] chars
+    # @param [Object] attrs
+    # @param [Symbol] method
     # @return [void]
-    def write(chars)
-      chars.each_char { write_char(_1) }
+    def write(chars, attrs = nil, method: :append)
+      chunks = [{text: chars.to_s, attrs:}.compact]
+      self.method(method).call(chunks)
+    end
+
+    ##
+    # Appends Markdown to the transcript.
+    # @param [String] chars
+    # @param [Symbol] method
+    # @return [void]
+    def markdown(chars, method: :append)
+      chunks = LLM::Repl::Markdown.new(chars).ast
+      self.method(method).call(chunks)
+    end
+
+    ##
+    # Start the transcript.
+    # @return [void]
+    def start
+      @cursor = @rows.size - 1
+      @snapshot = @rows.map(&:dup)
+    end
+
+    ##
+    # Finish the transcript.
+    # @return [void]
+    def finish
+      @cursor = nil
+      @snapshot = nil
     end
 
     ##
     # @return [void]
     def scroll_up(height)
-      max = [@lines.size - height, 0].max
+      max = [rows.size - height, 0].max
       @offset = [@offset + 1, max].min
     end
 
@@ -39,23 +79,72 @@ class LLM::Repl
     # @param [Integer] height
     # @return [Array<String>]
     def visible(height)
-      last = @lines.size - 1 - @offset
+      all = rows
+      last = all.size - 1 - @offset
       first = [last - height + 1, 0].max
-      @lines[first..last] || []
+      all[first..last] || []
     end
 
     private
 
-    def write_char(char)
-      if char == "\n"
-        @offset += 1 if @offset > 0
-        @lines << +""
-      elsif char == " " and @lines.last.length >= WIDTH
-        @offset += 1 if @offset > 0
-        @lines << +""
-      else
-        @lines.last << char
+    ##
+    # Appends a new row
+    # @param [Array<{text: String, attrs?: Integer}>] chunks
+    #  One or more chunks.
+    # @return [void]
+    def append(chunks)
+      chunks.each { wrap(_1, @rows) }
+    end
+
+    ##
+    # Replaces the content of the active row
+    # @param [Array<{text: String, attrs?: Integer}>] chunks
+    #  One or more chunks.
+    # @return [void]
+    def replace(chunks)
+      @rows = @snapshot.map(&:dup)
+      append(chunks)
+    end
+
+    ##
+    # Given a chunk this method wraps text at
+    # around 80 columns: a new row starts when
+    # the current character is " " and the sum
+    # of all characters in that row is greater
+    # than 80 columns.
+    def wrap(chunk, rows)
+      attrs = chunk[:attrs]
+      chunk[:text].to_s.each_char do |char|
+        if char == "\n"
+          rows << []
+        elsif char == " " and sum(rows.last) >= WIDTH
+          rows << []
+        else
+          rows.last << {text: char, attrs:}.compact
+        end
       end
     end
+
+    ##
+    # @api private
+    def rows
+      @rows.dup.tap do |rows|
+        ##
+        # Discard empty rows that would otherwise
+        # be rendered as newlines by the UI thread.
+        # It's not the most elegant way to deal with
+        # this and we probably shouldn't allow it to
+        # happen in the first place.
+        while rows.size > 1 and rows.last.empty?
+          rows.pop
+        end
+      end
+    end
+
+    ##
+    # @api private
+    def sum(row)
+      row.sum { _1[:text].to_s.length }
+    end
   end
 end

data/lib/llm/repl/window.rb

@@ -37,6 +37,7 @@ class LLM::Repl
       Curses.cbreak
       Curses.noecho
       Curses.stdscr.keypad(true)
+      Curses.stdscr.nodelay = true
       yield
     ensure
       Curses.close_screen
@@ -45,9 +46,10 @@ class LLM::Repl
     ##
     # @return [void]
     def redraw
-      Curses.clear
-      draw_status
-      draw_transcript
+      Curses.curs_set(0)
+      draw_status(offset: input.height + 1)
+      draw_divider(offset: 5)
+      draw_transcript(offset: 0)
       draw_input
       Curses.refresh
     end
@@ -55,7 +57,7 @@ class LLM::Repl
     ##
     # @return [Integer]
     def rows
-      [Curses.lines - 3, 1].max
+      [Curses.lines - (input.height + 4), 1].max
     end
 
     ##
@@ -78,28 +80,57 @@ class LLM::Repl
 
     private
 
-    def draw_status
-      Curses.setpos(0, 0)
+    def draw_status(offset:)
+      Curses.setpos(Curses.lines - offset, 0)
+      Curses.clrtoeol
       Curses.addstr(status.to_s)
-      provider = status.provider.to_s
-      Curses.setpos(0, [columns - provider.length, 0].max)
-      Curses.addstr(provider)
+      context = status.context_bar
+      Curses.setpos(Curses.lines - offset, [(columns - context.length) / 2, 0].max)
+      Curses.addstr(context)
+      cost = status.cost.to_s
+      Curses.setpos(Curses.lines - offset, [columns - cost.length, 0].max)
+      Curses.addstr(cost)
     end
 
-    def draw_transcript
-      visible = transcript.visible(rows)
-      visible.each_with_index do |row, index|
-        Curses.setpos(index + 2, 0)
-        Curses.addstr(row)
-      end
+    def draw_divider(offset:)
+      Curses.setpos(Curses.lines - offset, 0)
+      Curses.clrtoeol
+      Curses.addstr("─" * Curses.cols)
     end
 
     def draw_input
-      Curses.setpos(Curses.lines - 1, 0)
-      Curses.clrtoeol
-      Curses.addstr(input.to_s)
+      cols = columns
+      rows = input.lines(cols)
+      rows.each.with_index do |line, idx|
+        Curses.setpos((Curses.lines - input.height) + idx, 0)
+        Curses.clrtoeol
+        Curses.addstr(line)
+      end
+      line, col = input.cursor_pos(cols)
+      Curses.setpos((Curses.lines - input.height) + line, col)
     end
 
+    def draw_transcript(offset:)
+      rows = transcript.visible(self.rows)
+      rows.each.with_index(offset) do |row, index|
+        Curses.setpos(index, 0)
+        Curses.clrtoeol
+        row.each do |chunk|
+          text, attrs = chunk.values_at(:text, :attrs)
+          Curses.attron(attrs) if attrs
+          Curses.addstr(text)
+          Curses.attroff(attrs) if attrs
+        end
+      end
+      last_drawn = offset + rows.size
+      (last_drawn...self.rows).each do |line|
+        Curses.setpos(line, 0)
+        Curses.clrtoeol
+      end
+    end
+
+    ##
+    # @return [Integer]
     def columns
       Curses.cols
     end

data/lib/llm/repl.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 LLM.require "curses"
+LLM.require "kramdown"
 
 module LLM
   ##
@@ -18,19 +19,37 @@ module LLM
     require_relative "repl/status"
     require_relative "repl/transcript"
     require_relative "repl/input"
+    require_relative "repl/bar"
     require_relative "repl/stream"
+    require_relative "repl/markdown"
 
     ##
     # @param [LLM::Agent] agent
+    # @param [Array<LLM::Tool>] tools
+    #  Zero or more tools
+    # @param [Array<String>] skills
+    #  Zero or more skills
     # @return [LLM::Repl]
-    def initialize(agent)
+    def initialize(agent:, tools:, skills:)
       @agent = agent
       @provider = agent.llm.name
-      @status = Status.new(@provider)
+      @status = Status.new(@agent)
       @transcript = Transcript.new
-      @input = Input.new(@provider)
+      @input = Input.new(@agent, height: 3)
       @window = Window.new(@status, @transcript, @input)
-      @stream = Stream.new(self)
+      @thread = nil
+      @queue = Queue.new
+      @stream = Stream.new(self, @queue)
+      @skills = skills.map do |path|
+        ##
+        # I'm not sure it would make sense to expose
+        # the underlying context or not. In the meantime,
+        # this works and meets the expectations of the
+        # LLM::Skill class.
+        ctx = agent.instance_variable_get(:@ctx)
+        LLM::Skill.load(path).to_tool(ctx)
+      end
+      @tools = [agent.params[:tools], @skills, tools].flatten.compact
     end
 
     ##
@@ -38,26 +57,33 @@ module LLM
     def start
       window.open do
         loop do
-          window.redraw
-          text = input.readline(window)
-          break if text.nil?
-          next if text.empty?
-          status.text = "thinking"
-          write("user: #{text}\n")
-          window.redraw
-          write("agent: ")
-          agent.talk(text, stream:)
-          status.text = "idle"
-          write("\n\n")
+          case input.on_char(window, window.getch)
+          when :exit then break
+          when :submit then submit
+          when :up, :down, :backspace, :char then window.redraw
+          else
+            window.redraw
+            read!
+            sleep 0.01
+          end
         end
       end
     end
 
+    ##
+    # @param [String] chars
+    # @param [Object] attrs
+    # @return [void]
+    def write(chars, attrs = nil)
+      transcript.write(chars, attrs)
+      window.redraw
+    end
+
     ##
     # @param [String] chars
     # @return [void]
-    def write(chars)
-      transcript.write(chars)
+    def markdown(chars)
+      transcript.markdown(chars)
       window.redraw
     end
 
@@ -71,8 +97,63 @@ module LLM
 
     private
 
+    ##
+    # This method is called when the user submits their input.
+    # It spawns a second thread that maintains a line of
+    # communication with a model and the main thread - where
+    # the UI runs - remains responsive.
+    # @api private
+    def submit
+      return if thread&.alive?
+      text = input.take
+      return if text.empty?
+      status.text = "thinking"
+      write("user: ", Curses::A_BOLD)
+      markdown(text)
+      write("\nagent: ", Curses::A_BOLD)
+      @thread = Thread.new do
+        @queue << [:start]
+        agent.talk(text, tools:, stream:)
+        @queue << [:done]
+      rescue => e
+        @queue << [:error, e]
+      end
+    end
+
+    ##
+    # This method reads from the queue that is written to
+    # by a second thread. The queue is managed or written
+    # to by a subclass of {LLM::Stream LLM::Stream}.
+    # @api private
+    def read!
+      loop do
+        type, value = @queue.pop(true)
+        case type
+        when :start
+          transcript.start
+          stream.empty!
+        when :stream
+          transcript.markdown(value, method: :replace)
+        when :status
+          self.status = value
+        when :done
+          status.text = "idle"
+          @thread = nil
+          transcript.finish
+          write("\n\n")
+        when :error
+          # Do this better
+          status.text = "error"
+          transcript.finish
+          write("\nerror: #{value.message}\n", Curses::A_BOLD)
+          @thread = nil
+        end
+      end
+    rescue ThreadError
+    end
+
     attr_reader :agent, :provider, :stream,
                 :status, :transcript, :input,
-                :window
+                :window, :tools, :thread
   end
 end

data/lib/llm/sequel/agent.rb

@@ -38,6 +38,17 @@ module LLM::Sequel
     end
 
     module InstanceMethods
+      ##
+      # @note
+      #  This method does not persist to the database,
+      #  but it can inspect and alter runtime state in
+      #  a way that is temporary.
+      # @param (see LLM::Agent#repl)
+      # @return (see LLM::Agent#repl)
+      def repl(**params)
+        ctx.repl(**params)
+      end
+
       private
 
       def ctx

data/lib/llm/skill.rb

@@ -155,7 +155,7 @@ module LLM
     def agent(ctx)
       instructions, tools, tracer, inherit_tools = self.instructions, self.tools, ctx.llm.tracer, inherit_tools?
       params = ctx.params.merge(mode: ctx.mode).reject { [:tools, :schema].include?(_1) }
-      concurrency = params[:stream].extra[:concurrency] if LLM::Stream === params[:stream]
+      concurrency = params[:stream].extra[:concurrency]
       params[:concurrency] = concurrency if concurrency
       agent = Class.new(LLM::Agent) do
         instructions(instructions)

data/lib/llm/stream/disabled.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class LLM::Stream
+  ##
+  # An {LLM::Stream::Disabled LLM::Stream::Disabled} represents a stream
+  # that is explicitly turned off.
+  #
+  # {LLM::Stream.try} returns an instance of this class when given `false`
+  # or `nil`. Providers check {#enabled?} to decide whether to request a
+  # streaming response from the API. When disabled, the stream is replaced
+  # with `nil` before the transport layer executes the request.
+  #
+  # All callback methods inherited from {LLM::Stream LLM::Stream} are no-ops,
+  # so a disabled stream can be used safely wherever a stream object is
+  # expected.
+  class Disabled < self
+    ##
+    # @return [false]
+    def enabled?
+      false
+    end
+  end
+end

data/lib/llm/stream/io.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+class LLM::Stream
+  ##
+  # An {LLM::Stream::IO LLM::Stream::IO} wraps an object that responds to
+  # `#<<` and forwards streamed content to it.
+  #
+  # This enables any object that implements `#<<` - such as an IO, StringIO,
+  # or a custom logger - to be used as a stream target. {LLM::Stream.try}
+  # creates instances of this class automatically when given an IO-like
+  # object.
+  #
+  # @example Using an IO object as a stream
+  #   File.open("output.txt", "w") do |file|
+  #     ctx.ask("Tell me a story", stream: file)
+  #   end
+  class IO < self
+    ##
+    # @param [#<<] io
+    #  Any object that implements `#<<`.
+    def initialize(io)
+      @io = io
+    end
+
+    ##
+    # Writes a chunk of content to the wrapped IO object.
+    # @param [String] content
+    # @return [void]
+    def on_content(content)
+      @io << content
+    end
+
+    ##
+    # Forwards streamed content to the wrapped IO object.
+    # Redefined here because +alias_method+ in the parent class
+    # captures the base implementation, not the overridden one.
+    # @param [String] content
+    # @return [void]
+    def <<(content)
+      on_content(content)
+    end
+  end
+end

data/lib/llm/stream.rb

@@ -21,6 +21,34 @@ module LLM
   # also emit lifecycle callbacks like {#on_transform} or {#on_compaction}.
   class Stream
     require_relative "stream/queue"
+    require_relative "stream/io"
+    require_relative "stream/disabled"
+
+    ##
+    # This method will try to convert its argument into
+    # an instance of {LLM::Stream LLM::Stream} or a
+    # subclass of it.
+    #
+    # Acceptable inputs include: {LLM::Stream LLM::Stream}
+    # objects, IO objects who implement `#<<`, true, false,
+    # and nil. Anything else raises a TypeError.
+    #
+    # @raise [TypeError]
+    # @param [LLM::Stream, #<<, Boolean, NilClass] obj
+    # @return [LLM::Stream]
+    def self.try(obj, extra: {})
+      if LLM::Stream === obj
+        obj.tap { _1.extra.merge!(extra) }
+      elsif obj.respond_to?(:<<)
+        LLM::Stream::IO.new(obj).tap { _1.extra.merge!(extra) }
+      elsif obj == true
+        LLM::Stream.new.tap { _1.extra.merge!(extra) }
+      elsif obj.nil? || obj == false
+        LLM::Stream::Disabled.new.tap { _1.extra.merge!(extra) }
+      else
+        raise TypeError, "invalid stream object"
+      end
+    end
 
     ##
     # Returns extra context associated with the current streamed request.
@@ -52,6 +80,12 @@ module LLM
       queue.wait
     end
 
+    ##
+    # @return [Boolean]
+    def enabled?
+      true
+    end
+
     # @group Public callbacks
 
     ##

data/lib/llm/tools/git.rb

@@ -16,9 +16,8 @@ class LLM::Tool
     required %i[action]
 
     ##
-    # @param [String] path
-    # @param [Integer] start
-    # @param [Integer] stop
+    # @param [String] action
+    # @param [Array<String>, nil] arguments
     # @return [Hash]
     def call(action:, arguments: nil)
       command = spawn(action:, arguments:)

data/lib/llm/tools/pwd.rb

@@ -11,7 +11,6 @@ class LLM::Tool
     description "returns the current working directory"
 
     ##
-    # @param [String] path
     # @return [Hash]
     def call
       {ok: true, cwd: Dir.getwd}

data/lib/llm/tools/rg.rb

@@ -16,7 +16,8 @@ class LLM::Tool
     required %i[patterns]
 
     ##
-    # @param [String] pattern
+    # @param [Array<String>] patterns
+    # @param [String] path
     # @return [Hash]
     def call(patterns:, path: Dir.getwd)
       validate!(patterns:, path:)

data/lib/llm/tools/swap_text.rb

@@ -14,6 +14,12 @@ class LLM::Tool
     parameter :expected_count, Integer, "How many matches should be replaced"
     required %i[path before after]
 
+    ##
+    # @param [String] path
+    # @param [String] before
+    # @param [String] after
+    # @param [Integer] expected_count
+    # @return [Hash]
     def call(path:, before:, after:, expected_count: 1)
       content = File.read(path)
       count = content.scan(before).length

data/lib/llm/transport/execution.rb

@@ -29,6 +29,7 @@ class LLM::Transport
     #  When there is a network error at the operating system level
     # @return [LLM::Transport::Response]
     def execute(request:, operation:, stream: nil, stream_parser: self.stream_parser, model: nil, inputs: nil, &b)
+      stream = nil if !stream&.enabled?
       stream &&= LLM::Object.from(streamer: stream, parser: stream_parser, decoder: stream_decoder)
       owner = transport.request_owner
       tracer = self.tracer

data/lib/llm/version.rb

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

data/lib/llm.rb

@@ -252,6 +252,16 @@ module LLM
     LLM::Function.new(key, &b)
   end
 
+  ##
+  # @param [LLM::Provider] llm
+  #  A provider
+  # @param [Hash] params
+  #  Forwarded to LLM::Tracer::Logger
+  # @return [LLM::Tracer::Logger]
+  def logger(llm, **params)
+    LLM::Tracer::Logger.new(llm, params)
+  end
+
   ##
   # Provides a thread-safe lock
   # @param [Symbol] name The name of the lock

data/llm.gemspec

@@ -9,9 +9,13 @@ Gem::Specification.new do |spec|
   spec.email = ["robert@r.uby.dev"]
 
   spec.summary = "Ruby's capable AI runtime"
-  spec.description = "llm.rb is not a library, framework or toolkit but " \
-                     "an advanced runtime for building highly capable AI " \
-                     "applications on CRuby."
+  spec.description = <<~DESCRIPTION
+llm.rb is an advanced runtime for building capable AI applications
+on CRuby. By default it has zero runtime dependencies although certain
+functionality &ndash; such as ActiveRecord support &ndash; require
+optional dependencies that are opt-in.
+DESCRIPTION
+
   spec.license = "BUSL-1.1"
   spec.required_ruby_version = ">= 3.3.0"