llm.rb 4.9.0 → 4.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e876d90bb27d23cb36f97ee0edbc1fe8079a09f473b3a38a31fbd0247f3b9035
-  data.tar.gz: 82fce429783bcc2b8cb3bf8efc4b705ecc4e793cd6b0301ec616b48ec2d68f97
+  metadata.gz: 7fc9e03f0a1b44775f414d310b202dcc68c1a8ebbb4bd7e6e0517902551ffbdf
+  data.tar.gz: 40a11ffd6d8f91ec0babbfb442174e68dac38fc2183922ff5994ff33670c572c
 SHA512:
-  metadata.gz: e2164d4b134ad12316e1ffa1bdf0d73bc52e14c2514e48bfd6a4963dcb9b3f1bcec932728627a49fec1e4a941e576784d48ae50c59ee174eaa8191dda54123c3
-  data.tar.gz: 02bf971e89ee97485f83b87a44eef3cdfec0dc4eb5fc7aad3f1383dce34ef3f889a89ae77738933945248c8ea7d76062270cba2fad2d734eba77ea105abffbe4
+  metadata.gz: ac72f357d340917b99462f12f3a18d30039b3c4f34e8cbb1686da84f3c75b0d67919fc2d90732268301fa45a25d9e9d721d5e1f33a46a387196349878e384dd0
+  data.tar.gz: 92d7f611de8229d7f5cbe065169f0688940753eb1bffcc0ef907fd1d66ec18be840848b692aca81d24b1dfc6068011b644ed9be890e863ed8fa5d51194f089ed

data/README.md

@@ -4,7 +4,7 @@
 <p align="center">
   <a href="https://0x1eef.github.io/x/llm.rb?rebuild=1"><img src="https://img.shields.io/badge/docs-0x1eef.github.io-blue.svg" alt="RubyDoc"></a>
   <a href="https://opensource.org/license/0bsd"><img src="https://img.shields.io/badge/License-0BSD-orange.svg?" alt="License"></a>
-  <a href="https://github.com/llmrb/llm.rb/tags"><img src="https://img.shields.io/badge/version-4.9.0-green.svg?" alt="Version"></a>
+  <a href="https://github.com/llmrb/llm.rb/tags"><img src="https://img.shields.io/badge/version-4.10.0-green.svg?" alt="Version"></a>
 </p>
 
 ## About
@@ -139,6 +139,30 @@ ensure
 end
 ```
 
+You can also connect to a hosted MCP server over HTTP. This is useful when the
+server already runs remotely and exposes MCP through a URL instead of a local
+process:
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"])
+mcp = LLM.mcp(http: {
+  url: "https://api.githubcopilot.com/mcp/",
+  headers: {"Authorization" => "Bearer #{ENV.fetch("GITHUB_PAT")}"}
+})
+
+begin
+  mcp.start
+  ctx = LLM::Context.new(llm, stream: $stdout, tools: mcp.tools)
+  ctx.talk("List the available GitHub MCP toolsets.")
+  ctx.talk(ctx.functions.call) while ctx.functions.any?
+ensure
+  mcp.stop
+end
+```
+
 #### Streaming Chat
 
 This example demonstrates llm.rb's streaming support. The `stream: $stdout`
@@ -209,6 +233,7 @@ require "pp"
 class Report < LLM::Schema
   property :category, Enum["performance", "security", "outage"], "Report category", required: true
   property :summary, String, "Short summary", required: true
+  property :impact, OneOf[String, Integer], "Primary impact, as text or a count", required: true
   property :services, Array[String], "Impacted services", required: true
   property :timestamp, String, "When it happened", optional: true
 end
@@ -221,6 +246,7 @@ pp res.content!
 # {
 #   "category" => "performance",
 #   "summary" => "Database latency spiked, causing 5% request timeouts for 12 minutes.",
