ruby_llm 2.0.0 → 2.1.0

data/lib/ruby_llm/protocol/request_shapes/analysis.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class Protocol
+    module RequestShapes
+      # Finds what a provider would refuse in the turns a protocol read: parts
+      # with no data, empty turns, tool rounds whose calls and results do not
+      # pair up, and results that answer no call, plus the rules a protocol
+      # opts into. +pairing+ is how the provider matches results to calls:
+      # +:id+, or +:position+, which compares tool names in order. The rules
+      # are +:signed_steps+, where the first call of each step in the current
+      # turn needs a signature; +:signed_thinking+, where every thinking part
+      # does; and +:alternating_roles+, where user and model turns alternate,
+      # starting with the user.
+      class Analysis # :nodoc: all
+        KEPT_FIRST_TURNS = 10
+        KEPT_LAST_TURNS = 50
+
+        Round = Struct.new(:turn, :calls, :results)
+
+        def initialize(turns, pairing:, rules:)
+          @turns = turns
+          @pairing = pairing
+          @rules = rules
+          name_results
+        end
+
+        def kept_turns
+          return @turns if @turns.size <= KEPT_FIRST_TURNS + KEPT_LAST_TURNS
+
+          @turns.first(KEPT_FIRST_TURNS) + @turns.last(KEPT_LAST_TURNS)
+        end
+
+        # The request is the model call after every round of the current
+        # turn, which starts after the last user turn.
+        def step
+          rounds.count { |round| round.turn.index > last_user_turn.index } + 1 if last_user_turn
+        end
+
+        def tool_rounds
+          kept = kept_turns.to_set(&:index)
+          rounds.select { |round| kept.include?(round.turn.index) }.map do |round|
+            RequestShape::ToolRound.new(turn: round.turn.index, calls: round.calls.size,
+                                        results: round.results.size, paired: paired?(round))
+          end
+        end
+
+        def problems
+          found = [*parts_without_data, *empty_turns, *unpaired_rounds, *unmatched_results, *unsigned_calls,
+                   *unsigned_thinking, *roles_out_of_order]
+          found.each_with_index.sort_by { |problem, order| [problem.turn, problem.part || -1, order] }.map(&:first)
+        end
+
+        private
+
+        def located_parts(turns = @turns)
+          turns.flat_map { |turn| turn.parts.each_with_index.map { |part, position| [turn, position, part] } }
+        end
+
+        def last_user_turn
+          @turns.reverse.find { |turn| turn.speaker == :user }
+        end
+
+        def name_results
+          return unless @pairing == :id
+
+          names = {}
+          located_parts.each do |_, _, part|
+            names[part.call_id] = part.name if part.call? && part.call_id
+            part.name ||= names[part.result_id] if part.result?
+          end
+        end
+
+        # Consecutive model turns make one round, answered by the results in
+        # the turns that follow them up to the next model turn.
+        def rounds
+          @rounds ||= runs(@turns).push([]).each_cons(2).filter_map { |run, answers| round(run, answers) }
+        end
+
+        def round(run, answers)
+          calls = run.flat_map(&:parts).select(&:call?)
+          Round.new(run.first, calls, answers.flat_map(&:parts).select(&:result?)) if run.first.model? && calls.any?
+        end
+
+        def runs(turns)
+          turns.slice_when { |turn, following| turn.model? != following.model? }.to_a
+        end
+
+        def paired?(round)
+          calls = round.calls
+          results = round.results
+          return false unless calls.size == results.size
+          return calls.map(&:name) == results.map(&:name) unless @pairing == :id && (calls + results).all? { ids?(_1) }
+
+          calls.map(&:call_id).tally == results.map(&:result_id).tally
+        end
+
+        def ids?(part)
+          part.call? ? part.call_id : part.result_id
+        end
+
+        def parts_without_data
+          located_parts.filter_map do |turn, position, part|
+            next unless part.without_data
+
+            noun = part.kind == :other ? 'part' : "#{part.kind} part"
+            problem(:part_without_data, "#{noun} carries no data", turn:, part: position)
+          end
+        end
+
+        def empty_turns
+          @turns.select { |turn| turn.parts.empty? }.map { |turn| problem(:empty_turn, 'turn has no parts', turn:) }
+        end
+
+        def unpaired_rounds
+          rounds.reject { |round| paired?(round) }.map do |round|
+            calls = counted(round.calls.size, 'call')
+            results = counted(round.results.size, 'result')
+            message = if round.calls.size == round.results.size
+                        "#{calls} and #{results} that do not pair up"
+                      else
+                        "#{calls} but #{results}"
+                      end
+            problem(:unpaired_round, message, turn: round.turn)
+          end
+        end
+
+        # The one place a shape shows an id: a result naming a call the
+        # request never made can only be traced by the id it names.
+        def unmatched_results
+          return [] unless @pairing == :id
+
+          called = Set.new
+          located_parts.filter_map do |turn, position, part|
+            called << part.call_id if part.call? && part.call_id
+            next unless part.result? && !called.include?(part.result_id)
+
+            message = 'result answers no call in the request'
+            problem(:unmatched_result, message, turn:, part: position, call_id: part.result_id)
+          end
+        end
+
+        def unsigned_calls
+          return [] unless @rules.include?(:signed_steps)
+
+          start = last_user_turn ? @turns.index(last_user_turn) + 1 : 0
+          runs(@turns.drop(start)).select { |run| run.first.model? }.filter_map do |run|
+            turn, position, call = located_parts(run).find { |_, _, part| part.call? }
+            next if call.nil? || call.signed
+
+            message = 'first call of a step in the current turn has no signature'
+            problem(:unsigned_call, message, turn:, part: position)
+          end
+        end
+
+        def unsigned_thinking
+          return [] unless @rules.include?(:signed_thinking)
+
+          located_parts.filter_map do |turn, position, part|
+            next unless part.kind == :thinking && !part.signed
+
+            problem(:unsigned_thinking, 'thinking part has no signature', turn:, part: position)
+          end
+        end
+
+        def roles_out_of_order
+          return [] unless @rules.include?(:alternating_roles)
+
+          turns = @turns.reject { |turn| turn.speaker == :system }
+          problems = turns.each_cons(2).filter_map do |turn, following|
+            next unless turn.model? == following.model?
+
+            problem(:role_order, "follows another #{following.model? ? 'model' : 'user'} turn", turn: following)
+          end
+          first = turns.first
+          problems.unshift(problem(:role_order, 'conversation starts with a model turn', turn: first)) if first&.model?
+          problems
+        end
+
+        def problem(kind, message, turn:, part: nil, call_id: nil)
+          RequestShape::Problem.new(kind:, message:, turn: turn.index, part:, call_id:)
+        end
+
+        def counted(count, noun)
+          "#{count} #{noun}#{'s' unless count == 1}"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/protocol/request_shapes.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RubyLLM
+  class Protocol
+    # Builds the RequestShape a protocol returns from parse_request_shape. A
+    # protocol reads its payload into turns of parts, keeping each piece's
+    # size and never its content, and hands them to shape_request with the
+    # rules its provider enforces; Analysis then finds the problems.
+    module RequestShapes # :nodoc: all
+      SETTING_VALUE = /\A[\w.-]{1,40}\z/
+
+      # A piece of a turn as a protocol reads it, with the ids and flags the
+      # analysis needs and a shape never shows.
+      PartSpec = Struct.new(:kind, :measure, :unit, :name, :source, :mime_type, :signed, :call_id, :result_id,
+                            :without_data, keyword_init: true) do
+        def call?
+          kind == :tool_call
+        end
+
+        def result?
+          kind == :tool_result
+        end
+
+        def to_part
+          RequestShape::Part.new(kind:, size: measure, unit:, name:, source:, mime_type:, signed: signed || false)
+        end
+      end
+
+      # A turn as a protocol reads it. Its speaker, +:system+, +:user+,
+      # +:model+, or +:tool+, tells the analysis whose turn it is.
+      TurnSpec = Struct.new(:index, :role, :speaker, :parts, keyword_init: true) do
+        def model?
+          speaker == :model
+        end
+
+        def to_turn
+          RequestShape::Turn.new(index:, role:, parts: parts.map(&:to_part))
+        end
+      end
+
+      private
+
+      def shape_request(turns, payload:, instructions: [], tool_names: [], thinking_settings: {}, pairing: :id,
+                        rules: [])
+        analysis = Analysis.new(turns, pairing:, rules:)
+        kept = analysis.kept_turns
+        RequestShape.new(
+          provider: @provider&.slug, model: @model&.id, step: analysis.step, payload_keys: payload.keys,
+          thinking_settings: thinking_settings, instructions: instructions.map(&:to_part),
+          turns: kept.map(&:to_turn), turn_count: turns.size, omitted_turns: turns.size - kept.size,
+          tool_names: shape_list(tool_names).filter_map { |name| shape_name(name) },
+          tool_rounds: analysis.tool_rounds, problems: analysis.problems
+        )
+      end
+
+      def shape_turn(index, role, speaker, parts)
+        TurnSpec.new(index:, role: shape_name(role), speaker:, parts: parts.flatten.compact)
+      end
+
+      # A turn on the user's side that carries tool results answers a model
+      # turn instead of starting a new one.
+      def shape_answer(parts)
+        parts.flatten.compact.any?(&:result?) ? :tool : :user
+      end
+
+      def shape_instructions(text)
+        text.nil? ? [] : [shape_text(text)]
+      end
+
+      def shape_text(text, kind: :text, signed: false)
+        PartSpec.new(kind:, measure: shape_length(text), signed:, without_data: kind == :text && text.nil?)
+      end
+
+      def shape_summary(summary, signed: false)
+        parts = shape_list(summary)
+        measure = parts.sum { |part| shape_length(shape_hash(part)['text']).to_i } unless parts.empty?
+        PartSpec.new(kind: :thinking, measure:, signed:)
+      end
+
+      def shape_tool_call(name, arguments, id: nil, signed: false)
+        PartSpec.new(kind: :tool_call, name: shape_name(name), measure: shape_length(arguments),
+                     call_id: shape_name(id), signed:)
+      end
+
+      # A result made of content blocks counts the characters of its text,
+      # and its other blocks, such as images, follow it as parts of their
+      # own. The block reads one content block in the protocol's format.
+      def shape_tool_result(content, name: nil, id: nil)
+        result = PartSpec.new(kind: :tool_result, name: shape_name(name), result_id: shape_name(id))
+        unless content.is_a?(Array) && block_given?
+          result.measure = shape_length(content)
+          return [result]
+        end
+
+        texts, others = content.flat_map { |block| yield shape_hash(block) }.partition { |part| part.kind == :text }
+        result.measure = texts.sum { |part| part.measure.to_i }
+        [result, *others]
+      end
+
+      def shape_other(name, signed: false)
+        PartSpec.new(kind: :other, name: shape_name(name), signed:)
+      end
+
+      def shape_media(kind, source:, size: nil, unit: nil, mime_type: nil, signed: false)
+        mime_type = shape_name(mime_type)
+        PartSpec.new(kind: kind || shape_media_kind(mime_type), measure: size, unit:, source:, mime_type:, signed:)
+      end
+
+      def shape_inline(data, kind: nil, mime_type: nil, signed: false)
+        shape_media(kind, source: :inline, size: shape_bytes(data), unit: :bytes, mime_type:, signed:)
+      end
+
+      def shape_file(kind: nil, mime_type: nil)
+        shape_media(kind, source: :file, mime_type:)
+      end
+
+      # A URL field can hold a data URI instead of a link.
+      def shape_url(url, kind: nil, mime_type: nil)
+        return shape_media(kind, source: :url, mime_type:) unless url.is_a?(String) && url.start_with?('data:')
+
+        header, data = url.split(',', 2)
+        shape_inline(data, kind:, mime_type: header.delete_prefix('data:').split(';').first)
+      end
+
+      def shape_media_kind(mime_type)
+        type = mime_type.to_s
+        return :image if Files::MimeType.image?(type)
+        return :audio if Files::MimeType.audio?(type)
+        return :video if Files::MimeType.video?(type)
+
+        :document
+      end
+
+      def shape_tool_name(tool)
+        tool = shape_hash(tool)
+        tool['name'] || tool['type']
+      end
+
+      # Thinking settings are short words and numbers, such as an effort or
+      # a budget, so anything else is left out rather than risk content.
+      def shape_settings(settings, *names)
+        shape_hash(settings).slice(*names).select do |_, value|
+          [Integer, Float, TrueClass, FalseClass].any? { |type| value.is_a?(type) } ||
+            (value.is_a?(String) && value.match?(SETTING_VALUE))
+        end
+      end
+
+      def shape_signature?(signature)
+        signature.is_a?(String) && !signature.empty?
+      end
+
+      def shape_name(value)
+        value if value.is_a?(String) && !value.empty?
+      end
+
+      def shape_length(value)
+        case value
+        when nil then nil
+        when String then value.length
+        else JSON.generate(value).length
+        end
+      end
+
+      # Base64 carries three bytes in every four characters, and its padding
+      # marks the missing bytes of the last group.
+      def shape_bytes(data)
+        return unless data.is_a?(String)
+
+        ((data.length - data.count("\r\n")) * 3 / 4) - [data.count('='), 2].min
+      end
+
+      def shape_hash(value)
+        value.is_a?(Hash) ? value : {}
+      end
+
+      def shape_list(value)
+        value.is_a?(Array) ? value : []
+      end
+    end
+  end
+end

