ruby_llm 1.15.0 → 1.16.0

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,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'base64'
+
 module RubyLLM
   # Represents a generated image from an AI model.
   class Image

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/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

data/lib/ruby_llm/model/info.rb

@@ -5,7 +5,7 @@ module RubyLLM
     # Information about an AI model's capabilities, pricing, and metadata.
     class Info
       attr_reader :id, :name, :provider, :family, :created_at, :context_window, :max_output_tokens, :knowledge_cutoff,
-                  :modalities, :capabilities, :pricing, :metadata
+                  :modalities, :capabilities, :pricing, :metadata, :reasoning_options
 
       # Create a default model with assumed capabilities
       def self.default(model_id, provider)
@@ -31,7 +31,9 @@ module RubyLLM
         @modalities = Modalities.new(data[:modalities] || {})
         @capabilities = data[:capabilities] || []
         @pricing = Pricing.new(data[:pricing] || {})
-        @metadata = data[:metadata] || {}
+        @metadata = data[:metadata]&.dup || {}
+        @reasoning_options = normalize_reasoning_options(reasoning_options_from(data))
+        store_reasoning_options_metadata
       end
 
       def supports?(capability)
@@ -61,6 +63,14 @@ module RubyLLM
         modalities.input.include?('image')
       end
 
+      def reasoning_option(type)
+        reasoning_options.find { |option| option[:type] == type.to_s }
+      end
+
+      def reasoning_option_values(type)
+        Array(reasoning_option(type)&.fetch(:values, nil))
+      end
+
       def supports_video?
         modalities.input.include?('video')
       end
@@ -125,6 +135,30 @@ module RubyLLM
           metadata: metadata
         }
       end
+
+      private
+
+      def reasoning_options_from(data)
+        data[:reasoning_options] || metadata[:reasoning_options] || metadata['reasoning_options']
+      end
+
+      def store_reasoning_options_metadata
+        return unless reasoning_options.any?
+
+        metadata.delete('reasoning_options')
+        metadata[:reasoning_options] = reasoning_options
+      end
+
+      def normalize_reasoning_options(options)
+        Array(options).filter_map do |option|
+          next unless option.is_a?(Hash)
+
+          normalized = option.to_h.transform_keys(&:to_sym)
+          normalized[:type] = normalized[:type].to_s if normalized[:type]
+          normalized[:values] = Array(normalized[:values]).map(&:to_s) if normalized.key?(:values)
+          normalized
+        end
+      end
     end
   end
 end

data/lib/ruby_llm/model/pricing.rb

@@ -4,24 +4,30 @@ module RubyLLM
   module Model
     # A collection that manages and provides access to different categories of pricing information
     class Pricing
+      CATEGORIES = %i[text_tokens images audio_tokens embeddings].freeze
+
       def initialize(data)
         @data = {}
 
-        %i[text_tokens images audio_tokens embeddings].each do |category|
+        CATEGORIES.each do |category|
           @data[category] = PricingCategory.new(data[category]) if data[category] && !empty_pricing?(data[category])
         end
       end
 
-      def method_missing(method, *args)
-        if respond_to_missing?(method)
-          @data[method.to_sym] || PricingCategory.new
-        else
-          super
-        end
+      def text_tokens
+        category(:text_tokens)
+      end
+
+      def images
+        category(:images)
       end
 
-      def respond_to_missing?(method, include_private = false)
-        %i[text_tokens images audio_tokens embeddings].include?(method.to_sym) || super
+      def audio_tokens
+        category(:audio_tokens)
+      end
+
+      def embeddings
+        category(:embeddings)
       end
 
       def to_h
@@ -30,6 +36,10 @@ module RubyLLM
 
       private
 
+      def category(name)
+        @data[name] || PricingCategory.new
+      end
+
       def empty_pricing?(data)
         return true unless data
 

data/lib/ruby_llm/model/pricing_tier.rb

@@ -2,8 +2,18 @@
 
 module RubyLLM
   module Model
-    # A dynamic class for storing non-zero pricing values with flexible attribute access
+    # Stores non-zero pricing values for a single pricing tier.
     class PricingTier
+      ATTRIBUTES = %i[
+        input_per_million
+        output_per_million
+        cache_read_input_per_million
+        cache_write_input_per_million
+        cached_input_per_million
+        cache_creation_input_per_million
+        reasoning_output_per_million
+      ].freeze
+
       def initialize(data = {})
         @values = {}
 
@@ -12,17 +22,18 @@ module RubyLLM
         end
       end
 
-      def method_missing(method, *args)
-        if method.to_s.end_with?('=')
-          key = method.to_s.chomp('=').to_sym
-          @values[key] = args.first if args.first && args.first != 0.0
-        elsif @values.key?(method)
-          @values[method]
+      ATTRIBUTES.each do |attribute|
+        define_method(attribute) do
+          @values[attribute]
+        end
+
+        define_method("#{attribute}=") do |value|
+          @values[attribute] = value if value && value != 0.0
         end
       end
 
-      def respond_to_missing?(method, include_private = false)
-        method.to_s.end_with?('=') || @values.key?(method.to_sym) || super
+      def [](key)
+        @values[key.to_sym]
       end
 
       def to_h

data/lib/ruby_llm/model_registry.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Sources for model registry data.
+  module ModelRegistry
+    # Reads model registry data from the configured JSON file.
+    class JsonSource
+      def initialize(file = nil)
+        @file = file
+      end
+
+      def read
+        Models.read_from_json(@file || RubyLLM.config.model_registry_file)
+      end
+    end
+
+    # Reads model registry data from the configured Active Record model class.
+    class ActiveRecordSource
+      def read
+        model_class = resolve_model_class
+        return [] unless model_class.respond_to?(:table_exists?) && model_class.table_exists?
+
+        model_class.all.map(&:to_llm)
+      rescue StandardError => e
+        RubyLLM.logger.debug { "Failed to load models from database: #{e.message}, falling back to JSON" }
+        []
+      end
+
+      private
+
+      def resolve_model_class
+        model_class = RubyLLM.config.model_registry_class
+        return model_class unless model_class.is_a?(String)
+
+        model_class.split('::').inject(Object) { |scope, name| scope.const_get(name) }
+      end
+    end
+  end
+end