ruby_llm 2.0.0 → 2.1.0

data/lib/ruby_llm/providers/vertexai/gemini.rb

@@ -31,8 +31,8 @@ module RubyLLM
           "#{@provider.model_path(@model.id)}:countTokens"
         end
 
-        def render_count_tokens_payload(messages, **options)
-          count_tokens_request(messages, **options)
+        def render_count_tokens_payload(messages, **)
+          count_tokens_request(messages, **)
         end
 
         def caches_url

data/lib/ruby_llm/providers/vertexai/transcription.rb

@@ -35,6 +35,7 @@ module RubyLLM
           parts = data.dig('candidates', 0, 'content', 'parts') || []
           segments = parts.filter_map { |part| parse_transcription_segment(part) }
           text = parts.filter_map { |part| part['text'] || part.dig('audioTranscription', 'text') }.join
+          raise_if_transcription_blocked(data, text, response)
           words = segments.flat_map { |segment| segment['words'] }
           RubyLLM::Transcription.new(text:, model:, segments: segments.empty? ? nil : segments,
                                      words: words.empty? ? nil : words, **extract_usage(data))

data/lib/ruby_llm/providers/vertexai.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'stringio'
-
 module RubyLLM
   module Providers
     # Google Vertex AI implementation
@@ -28,6 +26,18 @@ module RubyLLM
           VertexAI::Capabilities
         end
 
+        def between_tools_off?(model_id) # :nodoc:
+          Providers::Anthropic.between_tools_off?(model_id)
+        end
+
+        def thinking_off_control(model_id) # :nodoc:
+          { enabled: false } if between_tools_off?(model_id)
+        end
+
+        def cache_write_input_multiplier(model_id, ttl) # :nodoc:
+          Providers::Anthropic.cache_write_input_multiplier(model_id, ttl) if model_id.to_s.start_with?('claude')
+        end
+
         def models_dev_alias(...)
           VertexAI::Models.models_dev_alias(...)
         end
@@ -68,11 +78,6 @@ module RubyLLM
         "#{location_path}/publishers/#{publisher}/models/#{model}"
       end
 
-      def initialize(config)
-        super
-        @authorizer = nil
-      end
-
       def batch_protocol
         batch_protocol_for_name(:gemini)
       end
@@ -111,6 +116,13 @@ module RubyLLM
         api_base_for(@config.vertexai_location)
       end
 
+      # Uploads are objects in the configured bucket, readable with any
+      # credentials the bucket admits.
+      def account_identity
+        bucket = @config.vertexai_batch_gcs_uri
+        account_digest(bucket) if bucket
+      end
+
       def api_base_for(location)
         return @config.vertexai_api_base if @config.vertexai_api_base
 
@@ -128,23 +140,26 @@ module RubyLLM
 
       def ranking_connection # :nodoc:
         base = @config.vertexai_ranking_api_base || 'https://discoveryengine.googleapis.com/v1'
-        @ranking_connection ||= Transport::Connection.new(self, @config, api_base: base).tap do |connection|
-          connection.connection.headers['X-Goog-User-Project'] = @config.vertexai_project_id
-        end
+        @ranking_connection ||= Transport::Connection.new(
+          self, @config, api_base: base, headers: { 'X-Goog-User-Project' => @config.vertexai_project_id }
+        )
       end
 
       # The rescue can't name Google::Auth::AuthorizationError directly:
       # when googleauth is missing, evaluating the constant would replace
       # the helpful install error with a NameError.
       def headers
-        initialize_authorizer unless @authorizer
-        @authorizer.apply({})
+        Credentials.for(@config).headers
       rescue StandardError => e
         raise unless defined?(Google::Auth::AuthorizationError) && e.is_a?(Google::Auth::AuthorizationError)
 
         raise UnauthorizedError, "Invalid Google Cloud credentials for Vertex AI: #{e.message}"
       end
 
