llm.rb 11.1.0 → 11.3.0

data/lib/llm/transport/http.rb

@@ -11,8 +11,10 @@ class LLM::Transport
   #
   # @api private
   class HTTP < self
+    include NetHTTPAdapter
+
     INTERRUPT_ERRORS = [::IOError, ::EOFError, Errno::EBADF].freeze
-    Request = Struct.new(:client, keyword_init: true)
+    ActiveRequest = Struct.new(:client, keyword_init: true)
 
     ##
     # @param [String] host
@@ -67,15 +69,18 @@ class LLM::Transport
 
     ##
     # Performs a request on the current HTTP transport.
-    # @param [Net::HTTPRequest] request
+    # Accepts both {Net::HTTPRequest} and {LLM::Transport::Request}.
+    #
+    # @param [Net::HTTPRequest, LLM::Transport::Request] request
     # @param [Fiber] owner
     # @param [LLM::Object, nil] stream
     # @yieldparam [LLM::Transport::Response] response
     # @return [Object]
     def request(request, owner:, stream: nil, &b)
+      http_req = resolve_request(request)
       client = client()
-      set_request(Request.new(client:), owner)
-      perform_request(client, request, stream, &b)
+      set_request(ActiveRequest.new(client:), owner)
+      perform_request(client, http_req, stream, &b)
     ensure
       clear_request(owner)
     end

data/lib/llm/transport/net_http_adapter.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+class LLM::Transport
+  ##
+  # @api private
+  module NetHTTPAdapter
+    private
+
+    def resolve_request(request)
+      return request if ::Net::HTTPRequest === request
+      build_net_http_request(request)
+    end
+
+    def build_net_http_request(req)
+      method = req.method.downcase.to_sym
+      path = req.path
+      headers = req.headers
+      http_req = case method
+      when :get then ::Net::HTTP::Get.new(path, headers)
+      when :post then ::Net::HTTP::Post.new(path, headers)
+      when :put then ::Net::HTTP::Put.new(path, headers)
+      when :patch then ::Net::HTTP::Patch.new(path, headers)
+      when :delete then ::Net::HTTP::Delete.new(path, headers)
+      else ::Net::HTTP::GenericRequest.new(method, path, nil, headers)
+      end
+      if req.body
+        http_req.body = req.body
+      elsif req.body_stream
+        http_req.body_stream = req.body_stream
+      end
+      http_req
+    end
+
+    def perform_request(client, request, stream, &b)
+      if stream
+        client.request(request) do |raw|
+          res = LLM::Transport::Response.from(raw)
+          if res.success?
+            parser = stream.decoder.new(stream.parser.new(stream.streamer))
+            res.read_body(parser)
+            body = parser.body
+            res.body = (Hash === body || Array === body) ? LLM::Object.from(body) : body
+          else
+            body = +""
+            res.read_body { body << _1 }
+            res.body = body
+          end
+        ensure
+          parser&.free
+        end
+      elsif b
+        client.request(request) do |raw|
+          res = LLM::Transport::Response.from(raw)
+          res.success? ? b.call(res) : res
+        end
+      else
+        LLM::Transport::Response.from(client.request(request))
+      end
+    end
+  end
+end

data/lib/llm/transport/persistent_http.rb

@@ -10,8 +10,10 @@ class LLM::Transport
   #
   # @api private
   class PersistentHTTP < self
+    include NetHTTPAdapter
+
     INTERRUPT_ERRORS = [::IOError, ::EOFError, Errno::EBADF].freeze
-    Request = Struct.new(:client, :connection, keyword_init: true)
+    ActiveRequest = Struct.new(:client, :connection, keyword_init: true)
     @registry = {}
     @monitor = Monitor.new
 
@@ -79,15 +81,18 @@ class LLM::Transport
 
     ##
     # Performs a request on the current HTTP transport.
