ruby_llm 1.13.2 → 1.16.0

data/lib/ruby_llm/models.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'date'
+require 'json'
+
 module RubyLLM
   # Registry of available AI models and their capabilities.
   class Models
@@ -14,8 +17,12 @@ module RubyLLM
       'deepseek' => 'deepseek',
       'mistral' => 'mistral',
       'openrouter' => 'openrouter',
-      'perplexity' => 'perplexity'
+      'perplexity' => 'perplexity',
+      'xai' => 'xai'
     }.freeze
+    MODELS_DEV_INPUT_MODALITIES = %w[text image audio pdf video file].freeze
+    MODELS_DEV_OUTPUT_MODALITIES = %w[text image audio video embeddings moderation].freeze
+    MODELS_DEV_AUTHORITY_CAPABILITIES = %w[function_calling structured_output reasoning vision].freeze
     PROVIDER_PREFERENCE = %w[
       openai
       anthropic
@@ -31,8 +38,32 @@ module RubyLLM
       ollama
       gpustack
     ].freeze
+    INSTANCE_DELEGATES = (Enumerable.instance_methods(false) + %i[
+      all
+      each
+      find
+      chat_models
+      embedding_models
+      audio_models
+      image_models
+      by_family
+      by_provider
+      load_from_json!
+      load_from_database!
+      save_to_json
+    ]).uniq.freeze
 
     class << self
+      INSTANCE_DELEGATES.each do |method_name|
+        define_method(method_name) do |*args, **kwargs, &block|
+          if kwargs.empty?
+            instance.public_send(method_name, *args, &block)
+          else
+            instance.public_send(method_name, *args, **kwargs, &block)
+          end
+        end
+      end
+
       def instance
         @instance ||= new
       end
@@ -42,27 +73,45 @@ module RubyLLM
       end
 
       def load_models(file = RubyLLM.config.model_registry_file)
+        source = RubyLLM.config.model_registry_source
+        if source && file == RubyLLM.config.model_registry_file
+          models = source.read
+          return models if models.any?
+
+          RubyLLM.logger.debug { 'Model registry source is empty, falling back to JSON registry' }
+        end
+
         read_from_json(file)
       end
 
       def read_from_json(file = RubyLLM.config.model_registry_file)
         data = File.exist?(file) ? File.read(file) : '[]'
-        JSON.parse(data, symbolize_names: true).map { |model| Model::Info.new(model) }
+        models = JSON.parse(data, symbolize_names: true).map { |model| Model::Info.new(model) }
+        filter_models(models)
       rescue JSON::ParserError
         []
       end
 
+      def read_from_database
+        ModelRegistry::ActiveRecordSource.new.read
+      end
+
       def refresh!(remote_only: false)
-        existing_models = load_existing_models
+        # Replaces the process-wide model registry. Call save_to_json when the
+        # refreshed registry should also be persisted.
+        RubyLLM.instrument('models.refresh.ruby_llm', remote_only:) do |payload|
+          existing_models = load_existing_models
 
-        provider_fetch = fetch_provider_models(remote_only: remote_only)
-        log_provider_fetch(provider_fetch)
+          provider_fetch = fetch_provider_models(remote_only: remote_only)
+          log_provider_fetch(provider_fetch)
 
-        models_dev_fetch = fetch_models_dev_models(existing_models)
-        log_models_dev_fetch(models_dev_fetch)
+          models_dev_fetch = fetch_models_dev_models(existing_models)
+          log_models_dev_fetch(models_dev_fetch)
 
-        merged_models = merge_with_existing(existing_models, provider_fetch, models_dev_fetch)
-        @instance = new(merged_models)
+          merged_models = merge_with_existing(existing_models, provider_fetch, models_dev_fetch)
+          payload[:model_count] = merged_models.size
+          @instance = new(merged_models)
+        end
       end
 
       def fetch_provider_models(remote_only: true) # rubocop:disable Metrics/PerceivedComplexity
