llm.rb 13.1.0 → 14.0.0

data/lib/llm/repl/markdown.rb

@@ -11,6 +11,26 @@ class LLM::Repl
     require_relative "markdown/table"
     include Table
 
+    ##
+    # Kramdown goes a bit beyond a standard markdown
+    # parser by representing certain characters or
+    # character sequences as distinct node types that are
+    # represented by `:typographic_sym`, and `:smart_quote`.
+    #
+    # The node's value maps back to one of the keys in
+    # this Hash, and the values are unicode characters
+    # that provide a visual representation of the node.
+    #
+    # @api private
+    SYMBOLS = {
+      hellip: "…",
+      ndash:  "–", mdash:  "—",
+      laquo:  "«", raquo:  "»",
+      laquo_space: "« ", raquo_space: "» ",
+      lsquo:  "‘", rsquo:  "’",
+      ldquo:  "“", rdquo:  "”"
+    }
+
     ##
     # @param [String] text
     # @param [Integer] width
@@ -65,17 +85,19 @@ class LLM::Repl
         emit("\n\n", attrs)
       when :header
         emit("\n", attrs)
-        node.children.each { walk(_1, Curses::A_BOLD) }
+        node.children.each { walk(_1, Curses::A_BOLD | Color.white) }
         emit("\n", attrs)
       when :strong
-        node.children.each { walk(_1, Curses::A_BOLD) }
+        node.children.each { walk(_1, Curses::A_BOLD | Color.white) }
       when :em
         node.children.each { walk(_1, Curses::A_UNDERLINE) }
       when :codespan
-        emit(node.value, Curses::A_REVERSE)
+        emit(node.value, Color.green)
       when :codeblock
-        emit(node.value, Curses::A_REVERSE)
+        emit(node.value, Color.green)
         emit("\n\n", attrs)
+      when :typographic_sym, :smart_quote
+        emit(symbol(node), attrs)
       when :br
         emit("\n", attrs)
       when :ul, :ol
@@ -100,7 +122,7 @@ class LLM::Repl
         emit("─" * @width, attrs)
         emit("\n\n", attrs)
       when :a
-        node.children.each { walk(_1, Curses::A_UNDERLINE) }
+        node.children.each { walk(_1, Curses::A_UNDERLINE | Color.green) }
       when :img
         emit("[image: #{node.attr["alt"]}]", attrs)
       else
@@ -111,5 +133,9 @@ class LLM::Repl
     def emit(text, attrs)
       @ast.push(Node.new(text.to_s, attrs))
     end
+
+    def symbol(node)
+      SYMBOLS[node.value]
+    end
   end
 end

data/lib/llm/repl/status.rb

@@ -4,6 +4,11 @@ class LLM::Repl
   ##
   # The {LLM::Repl::Status LLM::Repl::Status} class stores
   # the small status line shown at the top of the REPL.
+  #
+  # The status text can be a plain String, a single
+  # {LLM::Repl::Node LLM::Repl::Node} (text plus curses attributes),
+  # or an Array of either. Attributes on nodes are applied when the
+  # window draws the status line.
   # @api private
   class Status
     ##
@@ -12,14 +17,18 @@ class LLM::Repl
     def initialize(repl)
       @agent = repl.agent
       @provider = @agent.llm.name
-      @text = "idle"
+      @nodes = [Node.new("idle")]
     end
 
     ##
     # @return [String]
     def context_bar
       LLM::Repl::Bar.new(
-        used: @agent.usage.total_tokens,
+        ##
+        # After compaction the used context is unknown until the next
+        # response, so the bar renders an unknown state instead of a
+        # stale percentage.
+        used: @agent.compacted? ? nil : @agent.usage.total_tokens,
         total: @agent.context_window
       ).to_s
     end
@@ -30,12 +39,38 @@ class LLM::Repl
       "$#{@agent.cost}"
     end
 
+    ##
+    # Sets the status text.
+    # @param [String, LLM::Repl::Node, Array<String, LLM::Repl::Node>] value
+    # @return [Array<LLM::Repl::Node>]
+    def text=(value)
+      @nodes =
+        case value
+        when Node then [value]
+        when Array then value.map { |node| Node === node ? node : Node.new(node) }
+        else [Node.new(value)]
+        end
+    end
+
     ##
     # @return [String]
