ruby_llm 2.1.0 → 2.2.0

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

@@ -9,17 +9,16 @@ module RubyLLM
 
         def render_payload(messages, tools:, temperature:, model:, stream: false, max_output_tokens: nil,
                            schema: nil, thinking: nil, citations: false, caching: nil, tool_prefs: nil)
-          if thinking&.budget
-            RubyLLM.logger.debug { "Ollama has no thinking budgets; ignoring budget #{thinking.budget}" }
-          end
+          raise ArgumentError, 'Ollama has no thinking budget; use effort:' if thinking&.budget
+
           super
         end
 
-        def format_content(content, attachments = [])
-          Ollama::Media.format_content(content, attachments)
+        def render_content(content, attachments = [])
+          Ollama::Media.render_content(content, attachments)
         end
 
-        def format_role(role)
+        def render_role(role)
           role.to_s
         end
       end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Ollama
+      # Ollama embeds text, an image, and audio together when the input is
+      # one object holding each as a field.
+      module Embeddings
+        EMBEDDING_MEDIA_FIELDS = %i[image audio].freeze
+
+        module_function
+
+        def embedding_media?
+          true
+        end
+
+        def render_embedding_payload(text, model:, dimensions:, task_type: nil, title: nil, with: [],
+                                     provider_options: {})
+          input = with.any? ? media_embedding_input(text, with) : text
+          super(input, model:, dimensions:, task_type:, title:, provider_options:)
+        end
+
+        def media_embedding_input(text, attachments)
+          raise ArgumentError, 'embed one text at a time when embedding attachments' if text.is_a?(Array)
+
+          input = text.to_s.empty? ? {} : { text: text }
+          attachments.each do |attachment|
+            unless EMBEDDING_MEDIA_FIELDS.include?(attachment.type)
+              raise UnsupportedAttachmentError,
+                    attachment.mime_type
+            end
+            raise ArgumentError, "Ollama embeds one #{attachment.type} per input" if input.key?(attachment.type)
+
+            input[attachment.type] = attachment.encoded
+          end
+          input
+        end
+      end
+    end
+  end
+end

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

