ruby_llm 2.1.1 → 2.2.0

data/lib/ruby_llm/protocols/converse/media.rb

@@ -21,37 +21,37 @@ module RubyLLM
           end
         end
 
-        def format_content(content, attachments = [], used_document_names: nil, citations: false)
+        def render_content(content, attachments = [], used_document_names: nil, citations: false)
           used_document_names ||= {}
           blocks = []
           blocks << { text: content } unless content.nil? || content.empty?
           attachments.each do |attachment|
-            blocks << format_attachment(attachment, used_document_names:, citations:)
+            blocks << render_attachment(attachment, used_document_names:, citations:)
           end
           blocks
         end
 
-        def format_attachment(attachment, used_document_names:, citations: false)
+        def render_attachment(attachment, used_document_names:, citations: false)
           raise UnsupportedAttachmentError, attachment.mime_type unless supported_attachment?(attachment)
 
           if attachment.provider_file?
-            return format_provider_file_attachment(attachment, used_document_names:, citations:)
+            return render_provider_file_attachment(attachment, used_document_names:, citations:)
           end
 
           case attachment.type
           when :image
-            format_image_attachment(attachment)
+            render_image_attachment(attachment)
           when :audio
-            format_audio_attachment(attachment)
+            render_audio_attachment(attachment)
           when :video
-            format_video_attachment(attachment)
+            render_video_attachment(attachment)
           when :pdf, :document
-            format_document_attachment(attachment, used_document_names:, citations:)
+            render_document_attachment(attachment, used_document_names:, citations:)
           when :text
             if citations
-              format_text_document_attachment(attachment, used_document_names:)
+              render_text_document_attachment(attachment, used_document_names:)
             else
-              format_text_attachment(attachment)
+              render_text_attachment(attachment)
             end
           end
         end
@@ -71,7 +71,7 @@ module RubyLLM
           '3gpp' => 'three_gp'
         }.freeze
 
