ruby_llm 1.14.1 → 1.16.0

data/lib/ruby_llm/cost.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Represents the cost of token usage for a model response.
+  class Cost
+    COMPONENTS = %i[input output cache_read cache_write thinking].freeze
+    PER_MILLION = 1_000_000.0
+
+    attr_reader :tokens, :model, :category
+
+    def self.aggregate(costs)
+      costs = costs.compact.select(&:tokens?)
+      return new(amounts: {}, has_tokens: false) if costs.empty?
+
+      missing = COMPONENTS.select do |component|
+        costs.any? { |cost| cost.missing?(component) }
+      end
+
+      amounts = COMPONENTS.to_h do |component|
+        [component, missing.include?(component) ? nil : aggregate_component(costs, component)]
+      end
+
+      new(amounts:, missing:, has_tokens: true)
+    end
+
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(tokens: nil, model: nil, amounts: nil, missing: [], has_tokens: nil, category: :text_tokens,
+                   input_details: nil)
+      @tokens = tokens
+      @model = normalize_model(model)
+      @amounts = amounts
+      @missing = missing
+      @has_tokens = has_tokens
+      @category = category.to_sym
+      @input_details = input_details
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    def input
+      amount_for(:input)
+    end
+
+    def output
+      amount_for(:output)
+    end
+
+    def cache_read
+      amount_for(:cache_read)
+    end
+
+    def cache_write
+      amount_for(:cache_write)
+    end
+
+    def thinking
+      amount_for(:thinking)
+    end
+
+    alias reasoning thinking
+
+    alias cached_input cache_read
+    alias cache_creation cache_write
+
+    def total
+      return nil unless tokens?
+      return nil if COMPONENTS.any? { |component| missing?(component) }
+
+      costs = COMPONENTS.filter_map { |component| public_send(component) }
+      return nil if costs.empty?
+
+      costs.sum
+    end
+
+    def to_h
+      {
+        input: input,
+        output: output,
+        cache_read: cache_read,
+        cache_write: cache_write,
+        thinking: thinking,
+        total: total
+      }.compact
+    end
+
+    def tokens?
+      return @has_tokens unless @has_tokens.nil?
+
+      COMPONENTS.any? { |component| !tokens_for(component).nil? }
+    end
+
+    def missing?(component)
+      return @missing.include?(component) if aggregate?
+      return image_input_missing? if component == :input && detailed_image_input?
+      return false if component == :thinking && !thinking_priced_separately?
+
+      tokens = tokens_for(component)
+      tokens.to_i.positive? && price_for(component).nil?
+    end
+
+    private_class_method def self.aggregate_component(costs, component)
+      values = costs.filter_map { |cost| cost.public_send(component) }
+      values.empty? ? nil : values.sum
+    end
+
+    private
+
+    def amount_for(component)
+      return @amounts[component] if aggregate?
+      return image_input_amount if component == :input && detailed_image_input?
+
+      token_count = tokens_for(component)
+      return nil if token_count.nil?
+
+      token_count = token_count.to_i
+      return 0.0 if token_count.zero?
+
+      price = price_for(component)
+      return nil unless price
+
+      token_count * price / PER_MILLION
+    end
+
+    def aggregate?
+      !@amounts.nil?
+    end
+
+    def tokens_for(component)
+      return unless tokens
+
+      case component
+      when :input
+        tokens.input
+      when :output
+        tokens.output
+      when :cache_read
+        tokens.cache_read
+      when :cache_write
+        tokens.cache_write
+      when :thinking
+        tokens.thinking if thinking_priced_separately?
+      end
+    end
+
+    def price_for(component)
+      case component
+      when :input
+        text_pricing.input
+      when :output
+        output_pricing.output
+      when :cache_read
+        text_pricing.cache_read_input
+      when :cache_write
+        text_pricing.cache_write_input
+      when :thinking
+        text_pricing.reasoning_output
+      end
+    end
+
+    def text_pricing
+      model&.pricing&.text_tokens || RubyLLM::Model::PricingCategory.new
+    end
+
+    def image_pricing
+      model&.pricing&.images || RubyLLM::Model::PricingCategory.new
+    end
+
+    def output_pricing
+      image_cost? && image_pricing.output ? image_pricing : text_pricing
+    end
+
+    def image_cost?
+      %i[image images].include?(category)
+    end
+
+    def detailed_image_input?
+      image_cost? && @input_details.is_a?(Hash) && image_input_parts.any? { |_, tokens, _| !tokens.nil? }
+    end
+
+    def image_input_amount
+      return nil if image_input_missing?
+
+      image_input_parts.filter_map do |_, token_count, price|
+        next if token_count.nil? || token_count.to_i.zero?
+
+        token_count.to_i * price / PER_MILLION
+      end.sum
+    end
+
+    def image_input_missing?
+      image_input_parts.any? do |_, token_count, price|
+        token_count.to_i.positive? && price.nil?
+      end
+    end
+
+    def image_input_parts
+      [
+        [:text, input_detail('text_tokens'), text_pricing.input],
+        [:image, input_detail('image_tokens'), image_pricing.input || text_pricing.input]
+      ]
+    end
+
+    def input_detail(key)
+      @input_details[key] || @input_details[key.to_sym]
+    end
+
+    def thinking_priced_separately?
+      reasoning_price = text_pricing.reasoning_output
+      return false unless reasoning_price
+
+      output_price = text_pricing.output
+      output_price.nil? || reasoning_price != output_price
+    end
+
+    def normalize_model(model)
+      return RubyLLM.models.find(model.to_s) if model.is_a?(String) || model.is_a?(Symbol)
+      return model.to_llm if model.respond_to?(:to_llm)
+      return model if model.respond_to?(:pricing)
+
+      nil
+    rescue ModelNotFoundError
+      nil
+    end
+  end
+end

