ruby_llm 2.1.0 → 2.2.0

data/lib/ruby_llm/providers/elevenlabs.rb

@@ -14,7 +14,8 @@ module RubyLLM
       end
 
       def api_base
-        @config.elevenlabs_api_base || 'https://api.elevenlabs.io'
+        configured_api_base(:elevenlabs_api_base, 'https://api.elevenlabs.io',
+                            endpoints: %r{/v1/(?:speech-to-text\z|text-to-speech/.*\z)})
       end
 
       def headers

data/lib/ruby_llm/providers/gemini.rb

@@ -4,12 +4,15 @@ module RubyLLM
   module Providers
     # Native Gemini API implementation
     class Gemini < Provider
+      include Protocols::Gemini::RetryInfo
+
       protocol :gemini, Protocols::Gemini, batches: Protocols::Gemini::Batches
       protocol :interactions, Protocols::Interactions
       protocol :live_transcription, Protocols::Gemini::LiveTranscription
       protocol :files, Protocols::Gemini::Files
 
       def protocol_for(model, operation: nil, **)
+        return protocols[:interactions] if operation == :animate
         return protocols[:interactions] if operation == :transcribe && model.id == 'gemini-3.5-transcribe'
         return protocols[:live_transcription] if operation == :transcribe && model.id == 'gemini-3.5-transcribe-live'
 
@@ -17,7 +20,8 @@ module RubyLLM
       end
 
       def api_base
-        @config.gemini_api_base || 'https://generativelanguage.googleapis.com/v1beta'
+        configured_api_base(:gemini_api_base, 'https://generativelanguage.googleapis.com/v1beta',
+                            endpoints: %r{/models/[^/]+:\w+\z})
       end
 
       def headers
@@ -35,6 +39,14 @@ module RubyLLM
       end
 
       class << self
+        def open_telemetry_name # :nodoc:
+          'gcp.gemini'
+        end
+
+        def models_dev_provider_ids # :nodoc:
+          %w[google]
+        end
+
         def capabilities
           Gemini::Capabilities
         end

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

@@ -7,13 +7,33 @@ module RubyLLM
       module Chat
         module_function
 
-        def format_content(content, attachments = [])
-          GPUStack::Media.format_content(content, attachments)
+        def render_content(content, attachments = [])
+          GPUStack::Media.render_content(content, attachments)
         end
 
-        def format_role(role)
+        def render_role(role)
           role.to_s
         end
+
+        # vLLM truncates the rendered prompt to its last tokens. It summarizes
+        # nothing, and the cut can reach the system prompt. Truncating to the
+        # model's own limit without an output limit leaves no room to answer,
+        # and vLLM rejects the request.
+        def apply_compaction(payload, compaction)
+          log_ignored_compaction_options(compaction)
+          limit = compaction[:at] || (-1 if payload.key?(:max_tokens))
+          return payload.merge(truncate_prompt_tokens: limit, truncation_side: 'left') if limit
+
+          RubyLLM.logger.debug { "#{@provider.name} needs at: or an output limit to truncate, not truncating" }
+          payload
+        end
+
+        def log_ignored_compaction_options(compaction)
+          ignored = compaction.except(:at)
+          return if ignored.empty?
+
+          RubyLLM.logger.debug { "#{@provider.name} only truncates the prompt, dropping #{ignored.inspect}" }
+        end
       end
     end
   end

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

@@ -7,7 +7,7 @@ module RubyLLM
       module Embeddings
         module_function
 
-        def supports_embedding_media?
+        def embedding_media?
           true
         end
 
@@ -18,7 +18,7 @@ module RubyLLM
             raise ArgumentError, 'embed one text at a time when embedding attachments' if text.is_a?(Array)
 
             payload.delete(:input)
-            payload[:messages] = [{ role: 'user', content: GPUStack::Media.format_content(text, with) }]
+            payload[:messages] = [{ role: 'user', content: GPUStack::Media.render_content(text, with) }]
           end
           payload.merge(provider_options)
         end

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

