llm.rb 12.5.1 → 13.0.0

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module LLM::Function::Sequential
+  ##
+  # The {LLM::Function::Sequential::Task} class wraps a single
+  # direct function call behind the same task-like interface
+  # used by spawned concurrency modes.
+  class Task < LLM::Function::Task
+    ##
+    # @param [LLM::Function] fn
+    # @param [Hash] options
+    def initialize(fn, options = {})
+      @function = fn
+    end
+
+    ##
+    # @return [nil]
+    def spawn
+      # no-op — execution happens in wait
+    end
+
+    ##
+    # @return [Boolean]
+    def alive?
+      false
+    end
+
+    ##
+    # @return [nil]
+    def interrupt!
+      function.interrupt!
+      nil
+    end
+    alias_method :cancel!, :interrupt!
+
+    ##
+    # @return [LLM::Function::Return]
+    def wait
+      @result ||= function.call
+    end
+    alias_method :value, :wait
+
+    ##
+    # @return [Class]
+    def group_class
+      LLM::Function::Sequential::Group
+    end
+  end
+end

data/lib/llm/function/task.rb

@@ -2,71 +2,59 @@
 
 class LLM::Function
   ##
-  # The {LLM::Function::Task} class wraps a single concurrent function call and
-  # provides a small, uniform interface across threads, scheduler-backed fibers,
-  # and async tasks.
+  # This class is the superclass that all concurrency
+  # strategies must subclass in order to implement their
+  # own Task class. It provides a common interface that
+  # is the same across all concurrency strategies.
   class Task
     ##
-    # @return [Object]
-    attr_reader :task
+    # @return [LLM::Function]
+    attr_reader :function
 
     ##
-    # @return [LLM::Function, nil]
-    attr_reader :function
+    # @param [LLM::Function] fn
+    # @param [Hash] options
+    #  An optional set of options that are specific
+    #  to a given concurrency strategy.
+    def initialize(fn, options = {})
+      @function = fn
+    end
 
     ##
-    # @param [Thread, Fiber, Async::Task, Ractor, LLM::Function::Ractor::Task] task
-    # @param [LLM::Function, nil] function
-    # @return [LLM::Function::Task]
-    def initialize(task, function = nil)
-      @task = task
-      @function = function
+    # @abstract
+    # @return [nil]
+    def spawn
+      raise NotImplementedError
     end
 
     ##
+    # @abstract
     # @return [Boolean]
     def alive?
-      return task.alive? if task.respond_to?(:alive?)
-      false
+      raise NotImplementedError
     end
 
     ##
+    # @abstract
     # @return [nil]
     def interrupt!
-      task.interrupt! if task.respond_to?(:interrupt!)
-      function&.interrupt!
-      nil
+      raise NotImplementedError
     end
     alias_method :cancel!, :interrupt!
 
     ##
+    # @abstract
     # @return [LLM::Function::Return]
     def wait
-      if Thread === task
-        task.value
-      elsif Fiber === task
-        fiber.alive? ? scheduler.run : nil
-        task.value
-      else
-        task.wait
-      end
+      raise NotImplementedError
     end
     alias_method :value, :wait
 
     ##
+    # @abstract
     # @return [Class]
     def group_class
-      case task
-      when Thread then LLM::Function::ThreadGroup
-      when Fiber then LLM::Function::FiberGroup
-      else LLM::Function::TaskGroup
-      end
-    end
-
-    private
-
-    def scheduler
-      Fiber.scheduler
+      raise NotImplementedError
     end
   end
 end

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/tracing.rb

@@ -11,6 +11,8 @@ class LLM::Function
       result = super
       @tracer.on_tool_finish(result:, span:)
       result
+    rescue LLM::Interrupt
+      raise
     rescue => ex
       @tracer.on_tool_error(ex:, span:)
       raise(ex)

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! }
+      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:})
@@ -382,13 +378,9 @@ class LLM::Function
     runner = self.runner
     kwargs = arguments.respond_to?(:to_h) ? arguments.to_h.transform_keys(&:to_sym) : arguments
     Return.new(id, name, runner.call(**kwargs))
+  rescue LLM::Interrupt
+    raise
   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