llm.rb 10.0.0 → 11.0.0

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

@@ -7,7 +7,7 @@ module LLM::MCP::Transport
   # JSON-RPC messages with HTTP POST requests and buffers response
   # messages for non-blocking reads.
   class HTTP
-    require_relative "http/event_handler"
+    include LLM::Transport::Utils
 
     ##
     # @param [String] url
@@ -22,7 +22,7 @@ module LLM::MCP::Transport
     def initialize(url:, headers: {}, timeout: nil, transport: nil)
       @uri = URI.parse(url)
       @headers = headers
-      @transport = resolve_transport(transport, timeout:)
+      @transport = resolve_transport(uri, transport, timeout)
       @queue = []
       @monitor = Monitor.new
       @running = false
@@ -101,24 +101,11 @@ module LLM::MCP::Transport
       res
     end
 
-    def resolve_transport(transport, timeout:)
-      return default_transport(timeout:) if transport.nil?
-      if Class === transport && transport <= LLM::Transport
-        return transport.new(host: uri.host, port: uri.port, timeout:, ssl: uri.scheme == "https")
-      end
-      transport
-    end
-
-    def default_transport(timeout:)
-      LLM::Transport::HTTP.new(host: uri.host, port: uri.port, timeout:, ssl: uri.scheme == "https")
-    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
+        decoder = LLM::Transport::StreamDecoder.new { enqueue(_1) }
+        res.read_body { decoder << _1 }
+        decoder.free
       else
         body = +""
         res.read_body { body << _1 }

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

@@ -78,6 +78,13 @@ module LLM::MCP::Transport
       command.wait
     end
 
+    ##
+    # @return [Boolean]
+    #  Returns true when the MCP server connection is alive
+    def running?
+      command.alive?
+    end
+
     private
 
     attr_reader :command, :stdin, :stdout, :stderr

data/lib/llm/mcp.rb

@@ -26,29 +26,23 @@ class LLM::MCP
 
   ##
   # 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:)
+  def self.stdio(**stdio)
+    new(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:)
+  def self.http(**http)
+    new(http:)
   end
 
   ##
-  # @param [LLM::Provider, nil] llm
-  #  The provider to use for MCP transports that need one
   # @param [Hash, nil] stdio The configuration for the stdio transport
   # @option stdio [Array<String>] :argv
   #  The command to run for the MCP process
@@ -67,8 +61,7 @@ class LLM::MCP
   # @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
+  def initialize(stdio: nil, http: nil, timeout: 30)
     @timeout = timeout
     if stdio && http
       raise ArgumentError, "stdio and http are mutually exclusive"
@@ -116,12 +109,13 @@ class LLM::MCP
   ensure
     stop
   end
+  alias_method :session, :run
 
   ##
   # Returns the tools provided by the MCP process.
   # @return [Array<Class<LLM::Tool>>]
   def tools
-    res = call(transport, "tools/list")
+    res = with_session { call(transport, "tools/list") }
     res["tools"].map { LLM::Tool.mcp(self, _1) }
   end
 
@@ -129,7 +123,7 @@ class LLM::MCP
   # Returns the prompts provided by the MCP process.
   # @return [Array<LLM::Object>]
   def prompts
-    res = call(transport, "prompts/list")
+    res = with_session { call(transport, "prompts/list") }
     LLM::Object.from(res["prompts"])
   end
 
@@ -141,7 +135,7 @@ class LLM::MCP
   def find_prompt(name:, arguments: nil)
     params = {name:}
     params[:arguments] = arguments if arguments
-    res = call(transport, "prompts/get", params)
+    res = with_session { call(transport, "prompts/get", params) }
     res["messages"] = [*res["messages"]].map do |message|
       LLM::Message.new(
         message["role"],
@@ -159,13 +153,22 @@ 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 = {})
-    res = call(transport, "tools/call", {name:, arguments:})
+    res = with_session { call(transport, "tools/call", {name:, arguments:}) }
     adapt_tool_result(res)
   end
 
   private
 
