ruby_llm 2.1.1 → 2.2.0

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

data/lib/ruby_llm/providers/minimax.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    # MiniMax API integration, through its Anthropic-compatible endpoint.
+    class MiniMax < Provider
+      protocol :anthropic, MiniMax::Anthropic
+      protocol :media, Protocols::MiniMax
+      protocol :files, Protocols::MiniMax::Files
+      protocol :chat_completions, MiniMax::ChatCompletions
+      protocol :responses, MiniMax::Responses
+
+      MEDIA_OPERATIONS = %i[paint animate speak transcribe].freeze
+
+      # The one MiniMax model that applies a response_format, on Chat
+      # Completion v2. The others ignore every structured output field.
+      STRUCTURED_OUTPUT_MODEL = 'MiniMax-Text-01'
+
+      # The HTTP status each MiniMax status code stands for on endpoints that
+      # answer 200 and report the failure in base_resp.
+      FAILURE_STATUSES = {
+        1000 => 500, 1001 => 504, 1002 => 429, 1004 => 401, 1008 => 402, 1039 => 429, 2049 => 401, 2056 => 429
+      }.freeze
+
+      def resolve_protocol(name, model, operation: nil, **options)
+        name ||= :media if MEDIA_OPERATIONS.include?(operation)
+        super
+      end
+
+      def protocol_for(model, schema: nil, thinking: nil, tool_prefs: nil, provider_tools: [], messages: [], **)
+        return protocols[:chat_completions] if schema && model.id == STRUCTURED_OUTPUT_MODEL
+        return protocols[:responses] if web_search_route?(schema, thinking, tool_prefs, provider_tools, messages)
+
+        super
+      end
+
+      def api_base
+        configured_api_base(:minimax_api_base, 'https://api.minimax.io/anthropic', endpoints: %r{/v1/messages\z})
+      end
+
+      def media_base # :nodoc:
+        api_base.sub(%r{/anthropic/?\z}, '')
+      end
+
+      def headers
+        { 'Authorization' => "Bearer #{@config.minimax_api_key}" }
+      end
+
+      def account_identity
+        account_digest(api_base, @config.minimax_api_key)
+      end
+
+      def error_status(response)
+        code = failure_code(response)
+        FAILURE_STATUSES.fetch(code, 400) if code
+      end
+
+      def parse_error(response)
+        return super unless failure_code(response)
+
+        parse_error_body(response).dig('base_resp', 'status_msg')
+      end
+
+      class << self
+        def models_dev_provider_ids # :nodoc:
+          %w[minimax]
+        end
+
+        def configuration_options
+          %i[minimax_api_key minimax_api_base]
+        end
+
+        def configuration_requirements
+          %i[minimax_api_key]
+        end
+      end
+
+      private
+
+      # Only Responses cites web pages, but it ignores an attached PDF, so a
+      # chat that holds one stays on Messages, which reads it. Messages also
+      # raises on what MiniMax cannot carry and honours a thinking budget or
+      # off switch, all of which Responses would drop.
+      def web_search_route?(schema, thinking, tool_prefs, provider_tools, messages)
+        return false unless provider_tools.any? { |entry| entry[:name] == :web_search }
+        return false if messages_only_request?(schema, thinking, tool_prefs)
+
+        messages.none? { |message| message.attachments.any?(&:pdf?) }
+      end
+
+      def messages_only_request?(schema, thinking, tool_prefs)
+        schema || tool_prefs&.dig(:calls) == :one || (thinking && !thinking.effort)
+      end
+
+      def failure_code(response)
+        return unless response.body.to_s.include?('base_resp')
+
+        body = parse_error_body(response)
+        code = body.dig('base_resp', 'status_code') if body.is_a?(Hash)
+        code unless code.nil? || code.zero?
+      end
+    end
+  end
+end