Make one-shot API keywords explicit

Author: crmne

lib/ruby_llm/protocol.rb

@@ -75,14 +75,28 @@ def paint(prompt, model:, size:, with: nil, mask: nil, params: {}) # rubocop:dis
       parse_image_response(response, model:)
     end
 
-    def speak(input, model:, voice:, format:, params: {}, **options) # rubocop:disable Metrics/ParameterLists
-      payload = render_speech_payload(input, model:, voice:, format:, params:, **options)
+    def speak(input, model:, voice:, format:, params: {}, instructions: nil, speed: nil) # rubocop:disable Metrics/ParameterLists
+      payload = render_speech_payload(input, model:, voice:, format:, params:, instructions:, speed:)
       response = @connection.post speech_url(model:), payload
       parse_speech_response(response, model:, voice:, format:)
     end
 
-    def transcribe(audio_file, model:, language:, params: {}, **options)
+    def transcribe(audio_file, model:, language:, params: {}, prompt: nil, temperature: nil, response_format: nil, # rubocop:disable Metrics/ParameterLists
+                   timestamp_granularities: nil, speaker_names: nil, speaker_references: nil, chunking_strategy: nil,
+                   response_mime_type: nil, max_output_tokens: nil, safety_settings: nil)
       file_part = build_audio_file_part(audio_file)
+      options = {
+        prompt: prompt,
+        temperature: temperature,
+        response_format: response_format,
+        timestamp_granularities: timestamp_granularities,
+        speaker_names: speaker_names,
+        speaker_references: speaker_references,
+        chunking_strategy: chunking_strategy,
+        response_mime_type: response_mime_type,
+        max_output_tokens: max_output_tokens,
+        safety_settings: safety_settings
+      }.compact
       payload = render_transcription_payload(file_part, model:, language:, params:, **options)
       response = @connection.post transcription_url, payload
       parse_transcription_response(response, model:)

lib/ruby_llm/protocols/chat_completions/speech.rb

@@ -11,14 +11,14 @@ def speech_url(model:) # rubocop:disable Lint/UnusedMethodArgument
           'audio/speech'
         end
 
-        def render_speech_payload(input, model:, voice:, format:, params: {}, **options) # rubocop:disable Metrics/ParameterLists
+        def render_speech_payload(input, model:, voice:, format:, params: {}, instructions: nil, speed: nil) # rubocop:disable Metrics/ParameterLists
           {
             model: model,
             input: input,
             voice: voice || 'alloy',
             response_format: format,
-            instructions: options[:instructions],
-            speed: options[:speed]
+            instructions: instructions,
+            speed: speed
           }.compact.merge(params)
         end
 

lib/ruby_llm/protocols/chat_completions/transcription.rb

@@ -11,20 +11,25 @@ def transcription_url
           'audio/transcriptions'
         end
 
-        def render_transcription_payload(file_part, model:, language:, params: {}, **options)
+        # rubocop:disable Lint/UnusedMethodArgument, Metrics/ParameterLists
+        def render_transcription_payload(file_part, model:, language:, params: {}, prompt: nil, temperature: nil,
+                                         response_format: nil, timestamp_granularities: nil, speaker_names: nil,
+                                         speaker_references: nil, chunking_strategy: nil, response_mime_type: nil,
+                                         max_output_tokens: nil, safety_settings: nil)
           {
             model: model,
             file: file_part,
             language: language,
-            chunking_strategy: (options[:chunking_strategy] || 'auto' if supports_chunking_strategy?(model, options)),
-            response_format: response_format_for(model, options),
-            prompt: options[:prompt],
-            temperature: options[:temperature],
-            timestamp_granularities: options[:timestamp_granularities],
-            known_speaker_names: options[:speaker_names],
-            known_speaker_references: encode_speaker_references(options[:speaker_references])
+            chunking_strategy: resolved_chunking_strategy(model, chunking_strategy),
+            response_format: response_format_for(model, response_format),
+            prompt: prompt,
+            temperature: temperature,
+            timestamp_granularities: timestamp_granularities,
+            known_speaker_names: speaker_names,
+            known_speaker_references: encode_speaker_references(speaker_references)
           }.compact.merge(params)
         end
+        # rubocop:enable Lint/UnusedMethodArgument, Metrics/ParameterLists
 
         def encode_speaker_references(references)
           return nil unless references
@@ -34,15 +39,21 @@ def encode_speaker_references(references)
           end
         end
 
-        def response_format_for(model, options)
-          return options[:response_format] if options.key?(:response_format)
+        def resolved_chunking_strategy(model, chunking_strategy)
+          return unless supports_chunking_strategy?(model, chunking_strategy)
+
+          chunking_strategy || 'auto'
+        end
+
+        def response_format_for(model, response_format)
+          return response_format if response_format
 
           'diarized_json' if model.include?('diarize')
         end
 