-    # @param [Net::HTTPRequest] request
+    # Accepts both {Net::HTTPRequest} and {LLM::Transport::Request}.
+    #
+    # @param [Net::HTTPRequest, LLM::Transport::Request] request
     # @param [Fiber] owner
     # @param [LLM::Object, nil] stream
     # @yieldparam [LLM::Transport::Response] response
     # @return [Object]
     def request(request, owner:, stream: nil, &b)
-      client.connection_for(URI.join(base_uri, request.path)) do |connection|
-        set_request(Request.new(client:, connection:), owner)
-        perform_request(connection.http, request, stream, &b)
+      http_req = resolve_request(request)
+      client.connection_for(URI.join(base_uri, http_req.path)) do |connection|
+        set_request(ActiveRequest.new(client:, connection:), owner)
+        perform_request(connection.http, http_req, stream, &b)
       end
     ensure
       clear_request(owner)

data/lib/llm/transport/request.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+class LLM::Transport
+  ##
+  # {LLM::Transport::Request LLM::Transport::Request} defines the
+  # normalized request interface expected by transports.
+  #
+  # Providers build request objects through this class, then hand them
+  # to a transport for execution without depending on any specific HTTP
+  # client library.
+  class Request
+    ##
+    # @return [Object, nil]
+    attr_accessor :body
+
+    ##
+    # @return [IO, nil]
+    attr_accessor :body_stream
+
+    ##
+    # @return [String]
+    attr_reader :method
+
+    ##
+    # @return [String]
+    attr_reader :path
+
+    ##
+    # @return [Hash]
+    attr_reader :headers
+
+    ##
+    # @param [String] path
+    # @param [Hash, nil] headers
+    # @return [LLM::Transport::Request]
+    def self.get(path, headers = nil)
+      new("GET", path, headers)
+    end
+
+    ##
+    # @param [String] path
+    # @param [Hash, nil] headers
+    # @return [LLM::Transport::Request]
+    def self.post(path, headers = nil)
+      new("POST", path, headers)
+    end
+
+    ##
+    # @param [String] path
+    # @param [Hash, nil] headers
+    # @return [LLM::Transport::Request]
+    def self.put(path, headers = nil)
+      new("PUT", path, headers)
+    end
+
+    ##
+    # @param [String] path
+    # @param [Hash, nil] headers
+    # @return [LLM::Transport::Request]
+    def self.patch(path, headers = nil)
+      new("PATCH", path, headers)
+    end
+
+    ##
+    # @param [String] path
+    # @param [Hash, nil] headers
+    # @return [LLM::Transport::Request]
+    def self.delete(path, headers = nil)
+      new("DELETE", path, headers)
+    end
+
+    ##
+    # @param [String] method
+    # @param [String] path
+    # @param [Hash, nil] headers
+    # @return [LLM::Transport::Request]
+    def initialize(method, path, headers = nil)
+      @method = method.to_s.upcase
+      @path = path.to_s
+      @headers = {}
+      (headers || {}).each { self[_1] = _2 }
+    end
+
+    ##
+    # @param [String] key
+    # @return [String, nil]
+    def [](key)
+      @headers[normalize_header(key)]
+    end
+
+    ##
+    # @param [String] key
+    # @param [Object] value
+    # @return [String]
+    def []=(key, value)
+      @headers[normalize_header(key)] = value.to_s
+    end
+
+    ##
+    # @yieldparam [String] key
+    # @yieldparam [String] value
+    # @return [Hash]
+    def each_header(&block)
+      @headers.each(&block)
+    end
+
+    ##
+    # @return [String]
+    def inspect
+      "#<#{self.class.name}:0x#{object_id.to_s(16)}" \
+        " @method=#{@method} @path=#{@path}" \
+        " @headers=#{@headers.inspect}>"
+    end
+
+    private
+
+    def normalize_header(key)
+      key.to_s.downcase
+    end
+  end
+end

