ruby_llm 2.0.0 → 2.1.0

data/lib/ruby_llm/protocols/responses/request_shapes.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    class Responses
+      # Describes Responses API requests, including token counting and
+      # compaction, as RequestShape objects. Each input item is a turn, and a
+      # call's output answers the call by id.
+      module RequestShapes
+        def parse_request_shape(payload)
+          input = payload['input']
+          return unless input.is_a?(Array)
+
+          turns = input.each_with_index.map do |item, index|
+            item = shape_hash(item)
+            shape_turn(index, item['role'] || item['type'], shape_input_speaker(item), shape_input_item(item))
+          end
+          shape_request(turns, payload:, instructions: shape_instructions(payload['instructions']),
+                               tool_names: shape_list(payload['tools']).map { |tool| shape_tool_name(tool) },
+                               thinking_settings: shape_settings(payload['reasoning'], 'effort', 'summary'))
+        end
+
+        private
+
+        def shape_input_speaker(item)
+          case item['type']
+          when nil, 'message' then ChatCompletions::RequestShapes::SPEAKERS.fetch(item['role'], :user)
+          when /_output\z|_response\z/ then :tool
+          else :model
+          end
+        end
+
+        def shape_input_item(item)
+          case item['type']
+          when nil, 'message' then shape_input_content(item['content'])
+          when 'function_call' then [shape_tool_call(item['name'], item['arguments'], id: item['call_id'])]
+          when 'function_call_output'
+            shape_tool_result(item['output'], id: item['call_id']) { |part| shape_input_part(part) }
+          when 'reasoning' then [shape_summary(item['summary'], signed: shape_signature?(item['encrypted_content']))]
+          else [shape_other(item['type'])]
+          end
+        end
+
+        def shape_input_content(content)
+          return [shape_text(content)] if content.is_a?(String)
+
+          shape_list(content).map { |part| shape_input_part(shape_hash(part)) }
+        end
+
+        def shape_input_part(part)
+          case part['type']
+          when 'input_text', 'output_text' then shape_text(part['text'])
+          when 'input_image'
+            part.key?('file_id') ? shape_file(kind: :image) : shape_url(part['image_url'], kind: :image)
+          when 'input_file' then shape_input_file(part)
+          when 'input_audio' then shape_inline(shape_hash(part['input_audio'])['data'], kind: :audio)
+          else shape_other(part['type'])
+          end
+        end
+
+        def shape_input_file(part)
+          return shape_file(kind: :document) if part.key?('file_id')
+          return shape_url(part['file_url'], kind: :document) if part.key?('file_url')
+
+          shape_url(part['file_data'], kind: :document)
+        end
+      end
+    end
+  end
+end

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

@@ -9,6 +9,7 @@ module RubyLLM
         ERROR_STATUSES = {
           'server_error' => 500,
           'rate_limit_exceeded' => 429,
+          'too_many_requests' => 429,
           'insufficient_quota' => 429
         }.freeze
 
@@ -38,7 +39,7 @@ module RubyLLM
           when 'response.completed', 'response.incomplete'
             build_final_chunk(data)
           when 'response.failed'
-            raise Error, data.dig('response', 'error', 'message')
+            raise_failed_response(data['response'] || {})
           else
             chunk
           end
@@ -95,17 +96,32 @@ module RubyLLM
                 finish_reason: parse_finish_reason(response),
                 citations: parse_citations(response, output, nil),
                 server_tool_calls: server_tool_calls,
-                raw_content: server_tool_calls.any? ? output : nil,
-                **parse_usage(response['usage'] || {})
+                raw_content: keep_raw_output?(output, server_tool_calls) ? output : nil,
+                **parse_usage(response['usage'] || {}),
+                server_tool_use: parse_server_tool_use(response)
         end
 
-        # Responses reports a stream error as a flat event carrying a code,
-        # where Chat Completions nests type and message under an error object.
+        def raise_failed_response(response)
+          body = { 'error' => response['error'] }
+          raise_stream_error(JSON.generate(body), body, nil)
+        end
+
+        # OpenAI reports a stream error as a flat event carrying a code. Azure
+        # nests the code and type under an error object, as a failed response
+        # and Chat Completions do.
         def parse_streaming_error(data)
           event = JSON.parse(data)
