ruby_llm 2.1.1 → 2.2.0

data/lib/ruby_llm/providers/perplexity.rb

@@ -14,10 +14,11 @@ module RubyLLM
       protocol :chat_completions, ChatCompletions
       protocol :router_chat_completions, Protocols::Perplexity::Router
       protocol :files, Protocols::Perplexity::Files
-      protocol :agent_responses, Protocols::Perplexity::Agent
+      protocol :agent_responses, Protocols::Perplexity::Agent, batches: Protocols::Perplexity::Batches
 
       def api_base
-        @config.perplexity_api_base || 'https://api.perplexity.ai'
+        configured_api_base(:perplexity_api_base, 'https://api.perplexity.ai',
+                            endpoints: %r{/(?:chat/completions|v1/agent|v1/embeddings)\z})
       end
 
       # Chat runs on the Agent API. Embeddings and the model listing stay on
@@ -58,6 +59,10 @@ module RubyLLM
       end
 
       class << self
+        def models_dev_provider_ids # :nodoc:
+          %w[perplexity perplexity-agent]
+        end
+
         def configuration_options
           %i[perplexity_api_key perplexity_api_base]
         end
@@ -66,6 +71,12 @@ module RubyLLM
           %i[perplexity_api_key]
         end
       end
+
+      private
+
+      def batch_protocol
+        batch_protocol_for_name(:agent_responses)
+      end
     end
   end
 end

data/lib/ruby_llm/providers/typesafe.rb

@@ -7,7 +7,7 @@ module RubyLLM
       protocol :system_one, Protocols::SystemOne
 
       def api_base
-        @config.typesafe_api_base || 'https://api.typesafe.ai'
+        configured_api_base(:typesafe_api_base, 'https://api.typesafe.ai', endpoints: %r{/v1/systemone\z})
       end
 
       def headers

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

@@ -25,7 +25,11 @@ module RubyLLM
           raise Error, "#{@provider.name} doesn't support token counting for Claude models"
         end
 
-        def supports_provider_file_references?
+        def thinking_block_binding?
+          false
+        end
+
+        def provider_file_references?
           false
         end
       end

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

@@ -9,7 +9,13 @@ module RubyLLM
       # Google credentials shared by every Vertex AI provider in the process.
       # googleauth keeps the access token on the credentials object and
       # refreshes it a minute before it expires, so sharing the object shares
-      # the token.
+      # the token. With a token timeout, token requests go through the
+      # middleware and adapter of Faraday's default connection, as googleauth's
+      # own would, with that timeout and its proxy. Faraday 1 drops a
+      # builder's adapter when it duplicates a builder without middleware, so
+      # the builder is shared, not duplicated. The connection is built for
+      # each token fetch, so it takes the proxy the default connection would
+      # use at that moment, from its settings or the environment.
       class Credentials # :nodoc:
         CACHE = Support::ProcessCache.new
 
@@ -17,7 +23,8 @@ module RubyLLM
 
         def self.for(config)
           key = config.vertexai_service_account_key
-          CACHE.fetch([source(key), SCOPES]) { new(key) }
+          timeout = config.vertexai_token_timeout
+          CACHE.fetch([source(key), SCOPES, timeout]) { new(key, token_timeout: timeout) }
         end
 
         def self.cache
@@ -31,7 +38,8 @@ module RubyLLM
         end
         private_class_method :source
 
-        def initialize(service_account_key)
+        def initialize(service_account_key, token_timeout: nil)
+          @token_timeout = token_timeout
           @authorizer = build(service_account_key)
           @lock = Mutex.new
         end
@@ -44,6 +52,22 @@ module RubyLLM
         private
 
         def build(service_account_key)
