ruby_llm 1.13.2 → 1.16.0

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

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'faraday'
+require 'stringio'
+
 module RubyLLM
   module Providers
     class OpenAI
@@ -7,30 +10,79 @@ module RubyLLM
       module Images
         module_function
 
-        def images_url
-          'images/generations'
+        def images_url(with: nil, mask: nil)
+          editing?(with, mask) ? 'images/edits' : 'images/generations'
         end
 
-        def render_image_payload(prompt, model:, size:)
+        def render_image_payload(prompt, model:, size:, with: nil, mask: nil, params: {}) # rubocop:disable Metrics/ParameterLists
+          return render_edit_payload(prompt, model:, with:, mask:, params:) if editing?(with, mask)
+
           {
             model: model,
             prompt: prompt,
             n: 1,
             size: size
-          }
+          }.merge(params)
         end
 
         def parse_image_response(response, model:)
           data = response.body
-          image_data = data['data'].first
+          image_data = Array(data['data']).first
+
+          raise Error.new(nil, 'Unexpected response format from OpenAI image API') unless image_data
 
           Image.new(
             url: image_data['url'],
             mime_type: 'image/png', # DALL-E typically returns PNGs
             revised_prompt: image_data['revised_prompt'],
             model_id: model,
-            data: image_data['b64_json']
+            data: image_data['b64_json'],
+            usage: data['usage'] || {}
+          )
+        end
+
+        def validate_paint_inputs!(with:, mask:)
+          return unless editing?(with, mask)
+
+          raise ArgumentError, 'with: is required when mask: is provided' if mask && !attachments?(with)
+        end
+
+        def render_edit_payload(prompt, model:, with:, mask:, params:)
+          payload = params.merge(
+            model: model,
+            prompt: prompt,
+            image: build_upload_parts(with),
+            n: 1
           )
+          payload[:mask] = build_upload_part(mask) if mask
+          payload
+        end
+
+        def build_upload_parts(sources)
+          Array(sources).filter_map do |source|
+            next if blank_attachment?(source)
+
+            build_upload_part(source)
+          end
+        end
+
+        def build_upload_part(source)
+          attachment = Attachment.new(source)
+          raise UnsupportedAttachmentError, attachment.mime_type unless attachment.image?
+
+          Faraday::UploadIO.new(StringIO.new(attachment.content), attachment.mime_type, attachment.filename)
+        end
+
+        def editing?(with, mask)
+          attachments?(with) || !mask.nil?
+        end
+
+        def attachments?(value)
+          Array(value).any? { |item| !blank_attachment?(item) }
+        end
+
+        def blank_attachment?(value)
+          value.nil? || (value.is_a?(String) && value.strip.empty?)
         end
       end
     end

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

@@ -7,7 +7,7 @@ module RubyLLM
       module Media
         module_function
 
-        def format_content(content) # rubocop:disable Metrics/PerceivedComplexity
+        def format_content(content, document_attachments: :pdf, image_attachments: true, audio_attachments: true)
           if content.is_a?(RubyLLM::Content::Raw)
             value = content.value
             return value.is_a?(Hash) ? value.to_json : value
@@ -19,23 +19,36 @@ module RubyLLM
           parts << format_text(content.text) if content.text
 
           content.attachments.each do |attachment|
-            case attachment.type
-            when :image
-              parts << format_image(attachment)
-            when :pdf
-              parts << format_pdf(attachment)
-            when :audio
-              parts << format_audio(attachment)
-            when :text
-              parts << format_text_file(attachment)
-            else
-              raise UnsupportedAttachmentError, attachment.type
-            end
+            parts << format_attachment(
+              attachment,
+              document_attachments:,
+              image_attachments:,
+              audio_attachments:
+            )
           end
 
           parts
         end
 
+        def format_attachment(attachment, document_attachments:, image_attachments:, audio_attachments:)
+          case attachment.type
+          when :image
+            raise UnsupportedAttachmentError, attachment.mime_type unless image_attachments
+
+            format_image(attachment)
+          when :audio
+            raise UnsupportedAttachmentError, attachment.mime_type unless audio_attachments
+
+            format_audio(attachment)
+          when :pdf, :document
+            format_document_attachment(attachment, document_attachments)
+          when :text
+            format_text_file(attachment)
+          else
+            raise UnsupportedAttachmentError, attachment.mime_type
+          end
+        end
+
         def format_image(image)
           {
             type: 'image_url',
@@ -45,16 +58,20 @@ module RubyLLM
           }
         end
 
