llm.rb 8.0.0 → 9.0.0

data/lib/llm/function.rb

@@ -32,6 +32,7 @@ class LLM::Function
   require_relative "function/registry"
   require_relative "function/tracing"
   require_relative "function/array"
+  require_relative "function/call_group"
   require_relative "function/task"
   require_relative "function/thread_group"
   require_relative "function/fiber_group"

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

@@ -16,12 +16,13 @@ module LLM::MCP::Transport
     #  Extra headers to send with requests
     # @param [Integer, nil] timeout
     #  The timeout in seconds. Defaults to nil
+    # @param [LLM::Transport, Class, nil] transport
+    #  Optional override with any {LLM::Transport} instance or subclass
     # @return [LLM::MCP::Transport::HTTP]
-    def initialize(url:, headers: {}, timeout: nil)
+    def initialize(url:, headers: {}, timeout: nil, transport: nil)
       @uri = URI.parse(url)
-      @use_ssl = @uri.scheme == "https"
       @headers = headers
-      @timeout = timeout
+      @transport = resolve_transport(transport, timeout:)
       @queue = []
       @monitor = Monitor.new
       @running = false
@@ -61,21 +62,11 @@ module LLM::MCP::Transport
     # @return [void]
     def write(message)
       raise LLM::MCP::Error, "MCP transport is not running" unless running?
-      req = Net::HTTP::Post.new(uri.path, headers.merge("content-type" => "application/json"))
+      req = Net::HTTP::Post.new(uri.request_uri, headers.merge("content-type" => "application/json"))
       req.body = LLM.json.dump(message)
-      if persistent_client.nil?
-        http = Net::HTTP.start(uri.host, uri.port, use_ssl:, open_timeout: timeout, read_timeout: timeout)
-        args = [req]
-      else
-        http = persistent_client
-        args = [uri, req]
-      end
-      http.request(*args) do |res|
-        unless Net::HTTPSuccess === res
-          raise LLM::MCP::Error, "MCP transport write failed with HTTP #{res.code}"
-        end
-        read(res)
-      end
+      res = transport.request(req, owner: self) { consume(_1) }
+      res = LLM::Transport::Response.from(res)
+      raise LLM::MCP::Error, "MCP transport write failed with HTTP #{res.code}" unless res.success?
     end
 
     ##
@@ -100,30 +91,27 @@ module LLM::MCP::Transport
       @running
     end
 
-    ##
-    # 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: true)
-    #   # do something with 'mcp'
-    # @return [LLM::MCP::Transport::HTTP]
-    def persist!
-      LLM.lock(:mcp) do
-        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
-          http.open_timeout = timeout
-          LLM::MCP.clients[key] ||= http
-        end
-      end
-      self
+    private
+
+    attr_reader :uri, :headers, :transport
+
+    def consume(res)
+      res = LLM::Transport::Response.from(res)
+      read(res)
+      res
     end
-    alias_method :persistent, :persist!
 
-    private
+    def resolve_transport(transport, timeout:)
+      return default_transport(timeout:) if transport.nil?
+      if Class === transport && transport <= LLM::Transport
+        return transport.new(host: uri.host, port: uri.port, timeout:, ssl: uri.scheme == "https")
+      end
+      transport
+    end
 
-    attr_reader :uri, :use_ssl, :headers, :timeout
+    def default_transport(timeout:)
+      LLM::Transport::HTTP.new(host: uri.host, port: uri.port, timeout:, ssl: uri.scheme == "https")
+    end
 
     def read(res)
       if res["content-type"].to_s.include?("text/event-stream")
@@ -142,14 +130,6 @@ module LLM::MCP::Transport
       lock { @queue << message }
     end
 
-    def persistent_client
-      LLM::MCP.clients[key]
-    end
-
-    def key
-      "#{uri.scheme}:#{uri.host}:#{uri.port}:#{timeout}"
-    end
-
     def lock(&)
       @monitor.synchronize(&)
     end

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

@@ -78,14 +78,6 @@ module LLM::MCP::Transport
       command.wait
     end
 
-    ##
-    # This method is a no-op for stdio transports
-    # @return [LLM::MCP::Transport::Stdio]
-    def persist!
-      self
-    end
-    alias_method :persistent, :persist!
-
     private
 
     attr_reader :command, :stdin, :stdout, :stderr

data/lib/llm/mcp.rb

@@ -24,14 +24,6 @@ class LLM::MCP
 
   include RPC
 
-  @clients = {}
-
-  ##
-  # @api private
-  def self.clients
-    @clients
-  end
-
   ##
   # Builds an MCP client that uses the stdio transport.
   # @param [LLM::Provider, nil] llm
@@ -69,6 +61,9 @@ class LLM::MCP
   #  The URL for the MCP HTTP endpoint
   # @option http [Hash] :headers
   #  Extra headers for requests