+#   "impact" => "5% request timeouts",
 #   "services" => ["Database"],
 #   "timestamp" => "2024-06-05T10:42:00Z"
 # }

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module LLM::MCP::Transport
+  ##
+  # The {LLM::MCP::Transport::HTTP::EventHandler LLM::MCP::Transport::HTTP::EventHandler}
+  # class adapts generic server-sent event callbacks into decoded JSON-RPC
+  # messages for {LLM::MCP::Transport::HTTP LLM::MCP::Transport::HTTP}.
+  # It accumulates event data until a blank line terminates the current
+  # event, then parses the payload as JSON and yields it to the callback
+  # given at initialization.
+  # @private
+  class HTTP::EventHandler
+    ##
+    # @yieldparam [Hash] message
+    #  A decoded JSON-RPC message
+    # @return [LLM::MCP::Transport::HTTP::EventHandler]
+    def initialize(&on_message)
+      @on_message = on_message
+      reset
+    end
+
+    ##
+    # Receives the SSE event name.
+    # @param [LLM::EventStream::Event] event
+    #  The event stream event
+    # @return [void]
+    def on_event(event)
+      @event = event.value
+    end
+
+    ##
+    # Receives one line of SSE data.
+    # @param [LLM::EventStream::Event] event
+    #  The event stream event
+    # @return [void]
+    def on_data(event)
+      @data << event.value.to_s
+    end
+
+    # The generic event stream parser dispatches one line at a time.
+    # A blank line terminates the current SSE event.
+    # @param [LLM::EventStream::Event] event
+    #  The event stream event
+    # @return [void]
+    def on_chunk(event)
+      flush if event.chunk == "\n"
+    end
+
+    private
+
+    def flush
+      return reset if @data.empty? && @event.nil?
+      payload = @data.join("\n")
+      reset
+      return if payload.empty? || payload == "[DONE]"
+      @on_message.call(LLM.json.load(payload))
+    rescue *LLM.json.parser_error
+      reset
+    end
+
+    def reset
+      @event = nil
+      @data = []
+    end
+  end
+end

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module LLM::MCP::Transport
+  ##
+  # The {LLM::MCP::Transport::HTTP LLM::MCP::Transport::HTTP} class
+  # provides an HTTP transport for {LLM::MCP LLM::MCP}. It sends
+  # JSON-RPC messages with HTTP POST requests and buffers response
+  # messages for non-blocking reads.
+  class HTTP
+    require_relative "http/event_handler"
+
+    ##
+    # @param [String] url
+    #  The URL for the MCP HTTP endpoint
+    # @param [Hash] headers
+    #  Extra headers to send with requests
+    # @param [Integer, nil] timeout
+    #  The timeout in seconds. Defaults to nil
+    # @return [LLM::MCP::Transport::HTTP]
+    def initialize(url:, headers: {}, timeout: nil)
+      @uri = URI.parse(url)
+      @use_ssl = @uri.scheme == "https"
+      @headers = headers
+      @timeout = timeout
+      @queue = []
+      @monitor = Monitor.new
+      @running = false
+    end
+
+    ##
+    # Starts the HTTP transport.
+    # @raise [LLM::MCP::Error]
+    #  When the transport is already running
+    # @return [void]
+    def start
+      lock do
+        raise LLM::MCP::Error, "MCP transport is already running" if running?
+        @queue.clear
+        @running = true
+      end
+    end
+
+    ##
+    # Stops the HTTP transport and closes the connection.
+    # This method is idempotent.
+    # @return [void]
+    def stop
+      lock do
+        return nil unless running?
+        @running = false
+        nil
+      end
+    end
+
+    ##
+    # Writes a JSON-RPC message via HTTP POST.
+    # @param [Hash] message
+    #  The JSON-RPC message
+    # @raise [LLM::MCP::Error]
+    #  When the transport is not running or the HTTP request fails
+    # @return [void]
+    def write(message)
+      raise LLM::MCP::Error, "MCP transport is not running" unless running?
+      http = Net::HTTP.start(uri.host, uri.port, use_ssl:, open_timeout: timeout, read_timeout: timeout)
+      req = Net::HTTP::Post.new(uri.path, headers.merge("content-type" => "application/json"))
+      req.body = LLM.json.dump(message)
+      http.request(req) do |res|
+        unless Net::HTTPSuccess === res
+          raise LLM::MCP::Error, "MCP transport write failed with HTTP #{res.code}"
+        end
+        read(res)
+      end
+    end
+
+    ##
+    # Reads the next queued message without blocking.
+    # @raise [LLM::MCP::Error]
+    #  When the transport is not running
+    # @raise [IO::WaitReadable]
+    #  When no complete message is available to read
+    # @return [Hash]
+    def read_nonblock
+      lock do
+        raise LLM::MCP::Error, "MCP transport is not running" unless running?
+        raise IO::WaitReadable if @queue.empty?
+        @queue.shift
+      end
+    end
+
+    ##
+    # @return [Boolean]
+    #  Returns true when the MCP server connection is alive
+    def running?
+      @running
+    end
+
+    private
+
+    attr_reader :uri, :use_ssl, :headers, :timeout
+
+    def enqueue(message)
+      lock { @queue << message }
+    end
+
+    def read(res)
+      if res["content-type"].to_s.include?("text/event-stream")
+        parser = LLM::EventStream::Parser.new
+        parser.register EventHandler.new { enqueue(_1) }
+        res.read_body { parser << _1 }
+        parser.free
+      else
+        body = +""
+        res.read_body { body << _1 }
+        enqueue(LLM.json.load(body)) unless body.empty?
+      end
+    end
+
+    def lock(&)
+      @monitor.synchronize(&)
+    end
+  end
+end

