llm.rb 4.10.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.rb

@@ -61,10 +61,16 @@ module LLM::MCP::Transport
     # @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|
+      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
@@ -94,14 +100,30 @@ 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"}).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 enqueue(message)
-      lock { @queue << message }
-    end
-
     def read(res)
       if res["content-type"].to_s.include?("text/event-stream")
         parser = LLM::EventStream::Parser.new
@@ -115,6 +137,18 @@ module LLM::MCP::Transport
       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

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

@@ -9,8 +9,10 @@
 # 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"
@@ -20,6 +22,34 @@ class LLM::MCP
 
   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
@@ -35,11 +65,11 @@ class LLM::MCP
   #  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
+  # @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: nil, http: nil, timeout: 30)
     @llm = llm
-    @monitor = Monitor.new
     @timeout = timeout
     if stdio && http
       raise ArgumentError, "stdio and http are mutually exclusive"
@@ -57,31 +87,37 @@ class LLM::MCP
   # 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
 
   ##
@@ -90,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
@@ -109,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
 

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

@@ -51,6 +51,12 @@ module LLM::Google::ResponseAdapter
       super
     end
 
+    ##
+    # (see LLM::Contract::Completion#reasoning_content)
+    def reasoning_content
+      super
+    end
+
     ##
     # (see LLM::Contract::Completion#content!)
     def content!
@@ -60,21 +66,22 @@ module LLM::Google::ResponseAdapter
     private
 
     def adapt_choices
-      candidates.map.with_index do |choice, index|
+      candidates.map.with_index do |choice, cindex|
         content = choice.content || LLM::Object.new
         role = content.role || "model"
         parts = content.parts || [{"text" => choice.finishReason}]
         text = parts.filter_map { _1["text"] }.join
         tools = parts.select { _1["functionCall"] }
-        extra = {index:, response: self, tool_calls: adapt_tool_calls(tools), original_tool_calls: tools}
+        extra = {index: cindex, response: self, tool_calls: adapt_tool_calls(parts, cindex), original_tool_calls: tools}
         LLM::Message.new(role, text, extra)
       end
     end
 
-    def adapt_tool_calls(parts)
-      (parts || []).map do |part|
+    def adapt_tool_calls(parts, cindex)
+      (parts || []).each_with_index.filter_map do |part, pindex|
         tool = part["functionCall"]
-        {name: tool.name, arguments: tool.args}
+        next unless tool
+        {id: LLM::Google.tool_id(part:, cindex:, pindex:), name: tool.name, arguments: tool.args}
       end
     end
 

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

@@ -10,11 +10,13 @@ class LLM::Google
     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::Google::StreamParser]
-    def initialize(io)
+    def initialize(stream)
       @body = {"candidates" => []}
-      @io = io
+      @stream = stream
+      @emits = {tools: []}
     end
 
     ##
@@ -24,6 +26,13 @@ class LLM::Google
       tap { merge_chunk!(chunk) }
     end
 
+    ##
+    # Frees internal parser state used during streaming.
+    # @return [void]
+    def free
+      @emits.clear
+    end
+
     private
 
     def merge_chunk!(chunk)
@@ -49,7 +58,7 @@ class LLM::Google
         delta.each do |key, value|
           k = key.to_s
           if k == "content"
-            merge_candidate_content!(candidate["content"], value) if value
+            merge_candidate_content!(candidate["content"], value, index) if value
           else
             candidate[k] = value # Overwrite other fields
           end
@@ -57,24 +66,24 @@ class LLM::Google
       end
     end
 
-    def merge_candidate_content!(content, delta)
+    def merge_candidate_content!(content, delta, cindex)
       delta.each do |key, value|
         k = key.to_s
         if k == "parts"
           content["parts"] ||= []
-          merge_content_parts!(content["parts"], value) if value
+          merge_content_parts!(content["parts"], value, cindex) if value
         else
           content[k] = value
         end
       end
     end
 
-    def merge_content_parts!(parts, deltas)
+    def merge_content_parts!(parts, deltas, cindex)
       deltas.each do |delta|
         if delta["text"]
           merge_text!(parts, delta)
         elsif delta["functionCall"]
-          merge_function_call!(parts, delta)
+          merge_function_call!(parts, delta, cindex)
         elsif delta["inlineData"]
           parts << delta
         elsif delta["functionResponse"]
@@ -93,14 +102,14 @@ class LLM::Google
       if last_existing_part.is_a?(Hash) && last_existing_part["text"]
         last_existing_part["text"] ||= +""
         last_existing_part["text"] << text
-        @io << text if @io.respond_to?(:<<)
+        emit_content(text)
       else
         parts << delta
-        @io << text if @io.respond_to?(:<<)
+        emit_content(text)
       end
     end
 
-    def merge_function_call!(parts, delta)
+    def merge_function_call!(parts, delta, cindex)
       last_existing_part = parts.last
       last_call = last_existing_part.is_a?(Hash) ? last_existing_part["functionCall"] : nil
       delta_call = delta["functionCall"]
@@ -113,6 +122,40 @@ class LLM::Google
       else
         parts << delta
       end
+      emit_tool(parts.length - 1, cindex, parts.last || delta)
+    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(pindex, cindex, part)
+      return unless @stream.respond_to?(:on_tool_call)
+      return unless complete_tool?(part)
+      key = [cindex, pindex]
+      return if @emits[:tools].include?(key)
+      function, error = resolve_tool(part, cindex, pindex)
+      @emits[:tools] << key
+      @stream.on_tool_call(function, error)
+    end
+
+    def complete_tool?(part)
+      call = part["functionCall"]
+      call && call["name"] && Hash === call["args"]
+    end
+
+    def resolve_tool(part, cindex, pindex)
+      call = part["functionCall"]
+      registered = LLM::Function.find_by_name(call["name"])
+      fn = (registered || LLM::Function.new(call["name"])).dup.tap do |fn|
+        fn.id = LLM::Google.tool_id(part:, cindex:, pindex:)
+        fn.arguments = call["args"]
+      end
+      [fn, (registered ? nil : @stream.tool_not_found(fn))]
     end
   end
 end

data/lib/llm/providers/google/utils.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+class LLM::Google
+  module Utils
+    ##
+    # Returns a stable internal tool-call ID for Gemini function calls.
+    #
+    # Gemini responses may omit a direct tool-call ID, but llm.rb expects one
+    # for matching pending tool calls with tool returns across streaming and
+    # normal completion flows.
+    #
+    # When Gemini provides a `thoughtSignature`, that value is used as the
+    # basis for the ID. Otherwise the ID falls back to the candidate and part
+    # indexes, which are stable within the response.
+    #
+    # @param part [Hash]
+    #   A Gemini content part containing a `functionCall`.
+    # @param cindex [Integer]
+    #   The candidate index for the tool call.
+    # @param pindex [Integer]
+    #   The part index for the tool call within the candidate.
+    # @return [String]
+    #   Returns a stable internal tool-call ID.
+    def tool_id(part:, cindex:, pindex:)
+      signature = part["thoughtSignature"].to_s
+      return "google_#{signature}" unless signature.empty?
+      "google_call_#{cindex}_#{pindex}"
+    end
+  end
+end