llm.rb 4.11.1 → 4.13.0

data/lib/llm/context.rb

@@ -103,9 +103,9 @@ module LLM
     #   res = ctx.respond("What is the capital of France?")
     #   puts res.output_text
     def respond(prompt, params = {})
-      res_id = @messages.find(&:assistant?)&.response&.response_id
-      params = params.merge(previous_response_id: res_id, input: @messages.to_a).compact
       params = @params.merge(params)
+      res_id = params[:store] == false ? nil : @messages.find(&:assistant?)&.response&.response_id
+      params = params.merge(previous_response_id: res_id, input: @messages.to_a).compact
       res = @llm.responses.create(prompt, params)
       role = params[:role] || @llm.user_role
       @messages.concat LLM::Prompt === prompt ? prompt.to_a : [LLM::Message.new(role, prompt)]

data/lib/llm/function/task.rb

@@ -9,11 +9,17 @@ class LLM::Function
     # @return [Object]
     attr_reader :task
 
+    ##
+    # @return [LLM::Function, nil]
+    attr_reader :function
+
     ##
     # @param [Thread, Fiber, Async::Task] task
+    # @param [LLM::Function, nil] function
     # @return [LLM::Function::Task]
-    def initialize(task)
+    def initialize(task, function = nil)
       @task = task
+      @function = function
     end
 
     ##

data/lib/llm/function.rb

@@ -41,6 +41,13 @@ class LLM::Function
   prepend LLM::Function::Tracing
 
   Return = Struct.new(:id, :name, :value) do
+    ##
+    # Returns true when the return value represents an error.
+    # @return [Boolean]
+    def error?
+      Hash === value && value[:error] == true
+    end
+
     ##
     # Returns a Hash representation of {LLM::Function::Return}
     # @return [Hash]
@@ -186,7 +193,7 @@ class LLM::Function
     else
       raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :thread, :task, or :fiber"
     end
-    Task.new(task)
+    Task.new(task, self)
   ensure
     @called = true
   end
@@ -233,7 +240,11 @@ class LLM::Function
     when "LLM::Google"
       {name: @name, description: @description, parameters: @params}.compact
     when "LLM::Anthropic"
-      {name: @name, description: @description, input_schema: @params}.compact
+      {
+        name: @name,
+        description: @description,
+        input_schema: @params || {type: "object", properties: {}}
+      }.compact
     else
       format_openai(provider)
     end
