ruby_llm 2.1.0 → 2.2.0

data/lib/ruby_llm/providers/openrouter.rb

@@ -4,6 +4,8 @@ module RubyLLM
   module Providers
     # OpenRouter API integration.
     class OpenRouter < Provider
+      BAD_GATEWAY = 502
+
       # OpenRouter's dialect of the Chat Completions API.
       class ChatCompletions < Protocols::ChatCompletions
         include OpenRouter::Chat
@@ -30,22 +32,27 @@ module RubyLLM
         end
       end
 
+      # OpenRouter's dialect of the System One API for decision models such as Jev and Clef.
+      class SystemOne < Protocols::SystemOne
+        include OpenRouter::Judgments
+      end
+
       protocol :chat_completions, ChatCompletions, batches: Protocols::OpenRouter::Batches
       protocol :responses, Protocols::OpenRouter::Responses
       protocol :files, Protocols::OpenRouter::Files
+      protocol :system_one, SystemOne
 
-      def resolve_protocol(name, model, **request)
-        return fetch_protocol(:chat_completions) if !name && request[:operation]
-
+      def resolve_protocol(name, model, operation: nil, **options)
+        name ||= (operation == :judge ? :system_one : :chat_completions) if operation
         super
       end
 
       def api_base
-        @config.openrouter_api_base || 'https://openrouter.ai/api/v1'
+        configured_api_base(:openrouter_api_base, 'https://openrouter.ai/api/v1', endpoints: Protocols::ChatCompletions::ENDPOINT_PATHS)
       end
 
       def batch_api_base
-        "#{api_base.sub(%r{/v1/?\z}, '')}/beta/batches"
+        "#{api_base}/batches"
       end
 
       def headers
@@ -77,7 +84,27 @@ module RubyLLM
         end
       end
 
+      # OpenRouter answers 200 when an upstream provider fails after routing,
+      # with an error object or an empty body. A stream has no body here.
+      def error_status(response)
+        return if response.request.stream_response?
+
+        body = response.body.to_s
+        return BAD_GATEWAY if body.strip.empty?
+        return unless body.include?('"error"')
+
+        error = parse_error_body(response).then { |parsed| parsed['error'] if parsed.is_a?(Hash) }
+        return unless error.is_a?(Hash)
+
+        code = error['code']
+        code.is_a?(Integer) && code >= 400 ? code : BAD_GATEWAY
+      end
+
       class << self
+        def models_dev_provider_ids # :nodoc:
+          %w[openrouter]
+        end
+
         def configuration_options
           %i[openrouter_api_key openrouter_api_base openrouter_app_url openrouter_app_name]
         end

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

@@ -7,7 +7,7 @@ module RubyLLM
       module Chat
         module_function
 
-        def format_role(role)
+        def render_role(role)
           role.to_s
         end
 
@@ -15,8 +15,8 @@ module RubyLLM
           Perplexity::Media.supported_attachment?(attachment)
         end
 
-        def format_content(content, attachments = [])
-          Perplexity::Media.format_content(content, attachments)
+        def render_content(content, attachments = [])
+          Perplexity::Media.render_content(content, attachments)
         end
       end
     end

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

@@ -15,7 +15,7 @@ module RubyLLM
         def parse_embedding_response(response, model:, text:)
           data = response.body
           input_tokens = data.dig('usage', 'prompt_tokens')
-          vectors = Array(data['data']).map { |vector| decode_embedding(vector['embedding']) }
+          vectors = order_embedding_rows(Array(data['data'])).map { |vector| decode_embedding(vector['embedding']) }
           vectors = vectors.first if vectors.length == 1 && !text.is_a?(Array)
 
           Embedding.new(vectors:, model:, input_tokens:)

data/lib/ruby_llm/providers/perplexity/media.rb

@@ -11,22 +11,22 @@ module RubyLLM
           %i[image pdf document text].include?(attachment.type)
         end
 
-        def format_content(content, attachments = [])
-          Protocols::ChatCompletions::Media.format_parts(content, attachments) do |attachment|
+        def render_content(content, attachments = [])
+          Protocols::ChatCompletions::Media.render_parts(content, attachments) do |attachment|
             raise UnsupportedAttachmentError, attachment.mime_type unless supported_attachment?(attachment)
 
             case attachment.type
             when :image
-              Protocols::ChatCompletions::Media.format_image(attachment)
+              Protocols::ChatCompletions::Media.render_image(attachment)
             when :pdf, :document
-              format_document(attachment)
+              render_document(attachment)
             when :text
-              Protocols::ChatCompletions::Media.format_text_file(attachment)
+              Protocols::ChatCompletions::Media.render_text_file(attachment)
             end
           end
         end
 
-        def format_document(attachment)
+        def render_document(attachment)
           {
             type: 'file_url',
             file_url: {

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,