llm.rb 6.1.0 → 8.0.0

data/lib/llm/function/array.rb

@@ -26,7 +26,8 @@ class LLM::Function
     #   Controls concurrency strategy:
     #   - `:thread`: Use threads
     #   - `:task`: Use async tasks (requires async gem)
-    #   - `:fiber`: Use raw fibers
+    #   - `:fiber`: Use scheduler-backed fibers (requires Fiber.scheduler)
+    #   - `:fork`: Use forked child processes
     #   - `:ractor`: Use Ruby ractors (class-based tools only; MCP tools are not supported)
     #
     # @return [LLM::Function::ThreadGroup, LLM::Function::TaskGroup, LLM::Function::FiberGroup, LLM::Function::Ractor::Group]
@@ -38,10 +39,12 @@ class LLM::Function
         ThreadGroup.new(map { |fn| fn.spawn(:thread) })
       when :fiber
         FiberGroup.new(map { |fn| fn.spawn(:fiber) })
+      when :fork
+        Fork::Group.new(map { |fn| fn.spawn(:fork) })
       when :ractor
         Ractor::Group.new(map { |fn| fn.spawn(:ractor) })
       else
-        raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :thread, :task, :fiber, or :ractor"
+        raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :thread, :task, :fiber, :fork, or :ractor"
       end
     end
 
@@ -53,7 +56,8 @@ class LLM::Function
     #   Controls concurrency strategy:
     #   - `:thread`: Use threads
     #   - `:task`: Use async tasks (requires async gem)
-    #   - `:fiber`: Use raw fibers
+    #   - `:fiber`: Use scheduler-backed fibers (requires Fiber.scheduler)
+    #   - `:fork`: Use forked child processes
     #   - `:ractor`: Use Ruby ractors (class-based tools only; MCP tools are not supported)
     #
     # @return [Array<LLM::Function::Return>]

data/lib/llm/function/fiber_group.rb

@@ -4,10 +4,10 @@ class LLM::Function
   ##
   # The {LLM::Function::FiberGroup} class wraps an array of
   # {Fiber} objects that are running {LLM::Function} calls
-  # concurrently using raw fibers.
+  # concurrently using scheduler-backed fibers.
   #
   # This class provides the same interface as {LLM::Function::ThreadGroup}
-  # but uses raw fibers for lightweight concurrency without the async gem.
+  # but uses scheduler-backed fibers for cooperative concurrency.
   #
   # @example
   #   llm = LLM.openai(key: ENV["KEY"])
@@ -90,10 +90,16 @@ class LLM::Function
     #   order as the original fibers.
     def wait
       @fibers.map do |fiber|
-        fiber.resume if fiber.alive?
+        fiber.alive? ? scheduler.run : nil
         fiber.value
       end
     end
     alias_method :value, :wait
+
+    private
+
+    def scheduler
+      Fiber.scheduler
+    end
   end
 end