-        def format_pdf(pdf)
+        def format_document(document)
           {
             type: 'file',
             file: {
-              filename: pdf.filename,
-              file_data: pdf.for_llm
+              filename: document.filename,
+              file_data: document.for_llm
             }
           }
         end
 
+        def format_pdf(pdf)
+          format_document(pdf)
+        end
+
         def format_text_file(text_file)
           {
             type: 'text',
@@ -78,6 +95,13 @@ module RubyLLM
             text: text
           }
         end
+
+        def format_document_attachment(attachment, strategy)
+          return format_document(attachment) if strategy == :all
+          return format_document(attachment) if strategy == :pdf && attachment.pdf?
+
+          raise UnsupportedAttachmentError, attachment.mime_type
+        end
       end
     end
   end

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

@@ -17,14 +17,12 @@ module RubyLLM
 
             Model::Info.new(
               id: model_id,
-              name: capabilities.format_display_name(model_id),
+              name: model_id,
               provider: slug,
-              family: capabilities.model_family(model_id),
               created_at: model_data['created'] ? Time.at(model_data['created']) : nil,
               context_window: capabilities.context_window_for(model_id),
               max_output_tokens: capabilities.max_tokens_for(model_id),
-              modalities: capabilities.modalities_for(model_id),
-              capabilities: capabilities.capabilities_for(model_id),
+              capabilities: capabilities.critical_capabilities_for(model_id),
               pricing: capabilities.pricing_for(model_id),
               metadata: {
                 object: model_data['object'],

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module RubyLLM
   module Providers
     class OpenAI
@@ -13,7 +15,6 @@ module RubyLLM
 
         def build_chunk(data)
           usage = data['usage'] || {}
-          cached_tokens = usage.dig('prompt_tokens_details', 'cached_tokens')
           delta = data.dig('choices', 0, 'delta') || {}
           content_source = delta['content'] || data.dig('choices', 0, 'message', 'content')
           content, thinking_from_blocks = OpenAI::Chat.extract_content_and_thinking(content_source)
@@ -27,11 +28,11 @@ module RubyLLM
               signature: delta['reasoning_signature']
             ),
             tool_calls: parse_tool_calls(delta['tool_calls'], parse_arguments: false),
-            input_tokens: usage['prompt_tokens'],
-            output_tokens: usage['completion_tokens'],
-            cached_tokens: cached_tokens,
-            cache_creation_tokens: 0,
-            thinking_tokens: usage.dig('completion_tokens_details', 'reasoning_tokens')
+            input_tokens: OpenAI::Chat.input_tokens(usage),
+            output_tokens: OpenAI::Chat.output_tokens(usage),
+            cached_tokens: OpenAI::Chat.cache_read_tokens(usage),
+            cache_creation_tokens: OpenAI::Chat.cache_write_tokens(usage),
+            thinking_tokens: OpenAI::Chat.thinking_tokens(usage)
           )
         end
 

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module RubyLLM
   module Providers
     class OpenAI

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

@@ -60,6 +60,7 @@ module RubyLLM
             language: data['language'],
             duration: data['duration'],
             segments: data['segments'],
+            words: data['words'],
             input_tokens: usage['input_tokens'] || usage['prompt_tokens'],
             output_tokens: usage['output_tokens'] || usage['completion_tokens']
           )

data/lib/ruby_llm/providers/openai.rb

@@ -35,6 +35,16 @@ module RubyLLM
           OpenAI::Capabilities
         end
 
+        def configuration_options
+          %i[
+            openai_api_key
+            openai_api_base
+            openai_organization_id
+            openai_project_id
+            openai_use_system_role
+          ]
+        end
+
         def configuration_requirements
           %i[openai_api_key]
         end

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

@@ -52,7 +52,7 @@ module RubyLLM
 
         def parse_completion_response(response)
           data = response.body
-          return if data.empty?
+          return if data.nil? || data.empty?
 
           raise Error.new(response, data.dig('error', 'message')) if data.dig('error', 'message')
 
