llm.rb 11.0.0 → 11.2.0

data/lib/llm/schema.rb

@@ -20,14 +20,16 @@
 #
 # @example Ruby-style
 #  class Address < LLM::Schema
-#    property :street, String, "Street address", required: true
+#    property :street, String, "Street address"
+#    required %i[street]
 #  end
 #
 #  class Person < LLM::Schema
-#    property :name, String, "Person's name", required: true
-#    property :age, Integer, "Person's age", required: true
-#    property :hobbies, Array[String], "Person's hobbies", required: true
-#    property :address, Address, "Person's address", required: true
+#    property :name, String, "Person's name"
+#    property :age, Integer, "Person's age"
+#    property :hobbies, Array[String], "Person's hobbies"
+#    property :address, Address, "Person's address"
+#    required %i[name age hobbies address]
 #  end
 class LLM::Schema
   require_relative "schema/version"
@@ -74,6 +76,10 @@ class LLM::Schema
       end
       schema.array(item)
     end
+
+    def fetch(properties, name)
+      properties[name] || properties.fetch(name.to_s)
+    end
   end
 
   ##
@@ -103,6 +109,18 @@ class LLM::Schema
     end
   end
 
+  ##
+  # Mark existing properties as required.
+  # @param names [Array<Symbol,String>]
+  # @return [LLM::Schema::Object]
+  def self.required(names)
+    lock do
+      object.tap do |schema|
+        [*names].each { Utils.fetch(schema.properties, _1).required }
+      end
+    end
+  end
+
   ##
   # @api private
   # @return [LLM::Schema]

data/lib/llm/skill.rb

@@ -56,6 +56,7 @@ module LLM
       @instructions = ""
       @frontmatter = LLM::Object.from({})
       @tools = []
+      @inherit_tools = false
     end
 
     ##
@@ -74,18 +75,8 @@ module LLM
     # @param [LLM::Context] ctx
     # @return [Hash]
     def call(ctx)
-      instructions, tools, tracer = self.instructions, self.tools, ctx.llm.tracer
-      params = ctx.params.merge(mode: ctx.mode).reject { [:tools, :schema].include?(_1) }
-      concurrency = params[:stream].extra[:concurrency] if LLM::Stream === params[:stream]
-      params[:concurrency] = concurrency if concurrency
-      agent = Class.new(LLM::Agent) do
-        instructions(instructions)
-        tools(*tools)
-        tracer(tracer)
-      end.new(ctx.llm, params)
-      agent.messages.concat(messages_for(ctx))
-      res = agent.talk("Solve the user's query.")
-      {content: res.content}
+      content = agent(ctx).talk("Solve the user's query.").content
+      {content:}
     end
 
     ##
@@ -96,9 +87,10 @@ module LLM
     def to_tool(ctx)
       skill = self
       Class.new(LLM::Tool) do
+        attr_accessor :tracer
+
         name skill.name
         description skill.description
-        attr_accessor :tracer
 
         define_singleton_method(:skill?) do
           true
@@ -110,6 +102,13 @@ module LLM
       end
     end
 
+    ##
+    # Returns true when a skill should inherit tools from its parent
+    # @return [Boolean]
+    def inherit_tools?
+      @inherit_tools
+    end
+
     private
 
     def messages_for(ctx)
@@ -132,8 +131,39 @@ module LLM
       @frontmatter = LLM::Object.from(YAML.safe_load(match[1]) || {})
       @name = @frontmatter.name || @name
       @description = @frontmatter.description || @description
-      @tools = [*@frontmatter.tools].map { LLM::Tool.find_by_name!(_1) }
       @instructions = match[2]
+      @inherit_tools, @tools = parse_tools(@frontmatter.tools)
+    end
+
+    def parse_tools(tools)
+      case tools
+      when String
+        tools == "inherit" ? [true, []] : raise_invalid_error!(tools)
+      when Array
+        [false, [*@frontmatter.tools].map { LLM::Tool.find_by_name!(_1) }]
+      when NilClass
+        [false, []]
+      else
+        raise_invalid_error!(tools)
+      end
+    end
+
+    def raise_invalid_error!(tools)
+      raise LLM::Error, "invalid value for tools key: '#{tools}'"
+    end
+
+    def agent(ctx)
+      instructions, tools, tracer, inherit_tools = self.instructions, self.tools, ctx.llm.tracer, inherit_tools?
+      params = ctx.params.merge(mode: ctx.mode).reject { [:tools, :schema].include?(_1) }
+      concurrency = params[:stream].extra[:concurrency] if LLM::Stream === params[:stream]
+      params[:concurrency] = concurrency if concurrency
+      agent = Class.new(LLM::Agent) do
+        instructions(instructions)
+        tools(inherit_tools ? [*ctx.params[:tools]].reject(&:skill?) : tools)
+        tracer(tracer)
+      end.new(ctx.llm, params)
+      agent.messages.concat(messages_for(ctx))
+      agent
     end
   end
 end