+      def google_credentials # :nodoc:
+        Credentials.for(@config).authorizer
+      end
+
       class << self
         def configuration_options
           %i[
@@ -172,22 +187,6 @@ module RubyLLM
         end
       end
 
-      def initialize_authorizer
-        require 'googleauth'
-        @authorizer =
-          if @config.vertexai_service_account_key
-            ::Google::Auth::ServiceAccountCredentials.make_creds(
-              json_key_io: StringIO.new(@config.vertexai_service_account_key),
-              scope: SCOPES
-            )
-          else
-            ::Google::Auth.get_application_default(SCOPES)
-          end
-      rescue LoadError
-        raise Error,
-              'The googleauth gem ~> 1.15 is required for Vertex AI. Please add it to your Gemfile: gem "googleauth"'
-      end
-
       def batch_protocol_name_for(model)
         case model
         when %r{/} then :chat_completions

data/lib/ruby_llm/providers/xai/chat.rb

@@ -10,6 +10,12 @@ module RubyLLM
           role.to_s
         end
 
+        def supported_attachment?(attachment)
+          Protocols::ChatCompletions::Media.supported_attachment?(
+            attachment, document_attachments: :none, audio_attachments: false
+          )
+        end
+
         def format_content(content, attachments = [])
           Protocols::ChatCompletions::Media.format_content(
             content,

data/lib/ruby_llm/providers/xai/images.rb

@@ -3,10 +3,9 @@
 module RubyLLM
   module Providers
     class XAI
-      # Image generation and editing for the xAI API. Generation rejects the
-      # size parameter. Editing takes JSON image references (URL, data URI,
-      # or file id) instead of multipart uploads, up to three per request,
-      # and has no mask support.
+      # Image generation and editing for the xAI API. Editing takes JSON
+      # image references (URL, data URI, or file id) instead of multipart
+      # uploads, up to three per request, and has no mask support.
       module Images
         module_function
 
@@ -15,21 +14,21 @@ module RubyLLM
         end
 
         def render_image_payload(prompt, model:, size:, count: nil, with: nil, mask: nil, provider_options: {})
-          return render_edit_payload(prompt, model:, count:, with:, provider_options:) if editing?(with, mask)
+          return render_edit_payload(prompt, model:, size:, count:, with:, provider_options:) if editing?(with, mask)
 
-          RubyLLM.logger.debug { "Ignoring size #{size}. xAI image generation does not support a size parameter." }
-          payload = { model: model, prompt: prompt }
+          payload = { model: model, prompt: prompt, size: size }.compact
           payload[:n] = count if count
 
           payload.merge(provider_options)
         end
 
-        def render_edit_payload(prompt, model:, with:, provider_options:, count: nil)
+        def render_edit_payload(prompt, model:, with:, provider_options:, size: nil, count: nil)
           payload = {
             model: model,
             prompt: prompt,
-            images: image_references(with)
-          }
+            images: image_references(with),
+            size: size
+          }.compact
           payload[:n] = count if count
 
           payload.merge(provider_options)

data/lib/ruby_llm/providers/xai/responses.rb

@@ -27,24 +27,26 @@ module RubyLLM
           mcp: Protocols::Responses::SERVER_TOOL_ALIASES.fetch(:mcp)
         }.freeze
 
-        SERVER_TOOL_USAGE_COUNTERS = %w[num_sources_used num_server_side_tools_used].freeze
+        SERVER_TOOL_USAGE_NAMES = { 'code_interpreter' => 'code_execution' }.freeze
 
         def server_tool_aliases
           SERVER_TOOL_ALIASES
         end
 
         def parse_usage(usage)
-          super.merge(
-            server_tool_use: server_side_tool_usage(usage),
-            reported_cost: reported_cost(usage)
-          )
+          super.merge(reported_cost: reported_cost(usage))
         end
 
         private
 
-        def server_side_tool_usage(usage)
-          counters = usage.slice(*SERVER_TOOL_USAGE_COUNTERS).reject { |_, count| count.to_i.zero? }
-          counters.empty? ? nil : counters
+        # Each *_calls detail counts one tool; the totals and the X Search
+        # fetch counts beside them do not.
+        def parse_server_tool_use(response)
+          details = response.dig('usage', 'server_side_tool_usage_details').to_h
+          details.filter_map do |counter, count|
+            tool = counter[/\A(.+)_calls\z/, 1]
+            ["#{SERVER_TOOL_USAGE_NAMES.fetch(tool, tool)}_requests", count] if tool
+          end.to_h
         end
       end
     end

data/lib/ruby_llm/providers/xai/videos.rb

@@ -5,6 +5,8 @@ module RubyLLM
     class XAI
       # Grok Imagine generation, editing, and extension jobs.
       module Videos
+        include XAI::ReportedCost
+
         def video_url
           'videos/generations'
         end