@@ -114,7 +163,7 @@ module RubyLLM
         if assume_exists
           raise ArgumentError, 'Provider must be specified if assume_exists is true' unless provider
 
-          provider_class ||= raise(Error, "Unknown provider: #{provider.to_sym}")
+          provider_class ||= raise_unknown_provider(provider)
           provider_instance = provider_class.new(config)
 
           model = if provider_instance.local?
@@ -128,25 +177,12 @@ module RubyLLM
           model ||= Model::Info.default(model_id, provider_instance.slug)
         else
           model = Models.find model_id, provider
-          provider_class = Provider.providers[model.provider.to_sym] || raise(Error,
-                                                                              "Unknown provider: #{model.provider}")
+          provider_class = Provider.providers[model.provider.to_sym] || raise_unknown_provider(model.provider)
           provider_instance = provider_class.new(config)
         end
         [model, provider_instance]
       end
 
-      def method_missing(method, ...)
-        if instance.respond_to?(method)
-          instance.send(method, ...)
-        else
-          super
-        end
-      end
-
-      def respond_to_missing?(method, include_private = false)
-        instance.respond_to?(method, include_private) || super
-      end
-
       def fetch_models_dev_models(existing_models) # rubocop:disable Metrics/PerceivedComplexity
         RubyLLM.logger.info 'Fetching models from models.dev API...'
 
@@ -180,6 +216,11 @@ module RubyLLM
         existing_models
       end
 
+      def raise_unknown_provider(provider)
+        available = Provider.providers.keys.join(', ')
+        raise Error, "Unknown provider: #{provider.inspect}. Available providers: #{available}"
+      end
+
       def log_provider_fetch(provider_fetch)
         RubyLLM.logger.info "Fetching models from providers: #{provider_fetch[:configured_names].join(', ')}"
         provider_fetch[:failed].each do |failure|
@@ -232,7 +273,13 @@ module RubyLLM
           end
         end
 
-        models.sort_by { |m| [m.provider, m.id] }
+        filter_models(models).sort_by { |m| [m.provider, m.id] }
+      end
+
+      def filter_models(models)
+        models.reject do |model|
+          model.provider.to_s == 'vertexai' && model.id.to_s.include?('/')
+        end
       end
 
       def find_models_dev_model(key, models_dev_by_key)
@@ -281,7 +328,8 @@ module RubyLLM
         data[:modalities] = provider_model.modalities.to_h if blank_value?(data[:modalities])
         data[:pricing] = provider_model.pricing.to_h if blank_value?(data[:pricing])
         data[:metadata] = provider_model.metadata.merge(data[:metadata] || {})
-        data[:capabilities] = (models_dev_model.capabilities + provider_model.capabilities).uniq
+        provider_capabilities = provider_model.capabilities - MODELS_DEV_AUTHORITY_CAPABILITIES
+        data[:capabilities] = (models_dev_model.capabilities + provider_capabilities).uniq
         normalize_embedding_modalities(data)
         Model::Info.new(data)
       end
@@ -320,7 +368,7 @@ module RubyLLM
           name: model_data[:name] || model_data[:id],
           provider: provider_slug,
           family: model_data[:family],
-          created_at: created_date ? "#{created_date} 00:00:00 UTC" : nil,
+          created_at: Utils.iso_date_prefix_to_utc_midnight_string(created_date),
           context_window: model_data.dig(:limit, :context),
           max_output_tokens: model_data.dig(:limit, :output),
           knowledge_cutoff: normalize_models_dev_knowledge(model_data[:knowledge]),
@@ -338,7 +386,7 @@ module RubyLLM
         capabilities = []
         capabilities << 'function_calling' if model_data[:tool_call]
         capabilities << 'structured_output' if model_data[:structured_output]
-        capabilities << 'reasoning' if model_data[:reasoning]
+        capabilities << 'reasoning' if model_data[:reasoning] || model_data[:reasoning_options]
         capabilities << 'vision' if modalities[:input].intersect?(%w[image video pdf])
         capabilities.uniq
       end