data/lib/ruby_llm/protocol/stored_uploads.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class Protocol
+    # Reuses the provider file an attachment's store recorded in an earlier
+    # process. Before a process first reuses a file, the provider confirms
+    # it still has it; a file that is missing or expired is uploaded again.
+    class StoredUploads # :nodoc:
+      FILES = Support::ProcessCache.new(limit: 1024)
+
+      def self.files
+        FILES
+      end
+
+      def initialize(provider, store)
+        @provider = provider
+        @store = store
+        @account = provider.account_identity if store
+      end
+
+      def fetch
+        return yield unless @account
+
+        stored_file || remember(yield)
+      end
+
+      def forget(upload)
+        return unless @account
+
+        FILES.delete(key(upload.id))
+        @store.forget(upload.id, provider: @provider.slug, account: @account)
+      end
+
+      private
+
+      def stored_file
+        stored = @store.fetch(provider: @provider.slug, account: @account)
+        return if stored.nil? || stored.expired?
+
+        file = confirmed_file(stored.id)
+        file unless file.nil? || file.expired?
+      end
+
+      def confirmed_file(id)
+        FILES.fetch(key(id)) { @provider.find_file(id) }
+      rescue StandardError => e
+        RubyLLM.logger.debug { "Uploading again: #{@provider.slug} could not find #{id} (#{e.message})" }
+        nil
+      end
+
+      def remember(upload)
+        FILES.fetch(key(upload.id)) { upload }
+        @store.store(upload, provider: @provider.slug, account: @account)
+        upload
+      end
+
+      def key(id)
+        [@provider.slug, @account, id]
+      end
+    end
+  end
+end