-        def format_image_attachment(attachment)
+        def render_image_attachment(attachment)
           {
             image: {
               format: attachment.format,
@@ -82,7 +82,7 @@ module RubyLLM
           }
         end
 
-        def format_audio_attachment(attachment)
+        def render_audio_attachment(attachment)
           {
             audio: {
               format: media_format(attachment, AUDIO_FORMAT_ALIASES, SUPPORTED_AUDIO_FORMATS),
@@ -93,7 +93,7 @@ module RubyLLM
           }
         end
 
-        def format_video_attachment(attachment)
+        def render_video_attachment(attachment)
           {
             video: {
               format: media_format(attachment, VIDEO_FORMAT_ALIASES, SUPPORTED_VIDEO_FORMATS),
@@ -112,11 +112,11 @@ module RubyLLM
           format
         end
 
-        def format_text_attachment(attachment)
+        def render_text_attachment(attachment)
           { text: attachment.for_llm }
         end
 
-        def format_document_attachment(attachment, used_document_names:, citations: false)
+        def render_document_attachment(attachment, used_document_names:, citations: false)
           format = document_format(attachment)
 
           raise UnsupportedAttachmentError, attachment.mime_type unless supported_document_format?(attachment)
@@ -136,7 +136,7 @@ module RubyLLM
         # Text attachments become citable documents when citations are
         # enabled. Bedrock rejects text-format documents sent as bytes when
         # citations are on, so the text rides in the source's text member.
-        def format_text_document_attachment(attachment, used_document_names:)
+        def render_text_document_attachment(attachment, used_document_names:)
           document_name = unique_document_name(sanitize_document_name(attachment.filename), used_document_names)
           {
             document: {
@@ -148,7 +148,7 @@ module RubyLLM
           }
         end
 
-        def format_provider_file_attachment(attachment, used_document_names:, citations: false)
+        def render_provider_file_attachment(attachment, used_document_names:, citations: false)
           raise UnsupportedAttachmentError, attachment.mime_type unless supported_document_format?(attachment)
 
           document_name = unique_document_name(sanitize_document_name(attachment.filename), used_document_names)
@@ -180,11 +180,13 @@ module RubyLLM
         end
 
         def unique_document_name(base_name, used_names)
-          count = used_names[base_name].to_i
-          used_names[base_name] = count + 1
-          return base_name if count.zero?
-
-          "#{base_name}_#{count + 1}"
+          name = base_name
+          while used_names.key?(name)
+            used_names[base_name] += 1
+            name = "#{base_name}_#{used_names[base_name]}"
+          end
+          used_names[name] = 1
+          name
         end
       end
     end

data/lib/ruby_llm/protocols/converse/reasoning.rb

@@ -14,17 +14,17 @@ module RubyLLM
 
         module_function
 
-        def format_reasoning_fields(thinking, model, max_output_tokens = nil)
+        def render_reasoning_fields(thinking, model, max_output_tokens = nil)
           return nil unless thinking&.enabled?
-          return format_nova_reasoning_fields(thinking, model) if nova_model?(model)
+          return render_nova_reasoning_fields(thinking, model) if nova_model?(model)
           return disabled_reasoning_fields(model) if thinking.enabled == false
-          return format_adaptive_reasoning_fields(thinking) if adaptive_thinking?(thinking, model)
+          return render_adaptive_reasoning_fields(thinking) if adaptive_thinking?(thinking, model)
 
           effort = thinking.effort.to_s
           budget = reasoning_budget(thinking, effort, model, max_output_tokens)
           return { reasoning_config: { type: 'enabled', budget_tokens: budget } } if budget
 
-          format_effort_fields(effort, model) unless effort.empty?
+          render_effort_fields(effort, model) unless effort.empty?
         end
 
         def disabled_reasoning_fields(model)
@@ -42,7 +42,7 @@ module RubyLLM
 
         # Models that publish a reasoning_config enum, such as OpenAI's GPT
         # models, take the effort as its value and reject reasoning_effort.
-        def format_effort_fields(effort, model)
+        def render_effort_fields(effort, model)
           return { reasoning_config: effort } if reasoning_config_schema(model)
 
           { reasoning_effort: effort } unless effort == 'none'
@@ -52,14 +52,14 @@ module RubyLLM
         # adaptively, and reject a reasoning_config that enables a budget.
         def adaptive_thinking?(thinking, model)
           return false unless thinking.budget.nil?
-          return false unless Chat.foundation_model_id(model&.id).start_with?('anthropic.claude')
+          return false unless claude_model?(model)
 
           registered = registered_model(model)
           !registered.nil? && !registered.reasoning_option(:effort).nil? &&
             registered.reasoning_option(:budget_tokens).nil?
         end
 
-        def format_adaptive_reasoning_fields(thinking)
+        def render_adaptive_reasoning_fields(thinking)
           effort = thinking.effort.to_s
           return nil if effort == 'none'
           return { thinking: { type: 'adaptive' } } if effort.empty?
@@ -79,13 +79,17 @@ module RubyLLM
           end
         end
 
+        def claude_model?(model)
+          Chat.foundation_model_id(model&.id).start_with?('anthropic.claude')
+        end
+
         def nova_model?(model)
           Chat.foundation_model_id(model&.id).start_with?('amazon.nova')
         end
 
         # Nova 2 takes reasoningConfig with an effort level instead of a token budget,
         # and rejects an enabled reasoningConfig that names no effort.
-        def format_nova_reasoning_fields(thinking, model)
+        def render_nova_reasoning_fields(thinking, model)
           if thinking.budget
             raise ArgumentError,
                   "#{model&.id} takes a reasoning effort, not a token budget of #{thinking.budget}. " \
@@ -103,12 +107,22 @@ module RubyLLM
 
         def reasoning_budget(thinking, effort, model, max_output_tokens)
           return thinking.budget if thinking.budget.is_a?(Integer)
-          return nil if effort.empty? || effort == 'none'
+          return nil if effort == 'none'
+          return toggle_budget(thinking, model) if effort.empty?
 
           schema = reasoning_budget_schema(model)
           schema && effort_budget_tokens(effort, schema, max_output_tokens)
         end
 
+        # Claude generations that take a budget have no bare switch, so
+        # turning thinking on sends the smallest budget the model accepts.
+        def toggle_budget(thinking, model)
+          return nil unless thinking.enabled == true && claude_model?(model)
+
+          minimum = registered_model(model)&.reasoning_option(:budget_tokens)&.fetch(:min, nil)
+          [minimum, MINIMUM_BUDGET_TOKENS].max if minimum.is_a?(Integer)
+        end
+
         def reasoning_budget_schema(model)
           request_fields_schema(model) { |schema| schema.dig(:reasoningConfig, :budgetTokens) }
         end

data/lib/ruby_llm/protocols/converse/streaming.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'base64'
-require 'faraday'
 require 'json'
 
 module RubyLLM
@@ -9,7 +7,7 @@ module RubyLLM
     class Converse
       # Streaming implementation for Bedrock ConverseStream (AWS Event Stream).
       module Streaming
-        ErrorResponse = Struct.new(:body, :status)
+        include Protocols::Bedrock::EventStream
 
         private
 
@@ -19,28 +17,14 @@ module RubyLLM
 
         def stream_response(payload, additional_headers = {}, &block)
           @thinking_stream = ThinkingStream.new
+          @stream_text_lengths = Hash.new(0)
+          @stream_citations = {}
           accumulator = RubyLLM::Protocol::StreamAccumulator.new
-          decoder = event_stream_decoder
-          body = JSON.generate(payload)
-          progress = {}
-
-          faraday_v1 = Faraday::VERSION.start_with?('1')
-          on_data = RubyLLM::Protocol::Streaming::FaradayHandlers.build(
-            faraday_v1: faraday_v1,
-            on_chunk: ->(chunk, _env) { parse_stream_chunk(decoder, chunk, accumulator, progress, &block) },
-            on_failed_response: ->(chunk, env) { handle_failed_stream(chunk, env) }
-          )
-
-          response = @connection.post(stream_url, body, usage: @usage_tracker, stream: true) do |req|
-            req.headers.merge!(additional_headers) unless additional_headers.empty?
-            req.headers['Accept'] = 'application/vnd.amazon.eventstream'
-            (req.options.context ||= {})[RubyLLM::Transport::Connection::STREAM_PROGRESS_KEY] = progress
 
-            if faraday_v1
-              req.options[:on_data] = on_data
-            else
-              req.options.on_data = on_data
-            end
+          response = stream_events(stream_url, JSON.generate(payload), additional_headers) do |event|
+            chunk = build_chunk(event)
+            accumulator.add(chunk)
+            block.call(chunk)
           end
 
           message = accumulator.to_message(response)
@@ -48,139 +32,6 @@ module RubyLLM
           message
         end
 
-        def event_stream_decoder
-          require 'aws-eventstream'
-          Aws::EventStream::Decoder.new
-        rescue LoadError
-          raise Error,
-                'The aws-eventstream gem is required for Bedrock streaming. ' \
-                'Please add it to your Gemfile: gem "aws-eventstream"'
-        end
-
-        # The error body arrives in as many reads as the adapter hands out, so
-        # it accumulates on the env, which ErrorMiddleware clears per attempt.
-        def handle_failed_stream(chunk, env)
-          buffer = failed_stream_buffer(env)
-          buffer << chunk
-          error_response = env.merge(body: JSON.parse(buffer))
-          Transport::ErrorMiddleware.parse_error(provider: self, response: error_response)
-        rescue JSON::ParserError
-          RubyLLM.logger.debug { "Accumulating Bedrock stream error chunk: #{chunk}" }
-        end
-
-        def failed_stream_buffer(env)
-          (env[:streaming_state] ||= RubyLLM::Protocol::Streaming::StreamState.new).buffer
-        end
-
-        def parse_stream_chunk(decoder, raw_chunk, accumulator, progress)
-          handle_non_eventstream_error_chunk(raw_chunk)
-
-          decode_events(decoder, raw_chunk).each do |event|
-            chunk = build_chunk(event)
-            next unless chunk
-
-            accumulator.add(chunk)
-            progress[:started] = true
-            yield chunk
-          end
-        end
-
-        def handle_non_eventstream_error_chunk(raw_chunk)
-          text = raw_chunk.to_s
-
-          if text.start_with?('event: error')
-            payload = text.lines.find { |line| line.start_with?('data:') }&.delete_prefix('data:')&.strip
-            raise_streaming_chunk_error(payload) if payload
-            return
-          end
-
-          return unless text.lstrip.start_with?('{') && text.include?('"error"')
-
-          raise_streaming_chunk_error(text)
-        end
-
-        def raise_streaming_chunk_error(payload)
-          parsed = JSON.parse(payload)
-          message = parsed.dig('error', 'message') || parsed['message'] || 'Bedrock streaming error'
-          response = ErrorResponse.new({ 'message' => message }, 500)
-          Transport::ErrorMiddleware.parse_error(provider: self, response: response)
-        rescue JSON::ParserError
-          nil
-        end
-
-        def decode_events(decoder, raw_chunk)
-          events = []
-          message, eof = decoder.decode_chunk(raw_chunk)
-
-          while message
-            event = decode_event(message)
-            if event && RubyLLM.config.log_stream_debug
-              RubyLLM.logger.debug do
-                "Bedrock stream event keys: #{event.keys}"
-              end
-            end
-            events << event if event
-            break if eof
-
-            message, eof = decoder.decode_chunk
-          end
-
-          events
-        end
-
-        # ConverseStream delivers modeled errors as a frame after the 200, with
-        # the type in the frame headers and a bare message as the payload. Rewrap
-        # it under the exception name so raise_stream_error classifies it instead
-        # of the frame passing for an empty chunk.
-        def decode_event(message)
-          return decode_error_frame(message.headers) if stream_error_frame?(message)
-
-          exception_type = stream_exception_type(message)
-          payload = message.payload.read
-          event = decode_event_payload(payload)
-          return event unless exception_type
-
-          { exception_type => event || { 'message' => payload.to_s } }
-        end
-
-        # Failures the API does not model arrive as an error frame instead,
-        # with the code and message in the headers and nothing in the payload.
-        def stream_error_frame?(message)
-          event_header(message.headers, ':message-type') == 'error'
-        end
-
-        def decode_error_frame(headers)
-          detail = [event_header(headers, ':error-code'), event_header(headers, ':error-message')].compact.join(': ')
-          event = { 'type' => 'error' }
-          event['error'] = { 'message' => detail } unless detail.empty?
-          event
-        end
-
-        def stream_exception_type(message)
-          headers = message.headers
-          return nil unless event_header(headers, ':message-type') == 'exception'
-
-          event_header(headers, ':exception-type') || 'streamingException'
-        end
-
-        def event_header(headers, name)
-          header = headers[name]
-          header.respond_to?(:value) ? header.value : header
-        end
-
-        def decode_event_payload(payload)
-          outer = JSON.parse(payload)
-
-          if outer['bytes'].is_a?(String)
-            JSON.parse(Base64.decode64(outer['bytes']))
-          else
-            outer
-          end
-        rescue JSON::ParserError => e
-          RubyLLM.logger.debug { "Failed to decode Bedrock stream event payload: #{e.message}" }
-          nil
-        end
-
         def build_chunk(event)
           raise_stream_error(event) if stream_error_event?(event)
 
@@ -189,22 +40,22 @@ module RubyLLM
           Chunk.new(
             role: :assistant,
             model: event['modelId'] || @model&.id,
-            content: extract_content_delta(event),
-            citations: extract_citations_delta(event),
+            content: parse_content_delta(event),
+            citations: parse_block_citations(event),
             thinking: Thinking.build(
-              text: extract_thinking_delta(event),
-              signature: extract_thinking_signature(event)
+              text: parse_thinking_delta(event),
+              signature: parse_thinking_signature(event)
             ),
             raw_reasoning: streamed_thinking_blocks(event),
             tool_calls: extract_tool_calls(event),
-            server_tool_calls: extract_server_tool_call_events(event),
-            input_tokens: extract_input_tokens(metadata_usage, usage),
-            output_tokens: extract_output_tokens(metadata_usage, usage),
-            cache_read_tokens: extract_cache_read_tokens(metadata_usage, usage),
-            cache_write_tokens: extract_cache_write_tokens(metadata_usage, usage),
+            server_tool_calls: parse_server_tool_call_events(event),
+            input_tokens: parse_input_tokens(metadata_usage, usage),
+            output_tokens: parse_output_tokens(metadata_usage, usage),
+            cache_read_tokens: parse_cache_read_tokens(metadata_usage, usage),
+            cache_write_tokens: parse_cache_write_tokens(metadata_usage, usage),
             cache_write_tokens_by_ttl: Chat.cache_write_by_ttl(metadata_usage) || Chat.cache_write_by_ttl(usage),
-            thinking_tokens: extract_reasoning_tokens(metadata_usage, usage),
-            finish_reason: extract_finish_reason(event)
+            thinking_tokens: parse_reasoning_tokens(metadata_usage, usage),
+            finish_reason: parse_finish_reason(event)
           )
         end
 
@@ -214,7 +65,7 @@ module RubyLLM
           @thinking_stream.raw_reasoning if event.key?('messageStop') || event.key?('stopReason')
         end
 
-        def extract_finish_reason(event)
+        def parse_finish_reason(event)
           normalize_finish_reason(event.dig('messageStop', 'stopReason') || event['stopReason'])
         end
 
@@ -225,69 +76,66 @@ module RubyLLM
           ]
         end
 
-        def extract_input_tokens(metadata_usage, usage)
+        def parse_input_tokens(metadata_usage, usage)
           bedrock_usage = metadata_usage['inputTokens'] ? metadata_usage : usage
           Chat.input_tokens(bedrock_usage) if bedrock_usage['inputTokens']
         end
 
-        def extract_output_tokens(metadata_usage, usage)
+        def parse_output_tokens(metadata_usage, usage)
           metadata_usage['outputTokens'] || usage['outputTokens']
         end
 
-        def extract_cache_read_tokens(metadata_usage, usage)
+        def parse_cache_read_tokens(metadata_usage, usage)
           metadata_usage['cacheReadInputTokens'] || usage['cacheReadInputTokens']
         end
 
-        def extract_cache_write_tokens(metadata_usage, usage)
+        def parse_cache_write_tokens(metadata_usage, usage)
           metadata_usage['cacheWriteInputTokens'] || usage['cacheWriteInputTokens']
         end
 
-        def extract_reasoning_tokens(metadata_usage, usage)
+        def parse_reasoning_tokens(metadata_usage, usage)
           Chat.reasoning_tokens(metadata_usage) || Chat.reasoning_tokens(usage)
         end
 
-        def stream_error_event?(event)
-          event.keys.any? { |key| key.end_with?('Exception') } || event['type'] == 'error'
+        def parse_content_delta(event)
+          normalized_delta(event)['text']
         end
 
-        def raise_stream_error(event)
-          if event['type'] == 'error'
-            message = event.dig('error', 'message') || 'Bedrock streaming error'
-            response = ErrorResponse.new({ 'message' => message }, 500)
-            Transport::ErrorMiddleware.parse_error(provider: self, response: response)
-            return
-          end
+        # A citation delta arrives before the text it supports, so a block's
+        # citations wait for the block to stop and take its span of the response.
+        # A block still open when the message stops gives up what it has.
+        def parse_block_citations(event)
+          track_citation_block(event)
+          finished_citation_blocks(event).flat_map { |index| take_block_citations(index) }
+        end
 
-          key = event.keys.find { |candidate| candidate.end_with?('Exception') }
-          payload = event[key]
-          message = payload['message'] || key
-          status = case key
-                   when 'throttlingException' then 429
-                   when 'validationException' then 400
-                   when 'accessDeniedException', 'unrecognizedClientException' then 401
-                   when 'serviceUnavailableException' then 503
-                   else 500
-                   end
-
-          response = ErrorResponse.new({ 'message' => message }, status)
-          Transport::ErrorMiddleware.parse_error(provider: self, response: response)
+        def track_citation_block(event)
+          @stream_text_lengths ||= Hash.new(0)
+          @stream_citations ||= {}
+          index = event_block_index(event)
+          return unless index
+
+          delta = normalized_delta(event)
+          @stream_text_lengths[index] += delta['text'].length if delta['text'].is_a?(String)
+          (@stream_citations[index] ||= []) << delta['citation'] if delta['citation'].is_a?(Hash)
         end
 
-        def extract_content_delta(event)
-          normalized_delta(event)['text']
+        def finished_citation_blocks(event)
+          return @stream_citations.keys.sort if event.key?('messageStop') || event.key?('stopReason')
+          return [] if %w[delta start contentBlockDelta contentBlockStart].any? { |key| event.key?(key) }
+
+          [event_block_index(event)].compact
         end
 
-        # The cited span itself streams as ordinary text deltas; the citation
-        # delta carries the source. The final message resolves the span text
-        # from the accumulated content when indices are known.
-        def extract_citations_delta(event)
-          citation = normalized_delta(event)['citation']
-          return nil unless citation.is_a?(Hash)
+        def take_block_citations(index)
+          length = @stream_text_lengths[index]
+          start_index = @stream_text_lengths.sum { |block_index, size| block_index < index ? size : 0 }
+          span = length.zero? ? {} : { start_index:, end_index: start_index + length }
 
-          [Chat.parse_citation(citation)]
+          Array(@stream_citations.delete(index)).map { |citation| Chat.parse_citation(citation, **span) }
         end
 
-        def extract_thinking_delta(event)
+        def parse_thinking_delta(event)
           reasoning_content = normalized_delta(event)['reasoningContent'] || {}
 
           reasoning_text = reasoning_content['reasoningText'] || {}
@@ -295,33 +143,33 @@ module RubyLLM
           return reasoning_content['text'] if reasoning_content.key?('text')
           return '' if [reasoning_text, reasoning_content].any? { |block| block.key?('signature') }
 
-          extract_thinking_from_start(event)
+          parse_thinking_from_start(event)
         end
 
-        def extract_thinking_from_start(event)
+        def parse_thinking_from_start(event)
           start = event.dig('contentBlockStart', 'start', 'reasoningContent') || {}
           return unless start.key?('reasoningText')
 
           start.dig('reasoningText', 'text').to_s
         end
 
-        def extract_thinking_signature(event)
-          signature = extract_signature_from_delta(event)
+        def parse_thinking_signature(event)
+          signature = parse_signature_from_delta(event)
           return signature if signature
 
-          signature = extract_signature_from_start(event)
+          signature = parse_signature_from_start(event)
           return signature if signature
 
           nil
         end
 
-        def extract_signature_from_delta(event)
+        def parse_signature_from_delta(event)
           reasoning_content = normalized_delta(event)['reasoningContent'] || {}
           reasoning_text = reasoning_content['reasoningText'] || {}
           reasoning_text['signature'] || reasoning_content['signature'] || reasoning_content['redactedContent']
         end
 
-        def extract_signature_from_start(event)
+        def parse_signature_from_start(event)
           start = event.dig('contentBlockStart', 'start', 'reasoningContent')
           return nil unless start
 
@@ -333,8 +181,8 @@ module RubyLLM
         end
 
         def extract_tool_calls(event)
-          return extract_tool_call_start(event) if tool_call_start_event?(event)
-          return extract_tool_call_delta(event) if tool_call_delta_event?(event)
+          return parse_tool_call_start(event) if tool_call_start_event?(event)
+          return parse_tool_call_delta(event) if tool_call_delta_event?(event)
 
           nil
         end
@@ -347,7 +195,7 @@ module RubyLLM
           event['contentBlockDelta'] || event.dig('delta', 'toolUse')
         end
 
-        def extract_tool_call_start(event)
+        def parse_tool_call_start(event)
           tool_use = event.dig('contentBlockStart', 'start', 'toolUse') || event.dig('start', 'toolUse')
           return nil unless tool_use
 
@@ -358,27 +206,27 @@ module RubyLLM
 
           tool_use_id = tool_use['toolUseId']
           {
-            tool_use_id => ToolCall.new(
-              id: tool_use_id,
+            event_block_index(event) => ToolCall.new(
+              provider_call_id: tool_use_id,
               name: tool_use['name'],
               arguments: tool_use['input'] || {}
             )
           }
         end
 
-        def extract_tool_call_delta(event)
+        def parse_tool_call_delta(event)
           return nil if server_tool_block_event?(event)
 
           input = normalized_delta(event).dig('toolUse', 'input')
           return nil unless input
 
-          { nil => ToolCall.new(id: nil, name: nil, arguments: input) }
+          { event_block_index(event) => ToolCall.new(name: nil, arguments: input) }
         end
 
         # Server-executed tool steps stream as typed toolUse and toolResult
         # block starts. Their input deltas are not function-call arguments,
         # so the block index is remembered and its deltas skipped.
-        def extract_server_tool_call_events(event)
+        def parse_server_tool_call_events(event)
           start = event.dig('contentBlockStart', 'start') || event['start']
           return [] unless start.is_a?(Hash)