@@ -32,11 +34,11 @@ module RubyLLM
           { model: model, prompt: prompt, video: video_reference(video) }.merge(provider_options)
         end
 
-        def parse_video_job(response, model:)
+        def parse_video_job(response, model:, **request)
           id = response.body['request_id']
           raise Error.new('xAI did not return a video request id', response:) unless id
 
-          VideoJob.new(id: id, protocol: self, model: model, raw: response.body)
+          VideoJob.new(id: id, protocol: self, model: model, raw: response.body, **request)
         end
 
         def video_job_url(job)
@@ -45,11 +47,12 @@ module RubyLLM
 
         def parse_video_job_status(response, job:) # rubocop:disable Lint/UnusedMethodArgument
           body = response.body
-          case body['status']
-          when 'done' then { status: :completed, raw: body }
-          when 'failed', 'expired' then { status: :failed, raw: body, error: body['error'] || body['status'] }
-          else { status: :pending, raw: body }
-          end
+          state = case body['status']
+                  when 'done' then { status: :completed }
+                  when 'failed', 'expired' then { status: :failed, error: body['error'] || body['status'] }
+                  else { status: :pending }
+                  end
+          state.merge({ raw: body, reported_cost: reported_cost(body['usage'] || {}) }.compact)
         end
 
         def download_video(job)
@@ -77,9 +80,8 @@ module RubyLLM
 
         def video_reference(attachment)
           return { file_id: attachment.provider_file_id } if attachment.provider_file?
-          return { url: attachment.source.to_s } if attachment.url?
 
-          { url: attachment.for_llm }
+          { url: attachment.url_or_data_uri }
         end
       end
     end

data/lib/ruby_llm/providers/xai.rb

@@ -18,6 +18,10 @@ module RubyLLM
         }
       end
 
+      def account_identity
+        account_digest(api_base, @config.xai_api_key)
+      end
+
       class << self
         def capabilities
           XAI::Capabilities

data/lib/ruby_llm/railtie.rb

@@ -15,16 +15,27 @@ if defined?(Rails::Railtie)
 
       initializer 'ruby_llm.active_record' do
         ActiveSupport.on_load :active_record do
+          require 'ruby_llm/active_record/record'
           require 'ruby_llm/active_record/payload_helpers'
           require 'ruby_llm/active_record/model'
           require 'ruby_llm/active_record/tool_call'
           require 'ruby_llm/active_record/usage'
           require 'ruby_llm/active_record/batch'
+          require 'ruby_llm/active_record/mcp_credential'
+          require 'ruby_llm/active_record/provider_file'
           require 'ruby_llm/active_record/chat_methods'
           require 'ruby_llm/active_record/message_methods'
 
           require 'ruby_llm/active_record/acts_as'
           ::ActiveRecord::Base.include RubyLLM::ActiveRecord::ActsAs
+          RubyLLM.config.mcp_credential_store ||= RubyLLM::ActiveRecord::MCPCredential
+          RubyLLM::Accounting::Usage.ledger ||= RubyLLM::ActiveRecord::Usage
+        end
+      end
+
+      initializer 'ruby_llm.active_storage' do
+        ActiveSupport.on_load :active_storage_blob do
+          after_destroy { RubyLLM::ActiveRecord::ProviderFile.forget_blob(self) }
         end
       end
 