-  attr_reader :llm, :command, :transport, :timeout
+  attr_reader :command, :transport, :timeout
+
+  def with_session
+    return yield if transport.running?
+    session_started = true
+    start
+    yield
+  ensure
+    stop if session_started
+  end
 
   def adapt_content(content)
     case content

data/lib/llm/message.rb

@@ -205,7 +205,7 @@ module LLM
     # Returns a string representation of the message
     # @return [String]
     def inspect
-      "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
+      "#<#{LLM::Utils.object_id(self)} " \
       "tool_call=#{tool_calls.any?} role=#{role.inspect} " \
       "content=#{content.inspect} reasoning_content=#{reasoning_content.inspect}>"
     end

data/lib/llm/object/kernel.rb

@@ -48,7 +48,7 @@ class LLM::Object
     end
 
     def inspect
-      "#<#{self.class}:0x#{object_id.to_s(16)} properties=#{to_h.inspect}>"
+      "#<#{LLM::Utils.object_id(self)} properties=#{to_h.inspect}>"
     end
     alias_method :to_s, :inspect
 

data/lib/llm/provider.rb

@@ -32,7 +32,7 @@ class LLM::Provider
     @port = port
     @timeout = timeout
     @ssl = ssl
-    @base_path = normalize_base_path(base_path)
+    @base_path = LLM::Utils.normalize_base_path(base_path)
     @base_uri = URI("#{ssl ? "https" : "http"}://#{host}:#{port}/")
     @headers = {"User-Agent" => "llm.rb v#{LLM::VERSION}"}
     @transport = resolve_transport(transport, persistent:)
@@ -44,7 +44,7 @@ class LLM::Provider
   # @return [String]
   # @note The secret key is redacted in inspect for security reasons
   def inspect
-    "#<#{self.class.name}:0x#{object_id.to_s(16)} @key=[REDACTED] @transport=#{transport.inspect} @tracer=#{tracer.inspect}>"
+    "#<#{LLM::Utils.object_id(self)} @key=[REDACTED] @transport=#{transport.inspect} @tracer=#{tracer.inspect}>"
   end
 
   ##
@@ -353,13 +353,6 @@ class LLM::Provider
     "#{@base_path}#{suffix}"
   end
 
-  def normalize_base_path(path)
-    path = path.to_s.strip
-    return "" if path.empty? || path == "/"
-    path = "/#{path}" unless path.start_with?("/")
-    path.sub(%r{/+\z}, "")
-  end
-
   attr_reader :base_uri, :host, :port, :timeout, :ssl, :transport
 
   ##

data/lib/llm/response.rb

@@ -46,7 +46,7 @@ module LLM
     # Returns an inspection of the response object
     # @return [String]
     def inspect
-      "#<#{self.class.name}:0x#{object_id.to_s(16)} @body=#{body.inspect} @res=#{@res.inspect}>"
+      "#<#{LLM::Utils.object_id(self)} @body=#{body.inspect} @res=#{@res.inspect}>"
     end
 
     ##

data/lib/llm/sequel/agent.rb

@@ -33,19 +33,24 @@ module LLM::Sequel
         @llm_agent_options || Agent::DEFAULTS
       end
 
-      def model(model = nil)
-        return agent.model if model.nil?
-        agent.model(model)
+      def model(model = nil, &block)
+        return agent.model if model.nil? && !block
+        agent.model(model, &block)
       end
 
-      def tools(*tools)
-        return agent.tools if tools.empty?
-        agent.tools(*tools)
+      def tools(*tools, &block)
+        return agent.tools if tools.empty? && !block
+        agent.tools(*tools, &block)
       end
 
-      def schema(schema = nil)
-        return agent.schema if schema.nil?
-        agent.schema(schema)
+      def skills(*skills, &block)
+        return agent.skills if skills.empty? && !block
+        agent.skills(*skills, &block)
+      end
+
+      def schema(schema = nil, &block)
+        return agent.schema if schema.nil? && !block
+        agent.schema(schema, &block)
       end
 
       def instructions(instructions = nil)

data/lib/llm/sequel/plugin.rb