-        def supports_chunking_strategy?(model, options)
+        def supports_chunking_strategy?(model, chunking_strategy)
           return false if model.start_with?('whisper')
-          return true if options.key?(:chunking_strategy)
+          return true if chunking_strategy
 
           model.include?('diarize')
         end

lib/ruby_llm/protocols/gemini/files.rb

@@ -5,12 +5,15 @@ module Protocols
     class Gemini
       # Gemini Files API.
       class Files < UploadedFile::Protocol
-        def upload(file, filename: nil, display_name: nil, **)
+        # rubocop:disable Lint/UnusedMethodArgument, Metrics/ParameterLists
+        def upload(file, filename: nil, display_name: nil, purpose: nil, expires_after: nil, expiry: nil,
+                   visibility: nil, uri: nil, content_type: nil)
           attachment = file_attachment(file, filename:)
           upload_url = start_resumable_upload(attachment, display_name: display_name || attachment.filename)
           response = upload_file_bytes(upload_url, attachment)
           parse_file_response(response.body.fetch('file'))
         end
+        # rubocop:enable Lint/UnusedMethodArgument, Metrics/ParameterLists
 
         def download(file_id)
           file = find(file_id)

lib/ruby_llm/protocols/gemini/speech.rb

@@ -11,7 +11,7 @@ def speech_url(model:)
           "models/#{model}:generateContent"
         end
 
-        def render_speech_payload(input, model:, voice:, format:, params: {}, **options) # rubocop:disable Lint/UnusedMethodArgument,Metrics/ParameterLists
+        def render_speech_payload(input, model:, voice:, format:, params: {}, instructions: nil, speed: nil) # rubocop:disable Lint/UnusedMethodArgument,Metrics/ParameterLists
           RubyLLM.logger.debug { "Ignoring speech format #{format}. Gemini returns PCM audio." } if format
 
           payload = {

lib/ruby_llm/protocols/gemini/transcription.rb

@@ -7,21 +7,28 @@ class Gemini
       module Transcription
         DEFAULT_PROMPT = 'Transcribe the provided audio and respond with only the transcript text.'
 
-        def transcribe(audio_file, model:, language:, params: {}, **options)
+        # rubocop:disable Lint/UnusedMethodArgument, Metrics/ParameterLists
+        def transcribe(audio_file, model:, language:, params: {}, prompt: nil, temperature: nil,
+                       response_format: nil, timestamp_granularities: nil, speaker_names: nil,
+                       speaker_references: nil, chunking_strategy: nil, response_mime_type: 'text/plain',
+                       max_output_tokens: nil, safety_settings: nil)
           attachment = Attachment.new(audio_file)
-          payload = render_transcription_payload(attachment, language:, params:, **options)
+          payload = render_transcription_payload(attachment, language:, params:, prompt:, temperature:,
+                                                             response_mime_type:, max_output_tokens:, safety_settings:)
           response = @connection.post(transcription_url(model), payload)
           parse_transcription_response(response, model:)
         end
+        # rubocop:enable Lint/UnusedMethodArgument, Metrics/ParameterLists
 
         private
 
         def transcription_url(model)
           "models/#{model}:generateContent"
         end
 
-        def render_transcription_payload(attachment, language:, params: {}, **options)
-          prompt = build_prompt(options[:prompt], language)
+        def render_transcription_payload(attachment, language:, params: {}, prompt: nil, temperature: nil, # rubocop:disable Metrics/ParameterLists
+                                         response_mime_type: 'text/plain', max_output_tokens: nil, safety_settings: nil)
+          prompt = build_prompt(prompt, language)
           audio_part = format_audio_part(attachment)
 
           raise UnsupportedAttachmentError, attachment.mime_type unless attachment.audio?
@@ -38,20 +45,19 @@ def render_transcription_payload(attachment, language:, params: {}, **options)
             ]
           }
 
-          generation_config = build_generation_config(options)
+          generation_config = build_generation_config(response_mime_type:, temperature:, max_output_tokens:)
           payload[:generationConfig] = generation_config unless generation_config.empty?
-          payload[:safetySettings] = options[:safety_settings] if options[:safety_settings]
+          payload[:safetySettings] = safety_settings if safety_settings
 
           Utils.deep_merge(payload, params)
         end
 
-        def build_generation_config(options)
+        def build_generation_config(response_mime_type:, temperature:, max_output_tokens:)
           config = {}
-          response_mime_type = options.fetch(:response_mime_type, 'text/plain')
 
           config[:responseMimeType] = response_mime_type if response_mime_type
-          config[:temperature] = options[:temperature] if options.key?(:temperature)
-          config[:maxOutputTokens] = options[:max_output_tokens] if options[:max_output_tokens]
+          config[:temperature] = temperature if temperature
+          config[:maxOutputTokens] = max_output_tokens if max_output_tokens
 
           config
         end

lib/ruby_llm/protocols/openai/files.rb