data/lib/ruby_llm/deprecator.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Owns RubyLLM deprecation warnings so applications and tests can decide how
+  # aggressively to handle compatibility paths.
+  class Deprecator
+    def warn(message)
+      case RubyLLM.config.deprecation_behavior
+      when :silence
+        nil
+      when :raise
+        raise DeprecationError, message
+      else
+        RubyLLM.logger.warn(message)
+      end
+    end
+
+    def deprecate(name, replacement:, removal:)
+      warn("#{name} is deprecated and will be removed in RubyLLM #{removal}. Use #{replacement} instead.")
+    end
+  end
+
+  class DeprecationError < StandardError; end
+end

data/lib/ruby_llm/embedding.rb

@@ -23,7 +23,37 @@ module RubyLLM
                                                        config: config)
       model_id = model.id
 
-      provider_instance.embed(text, model: model_id, dimensions:)
+      payload = {
+        provider: provider_instance.slug,
+        provider_class: provider_instance.class.name,
+        model: model_id,
+        model_info: model,
+        input: text,
+        dimensions: dimensions
+      }
+
+      RubyLLM.instrument('embedding.ruby_llm', payload, config: config) do |event|
+        result = provider_instance.embed(text, model: model_id, dimensions:)
+        event[:result] = result
+        event[:response_model] = result.model
+        event[:input_tokens] = result.input_tokens
+        event[:embedding_dimensions] = vector_dimensions(result.vectors)
+        event[:embedding_count] = embedding_count(result.vectors)
+        result
+      end
+    end
+
+    def self.vector_dimensions(vectors)
+      return unless vectors.is_a?(Array)
+
+      vector = vectors.first.is_a?(Array) ? vectors.first : vectors
+      vector.length if vector.respond_to?(:length)
+    end
+
+    def self.embedding_count(vectors)
+      return unless vectors.is_a?(Array)
+
+      vectors.first.is_a?(Array) ? vectors.size : 1
     end
   end
 end