+          authorizer = google_credentials(service_account_key)
+          return authorizer unless @token_timeout && authorizer.respond_to?(:configure_connection)
+
+          authorizer.configure_connection(connection_builder: method(:token_connection))
+          authorizer
+        end
+
+        def token_connection
+          default = Faraday.default_connection
+          connection = Faraday.new(builder: default.builder, headers: default.headers, params: default.params,
+                                   ssl: default.ssl, request: default.options.merge(timeout: @token_timeout))
+          connection.proxy = default.proxy_for_request(@authorizer.token_credential_uri.to_s)
+          connection
+        end
+
+        def google_credentials(service_account_key)
           require 'googleauth'
           if service_account_key
             ::Google::Auth::ServiceAccountCredentials.make_creds(

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

@@ -23,7 +23,7 @@ module RubyLLM
           raise ArgumentError, "#{model} takes task instructions and titles in the text" if task_type || title
 
           payload = {
-            content: { parts: Protocols::Gemini::Media.format_content(text.is_a?(Array) ? text.first : text, with) },
+            content: { parts: Protocols::Gemini::Media.render_content(text.is_a?(Array) ? text.first : text, with) },
             outputDimensionality: dimensions
           }.compact
           Support::Utils.deep_merge(payload, provider_options)

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

@@ -11,12 +11,11 @@ module RubyLLM
           "#{@provider.model_path(model)}:predict"
         end
 
-        def supports_embedding_media?
+        def embedding_media?
           false
         end
 
-        # rubocop:disable-next Lint/UnusedMethodArgument
-        def render_embedding_payload(text, model:, dimensions:, task_type: nil, title: nil, provider_options: {})
+        def render_embedding_payload(text, dimensions:, task_type: nil, title: nil, provider_options: {}, **)
           instances = [text].flatten.map do |t|
             { content: t.to_s, task_type: task_type, title: title }.compact
           end

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

@@ -48,7 +48,7 @@ module RubyLLM
           @provider.model_path(model_id)
         end
 
-        def images_url(with: nil, mask: nil) # rubocop:disable Lint/UnusedMethodArgument
+        def images_url(**)
           id = model_id(@model)
 
           "#{@provider.model_path(id)}:#{image_endpoint_action(id)}"

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

@@ -10,6 +10,7 @@ module RubyLLM
         include Providers::Mistral::Embeddings
         include Providers::Mistral::Media
         include Providers::Mistral::Models
+        include Providers::Mistral::OCR
 
         # The Mistral model families Vertex AI serves directly. Shared by the
         # registry (which models to list) and protocol_for (where to route them).
@@ -22,6 +23,10 @@ module RubyLLM
         def stream_url
           "#{@provider.model_path(@model.id, publisher: 'mistralai')}:streamRawPredict"
         end
+
+        def ocr_url
+          completion_url
+        end
       end
     end
   end

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

@@ -29,6 +29,10 @@ module RubyLLM
           text-multilingual-embedding-002
         ].freeze
 
+        # Cloud Text-to-Speech voice models, which no publisher catalog lists.
+        # Each id is the model part of its voice names: en-US-Chirp3-HD-Charon.
+        TEXT_TO_SPEECH_MODELS = { 'Chirp3-HD' => 'Chirp 3: HD' }.freeze
+
         # Every publisher with models Vertex AI serves as a service. The rest
         # of the Model Garden is deploy-it-yourself and not callable directly.
         PUBLISHERS = %w[google anthropic mistralai meta deepseek-ai qwen openai moonshotai zai-org].freeze
@@ -57,7 +61,7 @@ module RubyLLM
           models = fetched.uniq(&:id)
           log_catalog(counts, models)
 
-          models + build_known_models(models.map(&:id))
+          models + build_known_models(models.map(&:id)) + text_to_speech_models
         end
 
         private
@@ -77,7 +81,7 @@ module RubyLLM
         def connection_for(location)
           return @connection if location == configured_location
 
-          Transport::Connection.new(@provider, @config, api_base: @provider.api_base_for(location))
+          @provider.signed_connection(@provider.api_base_for(location))
         end
 
         def log_catalog(counts, models)
@@ -178,6 +182,24 @@ module RubyLLM
           end
         end
 
+        def text_to_speech_models
+          TEXT_TO_SPEECH_MODELS.map do |model_id, name|
+            Model.new(
+              id: model_id,
+              name:,
+              provider: @provider.slug,
+              family: 'chirp',
+              created_at: nil,
+              context_window: nil,
+              max_output_tokens: nil,
+              modalities: { input: %w[text], output: %w[audio] },
+              capabilities: %w[speech_generation],
+              pricing: nil,
+              metadata: { source: 'cloud_text_to_speech' }
+            )
+          end
+        end
+
         def build_model_from_api_data(model_data, model_id)
           Model.new(
             id: model_id,

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

@@ -23,7 +23,7 @@ module RubyLLM
         def render_transcription_payload(attachment, language:, speaker_names:, provider_options:, prompt:, **)
           config = { languageCodes: language && Array(language), customVocabulary: prompt && Array(prompt),
                      diarization: speaker_names && true }.compact
-          payload = { contents: [{ role: 'user', parts: [format_audio_part(attachment)] }],
+          payload = { contents: [{ role: 'user', parts: [render_audio_part(attachment)] }],
                       generationConfig: { audioTranscriptionConfig: config } }
           Support::Utils.deep_merge(payload, provider_options)
         end
@@ -38,7 +38,7 @@ module RubyLLM
           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))