data/lib/llm/transport/response/curb.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+class LLM::Transport::Response
+  ##
+  # {LLM::Transport::Response::Curb LLM::Transport::Response::Curb}
+  # adapts a raw status code, header hash, and body string to the
+  # {LLM::Transport::Response LLM::Transport::Response} interface.
+  #
+  # This is the response wrapper used by the
+  # {LLM::Transport::Curb LLM::Transport::Curb} transport.
+  class Curb < self
+    ##
+    # @return [Integer]
+    attr_reader :code
+
+    ##
+    # @return [Hash]
+    attr_reader :headers
+
+    ##
+    # @return [String]
+    attr_accessor :body
+
+    ##
+    # @param [#to_i] code
+    # @param [Hash] headers
+    # @param [String] body
+    # @return [LLM::Transport::Response::Curb]
+    def initialize(code, headers = {}, body = +"")
+      @code = code.to_i
+      @headers = {}
+      (headers || {}).each { @headers[_1.to_s.downcase] = _2.to_s }
+      @body = body
+    end
+
+    ##
+    # @param [String] key
+    # @return [String, nil]
+    def [](key)
+      @headers[key.to_s.downcase]
+    end
+
+    ##
+    # @param [Object, nil] dest
+    # @yieldparam [String] chunk
+    # @return [void]
+    def read_body(dest = nil, &block)
+      return @body unless block_given? || dest
+      if dest
+        dest << @body.to_s
+      else
+        yield @body.to_s
+      end
+      @body
+    end
+
+    ##
+    # @return [Boolean]
+    def success?
+      code.between?(200, 299)
+    end
+
+    ##
+    # @return [Boolean]
+    def ok?
+      code == 200
+    end
+
+    ##
+    # @return [Boolean]
+    def bad_request?
+      code == 400
+    end
+
+    ##
+    # @return [Boolean]
+    def unauthorized?
+      code == 401
+    end
+
+    ##
+    # @return [Boolean]
+    def forbidden?
+      code == 403
+    end
+
+    ##
+    # @return [Boolean]
+    def not_found?
+      code == 404
+    end
+
+    ##
+    # @return [Boolean]
+    def rate_limited?
+      code == 429
+    end
+
+    ##
+    # @return [Boolean]
+    def server_error?
+      code.between?(500, 599)
+    end
+
+    ##
+    # @return [String]
+    def inspect
+      "#<#{self.class.name}:0x#{object_id.to_s(16)}" \
+        " @code=#{@code} @headers=#{@headers.inspect}>"
+    end
+  end
+end

data/lib/llm/transport/response.rb

@@ -17,6 +17,7 @@ class LLM::Transport
   # how the request was actually performed.
   class Response
     require_relative "response/http"
+    require_relative "response/curb"
 
     ##
     # @param [Object] res

data/lib/llm/transport/utils.rb

@@ -4,32 +4,57 @@ class LLM::Transport
   ##
   # Shared utility methods for HTTP-backed transports.
   #
+  # These methods resolve the transport options accepted by providers,
+  # MCP HTTP clients, and A2A HTTP clients into concrete
+  # {LLM::Transport} instances.
+  #
   # @api private
   module Utils
     extend self
-    private
 
-    def resolve_transport(uri, transport, timeout)
-      return default_transport(uri, timeout) if transport.nil?
-      if Class === transport && transport <= LLM::Transport
-        transport.new(
-          host: uri.host,
-          port: uri.port,
-          timeout:,
-          ssl: uri.scheme == "https"
-        )
+    ##
+    # Resolves a transport configuration into a transport instance.
+    #
+    # Nil values use the default Net::HTTP transport, or the persistent
+    # Net::HTTP transport when `persistent` is true. Transport subclasses
+    # are instantiated with the endpoint settings, symbols are resolved
+    # through {LLM::Transport} shortcut methods, and transport instances
+    # are returned as-is.
+    #
+    # @param [String] host
+    # @param [Integer] port
+    # @param [Integer, nil] timeout
+    # @param [Boolean] ssl
+    # @param [Boolean] persistent
+    # @param [LLM::Transport, Class, Symbol, nil] transport
+    # @return [LLM::Transport]
+    def resolve_transport(host:, port:, timeout:, ssl:, persistent:, transport:)
+      if transport.nil?
+        default_transport(host:, port:, timeout:, ssl:, persistent:)
+      elsif Class === transport && transport <= LLM::Transport
+        transport.new(host:, port:, timeout:, ssl:)
+      elsif Symbol === transport
+        transport = LLM::Transport.public_send(transport)
+        transport.new(host:, port:, timeout:, ssl:)
       else
         transport
       end
     end
 
