llm.rb 7.0.0 → 8.1.0

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
@@ -29,11 +60,19 @@ class LLM::Object < BasicObject
     @h.each(&)
   end
 
+  ##
+  # In-place transform of values with a block.
+  # @yieldparam [Object] v
+  # @return [Hash]
+  def transform_values!(&)
+    @h.transform_values!(&)
+  end
+
   ##
   # @param [Symbol, #to_sym] k
   # @return [Object]
   def [](k)
-    @h[key(k)]
+    @h[SINGLETON.key(@h, k)]
   end
 
   ##
@@ -47,7 +86,7 @@ class LLM::Object < BasicObject
   ##
   # @return [String]
   def to_json(...)
-    to_h.to_json(...)
+    LLM.json.dump(to_h, ...)
   end
 
   ##
@@ -83,16 +122,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 +172,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 +189,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/execution.rb

@@ -92,7 +92,7 @@ module LLM::Provider::Transport
         if stream
           http.request(request) do |res|
             if Net::HTTPSuccess === res
-              parser = StreamDecoder.new(stream_parser.new(stream))
+              parser = stream_decoder.new(stream_parser.new(stream))
               res.read_body(parser)
               body = parser.body
               res.body = (Hash === body || Array === body) ? LLM::Object.from(body) : body

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

@@ -399,6 +399,13 @@ class LLM::Provider
     raise NotImplementedError
   end
 