@@ -60,8 +60,7 @@ module RubyLLM
           return unless message_data
 
           usage = data['usage'] || {}
-          cached_tokens = usage.dig('prompt_tokens_details', 'cached_tokens')
-          thinking_tokens = usage.dig('completion_tokens_details', 'reasoning_tokens')
+          thinking_tokens = thinking_tokens(usage)
           thinking_text = extract_thinking_text(message_data)
           thinking_signature = extract_thinking_signature(message_data)
 
@@ -70,27 +69,56 @@ module RubyLLM
             content: message_data['content'],
             thinking: Thinking.build(text: thinking_text, signature: thinking_signature),
             tool_calls: OpenAI::Tools.parse_tool_calls(message_data['tool_calls']),
-            input_tokens: usage['prompt_tokens'],
-            output_tokens: usage['completion_tokens'],
-            cached_tokens: cached_tokens,
-            cache_creation_tokens: 0,
+            input_tokens: input_tokens(usage),
+            output_tokens: output_tokens(usage),
+            cached_tokens: cache_read_tokens(usage),
+            cache_creation_tokens: cache_write_tokens(usage),
             thinking_tokens: thinking_tokens,
             model_id: data['model'],
             raw: response
           )
         end
 
+        def input_tokens(usage)
+          return usage['prompt_cache_miss_tokens'] if usage['prompt_cache_miss_tokens']
+
+          prompt_tokens = usage['prompt_tokens']
+          return unless prompt_tokens
+
+          [prompt_tokens.to_i - cache_read_tokens(usage).to_i - cache_write_tokens(usage).to_i, 0].max
+        end
+
+        def output_tokens(usage)
+          OpenAI::Chat.output_tokens(usage)
+        end
+
+        def cache_read_tokens(usage)
+          usage.dig('prompt_tokens_details', 'cached_tokens') || usage['prompt_cache_hit_tokens']
+        end
+
+        def cache_write_tokens(usage)
+          usage.dig('prompt_tokens_details', 'cache_write_tokens') || 0
+        end
+
+        def thinking_tokens(usage)
+          OpenAI::Chat.thinking_tokens(usage)
+        end
+
         def format_messages(messages)
           messages.map do |msg|
             {
               role: format_role(msg.role),
-              content: OpenAI::Media.format_content(msg.content),
+              content: format_content(msg.content),
               tool_calls: OpenAI::Tools.format_tool_calls(msg.tool_calls),
               tool_call_id: msg.tool_call_id
             }.compact.merge(format_thinking(msg))
           end
         end
 
+        def format_content(content)
+          OpenAI::Media.format_content(content)
+        end
+
         def format_role(role)
           case role
           when :system

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

@@ -9,12 +9,12 @@ module RubyLLM
       module Images
         module_function
 
-        def images_url
+        def images_url(with: nil, mask: nil) # rubocop:disable Lint/UnusedMethodArgument
           'chat/completions'
         end
 