data/lib/llm/mcp.rb

@@ -6,8 +6,8 @@
 # clients and servers to exchange capabilities such as tools, prompts,
 # resources, and other structured interactions.
 #
-# In llm.rb, {LLM::MCP LLM::MCP} currently supports stdio servers and
-# focuses on discovering tools that can be used through
+# In llm.rb, {LLM::MCP LLM::MCP} currently supports stdio and HTTP
+# transports and focuses on discovering tools that can be used through
 # {LLM::Context LLM::Context} and {LLM::Agent LLM::Agent}.
 class LLM::MCP
   require "monitor"
@@ -15,6 +15,7 @@ class LLM::MCP
   require_relative "mcp/command"
   require_relative "mcp/rpc"
   require_relative "mcp/pipe"
+  require_relative "mcp/transport/http"
   require_relative "mcp/transport/stdio"
 
   include RPC
@@ -22,21 +23,34 @@ class LLM::MCP
   ##
   # @param [LLM::Provider, nil] llm
   #  The provider to use for MCP transports that need one
-  # @param [Hash] stdio The configuration for the stdio transport
+  # @param [Hash, nil] stdio The configuration for the stdio transport
   # @option stdio [Array<String>] :argv
   #  The command to run for the MCP process
   # @option stdio [Hash] :env
   #  The environment variables to set for the MCP process
   # @option stdio [String, nil] :cwd
   #  The working directory for the MCP process
+  # @param [Hash, nil] http The configuration for the HTTP transport
+  # @option http [String] :url
+  #  The URL for the MCP HTTP endpoint
+  # @option http [Hash] :headers
+  #  Extra headers for requests
   # @param [Integer] timeout The maximum amount of time to wait when reading from an MCP process
   # @return [LLM::MCP] A new MCP instance
-  def initialize(llm = nil, stdio:, timeout: 30)
+  def initialize(llm = nil, stdio: nil, http: nil, timeout: 30)
     @llm = llm
-    @command = Command.new(**stdio)
     @monitor = Monitor.new
-    @transport = Transport::Stdio.new(command:)
     @timeout = timeout
+    if stdio && http
+      raise ArgumentError, "stdio and http are mutually exclusive"
+    elsif stdio
+      @command = Command.new(**stdio)
+      @transport = Transport::Stdio.new(command:)
+    elsif http
+      @transport = Transport::HTTP.new(**http, timeout:)
+    else
+      raise ArgumentError, "stdio or http is required"
+    end
   end
 
   ##

data/lib/llm/schema/all_of.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class LLM::Schema
+  ##
+  # The {LLM::Schema::AllOf LLM::Schema::AllOf} class represents an
+  # allOf union in a JSON schema. It is a subclass of
+  # {LLM::Schema::Leaf LLM::Schema::Leaf}.
+  class AllOf < Leaf
+    ##
+    # Returns an allOf union for the given types.
+    # @return [LLM::Schema::AllOf]
+    def self.[](*types)
+      schema = LLM::Schema.new
+      new(types.map { LLM::Schema::Utils.resolve(schema, _1) })
+    end
+
+    ##
+    # @param [Array<LLM::Schema::Leaf>] values
+    #  The values required by the union
+    # @return [LLM::Schema::AllOf]
+    def initialize(values)
+      @values = values
+    end
+
+    ##
+    # @return [Hash]
+    def to_h
+      super.merge!(allOf: @values)
+    end
+  end
+end

