llm.rb 12.6.0 → 13.0.0

data/lib/llm/function/thread/group.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module LLM::Function::Thread
+  ##
+  # Wraps an array of {Thread::Task} objects for concurrent
+  # thread-based execution. Interrupts all tasks and waits
+  # for them to complete.
+  class Group < LLM::Function::Group
+    ##
+    # @param [Array<LLM::Function::Thread::Task>] tasks
+    def initialize(tasks)
+      @tasks = tasks
+    end
+
+    ##
+    # @return [nil]
+    def spawn
+      @tasks.each(&:spawn)
+      nil
+    ensure
+      @spawned = true
+    end
+
+    ##
+    # @return [Boolean]
+    def alive?
+      @tasks.any?(&:alive?)
+    end
+
+    ##
+    # @return [nil]
+    def interrupt!
+      @tasks.each(&:interrupt!)
+      nil
+    end
+    alias_method :cancel!, :interrupt!
+
+    ##
+    # @return [Array<LLM::Function::Return>]
+    def wait
+      spawn unless @spawned
+      @tasks.map(&:wait)
+    end
+    alias_method :value, :wait
+  end
+end

data/lib/llm/function/thread/task.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module LLM::Function::Thread
+  ##
+  # {LLM::Function::Thread::Task LLM::Function::Thread::Task}
+  # wraps a function call in a background thread for concurrent
+  # tool execution. The thread is created lazily when {#wait} is
+  # called, not when the task is constructed — so you can build
+  # a task, pass it around, and decide when to run it.
+  #
+  # Interrupting a running task raises {LLM::Interrupt} inside
+  # the thread, which stops the tool call mid-flight. The thread
+  # is created with `report_on_exception` disabled so unhandled
+  # exceptions propagate through {#wait} instead of to stderr.
+  class Task < LLM::Function::Task
+    ##
+    # @param [LLM::Function] fn
+    # @param [Hash] options
+    def initialize(fn, options = {})
+      super
+    end
+
+    ##
+    # @return [nil]
+    def spawn
+      @thread = ::Thread.new { function.call }
+      @thread.report_on_exception = false
+      nil
+    end
+
+    ##
+    # @return [Boolean]
+    def alive?
+      @thread&.alive? || false
+    end
+
+    ##
+    # @return [nil]
+    def interrupt!
+      @thread&.raise(LLM::Interrupt) if @thread&.alive?
+      function.interrupt!
+      nil
+    end
+    alias_method :cancel!, :interrupt!
+
+    ##
+    # @return [LLM::Function::Return]
+    def wait
+      spawn unless @thread
+      @thread.value
+    end
+    alias_method :value, :wait
+
+    ##
+    # @return [Class]
+    def group_class
+      LLM::Function::Thread::Group
+    end
+  end
+end

data/lib/llm/function.rb

@@ -2,29 +2,30 @@
 
 ##
 # The {LLM::Function LLM::Function} class represents a local
-# function that can be called by an LLM.
+# function that can be called by an LLM. Most users should define
+# tools as subclasses of {LLM::Tool} instead — Function is the
+# lower-level building block that Tool wraps.
 #
-# @example example #1
-#   LLM.function(:system) do |fn|
-#     fn.name "system"
-#     fn.description "Runs system commands"
-#     fn.params do |schema|
-#       schema.object(command: schema.string.required)
-#     end
-#     fn.define do |command:|
-#       {success: Kernel.system(command)}
+# @example Tool subclass (preferred for most users)
+#   class ReadFile < LLM::Tool
+#     name "read-file"
+#     description "Read a file from disk"
+#     parameter :path, String, "The filename or path"
+#     required %i[path]
+#
+#     def call(path:)
+#       {contents: File.read(path)}
 #     end
 #   end
 #
-# @example example #2
-#   class System < LLM::Tool
-#     name "system"
-#     description "Runs system commands"
-#     params do |schema|
+# @example Inline function (block-form DSL)
+#   LLM.function(:run_command) do |fn|
+#     fn.name "run-command"
+#     fn.description "Runs a shell command"
+#     fn.params do |schema|
 #       schema.object(command: schema.string.required)
 #     end
-#
-#     def call(command:)
+#     fn.define do |command:|
 #       {success: Kernel.system(command)}
 #     end
 #   end
@@ -32,16 +33,21 @@ class LLM::Function
   require_relative "function/registry"
   require_relative "function/tracing"
   require_relative "function/array"
-  require_relative "function/call_group"
-  require_relative "function/call_task"
+  require_relative "function/group"
+  require_relative "function/sequential/group"
   require_relative "function/task"
