ruby_llm 1.14.1 → 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
@@ -356,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
 
@@ -381,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]
@@ -392,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
 
@@ -411,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
@@ -474,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)
@@ -499,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
 
@@ -225,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))
 
@@ -248,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,11 +44,23 @@ 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?)
+
           {
             type: 'tool_result',
             tool_use_id: msg.tool_call_id,
-            content: Media.format_content(msg.content)
+            content: Media.format_content(content)
           }
         end
 
@@ -69,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
@@ -56,7 +58,7 @@ module RubyLLM
             content: parse_text_content(content_blocks),
             thinking: Thinking.build(text: thinking_text, signature: thinking_signature),
             tool_calls: parse_tool_calls(content_blocks),
-            input_tokens: usage['inputTokens'],
+            input_tokens: input_tokens(usage),
             output_tokens: usage['outputTokens'],
             cached_tokens: usage['cacheReadInputTokens'],
             cache_creation_tokens: usage['cacheWriteInputTokens'],
@@ -66,6 +68,13 @@ module RubyLLM
           )
         end
 
+        def input_tokens(usage)
+          input_tokens = usage['inputTokens']
+          return unless input_tokens
+
+          [input_tokens.to_i - usage['cacheReadInputTokens'].to_i - usage['cacheWriteInputTokens'].to_i, 0].max
+        end
+
         def render_messages(messages)
           rendered = []
           tool_result_blocks = []
@@ -154,19 +163,23 @@ module RubyLLM
 
         def render_tool_result_content(content)
           return render_raw_tool_result_content(content.value) if content.is_a?(RubyLLM::Content::Raw)
+          return [{ json: content }] if content.is_a?(Hash) || content.is_a?(Array)
+          return render_content_tool_result_content(content) if content.is_a?(RubyLLM::Content)
 
-          if content.is_a?(Hash) || content.is_a?(Array)
-            [{ json: content }]
-          elsif content.is_a?(RubyLLM::Content)
-            blocks = []
-            blocks << { text: content.text } if content.text
-            content.attachments.each do |attachment|
-              blocks << { text: attachment.for_llm }
-            end
-            blocks
-          else
-            [{ text: content.to_s }]
-          end
+          [text_tool_result_block(content)]
+        end
+
+        def render_content_tool_result_content(content)
+          blocks = []
+          blocks << text_tool_result_block(content.text) unless content.text.to_s.empty?
+          content.attachments.each { |attachment| blocks << text_tool_result_block(attachment.for_llm) }
+          blocks.empty? ? [text_tool_result_block(nil)] : blocks
+        end
+
+        def text_tool_result_block(text)
+          text = text.to_s
+          text = '(no output)' if text.empty?
+          { text: text }
         end
 
         def render_raw_tool_result_content(raw_value)

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