@@ -349,7 +397,8 @@ module RubyLLM
         text_standard = {
           input_per_million: cost[:input],
           output_per_million: cost[:output],
-          cached_input_per_million: cost[:cache_read],
+          cache_read_input_per_million: cost[:cache_read],
+          cache_write_input_per_million: cost[:cache_write],
           reasoning_output_per_million: cost[:reasoning]
         }.compact
 
@@ -374,6 +423,7 @@ module RubyLLM
           last_updated: model_data[:last_updated],
           status: model_data[:status],
           interleaved: model_data[:interleaved],
+          reasoning_options: model_data[:reasoning_options],
           cost: model_data[:cost],
           limit: model_data[:limit],
           knowledge: model_data[:knowledge]
@@ -385,8 +435,8 @@ module RubyLLM
         normalized = { input: [], output: [] }
         return normalized unless modalities
 
-        normalized[:input] = Array(modalities[:input]).compact
-        normalized[:output] = Array(modalities[:output]).compact
+        normalized[:input] = Array(modalities[:input]).compact & MODELS_DEV_INPUT_MODALITIES
+        normalized[:output] = Array(modalities[:output]).compact & MODELS_DEV_OUTPUT_MODALITIES
         normalized
       end
 
@@ -401,13 +451,22 @@ module RubyLLM
     end
 
     def initialize(models = nil)
-      @models = models || self.class.load_models
+      @models = self.class.filter_models(models || self.class.load_models)
     end
 
+    # Replaces this registry instance with models loaded from JSON.
     def load_from_json!(file = RubyLLM.config.model_registry_file)
       @models = self.class.read_from_json(file)
     end
 
+    # Replaces this registry instance with models loaded from the configured
+    # ActiveRecord model class.
+    def load_from_database!
+      @models = self.class.read_from_database
+    end
+
+    # Persists this registry instance to JSON without changing the global
+    # RubyLLM.models instance.
     def save_to_json(file = RubyLLM.config.model_registry_file)
       File.write(file, JSON.pretty_generate(all.map(&:to_h)))
     end
@@ -467,7 +526,7 @@ module RubyLLM
       resolved_id = resolve_bedrock_region_id(resolved_id) if provider.to_s == 'bedrock'
       all.find { |m| m.id == resolved_id && m.provider == provider.to_s } ||
         all.find { |m| m.id == model_id && m.provider == provider.to_s } ||
-        raise(ModelNotFoundError, "Unknown model: #{model_id} for provider: #{provider}")
+        raise_model_not_found(model_id, provider: provider)
     end
 
     def resolve_bedrock_region_id(model_id)
@@ -492,7 +551,21 @@ module RubyLLM
       alias_matches = all.select { |m| m.id == resolved_id }
       return preferred_match(alias_matches) if alias_matches.any?
 
-      raise(ModelNotFoundError, "Unknown model: #{model_id}")
+      raise_model_not_found(model_id)
+    end
+
+    def raise_model_not_found(model_id, provider: nil)
+      message = "Unknown model: #{model_id.inspect}"
+      message = "#{message} for provider: #{provider.inspect}" if provider
+
+      raise ModelNotFoundError, "#{message}. #{refresh_registry_guidance}"
+    end
+
+    def refresh_registry_guidance
+      rails_model = RubyLLM.config.model_registry_class
+      'If the model exists at the provider, refresh the registry with `RubyLLM.models.refresh!` ' \
+        'and persist it with `RubyLLM.models.save_to_json`. ' \
+        "Rails model registries can call `#{rails_model}.refresh!` instead."
     end
 
     def preferred_match(candidates)

data/lib/ruby_llm/models_schema.json

@@ -87,7 +87,10 @@
                 "type": "object",
                 "properties": {
                   "input_per_million": {"type": "number", "minimum": 0},
+                  "cache_read_input_per_million": {"type": "number", "minimum": 0},
+                  "cache_write_input_per_million": {"type": "number", "minimum": 0},
                   "cached_input_per_million": {"type": "number", "minimum": 0},
+                  "cache_creation_input_per_million": {"type": "number", "minimum": 0},
                   "output_per_million": {"type": "number", "minimum": 0},
                   "reasoning_output_per_million": {"type": "number", "minimum": 0}
                 }