+  ##
+  # @return [Class]
+  #  Returns the class responsible for decoding streamed response bodies
+  def stream_decoder
+    LLM::Provider::Transport::HTTP::StreamDecoder
+  end
+
   ##
   # Resolves tools to their function representations
   # @param [Array<LLM::Function, LLM::Tool>] tools

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+class LLM::Bedrock
+  ##
+  # Handles Bedrock API error responses.
+  #
+  # Bedrock errors come as JSON with:
+  #   { "message" => "...", "__type" => "..." }
+  # or as standard HTTP status codes.
+  #
+  # @api private
+  class ErrorHandler
+    ##
+    # @return [Net::HTTPResponse]
+    attr_reader :res
+
+    ##
+    # @return [Object, nil]
+    attr_reader :span
+
+    ##
+    # @param [LLM::Tracer] tracer
+    # @param [Object, nil] span
+    # @param [Net::HTTPResponse] res
+    # @return [LLM::Bedrock::ErrorHandler]
+    def initialize(tracer, span, res)
+      @tracer = tracer
+      @span = span
+      @res = res
+    end
+
+    ##
+    # @raise [LLM::Error]
+    def raise_error!
+      ex = error
+      @tracer.on_request_error(ex:, span:)
+    ensure
+      raise(ex) if ex
+    end
+
+    private
+
+    ##
+    # @return [LLM::Error]
+    def error
+      message = extract_message
+      case res
+      when Net::HTTPServerError
+        LLM::ServerError.new(message).tap { _1.response = res }
+      when Net::HTTPUnauthorized
+        LLM::UnauthorizedError.new(message).tap { _1.response = res }
+      when Net::HTTPForbidden
+        LLM::UnauthorizedError.new(message).tap { _1.response = res }
+      when Net::HTTPTooManyRequests
+        LLM::RateLimitError.new(message).tap { _1.response = res }
+      when Net::HTTPNotFound
+        LLM::Error.new("Bedrock model not found: #{message}").tap { _1.response = res }
+      else
+        LLM::Error.new(message).tap { _1.response = res }
+      end
+    end
+
+    ##
+    # @return [String]
+    def extract_message
+      body = parse_body
+      body["message"] || body["Message"] || body["__type"] || "Unexpected error"
+    end
+
+    ##
+    # @return [Hash]
+    def parse_body
+      return {} if res.body.nil? || res.body.empty?
+      parsed = LLM.json.load(res.body.dup.force_encoding(Encoding::UTF_8).scrub)
+      Hash === parsed ? parsed : {}
+    rescue *LLM.json.parser_error
+      {}
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+class LLM::Bedrock
+  ##
+  # The {LLM::Bedrock::Models} class provides a model object for
+  # interacting with [AWS Bedrock's ListFoundationModels API](
+  # https://docs.aws.amazon.com/bedrock/latest/APIReference/API_ListFoundationModels.html).
+  #
+  # Unlike the Converse API (which lives on `bedrock-runtime.<region>.amazonaws.com`),
+  # the models endpoint lives on the control plane at
+  # `bedrock.<region>.amazonaws.com`. This class manages its own HTTP
+  # connection since the provider's transport is pinned to the runtime host.
+  #
+  # @example
+  #   llm = LLM.bedrock(
+  #     access_key_id: ENV["AWS_ACCESS_KEY_ID"],
+  #     secret_access_key: ENV["AWS_SECRET_ACCESS_KEY"],
+  #     region: "us-east-1"
+  #   )
+  #   llm.models.all.each { |m| puts m.id }
+  class Models
+    ##
+    # @param [LLM::Bedrock] provider
+    # @return [LLM::Bedrock::Models]
+    def initialize(provider)
+      @provider = provider
+    end
+
+    ##
+    # List all foundation models available in the configured region.
+    #
+    # @note
+    #  This calls AWS Bedrock's ListFoundationModels API which returns
+    #  all models available in the region, not just the ones the
+    #  current account is subscribed to.
+    #
+    # @param [Hash] params Optional query parameters
+    #  (e.g. `byProvider: "Anthropic"`, `byInferenceType: "ON_DEMAND"`)
+    # @return [LLM::Response]
+    def all(**params)
+      host = credentials.host
+      handle_response http(host).request(build_request(host, params))
+    end
+
+    private
+
+    ##
+    # @param [String] host
+    # @return [Net::HTTP]
+    def http(host)
+      http = Net::HTTP.new(host, 443)
+      http.use_ssl = true
+      http.read_timeout = timeout
+      http
+    end
+
+    ##
+    # @param [String] host
+    # @param [Hash] params
+    # @return [Net::HTTP::Get]
+    def build_request(host, params)
+      path = "/foundation-models"
+      query = URI.encode_www_form(params) unless params.empty?
+      path = "#{path}?#{query}" if query && !query.empty?
+      body = ""
+      req = Net::HTTP::Get.new(path, {"Content-Type" => "application/json", "Accept" => "application/json"})
+      req.tap { sign!(req, body, host, query) }
+    end
+
+    ##
+    # @param [Net::HTTPResponse] res
+    # @return [LLM::Response]
+    # @raise [LLM::Error]
+    def handle_response(res)
+      case res
+      when Net::HTTPSuccess
+        res.body = LLM::Object.from(LLM.json.load(res.body || "{}"))
+        LLM::Bedrock::ResponseAdapter.adapt(res, type: :models)
+      else
+        body = +""
+        res.read_body { body << _1 } if res.body.nil?
+        LLM::Bedrock::ErrorHandler.new(tracer, nil, res).raise_error!
+      end
+    end
+
+    ##
+    # @param [Net::HTTPRequest] req
+    # @param [String] body
+    # @param [String] host
+    # @param [String, nil] query
+    # @return [Net::HTTPRequest]
+    def sign!(req, body, host = credentials.host, query = nil)
+      creds = credentials.tap { _1.host = host }
+      Signature.new(credentials: creds, method: "GET", path: "/foundation-models", query:, body:).sign!(req)
+    end
+
+    ##
+    # @return [LLM::Object]
+    def credentials
+      LLM::Object.from(@provider.send(:credentials).to_h).tap do
+        _1.host = "bedrock.#{_1.aws_region}.amazonaws.com"
+      end
+    end
+
+    [:timeout, :tracer].each do |m|
+      define_method(m) { @provider.send(m) }
+    end
+  end
+end