-    attr_accessor :text
+    def text
+      @nodes.map(&:text).join
+    end
 
     ##
     # @return [String]
     alias_method :to_s, :text
+
+    ##
+    # The nodes making up the status line.
+    # @return [Array<LLM::Repl::Node>]
+    def nodes
+      if @agent.compacted?
+        [Node.new("Context compacted")]
+      else
+        @nodes
+      end
+    end
   end
 end

data/lib/llm/repl/stream.rb

@@ -8,6 +8,10 @@ class LLM::Repl
   # tool returns.
   # @api private
   class Stream < LLM::Stream
+    ##
+    # @return [Hash<Symbol, LLM::Tool>]
+    attr_reader :tools
+
     ##
     # @param [LLM::Repl] repl
     # @return [LLM::Repl::Stream]
@@ -15,6 +19,7 @@ class LLM::Repl
       @repl = repl
       @_queue = queue
       @buffer = +""
+      @tools = {}
     end
 
     ##
@@ -30,15 +35,16 @@ class LLM::Repl
     # @param [LLM::Function] tool
     # @return [void]
     def on_tool_call(tool)
-      @_queue.push [:status, "#{tool.name}(#{format_args(tool)})"]
+      @tools[tool.name] = tool
+      @_queue.push [:status, [" ", lambda, " • #{tool.name}(#{format_args(tool)})"]]
     end
 
     ##
-    # @param [LLM::Function] _tool
+    # @param [LLM::Function] tool
     # @param [LLM::Function::Return] result
     # @return [void]
-    def on_tool_return(_tool, result)
-      @_queue.push [:status, @repl.thinking_text]
+    def on_tool_return(tool, result)
+      @tools.delete(tool.name)
     end
 
     ##
@@ -50,6 +56,12 @@ class LLM::Repl
 
     private
 
+    ##
+    # @return [LLM::Repl::Node]
+    def lambda
+      Node.new("λ", Curses::A_BOLD | Color.red)
+    end
+
     ##
     # Formats tool arguments as compact key: value pairs
     # suitable for the status line.  Strings are quoted and

data/lib/llm/repl/walker.rb

@@ -18,12 +18,13 @@ class LLM::Repl
     end
 
     ##
-    # @return [Object, nil]
+    # @return [Object, String, nil]
     def next
       if @items.empty?
         nil
       elsif @cursor >= @items.size - 1
-        @items[@cursor]
+        @cursor = @items.size
+        ""
       else
         @cursor += 1
         @items[@cursor]

data/lib/llm/repl/window.rb

@@ -23,6 +23,7 @@ class LLM::Repl
     #  A read-eval-print loop.
     # @return [LLM::Repl::Window]
     def initialize(repl)
+      @repl   = repl
       @status = repl.status
       @buffer = repl.buffer
       @input  = repl.input
@@ -33,6 +34,7 @@ class LLM::Repl
     # @return [void]
     def open
       Curses.init_screen
+      Color.enable
       Curses.cbreak
       Curses.noecho
       Curses.stdscr.keypad(true)
@@ -58,6 +60,12 @@ class LLM::Repl
       [Curses.lines - (input.height + 4), 1].max
     end
 
+    ##
+    # @return [Integer]
+    def columns
+      Curses.cols
+    end
+
     ##
     # @return [Object]
     def getch
@@ -107,11 +115,17 @@ class LLM::Repl
       rows.each.with_index(offset) do |row, index|
         Curses.setpos(index, 0)
         Curses.clrtoeol
+        Curses.setpos(index, gutter)
+        width = 0
         row.each do |chunk|
-          text, attrs = chunk.text, chunk.attrs
+          remaining = buffer.width - width
+          break if remaining <= 0
+          text, attrs = chunk.text.to_s, chunk.attrs
+          clipped = text[0, remaining]
           Curses.attron(attrs) if attrs
-          Curses.addstr(text)
+          Curses.addstr(clipped)
           Curses.attroff(attrs) if attrs
+          width += clipped.length
         end
       end
       last_drawn = offset + rows.size
@@ -124,7 +138,11 @@ class LLM::Repl
     def draw_status(offset:)
       Curses.setpos(Curses.lines - offset, 0)
       Curses.clrtoeol
-      Curses.addstr(status.to_s)
+      status.nodes.each do |node|
+        Curses.attron(node.attrs) if node.attrs
+        Curses.addstr(node.text)
+        Curses.attroff(node.attrs) if node.attrs
+      end
       context = status.context_bar
       Curses.setpos(Curses.lines - offset, [(columns - context.length) / 2, 0].max)
       Curses.addstr(context)
@@ -151,9 +169,11 @@ class LLM::Repl
     end
 
     ##
+    # 20% offset that occupies the left margin and
+    # helps center {LLM::Repl::Buffer LLM::Repl::Buffer}.
     # @return [Integer]
-    def columns
-      Curses.cols
+    def gutter
+      (columns * 0.2).floor
     end
   end
 end

data/lib/llm/repl.rb

@@ -15,6 +15,7 @@ module LLM
   # task correctly, or for it to correct course after a
   # mistake was made.
   class Repl
+    require_relative "repl/color"
     require_relative "repl/window"
     require_relative "repl/status"
     require_relative "repl/buffer"
@@ -29,7 +30,7 @@ module LLM
     attr_reader :agent, :provider, :stream,
                 :status, :buffer, :input,
                 :window, :tools, :thread,
-                :name, :path, :width
+                :name, :path
 
     ##
     # @param [LLM::Agent] agent
@@ -43,14 +44,14 @@ module LLM
     #  Zero or more skills
     # @return [LLM::Repl]
     def initialize(agent:, name: nil, tools: [], skills: [], path: nil)
-      @width = 80
       @path = path
       @name = name || "agent"
+      @sender = "You"
       @agent = configure(agent:, path:)
       @provider = agent.llm.name
-      @status = Status.new(self)
-      @buffer = Buffer.new(self)
       @input = Input.new(self, height: 3)
+      @buffer = Buffer.new(self)
+      @status = Status.new(self)
       @window = Window.new(self)
       @thread = nil
       @queue = Queue.new
@@ -112,7 +113,7 @@ module LLM
     # @param [String] chars
     # @return [Array<Node>]
     def markdown(chars)
-      LLM::Repl::Markdown.new(chars, width).ast
+      LLM::Repl::Markdown.new(chars, buffer.width).ast
     end
 
     ##
@@ -125,8 +126,21 @@ module LLM
 
     ##
     # @return [String]
-    def thinking_text
-      "thinking • Esc to cancel"
+    def think_text
+      " 🧠 • Thinking • Esc to cancel"
+    end
+
+    ##
+    # @return [String]
+    def connect_text
+      " 🌐 • Connecting • Esc to cancel"
+    end
+
+    ##
+    # Returns a label for the person who sent a message.
+    # @return [String]
+    def sender
+      @sender
     end
 
     private
@@ -138,11 +152,11 @@ module LLM
     def tree(messages)
       messages.flat_map do |message|
         next if message.tool_call? || message.tool_return?
-        user = message.assistant? ? name : "user"
+        user = message.assistant? ? name : sender
         [
-          Node.new("#{user}: ", Curses::A_BOLD),
-          Node.new(message.content),
-          Node.new(user == name ? "\n\n" : "\n")
+          Node.new("#{user}:\n", Curses::A_BOLD | Color.blue),
+          *markdown(message.content),
+          Node.new("\n\n")
         ]
       end.compact
     end
@@ -186,8 +200,8 @@ module LLM
         write("\n")
       in [:input, String => text]
         window.scroll_to_bottom
-        status.text = thinking_text
-        write_message("user", markdown(text))
+        status.text = connect_text
+        write_message(sender, markdown(text))
         @thread = Thread.new do
           @queue << [:start]
           agent.talk(text, tools:, stream:)
@@ -245,6 +259,7 @@ module LLM
           buffer.open
           stream.clear
         when :stream
+          status.text = think_text if stream.tools.empty?
           write_message name, markdown(value), method: :replace
         when :status
           self.status = value
@@ -254,6 +269,7 @@ module LLM
           @thread = nil
           write("\n")
         when :cancel
+          stream.tools.clear
           buffer.close
           status.text = "Idle"
           write_message(name, "Request cancelled")

data/lib/llm/stream.rb