data/lib/ruby_llm/error.rb

@@ -23,7 +23,17 @@ module RubyLLM
   class InvalidRoleError < StandardError; end
   class InvalidToolChoiceError < StandardError; end
   class ModelNotFoundError < StandardError; end
-  class UnsupportedAttachmentError < StandardError; end
+
+  # Raised when RubyLLM cannot format an attachment for the selected provider.
+  class UnsupportedAttachmentError < StandardError
+    GUIDANCE = 'Consider using a model that supports this attachment type.'
+
+    def initialize(type = nil)
+      message = 'Unsupported attachment type'
+      message = "#{message}: #{type}" if type
+      super("#{message}. #{GUIDANCE}")
+    end
+  end
 
   # Error classes for different HTTP status codes
   class BadRequestError < Error; end
@@ -35,78 +45,4 @@ module RubyLLM
   class ServerError < Error; end
   class ServiceUnavailableError < Error; end
   class UnauthorizedError < Error; end
-
-  # Faraday middleware that maps provider-specific API errors to RubyLLM errors.
-  class ErrorMiddleware < Faraday::Middleware
-    def initialize(app, options = {})
-      super(app)
-      @provider = options[:provider]
-    end
-
-    def call(env)
-      @app.call(env).on_complete do |response|
-        self.class.parse_error(provider: @provider, response: response)
-      end
-    end
-
-    class << self
-      CONTEXT_LENGTH_PATTERNS = [
-        /context length/i,
-        /context window/i,
-        /maximum context/i,
-        /request too large/i,
-        /too many tokens/i,
-        /token count exceeds/i,
-        /input[_\s-]?token/i,
-        /input or output tokens? must be reduced/i,
-        /reduce the length of messages/i
-      ].freeze
-
-      def parse_error(provider:, response:) # rubocop:disable Metrics/PerceivedComplexity
-        message = provider&.parse_error(response)
-
-        case response.status
-        when 200..399
-          message
-        when 400
-          if context_length_exceeded?(message)
-            raise ContextLengthExceededError.new(response, message || 'Context length exceeded')
-          end
-
-          raise BadRequestError.new(response, message || 'Invalid request - please check your input')
-        when 401
-          raise UnauthorizedError.new(response, message || 'Invalid API key - check your credentials')
-        when 402
-          raise PaymentRequiredError.new(response, message || 'Payment required - please top up your account')
-        when 403
-          raise ForbiddenError.new(response,
-                                   message || 'Forbidden - you do not have permission to access this resource')
-        when 429
-          if context_length_exceeded?(message)
-            raise ContextLengthExceededError.new(response, message || 'Context length exceeded')
-          end
-
-          raise RateLimitError.new(response, message || 'Rate limit exceeded - please wait a moment')
-        when 500
-          raise ServerError.new(response, message || 'API server error - please try again')
-        when 502..504
-          raise ServiceUnavailableError.new(response, message || 'API server unavailable - please try again later')
-        when 529
-          raise OverloadedError.new(response, message || 'Service overloaded - please try again later')
-        else
-          raise Error.new(response, message || 'An unknown error occurred')
-        end
-      end
-
-      private
-
-      def context_length_exceeded?(message)
-        return false if message.to_s.empty?
-
-        CONTEXT_LENGTH_PATTERNS.any? { |pattern| message.match?(pattern) }
-      end
-    end
-  end
 end
-
-Faraday::Middleware.register_middleware(llm_errors: RubyLLM::ErrorMiddleware)