data/lib/llm/schema/any_of.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class LLM::Schema
+  ##
+  # The {LLM::Schema::AnyOf LLM::Schema::AnyOf} class represents an
+  # anyOf union in a JSON schema. It is a subclass of
+  # {LLM::Schema::Leaf LLM::Schema::Leaf}.
+  class AnyOf < Leaf
+    ##
+    # Returns an anyOf union for the given types.
+    # @return [LLM::Schema::AnyOf]
+    def self.[](*types)
+      schema = LLM::Schema.new
+      new(types.map { LLM::Schema::Utils.resolve(schema, _1) })
+    end
+
+    ##
+    # @param [Array<LLM::Schema::Leaf>] values
+    #  The values allowed by the union
+    # @return [LLM::Schema::AnyOf]
+    def initialize(values)
+      @values = values
+    end
+
+    ##
+    # @return [Hash]
+    def to_h
+      super.merge!(anyOf: @values)
+    end
+  end
+end

data/lib/llm/schema/one_of.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class LLM::Schema
+  ##
+  # The {LLM::Schema::OneOf LLM::Schema::OneOf} class represents an
+  # oneOf union in a JSON schema. It is a subclass of
+  # {LLM::Schema::Leaf LLM::Schema::Leaf}.
+  class OneOf < Leaf
+    ##
+    # Returns a oneOf union for the given types.
+    # @return [LLM::Schema::OneOf]
+    def self.[](*types)
+      schema = LLM::Schema.new
+      new(types.map { LLM::Schema::Utils.resolve(schema, _1) })
+    end
+
+    ##
+    # @param [Array<LLM::Schema::Leaf>] values
+    #  The values allowed by the union
+    # @return [LLM::Schema::OneOf]
+    def initialize(values)
+      @values = values
+    end
+
+    ##
+    # @return [Hash]
+    def to_h
+      super.merge!(oneOf: @values)
+    end
+  end
+end

data/lib/llm/schema/parser.rb

@@ -8,6 +8,8 @@ class LLM::Schema
   # external JSON schema definitions into the schema objects used
   # throughout llm.rb.
   module Parser
+    METADATA_KEYS = %w[description default enum const].freeze
+
     ##
     # Parses a JSON schema into an {LLM::Schema::Leaf}.
     # @param [Hash] schema
@@ -27,6 +29,8 @@ class LLM::Schema
       when "number" then apply(parse_number(schema), schema)
       when "boolean" then apply(schema().boolean, schema)
       when "null" then apply(schema().null, schema)
+      when ::Array then apply(schema().any_of(*schema["type"].map { parse(schema.except("type", *METADATA_KEYS).merge("type" => _1), root) }), schema.except("type"))
+      when nil then parse_union(schema, root)
       else raise TypeError, "unsupported schema type #{schema["type"].inspect}"
       end
     end
@@ -50,6 +54,14 @@ class LLM::Schema
       schema().array(items)
     end
 
+    def parse_union(schema, root)
+      return apply(schema().any_of(*schema["anyOf"].map { parse(_1, root) }), schema) if schema.key?("anyOf")
+      return apply(schema().one_of(*schema["oneOf"].map { parse(_1, root) }), schema) if schema.key?("oneOf")
+      return apply(schema().all_of(*schema["allOf"].map { parse(_1, root) }), schema) if schema.key?("allOf")
+      return parse(infer_type(schema), root) if infer_type(schema)
+      raise TypeError, "unsupported schema type #{schema["type"].inspect}"
+    end
+
     def parse_string(schema)
       leaf = schema().string
       leaf.min(schema["minLength"]) if schema.key?("minLength")
@@ -105,5 +117,29 @@ class LLM::Schema
     rescue KeyError
       raise TypeError, "unresolvable schema ref #{ref.inspect}"
     end
+
+    def infer_type(schema)
+      if schema.key?("const")
+        schema.merge("type" => type_of(schema["const"]))
+      elsif schema.key?("enum")
+        type = type_of(schema["enum"].first)
+        return unless type && schema["enum"].all? { type_of(_1) == type }
+        schema.merge("type" => type)
+      elsif schema.key?("default")
+        schema.merge("type" => type_of(schema["default"]))
+      end
+    end
+
+    def type_of(value)
+      case value
+      when ::Hash then "object"
+      when ::Array then "array"
+      when ::String then "string"
+      when ::Integer then "integer"
+      when ::Float then "number"
+      when ::TrueClass, ::FalseClass then "boolean"
+      when ::NilClass then "null"
+      end
+    end
   end
 end