data/lib/ruby_llm/provider.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'json'
+require 'ruby_llm/error'
+
 module RubyLLM
   # Base class for LLM providers.
   class Provider
@@ -81,9 +84,10 @@ module RubyLLM
       parse_moderation_response(response, model:)
     end
 
-    def paint(prompt, model:, size:)
-      payload = render_image_payload(prompt, model:, size:)
-      response = @connection.post images_url, payload
+    def paint(prompt, model:, size:, with: nil, mask: nil, params: {}) # rubocop:disable Metrics/ParameterLists
+      validate_paint_inputs!(with:, mask:)
+      payload = render_image_payload(prompt, model:, size:, with:, mask:, params:)
+      response = @connection.post images_url(with:, mask:), payload
       parse_image_response(response, model:)
     end
 
@@ -164,6 +168,10 @@ module RubyLLM
         []
       end
 
+      def configuration_options
+        []
+      end
+
       def local?
         false
       end
@@ -182,6 +190,7 @@ module RubyLLM
 
       def register(name, provider_class)
         providers[name.to_sym] = provider_class
+        RubyLLM::Configuration.register_provider_options(provider_class.configuration_options)
       end
 
       def resolve(name)
@@ -220,7 +229,17 @@ module RubyLLM
 
     private
 
+    def validate_paint_inputs!(with:, mask:)
+      return if with.nil? && mask.nil?
+
+      raise UnsupportedAttachmentError, 'image reference'
+    end
+
     def build_audio_file_part(file_path)
+      require 'faraday/multipart'
+      require 'marcel'
+      require 'pathname'
+
       expanded_path = File.expand_path(file_path)
       mime_type = Marcel::MimeType.for(Pathname.new(expanded_path))
 
@@ -243,7 +262,9 @@ module RubyLLM
       missing = configuration_requirements.reject { |req| @config.send(req) }
       return if missing.empty?
 
-      raise ConfigurationError, "Missing configuration for #{name}: #{missing.join(', ')}"
+      raise ConfigurationError,
+            "Missing configuration for #{name}: #{missing.join(', ')}. " \
+            'Set these keys on RubyLLM.config before using this provider.'
     end
 
     def maybe_normalize_temperature(temperature, _model)

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

@@ -3,37 +3,10 @@
 module RubyLLM
   module Providers
     class Anthropic
-      # Determines capabilities and pricing for Anthropic models
+      # Provider-level capability checks used outside the model registry.
       module Capabilities
         module_function
 
-        def determine_context_window(_model_id)
-          200_000
-        end
-
-        def determine_max_tokens(model_id)
-          case model_id
-          when /claude-3-7-sonnet/, /claude-3-5/ then 8_192
-          else 4_096
-          end
-        end
-
-        def get_input_price(model_id)
-          PRICES.dig(model_family(model_id), :input) || default_input_price
-        end
-
-        def get_output_price(model_id)
-          PRICES.dig(model_family(model_id), :output) || default_output_price
-        end
-
-        def supports_vision?(model_id)
-          !model_id.match?(/claude-[12]/)
-        end
-
-        def supports_functions?(model_id)
-          !model_id.match?(/claude-[12]/)
-        end
-
         def supports_tool_choice?(_model_id)
           true
         end
@@ -41,111 +14,6 @@ module RubyLLM
         def supports_tool_parallel_control?(_model_id)
           true
         end