-  require_relative "function/thread_group"
-  require_relative "function/fiber_group"
-  require_relative "function/task_group"
+  require_relative "function/sequential/task"
+  require_relative "function/thread/task"
+  require_relative "function/fiber/task"
+  require_relative "function/async/reactor"
+  require_relative "function/async/task"
+  require_relative "function/thread/group"
+  require_relative "function/fiber/group"
+  require_relative "function/async/group"
   require_relative "function/fork"
-  require_relative "function/fork_group"
+  require_relative "function/fork/group"
   require_relative "function/ractor"
-  require_relative "function/ractor_group"
+  require_relative "function/ractor/group"
 
   extend LLM::Function::Registry
   prepend LLM::Function::Tracing
@@ -213,70 +219,60 @@ class LLM::Function
 
   ##
   # Call the function
-  # @return [LLM::Function::Return] The result of the function call
+  # @return [LLM::Function::Return]
   def call
-    call_function
+    llm = @tracer&.llm
+    llm ? llm.with_tracer(@tracer) { call_function } : call_function
   ensure
     @called = true
   end
 
+
   ##
-  # Calls the function concurrently.
-  #
-  # This is the low-level method that powers concurrent tool execution.
-  # Prefer the collection methods on {LLM::Context#functions} for most
-  # use cases: {LLM::Function::Array#call}, {LLM::Function::Array#wait},
-  # or {LLM::Function::Array#spawn}.
+  # Returns a function as a {LLM::Function::Task LLM::Function::Task}.
   #
   # @example
-  #   # Normal usage (via collection)
-  #   ctx.talk(ctx.functions.wait)
+  #   # As a group
+  #   ctx.talk(ctx.pending_functions.wait)
   #
-  #   # Direct usage (uncommon)
-  #   task = tool.spawn(:thread)
+  #   # As a task
+  #   task = tool.task(:thread)
   #   result = task.value
   #
   # @param [Symbol] strategy
   #   Controls concurrency strategy:
-  #   - `:call`: Call the function sequentially without spawning
+  #   - `:sequential`: Call the function sequentially
   #   - `:thread`: Use threads
-  #   - `:task`: Use async tasks (requires async gem)
+  #   - `:async`: Use async tasks (requires async gem)
   #   - `:fork`: Use a forked child process (requires xchan.rb support)
   #   - `:fiber`: Use scheduler-backed fibers (requires Fiber.scheduler)
-  #   - `:fork`: Use a forked child process (requires xchan.rb support)
   #   - `:ractor`: Use Ruby ractors (class-based tools only; MCP tools are not supported)
   #
   # @return [LLM::Function::Task]
   #   Returns a task whose `#value` is an {LLM::Function::Return}.
-  def spawn(strategy)
-    task = case strategy
-    when :call
-      CallTask.new(self)
-    when :task
+  def task(strategy, options = {})
+    case strategy
+    when :sequential
+      Sequential::Task.new(self, options)
+    when :async
       LLM.require "async" unless defined?(::Async)
-      Async { call! }
+      Async::Task.new(self, options)
     when :thread
-      Thread.new { call! }.tap { _1.report_on_exception = false }
+      Thread::Task.new(self, options)
     when :fiber
-      raise ArgumentError, "Fiber concurrency requires Fiber.scheduler" unless Fiber.scheduler
-      Fiber.schedule { call! }
+      Fiber::Task.new(self, options)
     when :fork
-      LLM.require "xchan" unless defined?(::Chan::UNIXSocket)
-      span = @tracer&.on_tool_start(id:, name:, arguments:, model:)
-      Fork::Task.new(self, tracer: @tracer, span:).spawn
+      LLM.require "xchan", "~> 0.22" unless defined?(::Chan::UNIXSocket)
+      Fork::Task.new(self, options.merge(tracer: @tracer))
     when :ractor
       raise LLM::RactorError, "Ractor concurrency only supports class-based tools" unless Class === @runner
       if @runner.respond_to?(:skill?) && @runner.skill?
         raise LLM::RactorError, "Ractor concurrency does not support skill-backed tools"
       end
-      span = @tracer&.on_tool_start(id:, name:, arguments:, model:)
-      Ractor::Task.new(@runner, id, name, arguments, tracer: @tracer, span:).spawn
+      Ractor::Task.new(self, options.merge(runner_class: @runner, id:, name:, arguments:, tracer: @tracer, model:))
     else
-      raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :call, :thread, :task, :fiber, :fork, or :ractor"
+      raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :sequential, :thread, :fiber, :async, :fork, or :ractor"
     end
-    Task.new(task, self)
-  ensure
-    @called = true
   end
 
   ##