+  # @option http [LLM::Transport, Class] :transport
+  #  Optional override with any {LLM::Transport} instance or subclass,
+  #  similar to {LLM::Provider}
   # @param [Integer] timeout
   #  The maximum amount of time to wait when reading from an MCP process
   # @return [LLM::MCP] A new MCP instance
@@ -82,8 +77,9 @@ class LLM::MCP
       @transport = Transport::Stdio.new(command:)
     elsif http
       persistent = http.delete(:persistent)
-      @transport = Transport::HTTP.new(**http, timeout:)
-      @transport.persistent if persistent
+      transport = http.delete(:transport)
+      transport ||= LLM::Transport::PersistentHTTP if persistent
+      @transport = Transport::HTTP.new(**http, timeout:, transport:)
     else
       raise ArgumentError, "stdio or http is required"
     end
@@ -121,19 +117,6 @@ class LLM::MCP
     stop
   end
 
-  ##
-  # 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: true)
-  #   # do something with 'mcp'
-  # @return [LLM::MCP]
-  def persist!
-    transport.persist!
-    self
-  end
-  alias_method :persistent, :persist!
-
   ##
   # Returns the tools provided by the MCP process.
   # @return [Array<Class<LLM::Tool>>]

data/lib/llm/object.rb

@@ -60,6 +60,14 @@ 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]

data/lib/llm/provider.rb

@@ -6,10 +6,7 @@
 #
 # @abstract
 class LLM::Provider
-  require "net/http"
-  require_relative "provider/transport/http"
-  require_relative "provider/transport/http/execution"
-  include Transport::HTTP::Execution
+  include LLM::Transport::Execution
 
   ##
   # @param [String, nil] key
@@ -27,7 +24,9 @@ class LLM::Provider
   # @param [Boolean] persistent
   #  Whether to use a persistent connection.
   #  Requires the net-http-persistent gem.
-  def initialize(key:, host:, port: 443, timeout: 60, ssl: true, base_path: "", persistent: false)
+  # @param [LLM::Transport, Class, nil] transport
+  #  Optional override with any {LLM::Transport} instance or subclass.
+  def initialize(key:, host:, port: 443, timeout: 60, ssl: true, base_path: "", persistent: false, transport: nil)
     @key = key
     @host = host
     @port = port
@@ -36,7 +35,7 @@ class LLM::Provider
     @base_path = normalize_base_path(base_path)
     @base_uri = URI("#{ssl ? "https" : "http"}://#{host}:#{port}/")
     @headers = {"User-Agent" => "llm.rb v#{LLM::VERSION}"}
-    @transport = Transport::HTTP.new(host:, port:, timeout:, ssl:, persistent:)
+    @transport = resolve_transport(transport, persistent:)
     @monitor = Monitor.new
   end
 
@@ -316,19 +315,6 @@ class LLM::Provider
     end
   end
 
-  ##
-  # This method configures a provider to use a persistent connection pool
-  # via the optional dependency [Net::HTTP::Persistent](https://github.com/drbrain/net-http-persistent)
-  # @example
-  #   llm = LLM.openai(key: ENV["KEY"]).persistent
-  #   # do something with 'llm'
-  # @return [LLM::Provider]
-  def persist!
-    transport.persist!
-    self
-  end
-  alias_method :persistent, :persist!
-
   ##
   # Interrupt the active request, if any.
   # @param [Fiber] owner
@@ -399,6 +385,13 @@ class LLM::Provider
     raise NotImplementedError
   end
 
+  ##
+  # @return [Class]
+  #  Returns the class responsible for decoding streamed response bodies
+  def stream_decoder
+    LLM::Transport::StreamDecoder
+  end
+
   ##
   # Resolves tools to their function representations
   # @param [Array<LLM::Function, LLM::Tool>] tools
@@ -424,6 +417,23 @@ class LLM::Provider
     @monitor.synchronize(&)
   end
 
+  ##
+  # @api private
+  def default_transport(persistent:)
+    transport_class = persistent ? LLM::Transport::PersistentHTTP : LLM::Transport::HTTP
+    transport_class.new(host:, port:, timeout:, ssl:)
+  end
+
+  ##
+  # @api private
+  def resolve_transport(transport, persistent:)
+    return default_transport(persistent:) if transport.nil?
+    if Class === transport && transport <= LLM::Transport
+      return transport.new(host:, port:, timeout:, ssl:)
+    end
+    transport
+  end
+
   ##
   # @api private
   def thread

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

@@ -5,7 +5,7 @@ class LLM::Anthropic
   # @private
   class ErrorHandler
     ##
-    # @return [Net::HTTPResponse]
+    # @return [LLM::Transport::Response]
     #  Non-2XX response from the server
     attr_reader :res
 
@@ -19,13 +19,13 @@ class LLM::Anthropic
     #  The tracer
     # @param [Object, nil] span
     #  The span
