ruby_llm 1.15.0 → 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,6 +73,14 @@ 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
 
@@ -53,17 +92,26 @@ module RubyLLM
         []
       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
@@ -115,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?
@@ -129,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...'
 
@@ -181,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|
@@ -288,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
@@ -327,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]),
@@ -345,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
@@ -382,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]
@@ -393,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
 
@@ -412,10 +454,19 @@ module RubyLLM
       @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
@@ -475,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)
@@ -500,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/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
@@ -229,10 +232,14 @@ module RubyLLM
     def validate_paint_inputs!(with:, mask:)
       return if with.nil? && mask.nil?
 
-      raise UnsupportedAttachmentError, "#{name} does not support image references in paint"
+      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))
 
@@ -255,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/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

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

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

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

@@ -16,7 +16,7 @@ module RubyLLM
 
           content = []
 
-          content << Media.format_text(msg.content) unless msg.content.nil? || msg.content.empty?
+          append_formatted_content(content, msg.content) unless msg.content.nil? || msg.content.empty?
 
           msg.tool_calls.each_value do |tool_call|
             content << format_tool_use_block(tool_call)
@@ -44,6 +44,15 @@ module RubyLLM
           }
         end
 
+        def append_formatted_content(content_blocks, content)
+          formatted_content = Media.format_content(content)
+          if formatted_content.is_a?(Array)
+            content_blocks.concat(formatted_content)
+          else
+            content_blocks << formatted_content
+          end
+        end
+
         def format_tool_result_block(msg)
           content = msg.content
           content = '(no output)' if content.nil? || (content.respond_to?(:empty?) && content.empty?)
@@ -72,12 +81,29 @@ module RubyLLM
 
         def extract_tool_calls(data)
           if json_delta?(data)
-            { nil => ToolCall.new(id: nil, name: nil, arguments: data.dig('delta', 'partial_json')) }
+            extract_tool_call_delta(data)
+          elsif content_block_start?(data)
+            extract_tool_call_start(data)
           else
             parse_tool_calls(data['content_block'])
           end
         end
 
+        def extract_tool_call_delta(data)
+          { data['index'] => ToolCall.new(id: nil, name: nil, arguments: data.dig('delta', 'partial_json')) }
+        end
+
+        def extract_tool_call_start(data)
+          tool_calls = parse_tool_calls(data['content_block'])
+          return tool_calls if tool_calls.nil? || data['index'].nil?
+
+          { data['index'] => tool_calls.values.first }
+        end
+
+        def content_block_start?(data)
+          data['type'] == 'content_block_start'
+        end
+
         def parse_tool_calls(content_blocks)
           return nil if content_blocks.nil?
 

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

@@ -24,7 +24,7 @@ module RubyLLM
             when :text
               parts << OpenAI::Media.format_text_file(attachment)
             else
-              raise UnsupportedAttachmentError, attachment.type
+              raise UnsupportedAttachmentError, attachment.mime_type
             end
           end
 

data/lib/ruby_llm/providers/bedrock/auth.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'digest'
+require 'json'
 require 'openssl'
 
 module RubyLLM

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

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

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

@@ -38,15 +38,17 @@ module RubyLLM
           case attachment.type
           when :image
             render_image_attachment(attachment)
-          when :pdf
+          when :pdf, :document
             render_document_attachment(attachment, used_document_names:)
           when :text
-            { text: attachment.for_llm }
+            render_text_attachment(attachment)
           else
             raise UnsupportedAttachmentError, attachment.mime_type
           end
         end
 
