llm.rb 12.1.0 → 12.3.0

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.1.0"
+  VERSION = "12.3.0"
 end

data/lib/llm.rb

@@ -180,6 +180,15 @@ module LLM
     LLM::XAI.new(**)
   end
 
+  ##
+  # @param key (see LLM::Mistral#initialize)
+  # @param host (see LLM::Mistral#initialize)
+  # @return (see LLM::Mistral#initialize)
+  def mistral(**)
+    lock(:require) { require_relative "llm/providers/mistral" unless defined?(LLM::Mistral) }
+    LLM::Mistral.new(**)
+  end
+
   ##
   # @param key (see LLM::ZAI#initialize)
   # @param host (see LLM::ZAI#initialize)
@@ -243,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

@@ -5,13 +5,17 @@ require_relative "lib/llm/version"
 Gem::Specification.new do |spec|
   spec.name = "llm.rb"
   spec.version = LLM::VERSION
-  spec.authors = ["bsdrobert", "Antar Azri", "Rodrigo Serrano"]
+  spec.authors = ["robert", "Antar Azri", "Rodrigo Serrano"]
   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"
 

data/resources/deepdive.md

@@ -25,44 +25,126 @@ features that didn't make it into the homepage documentation.
 
 ## Table of contents
 
-- [Agents](#agents)
-  - [As a subclass](#as-a-subclass)
-  - [As an object](#as-an-object)
-- [Skills](#skills)
-  - [SKILL.md](#skillmd)
-  - [Run it](#run-it)
-- [MCP](#mcp)
-  - [stdio](#stdio)
-  - [http](#http)
-- [A2A](#a2a)
-  - [rest](#rest)
-  - [jsonrpc](#jsonrpc)
-- [Transports](#transports)
-  - [net/http](#nethttp)
-  - [net/http/persistent](#nethttppersistent)
-  - [curb](#curb)
-- [Stream](#stream)
-  - [IO-like object](#io-like-object)
-  - [LLM::Stream](#llmstream)
-- [ORM](#orm)
-  - [ActiveRecord](#activerecord)
-  - [Sequel](#sequel)
-- [Schema](#schema)
-  - [Estimation](#estimation)
-- [Cancellation](#cancellation)
-  - [Cancel a request](#cancel-a-request)
-- [Tracer](#tracer)
-  - [Provider-wide tracer](#provider-wide-tracer)
-  - [Agent-local tracer](#agent-local-tracer)
-- [REPL](#repl)
-  - [LLM::Agent](#llmagent)
-- [Images](#images)
-  - [Generation](#generation)
-  - [Edits](#edits)
-- [Audio](#audio)
-  - [text-to-speech](#text-to-speech)
-  - [speech-to-text](#speech-to-text)
-  - [translation](#translation)
+**Overview**
+
+- [Welcome](#welcome)
+
+**Core**
+
+<details>
+<summary>Agents</summary>
+
+- [As a subclass](#as-a-subclass)
+- [As an object](#as-an-object)
+</details>
+
+<details>
+<summary>Tools</summary>
+
+- [LLM::Tool](#llmtool)
+- [Errors](#errors)
+</details>
+
+<details>
+<summary>Skills</summary>
+
+- [SKILL.md](#skillmd)
+- [Run it](#run-it)
+</details>
+
+<details>
+<summary>Schema</summary>
+
+- [Estimation](#estimation)
+</details>
+
+**Runtime**
+
+<details>
+<summary>Stream</summary>
+
+- [IO-like object](#io-like-object)
+- [LLM::Stream](#llmstream)
+</details>
+
+<details>
+<summary>Cancellation</summary>
+
+- [Cancel a request](#cancel-a-request)
+</details>
+
+<details>
+<summary>Transports</summary>
+
+- [net/http](#nethttp)
+- [net/http/persistent](#nethttppersistent)
+- [curb](#curb)
+</details>
+
+<details>
+<summary>Tracer</summary>
+
+- [Provider-wide tracer](#provider-wide-tracer)
+- [Agent-local tracer](#agent-local-tracer)
+</details>
+
+<details>
+<summary>REPL</summary>
+
+- [LLM::Agent](#llmagent)
+- [Tools](#tools)
+- [Skills](#skills-1)
+- [Tracer](#tracer-1)
+</details>
+
+**Persistence**
+
+<details>
+<summary>Serialization</summary>
+
+- [Save to disk](#save-to-disk)
+</details>
+
+<details>
+<summary>ORM</summary>
+
+- [ActiveRecord](#activerecord)
+- [Sequel](#sequel)
+</details>
+
+**Media**
+
+<details>
+<summary>Images</summary>
+
+- [Generation](#generation)
+- [Edits](#edits)
+- [DeepSeek](#deepseek)
+</details>
+
+<details>
+<summary>Audio</summary>
+
+- [text-to-speech](#text-to-speech)
+- [speech-to-text](#speech-to-text)
+- [translation](#translation)
+</details>
+
+**Protocols**
+
+<details>
+<summary>MCP</summary>
+
+- [stdio](#stdio)
+- [http](#http)
+</details>
+
+<details>
+<summary>A2A</summary>
+
+- [rest](#rest)
+- [jsonrpc](#jsonrpc)
+</details>
 
 ## Agents
 
@@ -808,21 +890,22 @@ agent = LLM::Agent.new(llm, tracer: LLM::Tracer::Logger.new(llm, path: "deepseek
 
 During the development and operation of agents it can often
 be helpful to drop into a read-eval-print loop. This gives
-you a simple way to confirm the work was successful, inspect
-anything that went wrong (for example, tool call errors), and
-keep talking to the same agent so you can learn about its
-decision-making process and make improvements for future runs.
-It can also be used to ask the agent to correct any errors
-that might have made.
+you a way to confirm the work was successful, inspect
+anything that went wrong, and keep talking to the same
+agent while its state is still intact.
 
-##### LLM::Agent
+#### LLM::Agent
 
 The [LLM::Agent#repl](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#repl-instance_method)
-method requires the [curses](https://github.com/ruby/curses)
-gem to be installed and available for require. It is an
-optional dependency that only becomes required when you
-call the [LLM::Agent#repl](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#repl-instance_method)
-method.
+method allows an agent to spawn a read-eval-print loop
+that can be useful while developing or operating agents.
+It can be used to debug tool calls, confirm an
+agent has done what was expected, or improve an agent by
+asking questions about what it has done up to that point.
+
+This feature requires that the [curses](https://github.com/ruby/curses)
+and [kramdown](https://github.com/gettalong/kramdown) libraries are
+installed and available to require.
 
 ```ruby
 require "llm"
@@ -832,6 +915,43 @@ agent = LLM::Agent.new(llm)
 agent.repl
 ```
 
+#### Tools
+
+The read-eval-print loop accepts a `tools` option that lets
+you attach additional tools for the duration of the session.
+
+```ruby
+llm = LLM.deepseek(key: ENV["KEY"])
+agent = LLM::Agent.new(llm)
+agent.repl(tools: [Debugger])
+```
+
+#### Skills
+
+The read-eval-print loop also accepts a `skills` option.
+This can be useful when you want to load extra skills
+without attaching them to an agent permanently.
+
+```ruby
+llm = LLM.deepseek(key: ENV["KEY"])
+agent = LLM::Agent.new(llm)
+agent.repl(skills: [__dir__])
+```
+
+#### Tracer
+
+By default the tracer is disabled for the duration of the
+session. This can be configured through the
+`tracer` option. Setting it to `true` will configure
+the REPL to use the tracer associated with an instance
+of [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html).
+
+```ruby
+llm = LLM.deepseek(key: ENV["KEY"])
+agent = LLM::Agent.new(llm, tracer: LLM.logger(llm, path: "agent.log"))
+agent.repl(tracer: true, tools: [Debugger])
+```
+
 [Back to top](#table-of-contents)
 
 ## Images