@@ -75,11 +75,12 @@ module LLM::Sequel
       ##
       # Persists the runtime state and usage columns back onto the record.
       # @return [void]
-      def self.save(obj, ctx, options)
+      def self.save!(obj, ctx, options)
         columns = self.columns(options)
         payload = serialize_context(ctx, options[:format])
         payload = wrap_json_payload(payload, options[:format])
-        obj.update(columns[:data_column] => payload)
+        obj[columns[:data_column]] = payload
+        obj.save_changes(raise_on_failure: true)
       end
 
       ##
@@ -159,16 +160,16 @@ module LLM::Sequel
     # @return [LLM::Response]
     def talk(...)
       options = self.class.llm_plugin_options
-      ctx.talk(...).tap { Utils.save(self, ctx, options) }
+      ctx.talk(...).tap { Utils.save!(self, ctx, options) }
     end
 
     ##
-    # Continues the stored context through the Responses API and flushes it.
-    # @see LLM::Context#respond
+    # Continues the stored context with new input and flushes it.
+    # @see LLM::Context#ask
     # @return [LLM::Response]
-    def respond(...)
+    def ask(...)
       options = self.class.llm_plugin_options
-      ctx.respond(...).tap { Utils.save(self, ctx, options) }
+      ctx.ask(...).tap { Utils.save!(self, ctx, options) }
     end
 
     ##

data/lib/llm/tool.rb

@@ -40,31 +40,54 @@ class LLM::Tool
   # @return [Class<LLM::Tool>]
   #  Returns a subclass of LLM::Tool
   def self.mcp(mcp, tool)
-    lock do
-      @mcp = true
-      klass = Class.new(LLM::Tool) do
-        name tool["name"]
-        description tool["description"]
-        params { tool["inputSchema"] || {type: "object", properties: {}} }
-
-        define_singleton_method(:inspect) do
-          "<LLM::Tool:0x#{object_id.to_s(16)} name=#{tool["name"]} (mcp)>"
-        end
-        singleton_class.alias_method :to_s, :inspect
-
-        define_singleton_method(:mcp?) do
-          true
-        end
-
-        define_method(:call) do |**args|
-          mcp.call_tool(tool["name"], args)
-        end
+    Class.new(LLM::Tool) do
+      name tool["name"]
+      description tool["description"]
+      params { tool["inputSchema"] || {type: "object", properties: {}} }
+
+      define_singleton_method(:inspect) do
+        "<#{LLM::Utils.object_id(self)} name=#{tool["name"]} (mcp)>"
+      end
+      singleton_class.alias_method :to_s, :inspect
+
+      define_singleton_method(:mcp?) do
+        true
+      end
+
+      define_method(:call) do |**args|
+        mcp.call_tool(tool["name"], args)
+      end
+    end
+  end
+
+  ##
+  # @param [LLM::A2A] a2a
+  #  The A2A client that will execute the tool call
+  # @param [LLM::A2A::Card::Skill]
+  #  An A2A tool
+  # @return [Class<LLM::Tool>]
+  #  Returns a subclass of LLM::Tool
+  def self.a2a(a2a, skill)
+    name = skill.name.gsub(" ", "-")
+    Class.new(LLM::Tool) do
+      name(name)
+      description(skill.description)
+      parameter :input, String, "The input string"
+      required %i[input]
+
+      define_singleton_method(:inspect) do
+        "<#{LLM::Utils.object_id(self)} name=#{name} (a2a)>"
+      end
+      singleton_class.alias_method :to_s, :inspect
+
+      define_singleton_method(:a2a?) do
+        true
+      end
+
+      define_method(:call) do |input:|
+        res = a2a.send_message(input)
+        {task: res}
       end
-      @mcp = false
-      register(klass)
-      klass
-    ensure
-      @mcp = false
     end
   end
 
@@ -106,8 +129,8 @@ class LLM::Tool
   def self.inherited(tool)
     LLM.lock(:inherited) do
       tool.instance_eval { @__monitor ||= Monitor.new }