-          return super unless event.is_a?(Hash) && event['type'] == 'error'
+          error = stream_error(event)
+          return super unless error
+
+          [ERROR_STATUSES[error['code']] || ERROR_STATUSES.fetch(error['type'], 400), error['message']]
+        end
+
+        def stream_error(event)
+          return unless event.is_a?(Hash)
+          return event['error'] if event['error'].is_a?(Hash)
 
-          [ERROR_STATUSES.fetch(event['code'], 400), event['message']]
+          event if event['type'] == 'error'
         end
 
         def chunk(content: nil, **attributes)

data/lib/ruby_llm/protocols/responses/token_counting.rb

@@ -13,8 +13,8 @@ module RubyLLM
           "#{completion_url}/input_tokens"
         end
 
-        def render_count_tokens_payload(messages, model:, **options)
-          render_payload(messages, model: model, temperature: nil, **options).slice(*COUNT_TOKENS_KEYS)
+        def render_count_tokens_payload(messages, model:, **)
+          render_payload(messages, model: model, temperature: nil, **).slice(*COUNT_TOKENS_KEYS)
         end
 
         def parse_count_tokens_response(response)

data/lib/ruby_llm/protocols/responses/tools.rb

@@ -8,6 +8,8 @@ module RubyLLM
       module Tools
         module_function
 
+        NATIVE_TOOL_SEARCH = { type: 'tool_search' }.freeze
+
         def tool_for(tool)
           definition = {
             type: 'function',
@@ -16,12 +18,37 @@ module RubyLLM
             parameters: ChatCompletions::Tools.parameters_schema_for(tool),
             strict: false
           }
+          definition[:defer_loading] = true if deferred?(tool)
 
           return definition if tool.provider_options.empty?
 
           RubyLLM::Support::Utils.deep_merge(definition, tool.provider_options)
         end
 
+        def deferred?(tool)
+          tool.is_a?(RubyLLM::Tool::Deferred)
+        end
+
+        # The API requires a search tool next to deferred tools, and rejects
+        # search items in the input of a request that declares none.
+        def apply_tool_search(payload)
+          tools = Array(payload[:tools])
+          return payload if tools.any? { |tool| search_tool?(tool) }
+          return payload.merge(tools: tools + [NATIVE_TOOL_SEARCH.dup]) if defers_loading?(tools)
+
+          payload.merge(input: payload[:input].reject do |item|
+            Chat::TOOL_SEARCH_ITEM_TYPES.include?(item[:type] || item['type'])
+          end)
+        end
+
+        def defers_loading?(tools)
+          tools.any? { |tool| tool[:defer_loading] || tool['defer_loading'] }
+        end
+
+        def search_tool?(tool)
+          (tool[:type] || tool['type']) == NATIVE_TOOL_SEARCH[:type]
+        end
+
         def build_tool_choice(tool_choice)
           case tool_choice
           when :auto, :none, :required

data/lib/ruby_llm/protocols/responses.rb

@@ -10,6 +10,7 @@ module RubyLLM
       include Responses::Approvals
       include Responses::Chat
       include Responses::Media
+      include Responses::RequestShapes
       include Responses::Streaming
       include Responses::Tools
 

