ruby_llm 2.1.0 → 2.2.0

data/lib/ruby_llm/protocols/responses/chat.rb

@@ -5,10 +5,27 @@ module RubyLLM
     class Responses
       # Chat methods of the OpenAI Responses API
       module Chat
+        def native_tool_namespace?(_namespace) = true
+
+        # Tool search loads a deferred function declared outside any
+        # namespace as a namespace named after the function, and the model
+        # calls it under that namespace.
+        def searched_tool_namespace?(call, tools) # :nodoc:
+          function = tools[call.name.to_sym]
+          return false if function.nil? || function.namespace || call.namespace != call.name.to_s
+
+          tools.each_value.none? { |tool| tool.namespace == call.namespace }
+        end
+
         def completion_url
           'responses'
         end
 
+        def wire_parameters
+          super.merge('reasoning' => :thinking, 'reasoning.effort' => :thinking,
+                      'max_output_tokens' => :max_output_tokens)
+        end
+
         OPENAI_INLINE_FILE_LIMIT = 50 * 1024 * 1024
         PROMPT_CACHE_OPTIONS = %i[key ttl mode retention].freeze
 
@@ -23,8 +40,8 @@ module RubyLLM
           # to ride back in the response. xAI only encrypts it when asked.
           payload = {
             model: model.id,
-            input: format_input(messages, caching:),
-            instructions: format_instructions(messages, caching:),
+            input: render_input(messages, caching:),
+            instructions: render_instructions(messages, caching:),
             stream: stream,
             store: false,
             include: ['reasoning.encrypted_content']
@@ -34,8 +51,12 @@ module RubyLLM
           payload[:max_output_tokens] = max_output_tokens unless max_output_tokens.nil?
 
           if tools.any?
-            payload[:tools] = tools.map { |_, tool| tool_for(tool) }
-            payload[:tool_choice] = build_tool_choice(tool_prefs[:choice]) unless tool_prefs[:choice].nil?
+            payload[:tools] = render_tools(tools)
+            payload[:input] = namespace_searched_calls(payload[:input], tools)
+            unless tool_prefs[:choice].nil?
+              Protocol::ToolNamespaces.validate_tool_choice(tools, tool_prefs[:choice])
+              payload[:tool_choice] = build_tool_choice(tool_prefs[:choice])
+            end
             payload[:parallel_tool_calls] = tool_prefs[:calls] == :many unless tool_prefs[:calls].nil?
           end
 
@@ -50,7 +71,8 @@ module RubyLLM
         end
 
         def parse_completion_body(data, raw:)
-          raise Error.new(data.dig('error', 'message'), response: raw) if data.dig('error', 'message')
+          raise_failed_response(data) if data.dig('error', 'message')
+          raise Error.new('The provider reported a failed response', response: raw) if data['status'] == 'failed'
 
           output = data['output'] || []
           content = parse_output_text(output)
@@ -69,14 +91,19 @@ module RubyLLM
             tool_calls: parse_pending_tool_calls(output, response: raw, finish_reason: finish_reason),
             server_tool_calls: server_tool_calls,
             raw_content: keep_raw_output?(output, server_tool_calls) ? output : nil,
+            phase: parse_phase(output),
             model: data['model'],
             raw: raw,
             finish_reason: finish_reason,
-            **parse_usage(data['usage'] || {}),
-            server_tool_use: parse_server_tool_use(data)
+            content_filters: ChatCompletions::ContentFilters.parse_content_filters(data),
+            **parse_completion_usage(data)
           )
         end
 
+        def parse_completion_usage(data)
+          parse_usage(data['usage'] || {}).merge(server_tool_use: parse_server_tool_use(data))
+        end
+
         # context_management is an OpenAI parameter that only OpenAI's own
         # endpoints serve; the other services on this wire format reject it.
         COMPACTION_PROVIDERS = %w[openai azure].freeze