-      tool.function.register(tool)
-      LLM::Tool.register(tool) unless lock { @mcp }
+      tool.function.define(tool)
+      LLM::Tool.register(tool) unless tool.mcp? || tool.a2a?
     end
   end
 
@@ -172,11 +195,18 @@ class LLM::Tool
     false
   end
 
+  ##
+  # Returns true if the tool is an A2A tool
+  # @return [Boolean]
+  def self.a2a?
+    false
+  end
+
   ##
   # Returns a function bound to this tool instance.
   # @return [LLM::Function]
   def function
-    @function ||= self.class.function.dup.tap { _1.register(self) }
+    @function ||= self.class.function.dup.tap { _1.define(self) }
   end
 
   ##

data/lib/llm/tracer.rb

@@ -128,7 +128,7 @@ module LLM
     ##
     # @return [String]
     def inspect
-      "#<#{self.class.name}:0x#{object_id.to_s(16)} @provider=#{@llm.class} @tracer=#{@tracer.inspect}>"
+      "#<#{LLM::Utils.object_id(self)} @provider=#{@llm.class} @tracer=#{@tracer.inspect}>"
     end
 
     ##

data/lib/llm/transport/http.rb

@@ -83,7 +83,7 @@ class LLM::Transport
     ##
     # @return [String]
     def inspect
-      "#<#{self.class.name}:0x#{object_id.to_s(16)}>"
+      "#<#{LLM::Utils.object_id(self)}>"
     end
 
     private

data/lib/llm/transport/stream_decoder.rb

@@ -13,13 +13,15 @@ class LLM::Transport
     attr_reader :parser
 
     ##
-    # @param [#parse!, #body] parser
+    # @param [#parse!, #body, nil] parser
+    # @yieldparam [Hash] chunk
     # @return [LLM::Transport::StreamDecoder]
-    def initialize(parser)
+    def initialize(parser = nil, &on_chunk)
       @buffer = +""
       @cursor = 0
       @data = []
       @parser = parser
+      @on_chunk = on_chunk
     end
 
     ##
@@ -78,7 +80,8 @@ class LLM::Transport
     def decode!(payload)
       return if payload.empty? || payload == "[DONE]"
       chunk = LLM.json.load(payload)
-      parser.parse!(chunk) if chunk
+      return unless chunk
+      parser ? parser.parse!(chunk) : @on_chunk&.call(chunk)
     rescue *LLM.json.parser_error
     end
 

data/lib/llm/transport/utils.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+class LLM::Transport
+  ##
+  # Shared utility methods for HTTP-backed transports.
+  #
+  # @api private
+  module Utils
+    extend self
+    private
+
+    def resolve_transport(uri, transport, timeout)
+      return default_transport(uri, timeout) if transport.nil?
+      if Class === transport && transport <= LLM::Transport
+        transport.new(
+          host: uri.host,
+          port: uri.port,
+          timeout:,
+          ssl: uri.scheme == "https"
+        )
+      else
+        transport
+      end
+    end
+
+    def default_transport(uri, timeout)
+      LLM::Transport::HTTP.new(
+        host: uri.host,
+        port: uri.port,
+        timeout:,
+        ssl: uri.scheme == "https"
+      )
+    end
+  end
+end

data/lib/llm/transport.rb

@@ -27,6 +27,7 @@ module LLM
   # transport-specific classes.
   class Transport
     require_relative "transport/response"
+    require_relative "transport/utils"
     require_relative "transport/stream_decoder"
     require_relative "transport/http"
     require_relative "transport/persistent_http"

data/lib/llm/utils.rb

@@ -25,5 +25,49 @@ module LLM
       else option
       end
     end
