llm.rb 4.8.0 → 4.9.0

data/lib/llm/mcp/rpc.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+class LLM::MCP
+  ##
+  # The {LLM::MCP::RPC} module provides the JSON-RPC interface used by
+  # {LLM::MCP}. MCP uses JSON-RPC to exchange messages between a client
+  # and a server. A client sends a method name and its parameters as a
+  # request, and the server replies with either a result or an error.
+  #
+  # This module is responsible for composing those requests, applying
+  # the defaults needed by built-in MCP methods such as initialize,
+  # and reading responses for request methods. Notifications are sent
+  # without waiting for a response, and errors are raised as
+  # {LLM::MCP::Error}.
+  # @private
+  module RPC
+    ##
+    # Sends a method over the transport.
+    # @param [LLM::MCP::Transport] transport
+    #  The transport to write to
+    # @param [String] method
+    #  The method name to call
+    # @param [Hash] params
+    #  The parameters to send with the method call
+    # @return [Object, nil]
+    #  The result of the method call, or nil if it's a notification
+    def call(transport, method, params = {})
+      message = {jsonrpc: "2.0", method:, params: default_params(method).merge(params)}
+      if notification?(method)
+        transport.write(message)
+        nil
+      else
+        @request_id = (@request_id || -1) + 1
+        id = @request_id
+        transport.write(message.merge(id:))
+        recv(transport, id)
+      end
+    end
+
+    private
+
+    ##
+    # Reads a response from the transport.
+    # @param [LLM::MCP::Transport] transport
+    #  The transport to read from
+    # @param [Integer] id
+    #  The request id to wait for
+    # @raise [LLM::MCP::Error]
+    #  When the MCP process returns an error
+    # @return [Object, nil]
+    #  The result returned by the MCP process
+    def recv(transport, id)
+      poll(timeout:, ex: [IO::WaitReadable]) do
+        loop do
+          res = transport.read_nonblock
+          next unless res["id"] == id
+          if res["error"]
+            raise LLM::MCP::Error.from(response: res)
+          else
+            break res["result"]
+          end
+        end
+      end
+    end
+
+    ##
+    # Returns default parameters for built-in methods.
+    # @param [String] method
+    #  The method name
+    # @return [Hash]
+    def default_params(method)
+      case method
+      when "initialize"
+        {protocolVersion: "2025-03-26", capabilities: {}}
+      else
+        {}
+      end
+    end
+
+    ##
+    # Returns true when the method is a notification.
+    # @param [String] method
+    #  The method name
+    # @return [Boolean]
+    def notification?(method)
+      method.to_s.start_with?("notifications/")
+    end
+
+    ##
+    # Returns the maximum amount of time to wait when reading from an MCP process.
+    # @return [Integer]
+    def timeout
+      @timeout ||= 5
+    end
+
+    ##
+    # Runs a block until it succeeds, times out, or raises an unhandled exception.
+    # @param [Integer] timeout
+    #  The timeout for the block, in seconds
+    # @param [Array<Class>] ex
+    #  The exceptions to retry when raised
+    # @yield
+    #  The block to run
+    # @raise [LLM::MCP::TimeoutError]
+    #  When the block takes longer than the timeout
+    # @return [Object]
+    def poll(timeout:, ex: [])
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      loop do
+        return yield
+      rescue *ex
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+        raise LLM::MCP::TimeoutError, "MCP process timed out" if duration > timeout
+        sleep 0.05
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module LLM::MCP::Transport
+  ##
+  # The {LLM::MCP::Transport::Stdio LLM::MCP::Transport::Stdio} class
+  # provides a stdio transport for {LLM::MCP LLM::MCP}. It sends JSON-RPC
+  # messages to an MCP process over stdin and stdout and delegates process
+  # lifecycle management to {LLM::MCP::Command LLM::MCP::Command}.
+  class Stdio
+    ##
+    # Returns a new Stdio transport instance.
+    # @param command [LLM::MCP::Command]
+    #  The command to run for the MCP process
+    # @return [LLM::MCP::Transport::Stdio]
+    def initialize(command:)
+      @command = command
+    end
+
+    ##
+    # Starts an MCP process over a stdio transport.
+    # This method is non-blocking and returns immediately.
+    # @raise [LLM::Error]
+    #  When the transport is already running
+    # @return [void]
+    def start
+      if command.alive?
+        raise LLM::MCP::Error, "MCP transport is already running"
+      else
+        command.start
+      end
+    end
+
+    ##
+    # Closes the connection to the MCP process.
+    # This method is idempotent and can be called multiple times without error.
+    # @return [void]
+    def stop
+      command.stop
+    end
+
+    ##
+    # Writes a message to the MCP process.
+    # @param [Hash] message
+    #  The message to write
+    # @raise [LLM::Error]
+    #  When the transport is not running
+    # @return [void]
+    def write(message)
+      if command.alive?
+        command.write(LLM.json.dump(message))
+      else
+        raise LLM::MCP::Error, "MCP transport is not running"
+      end
+    end
+
+    ##
+    # Reads a message from the MCP process without blocking.
+    # @raise [LLM::Error]
+    #  When the transport is not running
+    # @raise [IO::WaitReadable]
+    #  When no complete message is available to read
+    # @return [Hash]
+    #  The next message from the MCP process
+    def read_nonblock
+      if command.alive?
+        LLM.json.load(command.read_nonblock)
+      else
+        raise LLM::MCP::Error, "MCP transport is not running"
+      end
+    end
+
+    ##
+    # Waits for the command to exit.
+    # This method is blocking and will return only after the
+    # process has exited.
+    # @return [void]
+    def wait
+      command.wait
+    end
+
+    private
+
+    attr_reader :command, :stdin, :stdout, :stderr
+  end
+end

