llm.rb 4.9.0 → 4.11.0

data/lib/llm/function/task.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+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.
+  class Task
+    ##
+    # @return [Object]
+    attr_reader :task
+
+    ##
+    # @param [Thread, Fiber, Async::Task] task
+    # @return [LLM::Function::Task]
+    def initialize(task)
+      @task = task
+    end
+
+    ##
+    # @return [Boolean]
+    def alive?
+      task.alive?
+    end
+
+    ##
+    # @return [LLM::Function::Return]
+    def wait
+      if Thread === task
+        task.value
+      elsif Fiber === task
+        task.resume if task.alive?
+        task.value
+      else
+        task.wait
+      end
+    end
+    alias_method :value, :wait
+  end
+end

data/lib/llm/function.rb

@@ -29,12 +29,15 @@
 #     end
 #   end
 class LLM::Function
+  require_relative "function/registry"
   require_relative "function/tracing"
   require_relative "function/array"
+  require_relative "function/task"
   require_relative "function/thread_group"
   require_relative "function/fiber_group"
   require_relative "function/task_group"
 
+  extend LLM::Function::Registry
   prepend LLM::Function::Tracing
 
   Return = Struct.new(:id, :name, :value) do
@@ -144,7 +147,7 @@ class LLM::Function
   end
 
   ##
-  # Calls the function in a separate thread.
+  # Calls the function concurrently.
   #
   # This is the low-level method that powers concurrent tool execution.
   # Prefer the collection methods on {LLM::Context#functions} for most
@@ -156,8 +159,8 @@ class LLM::Function
   #   ctx.talk(ctx.functions.wait)
   #
   #   # Direct usage (uncommon)
-  #   thread = tool.spawn
-  #   result = thread.value
+  #   task = tool.spawn(:thread)
+  #   result = task.value
   #
   # @param [Symbol] strategy
   #   Controls concurrency strategy:
@@ -165,10 +168,10 @@ class LLM::Function
   #   - `:task`: Use async tasks (requires async gem)
   #   - `:fiber`: Use raw fibers
   #
-  # @return [Thread, Async::Task, Fiber]
-  #   Returns a thread, async task, or fiber whose `#value` is an {LLM::Function::Return}.
+  # @return [LLM::Function::Task]
+  #   Returns a task whose `#value` is an {LLM::Function::Return}.
   def spawn(strategy)
-    case strategy
+    task = case strategy
     when :task
       require "async" unless defined?(::Async)
       Async { call_function }
@@ -183,6 +186,7 @@ class LLM::Function
     else
       raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :thread, :task, or :fiber"
     end
+    Task.new(task)
   ensure
     @called = true
   end
@@ -260,7 +264,8 @@ class LLM::Function
   #   Returns a Return object with either the function result or error information.
   def call_function
     runner = ((Class === @runner) ? @runner.new : @runner)