-
-        def supports_json_mode?(model_id)
-          !model_id.match?(/claude-[12]/)
-        end
-
-        def supports_structured_output?(model_id)
-          match = model_id.match(/claude-(?:sonnet|opus|haiku)-(\d+)-(\d+)/)
-          return false unless match
-
-          major = match[1].to_i
-          minor = match[2].to_i
-          major > 4 || (major == 4 && minor >= 5)
-        end
-
-        def supports_extended_thinking?(model_id)
-          model_id.match?(/claude-3-7-sonnet/)
-        end
-
-        def model_family(model_id)
-          case model_id
-          when /claude-3-7-sonnet/  then 'claude-3-7-sonnet'
-          when /claude-3-5-sonnet/  then 'claude-3-5-sonnet'
-          when /claude-3-5-haiku/   then 'claude-3-5-haiku'
-          when /claude-3-opus/      then 'claude-3-opus'
-          when /claude-3-sonnet/    then 'claude-3-sonnet'
-          when /claude-3-haiku/     then 'claude-3-haiku'
-          else 'claude-2'
-          end
-        end
-
-        def model_type(_)
-          'chat'
-        end
-
-        PRICES = {
-          'claude-3-7-sonnet': { input: 3.0, output: 15.0 },
-          'claude-3-5-sonnet': { input: 3.0, output: 15.0 },
-          'claude-3-5-haiku': { input: 0.80, output: 4.0 },
-          'claude-3-opus': { input: 15.0, output: 75.0 },
-          'claude-3-haiku': { input: 0.25, output: 1.25 },
-          'claude-2': { input: 3.0, output: 15.0 }
-        }.freeze
-
-        def default_input_price
-          3.0
-        end
-
-        def default_output_price
-          15.0
-        end
-
-        def modalities_for(model_id)
-          modalities = {
-            input: ['text'],
-            output: ['text']
-          }
-
-          unless model_id.match?(/claude-[12]/)
-            modalities[:input] << 'image'
-            modalities[:input] << 'pdf'
-          end
-
-          modalities
-        end
-
-        def capabilities_for(model_id)
-          capabilities = ['streaming']
-
-          unless model_id.match?(/claude-[12]/)
-            capabilities << 'function_calling'
-            capabilities << 'batch'
-          end
-
-          capabilities << 'structured_output' if supports_structured_output?(model_id)
-          capabilities << 'reasoning' if model_id.match?(/claude-3-7-sonnet|claude-(?:sonnet|opus|haiku)-4/)
-          capabilities << 'citations' if model_id.match?(/claude-3\.5|claude-3-7/)
-          capabilities
-        end
-
-        def pricing_for(model_id)
-          family = model_family(model_id)
-          prices = PRICES.fetch(family.to_sym, { input: default_input_price, output: default_output_price })
-
-          standard_pricing = {
-            input_per_million: prices[:input],
-            output_per_million: prices[:output]
-          }
-
-          batch_pricing = {
-            input_per_million: prices[:input] * 0.5,
-            output_per_million: prices[:output] * 0.5
-          }
-
-          if model_id.match?(/claude-3-7/)
-            standard_pricing[:reasoning_output_per_million] = prices[:output] * 2.5
-            batch_pricing[:reasoning_output_per_million] = prices[:output] * 1.25
-          end
-
-          {
-            text_tokens: {
-              standard: standard_pricing,
-              batch: batch_pricing
-            }
-          }
-        end
       end
     end
   end

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

@@ -31,13 +31,9 @@ module RubyLLM
         def build_system_content(system_messages)
           return [] if system_messages.empty?
 
-          if system_messages.length > 1
-            RubyLLM.logger.warn(
-              "Anthropic's Claude implementation only supports a single system message. " \
-              'Multiple system messages will be combined into one.'
-            )
-          end
-
+          # Anthropic's `system` parameter accepts an array of text content blocks
+          # (each optionally with cache_control); each :system message becomes its
+          # own block in the resulting array.
           system_messages.flat_map do |msg|
             content = msg.content
 
@@ -57,8 +53,7 @@ module RubyLLM
             max_tokens: model.max_tokens || 4096
           }
 
-          thinking_payload = build_thinking_payload(thinking)
-          payload[:thinking] = thinking_payload if thinking_payload
+          add_thinking_fields(payload, thinking, model)
 
           payload
         end