data/lib/llm/mcp.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+##
+# The {LLM::MCP LLM::MCP} class provides access to servers that
+# implement the Model Context Protocol. MCP defines a standard way for
+# 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
+# {LLM::Context LLM::Context} and {LLM::Agent LLM::Agent}.
+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/stdio"
+
+  include RPC
+
+  ##
+  # @param [LLM::Provider, nil] llm
+  #  The provider to use for MCP transports that need one
+  # @param [Hash] 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
+  # @return [LLM::MCP] A new MCP instance
+  def initialize(llm = nil, stdio:, timeout: 30)
+    @llm = llm
+    @command = Command.new(**stdio)
+    @monitor = Monitor.new
+    @transport = Transport::Stdio.new(command:)
+    @timeout = timeout
+  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
+  end
+
+  ##
+  # Stops the MCP process.
+  # @return [void]
+  def stop
+    lock do
+      transport.stop
+      nil
+    end
+  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
+  end
+
+  ##
+  # Calls a tool by name with the given arguments
+  # @param [String] name The name of the tool to call
+  # @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
+  end
+
+  private
+
+  attr_reader :llm, :command, :transport, :timeout
+
+  def adapt_tool_result(result)
+    if result["structuredContent"]
+      result["structuredContent"]
+    elsif result["content"]
+      {content: result["content"]}
+    else
+      result
+    end
+  end
+
+  def lock(&)
+    @monitor.synchronize(&)
+  end
+end

data/lib/llm/message.rb

@@ -26,7 +26,7 @@ module LLM
     def initialize(role, content, extra = {})
       @role = role.to_s
       @content = content
-      @extra = extra
+      @extra = LLM::Object.from(extra)
     end
 
     ##
@@ -34,8 +34,9 @@ module LLM
     # @return [Hash]
     def to_h
       {role:, content:,
-       tools: @extra[:tool_calls],
-       original_tool_calls: extra[:original_tool_calls]}.compact
+       tools: extra.tool_calls,
+       usage:,
+       original_tool_calls: extra.original_tool_calls}.compact
     end
 
     ##
@@ -69,8 +70,9 @@ module LLM
     ##
     # @return [Array<LLM::Function>]
     def functions
-      @functions ||= tool_calls.map do |fn|
-        function = available_tools.find { _1.name.to_s == fn["name"] }.dup
+      @functions ||= tool_calls.filter_map do |fn|
+        function = available_tools.find { _1.name.to_s == fn["name"] } || next
+        function = function.dup
         function.tap { _1.id = fn.id }
         function.tap { _1.arguments = fn.arguments }
       end
@@ -119,7 +121,7 @@ module LLM
     # @return [LLM::Response, nil]
     #  Returns the response associated with the message, or nil
     def response
-      extra[:response]
+      extra.response
     end
 
     ##
@@ -129,7 +131,7 @@ module LLM
     # Returns annotations associated with the message
     # @return [Array<LLM::Object>]
     def annotations
-      @annotations ||= LLM::Object.from(extra["annotations"] || [])
+      @annotations ||= LLM::Object.from(extra.annotations || [])
     end
 
     ##
@@ -139,8 +141,7 @@ module LLM
     # Returns token usage statistics
     # @return [LLM::Object, nil]
     def usage
-      return nil unless response
-      @usage ||= response.usage
+      @usage ||= extra.usage || response&.usage
     end
     alias_method :token_usage, :usage
 
@@ -163,11 +164,12 @@ module LLM
     private
 
     def tool_calls
-      @tool_calls ||= LLM::Object.from(@extra[:tool_calls] || [])
+      @tool_calls ||= LLM::Object.from(extra.tool_calls || [])
     end
 
     def available_tools
-      response&.__tools__ || []
+      tools = extra.tools || response&.__tools__ || []
+      tools.map { _1.respond_to?(:function) ? _1.function : _1 }
     end
   end
 end