@@ -285,7 +281,7 @@ class LLM::Function
   #   llm = LLM.openai(key: ENV["KEY"])
   #   ctx = LLM::Context.new(llm, tools: [fn1, fn2])
   #   ctx.talk "I want to run the functions"
-  #   ctx.talk ctx.functions.map(&:cancel)
+  #   ctx.talk ctx.pending_functions.map(&:cancel)
   # @return [LLM::Function::Return]
   def cancel(reason: "function call cancelled")
     Return.new(id, name, {cancelled: true, reason:})
@@ -387,10 +383,4 @@ class LLM::Function
   rescue => ex
     Return.new(id, name, {error: true, type: ex.class.name, message: ex.message})
   end
-
-  def call!
-    llm = @tracer&.llm
-    return call unless llm.respond_to?(:with_tracer)
-    llm.with_tracer(@tracer) { call }
-  end
 end

data/lib/llm/loop_guard.rb

@@ -9,8 +9,7 @@
 # should be blocked before the loop keeps going.
 #
 # {LLM::LoopGuard LLM::LoopGuard} detects when a context is repeating the same
-# tool-call pattern instead of making progress. It is directly inspired by
-# General Intelligence Systems and its doom-loop detection approach.
+# tool-call pattern instead of making progress.
 #
 # The public interface is intentionally small:
 # - `call(ctx)` returns `nil` when no intervention is needed

data/lib/llm/mcp.rb

@@ -13,6 +13,28 @@
 # An MCP client is stateful. Coordinate lifecycle operations such as
 # {#start} and {#stop}; request methods can be issued concurrently and
 # responses are matched by JSON-RPC id.
+#
+# @example stdio transport
+#   llm   = LLM.deepseek(key: ENV["KEY"])
+#   mcp   = LLM::MCP.stdio(argv: ["npx", "-y", "@forgejo/mcp-server"])
+#   agent = LLM::Agent.new(llm)
+#
+#   # Preferred: session keeps one process alive across multiple calls
+#   mcp.session do
+#     agent.talk "What's happening on forgejo?", tools: mcp.tools
+#   end
+#
+#   # Also works: one-shot, spawns a new process per call
+#   agent.talk "What's happening on forgejo?", tools: mcp.tools
+#
+# @example HTTP transport
+#   mcp = LLM::MCP.http(
+#     url: "https://api.githubcopilot.com/mcp/",
+#     headers: {"Authorization" => "Bearer #{ENV.fetch('GITHUB_PAT')}"},
+#     transport: :net_http_persistent
+#   )
+#   agent = LLM::Agent.new(llm)
+#   agent.talk "What's happening on GitHub?", tools: mcp.tools
 class LLM::MCP
   require_relative "mcp/error"
   require_relative "mcp/command"

data/lib/llm/object.rb

@@ -133,7 +133,8 @@ class LLM::Object < BasicObject
   # @return [Object]
   def fetch(k = UNDEFINED, *args, &b)
     return SINGLETON.get(@h, :fetch) if k.equal?(UNDEFINED)
-    @h.fetch(SINGLETON.key(@h, k), *args, &b)
+    key = SINGLETON.key(@h, k)
+    @h.fetch(key || k, *args, &b)
   end
 
   ##

data/lib/llm/provider.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 ##
-# The Provider class represents an abstract class for
-# LLM (Language Model) providers.
+# The Provider class is the abstract base for LLM service integrations.
+# Most users interact with providers through {LLM::Agent} or
+# {LLM::Context} rather than calling {#complete} directly.
 #
 # @abstract
 class LLM::Provider
@@ -82,7 +83,9 @@ class LLM::Provider
   end
 
   ##
-  # Provides an interface to the chat completions API
+  # Provides an interface to the chat completions API.
+  # Most users should use {LLM::Context#talk} or {LLM::Agent#talk} instead.
+  #
   # @example
   #   llm = LLM.openai(key: ENV["KEY"])
   #   messages = [{role: "system", content: "Your task is to answer all of my questions"}]

data/lib/llm/providers/google.rb

@@ -209,11 +209,11 @@ module LLM
       role, model, stream = params.delete(:role),
                             params.delete(:model),
                             LLM::Stream.try(params.delete(:stream))
-      [params.merge!(stream: stream.enabled?), stream, tools, role, model]
+      [params, stream, tools, role, model]
     end
 
     def build_complete_request(prompt, params, role, model, stream)