data/lib/ruby_llm/protocol/stream_accumulator.rb

@@ -11,16 +11,11 @@ module RubyLLM
       def initialize
         @content = +''
         @citations = []
+        @citation_keys = {}
         @thinking_text = nil
         @thinking_signature = nil
         @tool_calls = {}
-        @input_tokens = nil
-        @output_tokens = nil
-        @cache_read_tokens = nil
-        @cache_write_tokens = nil
-        @thinking_tokens = nil
-        @server_tool_use = nil
-        @reported_cost = nil
+        @tokens = Tokens.new
         @server_tool_calls = []
         @raw_content = nil
         @raw_reasoning = nil
@@ -53,15 +48,7 @@ module RubyLLM
             text: @thinking_text,
             signature: @thinking_signature
           ),
-          tokens: Tokens.new(
-            input: @input_tokens,
-            output: @output_tokens,
-            cache_read: @cache_read_tokens,
-            cache_write: @cache_write_tokens,
-            thinking: @thinking_tokens,
-            server_tool_use: @server_tool_use,
-            reported_cost: @reported_cost
-          ),
+          tokens: @tokens,
           server_tool_calls: @server_tool_calls,
           raw_content: @raw_content,
           raw_reasoning: @raw_reasoning,
@@ -77,7 +64,11 @@ module RubyLLM
       # Providers like Perplexity repeat the full citation list on every chunk.
       def accumulate_citations(new_citations)
         new_citations.each do |citation|