@@ -9,14 +9,17 @@ class Files < UploadedFile::Protocol
 
         private
 
-        def render_upload_payload(attachment, purpose: nil, expires_after: nil, **)
+        # rubocop:disable Lint/UnusedMethodArgument, Metrics/ParameterLists
+        def render_upload_payload(attachment, purpose: nil, expires_after: nil, expiry: nil, visibility: nil,
+                                  display_name: nil, uri: nil, content_type: nil)
           unless purpose
             raise ArgumentError, "#{@provider.name} file uploads require purpose: " \
                                  "#{UPLOAD_PURPOSES.join(', ')}"
           end
 
           multipart_payload(attachment, purpose:, expires_after:)
         end
+        # rubocop:enable Lint/UnusedMethodArgument, Metrics/ParameterLists
 
         def parse_file_response(data)
           uploaded_file(

lib/ruby_llm/provider.rb

@@ -148,16 +148,35 @@ def paint(prompt, model:, size:, with: nil, mask: nil, params: {}) # rubocop:dis
       default_protocol.new(self).paint(prompt, model:, size:, with:, mask:, params:)
     end
 
-    def speak(input, model:, voice:, format:, params: {}, **options) # rubocop:disable Metrics/ParameterLists
-      default_protocol.new(self).speak(input, model:, voice:, format:, params:, **options)
+    def speak(input, model:, voice:, format:, params: {}, instructions: nil, speed: nil) # rubocop:disable Metrics/ParameterLists
+      default_protocol.new(self).speak(input, model:, voice:, format:, params:, instructions:, speed:)
     end
 
-    def transcribe(audio_file, model:, language:, params: {}, **options)
+    def transcribe(audio_file, model:, language:, params: {}, prompt: nil, temperature: nil, response_format: nil, # rubocop:disable Metrics/ParameterLists
+                   timestamp_granularities: nil, speaker_names: nil, speaker_references: nil, chunking_strategy: nil,
+                   response_mime_type: nil, max_output_tokens: nil, safety_settings: nil)
+      options = {
+        prompt: prompt,
+        temperature: temperature,
+        response_format: response_format,
+        timestamp_granularities: timestamp_granularities,
+        speaker_names: speaker_names,
+        speaker_references: speaker_references,
+        chunking_strategy: chunking_strategy,
+        response_mime_type: response_mime_type,
+        max_output_tokens: max_output_tokens,
+        safety_settings: safety_settings
+      }.compact
+
       default_protocol.new(self).transcribe(audio_file, model:, language:, params:, **options)
     end
 
-    def upload_file(file, **options)
+    def upload_file(file, filename: nil, purpose: nil, expires_after: nil, expiry: nil, visibility: nil, # rubocop:disable Metrics/ParameterLists
+                    display_name: nil, uri: nil, content_type: nil)
       ensure_files_supported!
+      options = { filename:, purpose:, expires_after:, expiry:, visibility:, display_name:, uri:, content_type: }
+                .compact
+
       file_protocol.new(self).upload(file, **options)
     end
 

lib/ruby_llm/providers/bedrock/files.rb

@@ -5,7 +5,9 @@ module Providers
     class Bedrock
       # S3-backed file storage for Bedrock batch input and output.
       class Files < UploadedFile::Protocol
-        def upload(file, uri: nil, filename: nil, content_type: nil, **)
+        # rubocop:disable Lint/UnusedMethodArgument, Metrics/ParameterLists
+        def upload(file, uri: nil, filename: nil, content_type: nil, purpose: nil, expires_after: nil, expiry: nil,
+                   visibility: nil, display_name: nil)
           attachment = file_attachment(file, filename:)
           target_uri = uri || storage_uri_for(attachment)
           bucket, key = parse_s3_uri(target_uri)
@@ -24,6 +26,7 @@ def upload(file, uri: nil, filename: nil, content_type: nil, **)
             mime_type: content_type || file_content_type(attachment)
           )
         end
+        # rubocop:enable Lint/UnusedMethodArgument, Metrics/ParameterLists
 
         def find(file_id)
           bucket, key = parse_s3_uri(file_id)

lib/ruby_llm/providers/mistral/files.rb

@@ -11,9 +11,12 @@ def download_file_url(file_id)
           "#{file_info_url(file_id)}/download"
         end
 
-        def render_upload_payload(attachment, purpose: nil, expiry: nil, visibility: nil, **)
+        # rubocop:disable Lint/UnusedMethodArgument, Metrics/ParameterLists
+        def render_upload_payload(attachment, purpose: nil, expiry: nil, visibility: nil, expires_after: nil,
+                                  display_name: nil, uri: nil, content_type: nil)
           multipart_payload(attachment, purpose:, expiry:, visibility:)
         end
+        # rubocop:enable Lint/UnusedMethodArgument, Metrics/ParameterLists
 
         def parse_file_response(data)
           uploaded_file(