llm.rb 12.6.0 → 13.1.0

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
@@ -198,7 +204,7 @@ class LLM::Function
         @params = params
       end
     else
-      @params
+      @params || LLM::Schema::Object.new({})
     end
   end
 
@@ -213,70 +219,59 @@ 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 +280,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 +382,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/anthropic.rb

@@ -88,7 +88,7 @@ module LLM
       {
         name: fn.name,
         description: fn.description,
-        input_schema: fn.params || {type: "object", properties: {}}
+        input_schema: fn.params.to_h
       }.compact
     end
 

data/lib/llm/providers/bedrock/request_adapter.rb

@@ -74,7 +74,7 @@ class LLM::Bedrock
           name: function.name,
           description: function.description,
           inputSchema: {
-            json: function.params || default_input_schema
+            json: function.params.to_h
           }
         }
       }

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/providers/mistral.rb

@@ -123,7 +123,7 @@ module LLM
     # @param [LLM::Function] fn
     # @return [Hash]
     def adapt_function(fn)
-      params = fn.params || {type: "object", properties: {}}
+      params = fn.params.to_h
       {
         type: "function",
         function: {name: fn.name, description: fn.description, parameters: params}

data/lib/llm/providers/ollama.rb

@@ -102,7 +102,7 @@ module LLM
     # @param [LLM::Function] fn
     # @return [Hash]
     def adapt_function(fn)
-      params = fn.params || {type: "object", properties: {}}
+      params = fn.params.to_h
       {
         type: "function", name: fn.name,
         function: {name: fn.name, description: fn.description, parameters: params}

data/lib/llm/providers/openai/responses.rb

@@ -92,7 +92,7 @@ class LLM::OpenAI
     def adapt_function(fn)
       {
         type: "function", name: fn.name, description: fn.description,
-        parameters: (fn.params || {type: "object", properties: {}}).to_h.merge(additionalProperties: false), strict: false
+        parameters: fn.params.to_h.merge(additionalProperties: false), strict: false
       }.compact
     end
 

data/lib/llm/providers/openai.rb

@@ -156,7 +156,7 @@ module LLM
     # @param [LLM::Function] fn
     # @return [Hash]
     def adapt_function(fn)
-      params = fn.params || {type: "object", properties: {}}
+      params = fn.params.to_h
       {
         type: "function", name: fn.name,
         function: {name: fn.name, description: fn.description, parameters: params}

data/lib/llm/repl/{transcript.rb → buffer.rb}

@@ -14,12 +14,13 @@ class LLM::Repl
   # 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
-
+  class Buffer
     ##
-    # @return [LLM::Repl::Transcript]
-    def initialize
+    # @param [LLM::Repl] repl
+    #  An instance of {LLM::Repl LLM::Repl}.
+    # @return [LLM::Repl::Buffer]
+    def initialize(repl)
+      @repl = repl
       @rows = [[]]
       @cursor = nil
       @snapshot = nil
@@ -27,37 +28,45 @@ class LLM::Repl
     end
 
     ##
-    # @param [String] chars
+    # @param [String, Array] chars
     # @param [Object] attrs
     # @param [Symbol] method
     # @return [void]
     def write(chars, attrs = nil, method: :append)
-      chunks = [{text: chars.to_s, attrs:}.compact]
+      case chars
+      when Array then chunks = chars
+      else chunks = [Node.new(chars.to_s, attrs)]
+      end
       self.method(method).call(chunks)
     end
 
     ##
-    # Appends Markdown to the transcript.
-    # @param [String] chars
+    # @param [String] user
+    # @param [String, Array] content
     # @param [Symbol] method
     # @return [void]
-    def markdown(chars, method: :append)
-      chunks = LLM::Repl::Markdown.new(chars).ast
-      self.method(method).call(chunks)
+    def write_message(user, content, method: :append)
+      chunks = [Node.new("#{user}: ", Curses::A_BOLD)]
+      case content
+      when Array then chunks.concat(content)
+      else chunks.push(Node.new(content))
+      end
+      chunks.push(Node.new("\n"))
+      write(chunks, method:)
     end
 
     ##
-    # Start the transcript.
+    # Open the buffer.
     # @return [void]
-    def start
+    def open
       @cursor = @rows.size - 1
       @snapshot = @rows.map(&:dup)
     end
 
     ##
-    # Finish the transcript.
+    # Close the buffer.
     # @return [void]
-    def finish
+    def close
       @cursor = nil
       @snapshot = nil
     end
@@ -93,9 +102,13 @@ class LLM::Repl
 
     private
 
+    ##
+    # @return [LLM::Repl]
+    attr_reader :repl
+
     ##
     # Appends a new row
-    # @param [Array<{text: String, attrs?: Integer}>] chunks
+    # @param [Array<Node>] chunks
     #  One or more chunks.
     # @return [void]
     def append(chunks)
@@ -104,12 +117,12 @@ class LLM::Repl
 
     ##
     # Replaces the content of the active row
-    # @param [Array<{text: String, attrs?: Integer}>] chunks
+    # @param [Array<Node>] chunks
     #  One or more chunks.
     # @return [void]
     def replace(chunks)
       @rows = @snapshot.map(&:dup)
-      append(chunks)
+      chunks.each { wrap(_1, @rows) }
     end
 
     ##
@@ -123,10 +136,10 @@ class LLM::Repl
       chunk[:text].to_s.each_char do |char|
         if char == "\n"
           rows << []
-        elsif char == " " and sum(rows.last) >= WIDTH
+        elsif char == " " and sum(rows.last) >= repl.width
           rows << []
         else
-          rows.last << {text: char, attrs:}.compact
+          rows.last << Node.new(char, attrs)
         end
       end
     end

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,20 +159,36 @@ 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
 
     ##
-    # Write a string to the transcript
-    # @param [String] str
+    # Write a string to the buffer
+    # @param [String] content
+    # @return [void]
+    def write(content)
+      write_message "command(#{self.class.name})", content
+    end
+
+    ##
+    # @param [String] user
+    # @param [String] content
     # @return [void]
-    def write(str, who: "command(#{self.class.name}): ")
-      @repl.write(who, Curses::A_BOLD)
-      @repl.write(str)
+    def write_message(user, content)
+      @repl.write_message(user, content)
     end
 
     ##
@@ -191,6 +224,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"
+      compactor.call(keep: n)
+      write "compact complete"
+    end
+
+    private
+
+    ##
+    # @return [LLM::Compactor::Truncate]
+    def compactor
+      @compactor ||= LLM::Compactor::Truncate.new(agent)
+    end
+  end
+end

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

@@ -11,13 +11,11 @@ class LLM::Repl
     # @return [void]
     def call(name: nil)
       if name.nil?
-        write("\n#{self.class.help}\n\n")
+        write(self.class.help)
       elsif command = LLM::Command.find_by(name:)
-        write("\n#{command.help}\n\n")
+        write(command.help)
       else
-        write "\nNo help for #{name} was found" \
-              "\nThat command doesn't exist." \
-              "\n\n"
+        write "no help for #{name} was found"
       end
     end
   end