data/lib/ruby_llm/error_middleware.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'ruby_llm/error'
+
+module RubyLLM
+  # Faraday middleware that maps provider-specific API errors to RubyLLM errors.
+  class ErrorMiddleware < Faraday::Middleware
+    def initialize(app, options = {})
+      super(app)
+      @provider = options[:provider]
+    end
+
+    def call(env)
+      @app.call(env).on_complete do |response|
+        self.class.parse_error(provider: @provider, response: response)
+      end
+    end
+
+    class << self
+      CONTEXT_LENGTH_PATTERNS = [
+        /context length/i,
+        /context window/i,
+        /maximum context/i,
+        /request too large/i,
+        /too many tokens/i,
+        /token count exceeds/i,
+        /input[_\s-]?token/i,
+        /input or output tokens? must be reduced/i,
+        /reduce the length of messages/i,
+        /prompt is too long/i
+      ].freeze
+
+      def parse_error(provider:, response:) # rubocop:disable Metrics/PerceivedComplexity
+        message = provider&.parse_error(response)
+
+        case response.status
+        when 200..399
+          message
+        when 400
+          if context_length_exceeded?(message)
+            raise ContextLengthExceededError.new(response, message || 'Context length exceeded')
+          end
+
+          raise BadRequestError.new(response, message || 'Invalid request - please check your input')
+        when 401
+          raise UnauthorizedError.new(response, message || 'Invalid API key - check your credentials')
+        when 402
+          raise PaymentRequiredError.new(response, message || 'Payment required - please top up your account')
+        when 403
+          raise ForbiddenError.new(response,
+                                   message || 'Forbidden - you do not have permission to access this resource')
+        when 429
+          if context_length_exceeded?(message)
+            raise ContextLengthExceededError.new(response, message || 'Context length exceeded')
+          end
+
+          raise RateLimitError.new(response, message || 'Rate limit exceeded - please wait a moment')
+        when 500
+          raise ServerError.new(response, message || 'API server error - please try again')
+        when 502..504
+          raise ServiceUnavailableError.new(response, message || 'API server unavailable - please try again later')
+        when 529
+          raise OverloadedError.new(response, message || 'Service overloaded - please try again later')
+        else
+          raise Error.new(response, message || 'An unknown error occurred')
+        end
+      end
+
+      private
+
+      def context_length_exceeded?(message)
+        return false if message.to_s.empty?
+
+        CONTEXT_LENGTH_PATTERNS.any? { |pattern| message.match?(pattern) }
+      end
+    end
+  end
+end
+
+Faraday::Middleware.register_middleware(llm_errors: RubyLLM::ErrorMiddleware)

data/lib/ruby_llm/image.rb

@@ -1,16 +1,19 @@
 # frozen_string_literal: true
 
+require 'base64'
+
 module RubyLLM
   # Represents a generated image from an AI model.
   class Image
-    attr_reader :url, :data, :mime_type, :revised_prompt, :model_id
+    attr_reader :url, :data, :mime_type, :revised_prompt, :model_id, :usage
 
-    def initialize(url: nil, data: nil, mime_type: nil, revised_prompt: nil, model_id: nil)
+    def initialize(url: nil, data: nil, mime_type: nil, revised_prompt: nil, model_id: nil, usage: {}) # rubocop:disable Metrics/ParameterLists
       @url = url
       @data = data
       @mime_type = mime_type
       @revised_prompt = revised_prompt
       @model_id = model_id
+      @usage = usage
     end
 
     def base64?
@@ -36,14 +39,46 @@ module RubyLLM
                    provider: nil,
                    assume_model_exists: false,
                    size: '1024x1024',
-                   context: nil)
+                   context: nil,
+                   with: nil,
+                   mask: nil,
+                   params: {})
       config = context&.config || RubyLLM.config
       model ||= config.default_image_model
       model, provider_instance = Models.resolve(model, provider: provider, assume_exists: assume_model_exists,
                                                        config: config)
       model_id = model.id
 