-    def default_transport(uri, timeout)
-      LLM::Transport::HTTP.new(
-        host: uri.host,
-        port: uri.port,
-        timeout:,
-        ssl: uri.scheme == "https"
-      )
+    private
+
+    ##
+    # Builds the default Net::HTTP transport for an endpoint.
+    #
+    # @param [String] host
+    # @param [Integer] port
+    # @param [Integer, nil] timeout
+    # @param [Boolean] ssl
+    # @param [Boolean] persistent
+    # @return [LLM::Transport]
+    def default_transport(host:, port:, timeout:, ssl:, persistent:)
+      target = persistent ? LLM::Transport::PersistentHTTP : LLM::Transport::HTTP
+      target.new(host:, port:, timeout:, ssl:)
     end
   end
 end

data/lib/llm/transport.rb

@@ -9,10 +9,10 @@ module LLM
   # execute provider requests without changing request adapters or
   # response adapters.
   #
-  # Providers currently construct {Net::HTTPRequest Net::HTTPRequest}
-  # objects before delegating to a transport. Custom transports are
-  # therefore expected to execute those requests directly, or transform
-  # them into backend-specific request objects before execution.
+  # Providers should construct {LLM::Transport::Request} objects before
+  # delegating to a transport. Custom transports can execute those
+  # requests directly, or transform them into backend-specific request
+  # objects before execution.
   #
   # Only {#request} is required. The remaining methods are optional hooks
   # for features such as interruption, request ownership, or persistence,
@@ -26,11 +26,14 @@ module LLM
   # can rely on one normalized response contract instead of
   # transport-specific classes.
   class Transport
+    require_relative "transport/request"
     require_relative "transport/response"
     require_relative "transport/utils"
     require_relative "transport/stream_decoder"
+    require_relative "transport/net_http_adapter"
     require_relative "transport/http"
     require_relative "transport/persistent_http"
+    require_relative "transport/curb"
     require_relative "transport/execution"
 
     ##
@@ -47,9 +50,17 @@ module LLM
       PersistentHTTP
     end
 
+    ##
+    # Returns the optional libcurl (curb) transport class.
+    # Requires the `curb` gem.
+    # @return [Class]
+    def self.curb
+      Curb
+    end
+
     ##
     # Performs a request through the transport.
-    # @param [Net::HTTPRequest] request
+    # @param [LLM::Transport::Request] request
     # @param [Object] owner
     # @param [LLM::Object, nil] stream
     # @yieldparam [LLM::Transport::Response] response
@@ -90,51 +101,12 @@ module LLM
     end
 
     ##
-    # @note
-    #  Custom transports may be able to reuse this helper when they
-    #  operate on Net::HTTPRequest objects, or implement their own
-    #  request body preparation path instead.
-    # @param [Net::HTTPRequest] request
+    # @param [LLM::Transport::Request] request
     # @param [IO] io
     # @return [void]
     def set_body_stream(request, io)
       request.body_stream = io
       request["transfer-encoding"] = "chunked" unless request["content-length"]
     end
-
-    private
-
-    ##
-    # @api private
-    # @note
-    #  Custom transports may be able to reuse this helper when they
-    #  execute requests through a Net::HTTP-compatible client, or
-    #  implement their own request execution path instead.
-    def perform_request(client, request, stream, &b)
-      if stream
-        client.request(request) do |raw|
-          res = LLM::Transport::Response.from(raw)
-          if res.success?
-            parser = stream.decoder.new(stream.parser.new(stream.streamer))
-            res.read_body(parser)
-            body = parser.body
-            res.body = (Hash === body || Array === body) ? LLM::Object.from(body) : body
-          else
-            body = +""
-            res.read_body { body << _1 }
-            res.body = body
-          end
-        ensure
-          parser&.free
-        end
-      elsif b
-        client.request(request) do |raw|
-          res = LLM::Transport::Response.from(raw)
-          res.success? ? b.call(res) : res
-        end
-      else
-        LLM::Transport::Response.from(client.request(request))
-      end
-    end
   end
 end