@@ -128,7 +128,10 @@ module LLM
     ##
     # Called when a streamed tool call has been fully constructed.
     # A stream implementation may start tool execution here by pushing
-    # `@queue << tool.task(:thread)` onto {#queue}.
+    # `@queue << tool.task(:thread).tap(&:spawn)` onto {#queue} — `spawn`
+    # returns nil, so `tap` keeps the task while starting it. The task
+    # carries the context's guard, so it is checked before the tool runs —
+    # a blocked call yields its guard return without executing.
     # @param [LLM::Function] tool
     #  The parsed tool call.
     # @return [nil]
@@ -151,19 +154,17 @@ module LLM
 
     ##
     # Called before a context transformer rewrites a prompt.
-    # @param [LLM::Context] ctx
-    # @param [#call] transformer
+    # @param [LLM::Transformer] transformer
     # @return [nil]
-    def on_transform(ctx, transformer)
+    def on_transform(transformer)
       nil
     end
 
     ##
     # Called after a context transformer finishes rewriting a prompt.
-    # @param [LLM::Context] ctx
-    # @param [#call] transformer
+    # @param [LLM::Transformer] transformer
     # @return [nil]
-    def on_transform_finish(ctx, transformer)
+    def on_transform_finish(transformer)
       nil
     end
 

data/lib/llm/tool.rb

@@ -150,6 +150,35 @@ class LLM::Tool
     end
   end
 
+  ##
+  # Assign multiple tool properties at once.
+  # @example
+  #   class Tool < LLM::Tool
+  #     set name: "my-tool",
+  #         description: "my tool does this and that",
+  #         parameters: [
+  #           [:name, String , "this and that"],
+  #           [:age , Integer, "this and that"]
+  #         ],
+  #         required: %i[name],
+  #         defaults: {age: 42}
+  #   end
+  # @param [Hash] properties
+  # @return [void]
+  def self.set(properties)
+    properties.each do
+      if _1.to_s == "parameters"
+        _2.each { |attributes| parameter(*attributes) }
+      else
+        if respond_to?(_1)
+          public_send(_1, _2)
+        else
+          raise KeyError, "key not found: #{_1}"
+        end
+      end
+    end
+  end
+
   ##
   # Returns (or sets) the tool name
   # @param [String, nil] name The tool name

data/lib/llm/transformer/null.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class LLM::Transformer
+  ##
+  # An {LLM::Transformer::Null LLM::Transformer::Null} is a
+  # transformer that does nothing. It is used as the default when
+  # no transformer strategy is configured.
+  #
+  # It returns the given message unchanged.
+  class Null < self
+    ##
+    # @param [LLM::Message] message
+    #  The message to transform
+    # @param [Hash] opts
+    #  Ignored
+    # @return [LLM::Message]
+    def call(message:, **opts)
+      message
+    end
+  end
+end

data/lib/llm/transformer.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # {LLM::Transformer LLM::Transformer} is the superclass for
+  # message transformers in llm.rb.
+  #
+  # A transformer is bound to a context and rewrites a single
+  # message before it is sent to the provider. Each subclass
+  # implements a different transformation: it takes a message in
+  # {#call} and returns a message. {LLM::Transformer::Null} is a
+  # no-op (the default).
+  #
+  # A transformer may mutate the message in place or return a new
+  # one. Either way, the returned message is what gets sent.
+  class Transformer
+    require_relative "transformer/null"
+
+    ##
+    # @return [LLM::Context]
+    attr_reader :ctx
+
+    ##
+    # @param ctx [LLM::Context, LLM::Agent]
+    # @return [LLM::Transformer]
+    def initialize(ctx)
+      @ctx = LLM::Agent === ctx ? ctx.instance_variable_get(:@ctx) : ctx
+    end
+
+    ##
+    # @abstract
+    # @param [LLM::Message] message
+    #  The message to transform
+    # @param [Hash] opts
+    #  Per-call options
+    # @return [LLM::Message]
+    def call(message:, **opts)
+      raise NotImplementedError
+    end
+
+    private
+
+    ##
+    # @return [LLM::Stream]
+    def stream
+      @ctx.params[:stream]
+    end
+
+    ##
+    # @return [LLM::Buffer]
+    def messages
+      @ctx.messages
+    end
+  end
+end

