llm.rb 9.0.0 → 11.0.0

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
 
   ##
@@ -339,6 +339,13 @@ class LLM::Provider
     LLM::Stream === stream || stream.respond_to?(:<<)
   end
 
+  ##
+  # @return [Boolean]
+  #  Returns true when an API key is configured
+  def key?
+    @key != nil && @key.to_s.strip.size > 0
+  end
+
   private
 
   def path(suffix)
@@ -346,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/providers/anthropic/stream_parser.rb

@@ -105,14 +105,14 @@ class LLM::Anthropic
     end
 
     def resolve_tool(tool)
-      registered = @stream.find_tool(tool["name"])
+      registered = @stream.__find__(tool["name"])
       fn = (registered || LLM::Function.new(tool["name"])).dup.tap do |fn|
         fn.id = tool["id"]
         fn.arguments = LLM::Anthropic.parse_tool_input(tool["input"])
         fn.tracer = @stream.extra[:tracer]
         fn.model = @stream.extra[:model]
       end
-      [fn, (registered ? nil : @stream.tool_not_found(fn))]
+      [fn, (registered ? nil : fn.unavailable)]
     end
   end
 end

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

@@ -184,14 +184,14 @@ class LLM::Bedrock
 
     def resolve_tool(tool)
       payload = tool["toolUse"] || {}
-      registered = @stream.find_tool(payload["name"])
+      registered = @stream.__find__(payload["name"])
       fn = (registered || LLM::Function.new(payload["name"])).dup.tap do |f|
         f.id = payload["toolUseId"]
         f.arguments = payload["input"] || {}
         f.tracer = @stream.extra[:tracer]
         f.model = @stream.extra[:model]
       end
-      [fn, registered ? nil : @stream.tool_not_found(fn)]
+      [fn, registered ? nil : fn.unavailable]
     end
 
     def content

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

@@ -153,14 +153,14 @@ class LLM::Google
 
     def resolve_tool(part, cindex, pindex)
       call = part["functionCall"]
-      registered = @stream.find_tool(call["name"])
+      registered = @stream.__find__(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"]
         fn.tracer = @stream.extra[:tracer]
         fn.model = @stream.extra[:model]
       end
-      [fn, (registered ? nil : @stream.tool_not_found(fn))]
+      [fn, (registered ? nil : fn.unavailable)]
     end
   end
 end

data/lib/llm/providers/openai/responses/stream_parser.rb

@@ -269,14 +269,14 @@ class LLM::OpenAI
     # @group Resolvers
 
     def resolve_tool(tool, arguments)
-      registered = @stream.find_tool(tool["name"])
+      registered = @stream.__find__(tool["name"])
       fn = (registered || LLM::Function.new(tool["name"])).dup.tap do |fn|
         fn.id = tool["call_id"]
         fn.arguments = arguments
         fn.tracer = @stream.extra[:tracer]
         fn.model = @stream.extra[:model]
       end
-      [fn, (registered ? nil : @stream.tool_not_found(fn))]
+      [fn, (registered ? nil : fn.unavailable)]
     end
 
     def parse_arguments(arguments)

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

@@ -185,14 +185,14 @@ class LLM::OpenAI
     end
 
     def resolve_tool(tool, function, arguments)
-      registered = @stream.find_tool(function["name"])
+      registered = @stream.__find__(function["name"])
       fn = (registered || LLM::Function.new(function["name"])).dup.tap do |fn|
         fn.id = tool["id"]
         fn.arguments = arguments
         fn.tracer = @stream.extra[:tracer]
         fn.model = @stream.extra[:model]
       end
-      [fn, (registered ? nil : @stream.tool_not_found(fn))]
+      [fn, (registered ? nil : fn.unavailable)]
     end
 
     def parse_arguments(arguments)

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/schema.rb

@@ -56,6 +56,8 @@ class LLM::Schema
     def resolve(schema, type)
       if LLM::Schema::Leaf === type
         type
+      elsif ::Array === type
+        resolve_array(schema, type)
       elsif Class === type && type.respond_to?(:object)
         type.object
       else
@@ -63,6 +65,15 @@ class LLM::Schema
         schema.public_send(target)
       end
     end
+
+    def resolve_array(schema, values)
+      item = if values.size == 1
+        resolve(schema, values[0])
+      else
+        schema.any_of(*values.map { resolve(schema, _1) })
+      end
+      schema.array(item)
+    end
   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)
