llm.rb 10.0.0 → 11.1.0

data/lib/llm/function.rb

@@ -109,8 +109,16 @@ class LLM::Function
 
   ##
   # Returns function arguments
-  # @return [Array, nil]
-  attr_accessor :arguments
+  # @return [Hash, Array, LLM::Object, nil]
+  attr_reader :arguments
+
+  ##
+  # Sets function arguments, wrapping them in an LLM::Object
+  # @param [Hash, LLM::Object] other
+  # @return [void]
+  def arguments=(other)
+    @arguments = LLM::Object.from(other)
+  end
 
   ##
   # Returns a tracer, or nil
@@ -182,7 +190,7 @@ class LLM::Function
   def define(klass = nil, &b)
     @runner = klass || b
   end
-  alias_method :register, :define
+  alias_method :def, :define
 
   ##
   # Call the function
@@ -373,10 +381,10 @@ class LLM::Function
   #   Returns a Return object with either the function result or error information.
   def call_function
     runner = self.runner
-    kwargs = Hash === arguments ? arguments.transform_keys(&:to_sym) : arguments
+    kwargs = arguments.respond_to?(:to_h) ? arguments.to_h.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})
+    Return.new(id, name, {error: true, type: ex.class.name, message: ex.message})
   end
 
   def call!

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

@@ -17,6 +17,7 @@ class LLM::Object
       case obj
       when self then from(obj.to_h)
       when Array then obj.map { |v| from(v) }
+      when String then obj
       else
         visited = {}
         obj.each { visited[_1] = visit(_2) }

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

@@ -184,6 +184,15 @@ class LLM::Object < BasicObject
     @h.slice(*args)
   end
 
+  ##
+  # @param [Hash, #to_h] other
+  # @return [Boolean]
+  def ==(other)
+    return false unless other.respond_to?(:to_h)
+    to_h == other.to_h || to_hash == other.to_h
+  end
+  alias_method :eql?, :==
+
   private
 
   def method_missing(m, *args, &b)

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

@@ -20,14 +20,16 @@
 #
 # @example Ruby-style
 #  class Address < LLM::Schema
-#    property :street, String, "Street address", required: true
+#    property :street, String, "Street address"
+#    required %i[street]
 #  end
 #
 #  class Person < LLM::Schema
-#    property :name, String, "Person's name", required: true
-#    property :age, Integer, "Person's age", required: true
-#    property :hobbies, Array[String], "Person's hobbies", required: true
-#    property :address, Address, "Person's address", required: true
+#    property :name, String, "Person's name"
+#    property :age, Integer, "Person's age"
+#    property :hobbies, Array[String], "Person's hobbies"
+#    property :address, Address, "Person's address"
+#    required %i[name age hobbies address]
 #  end
 class LLM::Schema
   require_relative "schema/version"
@@ -74,6 +76,10 @@ class LLM::Schema
       end
       schema.array(item)
     end
+
+    def fetch(properties, name)
+      properties[name] || properties.fetch(name.to_s)
+    end
   end
 
   ##
@@ -103,6 +109,18 @@ class LLM::Schema
     end
   end
 
+  ##
+  # Mark existing properties as required.
+  # @param names [Array<Symbol,String>]
+  # @return [LLM::Schema::Object]
+  def self.required(names)
+    lock do
+      object.tap do |schema|
+        [*names].each { Utils.fetch(schema.properties, _1).required }
+      end
+    end
+  end
+
   ##
   # @api private
   # @return [LLM::Schema]

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

@@ -56,6 +56,7 @@ module LLM
       @instructions = ""
       @frontmatter = LLM::Object.from({})
       @tools = []
+      @inherit_tools = false
     end
 
     ##
@@ -74,18 +75,8 @@ module LLM
     # @param [LLM::Context] ctx
     # @return [Hash]
     def call(ctx)
-      instructions, tools, tracer = self.instructions, self.tools, ctx.llm.tracer
-      params = ctx.params.merge(mode: ctx.mode).reject { [:tools, :schema].include?(_1) }
-      concurrency = params[:stream].extra[:concurrency] if LLM::Stream === params[:stream]
-      params[:concurrency] = concurrency if concurrency
-      agent = Class.new(LLM::Agent) do
-        instructions(instructions)
-        tools(*tools)
-        tracer(tracer)
-      end.new(ctx.llm, params)
-      agent.messages.concat(messages_for(ctx))
-      res = agent.talk("Solve the user's query.")
-      {content: res.content}
+      content = agent(ctx).talk("Solve the user's query.").content
+      {content:}
     end
 
     ##
@@ -96,9 +87,10 @@ module LLM
     def to_tool(ctx)
       skill = self
       Class.new(LLM::Tool) do
+        attr_accessor :tracer
+
         name skill.name
         description skill.description
-        attr_accessor :tracer
 
         define_singleton_method(:skill?) do
           true
@@ -110,6 +102,13 @@ module LLM
       end
     end
 
+    ##
+    # Returns true when a skill should inherit tools from its parent
+    # @return [Boolean]
+    def inherit_tools?
+      @inherit_tools
+    end
+
     private
 
     def messages_for(ctx)
@@ -132,8 +131,39 @@ module LLM
       @frontmatter = LLM::Object.from(YAML.safe_load(match[1]) || {})
       @name = @frontmatter.name || @name
       @description = @frontmatter.description || @description
-      @tools = [*@frontmatter.tools].map { LLM::Tool.find_by_name!(_1) }
       @instructions = match[2]
+      @inherit_tools, @tools = parse_tools(@frontmatter.tools)
+    end
+
+    def parse_tools(tools)
+      case tools
+      when String
+        tools == "inherit" ? [true, []] : raise_invalid_error!(tools)
+      when Array
+        [false, [*@frontmatter.tools].map { LLM::Tool.find_by_name!(_1) }]
+      when NilClass
+        [false, []]
+      else
+        raise_invalid_error!(tools)
+      end
+    end
+
+    def raise_invalid_error!(tools)
+      raise LLM::Error, "invalid value for tools key: '#{tools}'"
+    end
+
+    def agent(ctx)
+      instructions, tools, tracer, inherit_tools = self.instructions, self.tools, ctx.llm.tracer, inherit_tools?
+      params = ctx.params.merge(mode: ctx.mode).reject { [:tools, :schema].include?(_1) }
+      concurrency = params[:stream].extra[:concurrency] if LLM::Stream === params[:stream]
+      params[:concurrency] = concurrency if concurrency
+      agent = Class.new(LLM::Agent) do
+        instructions(instructions)
+        tools(inherit_tools ? ctx.params[:tools] : tools)
+        tracer(tracer)
+      end.new(ctx.llm, params)
+      agent.messages.concat(messages_for(ctx))
+      agent
     end
   end
 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/telemetry.rb

@@ -223,7 +223,9 @@ module LLM
       require "opentelemetry/sdk" unless defined?(OpenTelemetry)
       @exporter ||= OpenTelemetry::SDK::Trace::Export::InMemorySpanExporter.new
       processor = OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(@exporter)
-      @tracer_provider = OpenTelemetry::SDK::Trace::TracerProvider.new
+      @tracer_provider = OpenTelemetry::SDK::Trace::TracerProvider.new(
+        sampler: OpenTelemetry::SDK::Trace::Samplers::ALWAYS_ON
+      )
       @tracer_provider.add_span_processor(processor)
       @tracer = @tracer_provider.tracer("llm.rb", LLM::VERSION)
     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