-      provider_instance.paint(prompt, model: model_id, size:)
+      provider_instance.paint(prompt, model: model_id, size:, with:, mask:, params:)
+    end
+
+    def tokens
+      @tokens ||= Tokens.build(
+        input: usage_value('input_tokens'),
+        output: usage_value('output_tokens')
+      )
+    end
+
+    def cost
+      Cost.new(tokens:, model: model_info, category: :images, input_details: input_tokens_details)
+    end
+
+    def model_info
+      return unless model_id
+
+      @model_info ||= RubyLLM.models.find(model_id)
+    rescue ModelNotFoundError
+      nil
+    end
+
+    private
+
+    def input_tokens_details
+      usage_value('input_tokens_details')
+    end
+
+    def usage_value(key)
+      usage[key] || usage[key.to_sym]
     end
   end
 end

data/lib/ruby_llm/instrumentation.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Emits structured RubyLLM events without requiring a specific observability
+  # backend. Rails apps can use ActiveSupport::Notifications as the instrumenter.
+  module Instrumentation
+    module_function
+
+    def instrument(name, payload = nil, config: nil, **attributes)
+      payload = build_payload(payload, attributes)
+      instrumenter = instrumenter_for(config)
+      return yield(payload) if block_given? && !instrumenter
+
+      unless instrumenter.respond_to?(:instrument)
+        return yield(payload) if block_given?
+
+        return
+      end
+
+      if block_given?
+        instrumenter.instrument(name, payload) { yield(payload) }
+      else
+        instrumenter.instrument(name, payload)
+      end
+    end
+
+    def build_payload(payload, attributes)
+      payload ||= {}
+      attributes.empty? ? payload : payload.merge(attributes)
+    end
+
+    def instrumenter_for(config)
+      (config || RubyLLM.config).instrumenter
+    end
+  end
+end

data/lib/ruby_llm/message.rb

@@ -64,6 +64,14 @@ module RubyLLM
       tokens&.cache_creation
     end
 
+    def cache_read_tokens
+      tokens&.cache_read
+    end
+
+    def cache_write_tokens
+      tokens&.cache_write
+    end
+
     def thinking_tokens
       tokens&.thinking
     end
@@ -72,6 +80,10 @@ module RubyLLM
       tokens&.thinking
     end
 
+    def cost(model: nil)
+      Cost.new(tokens:, model: model || model_info)
+    end
+
     def to_h
       {
         role: role,
@@ -88,6 +100,14 @@ module RubyLLM
       super - [:@raw]
     end
 
+    def model_info
+      return unless model_id
+
+      @model_info ||= RubyLLM.models.find(model_id)
+    rescue ModelNotFoundError
+      nil
+    end
+
     private
 
     def normalize_content(content, role:, tool_calls:)

data/lib/ruby_llm/mime_type.rb

@@ -27,6 +27,13 @@ module RubyLLM
       type == 'application/pdf'
     end
 
+    def document?(type)
+      return false if pdf?(type) || text?(type)
+
+      DOCUMENT_MIME_TYPES.include?(type) ||
+        DOCUMENT_MIME_PREFIXES.any? { |prefix| type.start_with?(prefix) }
+    end
+
     def text?(type)
       type.start_with?('text/') ||
         TEXT_SUFFIXES.any? { |suffix| type.end_with?(suffix) } ||
@@ -67,5 +74,23 @@ module RubyLLM
       'application/yaml',            # Standard for YAML
       'application/toml'             # TOML configuration files
     ].freeze
+
+    DOCUMENT_MIME_TYPES = [
+      'application/msword',
+      'application/rtf',
+      'application/vnd.apple.keynote',
+      'application/vnd.apple.numbers',
+      'application/vnd.apple.pages',
+      'application/vnd.google-apps.document',
+      'application/vnd.google-apps.presentation',
+      'application/vnd.google-apps.spreadsheet',
+      'application/vnd.ms-excel',
+      'application/vnd.ms-powerpoint'
+    ].freeze
+
+    DOCUMENT_MIME_PREFIXES = [
+      'application/vnd.openxmlformats-officedocument.',
+      'application/vnd.oasis.opendocument.'
+    ].freeze
   end
 end