@@ -109,8 +136,35 @@ module RubyLLM
 
         PORTABLE_OUTPUT_ITEM_TYPES = (%w[message function_call] + TOOL_SEARCH_ITEM_TYPES).freeze
 
+        # A message carries one thinking signature and one phase, so output
+        # with more reasoning items or phases than that only replays whole
+        # from its raw items.
         def keep_raw_output?(output, server_tool_calls)
-          server_tool_calls.any? || output.any? { |item| namespaced_call?(item) }
+          server_tool_calls.any? || output.any? { |item| namespaced_call?(item) } ||
+            output.count { |item| item['type'] == 'reasoning' } > 1 || message_phases(output).uniq.size > 1
+        end
+
+        def parse_phase(output)
+          message_phases(output).compact.last
+        end
+
+        # Structured output lives in the final_answer items, and a turn is
+        # read whole only when none of its items carries a phase, as in
+        # OpenAI's SDKs. Commentary, unphased text beside a final answer,
+        # and phases OpenAI adds later are not the answer. A turn whose
+        # items carry different phases keeps them in raw_content; otherwise
+        # its one phase tells.
+        def parse_answer_text(message)
+          output = message.raw_content
+          if output.is_a?(Array) && message_phases(output).any?
+            parse_output_text(output.select { |item| item['phase'] == 'final_answer' }) || ''
+          elsif !message.phase.nil? && message.phase != 'final_answer'
+            ''
+          end
+        end
+
+        def message_phases(output)
+          output.select { |item| item['type'] == 'message' }.map { |item| item['phase'] }
         end
 
         def namespaced_call?(item)
@@ -143,12 +197,26 @@ module RubyLLM
         end
 
         # Result payloads differ by item type; compaction items carry an
-        # opaque encrypted_content instead of a readable result.
+        # opaque encrypted_content instead of a readable result, and a web
+        # search keeps the sources it found in its action.
         SERVER_TOOL_RESULT_KEYS = %w[result results outputs output encrypted_content].freeze
 
         def server_tool_result(item)
           key = SERVER_TOOL_RESULT_KEYS.find { |candidate| item[candidate] }
-          item[key] if key
+          return item[key] if key
+
+          action = item['action']
+          action['sources'] if action.is_a?(Hash)
+        end
+
+        # Only what a search returned. The address in an open_page or
+        # find_in_page action is the model's own choice and need not be a
+        # result, so text the model read could steer it there.
+        def parse_web_sources(message)
+          searches = message.server_tool_calls.select { |call| call.type == 'web_search_call' }
+          searches.flat_map { |call| Array(call.raw.dig('action', 'sources')) }.filter_map do |source|
+            WebSource.new(url: source['url'], title: source['title']) if source['url']
+          end
         end
 
         def parse_citations(data, output, content)
@@ -158,13 +226,15 @@ module RubyLLM
 
         def parse_output_citations(output, content)
           offset = 0
-          output.select { |item| item['type'] == 'message' }.flat_map do |message|
+          text_messages(output).each_with_index.flat_map do |message, index|
+            offset += MESSAGE_SEPARATOR.length if index.positive?
             Array(message['content']).flat_map do |part|
               key = MESSAGE_TEXT_KEYS[part['type']]
               next [] unless key
 
-              citations = offset_citations(parse_annotations(part['annotations'], nil), offset, content)
-              offset += part[key].to_s.length
+              text, markers = CitationMarkers.strip(part[key].to_s)
+              citations = offset_citations(parse_annotations(part['annotations'], nil), offset, content, markers)
+              offset += text.length
               citations
             end
           end
@@ -195,10 +265,10 @@ module RubyLLM
           )
         end
 
-        def offset_citations(citations, offset, content)
+        def offset_citations(citations, offset, content, markers = CitationMarkers.new)
           citations.map do |citation|