data/lib/llm/tool.rb

@@ -202,6 +202,13 @@ class LLM::Tool
     false
   end
 
+  ##
+  # Returns true if the tool is a skill
+  # @return [Boolean]
+  def self.skill?
+    false
+  end
+
   ##
   # Returns a function bound to this tool instance.
   # @return [LLM::Function]
@@ -216,6 +223,20 @@ class LLM::Tool
     self.class.mcp?
   end
 
+  ##
+  # Returns true if the tool is an A2A tool
+  # @return [Boolean]
+  def a2a?
+    self.class.a2a?
+  end
+
+  ##
+  # Returns true if the tool is a skill
+  # @return [Boolean]
+  def skill?
+    self.class.skill?
+  end
+
   ##
   # Called when an in-flight tool run is interrupted.
   # Tools can override this to implement cooperative cleanup.

data/lib/llm/tracer/telemetry.rb

@@ -223,7 +223,9 @@ module LLM
       require "opentelemetry/sdk" unless defined?(OpenTelemetry)
       @exporter ||= OpenTelemetry::SDK::Trace::Export::InMemorySpanExporter.new
       processor = OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(@exporter)
-      @tracer_provider = OpenTelemetry::SDK::Trace::TracerProvider.new
+      @tracer_provider = OpenTelemetry::SDK::Trace::TracerProvider.new(
+        sampler: OpenTelemetry::SDK::Trace::Samplers::ALWAYS_ON
+      )
       @tracer_provider.add_span_processor(processor)
       @tracer = @tracer_provider.tracer("llm.rb", LLM::VERSION)
     end