@@ -246,7 +257,7 @@ class LLM::Function
     when "LLM::OpenAI::Responses"
       {
         type: "function", name: @name, description: @description,
-        parameters: @params.to_h.merge(additionalProperties: false), strict: true
+        parameters: (@params || {type: "object", properties: {}}).to_h.merge(additionalProperties: false), strict: false
       }.compact
     else
       {

data/lib/llm/mcp/error.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class LLM::MCP
-  class Error < LLM::Error
+  Error = Class.new(LLM::Error) do
     attr_reader :code, :data
 
     ##
@@ -27,5 +27,35 @@ class LLM::MCP
     end
   end
 
+  MismatchError = Class.new(Error) do
+    ##
+    # @return [Integer, String]
+    #  The request id the client was waiting for
+    attr_reader :expected_id
+
+    ##
+    # @return [Integer, String]
+    #  The response id received from the server
+    attr_reader :actual_id
+
+    ##
+    # @param [Integer, String] expected_id
+    #  The request id the client was waiting for
+    # @param [Integer, String] actual_id
+    #  The response id received from the server instead
+    def initialize(expected_id:, actual_id:)
+      @expected_id = expected_id
+      @actual_id = actual_id
+      super(message)
+    end
+
+    ##
+    # @return [String]
+    def message
+      "mismatched MCP response id #{actual_id.inspect} " \
+      "while waiting for #{expected_id.inspect}"
+    end
+  end
+
   TimeoutError = Class.new(Error)
 end

data/lib/llm/mcp/rpc.rb

@@ -53,11 +53,14 @@ class LLM::MCP
       poll(timeout:, ex: [IO::WaitReadable]) do
         loop do
           res = transport.read_nonblock
-          next unless res["id"] == id
-          if res["error"]
+          if res["id"] == id && res["error"]
             raise LLM::MCP::Error.from(response: res)
-          else
+          elsif res["id"] == id
             break res["result"]
+          elsif res["method"]
+            next
+          elsif res.key?("id")
+            raise LLM::MCP::MismatchError.new(expected_id: id, actual_id: res["id"])
           end
         end
       end
@@ -101,6 +104,8 @@ class LLM::MCP
     #  The exceptions to retry when raised
     # @yield
     #  The block to run
+    # @raise [LLM::MCP::MismatchError]
+    #  When an unrelated response id is received while waiting
     # @raise [LLM::MCP::TimeoutError]
     #  When the block takes longer than the timeout
     # @return [Object]

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

@@ -104,7 +104,7 @@ module LLM::MCP::Transport
     # Configures the transport to use a persistent HTTP connection pool
     # via the optional dependency [Net::HTTP::Persistent](https://github.com/drbrain/net-http-persistent)
     # @example
-    #   mcp = LLM.mcp(http: {url: "https://example.com/mcp"}).persist!
+    #   mcp = LLM.mcp(http: {url: "https://example.com/mcp"}).persistent
     #   # do something with 'mcp'
     # @return [LLM::MCP::Transport::HTTP]
     def persist!
@@ -119,6 +119,7 @@ module LLM::MCP::Transport
       end
       self
     end
+    alias_method :persistent, :persist!
 
     private
 

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

@@ -84,6 +84,7 @@ module LLM::MCP::Transport
     def persist!
       self
     end
+    alias_method :persistent, :persist!
 
     private
 

data/lib/llm/mcp.rb

@@ -104,13 +104,14 @@ class LLM::MCP
   # Configures an HTTP MCP transport to use a persistent connection pool
   # via the optional dependency [Net::HTTP::Persistent](https://github.com/drbrain/net-http-persistent)
   # @example
-  #   mcp = LLM.mcp(http: {url: "https://example.com/mcp"}).persist!
+  #   mcp = LLM.mcp(http: {url: "https://example.com/mcp"}).persistent
   #   # do something with 'mcp'
   # @return [LLM::MCP]
   def persist!
     transport.persist!
     self
   end
+  alias_method :persistent, :persist!
 
   ##
   # Returns the tools provided by the MCP process.
@@ -120,6 +121,34 @@ class LLM::MCP
     res["tools"].map { LLM::Tool.mcp(self, _1) }
   end
 
+  ##
+  # Returns the prompts provided by the MCP process.
+  # @return [Array<LLM::Object>]
+  def prompts
+    res = call(transport, "prompts/list")
+    LLM::Object.from(res["prompts"])
+  end
+
+  ##
+  # Returns a prompt by name.
+  # @param [String] name The prompt name
+  # @param [Hash<String, String>, nil] arguments The prompt arguments
+  # @return [LLM::Object]
+  def find_prompt(name:, arguments: nil)
+    params = {name:}
+    params[:arguments] = arguments if arguments
+    res = call(transport, "prompts/get", params)
+    res["messages"] = [*res["messages"]].map do |message|
+      LLM::Message.new(
+        message["role"],
+        adapt_content(message["content"]),
+        {original_content: message["content"]}
+      )
+    end
+    LLM::Object.from(res)
+  end
+  alias_method :get_prompt, :find_prompt
+
   ##
   # Calls a tool by name with the given arguments
   # @param [String] name The name of the tool to call
@@ -134,6 +163,19 @@ class LLM::MCP
 
   attr_reader :llm, :command, :transport, :timeout
 
+  def adapt_content(content)
+    case content
+    when String
+      content
+    when Hash
+      content["type"] == "text" ? content["text"].to_s : LLM::Object.from(content)
+    when Array
+      content.map { adapt_content(_1) }
+    else
+      content
+    end
+  end
+
   def adapt_tool_result(result)
     if result["structuredContent"]
       result["structuredContent"]

data/lib/llm/provider.rb

@@ -308,7 +308,7 @@ class LLM::Provider
   # This method configures a provider to use a persistent connection pool
   # via the optional dependency [Net::HTTP::Persistent](https://github.com/drbrain/net-http-persistent)
   # @example
-  #   llm = LLM.openai(key: ENV["KEY"]).persist!
+  #   llm = LLM.openai(key: ENV["KEY"]).persistent
   #   # do something with 'llm'
   # @return [LLM::Provider]
   def persist!
@@ -317,14 +317,13 @@ class LLM::Provider
       tap { @client = client }
     end
   end
+  alias_method :persistent, :persist!
 
   ##
   # @param [Object] stream
   # @return [Boolean]
   def streamable?(stream)
-    stream.respond_to?(:on_content) ||
-      stream.respond_to?(:on_reasoning_content) ||
-      stream.respond_to?(:<<)
+    LLM::Stream === stream || stream.respond_to?(:<<)
   end
 
   private

data/lib/llm/providers/anthropic/request_adapter/completion.rb

@@ -28,12 +28,19 @@ module LLM::Anthropic::RequestAdapter
 
     def adapt_message
       if message.tool_call?
-        {role: message.role, content: message.extra[:original_tool_calls]}
+        {role: message.role, content: adapt_tool_calls}
       else
         {role: message.role, content: adapt_content(content)}
       end
     end
 
+    def adapt_tool_calls
+      message.extra[:tool_calls].filter_map do |tool|
+        next unless tool[:id] && tool[:name]
+        {type: "tool_use", id: tool[:id], name: tool[:name], input: LLM::Anthropic.parse_tool_input(tool[:arguments])}
+      end
+    end
+
     ##
     # @param [String, URI] content
     #  The content to format

data/lib/llm/providers/anthropic/response_adapter/completion.rb

@@ -66,7 +66,8 @@ module LLM::Anthropic::ResponseAdapter
     private
 
     def adapt_choices
-      texts.map.with_index do |choice, index|
+      source = texts.empty? && tools.any? ? [{"text" => ""}] : texts
+      source.map.with_index do |choice, index|
         extra = {
           index:, response: self,
           tool_calls: adapt_tool_calls(tools), original_tool_calls: tools
@@ -77,7 +78,11 @@ module LLM::Anthropic::ResponseAdapter
 
     def adapt_tool_calls(tools)
       (tools || []).filter_map do |tool|
-        {id: tool.id, name: tool.name, arguments: tool.input}
+        {
+          id: tool.id,
+          name: tool.name,
+          arguments: LLM::Anthropic.parse_tool_input(tool.input)
+        }
       end
     end
 

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

@@ -105,7 +105,7 @@ class LLM::Anthropic
       registered = LLM::Function.find_by_name(tool["name"])
       fn = (registered || LLM::Function.new(tool["name"])).dup.tap do |fn|
         fn.id = tool["id"]
-        fn.arguments = tool["input"]
+        fn.arguments = LLM::Anthropic.parse_tool_input(tool["input"])
       end
       [fn, (registered ? nil : @stream.tool_not_found(fn))]
     end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class LLM::Anthropic
+  module Utils
+    ##
+    # Normalizes Anthropic tool input to a Hash suitable for kwargs.
+    # @param input [Hash, String, nil]
+    # @return [Hash]
+    def parse_tool_input(input)
+      case input
+      when Hash then input
+      when String
+        parsed = LLM.json.load(input)
+        Hash === parsed ? parsed : {}
+      when nil then {}
+      else
+        input.respond_to?(:to_h) ? input.to_h : {}
+      end
+    rescue *LLM.json.parser_error
+      {}
+    end
+  end
+end

data/lib/llm/providers/anthropic.rb

@@ -14,6 +14,7 @@ module 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/utils"
     require_relative "anthropic/error_handler"
     require_relative "anthropic/request_adapter"
     require_relative "anthropic/response_adapter"
@@ -21,6 +22,7 @@ module LLM
     require_relative "anthropic/models"
     require_relative "anthropic/files"
     include RequestAdapter
+    extend Utils
 
     HOST = "api.anthropic.com"
 
@@ -79,6 +81,15 @@ module LLM
       "assistant"
     end
 
+    ##
+    # Anthropic expects tool results to be sent as user messages
+    # containing `tool_result` content blocks rather than a distinct
+    # `tool` role.
+    # @return (see LLM::Provider#tool_role)
+    def tool_role
+      :user
+    end
+
     ##
     # Returns the default model for chat completions
     # @see https://docs.anthropic.com/en/docs/about-claude/models/all-models#model-comparison-table claude-sonnet-4-20250514

data/lib/llm/providers/openai/request_adapter/respond.rb

@@ -15,6 +15,8 @@ module LLM::OpenAI::RequestAdapter
       catch(:abort) do
         if Hash === message
           {role: message[:role], content: adapt_content(message[:content])}
+        elsif message.tool_call?
+          message.extra[:original_tool_calls]
         else
           adapt_message
         end
@@ -23,12 +25,12 @@ module LLM::OpenAI::RequestAdapter
 
     private
 
-    def adapt_content(content)
+    def adapt_content(content, role: message.role)
       case content
       when String
-        [{type: :input_text, text: content.to_s}]
+        [{type: text_content_type(role), text: content.to_s}]
       when LLM::Response then adapt_remote_file(content)
-      when LLM::Message then adapt_content(content.content)
+      when LLM::Message then adapt_content(content.content, role: content.role)
       when LLM::Object
         case content.kind
         when :image_url then [{type: :image_url, image_url: {url: content.value.to_s}}]
@@ -46,7 +48,7 @@ module LLM::OpenAI::RequestAdapter
       when Array
         adapt_array
       else
-        {role: message.role, content: adapt_content(content)}
+        {role: message.role, content: adapt_content(content, role: message.role)}
       end
     end
 
@@ -56,7 +58,7 @@ module LLM::OpenAI::RequestAdapter
       elsif returns.any?
         returns.map { {type: "function_call_output", call_id: _1.id, output: LLM.json.dump(_1.value)} }
       else
-        {role: message.role, content: content.flat_map { adapt_content(_1) }}
+        {role: message.role, content: content.flat_map { adapt_content(_1, role: message.role) }}
       end
     end
 
@@ -83,5 +85,9 @@ module LLM::OpenAI::RequestAdapter
     def message = @message
     def content = message.content
     def returns = content.grep(LLM::Function::Return)
+
+    def text_content_type(role)
+      role.to_s == "assistant" ? :output_text : :input_text
+    end
   end
 end

data/lib/llm/providers/openai/response_adapter/responds.rb

@@ -60,6 +60,13 @@ module LLM::OpenAI::ResponseAdapter
       body.model
     end
 
+    ##
+    # OpenAI's Responses API does not expose a system fingerprint.
+    # @return [nil]
+    def system_fingerprint
+      nil
+    end
+
     ##
     # Returns the aggregated text content from the response outputs.
     # @return [String]
@@ -88,10 +95,15 @@ module LLM::OpenAI::ResponseAdapter
     private
 
     def adapt_message
-      message = LLM::Message.new("assistant", +"", {response: self, tool_calls: [], reasoning_content: +""})
+      message = LLM::Message.new(
+        "assistant",
+        +"",
+        {response: self, tool_calls: [], original_tool_calls: [], reasoning_content: +""}
+      )
       output.each do |choice|
         if choice.type == "function_call"
           message.extra[:tool_calls] << adapt_tool(choice)
+          message.extra[:original_tool_calls] << choice
         elsif choice.type == "reasoning"
           (choice.summary || []).each do |summary|
             next unless summary["type"] == "summary_text"

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

@@ -43,11 +43,19 @@ class LLM::OpenAI
           @body[k] = v
         end
         @body["output"] ||= []
+      when "response.in_progress", "response.completed"
+        response = chunk["response"] || {}
+        response.each do |k, v|
+          next if k == "output" && @body["output"].is_a?(Array) && @body["output"].any?
+          @body[k] = v
+        end
+        @body["output"] ||= response["output"] || []
       when "response.output_item.added"
         output_index = chunk["output_index"]
         item = chunk["item"]
         @body["output"][output_index] = item
         @body["output"][output_index]["content"] ||= []
+        @body["output"][output_index]["summary"] ||= [] if item["type"] == "reasoning"
       when "response.content_part.added"
         output_index = chunk["output_index"]
         content_index = chunk["content_index"]
@@ -55,6 +63,25 @@ class LLM::OpenAI
         @body["output"][output_index] ||= {"content" => []}
         @body["output"][output_index]["content"] ||= []
         @body["output"][output_index]["content"][content_index] = part
+      when "response.reasoning_summary_text.delta"
+        output_item = @body["output"][chunk["output_index"]]
+        if output_item && output_item["type"] == "reasoning"
+          summary_index = chunk["summary_index"] || 0
+          output_item["summary"] ||= []
+          output_item["summary"][summary_index] ||= {"type" => "summary_text", "text" => +""}
+          output_item["summary"][summary_index]["text"] << chunk["delta"]
+          emit_reasoning_content(chunk["delta"])
+        end
+      when "response.reasoning_summary_text.done"
+        output_item = @body["output"][chunk["output_index"]]
+        if output_item && output_item["type"] == "reasoning"
+          summary_index = chunk["summary_index"] || 0
+          output_item["summary"] ||= []
+          output_item["summary"][summary_index] = {
+            "type" => "summary_text",
+            "text" => chunk["text"]
+          }
+        end
       when "response.output_text.delta"
         output_index = chunk["output_index"]
         content_index = chunk["content_index"]
@@ -102,6 +129,10 @@ class LLM::OpenAI
       end
     end
 
+    def emit_reasoning_content(value)
+      @stream.on_reasoning_content(value) if @stream.respond_to?(:on_reasoning_content)
+    end
+
     def emit_tool(index, tool)
       return unless @stream.respond_to?(:on_tool_call)
       return unless complete_tool?(tool)

data/lib/llm/stream/queue.rb

@@ -8,8 +8,10 @@ class LLM::Stream
   # returns an array of {LLM::Function::Return} values.
   class Queue
     ##
+    # @param [LLM::Stream] stream
     # @return [LLM::Stream::Queue]
-    def initialize
+    def initialize(stream)
+      @stream = stream
       @items = []
     end
 
@@ -39,13 +41,24 @@ class LLM::Stream
     # @return [Array<LLM::Function::Return>]
     def wait(strategy)
       returns, tasks = @items.shift(@items.length).partition { LLM::Function::Return === _1 }
-      returns.concat case strategy
+      results = case strategy
       when :thread then LLM::Function::ThreadGroup.new(tasks).wait
       when :task then LLM::Function::TaskGroup.new(tasks).wait
       when :fiber then LLM::Function::FiberGroup.new(tasks).wait
       else raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :thread, :task, or :fiber"
       end
+      returns.concat fire_hooks(tasks, results)
     end
     alias_method :value, :wait
+
+    private
+
+    def fire_hooks(tasks, results)
+      results.each_with_index do |ret, idx|
+        tool = tasks[idx]&.function
+        @stream.on_tool_return(tool, ret) if tool
+      end
+      results
+    end
   end
 end

data/lib/llm/stream.rb

@@ -5,20 +5,20 @@ module LLM
   # The {LLM::Stream LLM::Stream} class provides the callback interface for
   # streamed model output in llm.rb.
   #
-  # A stream object can be an instance of {LLM::Stream LLM::Stream}, a
-  # subclass that overrides the callbacks it needs, or any other object that
-  # implements some or all of the same interface. {#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.
+  # A stream object can be an instance of {LLM::Stream LLM::Stream} or a
+  # 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.
   #
   # @note The `on_*` callbacks run inline with the streaming parser. They
   #   therefore block streaming progress and should generally return as
   #   quickly as possible.
   #
-  # The most common callback is {#on_content}, which also maps to {#<<} for
-  # compatibility with `StringIO`-style objects. Providers may also call
-  # {#on_reasoning_content} and {#on_tool_call} when that data is available.
+  # The most common callback is {#on_content}, which also maps to {#<<}.
+  # Providers may also call {#on_reasoning_content} and {#on_tool_call} when
+  # that data is available.
   class Stream
     require_relative "stream/queue"
 
@@ -26,7 +26,7 @@ module LLM
     # Returns a lazily-initialized queue for tool results or spawned work.
     # @return [LLM::Stream::Queue]
     def queue
-      @queue ||= Queue.new
+      @queue ||= Queue.new(self)
     end
 
     ##
@@ -79,6 +79,20 @@ module LLM
       nil
     end
 
+    ##
+    # Called when queued streamed tool work returns.
+    # @note This callback runs when {#wait} resolves work that was queued from
+    #   {#on_tool_call}, such as values returned by `tool.spawn(:thread)`,
+    #   `tool.spawn(:fiber)`, or `tool.spawn(:task)`.
+    # @param [LLM::Function] tool
+    #  The tool that returned.
+    # @param [LLM::Function::Return] ret
+    #  The completed tool return.
+    # @return [nil]
+    def on_tool_return(tool, ret)
+      nil
+    end
+
     # @endgroup
 
     # @group Error handlers

data/lib/llm/version.rb

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