data/lib/ruby_llm/request_shape/part.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class RequestShape
+    # A Part describes one piece of a turn by its kind and size, never by
+    # its content.
+    #
+    #   part.kind    # => :tool_call
+    #   part.name    # => "find_tasks"
+    #   part.size    # => 42
+    #   part.unit    # => :chars
+    #   part.signed? # => true
+    #   part.to_s    # => "call find_tasks (args 42 chars), signed"
+    #
+    class Part
+      include Support::Inspectable
+
+      TEXT_KINDS = %i[text thinking].freeze
+      private_constant :TEXT_KINDS
+
+      # The kind of piece: +:text+, +:thinking+, +:image+, +:audio+,
+      # +:video+, +:document+, +:tool_call+, +:tool_result+, or +:other+
+      # for a piece RubyLLM does not classify, such as a provider tool step.
+      attr_reader :kind
+
+      # The size of the piece as the request sends it, in #unit: the
+      # characters of text, thinking, tool call arguments, and a tool
+      # result's text, or of its JSON when it is structured data, and the
+      # bytes of inline media. Media inside a tool result follows it as
+      # parts of its own. Returns +nil+ when there is nothing to measure,
+      # such as media sent by URL or thinking the provider encrypted.
+      attr_reader :size
+
+      # The unit of #size: +:chars+ or +:bytes+, or +nil+ without a size.
+      attr_reader :unit
+
+      # The tool's name for a tool call, and for a tool result the name of
+      # the call it answers, which is +nil+ when no call in the request
+      # matches it. For an +:other+ piece, the provider's name for it.
+      attr_reader :name
+
+      # Where media comes from: +:inline+ for bytes in the request, +:url+
+      # for a link the provider fetches, or +:file+ for a file stored with
+      # the provider. Returns +nil+ for pieces that are not media.
+      attr_reader :source
+
+      # The MIME type of media, as the request gives it or as its format
+      # implies, or +nil+.
+      attr_reader :mime_type
+
+      # Creates a part. Every attribute but +kind+ is optional. A +size+
+      # counts characters unless +unit+ says +:bytes+; pass +signed: true+
+      # when the piece carries a thinking signature.
+      def initialize(kind:, size: nil, unit: nil, name: nil, source: nil, mime_type: nil, signed: false)
+        @kind = kind
+        @size = size
+        @unit = size && (unit || :chars)
+        @name = name
+        @source = source
+        @mime_type = mime_type
+        @signed = signed
+      end
+
+      # Returns whether the piece carries a thinking signature, the token a
+      # provider issues to verify replayed thinking or tool calls.
+      def signed?
+        @signed
+      end
+
+      # Returns the part in words, with its size and unit:
+      #
+      #   text (13 chars)
+      #   image/png (34512 bytes)
+      #   document (url)
+      #   result find_tasks (6859 chars)
+      #   thinking (no text), signed
+      #
+      def to_s
+        signed? ? "#{description}, signed" : description
+      end
+
+      # Returns the part as a Hash, with its size under its unit, omitting
+      # attributes it does not have.
+      def to_h
+        hash = { kind: kind, name: name }
+        hash[unit] = size if size
+        hash.merge(source: source, mime_type: mime_type, signed: signed? || nil).compact
+      end
+
+      def inspect_attributes # :nodoc:
+        to_h
+      end
+
+      private
+
+      def description
+        case kind
+        when :tool_call then ['call', name, size && "(args #{measured})"].compact.join(' ')
+        when :tool_result then ['result', name, size && "(#{measured})"].compact.join(' ')
+        when :other then name || 'part of no known kind'
+        else "#{mime_type || kind} (#{size ? measured : missing})"
+        end
+      end
+
+      def measured
+        noun = { chars: 'char', bytes: 'byte' }.fetch(unit, unit.to_s)
+        "#{size} #{noun}#{'s' unless size == 1}"
+      end
+
+      def missing
+        return source.to_s if source && source != :inline
+
+        TEXT_KINDS.include?(kind) ? 'no text' : 'no data'
+      end
+    end
+  end
+end

data/lib/ruby_llm/request_shape/problem.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class RequestShape
+    # A Problem is something in a request that providers are known to
+    # reject, found by the protocol that rendered it: a part with no data, a
+    # tool round whose calls and results do not pair up, a step that lacks
+    # the signature the provider requires, or roles out of order.
+    #
+    #   problem.kind    # => :part_without_data
+    #   problem.turn    # => 3
+    #   problem.part    # => 0
+    #   problem.to_s    # => "problem at #3, part 0: thinking part carries no data"
+    #
+    class Problem
+      include Support::Inspectable
+
+      # What is wrong: +:part_without_data+, +:empty_turn+,
+      # +:unpaired_round+, +:unmatched_result+, +:unsigned_call+,
+      # +:unsigned_thinking+, or +:role_order+.
+      attr_reader :kind
+
+      # The index of the turn the problem is in, or +nil+.
+      attr_reader :turn
+
+      # The position of the part in the turn's parts, or +nil+ when the
+      # problem concerns the whole turn.
+      attr_reader :part
+
+      # The id of the call an unmatched tool result names, the only id a
+      # shape shows, or +nil+.
+      attr_reader :call_id
+
+      # The problem in words.
+      attr_reader :message
+
+      # Creates a problem of +kind+ described by +message+.
+      def initialize(kind:, message:, turn: nil, part: nil, call_id: nil)
+        @kind = kind
+        @message = message
+        @turn = turn
+        @part = part
+        @call_id = call_id
+      end
+
+      # Returns the problem as one line, with where it is.
+      def to_s
+        location = ["##{turn}", part && "part #{part}"].compact.join(', ') if turn
+        line = location ? "problem at #{location}: #{message}" : "problem: #{message}"
+        call_id ? "#{line} (call id #{call_id})" : line
+      end
+
+      # Returns the problem as a Hash, omitting attributes it does not have.
+      def to_h
+        { kind: kind, turn: turn, part: part, call_id: call_id, message: message }.compact
+      end
+
+      def inspect_attributes # :nodoc:
+        to_h
+      end
+    end
+  end
+end