@@ -11,22 +11,22 @@ module RubyLLM
           %i[image audio 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 :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: {

data/lib/ruby_llm/providers/ollama/speech.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Ollama
+      # Ollama's dialect of speech generation. Its voices come from each model,
+      # so a call with no voice leaves the choice to the model, and it answers
+      # with WAV unless asked for PCM.
+      module Speech
+        DEFAULT_VOICE = 'default'
+        DEFAULT_FORMAT = 'wav'
+
+        def render_speech_payload(input, model:, voice:, format:, provider_options: {})
+          { model:, input:, voice:, response_format: format }.compact.merge(provider_options)
+        end
+
+        def parse_speech_response(response, model:, voice:, format:)
+          RubyLLM::Speech.new(data: response.body, model:, voice: voice || DEFAULT_VOICE,
+                              format: (format || DEFAULT_FORMAT).to_s, characters: @speech_characters)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/ollama.rb

@@ -7,8 +7,10 @@ module RubyLLM
       # Ollama's dialect of the Chat Completions API.
       class ChatCompletions < Protocols::ChatCompletions
         include Ollama::Chat
+        include Ollama::Embeddings
         include Ollama::Media
         include Ollama::Models
+        include Ollama::Speech
       end
 
       # Ollama's dialect of the System One API for decision models such as Clef.
@@ -16,11 +18,21 @@ module RubyLLM
         include Ollama::Judgments
       end
 
+      # Ollama's stateless Responses API, which serves manual compaction.
+      class Responses < Protocols::Responses
+        include Protocols::Responses::Compaction
+
+        def render_image(image, image_url: image.for_llm, **)
+          super
+        end
+      end
+
       protocol :chat_completions, ChatCompletions
       protocol :system_one, SystemOne
+      protocol :responses, Responses
 
       def api_base
-        @config.ollama_api_base
+        configured_api_base(:ollama_api_base, example: 'http://localhost:11434/v1', endpoints: Protocols::ChatCompletions::ENDPOINT_PATHS)
       end
 
       def resolve_protocol(name, model, operation: nil, **options)

data/lib/ruby_llm/providers/ollama_cloud.rb

@@ -7,12 +7,25 @@ module RubyLLM
       # Ollama Cloud's dialect of the Chat Completions API.
       class ChatCompletions < Ollama::ChatCompletions
         include OllamaCloud::Models
+
+        abstract :embedding_url, :embedding_media?, :speech_url, :build_audio_file_part, :render_image_payload,
+                 :render_moderation_payload
+      end
+
+      # Ollama Cloud's dialect of the System One API for decision models such as Clef.
+      class SystemOne < Ollama::SystemOne
       end
 
       protocol :chat_completions, ChatCompletions
+      protocol :system_one, SystemOne
 
       def api_base
-        @config.ollama_cloud_api_base || 'https://ollama.com/v1'
+        configured_api_base(:ollama_cloud_api_base, 'https://ollama.com/v1', endpoints: Protocols::ChatCompletions::ENDPOINT_PATHS)
+      end
+
+      def resolve_protocol(name, model, operation: nil, **options)
+        name ||= :system_one if operation == :judge
+        super
       end
 
       def headers
@@ -20,6 +33,14 @@ module RubyLLM
       end
 
       class << self
+        def open_telemetry_name # :nodoc:
+          'ollama'
+        end
+
+        def models_dev_provider_ids # :nodoc:
+          %w[ollama-cloud]
+        end
+
         def configuration_options
           %i[ollama_cloud_api_key ollama_cloud_api_base]
         end

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

@@ -7,6 +7,14 @@ module RubyLLM
       class Responses < Protocols::Responses
         include Protocols::Responses::TokenCounting
         include Protocols::Responses::Compaction
+
+        def document_urls?
+          true
+        end
+
+        def web_search_sources?
+          true
+        end
       end
     end
   end

data/lib/ruby_llm/providers/openai.rb

@@ -19,7 +19,7 @@ module RubyLLM
       end
 
       def api_base
-        @config.openai_api_base || 'https://api.openai.com/v1'
+        configured_api_base(:openai_api_base, 'https://api.openai.com/v1', endpoints: Protocols::ChatCompletions::ENDPOINT_PATHS)
       end
 
       def resolve_protocol(name, model, operation: nil, **options)
@@ -29,9 +29,9 @@ module RubyLLM
 
       # Audio, realtime, and dedicated search models only exist on Chat Completions.
       def protocol_for(model, **)
-        return protocols[:chat_completions] if Capabilities::SEARCH_MODELS.include?(model.id)
+        return fetch_protocol(:chat_completions) if Capabilities::SEARCH_MODELS.include?(model.id)
 
-        model.id.match?(/audio|realtime/) ? protocols[:chat_completions] : super
+        model.id.match?(/audio|realtime/) ? fetch_protocol(:chat_completions) : super
       end
 
       def headers
@@ -69,6 +69,10 @@ module RubyLLM
       def batch_cost_multiplier(**) = 0.5
 
       class << self
+        def models_dev_provider_ids # :nodoc:
+          %w[openai]
+        end
+
         def capabilities
           OpenAI::Capabilities
         end

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

@@ -38,8 +38,8 @@ module RubyLLM
           OpenRouter::Media.supported_attachment?(attachment)
         end
 
-        def format_content(content, attachments = [])
-          OpenRouter::Media.format_content(content, attachments)
+        def render_content(content, attachments = [])
+          OpenRouter::Media.render_content(content, attachments)
         end
 
         def render_payload(messages, tools:, temperature:, model:, stream: false, max_output_tokens: nil, schema: nil,
@@ -85,7 +85,7 @@ module RubyLLM
           reasoning[:enabled] = thinking.enabled
         end
 
-        def format_thinking(msg)
+        def render_thinking(msg)
           return {} unless msg.role == :assistant
           return { reasoning_details: msg.raw_reasoning } if msg.raw_reasoning.is_a?(Array)
 
@@ -103,7 +103,7 @@ module RubyLLM
           end
         end
 
-        def format_message_content(msg, caching: nil)
+        def render_message_content(msg, caching: nil)
           content = super
           return content unless caching != false && msg.cache_until_here?
 
@@ -127,7 +127,7 @@ module RubyLLM
           ttl ||= options[:ttl]
 
           { type: CACHE_CONTROL_TYPE }.tap do |control|
-            control[:ttl] = ttl if ttl
+            control[:ttl] = render_cache_lifetime(ttl) if ttl
           end
         end
 
@@ -142,6 +142,8 @@ module RubyLLM
                 "OpenRouter prompt caching accepts :ttl, got #{format_cache_option_keys(unsupported)}"
         end
 
+        def cache_option_names = PROMPT_CACHE_OPTIONS
+
         def format_cache_option_keys(keys)
           keys.map { |key| ":#{key}" }.join(', ')
         end
@@ -158,10 +160,14 @@ module RubyLLM
           cost
         end
 
-        def supports_provider_file_references?
+        def provider_file_references?
           true
         end
 
+        def provider_file_upload_options(_attachment)
+          {}
+        end
+
         def default_large_file_upload_threshold
           OPENROUTER_INLINE_FILE_THRESHOLD
         end
@@ -170,7 +176,7 @@ module RubyLLM
           attachment.pdf?
         end
 
-        def extract_thinking_text(message_data)
+        def parse_thinking_text(message_data)
           candidate = message_data['reasoning']
           return candidate if candidate.is_a?(String)
 
@@ -189,7 +195,7 @@ module RubyLLM
           text.empty? ? nil : text
         end
 
-        def extract_thinking_signature(message_data)
+        def parse_thinking_signature(message_data)
           details = message_data['reasoning_details']
           return nil unless details.is_a?(Array)
 
@@ -204,7 +210,7 @@ module RubyLLM
 
         # OpenRouter requires the reasoning_details array back untouched for
         # signed reasoning to survive multi-turn tool calls.
-        def extract_raw_reasoning(message_data)
+        def parse_raw_reasoning(message_data)
           details = message_data['reasoning_details']
           details if details.is_a?(Array) && !details.empty?
         end

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

@@ -7,9 +7,13 @@ module RubyLLM
       module Embeddings
         EMBEDDING_MEDIA_TYPES = { audio: :input_audio, video: :input_video, pdf: :input_file }.freeze
 
+        def rejected_options(operation)
+          operation == :embed ? %i[title] : super
+        end
+
         module_function
 
-        def supports_embedding_media?
+        def embedding_media?
           true
         end
 
@@ -18,7 +22,7 @@ module RubyLLM
           input = if with.any?
                     raise ArgumentError, 'embed one text at a time when embedding attachments' if text.is_a?(Array)
 
-                    [{ content: format_embedding_content(text, with) }]
+                    [{ content: render_embedding_content(text, with) }]
                   else
                     text
                   end
@@ -28,21 +32,21 @@ module RubyLLM
           payload.merge(provider_options)
         end
 
-        def format_embedding_content(text, attachments)
-          Protocols::ChatCompletions::Media.format_parts(text, attachments) do |attachment|
-            format_embedding_attachment(attachment)
+        def render_embedding_content(text, attachments)
+          Protocols::ChatCompletions::Media.render_parts(text, attachments) do |attachment|
+            render_embedding_attachment(attachment)
           end
         end
 
-        def format_embedding_attachment(attachment)
+        def render_embedding_attachment(attachment)
           raise UnsupportedAttachmentError, attachment.mime_type if attachment.provider_file?
 
           if (type = EMBEDDING_MEDIA_TYPES[attachment.type])
             { type: type.to_s, type => { data: attachment.for_llm, format: attachment.format } }
           elsif attachment.type == :image
-            Protocols::ChatCompletions::Media.format_image(attachment)
+            Protocols::ChatCompletions::Media.render_image(attachment)
           else
-            Protocols::ChatCompletions::Media.format_attachment(
+            Protocols::ChatCompletions::Media.render_attachment(
               attachment, document_attachments: :none, image_attachments: true, audio_attachments: false
             )
           end

data/lib/ruby_llm/providers/openrouter/images.rb

@@ -7,34 +7,40 @@ module RubyLLM
       # OpenRouter has a unified images endpoint that generates and edits
       # images across providers and reports the exact cost of each call.
       module Images
+        ASPECT_RATIO = /\A(?:\d+:\d+|auto)\z/
+
+        def rejected_options(operation)
+          operation == :paint ? %i[count] : super
+        end
+
         module_function
 
-        def images_url(with: nil, mask: nil) # rubocop:disable Lint/UnusedMethodArgument
+        def images_url(**)
           'images'
         end
 
-        def render_image_payload(prompt, model:, size:, count: nil, with: nil, mask: nil, provider_options: {}) # rubocop:disable Lint/UnusedMethodArgument
-          RubyLLM.logger.debug { "Ignoring size #{size}. Use aspect_ratio/resolution provider options instead." }
-          if count && count > 1
-            RubyLLM.logger.debug do
-              "Ignoring count #{count}. OpenRouter generates one image per request."
-            end
-          end
+        def render_image_payload(prompt, model:, size:, with: nil, provider_options: {}, **)
           payload = { model: model, prompt: prompt }
           references = build_input_references(with)
           payload[:input_references] = references if references.any?
+          payload.merge!(render_image_size(size)) if size
           payload.merge(provider_options)
         end
 
+        def render_image_size(size)
+          value = size.to_s.strip
+          value.match?(ASPECT_RATIO) ? { aspect_ratio: value } : { size: value }
+        end
+
         def build_input_references(with)
           Attachment.wrap(with, config: @config).map do |attachment|
             raise UnsupportedAttachmentError, attachment.mime_type unless attachment.image?
 
-            Protocols::ChatCompletions::Media.format_image(attachment)
+            Protocols::ChatCompletions::Media.render_image(attachment)
           end
         end
 
-        def validate_paint_inputs!(with:, mask:) # rubocop:disable Lint/UnusedMethodArgument
+        def validate_paint_inputs!(mask:, **)
           raise UnsupportedAttachmentError, 'image mask' unless mask.nil?
         end
 

data/lib/ruby_llm/providers/openrouter/judgments.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenRouter
+      # OpenRouter's dialect of the System One API: the Decisions route, media
+      # parts inside the state, and the exact cost of each judgment.
+      module Judgments
+        module_function
+
+        def judgment_url
+          '../alpha/decisions'
+        end
+
+        def render_judgment_payload(input, questions:, model:, with: [], provider_options: {})
+          parts = with.map { |attachment| render_judgment_part(attachment) }
+          super(render_judgment_state(input, parts), questions:, model:, provider_options:)
+        end
+
+        def render_judgment_state(input, parts)
+          return input if parts.empty?
+          return parts if input.nil?
+
+          input.is_a?(Array) ? input + parts : [input, *parts]
+        end
+
+        def render_judgment_part(attachment)
+          raise UnsupportedAttachmentError, attachment.mime_type if attachment.provider_file?
+
+          case attachment.type
+          when :image
+            Protocols::ChatCompletions::Media.with_image_detail(
+              { type: 'image_url', image_url: { url: attachment.for_llm } }, attachment
+            )
+          when :audio then Protocols::ChatCompletions::Media.render_audio(attachment)
+          when :video then { type: 'video_url', video_url: { url: attachment.for_llm } }
+          else raise UnsupportedAttachmentError, attachment.mime_type
+          end
+        end
+
+        def reported_cost(usage)
+          usage['cost']
+        end
+      end
+    end
+  end
+end

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

@@ -12,19 +12,19 @@ module RubyLLM
           attachment.video? || Protocols::ChatCompletions::Media.supported_attachment?(attachment)
         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 == :video
-              format_video(attachment)
+              render_video(attachment)
             else
-              Protocols::ChatCompletions::Media.format_attachment(
+              Protocols::ChatCompletions::Media.render_attachment(
                 attachment, document_attachments: :pdf, image_attachments: true, audio_attachments: true
               )
             end
           end
         end
 
-        def format_video(video)
+        def render_video(video)
           {
             type: 'video_url',
             video_url: {

data/lib/ruby_llm/providers/openrouter/models.rb

@@ -4,8 +4,8 @@ module RubyLLM
   module Providers
     class OpenRouter
       # Models methods of the OpenRouter API integration. Chat models come
-      # from the main catalog; embedding, speech, transcription, and image
-      # models live in separate catalogs that are merged in.
+      # from the main catalog; embedding, speech, transcription, image, and
+      # decision models live in separate catalogs that are merged in.
       module Models
         CATALOG_URLS = [
           'models',
@@ -13,18 +13,26 @@ module RubyLLM
           'models?output_modalities=speech',
           'models?output_modalities=transcription',
           'models?output_modalities=rerank',
+          'models?output_modalities=decisions',
           'images/models'
         ].freeze
 
         OUTPUT_MODALITY_MAP = {
           'speech' => 'audio',
-          'transcription' => 'text'
+          'transcription' => 'text',
+          'decisions' => 'judgment'
         }.freeze
 
         CAPABILITY_BY_OUTPUT_MODALITY = {
           'speech' => 'speech_generation',
           'transcription' => 'transcription',
-          'image' => 'image_generation'
+          'image' => 'image_generation',
+          'decisions' => 'judgment'
+        }.freeze
+
+        CAPABILITIES_BY_INPUT_MODALITY = {
+          'image' => %w[vision],
+          'video' => %w[vision video]
         }.freeze
 
         CAPABILITY_PARAMETERS = {
@@ -71,7 +79,9 @@ module RubyLLM
             end
 
             capabilities = supported_parameters_to_capabilities(model_data['supported_parameters']) |
+                           input_modality_capabilities(modalities[:input]) |
                            output_modalities.filter_map { |modality| CAPABILITY_BY_OUTPUT_MODALITY[modality] }
+            capabilities -= ['streaming'] if output_modalities.include?('decisions')
 
             Model.new(
               id: model_data['id'],
@@ -97,14 +107,16 @@ module RubyLLM
           end
         end
 
+        def input_modality_capabilities(input_modalities)
+          input_modalities.flat_map { |modality| CAPABILITIES_BY_INPUT_MODALITY.fetch(modality, []) }.uniq
+        end
+
         def supported_parameters_to_capabilities(params)
           return [] unless params
 
-          capabilities = ['streaming'] + CAPABILITY_PARAMETERS.filter_map do |capability, parameters|
+          ['streaming'] + CAPABILITY_PARAMETERS.filter_map do |capability, parameters|
             capability if parameters.any? { |parameter| params.include?(parameter) }
           end
-          capabilities << 'predicted_outputs' if params.include?('logit_bias') && params.include?('top_k')
-          capabilities
         end
       end
     end

data/lib/ruby_llm/providers/openrouter/streaming.rb

@@ -16,11 +16,11 @@ module RubyLLM
           Chunk.new(
             role: :assistant,
             model: data['model'],
-            content: delta['content'],
-            citations: extract_chunk_citations(delta, data),
+            content: delta['content'] || delta['refusal'],
+            citations: parse_chunk_citations(delta, data),
             thinking: Thinking.build(
-              text: extract_thinking_text(delta),
-              signature: extract_thinking_signature(delta)
+              text: parse_thinking_text(delta),
+              signature: parse_thinking_signature(delta)
             ),
             raw_reasoning: accumulate_raw_reasoning(delta['reasoning_details']),
             tool_calls: parse_tool_calls(delta['tool_calls'], parse_arguments: false, stream_keys: true),

data/lib/ruby_llm/providers/openrouter/videos.rb

@@ -36,7 +36,7 @@ module RubyLLM
           "videos/#{job.id}"
         end
 
-        def parse_video_job_status(response, job:) # rubocop:disable Lint/UnusedMethodArgument
+        def parse_video_job_status(response, **)
           body = response.body
           status = job_status(body)
           state = { status: status, raw: body, reported_cost: reported_cost(body['usage'] || {}) }