+        SUPPORTED_DOCUMENT_FORMATS = %w[pdf csv doc docx xls xlsx html txt md].freeze
+
         def render_image_attachment(attachment)
           {
             image: {
@@ -58,11 +60,19 @@ module RubyLLM
           }
         end
 
+        def render_text_attachment(attachment)
+          { text: attachment.for_llm }
+        end
+
         def render_document_attachment(attachment, used_document_names:)
+          format = document_format(attachment)
+
+          raise UnsupportedAttachmentError, attachment.mime_type unless supported_document_format?(attachment)
+
           document_name = unique_document_name(sanitize_document_name(attachment.filename), used_document_names)
           {
             document: {
-              format: attachment.format,
+              format: format,
               name: document_name,
               source: {
                 bytes: attachment.encoded
@@ -71,6 +81,14 @@ module RubyLLM
           }
         end
 
+        def supported_document_format?(attachment)
+          SUPPORTED_DOCUMENT_FORMATS.include?(document_format(attachment))
+        end
+
+        def document_format(attachment)
+          attachment.extension || attachment.format
+        end
+
         def sanitize_document_name(filename)
           base = File.basename(filename.to_s, '.*')
           safe = base.gsub(/[^a-zA-Z0-9_-]/, '_')

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

@@ -10,7 +10,7 @@ module RubyLLM
         REGION_PREFIXES = %w[global us eu ap sa ca me af il].freeze
 
         def models_api_base
-          "https://bedrock.#{bedrock_region}.amazonaws.com"
+          @config.bedrock_api_base || "https://bedrock.#{bedrock_region}.amazonaws.com"
         end
 
         def models_url

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

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require 'base64'
+require 'faraday'
+require 'json'
+
 module RubyLLM
   module Providers
     class Bedrock
@@ -224,6 +228,7 @@ module RubyLLM
 
           reasoning_text = reasoning_content['reasoningText'] || {}
           return reasoning_text['text'] if reasoning_text['text']
+          return reasoning_content['text'] if reasoning_content['text']
           return event.dig('delta', 'thinking') if event.dig('delta', 'type') == 'thinking_delta'
 
           nil
@@ -244,6 +249,7 @@ module RubyLLM
           reasoning_content = delta['reasoningContent'] || {}
           reasoning_text = reasoning_content['reasoningText'] || {}
           return reasoning_text['signature'] if reasoning_text['signature']
+          return reasoning_content['signature'] if reasoning_content['signature']
           return event.dig('delta', 'signature') if event.dig('delta', 'type') == 'signature_delta'
 
           nil

data/lib/ruby_llm/providers/bedrock.rb

@@ -11,7 +11,7 @@ module RubyLLM
       include Bedrock::Streaming
 
       def api_base
-        "https://bedrock-runtime.#{bedrock_region}.amazonaws.com"
+        @config.bedrock_api_base || "https://bedrock-runtime.#{bedrock_region}.amazonaws.com"
       end
 
       def headers
@@ -54,7 +54,7 @@ module RubyLLM
 
       class << self
         def configuration_options
-          %i[bedrock_api_key bedrock_secret_key bedrock_region bedrock_session_token]
+          %i[bedrock_api_key bedrock_secret_key bedrock_region bedrock_session_token bedrock_api_base]
         end
 
         def configuration_requirements

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

@@ -7,6 +7,19 @@ module RubyLLM
       module Capabilities
         module_function
 
+        DEFAULT_CONTEXT_WINDOW = 1_000_000
+        DEFAULT_MAX_OUTPUT_TOKENS = 384_000
+        DEFAULT_PRICES = {
+          input: 0.14,
+          output: 0.28,
+          cache_read: 0.0028
+        }.freeze
+        PRO_PRICES = {
+          input: 0.435,
+          output: 0.87,
+          cache_read: 0.003625
+        }.freeze
+
         def supports_tool_choice?(_model_id)
           true
         end
@@ -14,6 +27,36 @@ module RubyLLM
         def supports_tool_parallel_control?(_model_id)
           false
         end
+
+        def context_window_for(_model_id)
+          DEFAULT_CONTEXT_WINDOW
+        end
+
+        def max_tokens_for(_model_id)
+          DEFAULT_MAX_OUTPUT_TOKENS
+        end
+
+        def critical_capabilities_for(model_id)
+          v4_model = model_id.start_with?('deepseek-v4-')
+          capabilities = ['function_calling']
+          capabilities << 'structured_output' if v4_model
+          capabilities << 'reasoning' if model_id == 'deepseek-reasoner' || v4_model
+          capabilities
+        end
+
+        def pricing_for(model_id)
+          prices = model_id == 'deepseek-v4-pro' ? PRO_PRICES : DEFAULT_PRICES
+
+          {
+            text_tokens: {
+              standard: {
+                input_per_million: prices[:input],
+                output_per_million: prices[:output],
+                cache_read_input_per_million: prices[:cache_read]
+              }
+            }
+          }
+        end
       end
     end
   end

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

@@ -10,6 +10,15 @@ module RubyLLM
         def format_role(role)
           role.to_s
         end
+
+        def format_content(content)
+          OpenAI::Media.format_content(
+            content,
+            document_attachments: :none,
+            image_attachments: false,
+            audio_attachments: false
+          )
+        end
       end
     end
   end