-      action = stream ? "streamGenerateContent?key=#{@key}&alt=sse" : "generateContent?key=#{@key}"
+      action = stream.enabled? ? "streamGenerateContent?key=#{@key}&alt=sse" : "generateContent?key=#{@key}"
       model.respond_to?(:id) ? model.id : model
       path = ["/v1beta/models/#{model}", action].join(":")
       req  = LLM::Transport::Request.post(path, headers)

data/lib/llm/repl/command.rb

@@ -11,6 +11,17 @@ class LLM::Repl
     SINGLETON = self
     private_constant :UNDEFINED, :SINGLETON
 
+    ##
+    # @param [String] str
+    #  An input string
+    # @return [Array<String>]
+    #  An array of command names who match the input string
+    def self.complete(str)
+      registry.keys.select do |name|
+        name.start_with?(str[1..])
+      end
+    end
+
     ##
     # @api private
     Parameter = Struct.new(:name, :type, :description, :options, :index, :value) do
@@ -62,31 +73,37 @@ class LLM::Repl
       if input != UNDEFINED
         return nil unless input[0] == "/"
         n, = input.split(" ")
-        registry.find { n[1..] == _1.name }
+        registry.values.find { n[1..] == _1.name }
       elsif name != UNDEFINED
-        registry.find { name == _1.name }
+        registry.values.find { name == _1.name }
       else
         raise ArgumentError, "provide either an input or a name"
       end
     end
 
     ##
-    # @param [LLM::Repl::Command] command
+    # @param [LLM::Repl::Command] outer
     #  A new subclass
     # @return [void]
-    def self.inherited(command)
+    def self.inherited(outer)
       LLM.lock(:inherited) do
-        registry << command
-        command.instance_variable_set(:@parameters, {})
-        command.define_singleton_method(:inherited) { |command| SINGLETON.inherited(command) }
+        @registry[outer] = outer
+        outer.instance_variable_set(:@parameters, {})
+        outer.define_singleton_method(:inherited) do |inner|
+          SINGLETON.inherited(inner)
+          inner.instance_variable_set(:@name, outer.instance_variable_get(:@name))
+          inner.instance_variable_set(:@description, outer.instance_variable_get(:@description))
+          inner.instance_variable_set(:@parameters, outer.instance_variable_get(:@parameters))
+        end
       end
     end
 
     ##
     # @return [Array<LLM::Repl::Command]
     def self.registry
-      @registry ||= []
+      @registry.transform_keys(&:name)
     end
+    @registry = {}
 
     ##
     # Set or get a command name.
@@ -142,11 +159,20 @@ class LLM::Repl
       end
     end
 
+    ##
+    # @return [LLM::Repl]
+    attr_reader :repl
+
+    ##
+    # @return [LLM::Agent]
+    attr_reader :agent
+
     ##
     # @param [LLM::Repl] repl
     # @return [LLM::Repl::Command]
     def initialize(repl)
       @repl = repl
+      @agent = repl.agent
     end
 
     ##
@@ -191,6 +217,7 @@ class LLM::Repl
       self.class.parameters
     end
 
+    require_relative "commands/compact"
     require_relative "commands/exit"
     require_relative "commands/help"
   end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class LLM::Repl
+  ##
+  # The 'compact' command frees space in the
+  # context window and llm.rb is designed to
+  # support multiple compaction strategies with
+  # different trade offs. This command, though,
+  # uses the 'truncate' strategy. See
+  # {LLM::Compactor::Truncate LLM::Compactor::Truncate}
+  # for more details.
+  class Command::Compact < Command
+    name "compact"
+    description "frees space in the context window"
+    parameter :n, String, "the number of messages to keep"
+
+    ##
+    # @return [void]
+    def call(n: 128)
+      write("compact in progress\n")
+      compactor.call(keep: n)
+      write("compact complete\n\n")
+    end
+
+    private
+
+    ##
+    # @return [LLM::Compactor::Truncate]
+    def compactor
+      @compactor ||= LLM::Compactor::Truncate.new(agent)
+    end
+  end
+end

data/lib/llm/repl/input.rb

@@ -12,16 +12,30 @@ class LLM::Repl
       F: Curses::KEY_CTRL_F,
       K: Curses::KEY_CTRL_K,
       Y: Curses::KEY_CTRL_Y,
-      D: Curses::KEY_CTRL_D
+      D: Curses::KEY_CTRL_D,
+      P: Curses::KEY_CTRL_P,
+      N: Curses::KEY_CTRL_N
     }
 
+    ##
+    # This hash tracks how many times a given key
+    # was pressed repeatedly without being
+    # interrupted by another key. The previous key
+    # is reset to 0 when a different key is pressed.
+    REPEATS = {}
+    REPEATS.default = 0
+
     UP        = Curses::Key::UP
     DOWN      = Curses::Key::DOWN
     LEFT      = Curses::Key::LEFT
     RIGHT     = Curses::Key::RIGHT