data/lib/ruby_llm/protocols/system_one/judgments.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    class SystemOne
+      module Judgments # :nodoc:
+        TYPES = { probability: 'noul', choice: 'choice', score: 'score' }.freeze
+        BOOLEAN_KEYS = { 'yes' => 'true', 'true' => 'true', 'no' => 'false', 'false' => 'false' }.freeze
+
+        module_function
+
+        def judgment_url
+          'v1/systemone'
+        end
+
+        def render_judgment_payload(input, questions:, model:, with: [], provider_options: {})
+          raise UnsupportedAttachmentError, with.first.mime_type unless with.empty?
+
+          reserved = provider_options.keys.map(&:to_s) & %w[model state questions]
+          unless reserved.empty?
+            raise ArgumentError, "Use the judgment arguments instead of provider_options for #{reserved.join(', ')}"
+          end
+
+          {
+            model:,
+            state: input,
+            questions: questions.transform_values { |question| render_question(question) }
+          }.merge(provider_options)
+        end
+
+        def render_question(question)
+          criteria = question.criteria
+          if question.type == :probability && criteria
+            criteria = criteria.transform_keys { |key| BOOLEAN_KEYS.fetch(key.to_s) }
+          end
+
+          { type: TYPES.fetch(question.type), instructions: question.instructions, criteria: }.compact
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/protocols/system_one/models.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    class SystemOne
+      module Models # :nodoc:
+        module_function
+
+        def models_url
+          'v1/models'
+        end
+
+        def parse_list_models_response(response, slug)
+          Array(response.body['models']).map do |entry|
+            Model.new(
+              id: entry['name'], name: entry['name'], provider: slug,
+              created_at: entry['release_date'],
+              modalities: { input: ['text'], output: ['judgment'] },
+              capabilities: ['judgment'],
+              metadata: { description: entry['description'] }.compact
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/protocols/system_one/responses.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    class SystemOne
+      module Responses # :nodoc:
+        module_function
+
+        def parse_judgment_response(response, questions:)
+          body = response.body
+          answers = questions.values.to_h do |question|
+            [question.name, parse_answer(body.fetch('answers').fetch(question.name.to_s), question)]
+          end
+          RubyLLM::Judgment.new(
+            answers:, model: body['model'], raw: response, model_info: @model,
+            tokens: Tokens.new(input: body.dig('usage', 'input_tokens'), output: body.dig('usage', 'output_tokens'))
+          )
+        rescue KeyError, NoMethodError, TypeError => e
+          raise Error.new("System One returned an invalid judgment: #{e.message}", response:)
+        end
+
+        def parse_answer(answer, question)
+          case question.type
+          when :probability then RubyLLM::Probability.new(probability: answer.fetch('noul'))
+          when :choice then parse_choice(answer, question)
+          when :score then parse_score(answer, question)
+          end
+        end
+
+        def parse_choice(answer, question)
+          options = question.criteria.keys.to_h { |key| [key.to_s, key] }
+          RubyLLM::Choice.new(
+            choice: options.fetch(answer.fetch('choice')),
+            probabilities: parse_probabilities(answer.fetch('probabilities'), options),
+            confidence: answer.fetch('confidence')
+          )
+        end
+
+        def parse_score(answer, question)
+          indexes = question.criteria.each_index.to_h { |index| [index.to_s, index] }
+          legend = answer.fetch('legend')
+          RubyLLM::Score.new(
+            score: answer.fetch('score'), levels: indexes.keys.map { |key| legend.fetch(key) },
+            probabilities: parse_probabilities(answer.fetch('probabilities'), indexes),
+            confidence: answer.fetch('confidence')
+          )
+        end
+
+        def parse_probabilities(values, keys)
+          keys.to_h { |wire, key| [key, values.fetch(wire)] }
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/protocols/system_one.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    # The System One protocol for typed questions and probabilistic answers.
+    class SystemOne < Protocol
+      include SystemOne::Models
+      include SystemOne::Judgments
+      include SystemOne::Responses
+
+      def parse_error_response(response)
+        body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
+        return unless body.is_a?(Hash)
+
+        detail = body['detail']
+        case detail
+        when String
+          detail
+        when Hash
+          detail['message']
+        end
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/ruby_llm/protocols/vertexai/embedding_prediction/requests.rb

@@ -11,8 +11,8 @@ module RubyLLM
           def validate_embedding_request!(request)
             text = request.fetch(:text)
             values = text.is_a?(Array) ? text : [text]
-            unless values.any? && values.all? { |value| value.is_a?(String) && !value.empty? }
-              raise ArgumentError, 'Vertex AI embedding batches require nonempty text strings'
+            unless values.any? && values.all?(String)
+              raise ArgumentError, 'Vertex AI embedding batches require a nonempty list of text strings'
             end
 
             payload = request.fetch(:payload)

data/lib/ruby_llm/protocols/vertexai/files.rb

@@ -8,6 +8,12 @@ module RubyLLM
         # GCS object names allow spaces and other characters URI() rejects.
         GCS_URI = %r{\Ags://([^/]+)/?(.*)\z}m
 
+        STORAGE_CLIENTS = Support::ProcessCache.new
+
+        def self.storage_clients
+          STORAGE_CLIENTS
+        end
+
         # rubocop:disable-next Lint/UnusedMethodArgument
         def upload(file, filename: nil, purpose: nil, expires_in: nil, uri: nil, content_type: nil,
                    provider_options: {})
@@ -74,17 +80,39 @@ module RubyLLM
         def storage
           require 'google/cloud/storage'
 
-          options = { project_id: @config.vertexai_project_id }
-          if @config.vertexai_service_account_key
-            options[:credentials] =
-              JSON.parse(@config.vertexai_service_account_key)
-          end
-          ::Google::Cloud::Storage.new(**options)
+          STORAGE_CLIENTS.fetch(storage_key) { ::Google::Cloud::Storage.new(**storage_options) }
         rescue LoadError
           raise Error, 'The google-cloud-storage gem is required for Vertex AI file uploads. ' \
                        'Please add it to your Gemfile: gem "google-cloud-storage"'
         end
 
+        # Without a key, Cloud Storage resolves its own credentials, including
+        # settings of its own such as STORAGE_KEYFILE.
+        def storage_options
+          options = { project_id: @config.vertexai_project_id }
+          options[:credentials] = @provider.google_credentials if @config.vertexai_service_account_key
+          options
+        end
+
+        # A client keeps the credentials, scope, endpoint, and settings it was
+        # built with, so only callers that would build the same one share it.
+        def storage_key
+          settings = ::Google::Cloud::Storage.configure
+          [
+            storage_options,
+            settings.fields!.to_h { |field| [field, settings[field]] },
+            ::Google::Cloud.configure.credentials,
+            ENV.values_at(*credential_variables)
+          ]
+        end
+
+        def credential_variables
+          storage = ::Google::Cloud::Storage::Credentials
+          loader = ::Google::Auth::CredentialsLoader
+          storage::PATH_ENV_VARS + storage::JSON_ENV_VARS +
+            loader.constants.grep(/_VAR\z/).map { |name| loader.const_get(name) }
+        end
+
         def bucket(name)
           storage.bucket(name) || raise(Error, "GCS bucket not found: #{name}")
         end

data/lib/ruby_llm/protocols/vertexai/ranking.rb

@@ -15,50 +15,29 @@ module RubyLLM
         end
 
         def render_rerank_payload(query, documents, model:, top_n: nil, provider_options: {})
-          validate_ranking_input(query, documents, top_n)
+          raise ArgumentError, 'Vertex AI Search reranking documents must be text' unless documents.all?(String)
+
           records = documents.each_with_index.map { |document, index| { id: index.to_s, content: document } }
           { model: model, query: query, records: records, topN: top_n }.compact.merge(provider_options)
         end
 
         def parse_rerank_response(response, model:, documents: [])
-          records = response.body['records']
-          raise Error.new('Vertex AI Search returned no ranking records', response:) unless records.is_a?(Array)
-
-          seen = []
-          results = records.map do |record|
+          seen = Set.new
+          results = Array(response.body['records']).map do |record|
             index = ranking_index(record, documents)
-            raise Error.new('Vertex AI Search returned a duplicate document id', response:) if seen.include?(index)
+            raise Error.new('Vertex AI Search returned a duplicate document id', response:) unless seen.add?(index)
 
-            seen << index
-            Rerank::Result.new(index: index, document: documents[index], score: record.fetch('score'))
+            Rerank::Result.new(index: index, document: documents[index], score: record['score'])
           end
           Rerank.new(results: results, model: model, raw: response.body)
         end
 
         private
 
-        def validate_ranking_input(query, documents, top_n)
-          unless query.is_a?(String) && !query.empty?
-            raise ArgumentError, 'Vertex AI Search reranking requires a nonempty query'
-          end
-          unless valid_ranking_documents?(documents)
-            raise ArgumentError, 'Vertex AI Search reranking accepts between 1 and 1000 nonempty text documents'
-          end
-          return if top_n.nil? || (top_n.is_a?(Integer) && top_n.positive?)
-
-          raise ArgumentError, 'top_n must be a positive integer'
-        end
-
-        def valid_ranking_documents?(documents)
-          documents.is_a?(Array) && (1..1000).cover?(documents.length) &&
-            documents.all? { |document| document.is_a?(String) && !document.empty? }
-        end
-
         def ranking_index(record, documents)
-          id = record['id'] if record.is_a?(Hash)
-          unless id.is_a?(String) && id.match?(/\A(?:0|[1-9]\d*)\z/) && id.to_i < documents.length &&
-                 record['score'].is_a?(Numeric)
-            raise Error, 'Vertex AI Search returned an invalid document id or score'
+          id = record['id']
+          unless id.is_a?(String) && id.match?(/\A(?:0|[1-9]\d*)\z/) && id.to_i < documents.length
+            raise Error, 'Vertex AI Search returned an invalid document id'
           end
 
           id.to_i

data/lib/ruby_llm/protocols/vertexai/research.rb

@@ -22,7 +22,6 @@ module RubyLLM
         def server_tool_aliases = SERVER_TOOL_ALIASES
 
         def create_research_job(prompt, agent:, with: nil, provider_tools: nil, provider_options: {})
-          validate_research_agent(agent)
           payload = render_research_payload(prompt, agent:, with:, provider_tools:, provider_options:)
           response = @connection.post(research_url, payload, idempotent: false)
           parse_research_job(response, agent:)
@@ -37,14 +36,14 @@ module RubyLLM
           response = @connection.get(research_url(job.id)) do |request|
             request.options.timeout = request_timeout(timeout)
           end
-          parse_research_state(response, id: job.id, agent: job.agent)
+          parse_research_state(response)
         end
 
         def cancel_research_job(job, timeout: nil)
           response = @connection.post("#{research_url(job.id)}/cancel", {}, idempotent: false) do |request|
             request.options.timeout = request_timeout(timeout)
           end
-          parse_research_state(response, id: job.id, agent: job.agent)
+          parse_research_state(response)
         end
 
         private
@@ -65,17 +64,10 @@ module RubyLLM
           [timeout, @config.request_timeout].compact.min
         end
 
-        def validate_research_agent(agent)
-          return if agent == 'deep-research-preview-04-2026'
-
-          raise ArgumentError, 'Vertex AI research requires the supported Deep Research agent ID'
-        end
-
         def render_research_payload(prompt, agent:, with:, provider_tools:, provider_options:)
           raise ArgumentError, 'Research requires a nonempty prompt' unless prompt.is_a?(String) && !prompt.empty?
 
           attachments = Attachment.wrap(with, config: @config)
-          validate_research_attachments(attachments)
           payload = { agent:, input: render_interaction_content(prompt, attachments), background: true, stream: false }
           payload[:tools] = [] unless provider_tools.nil?
           options = render_research_options(provider_options)
@@ -87,14 +79,6 @@ module RubyLLM
           apply_provider_tools(payload, entries).merge(options)
         end
 
-        def validate_research_attachments(attachments)
-          attachments.each do |attachment|
-            next if attachment.image? || attachment.pdf? || attachment.text?
-
-            raise UnsupportedAttachmentError, attachment.mime_type
-          end
-        end
-
         def render_research_options(provider_options)
           options = Support::Utils.deep_symbolize_keys(provider_options)
           unsupported = options.keys - %i[agent_config service_tier]
@@ -121,7 +105,7 @@ module RubyLLM
 
         def parse_research_job(response, agent: nil, id: nil)
           data = response.body
-          state = parse_research_state(response, agent:, id:)
+          state = parse_research_state(response)
           ResearchJob.new(id: data['id'], provider: @provider.slug, agent: data['agent'] || agent, protocol: self,
                           **state)
         rescue RubyLLM::Error, ArgumentError => e
@@ -135,9 +119,9 @@ module RubyLLM
                                        job:, response:), cause: e
         end
 
-        def parse_research_state(response, id: nil, agent: nil)
+        def parse_research_state(response)
           data = response.body
-          validate_research_response(data, response, id:, agent:)
+          validate_research_response(data, response)
           status = STATUSES.fetch(data['status'])
           message = parse_research_message(data, response) if %i[completed incomplete].include?(status)
           {
@@ -146,21 +130,10 @@ module RubyLLM
           }
         end
 
-        def validate_research_response(data, response, id:, agent:)
-          unless data.is_a?(Hash) && !data['id'].to_s.empty? && STATUSES.key?(data['status'])
-            raise RubyLLM::Error.new('Vertex AI research returned no recognized job state', response:)
-          end
-
-          validate_research_identity(data, response, id:, agent:)
-          validate_research_agent(data['agent'] || agent)
-        rescue ArgumentError => e
-          raise RubyLLM::Error.new(e.message, response:), cause: e
-        end
+        def validate_research_response(data, response)
+          return if data.is_a?(Hash) && !data['id'].to_s.empty? && STATUSES.key?(data['status'])
 
-        def validate_research_identity(data, response, id:, agent:)
-          return unless (id && id != data['id']) || (agent && data['agent'] && agent != data['agent'])
-
-          raise RubyLLM::Error.new('Vertex AI research returned a different job identity', response:)
+          raise RubyLLM::Error.new('Vertex AI research returned no recognized job state', response:)
         end
 
         def parse_research_tokens(data)
@@ -174,12 +147,7 @@ module RubyLLM
           state = data.merge('status' => data['status'] == 'completed' ? 'completed' : 'incomplete')
           tokens = parse_research_tokens(data)
           cost = Cost.from_h({ total: tokens.reported_cost }.compact, tokens:)
-          message = parse_completion_body(state, raw: response, model: nil, cost:)
-          if message.content.to_s.empty? && message.attachments.empty?
-            raise RubyLLM::Error.new('Vertex AI research finished without a report', response:)
-          end
-
-          message
+          parse_completion_body(state, raw: response, model: nil, cost:)
         end
 
         def parse_research_error(data)

data/lib/ruby_llm/protocols/xai/streaming_transcription.rb

@@ -4,7 +4,6 @@ module RubyLLM
   module Protocols
     module XAI
       module StreamingTranscription # :nodoc: all
-        SAMPLE_RATES = [8000, 16_000, 22_050, 24_000, 44_100, 48_000].freeze
         ENCODINGS = { [1, 16] => 'pcm', [6, 8] => 'alaw', [7, 8] => 'mulaw' }.freeze
 
         def stream_transcription(payload, model:, &block)
@@ -53,9 +52,7 @@ module RubyLLM
 
         def streaming_transcription_url(payload, audio:)
           encoding = ENCODINGS[[audio.encoding, audio.bits_per_sample]]
-          unless encoding && SAMPLE_RATES.include?(audio.sample_rate) && (1..8).cover?(audio.channels)
-            raise ArgumentError, 'xAI streaming requires 16-bit PCM or 8-bit G.711 WAV audio at a supported sample rate'
-          end
+          raise ArgumentError, 'xAI streaming requires 16-bit PCM or 8-bit G.711 WAV audio' unless encoding
 
           params = payload.except(:file).merge(encoding:, sample_rate: audio.sample_rate, interim_results: true)
           params[:channels] = audio.channels
@@ -68,7 +65,7 @@ module RubyLLM
 
         def send_transcription_audio(socket, audio)
           offset = 0
-          bytes = audio.sample_rate * audio.channels * audio.bits_per_sample / 8 / 10
+          bytes = [audio.sample_rate * audio.channels * audio.bits_per_sample / 8 / 10, 1].max
           while offset < audio.data.bytesize
             socket.send_binary(audio.data.byteslice(offset, bytes))
             offset += bytes