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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+##
+# The {LLM::Model LLM::Model} class provides a normalized view of
+# a provider model record returned by the models API.
+class LLM::Model
+  ##
+  # The provider-specific model payload.
+  # @return [LLM::Object]
+  attr_reader :raw
+
+  ##
+  # @param [LLM::Object, Hash] raw
+  def initialize(raw)
+    @raw = raw
+  end
+
+  ##
+  # Returns a normalized identifier suitable for API calls.
+  # @return [String, nil]
+  def id
+    normalize_id(raw.id || raw.model || raw.name)
+  end
+
+  ##
+  # Returns a display-friendly model name.
+  # @return [String, nil]
+  def name
+    raw.display_name || raw.displayName || id
+  end
+
+  ##
+  # Best-effort predicate for chat support.
+  # @return [Boolean]
+  def chat?
+    return true if anthropic?
+    return [*(raw.supportedGenerationMethods || [])].include?("generateContent") if google?
+    openai_compatible_chat?
+  end
+
+  ##
+  # Returns a Hash representation of the normalized model.
+  # @return [Hash]
+  def to_h
+    {id:, name:, chat?: chat?}.compact
+  end
+
+  ##
+  # @private
+  module Collection
+    include ::Enumerable
+
+    ##
+    # @yield [model]
+    # @yieldparam [LLM::Model] model
+    # @return [Enumerator, void]
+    def each(&)
+      return enum_for(:each) unless block_given?
+      models.each(&)
+    end
+
+    ##
+    # Returns an element, or a slice, or nil.
+    # @return [Object, Array<Object>, nil]
+    def [](*pos, **kw)
+      models[*pos, **kw]
+    end
+
+    ##
+    # @return [Boolean]
+    def empty?
+      models.empty?
+    end
+
+    ##
+    # @return [Integer]
+    def size
+      models.size
+    end
+
+    ##
+    # Returns normalized models.
+    # @return [Array<LLM::Model>]
+    def models
+      @models ||= raw_models.map { LLM::Model.new(_1) }
+    end
+  end
+
+  private
+
+  def normalize_id(value)
+    value&.sub(%r{\Amodels/}, "")
+  end
+
+  def anthropic?
+    raw.type == "model" && raw.key?(:display_name) && raw.key?(:created_at)
+  end
+
+  def google?
+    raw.key?(:supportedGenerationMethods)
+  end
+
+  def openai_compatible_chat?
+    value = [id, raw.name, raw.model].compact.join(" ").downcase
+    return false if value.include?("embedding")
+    return false if value.include?("moderation")
+    return false if value.include?("tts")
+    return false if value.include?("transcrib")
+    return false if value.include?("image")
+    return false if value.include?("whisper")
+    return false if value.include?("dall")
+    return false if value.include?("omni-moderation")
+    true
+  end
+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