-          @citations << citation unless @citations.include?(citation)
+          key = citation.to_h
+          next if @citation_keys.key?(key)
+
+          @citation_keys[key] = true
+          @citations << citation
         end
       end
 
@@ -182,14 +173,7 @@ module RubyLLM
       end
 
       def count_tokens(chunk)
-        tokens = chunk.tokens
-        @input_tokens = tokens.input if tokens.input
-        @output_tokens = tokens.output if tokens.output
-        @cache_read_tokens = tokens.cache_read if tokens.cache_read
-        @cache_write_tokens = tokens.cache_write if tokens.cache_write
-        @thinking_tokens = tokens.thinking if tokens.thinking
-        @server_tool_use = tokens.server_tool_use if tokens.server_tool_use
-        @reported_cost = tokens.reported_cost if tokens.reported_cost
+        @tokens = @tokens.merge(chunk.tokens)
       end
 
       def handle_chunk_content(chunk)

data/lib/ruby_llm/protocol/streaming.rb

@@ -1,15 +1,23 @@
 # frozen_string_literal: true
 
-require 'event_stream_parser'
 require 'faraday'
 require 'json'
 
 module RubyLLM
   class Protocol
     module Streaming # :nodoc: all
-      StreamState = Struct.new(:parser, :buffer) do
+      MAX_JSON_BODY_BYTES = 1024 * 1024
+
+      StreamState = Struct.new(:parser, :buffer, :json_body) do
         def initialize
-          super(EventStreamParser::Parser.new, +'')
+          super
+          reset
+        end
+
+        def reset
+          self.parser = Transport::EventStreamParser.new
+          self.buffer = +''
+          self.json_body = nil
         end
       end
 