data/lib/llm/version.rb

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

data/lib/llm.rb

@@ -7,7 +7,7 @@
 #
 # @example The three-step workflow
 #   require "llm"
-#   llm = LLM.deepseek(key: ENV["KEY"])           # 1. pick a provider
+#   llm = LLM.deepseek(key: ENV["KEY"])            # 1. pick a provider
 #   agent = LLM::Agent.new(llm, stream: $stdout)   # 2. create an agent
 #   agent.talk "Hello world"                       # 3. talk to it
 #
@@ -17,6 +17,7 @@ module LLM
   require "stringio"
   require "securerandom"
   require_relative "llm/compactor"
+  require_relative "llm/transformer"
   require_relative "llm/json_adapter"
   require_relative "llm/tracer"
   require_relative "llm/error"
@@ -40,7 +41,7 @@ module LLM
   require_relative "llm/stream"
   require_relative "llm/provider"
   require_relative "llm/context"
-  require_relative "llm/loop_guard"
+  require_relative "llm/guard"
   require_relative "llm/agent"
   require_relative "llm/buffer"
   require_relative "llm/function"
@@ -218,6 +219,15 @@ module LLM
     LLM::ZAI.new(**)
   end
 
+  ##
+  # @param key (see LLM::Moonshot#initialize)
+  # @param host (see LLM::Moonshot#initialize)
+  # @return (see LLM::Moonshot#initialize)
+  def moonshot(**)
+    lock(:require) { require_relative "llm/providers/moonshot" unless defined?(LLM::Moonshot) }
+    LLM::Moonshot.new(**)
+  end
+
   ##
   # @param [Hash] opts
   #  MCP client options

data/llm.gemspec

@@ -30,6 +30,7 @@ DESCRIPTION
     "lib/*.rb", "lib/**/*.rb",
     "data/*.json", "CHANGELOG.md",
     "resources/deepdive.md",
+    "resources/deepdive/*/*.md",
     "llm.gemspec", "bin/llm.rb"
   ]
   spec.executables = ["llm.rb"]

data/resources/deepdive/advanced/cancellation.md

@@ -0,0 +1,74 @@
+
+## Cancellation
+
+### Introduction
+
+#### Overview
+
+Cancellation lets you abort a model request mid-stream and interrupt
+any tools that are currently executing. The user changes their mind.
+The model goes off course. A tool hangs. In all three cases,
+cancellation stops the work and reclaims the tokens.
+
+#### How it works
+
+When you want to cancel an active request or tool call, call
+[`LLM::Agent#cancel!`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#cancel!)
+or
+[`LLM::Context#cancel!`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#cancel!)
+from any thread. Two things
+happen at once:
+
+[`LLM::Interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM/Interrupt.html)
+is raised on the thread where
+[`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk)
+or
+[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk)
+is running, so the caller
+can rescue it and know the request was cancelled.
+
+At the same time,
+[`LLM::Interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM/Interrupt.html)
+is raised on every active tool.
+A tool running in a thread gets it on that thread. A tool in a
+fiber gets it on that fiber. A tool in a forked process gets it
+via a message over the control channel. Pending tools (not yet
+started) are cancelled through
+[`LLM::Function#cancel`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#cancel)
+without ever being executed.
+
+The transport layer also cancels the in-flight HTTP request.
+
+```ruby
+require "llm"
+
+llm = LLM.deepseek(key: ENV["DEEPSEEK_SECRET"])
+agent = LLM::Agent.new(llm)
+queue = Queue.new
+
+Thread.new do
+  queue.push(nil)
+  sleep(2)
+  agent.cancel!
+end
+
+begin
+  queue.pop
+  agent.talk "write me a very long poem", stream: $stdout
+rescue LLM::Interrupt
+  puts "request cancelled!"
+end
+```
+
+#### Why would I use it?
+
+Cancellation prevents wasted time and tokens when the model goes
+off course, the user changes their mind, or a tool hangs. A forked
+tool that enters an infinite loop would run forever without it.
+
+#### Notes
+
+The `:ractor` strategy delivers the interrupt through ractor
+message passing. The `:fork` strategy delivers it via a message
+over the xchan control channel. All other strategies raise the
+exception directly on the executing thread or fiber.