+
+    ##
+    # Normalizes an HTTP API base path.
+    #
+    # Blank paths normalize to an empty string. Non-empty paths are
+    # prefixed with a leading slash and stripped of trailing slashes.
+    #
+    # @param [String, nil] path
+    # @return [String]
+    def normalize_base_path(path)
+      path = path.to_s.strip
+      return "" if path.empty? || path == "/"
+      path = "/#{path}" unless path.start_with?("/")
+      path.sub(%r{/+\z}, "")
+    end
+
+    ##
+    # Returns the Ruby module or class name for an object.
+    #
+    # This bypasses overridden `#name` implementations by binding
+    # {Module#name} directly.
+    #
+    # @param [Module] obj
+    # @return [String, nil]
+    def name_of(obj)
+      ::Module.instance_method(:name).bind(obj).call
+    end
+
+    ##
+    # Renders the class-and-object-id portion of an inspect string.
+    #
+    # This returns strings like `LLM::Tool:0x1234abcd`, which can be
+    # embedded into custom inspect output.
+    #
+    # @param [Object] obj
+    # @return [String]
+    def object_id(obj)
+      klass = if Class === obj
+        name_of(obj) || name_of(obj.superclass) || obj.class.name
+      else
+        obj.class.name || obj.class.to_s
+      end
+      "#{klass}:0x#{obj.object_id.to_s(16)}"
+    end
   end
 end

data/lib/llm/version.rb

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

data/lib/llm.rb

@@ -2,6 +2,7 @@
 
 module LLM
   require "stringio"
+  require "securerandom"
   require_relative "llm/json_adapter"
   require_relative "llm/tracer"
   require_relative "llm/error"
@@ -35,6 +36,7 @@ module LLM
   require_relative "llm/skill"
   require_relative "llm/server_tool"
   require_relative "llm/mcp"
+  require_relative "llm/a2a"
 
   ##
   # Thread-safe monitors for different contexts
@@ -179,8 +181,6 @@ module LLM
   end
 
   ##
-  # @param [LLM::Provider, nil] llm
-  #  The provider to use for MCP transports that need one
   # @param [Hash, nil] stdio
   # @option stdio [Array<String>] :argv
   #  The command to run for the MCP process
@@ -189,8 +189,27 @@ module LLM
   # @option stdio [String, nil] :cwd
   #  The working directory for the MCP process
   # @return [LLM::MCP]
-  def mcp(llm = nil, **)
-    LLM::MCP.new(llm, **)
+  def mcp(**)
+    LLM::MCP.new(**)
+  end
+
+  ##
+  # Creates a new A2A client connected to a remote agent.
+  #
+  # @param [Hash, nil] http
+  # @option http [String] :url
+  #  The base URL of the A2A agent (e.g., "https://agent.example.com")
+  # @option http [Hash<String, String>] :headers
+  #  Extra HTTP headers (e.g., Authorization)
+  # @option http [Integer, nil] :timeout
+  #  Request timeout in seconds
+  # @option http [LLM::Transport, Class, nil] :transport
+  #  Optional transport override
+  # @param [Symbol] binding
+  #  The protocol binding to use. One of `:rest` or `:jsonrpc`
+  # @return [LLM::A2A]
+  def a2a(http:, binding: :rest)
+    LLM::A2A.http(**http, binding:)
   end
 
   ##

data/llm.gemspec

@@ -9,7 +9,22 @@ Gem::Specification.new do |spec|
   spec.email = ["azantar@proton.me", "0x1eef@hardenedbsd.org"]
 
   spec.summary = "Ruby's most capable AI runtime"
-  spec.description = spec.summary
+  spec.description = <<~DESC
+  llm.rb is Ruby's most capable AI runtime.
+
+  It runs on Ruby's standard library by default. loads optional pieces
+  only when needed, and offers a single runtime for providers, agents,
+  tools, skills, MCP, A2A (Agent2Agent), RAG (vector stores & embeddings),
+  streaming, files, and persisted state. As a bonus, llm.rb is also available
+  for mruby.
+
+  It supports OpenAI, OpenAI-compatible endpoints, Anthropic, Google
+  Gemini, DeepSeek, xAI, Z.ai, AWS Bedrock, Ollama, and llama.cpp. It
+  also includes built-in ActiveRecord and Sequel support, plus concurrent
+  tool execution through threads, tasks (via async gem), fibers, ractors,
+  and fork (via xchan.rb gem).
+  DESC
+
   spec.license = "0BSD"
   spec.required_ruby_version = ">= 3.3.0"