data/lib/llm/schema.rb

@@ -35,6 +35,9 @@ class LLM::Schema
   require_relative "schema/leaf"
   require_relative "schema/object"
   require_relative "schema/array"
+  require_relative "schema/all_of"
+  require_relative "schema/any_of"
+  require_relative "schema/one_of"
   require_relative "schema/string"
   require_relative "schema/enum"
   require_relative "schema/number"
@@ -45,6 +48,23 @@ class LLM::Schema
   @__monitor = Monitor.new
   extend LLM::Schema::Parser
 
+  ##
+  # @api private
+  module Utils
+    extend self
+
+    def resolve(schema, type)
+      if LLM::Schema::Leaf === type
+        type
+      elsif Class === type && type.respond_to?(:object)
+        type.object
+      else
+        target = type.name.split("::").last.downcase
+        schema.public_send(target)
+      end
+    end
+  end
+
   ##
   # Configures a monitor for a subclass
   # @return [void]
@@ -65,14 +85,7 @@ class LLM::Schema
   #  A hash of options
   def self.property(name, type, description, options = {})
     lock do
-      if LLM::Schema::Leaf === type
-        prop = type
-      elsif Class === type && type.respond_to?(:object)
-        prop = type.object
-      else
-        target = type.name.split("::").last.downcase
-        prop = schema.public_send(target)
-      end
+      prop = Utils.resolve(schema, type)
       options = {description:}.merge(options)
       options.each { (_2 == true) ? prop.public_send(_1) : prop.public_send(_1, *_2) }
       object[name] = prop
@@ -120,6 +133,30 @@ class LLM::Schema
     Array.new(*items)
   end
 
+  ##
+  # Returns an anyOf union
+  # @param [Array<LLM::Schema::Leaf>] values The union values
+  # @return [LLM::Schema::AnyOf]
+  def any_of(*values)
+    AnyOf.new(values)
+  end
+
+  ##
+  # Returns an allOf union
+  # @param [Array<LLM::Schema::Leaf>] values The union values
+  # @return [LLM::Schema::AllOf]
+  def all_of(*values)
+    AllOf.new(values)
+  end
+
+  ##
+  # Returns a oneOf union
+  # @param [Array<LLM::Schema::Leaf>] values The union values
+  # @return [LLM::Schema::OneOf]
+  def one_of(*values)
+    OneOf.new(values)
+  end
+
   ##
   # Returns a string
   # @return [LLM::Schema::String]

data/lib/llm/tool.rb

@@ -22,9 +22,10 @@ class LLM::Tool
   extend LLM::Tool::Param
 
   types = [
-    :Leaf, :String, :Enum, :Array,
+    :Leaf, :String, :Enum,
+    :AllOf, :AnyOf, :OneOf,
     :Object, :Integer, :Number,
-    :Boolean, :Null
+    :Array, :Boolean, :Null
   ]
   types.each do |constant|
     const_set constant, LLM::Schema.const_get(constant)

data/lib/llm/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 4.9.0
+  version: 4.10.0
 platform: ruby
 authors:
 - Antar Azri
@@ -271,6 +271,8 @@ files:
 - lib/llm/mcp/error.rb
 - lib/llm/mcp/pipe.rb
 - lib/llm/mcp/rpc.rb
+- lib/llm/mcp/transport/http.rb
+- lib/llm/mcp/transport/http/event_handler.rb
 - lib/llm/mcp/transport/stdio.rb
 - lib/llm/message.rb
 - lib/llm/mime.rb
@@ -358,6 +360,8 @@ files:
 - lib/llm/registry.rb
 - lib/llm/response.rb
 - lib/llm/schema.rb
+- lib/llm/schema/all_of.rb
+- lib/llm/schema/any_of.rb
 - lib/llm/schema/array.rb
 - lib/llm/schema/boolean.rb
 - lib/llm/schema/enum.rb
@@ -366,6 +370,7 @@ files:
 - lib/llm/schema/null.rb
 - lib/llm/schema/number.rb
 - lib/llm/schema/object.rb
+- lib/llm/schema/one_of.rb
 - lib/llm/schema/parser.rb
 - lib/llm/schema/string.rb
 - lib/llm/schema/version.rb