-    # @param [Net::HTTPResponse] res
+    # @param [LLM::Transport::Response, Net::HTTPResponse] res
     #  The response from the server
     # @return [LLM::Anthropic::ErrorHandler]
     def initialize(tracer, span, res)
       @tracer = tracer
       @span = span
-      @res = res
+      @res = LLM::Transport::Response.from(res)
     end
 
     ##
@@ -43,12 +43,11 @@ class LLM::Anthropic
     ##
     # @return [LLM::Error]
     def error
-      case res
-      when Net::HTTPServerError
+      if res.server_error?
         LLM::ServerError.new("Server error").tap { _1.response = res }
-      when Net::HTTPUnauthorized
+      elsif res.unauthorized?
         LLM::UnauthorizedError.new("Authentication error").tap { _1.response = res }
-      when Net::HTTPTooManyRequests
+      elsif res.rate_limited?
         LLM::RateLimitError.new("Too many requests").tap { _1.response = res }
       else
         LLM::Error.new("Unexpected response").tap { _1.response = res }

data/lib/llm/providers/anthropic/files.rb

@@ -58,7 +58,7 @@ class LLM::Anthropic
       multi = LLM::Multipart.new(params.merge!(file: LLM.File(file)))
       req = Net::HTTP::Post.new("/v1/files", headers)
       req["content-type"] = multi.content_type
-      set_body_stream(req, multi.body)
+      transport.set_body_stream(req, multi.body)
       res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :file)
       tracer.on_request_finish(operation: "request", res:, span:)
@@ -159,7 +159,7 @@ class LLM::Anthropic
       @provider.instance_variable_get(:@key)
     end
 
-    [:headers, :execute, :set_body_stream].each do |m|
+    [:headers, :execute, :transport].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end

data/lib/llm/providers/anthropic/response_adapter/completion.rb

@@ -27,6 +27,36 @@ module LLM::Anthropic::ResponseAdapter
       0
     end
 
+    ##
+    # (see LLM::Contract::Completion#input_audio_tokens)
+    def input_audio_tokens
+      super
+    end
+
+    ##
+    # (see LLM::Contract::Completion#output_audio_tokens)
+    def output_audio_tokens
+      super
+    end
+
+    ##
+    # (see LLM::Contract::Completion#input_image_tokens)
+    def input_image_tokens
+      super
+    end
+
+    ##
+    # (see LLM::Contract::Completion#cache_read_tokens)
+    def cache_read_tokens
+      body.usage&.cache_read_input_tokens || 0
+    end
+
+    ##
+    # (see LLM::Contract::Completion#cache_write_tokens)
+    def cache_write_tokens
+      body.usage&.cache_creation_input_tokens || 0
+    end
+
     ##
     # (see LLM::Contract::Completion#total_tokens)
     def total_tokens

data/lib/llm/providers/anthropic.rb

@@ -161,7 +161,7 @@ module LLM
       payload = adapt(messages)
       body = LLM.json.dump(payload.merge!(params))
       req = Net::HTTP::Post.new("/v1/messages", headers)
-      set_body_stream(req, StringIO.new(body))
+      transport.set_body_stream(req, StringIO.new(body))
       req
     end
 

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

@@ -0,0 +1,79 @@
+# 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 [LLM::Transport::Response]
+    attr_reader :res
+
+    ##
+    # @return [Object, nil]
+    attr_reader :span
+
+    ##
+    # @param [LLM::Tracer] tracer
+    # @param [Object, nil] span
+    # @param [LLM::Transport::Response, Net::HTTPResponse] res
+    # @return [LLM::Bedrock::ErrorHandler]
+    def initialize(tracer, span, res)
+      @tracer = tracer
+      @span = span
+      @res = LLM::Transport::Response.from(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
+      if res.server_error?
+        LLM::ServerError.new(message).tap { _1.response = res }
+      elsif res.unauthorized?
+        LLM::UnauthorizedError.new(message).tap { _1.response = res }
+      elsif res.forbidden?
+        LLM::UnauthorizedError.new(message).tap { _1.response = res }
+      elsif res.rate_limited?
+        LLM::RateLimitError.new(message).tap { _1.response = res }
+      elsif res.not_found?
+        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 builds a matching
+  # transport for the control-plane host from the provider's current
+  # transport class.
+  #
+  # @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
+      req = build_request(host, params)
+      res = build_transport(host).request(req, owner: self)
+      handle_response(res)
+    end
+
+    private
+
+    ##
+    # @param [String] host
+    # @return [LLM::Transport]
+    def build_transport(host)
+      transport.class.new(host:, port: 443, timeout:, ssl: true)
+    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 [LLM::Transport::Response, Net::HTTPResponse] res
+    # @return [LLM::Response]
+    # @raise [LLM::Error]
+    def handle_response(res)
+      res = LLM::Transport::Response.from(res)
+      if res.success?
+        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, :transport].each do |m|
+      define_method(m) { @provider.send(m) }
+    end
+  end
+end