data/lib/ruby_llm/request_shape/tool_round.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class RequestShape
+    # A ToolRound describes a model turn that called tools and the results
+    # the request sends back before the next model turn: how many of each,
+    # and whether they pair up the way the provider matches them.
+    #
+    #   round.turn    # => 1
+    #   round.calls   # => 2
+    #   round.results # => 1
+    #   round.paired? # => false
+    #   round.to_s    # => "tool round at #1: 2 calls, 1 result, not paired"
+    #
+    class ToolRound
+      include Support::Inspectable
+
+      # The index of the turn that made the calls.
+      attr_reader :turn
+
+      # The number of tool calls in the round.
+      attr_reader :calls
+
+      # The number of tool results sent back for the round.
+      attr_reader :results
+
+      # Creates a round at +turn+ with the number of +calls+ and +results+,
+      # and whether they are +paired+.
+      def initialize(turn:, calls:, results:, paired:)
+        @turn = turn
+        @calls = calls
+        @results = results
+        @paired = paired
+      end
+
+      # Returns whether every call has its result, matched the way the
+      # provider matches them: by call id, or by position and tool name.
+      def paired?
+        @paired
+      end
+
+      # Returns the round in words.
+      def to_s
+        "tool round at ##{turn}: #{counted(calls, 'call')}, #{counted(results, 'result')}, " \
+          "#{paired? ? 'paired' : 'not paired'}"
+      end
+
+      # Returns the round as a Hash with its turn, counts, and pairing.
+      def to_h
+        { turn: turn, calls: calls, results: results, paired: paired? }
+      end
+
+      def inspect_attributes # :nodoc:
+        to_h
+      end
+
+      private
+
+      def counted(count, noun)
+        "#{count} #{noun}#{'s' unless count == 1}"
+      end
+    end
+  end
+end

data/lib/ruby_llm/request_shape/turn.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class RequestShape
+    # A Turn describes one entry of a request's conversation: a message, or
+    # one item where the provider sends a model's reasoning and tool calls as
+    # items of their own.
+    #
+    #   turn = error.request_shape.turns.last
+    #   turn.index # => 4
+    #   turn.role  # => "user"
+    #   turn.to_s  # => "#4 user: text (31 chars)"
+    #
+    class Turn
+      include Support::Inspectable
+
+      # The turn's 0-indexed position in the request, the position a
+      # provider's error message counts from.
+      attr_reader :index
+
+      # The turn's role as the payload names it, such as <tt>"model"</tt>,
+      # or for an entry that names no role, its type, such as
+      # <tt>"function_call"</tt>. Returns +nil+ when the entry names neither.
+      attr_reader :role
+
+      # The Part objects of the turn, in order.
+      attr_reader :parts
+
+      # Creates a turn at +index+ with +role+ and +parts+.
+      def initialize(index:, role:, parts: [])
+        @index = index
+        @role = role
+        @parts = parts
+      end
+
+      # Returns the turn as one line: its index, its role, and its parts.
+      #
+      #   turn.to_s # => "#3 model: thinking (11 chars), text (13 chars), signed"
+      #
+      def to_s
+        "##{[index, role].compact.join(' ')}: #{parts.empty? ? 'no parts' : parts.join(', ')}"
+      end
+
+      # Returns the turn as a Hash with its index, role, and parts.
+      def to_h
+        { index: index, role: role, parts: parts.map(&:to_h) }
+      end
+
+      def inspect_attributes # :nodoc:
+        { index: index, role: role, parts: parts.join(', ') }
+      end
+    end
+  end
+end