@@ -33,13 +41,15 @@ module RubyLLM
       # parsed event Hash. Returns the Faraday response.
       def stream_events(url, payload, additional_headers = {}, &block)
         progress = {}
-        on_data = build_on_data_handler(progress) do |data|
+        fallback_state = StreamState.new
+        on_data = build_on_data_handler(progress, fallback_state: fallback_state) do |data|
           block.call(data) if data.is_a?(Hash)
         end
 
-        @connection.post url, payload, usage: @usage_tracker do |req|
+        @connection.post url, payload, usage: @usage_tracker, stream: true do |req|
           req.headers = additional_headers.merge(req.headers) unless additional_headers.empty?
           (req.options.context ||= {})[Transport::Connection::STREAM_PROGRESS_KEY] = progress
+          req.options.context[Transport::ErrorMiddleware::STREAM_RESET_KEY] = fallback_state.method(:reset)
           if faraday_1?
             req.options[:on_data] = on_data
           else
@@ -60,12 +70,9 @@ module RubyLLM
         Faraday::VERSION.start_with?('1')
       end
 
-      # Parser state lives on the env so every retry attempt starts fresh;
-      # ErrorMiddleware clears it per attempt. Faraday v1 passes no env to
-      # on_data, so it falls back to one state for the whole request.
-      def build_on_data_handler(progress = {}, &handler)
-        fallback_state = StreamState.new
-
+      # Some adapters omit the env, so ErrorMiddleware also resets the
+      # request's fallback state before each attempt.
+      def build_on_data_handler(progress = {}, fallback_state: StreamState.new, &handler)
         FaradayHandlers.build(
           faraday_v1: faraday_1?,
           on_chunk: lambda { |chunk, env|
@@ -86,36 +93,35 @@ module RubyLLM
       def process_stream_chunk(chunk, state, env, progress, &)
         RubyLLM.logger.debug { "Received chunk: #{chunk}" } if RubyLLM.config.log_stream_debug
 
-        if error_chunk?(chunk)
-          handle_error_chunk(chunk, env)
-        elsif json_error_payload?(chunk)
-          handle_json_error_chunk(chunk, env)
+        if json_body?(chunk, state)
+          handle_json_body(chunk, state, env)
         else
           handle_sse(chunk, state.parser, env, progress, &)
         end
       end
 
-      # An error event split across network reads reaches here in pieces, so only
-      # a whole one takes this shortcut; the rest go to the parser, which buffers
-      # them until the event is complete.
-      def error_chunk?(chunk)
-        chunk.start_with?('event: error') && chunk.end_with?("\n\n")
+      # Adapters cut reads anywhere, so a read inside an event can start with
+      # "{". Only the first bytes of a body can open a bare JSON error.
+      def json_body?(chunk, state)
+        state.json_body = chunk.lstrip.start_with?('{') if state.json_body.nil? && !chunk.strip.empty?
+        state.json_body
       end
 
-      def json_error_payload?(chunk)
-        chunk.lstrip.start_with?('{') && chunk.include?('"error"')
-      end
-
-      def handle_json_error_chunk(chunk, env)
-        parse_error_from_json(chunk, env, 'Failed to parse JSON error chunk')
-      end
+      def handle_json_body(chunk, state, env)
+        if state.buffer.bytesize + chunk.bytesize > MAX_JSON_BODY_BYTES
+          raise Error, "Streaming JSON response exceeds #{MAX_JSON_BODY_BYTES} bytes"
+        end
 
-      def handle_error_chunk(chunk, env)
-        error_data = chunk.split("\n")[1]&.delete_prefix('data: ')
-        parse_error_from_json(error_data, env, 'Failed to parse error chunk') if error_data
+        state.buffer << chunk
+        parsed = JSON.parse(state.buffer)
+        raise_stream_error(state.buffer, parsed, env) if parsed.is_a?(Hash) && parsed['error']
+      rescue JSON::ParserError
+        RubyLLM.logger.debug { 'Waiting for the remaining JSON response bytes' }
       end
 
       def handle_failed_response(chunk, buffer, env)
+        return if buffer.bytesize + chunk.bytesize > MAX_JSON_BODY_BYTES
+
         buffer << chunk
         error_data = JSON.parse(buffer)
         raise_stream_error(buffer, error_data, env)
@@ -184,7 +190,8 @@ module RubyLLM
         if faraday_1? || env.nil?
           Struct.new(:body, :status).new(parsed_data, error_status)
         else
-          env.merge(body: parsed_data, status: error_status)
+          # Faraday writes body into the request until a status is set.
+          env.merge(status: error_status, body: parsed_data)
         end
       end