data/lib/llm/model.rb

@@ -34,7 +34,7 @@ class LLM::Model
   # @return [Boolean]
   def chat?
     return true if anthropic?
-    return [*(raw.supportedGenerationMethods || [])].include?("generateContent") if gemini?
+    return [*(raw.supportedGenerationMethods || [])].include?("generateContent") if google?
     openai_compatible_chat?
   end
 
@@ -96,7 +96,7 @@ class LLM::Model
     raw.type == "model" && raw.key?(:display_name) && raw.key?(:created_at)
   end
 
-  def gemini?
+  def google?
     raw.key?(:supportedGenerationMethods)
   end
 

data/lib/llm/prompt.rb

@@ -5,20 +5,20 @@
 # a single request from multiple role-aware messages.
 # A prompt is not just a string. It is an ordered chain of
 # messages with explicit roles (for example `system` and `user`).
-# Use {LLM::Session#prompt} when building a prompt inside a session.
+# Use {LLM::Context#prompt} when building a prompt inside a session.
 # Use `LLM::Prompt.new(provider)` directly when you want to construct
 # or pass prompt objects around explicitly.
 #
 # @example
 #   llm = LLM.openai(key: ENV["KEY"])
-#   ses = LLM::Session.new(llm)
+#   ctx = LLM::Context.new(llm)
 #
-#   prompt = ses.prompt do
+#   prompt = ctx.prompt do
 #     system "Your task is to assist the user"
 #     user "Hello. Can you assist me?"
 #   end
 #
-#   res = ses.talk(prompt)
+#   res = ctx.talk(prompt)
 class LLM::Prompt
   ##
   # @param [LLM::Provider] provider
@@ -57,7 +57,7 @@ class LLM::Prompt
   #  The message content
   # @return [void]
   def user(content)
-    chat(content, role: @provider.user_role)
+    talk(content, role: @provider.user_role)
   end
 
   ##
@@ -65,7 +65,7 @@ class LLM::Prompt
   #  The message content
   # @return [void]
   def system(content)
-    chat(content, role: @provider.system_role)
+    talk(content, role: @provider.system_role)
   end
 
   ##
@@ -73,7 +73,7 @@ class LLM::Prompt
   #  The message content
   # @return [void]
   def developer(content)
-    chat(content, role: @provider.developer_role)
+    talk(content, role: @provider.developer_role)
   end
 
   ##
@@ -82,4 +82,14 @@ class LLM::Prompt
   def to_a
     @buffer.dup
   end
+
+  ##
+  # Returns true when two prompts have the same buffer
+  # @param [LLM::Prompt] other
+  # @return [Boolean]
+  def ==(other)
+    return false unless LLM::Prompt === other
+    @buffer == other.to_a
+  end
+  alias_method :eql?, :==
 end

data/lib/llm/provider.rb

@@ -50,6 +50,15 @@ class LLM::Provider
     "#<#{self.class.name}:0x#{object_id.to_s(16)} @key=[REDACTED] @client=#{@client.inspect} @tracer=#{tracer.inspect}>"
   end
 
+  ##
+  # @raise [NotImplementedError]
+  #  When the method is not implemented by a subclass
+  # @return [Symbol]
+  #  Returns the provider's name
+  def name
+    raise NotImplementedError
+  end
+
   ##
   # Provides an embedding
   # @param [String, Array<String>] input
@@ -93,10 +102,10 @@ class LLM::Provider
   # Starts a new chat powered by the chat completions API
   # @param prompt (see LLM::Provider#complete)
   # @param params (see LLM::Provider#complete)
-  # @return [LLM::Session]
+  # @return [LLM::Context]
   def chat(prompt, params = {})
     role = params.delete(:role)
-    LLM::Session.new(self, params).talk(prompt, role:)
+    LLM::Context.new(self, params).talk(prompt, role:)
   end
 
   ##
@@ -104,10 +113,10 @@ class LLM::Provider
   # @param prompt (see LLM::Provider#complete)
   # @param params (see LLM::Provider#complete)
   # @raise (see LLM::Provider#complete)
-  # @return [LLM::Session]
+  # @return [LLM::Context]
   def respond(prompt, params = {})
     role = params.delete(:role)
-    LLM::Session.new(self, params).respond(prompt, role:)
+    LLM::Context.new(self, params).respond(prompt, role:)
   end
 
   ##
@@ -122,7 +131,7 @@ class LLM::Provider
   end
 
   ##
-  # @return [LLM::OpenAI::Images, LLM::Gemini::Images]
+  # @return [LLM::OpenAI::Images, LLM::Google::Images]
   #  Returns an interface to the images API
   def images
     raise NotImplementedError