@@ -11,24 +11,24 @@ module RubyLLM
           %i[image audio video 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
-              format_image(attachment)
+              render_image(attachment)
             when :audio
-              Protocols::ChatCompletions::Media.format_audio(attachment)
+              Protocols::ChatCompletions::Media.render_audio(attachment)
             when :video
-              format_video(attachment)
+              render_video(attachment)
             when :text
-              Protocols::ChatCompletions::Media.format_text_file(attachment)
+              Protocols::ChatCompletions::Media.render_text_file(attachment)
             end
           end
         end
 
-        def format_image(image)
+        def render_image(image)
           {
             type: 'image_url',
             image_url: {
@@ -38,7 +38,7 @@ module RubyLLM
           }
         end
 
-        def format_video(video)
+        def render_video(video)
           {
             type: 'video_url',
             video_url: { url: video.for_llm }

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

@@ -7,19 +7,27 @@ module RubyLLM
       module Transcription
         module_function
 
-        def stream_transcription(payload, model:, &)
-          super({ stream_include_usage: 'true' }.merge(payload), model:, &)
+        # Usage may follow the finish reason in an event of its own, so only
+        # the end of the stream can say the transcript is done.
+        def stream_transcription(payload, model:, &block)
+          last = nil
+          result = super({ stream_include_usage: 'true' }.merge(payload), model:) do |chunk|
+            last = chunk
+            block.call(chunk) unless chunk.done?
+          end
+          block.call(RubyLLM::TranscriptionChunk.new(type: RubyLLM::TranscriptionChunk::DONE, text: result.text,
+                                                     raw: last&.raw))
+          result
         end
 
         def build_transcription_chunk(data)
           return super unless data.key?('choices')
 
-          choice = data['choices'].first || {}
-          finished = choice['finish_reason'] || data['choices'].empty?
+          choice = data['choices'].first
 
           RubyLLM::TranscriptionChunk.new(
-            type: finished ? RubyLLM::TranscriptionChunk::DONE : RubyLLM::TranscriptionChunk::DELTA,
-            delta: choice.dig('delta', 'content'),
+            type: choice ? RubyLLM::TranscriptionChunk::DELTA : RubyLLM::TranscriptionChunk::DONE,
+            delta: choice&.dig('delta', 'content'),
             raw: data
           )
         end

data/lib/ruby_llm/providers/gpustack.rb

@@ -27,7 +27,7 @@ module RubyLLM
       end
 
       def api_base
-        @config.gpustack_api_base
+        configured_api_base(:gpustack_api_base, example: 'http://HOST/v1', endpoints: Protocols::ChatCompletions::ENDPOINT_PATHS)
       end
 
       def backend_api_base # :nodoc:

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

@@ -7,22 +7,39 @@ module RubyLLM
       module Chat
         module_function
 
-        def format_role(role)
+        REJECTED_EFFORT = /\AUnexpected reasoning effort /
+
+        def render_role(role)
           role.to_s
         end
 
+        # The API accepts cache fields and ignores them; it caches long
+        # prompts by itself.
+        def openai_prompt_caching?
+          false
+        end
+
+        def apply_prompt_cache_params(_payload, caching)
+          prompt_cache_options(caching) if caching
+        end
+
+        # The API names a rejected effort only in its message.
+        def parse_unsupported_parameter(response)
+          super || (:thinking if parse_error(response).to_s.match?(REJECTED_EFFORT))
+        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_parts(content, attachments) do |attachment|
+        def render_content(content, attachments = [])
+          Protocols::ChatCompletions::Media.render_parts(content, attachments) do |attachment|
             if attachment.type == :image && !attachment.provider_file?
-              format_inline_image(attachment)
+              render_inline_image(attachment)
             else
-              Protocols::ChatCompletions::Media.format_attachment(
+              Protocols::ChatCompletions::Media.render_attachment(
                 attachment, document_attachments: :none, image_attachments: true, audio_attachments: false
               )
             end
@@ -30,7 +47,7 @@ module RubyLLM
         end
 
         # Hetzner's servers can't fetch URLs, so remote images travel inline too.
-        def format_inline_image(image)
+        def render_inline_image(image)
           { type: 'image_url', image_url: { url: image.for_llm } }
         end
       end

data/lib/ruby_llm/providers/hetzner.rb

@@ -12,7 +12,7 @@ module RubyLLM
       protocol :chat_completions, ChatCompletions
 
       def api_base
-        @config.hetzner_api_base || 'https://inference.hetzner.com/api/v1'
+        configured_api_base(:hetzner_api_base, 'https://inference.hetzner.com/v1', endpoints: Protocols::ChatCompletions::ENDPOINT_PATHS)
       end
 
       def headers
@@ -20,6 +20,10 @@ module RubyLLM
       end
 
       class << self
+        def models_dev_provider_ids # :nodoc:
+          %w[hetzner]
+        end
+
         def configuration_options
           %i[hetzner_api_key hetzner_api_base]
         end

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Meta
+      # Meta's dialect of the OpenAI Responses API, the format Meta
+      # recommends because it replays encrypted reasoning across turns.
+      # https://dev.meta.ai/docs/protocols/responses
+      class Responses < Protocols::Responses
+        include Protocols::Responses::TokenCounting
+        include Protocols::Meta::Transcription
+
+        SERVER_TOOL_ALIASES = {
+          web_search: { tool: { type: 'web_search' } }
+        }.freeze
+
+        PROMPT_CACHE_OPTIONS = %i[key ttl].freeze
+        AUDIO_FORMATS = %w[mp3 wav].freeze
+
+        def server_tool_aliases
+          SERVER_TOOL_ALIASES
+        end
+
+        def document_urls?
+          true
+        end
+
+        def web_search_sources?
+          true
+        end
+
+        def apply_end_user(payload, identifier)
+          payload.merge(safety_identifier: identifier)
+        end
+
+        # Meta takes a cache key and a retention hint, in_memory or 24h,
+        # and no cache breakpoints.
+        def prompt_cache_params(caching)
+          options = caching.to_h.transform_keys(&:to_sym)
+          unsupported = options.keys - PROMPT_CACHE_OPTIONS
+          unless unsupported.empty?
+            raise ArgumentError,
+                  "Meta prompt caching accepts :key and :ttl, got #{format_cache_option_keys(unsupported)}"
+          end
+
+          ttl = options[:ttl] && render_cache_lifetime(options[:ttl])
+          { prompt_cache_key: options[:key], prompt_cache_retention: ttl }.compact
+        end
+
+        def cache_option_names = PROMPT_CACHE_OPTIONS
+
+        def inject_cache_breakpoint(item)
+          item
+        end
+
+        def supported_attachment?(attachment)
+          return super if attachment.provider_file?
+          return AUDIO_FORMATS.include?(attachment.format) if attachment.audio?
+
+          attachment.video? || super
+        end
+
+        # Meta's fetcher is refused by many hosts, so remote media travels inline.
+        def render_attachment(attachment)
+          return super if attachment.provider_file? || !supported_attachment?(attachment)
+
+          case attachment.type
+          when :video then { type: 'input_video', video_url: attachment.for_llm }
+          when :audio then { type: 'input_audio', input_audio: { data: attachment.encoded, format: attachment.format } }
+          else super
+          end
+        end
+
+        # Meta refuses to fetch many remote images, so images travel inline.
+        def render_image(image, image_url: image.for_llm, **)
+          super
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/meta.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    # Meta Model API integration for the Muse models.
+    class Meta < Provider
+      protocol :responses, Meta::Responses
+      protocol :files, Protocols::OpenAI::Files
+
+      def api_base
+        configured_api_base(:meta_api_base, 'https://api.meta.ai/v1', endpoints: Protocols::ChatCompletions::ENDPOINT_PATHS)
+      end
+
+      def headers
+        { 'Authorization' => "Bearer #{@config.meta_api_key}" }
+      end
+
+      def account_identity
+        account_digest(api_base, @config.meta_api_key)
+      end
+
+      class << self
+        def models_dev_provider_ids # :nodoc:
+          %w[meta]
+        end
+
+        def configuration_options
+          %i[meta_api_key meta_api_base]
+        end
+
+        def configuration_requirements
+          %i[meta_api_key]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class MiniMax
+      # MiniMax's dialect of the Anthropic Messages API. MiniMax has no
+      # Files API on this endpoint, and web search is the one server tool it
+      # runs, in Anthropic's first version.
+      class Anthropic < Protocols::Anthropic
+        SERVER_TOOL_ALIASES = {
+          web_search: { tool: { type: 'web_search_20250305', name: 'web_search' } }
+        }.freeze
+
+        RESPONSES_ITEMS = %w[reasoning web_search_call message function_call].freeze
+        private_constant :RESPONSES_ITEMS
+
+        def render_payload(messages, tools:, schema: nil, tool_prefs: nil, **)
+          raise ArgumentError, "MiniMax's Messages API has no structured output" if schema
+          raise ArgumentError, 'MiniMax does not accept calls: :one' if tools.any? && tool_prefs&.dig(:calls) == :one
+
+          super
+        end
+
+        def render_count_tokens_payload(messages, tool_prefs: nil, **)
+          super(messages, **, schema: nil, tool_prefs: tool_prefs&.except(:calls))
+        end
+
+        def server_tool_aliases
+          SERVER_TOOL_ALIASES
+        end
+
+        def provider_file_references?
+          false
+        end
+
+        def supported_attachment?(attachment)
+          return attachment.source.provider == 'minimax' if attachment.provider_file? && attachment.video?
+
+          attachment.video? || super
+        end
+
+        private
+
+        # A video block is documented for user messages only; tool results
+        # and system prompts take the attachments Anthropic's format does.
+        def supported_message_attachment?(message, attachment)
+          return false if attachment.video? && message.role != :user
+
+          super
+        end
+
+        def render_content(content, attachments = [], citations: false)
+          blocks = super(content, [], citations:)
+          attachments.each do |attachment|
+            blocks.concat(attachment.video? ? [render_video(attachment)] : super(nil, [attachment], citations:))
+          end
+          blocks
+        end
+
+        def append_formatted_content(content_blocks, msg, citations: false)
+          video = msg.attachments.find(&:video?) unless msg.role == :user
+          raise UnsupportedAttachmentError, video.mime_type if video
+
+          content_blocks.concat(render_content(msg.content, msg.attachments, citations:))
+        end
+
+        def render_video(video)
+          raise UnsupportedAttachmentError, video.mime_type unless supported_attachment?(video)
+
+          { type: 'video', source: video_source(video) }
+        end
+
+        # MiniMax's fetcher is refused by many hosts, so remote videos travel inline.
+        def video_source(video)
+          return { type: 'url', url: "mm_file://#{video.provider_file_id}" } if video.provider_file?
+
+          media_type = video.mime_type == 'video/quicktime' ? 'video/mov' : video.mime_type
+          { type: 'base64', media_type:, data: video.encoded }
+        end
+
+        # A web search turn answered on Responses keeps that route's output
+        # items, which a Messages request cannot carry.
+        def foreign_native_content?(message)
+          super || (message.role == :assistant && responses_output?(message.raw_content))
+        end
+
+        def responses_output?(raw_content)
+          raw_content.is_a?(Array) && raw_content.any? do |item|
+            item.is_a?(Hash) && RESPONSES_ITEMS.include?(item['type'])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/minimax/chat_completions.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class MiniMax
+      # MiniMax's own Chat Completion v2 route, used only for structured
+      # output on the one model that applies response_format. That model
+      # nests its answer under the schema name, so parsing removes the
+      # wrapper, which cannot be done part by part on a stream.
+      class ChatCompletions < Protocols::ChatCompletions
+        def completion_url
+          "#{@provider.media_base}/v1/text/chatcompletion_v2"
+        end
+
+        def render_payload(messages, schema: nil, stream: false, **)
+          raise ArgumentError, "#{@model.id} does not stream structured output" if schema && stream
+
+          @schema_name = schema&.dig(:name)
+          super
+        end
+
+        def parse_completion_body(data, raw:)
+          super(unwrap_schema_result(data), raw: raw)
+        end
+
+        private
+
+        def unwrap_schema_result(data)
+          content = data.dig('choices', 0, 'message', 'content')
+          return data unless @schema_name && content.is_a?(String)
+
+          parsed = parse_json(content)
+          return data unless parsed.is_a?(Hash) && parsed.keys == [@schema_name]
+
+          choice = data['choices'][0]
+          message = choice['message'].merge('content' => JSON.generate(parsed[@schema_name]))
+          data.merge('choices' => [choice.merge('message' => message), *data['choices'][1..]])
+        end
+
+        def parse_json(content)
+          JSON.parse(content)
+        rescue JSON::ParserError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class MiniMax
+      # MiniMax's Responses route, used for web search because only this
+      # endpoint returns citations. It holds no state: store is always false.
+      # https://platform.minimax.io/docs/api-reference/responses-create
+      class Responses < Protocols::Responses
+        SERVER_TOOL_ALIASES = {
+          web_search: { tool: { type: 'web_search' } }
+        }.freeze
+
+        # MiniMax reports a search's pages only through its citations.
+        def self.parse_web_sources(message)
+          message.citations.filter_map do |citation|
+            WebSource.new(url: citation.url, title: citation.title) if citation.url
+          end
+        end
+
+        def completion_url
+          "#{@provider.media_base}/v1/responses"
+        end
+
+        def server_tool_aliases
+          SERVER_TOOL_ALIASES
+        end
+
+        private
+
+        def provider_file_references?
+          false
+        end
+
+        # MiniMax sends url_citation annotations with both offsets at 0, so
+        # they say nothing about the span they support. Its content field is
+        # the quoted snippet.
+        def parse_annotations(annotations, _content)
+          Array(annotations).filter_map do |annotation|
+            next unless annotation['type'] == 'url_citation'
+
+            Citation.new(url: annotation['url'], title: annotation['title'], cited_text: annotation['content'])
+          end
+        end
+
+        def offset_citations(citations, *)
+          citations
+        end
+      end
+    end
+  end
+end