+    PGUP      = Curses::KEY_PPAGE
+    PGDOWN    = Curses::KEY_NPAGE
+
+    TAB       = 9
     ESC       = 27
-    ENTER     = [Curses::Key::ENTER, 10, 13]
-    BACKSPACE = [Curses::Key::BACKSPACE, 127]
+    ENTER     = 10
+    BACKSPACE = 127
 
     ##
     # Threshold in seconds. If characters arrive faster than
@@ -35,21 +49,24 @@ class LLM::Repl
     attr_reader :buffer
 
     ##
-    # @param [Boolean] bool
+    # @param [Boolean] value
     # @return [void]
     attr_writer :paste
 
     ##
-    # @param [LLM::Agent] agent
+    # @param [LLM::Repl] repl
     # @return [LLM::Repl::Input]
-    def initialize(agent, options = {})
-      @agent = agent
-      @provider = agent.llm.name
+    def initialize(repl, options = {})
+      @name = repl.name
+      @agent = repl.agent
+      @provider = @agent.llm.name
       @buffer = +""
       @cursor = 0
       @scroll = 0
       @height = options.fetch(:height, 3)
       @last_char_at = nil
+      @memory = @agent.messages.select(&:user?).map(&:content)
+      @walker = Walker.new(@memory)
       @paste = false
     end
 
@@ -59,8 +76,28 @@ class LLM::Repl
     # @return [Symbol, nil]
     def on_char(window, char, now)
       is_paste = lambda { @last_char_at and (now - @last_char_at) < PASTE_THRESHOLD }
-      if ESC == char
+      if char and @char != char
+        REPEATS[@char] = 0
+      end
+      if PGUP == char
+        (window.rows - 3).times { window.scroll_up }
+        :pageup
+      elsif PGDOWN == char
+        (window.rows - 3).times { window.scroll_down }
+        :pagedown
+      elsif TAB == char
+        autocomplete
+        :tab
+      elsif ESC == char
         @agent.cancel!
+      elsif CTRL[:P] == char
+        @buffer = @walker.prev.dup
+        @cursor = @buffer.size
+        :ctrl_p
+      elsif CTRL[:N] == char
+        @buffer = @walker.next.dup
+        @cursor = @buffer.size
+        :ctrl_n
       elsif CTRL[:D] == char
         delete
         :ctrl_d
@@ -85,14 +122,16 @@ class LLM::Repl
       elsif char == RIGHT
         move_right
         :right
-      elsif BACKSPACE.include?(char)
+      elsif BACKSPACE == char
         backspace
         :backspace
-      elsif ENTER.include?(char)
+      elsif ENTER == char
         if @paste = is_paste.()
           insert("\n")
           :char
         else
+          @memory.push(@buffer.dup)
+          @walker.cursor = @memory.size
           :submit
         end
       elsif char == UP
@@ -108,19 +147,23 @@ class LLM::Repl
         nil
       end
     ensure
-      @last_char_at = now if char
+      if char
+        REPEATS[char] += 1
+        @last_char_at = now
+        @char = char
+      end
     end
 
     ##
     # @return [String]
     def to_s
-      "#{@provider}> #{@buffer}"
+      "#{prompt}#{@buffer}"
     end
 
     ##
     # @return [Integer]
     def cursor
-      prompt.length + @cursor
+      prompt.size + @cursor
     end
 
     ##
@@ -182,6 +225,28 @@ class LLM::Repl
       @cursor = [0, @cursor + 1].max
     end
 
+    ##
+    # @return [void]
+    def autocomplete
+      return unless @buffer[0] == "/"
+      ##
+      # This method implements a simple autocomplete
+      # that supports cycling through all known
+      # commands. When given tab in quick succession,
+      # we cycle to the nearest neighbour for the last
+      # full match. However, it's not based on similarity,
+      # it's just the next element in the array.
+      keys = LLM::Command.registry.keys
+      candidates = LLM::Command.complete(@buffer)
+      if REPEATS[TAB] >= 1
+        candidate = keys[keys.index(candidates[0]) + 1] || keys[0]
+      else
+        candidate = candidates[0]
+      end
+      @buffer = "/#{candidate}"
+      @cursor = @buffer.size
+    end
+
     ##
     # @return [void]
     def kill
@@ -238,7 +303,7 @@ class LLM::Repl
     end
 
     def prompt
-      "#{@provider}> "
+      "#{@provider}(#{@name})> "
     end
 
     def insert(char)