@@ -264,13 +273,13 @@ class LLM::Provider
 
   ##
   # @return [LLM::Tracer]
-  #  Returns a thread-local tracer
+  #  Returns a fiber-local tracer
   def tracer
     weakmap[self] || LLM::Tracer::Null.new(self)
   end
 
   ##
-  # Set a thread-local tracer
+  # Set a fiber-local tracer
   # @example
   #   llm = LLM.openai(key: ENV["KEY"])
   #   Thread.new do
@@ -367,16 +376,22 @@ class LLM::Provider
     args = (Net::HTTP === http) ? [request] : [URI.join(base_uri, request.path), request]
     res = if stream
       http.request(*args) do |res|
-        handler = event_handler.new stream_parser.new(stream)
-        parser = LLM::EventStream::Parser.new
-        parser.register(handler)
-        res.read_body(parser)
-        # If the handler body is empty, the response was
-        # most likely not streamed or parsing failed.
-        # Preserve the raw body in that case so standard
-        # JSON/error handling can parse it later.
-        body = handler.body.empty? ? parser.body : handler.body
-        res.body = Hash === body || Array === body ? LLM::Object.from(body) : body
+        if Net::HTTPSuccess === res
+          handler = event_handler.new stream_parser.new(stream)
+          parser = LLM::EventStream::Parser.new
+          parser.register(handler)
+          res.read_body(parser)
+          # If the handler body is empty, the response was
+          # most likely not streamed or parsing failed.
+          # Preserve the raw body in that case so standard
+          # JSON/error handling can parse it later.
+          body = handler.body.empty? ? parser.body : handler.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

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

@@ -10,10 +10,10 @@ class LLM::Anthropic
   #   require "llm"
   #
   #   llm = LLM.anthropic(key: ENV["KEY"])
-  #   ses = LLM::Session.new(llm)
+  #   ctx = LLM::Context.new(llm)
   #   file = llm.files.create file: "/books/goodread.pdf"
-  #   ses.talk ["Tell me about this PDF", file]
-  #   ses.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
+  #   ctx.talk ["Tell me about this PDF", file]
+  #   ctx.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
   class Files
     ##
     # Returns a new Files object

data/lib/llm/providers/anthropic.rb

@@ -10,9 +10,9 @@ module LLM
   #   require "llm"
   #
   #   llm = LLM.anthropic(key: ENV["KEY"])
-  #   ses = LLM::Session.new(llm)
-  #   ses.talk ["Tell me about this photo", ses.local_file("/images/photo.png")]
-  #   ses.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
+  #   ctx = LLM::Context.new(llm)
+  #   ctx.talk ["Tell me about this photo", ctx.local_file("/images/photo.png")]
+  #   ctx.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
   class Anthropic < Provider
     require_relative "anthropic/error_handler"
     require_relative "anthropic/request_adapter"
@@ -30,6 +30,13 @@ module LLM
       super(host: HOST, **)
     end
 
+    ##
+    # @return [Symbol]
+    #  Returns the provider's name
+    def name
+      :anthropic
+    end
+
     ##
     # Provides an interface to the chat completions API
     # @see https://docs.anthropic.com/en/api/messages Anthropic docs
@@ -139,12 +146,20 @@ module LLM
     end
 
     def build_complete_request(prompt, params, role)
-      messages = [*(params.delete(:messages) || []), Message.new(role, prompt)]
+      messages = build_complete_messages(prompt, params, role)
       payload = adapt(messages)
       body = LLM.json.dump(payload.merge!(params))
       req = Net::HTTP::Post.new("/v1/messages", headers)
       set_body_stream(req, StringIO.new(body))
       req
     end
+
+    def build_complete_messages(prompt, params, role)
+      if LLM::Prompt === prompt
+        [*(params.delete(:messages) || []), *prompt.to_a]
+      else
+        [*(params.delete(:messages) || []), Message.new(role, prompt)]
+      end
+    end
   end
 end

data/lib/llm/providers/deepseek.rb

@@ -14,9 +14,9 @@ module LLM
   #   require "llm"
   #
   #   llm = LLM.deepseek(key: ENV["KEY"])
-  #   ses = LLM::Session.new(llm)
-  #   ses.talk ["Tell me about this photo", ses.local_file("/images/photo.png")]
-  #   ses.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
+  #   ctx = LLM::Context.new(llm)
+  #   ctx.talk ["Tell me about this photo", ctx.local_file("/images/photo.png")]
+  #   ctx.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
   class DeepSeek < OpenAI
     require_relative "deepseek/request_adapter"
     include DeepSeek::RequestAdapter
@@ -28,6 +28,13 @@ module LLM
       super
     end
 
+    ##
+    # @return [Symbol]
+    #  Returns the provider's name
+    def name
+      :deepseek
+    end
+
     ##
     # @raise [NotImplementedError]
     def files