+                                     words: words.empty? ? nil : words, **parse_usage(data))
         end
 
         def parse_transcription_segment(part)

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

@@ -10,7 +10,7 @@ module RubyLLM
         end
 
         def video_job_url(job)
-          "#{job.id.split('/operations/').first}:fetchPredictOperation"
+          "#{video_operation_name(job).split('/operations/').first}:fetchPredictOperation"
         end
 
         def refresh_video_job(job)

data/lib/ruby_llm/providers/vertexai.rb

@@ -4,6 +4,8 @@ module RubyLLM
   module Providers
     # Google Vertex AI implementation
     class VertexAI < Provider
+      include Protocols::Gemini::RetryInfo
+
       protocol :gemini, VertexAI::Gemini, batches: VertexAI::Gemini::Batches
       protocol :anthropic, VertexAI::Anthropic, batches: VertexAI::Anthropic::Batches
       protocol :mistral, VertexAI::Mistral
@@ -13,6 +15,7 @@ module RubyLLM
       protocol :transcription, VertexAI::Transcription
       protocol :live_transcription, VertexAI::LiveTranscription
       protocol :ranking, Protocols::VertexAI::Ranking
+      protocol :text_to_speech, Protocols::VertexAI::TextToSpeech
       protocol :research, Protocols::VertexAI::Research
       protocol :files, Protocols::VertexAI::Files
 
@@ -47,6 +50,19 @@ module RubyLLM
         def models_dev_model_id(id)
           id&.split('@')&.first
         end
+
+        def open_telemetry_name # :nodoc:
+          'gcp.vertex_ai'
+        end
+
+        def models_dev_provider_ids # :nodoc:
+          %w[google-vertex]
+        end
+      end
+
+      def initialize(config) # :nodoc:
+        super
+        @connection = signed_connection(api_base)
       end
 
       # Vertex AI hosts models from several publishers, each speaking its
@@ -55,8 +71,8 @@ module RubyLLM
       def protocol_for(model, operation: nil, **)
         return protocols[:ranking] if operation == :rerank
 
-        transcription = transcription_protocol_for(model.id) if operation == :transcribe
-        return transcription if transcription
+        audio = audio_protocol_for(model.id, operation)
+        return audio if audio
 
         if operation == :embed && %w[gemini-embedding-2 gemini-embedding-2-preview].include?(model.id)
           return protocols[:embed_content]
@@ -124,12 +140,15 @@ module RubyLLM
       end
 
       def api_base_for(location)
-        return @config.vertexai_api_base if @config.vertexai_api_base
+        if @config.vertexai_api_base
+          return configured_api_base(:vertexai_api_base, example: 'https://LOCATION-aiplatform.googleapis.com/v1beta1',
+                                                         endpoints: %r{/projects/.*\z})
+        end
 
-        if location.to_s == 'global'
-          'https://aiplatform.googleapis.com/v1beta1'
-        else
-          "https://#{location}-aiplatform.googleapis.com/v1beta1"
+        case location.to_s
+        when 'global' then 'https://aiplatform.googleapis.com/v1beta1'
+        when 'eu', 'us' then "https://aiplatform.#{location}.rep.googleapis.com/v1beta1"
+        else "https://#{location}-aiplatform.googleapis.com/v1beta1"
         end
       end
 
@@ -140,11 +159,25 @@ 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, headers: { 'X-Goog-User-Project' => @config.vertexai_project_id }
+        @ranking_connection ||= signed_connection(
+          base, headers: { 'X-Goog-User-Project' => @config.vertexai_project_id }
+        )
+      end
+
+      # Cloud Text-to-Speech answers at the multi-region or region named by
+      # vertexai_location, never at the global endpoint unless asked for it.
+      def text_to_speech_connection # :nodoc:
+        @text_to_speech_connection ||= signed_connection(
+          text_to_speech_api_base, headers: { 'X-Goog-User-Project' => @config.vertexai_project_id }
         )
       end
 