-        def render_image_payload(prompt, model:, size:)
-          RubyLLM.logger.debug "Ignoring size #{size}. OpenRouter image generation does not support size parameter."
+        def render_image_payload(prompt, model:, size:, with: nil, mask: nil, params: {}) # rubocop:disable Lint/UnusedMethodArgument,Metrics/ParameterLists
+          RubyLLM.logger.debug { "Ignoring size #{size}. OpenRouter image generation does not support size parameter." }
           {
             model: model,
             messages: [

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

@@ -23,7 +23,7 @@ module RubyLLM
             pricing_types = {
               prompt: :input_per_million,
               completion: :output_per_million,
-              input_cache_read: :cached_input_per_million,
+              input_cache_read: :cache_read_input_per_million,
               internal_reasoning: :reasoning_output_per_million
             }
 

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

@@ -13,7 +13,6 @@ module RubyLLM
 
         def build_chunk(data)
           usage = data['usage'] || {}
-          cached_tokens = usage.dig('prompt_tokens_details', 'cached_tokens')
           delta = data.dig('choices', 0, 'delta') || {}
 
           Chunk.new(
@@ -25,11 +24,11 @@ module RubyLLM
               signature: extract_thinking_signature(delta)
             ),
             tool_calls: OpenAI::Tools.parse_tool_calls(delta['tool_calls'], parse_arguments: false),
-            input_tokens: usage['prompt_tokens'],
-            output_tokens: usage['completion_tokens'],
-            cached_tokens: cached_tokens,
-            cache_creation_tokens: 0,
-            thinking_tokens: usage.dig('completion_tokens_details', 'reasoning_tokens')
+            input_tokens: OpenRouter::Chat.input_tokens(usage),
+            output_tokens: OpenRouter::Chat.output_tokens(usage),
+            cached_tokens: OpenRouter::Chat.cache_read_tokens(usage),
+            cache_creation_tokens: OpenRouter::Chat.cache_write_tokens(usage),
+            thinking_tokens: OpenRouter::Chat.thinking_tokens(usage)
           )
         end
 

data/lib/ruby_llm/providers/openrouter.rb

@@ -49,6 +49,10 @@ module RubyLLM
       end
 
       class << self
+        def configuration_options
+          %i[openrouter_api_key openrouter_api_base]
+        end
+
         def configuration_requirements
           %i[openrouter_api_key]
         end

data/lib/ruby_llm/providers/perplexity/capabilities.rb

@@ -3,63 +3,55 @@
 module RubyLLM
   module Providers
     class Perplexity
-      # Determines capabilities and pricing for Perplexity models
+      # Provider-level capability checks and narrow registry fallbacks.
       module Capabilities
         module_function
 
-        def context_window_for(model_id)
-          case model_id
-          when /sonar-pro/ then 200_000
-          else 128_000
-          end
-        end
+        PRICES = {
+          sonar: { input: 1.0, output: 1.0 },
+          sonar_pro: { input: 3.0, output: 15.0 },
+          sonar_reasoning: { input: 1.0, output: 5.0 },
+          sonar_reasoning_pro: { input: 2.0, output: 8.0 },
+          sonar_deep_research: {
+            input: 2.0,
+            output: 8.0,
+            reasoning_output: 3.0
+          }
+        }.freeze
 
-        def max_tokens_for(model_id)
-          case model_id
-          when /sonar-(?:pro|reasoning-pro)/ then 8_192
-          else 4_096
-          end
+        def supports_tool_choice?(_model_id)
+          false
         end
 
-        def input_price_for(model_id)
-          PRICES.dig(model_family(model_id), :input) || 1.0
+        def supports_tool_parallel_control?(_model_id)
+          false
         end
 
-        def output_price_for(model_id)
-          PRICES.dig(model_family(model_id), :output) || 1.0
+        def context_window_for(model_id)
+          model_id.match?(/sonar-pro/) ? 200_000 : 128_000
         end
 
-        def supports_vision?(model_id)
-          case model_id
-          when /sonar-reasoning-pro/, /sonar-reasoning/, /sonar-pro/, /sonar/ then true
-          else false
-          end
+        def max_tokens_for(model_id)
+          model_id.match?(/sonar-(?:pro|reasoning-pro)/) ? 8_192 : 4_096
         end
 
-        def supports_functions?(_model_id)
-          false
+        def critical_capabilities_for(model_id)
+          capabilities = []
+          capabilities << 'vision' if model_id.match?(/sonar(?:-pro|-reasoning(?:-pro)?)?$/)
+          capabilities << 'reasoning' if model_id.match?(/reasoning|deep-research/)
+          capabilities
         end
 
-        def supports_json_mode?(_model_id)
-          true
-        end
+        def pricing_for(model_id)
+          prices = PRICES.fetch(model_family(model_id), { input: 1.0, output: 1.0 })
 
-        def format_display_name(model_id)
-          case model_id
-          when 'sonar' then 'Sonar'
-          when 'sonar-pro' then 'Sonar Pro'
-          when 'sonar-reasoning' then 'Sonar Reasoning'
-          when 'sonar-reasoning-pro' then 'Sonar Reasoning Pro'
-          when 'sonar-deep-research' then 'Sonar Deep Research'
-          else
-            model_id.split('-')
-                    .map(&:capitalize)
-                    .join(' ')
-          end
-        end
+          standard = {
+            input_per_million: prices[:input],
+            output_per_million: prices[:output]
+          }
+          standard[:reasoning_output_per_million] = prices[:reasoning_output] if prices[:reasoning_output]
 
-        def model_type(_model_id)
-          'chat'
+          { text_tokens: { standard: standard } }
         end
 
         def model_family(model_id)
@@ -73,64 +65,7 @@ module RubyLLM
           end
         end
 
-        def modalities_for(_model_id)
-          {
-            input: ['text'],
-            output: ['text']
-          }
-        end
-
-        def capabilities_for(model_id)
-          capabilities = %w[streaming json_mode]
-          capabilities << 'vision' if supports_vision?(model_id)
-          capabilities
-        end
-
-        def pricing_for(model_id)
-          family = model_family(model_id)
-          prices = PRICES.fetch(family, { input: 1.0, output: 1.0 })
-
-          standard_pricing = {
-            input_per_million: prices[:input],
-            output_per_million: prices[:output]
-          }
-
-          standard_pricing[:citation_per_million] = prices[:citation] if prices[:citation]
-          standard_pricing[:reasoning_per_million] = prices[:reasoning] if prices[:reasoning]
-          standard_pricing[:search_per_thousand] = prices[:search_queries] if prices[:search_queries]
-
-          {
-            text_tokens: {
-              standard: standard_pricing
-            }
-          }
-        end
-
-        PRICES = {
-          sonar: {
-            input: 1.0,
-            output: 1.0
-          },
-          sonar_pro: {
-            input: 3.0,
-            output: 15.0
-          },
-          sonar_reasoning: {
-            input: 1.0,
-            output: 5.0
-          },
-          sonar_reasoning_pro: {
-            input: 2.0,
-            output: 8.0
-          },
-          sonar_deep_research: {
-            input: 2.0,
-            output: 8.0,
-            citation: 2.0,
-            reasoning: 3.0,
-            search_queries: 5.0
-          }
-        }.freeze
+        module_function :context_window_for, :max_tokens_for, :critical_capabilities_for, :pricing_for, :model_family
       end
     end
   end

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

@@ -10,6 +10,17 @@ module RubyLLM
         def format_role(role)
           role.to_s
         end
+
+        def format_messages(messages)
+          messages.map do |msg|
+            {
+              role: format_role(msg.role),
+              content: Perplexity::Media.format_content(msg.content),
+              tool_calls: OpenAI::Tools.format_tool_calls(msg.tool_calls),
+              tool_call_id: msg.tool_call_id
+            }.compact.merge(OpenAI::Chat.format_thinking(msg))
+          end
+        end
       end
     end
   end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Perplexity
+      # Handles Perplexity Sonar media content.
+      module Media
+        module_function
+
+        SUPPORTED_DOCUMENT_EXTENSIONS = %w[pdf doc docx txt rtf].freeze
+
+        def format_content(content) # rubocop:disable Metrics/PerceivedComplexity
+          if content.is_a?(RubyLLM::Content::Raw)
+            value = content.value
+            return value.is_a?(Hash) ? value.to_json : value
+          end
+          return content.to_json if content.is_a?(Hash) || content.is_a?(Array)
+          return content unless content.is_a?(Content)
+
+          parts = []
+          parts << OpenAI::Media.format_text(content.text) if content.text
+
+          content.attachments.each do |attachment|
+            case attachment.type
+            when :image
+              parts << OpenAI::Media.format_image(attachment)
+            when :pdf, :document
+              parts << format_document(attachment)
+            when :text
+              parts << format_text_attachment(attachment)
+            else
+              raise UnsupportedAttachmentError, attachment.mime_type
+            end
+          end
+
+          parts
+        end
+
+        def format_document(attachment)
+          raise UnsupportedAttachmentError, attachment.mime_type unless supported_file?(attachment)
+
+          {
+            type: 'file_url',
+            file_url: {
+              url: attachment.url? ? attachment.source.to_s : attachment.encoded
+            }
+          }
+        end
+
+        def format_text_attachment(attachment)
+          OpenAI::Media.format_text_file(attachment)
+        end
+
+        def supported_file?(attachment)
+          return true if attachment.pdf?
+
+          SUPPORTED_DOCUMENT_EXTENSIONS.include?(attachment.extension)
+        end
+      end
+    end
+  end
+end