-            start_index = citation.start_index && (citation.start_index + offset)
-            end_index = citation.end_index && (citation.end_index + offset)
+            start_index = citation.start_index && (markers.shift(citation.start_index) + offset)
+            end_index = citation.end_index && (markers.shift(citation.end_index) + offset)
 
             Citation.new(citation.to_h.merge(
                            start_index: start_index,
@@ -229,10 +299,14 @@ module RubyLLM
 
           {}.tap do |cache_options|
             cache_options[:mode] = options[:mode] if options[:mode]
-            cache_options[:ttl] = ttl if ttl
+            cache_options[:ttl] = render_cache_lifetime(ttl) if ttl
           end
         end
 
+        def render_cache_lifetime(ttl)
+          Protocol::CacheLifetime.render(ttl)
+        end
+
         def retention_ttl(retention)
           return unless retention
 
@@ -252,6 +326,8 @@ module RubyLLM
                 "Responses prompt caching accepts :key, :ttl, and :mode, got #{format_cache_option_keys(unsupported)}"
         end
 
+        def cache_option_names = PROMPT_CACHE_OPTIONS
+
         def format_cache_option_keys(keys)
           keys.map { |key| ":#{key}" }.join(', ')
         end
@@ -291,31 +367,31 @@ module RubyLLM
         # The +instructions+ parameter is a plain string and cannot carry a
         # breakpoint marker or a file. When any system message needs one, every
         # system message rides along as an input item, so their order holds.
-        def format_instructions(messages, caching: nil)
+        def render_instructions(messages, caching: nil)
           system = messages.select { |msg| msg.role == :system }
           return if system.empty? || system_input_items?(system, caching:)
 
           system.map { |msg| msg.content.to_s }.join("\n\n")
         end
 
-        def format_input(messages, caching: nil)
+        def render_input(messages, caching: nil)
           system, conversation = messages.partition { |msg| msg.role == :system }
           system_items = if system_input_items?(system, caching:)
-                           system.flat_map { |msg| [format_item(msg, caching:)].flatten(1) }
+                           system.flat_map { |msg| [render_item(msg, caching:)].flatten(1) }
                          else
                            []
                          end
 
-          system_items + format_conversation(conversation, caching:)
+          system_items + render_conversation(conversation, caching:)
         end
 
-        def format_conversation(messages, caching: nil)
+        def render_conversation(messages, caching: nil)
           messages.each_with_object([]) do |message, input|
             raw = message.raw_content
             if raw.is_a?(Hash) && raw['object'] == 'response.compaction'
               input.replace(raw.fetch('output'))
             else
-              input.concat([format_item(message, caching:)].flatten(1))
+              input.concat([render_item(message, caching:)].flatten(1))
             end
           end
         end
@@ -328,17 +404,17 @@ module RubyLLM
           msg.role == :system && ((caching != false && msg.cache_until_here?) || msg.attachments.any?)
         end
 
-        def format_item(msg, caching: nil)
+        def render_item(msg, caching: nil)
           case msg.role
           when :system
-            item = { role: 'system', content: format_content(msg.content, msg.attachments) }
+            item = { role: 'system', content: render_content(msg.content, msg.attachments) }
             caching != false && msg.cache_until_here? ? inject_cache_breakpoint(item) : item
           when :tool
-            format_tool_items(msg)
+            render_tool_items(msg)
           when :assistant
-            format_assistant_items(msg)
+            render_assistant_items(msg)
           else
-            item = { role: 'user', content: format_content(msg.content, msg.attachments) }
+            item = { role: 'user', content: render_content(msg.content, msg.attachments) }
             caching != false && msg.cache_until_here? ? inject_cache_breakpoint(item) : item
           end
         end
@@ -360,37 +436,44 @@ module RubyLLM
 
         # Function call outputs are text-only on the wire, so tool attachments
         # ride a user item spliced in right after the result.
-        def format_tool_items(msg)
+        def render_tool_items(msg)
           return msg.raw_content if msg.raw_content
 
           items = [{
             type: 'function_call_output',
-            call_id: msg.tool_call_id,
-            output: format_content(msg.content)
+            call_id: msg.provider_call_id,
+            output: render_content(msg.content)
           }]
 
           if msg.attachments.any?
-            parts = [{ type: 'input_text', text: "Attachments from tool call #{msg.tool_call_id}:" }]
-            parts.concat(format_content(nil, msg.attachments))
-            items << { role: 'user', content: parts }
+            items << render_attachment_item("Attachments from tool call #{msg.provider_call_id}:", msg.attachments)
           end
 
           items
         end
 
-        def format_assistant_items(msg)
+        def render_attachment_item(label, attachments)
+          parts = [{ type: 'input_text', text: label }]
+          parts.concat(render_content(nil, attachments))
+          { role: 'user', content: parts }
+        end
+
+        # Assistant output is text-only on the wire, so the attachments of a
+        # replayed assistant turn ride a user item spliced in after it.
+        def render_assistant_items(msg)
           # Turns that used server tools replay their output items verbatim,
           # reasoning and tool results included, as stateless chaining expects.
-          return msg.raw_content if msg.raw_content
+          return replayed_output(msg) if msg.raw_content
 
           items = []
-          items << format_reasoning_item(msg.thinking) if own_signature(msg)
-          items << { role: 'assistant', content: format_output_content(msg) } unless empty_content?(msg.content)
-          items.concat(format_function_call_items(msg.tool_calls)) if msg.tool_call?
+          items << render_reasoning_item(msg.thinking) if own_signature(msg)
+          items << render_output_item(msg) unless empty_content?(msg.content)
+          items.concat(render_function_call_items(msg.tool_calls)) if msg.tool_call?
+          items << render_attachment_item('Attachments from the assistant:', msg.attachments) if msg.attachments.any?
           items
         end
 
-        def format_reasoning_item(thinking)
+        def render_reasoning_item(thinking)
           {
             type: 'reasoning',
             summary: thinking.text ? [{ type: 'summary_text', text: thinking.text }] : [],
@@ -398,19 +481,25 @@ module RubyLLM
           }
         end
 
-        def format_function_call_items(tool_calls)
-          tool_calls.map do |_, tc|
+        def replayed_output(msg)
+          Protocol::ReplayedArguments.blank(msg.raw_content, msg,
+                                            id: %w[call_id id], arguments: 'arguments', empty: '{}')
+        end
+
+        def render_function_call_items(tool_calls)
+          tool_calls.map do |tc|
             {
               type: 'function_call',
-              call_id: tc.id,
+              call_id: tc.provider_call_id,
               name: tc.name,
+              namespace: tc.namespace,
               arguments: JSON.generate(tc.arguments)
-            }
+            }.compact
           end
         end
 
-        def format_output_content(msg)
-          [{ type: 'output_text', text: msg.content }]
+        def render_output_item(msg)
+          { role: 'assistant', content: [{ type: 'output_text', text: msg.content }], phase: msg.phase }.compact
         end
 
         def empty_content?(content)
@@ -418,53 +507,54 @@ module RubyLLM
         end
 
         MESSAGE_TEXT_KEYS = { 'output_text' => 'text', 'refusal' => 'refusal' }.freeze
+        MESSAGE_SEPARATOR = "\n\n"
 
         def parse_output_text(output)
-          texts = output.select { |item| item['type'] == 'message' }.flat_map do |message|
+          texts = text_messages(output).map do |message|
             Array(message['content']).filter_map do |part|
               key = MESSAGE_TEXT_KEYS[part['type']]
-              part[key] if key
-            end
+              CitationMarkers.strip(part[key]).first if key && part[key]
+            end.join
           end
 
-          texts.empty? ? nil : texts.join
+          texts.empty? ? nil : texts.join(MESSAGE_SEPARATOR)
+        end
+
+        def text_messages(output)
+          output.select do |item|
+            item['type'] == 'message' && Array(item['content']).any? { |part| MESSAGE_TEXT_KEYS.key?(part['type']) }
+          end
         end
 
         FINISH_REASONS = {
-          'completed' => :stop, 'max_output_tokens' => :max_tokens, 'content_filter' => :content_filter
+          'completed' => :stop, 'function_call' => :tool_calls,
+          'max_output_tokens' => :max_tokens, 'content_filter' => :content_filter
         }.freeze
 
         def finish_reasons = FINISH_REASONS
 
         def parse_finish_reason(data)
-          reason = data.dig('incomplete_details', 'reason') || (data['status'] if data['status'] == 'completed')
-          normalize_finish_reason(reason)
+          normalize_finish_reason(data.dig('incomplete_details', 'reason') || parse_completed_reason(data))
         end
 
-        def parse_function_calls(output, response: nil, finish_reason: nil)
-          calls = output.select { |item| item['type'] == 'function_call' }
-          return nil if calls.empty?
+        def parse_completed_reason(data)
+          return unless data['status'] == 'completed'
 
-          calls.to_h do |call|
-            arguments = call['arguments']
-
-            [
-              call['call_id'],
-              ToolCall.new(
-                id: call['call_id'],
-                name: call['name'],
-                arguments: parse_function_call_arguments(arguments, response: response, finish_reason: finish_reason)
-              )
-            ]
-          end
+          Array(data['output']).any? { |item| item['type'] == 'function_call' } ? 'function_call' : 'completed'
         end
 
-        def parse_function_call_arguments(arguments, response: nil, finish_reason: nil)
-          return {} if arguments.nil? || arguments.empty?
+        def parse_function_calls(output, response: nil, finish_reason: nil)
+          calls = output.select { |item| item['type'] == 'function_call' }
+          return nil if calls.empty?
 
-          JSON.parse(arguments)
-        rescue JSON::ParserError => e
-          raise ToolCallParseError.new(response: response, finish_reason: finish_reason), cause: e
+          ToolCall.index(calls.map do |call|
+            ToolCall.new(
+              provider_call_id: call['call_id'],
+              name: call['name'],
+              namespace: call['namespace'],
+              **ToolCall.parse_arguments(call['arguments'], response:, finish_reason:)
+            )
+          end, by: :provider_call_id)
         end
 
         def parse_reasoning_summary(output)
@@ -472,14 +562,14 @@ module RubyLLM
             Array(item['summary']).filter_map { |part| part['text'] }
           end
 
-          texts.empty? ? nil : texts.join("\n")
+          texts.empty? ? nil : texts.join("\n\n")
         end
 
         def parse_reasoning_signature(output)
           output.find { |item| item['type'] == 'reasoning' }&.dig('encrypted_content')
         end
 
-        def supports_provider_file_references?
+        def provider_file_references?
           true
         end
 

data/lib/ruby_llm/protocols/responses/citation_markers.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    class Responses
+      # Removes the citation markers OpenAI's models write into their text:
+      # U+E200, then "cite" and the sources and line locators it cites, each
+      # after a U+E202, then U+E201. Only OpenAI's own tools turn them into annotations, so
+      # a model that writes them without those tools leaves them in the
+      # answer. Model output is untrusted: each character is read once, and
+      # an unclosed marker holds back at most MAX_LENGTH characters. A space
+      # before a removed marker goes too when punctuation, a space, or the end
+      # of the text follows. Only a marker holds a space past the end of a
+      # stream chunk, so text keeps its order across content parts. #shift
+      # maps an index into the text as sent onto the text without markers.
+      class CitationMarkers # :nodoc:
+        OPEN = "\u{E200}"
+        CLOSE = "\u{E201}"
+        SEPARATOR = "\u{E202}"
+        MARKS = [OPEN, CLOSE, SEPARATOR].freeze
+        CITE = 'cite'
+        REFERENCE = /\A[\w-]*\z/
+        SPACE = ' '
+        BOUNDARY = /[[:space:].,;:!?)\]}]/
+        MAX_LENGTH = 256
+
+        def self.strip(text)
+          markers = new
+          ["#{markers.feed(text)}#{markers.finish}", markers]
+        end
+
+        def initialize
+          @held = nil
+          @seen = 0
+          @removed = []
+          @space_at = nil
+          @after_marker = false
+        end
+
+        def feed(text)
+          return text if text.nil? || text.empty?
+
+          output = +''
+          text.each_char { |char| read(char, output) }
+          settle_space(output, boundary: false) unless @held || @after_marker
+          output.empty? ? nil : output
+        end
+
+        def finish
+          output = +''
+          held = take_held
+          if held && !citation_prefix?(held)
+            release(held, output)
+          else
+            drop(held) if held
+            settle_space(output, boundary: true)
+          end
+          output.empty? ? nil : output
+        end
+
+        def shift(index)
+          return index if index.nil?
+
+          index - @removed.sum { |position, length| position < index ? length : 0 }
+        end
+
+        private
+
+        def read(char, output)
+          if @held
+            hold(char, output)
+          elsif char == OPEN
+            open_marker
+          elsif MARKS.include?(char)
+            @removed << [@seen, 1]
+          else
+            write(char, output)
+          end
+          @seen += 1
+        end
+
+        def write(char, output)
+          settle_space(output, boundary: char.match?(BOUNDARY))
+          if char == SPACE
+            @space_at = @seen
+          else
+            output << char
+          end
+        end
+
+        def settle_space(output, boundary:)
+          if @space_at && @after_marker && boundary
+            @removed << [@space_at, 1]
+          elsif @space_at
+            output << SPACE
+          end
+          @space_at = nil
+          @after_marker = false
+        end
+
+        def open_marker
+          @held = +OPEN
+          @held_at = @seen
+        end
+
+        def hold(char, output)
+          if char == OPEN
+            release(@held, output)
+            open_marker
+          else
+            @held << char
+            return close_marker(output) if char == CLOSE
+
+            release(take_held, output) if @held.length > MAX_LENGTH
+          end
+        end
+
+        def close_marker(output)
+          held = take_held
+          complete_marker?(held.delete_suffix(CLOSE)) ? drop(held) : release(held, output)
+        end
+
+        def citation_prefix?(held)
+          CITE.start_with?(held.delete_prefix(OPEN)) || marker?(held)
+        end
+
+        def complete_marker?(held)
+          marker?(held) && held.split(SEPARATOR, -1).drop(1).none?(&:empty?)
+        end
+
+        def marker?(held)
+          word, *references = held.delete_prefix(OPEN).split(SEPARATOR, -1)
+          return false unless word.to_s.end_with?(CITE) && word.each_char.all? { |char| alphanumeric?(char) }
+
+          references.all? { |reference| reference.match?(REFERENCE) }
+        end
+
+        def alphanumeric?(char)
+          char.match?(/[[:alnum:]]/)
+        end
+
+        def take_held
+          held = @held
+          @held = nil
+          held
+        end
+
+        def drop(held)
+          @removed << [@held_at, held.length]
+          @after_marker = true
+          nil
+        end
+
+        def release(held, output)
+          settle_space(output, boundary: false)
+          held.each_char.with_index do |char, index|
+            if MARKS.include?(char)
+              @removed << [@held_at + index, 1]
+            else
+              output << char
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/protocols/responses/compaction.rb

@@ -10,8 +10,8 @@ module RubyLLM
         end
 
         def render_compaction_payload(messages)
-          { model: model.id, input: format_input(messages, caching: false),
-            instructions: format_instructions(messages, caching: false) }.compact
+          { model: model.id, input: render_input(messages, caching: false),
+            instructions: render_instructions(messages, caching: false) }.compact
         end
 
         def parse_compaction_response(response)