+      # Signs each attempt as it is sent, so a retry never replays an access
+      # token that expired while the previous attempt waited.
+      def signed_connection(base_url, headers: {}) # :nodoc:
+        Transport::Connection.new(self, @config, api_base: base_url, headers:, signer: ->(_env) { self.headers })
+      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.
@@ -170,6 +203,7 @@ module RubyLLM
             vertexai_batch_gcs_uri
             vertexai_ranking_api_base
             vertexai_ranking_config
+            vertexai_token_timeout
           ]
         end
 
@@ -180,6 +214,19 @@ module RubyLLM
 
       private
 
+      def text_to_speech_api_base
+        location = @config.vertexai_location.to_s
+        host = location == 'global' ? 'texttospeech.googleapis.com' : "#{location}-texttospeech.googleapis.com"
+        "https://#{host}/v1"
+      end
+
+      def audio_protocol_for(id, operation)
+        case operation
+        when :transcribe then transcription_protocol_for(id)
+        when :speak then protocols[:text_to_speech] if Protocols::VertexAI::TextToSpeech::MODELS.include?(id)
+        end
+      end
+
       def transcription_protocol_for(id)
         case id
         when 'gemini-3.5-transcribe-preview' then protocols[:transcription]

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

@@ -6,7 +6,7 @@ module RubyLLM
       # Chat implementation for xAI
       # https://docs.x.ai/docs/api-reference#chat-completions
       module Chat
-        def format_role(role)
+        def render_role(role)
           role.to_s
         end
 
@@ -16,8 +16,8 @@ module RubyLLM
           )
         end
 