@@ -72,7 +67,7 @@ module RubyLLM
           end
           payload[:system] = system_content unless system_content.empty?
           payload[:temperature] = temperature unless temperature.nil?
-          payload[:output_config] = build_output_config(schema) if schema
+          payload[:output_config] = payload.fetch(:output_config, {}).merge(build_output_config(schema)) if schema
         end
 
         def build_output_config(schema)
@@ -176,7 +171,7 @@ module RubyLLM
           end
 
           content_blocks = prepend_thinking_block([], msg, thinking_enabled)
-          content_blocks << Media.format_text(msg.content) unless msg.content.nil? || msg.content.empty?
+          append_formatted_content(content_blocks, msg.content) unless msg.content.nil? || msg.content.empty?
 
           msg.tool_calls.each_value do |tool_call|
             content_blocks << {
@@ -235,18 +230,57 @@ module RubyLLM
           end
         end
 
-        def build_thinking_payload(thinking)
+        def add_thinking_fields(payload, thinking, model)
+          thinking_payload = build_thinking_payload(thinking, model)
+          return unless thinking_payload
+
+          payload[:thinking] = thinking_payload[:thinking] if thinking_payload[:thinking]
+          return unless thinking_payload[:output_config]
+
+          payload[:output_config] = payload.fetch(:output_config, {}).merge(thinking_payload[:output_config])
+        end
+
+        def build_thinking_payload(thinking, model)
           return nil unless thinking&.enabled?
 
+          effort = resolve_effort(thinking)
+          return nil if effort == 'none'
+
           budget = resolve_budget(thinking)
-          raise ArgumentError, 'Anthropic thinking requires a budget' if budget.nil?
+          if budget
+            return enabled_thinking_payload(budget) if model.reasoning_option('budget_tokens')
+
+            raise ArgumentError, "Anthropic thinking budget is not supported for #{model.id}"
+          end
+
+          raise ArgumentError, 'Anthropic adaptive thinking requires an effort' if effort.nil?
+          return adaptive_thinking_payload(effort) if model.reasoning_option('effort')
 
+          raise ArgumentError, "Anthropic thinking effort is not supported for #{model.id}"
+        end
+
+        def enabled_thinking_payload(budget)
           {
-            type: 'enabled',
-            budget_tokens: budget
+            thinking: {
+              type: 'enabled',
+              budget_tokens: budget
+            }
           }
         end
 
+        def adaptive_thinking_payload(effort)
+          {
+            thinking: { type: 'adaptive' },
+            output_config: { effort: effort }
+          }
+        end
+
+        def resolve_effort(thinking)
+          effort = thinking.respond_to?(:effort) ? thinking.effort : nil
+          effort = effort.to_s if effort
+          effort.nil? || effort.empty? ? nil : effort
+        end
+
         def resolve_budget(thinking)
           budget = thinking.respond_to?(:budget) ? thinking.budget : thinking
           budget.is_a?(Integer) ? budget : nil

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'time'
+
 module RubyLLM
   module Providers
     class Anthropic
@@ -11,21 +13,15 @@ module RubyLLM
           'v1/models'
         end
 
-        def parse_list_models_response(response, slug, capabilities)
+        def parse_list_models_response(response, slug, _capabilities)
           Array(response.body['data']).map do |model_data|
             model_id = model_data['id']
 
             Model::Info.new(
               id: model_id,
-              name: model_data['display_name'],
+              name: model_data['display_name'] || model_id,
               provider: slug,
-              family: capabilities.model_family(model_id),
               created_at: Time.parse(model_data['created_at']),
-              context_window: capabilities.determine_context_window(model_id),
-              max_output_tokens: capabilities.determine_max_tokens(model_id),
-              modalities: capabilities.modalities_for(model_id),
-              capabilities: capabilities.capabilities_for(model_id),
-              pricing: capabilities.pricing_for(model_id),
               metadata: {}
             )
           end

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

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