data/lib/llm/function/fork/job.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+class LLM::Function
+  ##
+  # The {LLM::Function::Fork::Job} class represents a single fork-backed
+  # function call inside the child process.
+  #
+  # It is executed in the forked process and is responsible for running the
+  # resolved tool instance, handling control messages such as interrupts, and
+  # writing the final result back to the parent process.
+  class Fork::Job
+    ##
+    # @param [LLM::Function] function
+    # @param [LLM::Object] ch
+    # @return [LLM::Function::Fork::Job]
+    def initialize(function, ch)
+      @function = function
+      @ch = ch
+    end
+
+    ##
+    # @return [void]
+    def call
+      runner = @function.runner
+      controller = setup(runner)
+      @ch.result.write([:result, call!(runner)])
+    rescue => ex
+      @ch.result.write([:result, error(ex)])
+    ensure
+      controller&.kill
+      [@ch.control, @ch.result].each { _1.close unless _1.closed? }
+    end
+
+    private
+
+    def call!(runner)
+      kwargs = if Hash === @function.arguments
+        @function.arguments.transform_keys(&:to_sym)
+      else
+        @function.arguments
+      end
+      {id: @function.id, name: @function.name, value: runner.call(**kwargs)}
+    end
+
+    def error(ex)
+      {
+        id: @function.id,
+        name: @function.name,
+        value: {error: true, type: ex.class.name, message: ex.message}
+      }
+    end
+
+    def setup(runner)
+      ready = Queue.new
+      thread = Thread.new do
+        ready << true
+        kind = @ch.control.recv
+        next unless kind == :interrupt
+        hook = %i[on_cancel on_interrupt].find { runner.respond_to?(_1) }
+        runner.public_send(hook) if hook
+      rescue IOError, ArgumentError
+      end
+      ready.pop
+      thread
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+class LLM::Function
+  ##
+  # The {LLM::Function::Fork::Task} class wraps a fork-backed function call
+  # and exchanges control and result messages with the child process.
+  class Fork::Task
+    ##
+    # @param [LLM::Function] function
+    # @param [LLM::Tracer, nil] tracer
+    # @param [Object, nil] span
+    # @return [LLM::Function::Fork::Task]
+    def initialize(function, tracer: nil, span: nil)
+      @function = function
+      @tracer = tracer
+      @span = span
+      @waited = false
+    end
+
+    ##
+    # @return [LLM::Function::Fork::Task]
+    def spawn
+      @ch = LLM::Object.from(control: xchan(:marshal), result: xchan(:marshal))
+      @pid = Kernel.fork { Fork::Job.new(@function, @ch).call }
+      self
+    end
+
+    ##
+    # @return [Boolean]
+    def alive?
+      return false if @waited
+      result = ::Process.waitpid(@pid, ::Process::WNOHANG)
+      @waited = !result.nil?
+      !@waited
+    rescue Errno::ECHILD
+      @waited = true
+      false
+    end
+
+    ##
+    # @return [nil]
+    def interrupt!
+      return nil if @waited
+      @ch.control.write(:interrupt)
+      nil
+    rescue Errno::ESRCH, IOError
+      nil
+    end
+    alias_method :cancel!, :interrupt!
+
+    ##
+    # @return [LLM::Function::Return]
+    def wait
+      kind, data = @ch.result.recv
+      raise ArgumentError, "Unknown fork message: #{kind.inspect}" unless kind == :result
+      result = Return.new(data[:id], data[:name], data[:value])
+      reap
+      @tracer&.on_tool_finish(result:, span: @span)
+      result
+    ensure
+      reap
+      [@ch.control, @ch.result].each { _1.close unless _1.closed? }
+    end
+    alias_method :value, :wait
+
+    private
+
+    def reap
+      return if @waited
+      ::Process.waitpid(@pid)
+      @waited = true
+    rescue Errno::ECHILD
+      @waited = true
+    end
+  end
+end

data/lib/llm/function/fork.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class LLM::Function
+  module Fork
+    require_relative "fork/job"
+    require_relative "fork/task"
+  end
+end

data/lib/llm/function/fork_group.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+class LLM::Function
+  ##
+  # The {LLM::Function::Fork::Group} class wraps an array of
+  # {LLM::Function::Task} objects that are running in forked child processes.
+  class Fork::Group
+    ##
+    # @param [Array<LLM::Function::Task>] tasks
+    # @return [LLM::Function::Fork::Group]
+    def initialize(tasks)
+      @tasks = tasks
+    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
+      @tasks.map(&:wait)
+    end
+    alias_method :value, :wait
+  end
+end

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

@@ -19,9 +19,19 @@ class LLM::Function
     # @param [Object, nil] span
     # @return [LLM::Function::Ractor::Task]
     def initialize(runner_class, id, name, arguments, tracer: nil, span: nil)
+      @runner_class = runner_class
+      @id = id
+      @name = name
+      @arguments = arguments
       @tracer = tracer
       @span = span
-      @mailbox = Ractor::Mailbox.new(build_task(runner_class, id, name, arguments))
+    end
+
+    ##
+    # @return [LLM::Function::Ractor::Task]
+    def spawn
+      @mailbox = Ractor::Mailbox.new(build_task)
+      self
     end
 
     ##
@@ -49,8 +59,8 @@ class LLM::Function
 
     private
 
-    def build_task(runner_class, id, name, arguments)
-      ::Ractor.new(runner_class, id, name, arguments) do |runner_class, id, name, arguments|
+    def build_task
+      ::Ractor.new(@runner_class, @id, @name, @arguments) do |runner_class, id, name, arguments|
         LLM::Function::Ractor::Job.new(::Ractor.current, runner_class, id, name, arguments).call
       end
     end

data/lib/llm/function/task.rb

@@ -3,7 +3,8 @@
 class LLM::Function
   ##
   # The {LLM::Function::Task} class wraps a single concurrent function call and
-  # provides a small, uniform interface across threads, fibers, and async tasks.
+  # provides a small, uniform interface across threads, scheduler-backed fibers,
+  # and async tasks.
   class Task
     ##
     # @return [Object]
@@ -32,6 +33,7 @@ class LLM::Function
     ##
     # @return [nil]
     def interrupt!
+      task.interrupt! if task.respond_to?(:interrupt!)
       function&.interrupt!
       nil
     end
@@ -43,12 +45,18 @@ class LLM::Function
       if Thread === task
         task.value
       elsif Fiber === task
-        task.resume if task.alive?
+        fiber.alive? ? scheduler.run : nil
         task.value
       else
         task.wait
       end
     end
     alias_method :value, :wait
+
+    private
+
+    def scheduler
+      Fiber.scheduler
+    end
   end
 end

data/lib/llm/function.rb

@@ -36,6 +36,8 @@ class LLM::Function
   require_relative "function/thread_group"
   require_relative "function/fiber_group"
   require_relative "function/task_group"
+  require_relative "function/fork"
+  require_relative "function/fork_group"
   require_relative "function/ractor"
   require_relative "function/ractor_group"
 
@@ -209,7 +211,9 @@ class LLM::Function
   #   Controls concurrency strategy:
   #   - `:thread`: Use threads
   #   - `:task`: Use async tasks (requires async gem)
-  #   - `:fiber`: Use raw fibers
+  #   - `: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]
@@ -217,25 +221,26 @@ class LLM::Function
   def spawn(strategy)
     task = case strategy
     when :task
-      require "async" unless defined?(::Async)
+      LLM.require "async" unless defined?(::Async)
       Async { call! }
     when :thread
       Thread.new { call! }
     when :fiber
-      Fiber.new do
-        call!
-      ensure
-        Fiber.yield
-      end.tap(&:resume)
+      raise ArgumentError, "Fiber concurrency requires Fiber.scheduler" unless Fiber.scheduler
+      Fiber.schedule { call! }
+    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
     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:)
+      Ractor::Task.new(@runner, id, name, arguments, tracer: @tracer, span:).spawn
     else
-      raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :thread, :task, :fiber, or :ractor"
+      raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :thread, :task, :fiber, :fork, or :ractor"
     end
     Task.new(task, self)
   ensure
@@ -306,6 +311,15 @@ class LLM::Function
     end
   end
 
+  ##
+  # Returns the bound function runner instance.
+  # @return [Object]
+  def runner
+    runner = Class === @runner ? @runner.new : @runner
+    runner.tracer = @tracer if runner.respond_to?(:tracer=)
+    runner
+  end
+
   private
 
   def format_openai(provider)
@@ -331,8 +345,7 @@ class LLM::Function
   # @return [LLM::Function::Return]
   #   Returns a Return object with either the function result or error information.
   def call_function
-    runner = ((Class === @runner) ? @runner.new : @runner)
-    runner.tracer = @tracer if runner.respond_to?(:tracer=)
+    runner = self.runner
     kwargs = Hash === arguments ? arguments.transform_keys(&:to_sym) : arguments
     Return.new(id, name, runner.call(**kwargs))
   rescue => ex

data/lib/llm/loop_guard.rb

@@ -10,8 +10,7 @@
 #
 # {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' Brute runtime and its doom-loop detection
-# approach.
+# General Intelligence Systems and its doom-loop detection approach.
 #
 # The public interface is intentionally small:
 # - `call(ctx)` returns `nil` when no intervention is needed
@@ -22,14 +21,6 @@
 # {LLM::Agent LLM::Agent} enables this guard by default through its wrapped
 # context.
 #
-# Brute is MIT licensed. The relevant license grant is:
-#
-#   Permission is hereby granted, free of charge, to any person obtaining a copy
-#   of this software and associated documentation files (the "Software"), to deal
-#   in the Software without restriction, including without limitation the rights
-#   to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-#   copies of the Software, and to permit persons to whom the Software is
-#   furnished to do so.
 class LLM::LoopGuard
   ##
   # The default number of repeated tool-call patterns required before

data/lib/llm/mcp/command.rb

@@ -34,7 +34,7 @@ class LLM::MCP
     # @return [void]
     def start
       raise LLM::MCP::Error, "MCP command is already running" if alive?
-      @stdout, @stderr, @stdin = 3.times.map { Pipe.new }
+      @stdout, @stderr, @stdin = 3.times.map { LLM::Pipe.new }
       @buffers.clear
       @pid = Process.spawn(env.to_h, *argv, {chdir: cwd, out: stdout.w, err: stderr.w, in: stdin.r}.compact)
       [stdin.close_reader, [stdout, stderr].each(&:close_writer)]

data/lib/llm/mcp/transport/http.rb

@@ -104,12 +104,12 @@ module LLM::MCP::Transport
     # Configures the transport to use a persistent HTTP connection pool
     # via the optional dependency [Net::HTTP::Persistent](https://github.com/drbrain/net-http-persistent)
     # @example
-    #   mcp = LLM.mcp(http: {url: "https://example.com/mcp"}).persistent
+    #   mcp = LLM::MCP.http(url: "https://example.com/mcp", persistent: true)
     #   # do something with 'mcp'
     # @return [LLM::MCP::Transport::HTTP]
     def persist!
       LLM.lock(:mcp) do
-        require "net/http/persistent" unless defined?(Net::HTTP::Persistent)
+        LLM.require "net/http/persistent" unless defined?(Net::HTTP::Persistent)
         unless LLM::MCP.clients.key?(key)
           http = Net::HTTP::Persistent.new(name: self.class.name)
           http.read_timeout = timeout

data/lib/llm/mcp.rb

@@ -19,17 +19,18 @@ class LLM::MCP
   require_relative "mcp/mailbox"
   require_relative "mcp/router"
   require_relative "mcp/rpc"
-  require_relative "mcp/pipe"
   require_relative "mcp/transport/http"
   require_relative "mcp/transport/stdio"
 
   include RPC
 
-  @@clients = {}
+  @clients = {}
 
   ##
   # @api private
-  def self.clients = @@clients
+  def self.clients
+    @clients
+  end
 
   ##
   # Builds an MCP client that uses the stdio transport.
@@ -80,7 +81,9 @@ class LLM::MCP
       @command = Command.new(**stdio)
       @transport = Transport::Stdio.new(command:)
     elsif http
+      persistent = http.delete(:persistent)
       @transport = Transport::HTTP.new(**http, timeout:)
+      @transport.persistent if persistent
     else
       raise ArgumentError, "stdio or http is required"
     end
@@ -122,7 +125,7 @@ class LLM::MCP
   # Configures an HTTP MCP transport to use a persistent connection pool
   # via the optional dependency [Net::HTTP::Persistent](https://github.com/drbrain/net-http-persistent)
   # @example
-  #   mcp = LLM.mcp(http: {url: "https://example.com/mcp"}).persistent
+  #   mcp = LLM::MCP.http(url: "https://example.com/mcp", persistent: true)
   #   # do something with 'mcp'
   # @return [LLM::MCP]
   def persist!

data/lib/llm/object/kernel.rb

@@ -4,6 +4,8 @@ class LLM::Object
   ##
   # @private
   module Kernel
+    TypeError = ::TypeError
+
     def tap(...)
       ::Kernel.instance_method(:tap).bind(self).call(...)
     end
@@ -26,11 +28,15 @@ class LLM::Object
     alias_method :is_a?, :kind_of?
 
     def respond_to?(m, include_private = false)
-      !!key(m) || self.class.method_defined?(m)
+      !!SINGLETON.key(@h, m) || self.class.method_defined?(m)
     end
 
     def respond_to_missing?(m, include_private = false)
-      !!key(m)
+      !!SINGLETON.key(@h, m)
+    end
+
+    def raise(...)
+      ::Kernel.raise(...)
     end
 
     def object_id

data/lib/llm/object.rb

@@ -8,6 +8,37 @@ class LLM::Object < BasicObject
   require_relative "object/builder"
   require_relative "object/kernel"
 
+  SINGLETON = self
+  UNDEFINED = ::Object.new.freeze
+  LLM = ::LLM
+  private_constant :SINGLETON, :UNDEFINED, :LLM
+
+  ##
+  # @api private
+  # @param [Hash] h
+  # @param [#to_s, #to_sym] k
+  # @return [String, Symbol, nil]
+  def self.key(h, k)
+    return nil if k.nil?
+    if h.key?(k.to_s)
+      k.to_s
+    elsif h.key?(k.to_sym)
+      k.to_sym
+    else
+      nil
+    end
+  end
+
+  ##
+  # @api private
+  # @param [Hash] h
+  # @param [#to_s, #to_sym] k
+  # @return [Object, nil]
+  def self.get(h, k)
+    name = key(h, k)
+    h[name] if name
+  end
+
   extend Builder
   include Kernel
   include ::Enumerable
@@ -33,7 +64,7 @@ class LLM::Object < BasicObject
   # @param [Symbol, #to_sym] k
   # @return [Object]
   def [](k)
-    @h[key(k)]
+    @h[SINGLETON.key(@h, k)]
   end
 
   ##
@@ -47,7 +78,7 @@ class LLM::Object < BasicObject
   ##
   # @return [String]
   def to_json(...)
-    to_h.to_json(...)
+    LLM.json.dump(to_h, ...)
   end
 
   ##
@@ -83,16 +114,39 @@ class LLM::Object < BasicObject
   ##
   # @param [String, Symbol] k
   # @return [Boolean]
-  def key?(k)
-    @h.key?(key(k))
+  def key?(k = UNDEFINED)
+    return SINGLETON.get(@h, :key?) if k.equal?(UNDEFINED)
+    @h.key?(SINGLETON.key(@h, k))
   end
   alias_method :has_key?, :key?
 
   ##
   # @param [String, Symbol] k
   # @return [Object]
-  def fetch(k, *args, &b)
-    @h.fetch(key(k), *args, &b)
+  def fetch(k = UNDEFINED, *args, &b)
+    return SINGLETON.get(@h, :fetch) if k.equal?(UNDEFINED)
+    @h.fetch(SINGLETON.key(@h, k), *args, &b)
+  end
+
+  ##
+  # @param [Hash, to_h] other
+  #  The hash to merge
+  # @return [LLM::Object]
+  #  Returns a new LLM::Object
+  def merge(other = UNDEFINED)
+    return SINGLETON.get(@h, :merge) if other.equal?(UNDEFINED)
+    other = ::Hash.try_convert(other)
+    raise TypeError, "#{other} cannot be coerced into a Hash" unless other
+    SINGLETON.from @h.merge(other)
+  end
+
+  ##
+  # @param [#to_s, #to_sym] k
+  #  The key name
+  # @return [void]
+  def delete(k = UNDEFINED)
+    return SINGLETON.get(@h, :delete) if k.equal?(UNDEFINED)
+    @h.delete(SINGLETON.key(@h, k))
   end
 
   ##
@@ -110,14 +164,16 @@ class LLM::Object < BasicObject
 
   ##
   # @return [Object, nil]
-  def dig(...)
-    @h.dig(...)
+  def dig(*args)
+    return SINGLETON.get(@h, :dig) if args.empty?
+    @h.dig(*args)
   end
 
   ##
   # @return [Hash]
-  def slice(...)
-    @h.slice(...)
+  def slice(*args)
+    return SINGLETON.get(@h, :slice) if args.empty?
+    @h.slice(*args)
   end
 
   private
@@ -125,20 +181,10 @@ class LLM::Object < BasicObject
   def method_missing(m, *args, &b)
     if m.to_s.end_with?("=")
       self[m[0..-2]] = args.first
-    elsif k = key(m)
+    elsif k = SINGLETON.key(@h, m)
       @h[k]
     else
       nil
     end
   end
-
-  def key(k)
-    if @h.key?(k.to_s)
-      k.to_s
-    elsif @h.key?(k.to_sym)
-      k.to_sym
-    else
-      nil
-    end
-  end
 end