llm.rb 7.0.0 → 8.0.0

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/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

data/lib/llm/{mcp/pipe.rb → pipe.rb}

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
 
-class LLM::MCP
+module LLM
   ##
-  # The {LLM::MCP::Pipe LLM::MCP::Pipe} class wraps a pair of IO
-  # objects created by {IO.pipe}. It is used by
-  # {LLM::MCP::Transport::Stdio LLM::MCP::Transport::Stdio} to manage
-  # the stdin, stdout, and stderr streams of an MCP process through
-  # one small interface.
+  # The {LLM::Pipe LLM::Pipe} class wraps a pair of IO objects created by
+  # {IO.pipe}. It is used by llm.rb internals to manage process and stream
+  # communication through one small interface.
   class Pipe
     ##
     # @return [IO]
@@ -20,9 +18,12 @@ class LLM::MCP
 
     ##
     # Returns a new pipe.
-    # @return [LLM::MCP::Pipe]
-    def initialize
+    # @param [Boolean] binmode
+    #  Whether both ends of the pipe should be switched to binary mode
+    # @return [LLM::Pipe]
+    def initialize(binmode: false)
       @r, @w = IO.pipe
+      [@r, @w].each(&:binmode) if binmode
     end
 
     ##

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

@@ -53,7 +53,7 @@ class LLM::Provider
       # @return [Object]
       def request_owner
         return Fiber.current unless defined?(::Async)
-        Async::Task.current || Fiber.current
+        Async::Task.current? ? Async::Task.current : Fiber.current
       end
 
       ##

data/lib/llm/stream/queue.rb

@@ -46,7 +46,7 @@ class LLM::Stream
     #   to wait on:
     #   - `:thread`: Use threads
     #   - `:task`: Use async tasks (requires async gem)
-    #   - `:fiber`: Use raw fibers
+    #   - `:fiber`: Use scheduler-backed fibers (requires Fiber.scheduler)
     #   - `:ractor`: Use Ruby ractors (class-based tools only; MCP tools are not supported)
     #   - `[:thread, :ractor]`: Wait for any queued thread or ractor work, in the
     #     given order. This is useful when different tools were spawned with

data/lib/llm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LLM
-  VERSION = "7.0.0"
+  VERSION = "8.0.0"
 end

data/lib/llm.rb

@@ -20,6 +20,7 @@ module LLM
   require_relative "llm/mime"
   require_relative "llm/multipart"
   require_relative "llm/file"
+  require_relative "llm/pipe"
   require_relative "llm/stream"
   require_relative "llm/provider"
   require_relative "llm/context"
@@ -48,7 +49,24 @@ module LLM
 
   ##
   # @api private
-  def self.clients = @clients
+  def self.clients
+    @clients
+  end
+
+  ##
+  # Requires an optional runtime dependency
+  # @raise [LLM::DependencyError]
+  #  When the dependency cannot be loaded
+  def self.require(name)
+    super
+  rescue ::LoadError
+    names = {"xchan" => "xchan.rb", "net/http/persistent" => "net-http-persistent"}
+    name = names[name] || name
+    raise LLM::LoadError,
+      "#{name} is an optional runtime dependency but it does not appear to be installed. " \
+      "Consider 'gem install #{name}', adding '#{name}' to your Gemfile or " \
+      "opting out of the functionality provided by '#{name}'"
+  end
 
   ##
   # @param [Symbol, LLM::Provider] llm

data/llm.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
   DESCRIPTION
 
   spec.license = "0BSD"
-  spec.required_ruby_version = ">= 3.2.0"
+  spec.required_ruby_version = ">= 3.3.0"
 
   spec.homepage = "https://github.com/llmrb/llm.rb"
   spec.metadata["homepage_uri"] = "https://github.com/llmrb/llm.rb"
@@ -57,5 +57,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "activerecord", "~> 8.0"
   spec.add_development_dependency "sequel", "~> 5.0"
   spec.add_development_dependency "sqlite3", "~> 2.0"
+  spec.add_development_dependency "xchan.rb", "~> 0.20"
   spec.add_development_dependency "pg", "~> 1.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 7.0.0
+  version: 8.0.0
 platform: ruby
 authors:
 - Antar Azri
@@ -236,6 +236,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: xchan.rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.20'
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
@@ -301,6 +315,10 @@ files:
 - lib/llm/function.rb
 - lib/llm/function/array.rb
 - lib/llm/function/fiber_group.rb
+- lib/llm/function/fork.rb
+- lib/llm/function/fork/job.rb
+- lib/llm/function/fork/task.rb
+- lib/llm/function/fork_group.rb
 - lib/llm/function/ractor.rb
 - lib/llm/function/ractor/job.rb
 - lib/llm/function/ractor/mailbox.rb
@@ -317,7 +335,6 @@ files:
 - lib/llm/mcp/command.rb
 - lib/llm/mcp/error.rb
 - lib/llm/mcp/mailbox.rb
-- lib/llm/mcp/pipe.rb
 - lib/llm/mcp/router.rb
 - lib/llm/mcp/rpc.rb
 - lib/llm/mcp/transport/http.rb
@@ -331,6 +348,7 @@ files:
 - lib/llm/object.rb
 - lib/llm/object/builder.rb
 - lib/llm/object/kernel.rb
+- lib/llm/pipe.rb
 - lib/llm/prompt.rb
 - lib/llm/provider.rb
 - lib/llm/provider/transport/http.rb
@@ -464,7 +482,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="