-        def format_content(content, attachments = [])
-          Protocols::ChatCompletions::Media.format_content(
+        def render_content(content, attachments = [])
+          Protocols::ChatCompletions::Media.render_content(
             content,
             attachments,
             document_attachments: :none,

data/lib/ruby_llm/providers/xai/chat_completions/batches.rb

@@ -76,13 +76,18 @@ module RubyLLM
           def parse_batch_status(raw_status, completed:)
             return :pending unless completed
 
-            raw_status == 'failed' ? :failed : :succeeded
+            case raw_status
+            when 'failed' then :failed
+            when 'cancelled' then :cancelled
+            else :succeeded
+            end
           end
 
           def xai_batch_status(state, completed:)
             return 'failed' unless state['error'].to_s.empty?
+            return 'processing' unless completed
 
-            completed ? 'completed' : 'processing'
+            state['num_cancelled'].to_i.positive? ? 'cancelled' : 'completed'
           end
 
           def completed_batch_state?(state)
@@ -96,7 +101,7 @@ module RubyLLM
                    result.dig('response', 'chat_get_completion')
 
             if body
-              [index, parse_completion_body(body, raw: body)]
+              parsed_batch_result(index, request_id, body) { parse_completion_body(body, raw: body) }
             else
               [index, nil, batch_failure(request_id, batch_error_message(result))]
             end

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

@@ -35,7 +35,7 @@ module RubyLLM
         end
 
         def image_references(sources)
-          Array(sources).filter_map do |source|
+          Support::Utils.to_safe_array(sources).filter_map do |source|
             next if blank_attachment?(source)
 
             { type: 'image_url', url: image_reference_url(source) }
@@ -43,7 +43,7 @@ module RubyLLM
         end
 
         def image_reference_url(source)
-          attachment = Attachment.new(source, config: @config)
+          attachment = source.is_a?(Attachment) ? source : Attachment.new(source, config: @config)
           return attachment.provider_file_id if attachment.provider_file?
           return attachment.source.to_s if attachment.url?
 
@@ -68,12 +68,17 @@ module RubyLLM
               data: image_data['b64_json'],
               mime_type: image_data['mime_type'] || 'image/png',
               model: model,
-              usage: index.zero? ? (data['usage'] || {}) : {}
+              usage: index.zero? ? image_usage(data) : {}
             )
           end
         end
 
-        def validate_paint_inputs!(with:, mask:) # rubocop:disable Lint/UnusedMethodArgument
+        def image_usage(data)
+          usage = data['usage'] || {}
+          usage.merge('cost' => reported_cost(usage)).compact
+        end
+
+        def validate_paint_inputs!(mask:, **)
           raise Error, 'xAI image editing does not support a mask parameter' if mask
         end
 

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

@@ -4,8 +4,8 @@ module RubyLLM
   module Providers
     class XAI
       # Models metadata for xAI list models. The list endpoint omits the
-      # model-less TTS and STT services, so those are appended under the
-      # grok-tts and grok-stt names from xAI's model catalog.
+      # TTS and STT services, so those are appended under the grok-tts and
+      # grok-stt names from xAI's model catalog.
       module Models
         module_function
 

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

@@ -33,6 +33,16 @@ module RubyLLM
           SERVER_TOOL_ALIASES
         end
 
+        # xAI answers tool_search and defer_loading with 403 for every
+        # account outside its alpha, so Chat brings its own search.
+        def tool_search?
+          false
+        end
+
+        def document_urls?
+          true
+        end
+
         def parse_usage(usage)
           super.merge(reported_cost: reported_cost(usage))
         end

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

@@ -9,11 +9,11 @@ module RubyLLM
       module Speech
         module_function
 
-        def speech_url(model:) # rubocop:disable Lint/UnusedMethodArgument
+        def speech_url(**)
           'tts'
         end
 
-        def render_speech_payload(input, model:, voice:, format:, provider_options: {}) # rubocop:disable Lint/UnusedMethodArgument
+        def render_speech_payload(input, voice:, format:, provider_options: {}, **)
           payload = {
             text: input,
             voice_id: voice,

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

@@ -4,30 +4,34 @@ module RubyLLM
   module Providers
     class XAI
       # Transcription dialect for the xAI Voice API. The /v1/stt endpoint is
-      # model-less multipart with the audio file last in the form; giving
-      # speaker names turns on diarization, which labels each word with a
-      # numeric speaker index.
+      # multipart with the audio file last in the form; requesting speaker
+      # labels turns on diarization, which labels each word with a numeric
+      # speaker index.
       module Transcription
+        # grok-stt is the registry's name for the service; the API has its own.
+        MODEL_IDS = { 'grok-stt' => 'grok-voice-transcribe-2.0' }.freeze
+
         def render_transcription_options(timestamps:, **)
           return {} if timestamps.nil? || timestamps == :word
 
           raise ArgumentError, 'xAI transcription timestamps must be word'
         end
 
+        def rejected_options(operation)
+          operation == :transcribe ? %i[format temperature prompt speaker_references named_speakers] : super
+        end
+
         module_function
 
         def transcription_url
           'stt'
         end
 
-        # rubocop:disable-next Lint/UnusedMethodArgument
-        def render_transcription_payload(file_part, model:, language:, format: nil, speaker_names: nil,
-                                         speaker_references: nil, provider_options: {}, prompt: nil,
-                                         temperature: nil)
-          payload = {}
+        def render_transcription_payload(file_part, model:, language:, speaker_names: nil, provider_options: {}, **)
+          payload = { model: MODEL_IDS.fetch(model, model) }
           payload[:language] = language if language
           payload[:diarize] = true if speaker_names
-          payload.merge(provider_options).merge(file: file_part)
+          payload.merge(provider_options.transform_keys(&:to_sym)).except(:file).merge(file: file_part)
         end
 
         def parse_transcription_response(response, model:)
@@ -38,6 +42,7 @@ module RubyLLM
             model: model,
             language: data['language'],
             duration: data['duration'],
+            audio_seconds: data['duration'],
             segments: data['channels'],
             words: data['words']
           )

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

@@ -45,7 +45,7 @@ module RubyLLM
           "videos/#{job.id}"
         end
 
-        def parse_video_job_status(response, job:) # rubocop:disable Lint/UnusedMethodArgument
+        def parse_video_job_status(response, **)
           body = response.body
           state = case body['status']
                   when 'done' then { status: :completed }

data/lib/ruby_llm/providers/xai.rb

@@ -9,7 +9,7 @@ module RubyLLM
       protocol :files, Protocols::XAI::Files
 
       def api_base
-        @config.xai_api_base || 'https://api.x.ai/v1'
+        configured_api_base(:xai_api_base, 'https://api.x.ai/v1', endpoints: Protocols::ChatCompletions::ENDPOINT_PATHS)
       end
 
       def headers
@@ -23,6 +23,14 @@ module RubyLLM
       end
 
       class << self
+        def open_telemetry_name # :nodoc:
+          'x_ai'
+        end
+
+        def models_dev_provider_ids # :nodoc:
+          %w[xai]
+        end
+
         def capabilities
           XAI::Capabilities
         end