data/lib/llm/transport/curb.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+class LLM::Transport
+  ##
+  # The {LLM::Transport::Curb LLM::Transport::Curb} transport is an
+  # optional adapter for libcurl via the
+  # [curb](https://github.com/taf2/curb) gem.
+  #
+  # Curb is a C extension around libcurl. It releases the GVL during
+  # I/O so other Ruby threads can run while requests are in flight. Its
+  # timeout handling is built into libcurl itself — no thread-based
+  # timeout library required. It supports HTTP/2, connection reuse, and
+  # a wider range of network protocols out of the box.
+  #
+  # Unlike the built-in Net::HTTP transports, this transport does not
+  # require any Ruby standard library HTTP client and can be used on
+  # platforms where Net::HTTP is not available or desired.
+  #
+  # @example
+  #   LLM.openai(key: ENV["KEY"], transport: :curb)
+  #
+  # @api private
+  class Curb < self
+    INTERRUPT_ERRORS = [::IOError, ::EOFError, Errno::EBADF].freeze
+    ActiveRequest = Struct.new(:easy, keyword_init: true)
+
+    ##
+    # @param [String] host
+    # @param [Integer] port
+    # @param [Integer] timeout
+    # @param [Boolean] ssl
+    # @return [LLM::Transport::Curb]
+    def initialize(host:, port:, timeout:, ssl:)
+      @host = host
+      @port = port
+      @timeout = timeout
+      @ssl = ssl
+      @base_uri = URI("#{ssl ? "https" : "http"}://#{host}:#{port}/")
+      @monitor = Monitor.new
+    end
+
+    ##
+    # Returns the current request owner.
+    # @return [Object]
+    def request_owner
+      return Fiber.current unless defined?(::Async)
+      Async::Task.current? ? Async::Task.current : Fiber.current
+    end
+
+    ##
+    # @return [Array<Class<Exception>>]
+    def interrupt_errors
+      [*INTERRUPT_ERRORS, *optional_interrupt_errors]
+    end
+
+    ##
+    # Interrupt an active request, if any.
+    #
+    # Sets the interrupt flag so the on_body callback can raise
+    # LLM::Interrupt on the next chunk.
+    #
+    # @param [Fiber] owner
+    # @return [nil]
+    def interrupt!(owner)
+      request_for(owner) or return
+      lock { (@interrupts ||= {})[owner] = true }
+    rescue *interrupt_errors
+      nil
+    end
+
+    ##
+    # Returns whether an execution owner was interrupted.
+    # @param [Fiber] owner
+    # @return [Boolean, nil]
+    def interrupted?(owner)
+      lock { @interrupts&.delete(owner) }
+    end
+
+    ##
+    # Performs a request through curb and returns a transport response
+    # wrapper so the provider layer can stay transport-agnostic.
+    #
+    # @param [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)
+      easy = build_easy(request)
+      set_request(ActiveRequest.new(easy:), owner)
+      if stream
+        perform_streaming(easy, owner, stream)
+      elsif b
+        res = perform_blocking(easy, owner)
+        if LLM::Transport::Response === res
+          res.success? ? b.call(res) : res
+        else
+          res
+        end
+      else
+        perform_blocking(easy, owner)
+      end
+    ensure
+      clear_request(owner)
+    end
+
+    ##
+    # @return [String]
+    def inspect
+      "#<#{LLM::Utils.object_id(self)}>"
+    end
+
+    private
+
+    attr_reader :host, :port, :timeout, :ssl, :base_uri
+
+    def build_easy(request)
+      LLM.require "curb" unless defined?(::Curl)
+      easy = ::Curl::Easy.new(request_url(request))
+      easy.timeout = timeout
+      easy.connect_timeout = timeout
+      request.headers.each { |k, v| easy.headers[k] = v }
+      easy.follow_location = true
+      easy.ssl_verify_peer = false if !ssl
+      set_body(easy, request)
+      easy
+    end
+
+    def request_url(request)
+      path = request.path
+      return path if path.start_with?("http://", "https://")
+      scheme = ssl ? "https" : "http"
+      default_port = ssl ? 443 : 80
+      authority = port && port.to_i > 0 && port.to_i != default_port \
+                    ? "#{host}:#{port}" : host
+      "#{scheme}://#{authority}#{path}"
+    end
+
+    def set_body(easy, request)
+      case request.method
+      when "POST"
+        easy.post_body = request.body if request.body
+      when "PUT"
+        easy.put_data = request.body if request.body
+      when "DELETE"
+        easy.delete = true
+      end
+    end
+
+    def perform_blocking(easy, owner)
+      check_interrupted(owner)
+      easy.on_body { |chunk|
+        check_interrupted(owner)
+        chunk.bytesize
+      }
+      easy.perform
+      build_response(easy)
+    end
+
+    def perform_streaming(easy, owner, stream)
+      res = nil
+      raw_body = +""
+      decoder = stream.decoder.new(stream.parser.new(stream.streamer))
+      easy.on_body do |chunk|
+        raise LLM::Interrupt, "request interrupted" if interrupted?(owner)
+        if (res ||= build_response_from_headers(easy))&.success? \
+           && res["content-type"].to_s.include?("text/event-stream")
+          decoder << chunk
+        else
+          raw_body << chunk
+        end
+        chunk.bytesize
+      end
+      easy.perform
+      res ||= build_response(easy)
+      if raw_body.empty?
+        body = decoder.body
+        res.body = (Hash === body || Array === body) \
+                     ? LLM::Object.from(body) : body
+      else
+        res.body = raw_body
+      end
+      res
+    ensure
+      decoder&.free
+    end
+
+    def build_response(easy)
+      LLM::Transport::Response::Curb.new(
+        easy.response_code.to_i,
+        parse_headers(easy.header_str.to_s),
+        easy.body_str.to_s
+      )
+    end
+
+    def build_response_from_headers(easy)
+      return nil if easy.header_str.to_s.empty?
+      LLM::Transport::Response::Curb.new(
+        easy.response_code.to_i,
+        parse_headers(easy.header_str.to_s),
+        +""
+      )
+    end
+
+    def parse_headers(header_str)
+      headers = {}
+      header_str.each_line do |line|
+        line = line.strip
+        next if line.empty? || line.start_with?("HTTP/")
+        key, value = line.split(/: \s*/, 2)
+        headers[key.downcase] = value if key && value
+      end
+      headers
+    end
+
+    def check_interrupted(owner)
+      raise LLM::Interrupt, "request interrupted" if interrupted?(owner)
+    end
+
+    def request_for(owner)
+      lock do
+        @requests ||= {}
+        @requests[owner]
+      end
+    end
+
+    def set_request(req, owner)
+      lock do
+        @requests ||= {}
+        @requests[owner] = req
+      end
+    end
+
+    def clear_request(owner)
+      lock { @requests&.delete(owner) }
+    end
+
+    def lock(&)
+      @monitor.synchronize(&)
+    end
+
+    def optional_interrupt_errors
+      defined?(::Async::Stop) ? [Async::Stop] : []
+    end
+  end
+end

data/lib/llm/transport/execution.rb

@@ -13,7 +13,7 @@ class LLM::Transport
 
     ##
     # Executes a HTTP request
-    # @param [Net::HTTPRequest] request
+    # @param [LLM::Transport::Request] request
     #  The request to send
     # @param [Proc] b
     #  A block to yield the response to (optional)

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