llm.rb 12.0.0 → 12.1.0

data/data/zai.json

@@ -11,6 +11,7 @@
     "glm-4.7": {
       "id": "glm-4.7",
       "name": "GLM-4.7",
+      "description": "Mature GLM model for dependable coding, reasoning, and structured agent tasks",
       "family": "glm",
       "attachment": false,
       "reasoning": true,
@@ -50,6 +51,7 @@
     "glm-4.5v": {
       "id": "glm-4.5v",
       "name": "GLM-4.5V",
+      "description": "GLM vision model for visual reasoning, documents, and multimodal agents",
       "family": "glm",
       "attachment": true,
       "reasoning": true,
@@ -86,6 +88,7 @@
     "glm-4.5": {
       "id": "glm-4.5",
       "name": "GLM-4.5",
+      "description": "Hybrid-reasoning GLM release that made the 4.5 line broadly useful",
       "family": "glm",
       "attachment": false,
       "reasoning": true,
@@ -122,6 +125,7 @@
     "glm-4.7-flashx": {
       "id": "glm-4.7-flashx",
       "name": "GLM-4.7-FlashX",
+      "description": "Efficient GLM model for fast reasoning, coding, and agent workflows",
       "family": "glm-flash",
       "attachment": false,
       "reasoning": true,
@@ -158,6 +162,7 @@
     "glm-5.1": {
       "id": "glm-5.1",
       "name": "GLM-5.1",
+      "description": "Strong GLM coding model for agentic engineering, terminals, and repository generation",
       "family": "glm",
       "attachment": false,
       "reasoning": true,
@@ -197,6 +202,7 @@
     "glm-4.6": {
       "id": "glm-4.6",
       "name": "GLM-4.6",
+      "description": "Late GLM-4 workhorse for coding agents, reasoning, and structured tasks",
       "family": "glm",
       "attachment": false,
       "reasoning": true,
@@ -233,6 +239,7 @@
     "glm-5.2": {
       "id": "glm-5.2",
       "name": "GLM-5.2",
+      "description": "Open flagship GLM for long-horizon coding agents and million-token context work",
       "family": "glm",
       "attachment": false,
       "reasoning": true,
@@ -276,6 +283,7 @@
     "glm-4.6v": {
       "id": "glm-4.6v",
       "name": "GLM-4.6V",
+      "description": "GLM vision model for visual reasoning, documents, and multimodal agents",
       "family": "glm",
       "attachment": true,
       "reasoning": true,
@@ -312,6 +320,7 @@
     "glm-5v-turbo": {
       "id": "glm-5v-turbo",
       "name": "GLM-5V-Turbo",
+      "description": "Fast GLM vision model for screenshots, documents, and multimodal agent tasks",
       "family": "glm",
       "attachment": true,
       "reasoning": true,
@@ -353,6 +362,7 @@
     "glm-4.5-air": {
       "id": "glm-4.5-air",
       "name": "GLM-4.5-Air",
+      "description": "Lighter GLM-4.5 variant for fast coding assistance and cheaper agents",
       "family": "glm-air",
       "attachment": false,
       "reasoning": true,
@@ -389,6 +399,7 @@
     "glm-4.7-flash": {
       "id": "glm-4.7-flash",
       "name": "GLM-4.7-Flash",
+      "description": "Budget GLM lane for fast coding help, routing, and everyday automation",
       "family": "glm-flash",
       "attachment": false,
       "reasoning": true,
@@ -425,6 +436,7 @@
     "glm-4.5-flash": {
       "id": "glm-4.5-flash",
       "name": "GLM-4.5-Flash",
+      "description": "Efficient GLM model for fast reasoning, coding, and agent workflows",
       "family": "glm-flash",
       "attachment": false,
       "reasoning": true,
@@ -461,6 +473,7 @@
     "glm-5": {
       "id": "glm-5",
       "name": "GLM-5",
+      "description": "General GLM flagship for coding, analysis, and tool-heavy engineering workflows",
       "family": "glm",
       "attachment": false,
       "reasoning": true,
@@ -499,6 +512,7 @@
     "glm-5-turbo": {
       "id": "glm-5-turbo",
       "name": "GLM-5-Turbo",
+      "description": "Faster GLM-5 lane for coding agents that need lower latency",
       "family": "glm",
       "attachment": false,
       "reasoning": true,

data/lib/llm/agent.rb

@@ -61,7 +61,11 @@ module LLM
     #  Returns the current tools when no argument is provided
     def self.tools(*tools, &block)
       return @tools || [] if tools.empty? && !block
-      @tools = block || tools.flatten
+      if tools.size == 1 and tools.grep(Symbol).any?
+        @tools = tools.first
+      else
+        @tools = block || tools.flatten
+      end
     end
 
     ##
@@ -334,6 +338,15 @@ module LLM
       @tracer || @ctx.tracer
     end
 
+    ##
+    # @param [LLM::Tracer, nil] other
+    #  A tracer, or nil.
+    # @return [void]
+    def tracer=(other)
+      @ctx.tracer = other
+      @tracer = other
+    end
+
     ##
     # @return [LLM::Stream, #<<, nil]
     #  Returns a stream object, or nil
@@ -375,6 +388,17 @@ module LLM
       @ctx.context_window
     end
 
+    ##
+    # Start a minimalist repl that can interact
+    # with the agent and its current state. This
+    # method requires the 'curses' gem to be installed
+    # and available to require.
+    # @return [void]
+    def repl
+      require_relative "repl" unless defined?(::LLM::Repl)
+      LLM::Repl.new(self).start
+    end
+
     ##
     # @see LLM::Context#params
     # @return [Hash]

data/lib/llm/context.rb

@@ -421,6 +421,14 @@ module LLM
       @llm.tracer
     end
 
+    ##
+    # @param [LLM::Tracer, nil] other
+    #  A tracer, or nil.
+    # @return [void]
+    def tracer=(other)
+      @llm.tracer = nil
+    end
+
     ##
     # @return [LLM::Stream, #<<, nil]
     #  Returns a stream object, or nil

data/lib/llm/json_adapter.rb

@@ -38,11 +38,11 @@ module LLM
     def self.dump(obj, state = nil, **options)
       require "json" unless defined?(::JSON)
       if ::JSON::State === state
-        ::JSON.generate(obj, state)
+        ::JSON.generate(normalize(obj), state)
       elsif state
-        ::JSON.dump(obj, state, **options)
+        ::JSON.dump(normalize(obj), state, **options)
       else
-        ::JSON.dump(obj, **options)
+        ::JSON.dump(normalize(obj), **options)
       end
     end
 
@@ -59,6 +59,32 @@ module LLM
       require "json" unless defined?(::JSON)
       [::JSON::ParserError]
     end
+
+    ##
+    # JSON 3.0 compat
+    # Walks `obj` and encodes every string that is
+    # found into a UTF-8 compatible string.
+    def self.normalize(obj)
+      case obj
+      when String then normalize_string(obj)
+      when Array then obj.map { normalize(_1) }
+      when Hash then obj.map { [_1, normalize(_2)] }.to_h
+      when LLM::Object then obj.map { [_1, normalize(_2)] }.to_h
+      else obj
+      end
+    end
+    private_class_method :normalize
+
+    ##
+    # JSON 3.0 compat
+    # Normalizes a string as a UTF-8 encoded string
+    # that's compatible with the JSON spec.
+    def self.normalize_string(str)
+      return str if str.encoding == Encoding::UTF_8
+      str = (+str).force_encoding("UTF-8")
+      str.valid_encoding? ? str : str.scrub
+    end
+    private_class_method :normalize_string
   end
 
   ##

data/lib/llm/provider.rb

@@ -286,7 +286,7 @@ class LLM::Provider
   #  A tracer
   # @return [void]
   def tracer=(tracer)
-    @tracer = tracer
+    @tracer = tracer || LLM::Tracer::Null.new(self)
   end
 
   ##

data/lib/llm/providers/llamacpp.rb

@@ -23,7 +23,7 @@ module LLM
     ##
     # @param (see LLM::Provider#initialize)
     # @return [LLM::LlamaCpp]
-    def initialize(host: "localhost", port: 8080, ssl: false, **)
+    def initialize(host: "localhost", port: 8013, ssl: false, **)
       super
     end
 
@@ -71,11 +71,11 @@ module LLM
     end
 
     ##
-    # Returns the default model for chat completions
-    # @see https://ollama.com/library/qwen3 qwen3
-    # @return [String]
+    # Returns nil.
+    # Whatever model is served by llamacpp acts as the default.
+    # @return [nil]
     def default_model
-      "qwen3"
+      nil
     end
   end
 end

data/lib/llm/repl/input.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+class LLM::Repl
+  ##
+  # The {LLM::Repl::Input LLM::Repl::Input} class manages
+  # the editable input line shown at the bottom of the REPL.
+  # @api private
+  class Input
+    UP        = Curses::Key::UP
+    DOWN      = Curses::Key::DOWN
+    ENTER     = [Curses::Key::ENTER, 10, 13]
+    BACKSPACE = [Curses::Key::BACKSPACE, 127]
+    EOF       = [nil, 4]
+
+    ##
+    # @param [String, Symbol] provider
+    # @return [LLM::Repl::Input]
+    def initialize(provider)
+      @provider = provider
+      @buffer = +""
+    end
+
+    ##
+    # @param [LLM::Repl::Window] window
+    # @return [String, nil]
+    def readline(window)
+      catch(:done) do
+        @buffer.clear
+        loop do
+          on_char(window, window.getch)
+          window.redraw
+        end
+      end
+    end
+
+    ##
+    # @return [String]
+    def to_s
+      "> #{@buffer}"
+    end
+
+    private
+
+    def on_char(window, char)
+      if EOF.include?(char)
+        throw(:done, nil)
+      elsif BACKSPACE.include?(char)
+        @buffer.chop!
+      elsif ENTER.include?(char)
+        buf = @buffer.dup
+        @buffer.clear
+        throw(:done, buf)
+      elsif char == UP
+        window.scroll_up
+      elsif char == DOWN
+        window.scroll_down
+      elsif String === char
+        @buffer << char
+      else
+        # ???
+      end
+    end
+  end
+end

data/lib/llm/repl/status.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+class LLM::Repl
+  ##
+  # The {LLM::Repl::Status LLM::Repl::Status} class stores
+  # the small status line shown at the top of the REPL.
+  # @api private
+  class Status
+    ##
+    # @param [String, Symbol] provider
+    # @return [LLM::Repl::Status]
+    def initialize(provider)
+      @provider = provider
+      @text = "idle"
+    end
+
+    ##
+    # @return [String]
+    attr_reader :provider
+
+    ##
+    # @param [String] value
+    # @return [void]
+    attr_accessor :text
+
+    ##
+    # @return [String]
+    alias_method :to_s, :text
+  end
+end

data/lib/llm/repl/stream.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+class LLM::Repl
+  ##
+  # The {LLM::Repl::Stream LLM::Repl::Stream} class manages
+  # the stream for the {LLM::Repl LLM::Repl} class. This class
+  # has defined hooks that receive text, tool calls, and
+  # tool returns.
+  # @api private
+  class Stream < LLM::Stream
+    ##
+    # @param [LLM::Repl] repl
+    # @return [LLM::Repl::Stream]
+    def initialize(repl)
+      @repl = repl
+    end
+
+    ##
+    # @param [String] chars
+    #  One or more chars
+    # @return [void]
+    def on_content(chars)
+      @repl.write(chars)
+    end
+
+    ##
+    # @param [LLM::Function] tool
+    # @param [LLM::Function::Return, nil] error
+    # @return [void]
+    def on_tool_call(tool, error)
+      if error
+        @repl.status = "tool error: #{tool.name}"
+      else
+        @repl.status = "tool: #{tool.name}"
+      end
+    end
+
+    ##
+    # @param [LLM::Function] _tool
+    # @param [LLM::Function::Return] result
+    # @return [void]
+    def on_tool_return(_tool, result)
+      @repl.status = "tool done: #{result.name}"
+    end
+  end
+end

data/lib/llm/repl/transcript.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+class LLM::Repl
+  ##
+  # The {LLM::Repl::Transcript LLM::Repl::Transcript} class
+  # stores streamed output for the REPL.
+  # @api private
+  class Transcript
+    WIDTH = 80
+
+    ##
+    # @return [LLM::Repl::Transcript]
+    def initialize
+      @lines = [+""]
+      @offset = 0
+    end
+
+    ##
+    # @param [String] chars
+    # @return [void]
+    def write(chars)
+      chars.each_char { write_char(_1) }
+    end
+
+    ##
+    # @return [void]
+    def scroll_up(height)
+      max = [@lines.size - height, 0].max
+      @offset = [@offset + 1, max].min
+    end
+
+    ##
+    # @return [void]
+    def scroll_down
+      @offset = [@offset - 1, 0].max
+    end
+
+    ##
+    # @param [Integer] height
+    # @return [Array<String>]
+    def visible(height)
+      last = @lines.size - 1 - @offset
+      first = [last - height + 1, 0].max
+      @lines[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
+      end
+    end
+  end
+end

data/lib/llm/repl/window.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+class LLM::Repl
+  ##
+  # The {LLM::Repl::Window LLM::Repl::Window} class draws the
+  # curses screen for the REPL.
+  # @api private
+  class Window
+    ##
+    # @return [LLM::Repl::Status]
+    attr_reader :status
+
+    ##
+    # @return [LLM::Repl::Transcript]
+    attr_reader :transcript
+
+    ##
+    # @return [LLM::Repl::Input]
+    attr_reader :input
+
+    ##
+    # @param [LLM::Repl::Status] status
+    # @param [LLM::Repl::Transcript] transcript
+    # @param [LLM::Repl::Input] input
+    # @return [LLM::Repl::Window]
+    def initialize(status, transcript, input)
+      @status = status
+      @transcript = transcript
+      @input = input
+    end
+
+    ##
+    # @yield
+    # @return [void]
+    def open
+      Curses.init_screen
+      Curses.cbreak
+      Curses.noecho
+      Curses.stdscr.keypad(true)
+      yield
+    ensure
+      Curses.close_screen
+    end
+
+    ##
+    # @return [void]
+    def redraw
+      Curses.clear
+      draw_status
+      draw_transcript
+      draw_input
+      Curses.refresh
+    end
+
+    ##
+    # @return [Integer]
+    def rows
+      [Curses.lines - 3, 1].max
+    end
+
+    ##
+    # @return [Object]
+    def getch
+      Curses.getch
+    end
+
+    ##
+    # @return [void]
+    def scroll_up
+      transcript.scroll_up(rows)
+    end
+
+    ##
+    # @return [void]
+    def scroll_down
+      transcript.scroll_down
+    end
+
+    private
+
+    def draw_status
+      Curses.setpos(0, 0)
+      Curses.addstr(status.to_s)
+      provider = status.provider.to_s
+      Curses.setpos(0, [columns - provider.length, 0].max)
+      Curses.addstr(provider)
+    end
+
+    def draw_transcript
+      visible = transcript.visible(rows)
+      visible.each_with_index do |row, index|
+        Curses.setpos(index + 2, 0)
+        Curses.addstr(row)
+      end
+    end
+
+    def draw_input
+      Curses.setpos(Curses.lines - 1, 0)
+      Curses.clrtoeol
+      Curses.addstr(input.to_s)
+    end
+
+    def columns
+      Curses.cols
+    end
+  end
+end

data/lib/llm/repl.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+LLM.require "curses"
+
+module LLM
+  ##
+  # The {LLM::Repl LLM::Repl} class provides a small
+  # read-eval-print loop around an instance of
+  # {LLM::Agent LLM::Agent}.
+  #
+  # It can be used to keep talking to an agent after it
+  # has been set up or has performed a task. This can be
+  # useful when you want to confirm the agent handled the
+  # task correctly, or for it to correct course after a
+  # mistake was made.
+  class Repl
+    require_relative "repl/window"
+    require_relative "repl/status"
+    require_relative "repl/transcript"
+    require_relative "repl/input"
+    require_relative "repl/stream"
+
+    ##
+    # @param [LLM::Agent] agent
+    # @return [LLM::Repl]
+    def initialize(agent)
+      @agent = agent
+      @provider = agent.llm.name
+      @status = Status.new(@provider)
+      @transcript = Transcript.new
+      @input = Input.new(@provider)
+      @window = Window.new(@status, @transcript, @input)
+      @stream = Stream.new(self)
+    end
+
+    ##
+    # @return [void]
+    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")
+        end
+      end
+    end
+
+    ##
+    # @param [String] chars
+    # @return [void]
+    def write(chars)
+      transcript.write(chars)
+      window.redraw
+    end
+
+    ##
+    # @param [String] value
+    # @return [void]
+    def status=(value)
+      status.text = value
+      window.redraw
+    end
+
+    private
+
+    attr_reader :agent, :provider, :stream,
+                :status, :transcript, :input,
+                :window
+  end
+end

data/lib/llm/tools/chdir.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# frozen_string_literal
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::Chdir LLM::Tool::Chdir} class implements
+  # a tool that can change the current working directory.
+  class Chdir < self
+    name "chdir"
+    description "change the current working directory"
+    parameter :path, String, "the new working directory"
+    required %i[path]
+
+    ##
+    # @param [String] path
+    # @return [Hash]
+    def call(path:)
+      Dir.chdir(path)
+      {ok: true, cwd: path}
+    end
+  end
+end