-    Return.new(id, name, runner.call(**arguments))
+    kwargs = Hash === arguments ? arguments.transform_keys(&:to_sym) : arguments
+    Return.new(id, name, runner.call(**kwargs))
   rescue => ex
     Return.new(id, name,  {error: true, type: ex.class.name, message: ex.message})
   end

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,156 @@
+# 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?
+      req = Net::HTTP::Post.new(uri.path, 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
+    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
+
+    ##
+    # 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"}).persist!
+    #   # do something with 'mcp'
+    # @return [LLM::MCP::Transport::HTTP]
+    def persist!
+      LLM.lock(:mcp) do
+        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
+    end
+
+    private
+
+    attr_reader :uri, :use_ssl, :headers, :timeout
+
+    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 enqueue(message)
+      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
+  end
+end

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

@@ -78,6 +78,13 @@ 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
+
     private
 
     attr_reader :command, :stdin, :stdout, :stderr

data/lib/llm/mcp.rb

@@ -6,68 +6,118 @@
 # 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}.
+#
+# Like {LLM::Context LLM::Context}, an MCP client is stateful and is
+# expected to remain isolated to a single thread.
 class LLM::MCP
-  require "monitor"
   require_relative "mcp/error"
   require_relative "mcp/command"
   require_relative "mcp/rpc"
   require_relative "mcp/pipe"
+  require_relative "mcp/transport/http"
   require_relative "mcp/transport/stdio"
 
   include RPC
 
+  @@clients = {}
+
+  ##
+  # @api private
+  def self.clients = @@clients
+
+  ##
+  # Builds an MCP client that uses the stdio transport.
+  # @param [LLM::Provider, nil] llm
+  #  An instance of LLM::Provider. Optional.
+  # @param [Hash] stdio
+  #  The stdio transport configuration
+  # @return [LLM::MCP]
+  def self.stdio(llm = nil, **stdio)
+    new(llm, stdio:)
+  end
+
+  ##
+  # Builds an MCP client that uses the HTTP transport.
+  # @param [LLM::Provider, nil] llm
+  #  An instance of LLM::Provider. Optional.
+  # @param [Hash] http
+  #  The HTTP transport configuration
+  # @return [LLM::MCP]
+  def self.http(llm = nil, **http)
+    new(llm, http:)
+  end
+
   ##
   # @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 [Integer] timeout The maximum amount of time to wait when reading from an 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
 
   ##
   # Starts the MCP process.
   # @return [void]
   def start
-    lock do
-      transport.start
-      call(transport, "initialize", {clientInfo: {name: "llm.rb", version: LLM::VERSION}})
-      call(transport, "notifications/initialized")
-    end
+    transport.start
+    call(transport, "initialize", {clientInfo: {name: "llm.rb", version: LLM::VERSION}})
+    call(transport, "notifications/initialized")
   end
 
   ##
   # Stops the MCP process.
   # @return [void]
   def stop
-    lock do
-      transport.stop
-      nil
-    end
+    transport.stop
+    nil
+  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"}).persist!
+  #   # do something with 'mcp'
+  # @return [LLM::MCP]
+  def persist!
+    transport.persist!
+    self
   end
 
   ##
   # Returns the tools provided by the MCP process.
   # @return [Array<Class<LLM::Tool>>]
   def tools
-    lock do
-      res = call(transport, "tools/list")
-      res["tools"].map { LLM::Tool.mcp(self, _1) }
-    end
+    res = call(transport, "tools/list")
+    res["tools"].map { LLM::Tool.mcp(self, _1) }
   end
 
   ##
@@ -76,10 +126,8 @@ class LLM::MCP
   # @param [Hash] arguments The arguments to pass to the tool
   # @return [Object] The result of the tool call
   def call_tool(name, arguments = {})
-    lock do
-      res = call(transport, "tools/call", {name:, arguments:})
-      adapt_tool_result(res)
-    end
+    res = call(transport, "tools/call", {name:, arguments:})
+    adapt_tool_result(res)
   end
 
   private
@@ -95,8 +143,4 @@ class LLM::MCP
       result
     end
   end
-
-  def lock(&)
-    @monitor.synchronize(&)
-  end
 end

data/lib/llm/message.rb

@@ -33,7 +33,7 @@ module LLM
     # Returns a Hash representation of the message.
     # @return [Hash]
     def to_h
-      {role:, content:,
+      {role:, content:, reasoning_content:,
        tools: extra.tool_calls,
        usage:,
        original_tool_calls: extra.original_tool_calls}.compact
@@ -67,6 +67,13 @@ module LLM
       LLM.json.load(content)
     end
 
+    ##
+    # Returns reasoning content associated with the message
+    # @return [String, nil]
+    def reasoning_content
+      extra.reasoning_content
+    end
+
     ##
     # @return [Array<LLM::Function>]
     def functions
@@ -158,7 +165,7 @@ module LLM
     def inspect
       "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
       "tool_call=#{tool_calls.any?} role=#{role.inspect} " \
-      "content=#{content.inspect}>"
+      "content=#{content.inspect} reasoning_content=#{reasoning_content.inspect}>"
     end
 
     private

data/lib/llm/provider.rb

@@ -318,6 +318,15 @@ class LLM::Provider
     end
   end
 
+  ##
+  # @param [Object] stream
+  # @return [Boolean]
+  def streamable?(stream)
+    stream.respond_to?(:on_content) ||
+      stream.respond_to?(:on_reasoning_content) ||
+      stream.respond_to?(:<<)
+  end
+
   private
 
   attr_reader :client, :base_uri, :host, :port, :timeout, :ssl
@@ -393,6 +402,7 @@ class LLM::Provider
           res.body = body
         end
       ensure
+        handler&.free
         parser&.free
       end
     else

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

@@ -51,6 +51,12 @@ module LLM::Anthropic::ResponseAdapter
       super
     end
 
+    ##
+    # (see LLM::Contract::Completion#reasoning_content)
+    def reasoning_content
+      super
+    end
+
     ##
     # (see LLM::Contract::Completion#content!)
     def content!

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

@@ -10,11 +10,12 @@ class LLM::Anthropic
     attr_reader :body
 
     ##
-    # @param [#<<] io An IO-like object
+    # @param [#<<, LLM::Stream] stream
+    #  A stream sink that implements {#<<} or the {LLM::Stream} interface
     # @return [LLM::Anthropic::StreamParser]
-    def initialize(io)
+    def initialize(stream)
       @body = {"role" => "assistant", "content" => []}
-      @io = io
+      @stream = stream
     end
 
     ##
@@ -24,6 +25,12 @@ class LLM::Anthropic
       tap { merge!(chunk) }
     end
 
+    ##
+    # Frees internal parser state used during streaming.
+    # @return [void]
+    def free
+    end
+
     private
 
     def merge!(chunk)
@@ -34,7 +41,7 @@ class LLM::Anthropic
       elsif chunk["type"] == "content_block_delta"
         if chunk["delta"]["type"] == "text_delta"
           @body["content"][chunk["index"]]["text"] << chunk["delta"]["text"]
-          @io << chunk["delta"]["text"] if @io.respond_to?(:<<)
+          emit_content(chunk["delta"]["text"])
         elsif chunk["delta"]["type"] == "input_json_delta"
           content = @body["content"][chunk["index"]]
           if Hash === content["input"]
@@ -53,6 +60,9 @@ class LLM::Anthropic
         if content["input"]
           content["input"] = LLM.json.load(content["input"])
         end
+        if content["type"] == "tool_use"
+          emit_tool(content)
+        end
       end
     end
 
@@ -76,5 +86,28 @@ class LLM::Anthropic
         end
       end
     end
+
+    def emit_content(value)
+      if @stream.respond_to?(:on_content)
+        @stream.on_content(value)
+      elsif @stream.respond_to?(:<<)
+        @stream << value
+      end
+    end
+
+    def emit_tool(tool)
+      return unless @stream.respond_to?(:on_tool_call)
+      function, error = resolve_tool(tool)
+      @stream.on_tool_call(function, error)
+    end
+
+    def resolve_tool(tool)
+      registered = LLM::Function.find_by_name(tool["name"])
+      fn = (registered || LLM::Function.new(tool["name"])).dup.tap do |fn|
+        fn.id = tool["id"]
+        fn.arguments = tool["input"]
+      end
+      [fn, (registered ? nil : @stream.tool_not_found(fn))]
+    end
   end
 end

data/lib/llm/providers/anthropic.rb

@@ -141,7 +141,7 @@ module LLM
       tools = resolve_tools(params.delete(:tools))
       params = [params, adapt_tools(tools)].inject({}, &:merge!).compact
       role, stream = params.delete(:role), params.delete(:stream)
-      params[:stream] = true if stream.respond_to?(:<<) || stream == true
+      params[:stream] = true if streamable?(stream) || stream == true
       [params, stream, tools, role]
     end