@@ -58,6 +63,11 @@ module LLM::Sequel
         agent.concurrency(concurrency)
       end
 
+      def confirm(*tool_names, &block)
+        return agent.confirm if tool_names.empty? && !block
+        agent.confirm(*tool_names, &block)
+      end
+
       def tracer(tracer = nil, &block)
         return agent.tracer if tracer.nil? && !block
         agent.tracer(tracer, &block)

data/lib/llm/sequel/plugin.rb

@@ -30,12 +30,7 @@ module LLM::Sequel
       # Resolves a single configured option against a model instance.
       # @return [Object]
       def self.resolve_option(obj, option)
-        case option
-        when Proc then obj.instance_exec(&option)
-        when Symbol then obj.send(option)
-        when Hash then option.dup
-        else option
-        end
+        LLM::Utils.resolve_option(obj, option)
       end
 
       ##
@@ -80,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
 
       ##
@@ -164,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/stream.rb

@@ -9,8 +9,7 @@ module LLM
   # subclass that overrides the callbacks it needs. For basic streaming,
   # llm.rb also accepts any object that implements `#<<`. {#queue} provides
   # a small helper for collecting asynchronous tool work started from a
-  # callback, and {#tool_not_found} returns an in-band tool error when a
-  # streamed tool cannot be resolved.
+  # callback.
   #
   # @note The `on_*` callbacks run inline with the streaming parser. They
   #   therefore block streaming progress and should generally return as
@@ -150,48 +149,24 @@ module LLM
 
     # @endgroup
 
-    # @group Error handlers
-
-    ##
-    # Returns a function return describing a streamed tool that could not
-    # be resolved.
-    # @note This is mainly useful as a fallback from {#on_tool_call}. It
-    #   should be uncommon in normal use, since streamed tool callbacks only
-    #   run for tools already defined in the context.
-    # @param [LLM::Function] tool
-    # @return [LLM::Function::Return]
-    def tool_not_found(tool)
-      LLM::Function::Return.new(tool.id, tool.name, {
-        error: true, type: LLM::NoSuchToolError.name, message: "tool not found"
-      })
-    end
-
-    ##
-    # Returns the tool definitions available for the current streamed request.
-    # This prefers request-local tools attached to the stream and falls back
-    # to the current context defaults when present.
-    # @return [Array<LLM::Function, LLM::Tool>]
-    def tools
-      extra[:tools] || ctx&.params&.dig(:tools) || []
-    end
+    # @group Finders
 
     ##
     # Resolves a streamed tool call against the current request tools first,
     # then falls back to the global function registry.
     # @param [String] name
     # @return [LLM::Function, nil]
-    def find_tool(name)
-      tool = tools.find do |candidate|
-        candidate_name =
-          if candidate.respond_to?(:function)
-            candidate.function.name
-          else
-            candidate.name
-          end
-        candidate_name.to_s == name.to_s
+    def __find__(name)
+      tools = extra[:tools] || ctx&.params&.dig(:tools) || []
+      tool = tools.find do
+        candidate = _1.respond_to?(:function) ? _1.function.name : _1.name
+        candidate.to_s == name.to_s
       end
-      tool&.then { _1.respond_to?(:function) ? _1.function : _1 } ||
+      if tool
+        tool.respond_to?(:function) ? tool.function : tool
+      else
         LLM::Function.find_by_name(name)
+      end
     end
 
     # @endgroup

data/lib/llm/tool/param.rb

@@ -62,14 +62,7 @@ class LLM::Tool
       extend self
 
       def resolve(schema, type)
-        if LLM::Schema::Leaf === type
-          type
-        elsif Class === type && type.respond_to?(:object)
-          type.object
-        else
-          target = type.name.split("::").last.downcase
-          schema.public_send(target)
-        end
+        LLM::Schema::Utils.resolve(schema, type)
       end
 
       def setup(leaf, description, options)

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