data/lib/llm/version.rb

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

data/llm.gemspec

@@ -5,8 +5,8 @@ require_relative "lib/llm/version"
 Gem::Specification.new do |spec|
   spec.name = "llm.rb"
   spec.version = LLM::VERSION
-  spec.authors = ["Antar Azri", "0x1eef", "Christos Maris", "Rodrigo Serrano"]
-  spec.email = ["azantar@proton.me", "0x1eef@hardenedbsd.org"]
+  spec.authors = ["0x1eef (Robert)", "Antar Azri", "Rodrigo Serrano", "Christos Maris"]
+  spec.email = ["robert@4.4bsd.dev"]
 
   spec.summary = "Ruby's most capable AI runtime"
   spec.description = <<~DESC
@@ -28,10 +28,10 @@ Gem::Specification.new do |spec|
   spec.license = "0BSD"
   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"
+  spec.homepage = "https://llmrb.github.io"
+  spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/llmrb/llm.rb"
-  spec.metadata["documentation_uri"] = "https://0x1eef.github.io/x/llm.rb"
+  spec.metadata["documentation_uri"] = "https://llmrb.github.io/llm.rb"
   spec.metadata["changelog_uri"] = "https://0x1eef.github.io/x/llm.rb/file.CHANGELOG.html"
 
   spec.files = Dir[
@@ -60,4 +60,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "sqlite3", "~> 2.0"
   spec.add_development_dependency "xchan.rb", "~> 0.20"
   spec.add_development_dependency "pg", "~> 1.5"
+  spec.add_development_dependency "irb", "~> 1.18"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 11.1.0
+  version: 11.3.0
 platform: ruby
 authors:
+- 0x1eef (Robert)
 - Antar Azri
-- '0x1eef'
-- Christos Maris
 - Rodrigo Serrano
+- Christos Maris
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
@@ -264,6 +264,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.18'
 description: |
   llm.rb is Ruby's most capable AI runtime.
 
@@ -279,8 +293,7 @@ description: |
   tool execution through threads, tasks (via async gem), fibers, ractors,
   and fork (via xchan.rb gem).
 email:
-- azantar@proton.me
-- 0x1eef@hardenedbsd.org
+- robert@4.4bsd.dev
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -482,10 +495,14 @@ files:
 - lib/llm/tracer/null.rb
 - lib/llm/tracer/telemetry.rb
 - lib/llm/transport.rb
+- lib/llm/transport/curb.rb
 - lib/llm/transport/execution.rb
 - lib/llm/transport/http.rb
+- lib/llm/transport/net_http_adapter.rb
 - lib/llm/transport/persistent_http.rb
+- lib/llm/transport/request.rb
 - lib/llm/transport/response.rb
+- lib/llm/transport/response/curb.rb
 - lib/llm/transport/response/http.rb
 - lib/llm/transport/stream_decoder.rb
 - lib/llm/transport/utils.rb
@@ -495,13 +512,13 @@ files:
 - lib/sequel/plugins/agent.rb
 - lib/sequel/plugins/llm.rb
 - llm.gemspec
-homepage: https://github.com/llmrb/llm.rb
+homepage: https://llmrb.github.io
 licenses:
 - 0BSD
 metadata:
-  homepage_uri: https://github.com/llmrb/llm.rb
+  homepage_uri: https://llmrb.github.io
   source_code_uri: https://github.com/llmrb/llm.rb
-  documentation_uri: https://0x1eef.github.io/x/llm.rb
+  documentation_uri: https://llmrb.github.io/llm.rb
   changelog_uri: https://0x1eef.github.io/x/llm.rb/file.CHANGELOG.html
 rdoc_options: []
 require_paths: