Add provider configuration checks and selective model refresh

- Add configuration_requirements for each provider to specify needed configs
- Show helpful error messages with exact config code needed
- Make Models.refresh! ignore unconfigured providers while preserving their models
- Add informative logging about which providers are being refreshed/skipped

Author: crmne

lib/ruby_llm/error.rb

@@ -22,6 +22,7 @@ def initialize(response = nil, message = nil)
   class ModelNotFoundError < StandardError; end
   class InvalidRoleError < StandardError; end
   class UnsupportedFunctionsError < StandardError; end
+  class ConfigurationError < StandardError; end
   class UnauthorizedError < Error; end
   class PaymentRequiredError < Error; end
   class ServiceUnavailableError < Error; end

lib/ruby_llm/models.rb

@@ -26,10 +26,21 @@ def models_file
         File.expand_path('models.json', __dir__)
       end
 
-      # Class method to refresh model data
-      def refresh!
-        models = RubyLLM.providers.flat_map(&:list_models).sort_by(&:id)
-        @instance = new(models)
+      def refresh! # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity
+        configured = Provider.configured_providers
+
+        # Log provider status
+        skipped = Provider.providers.values - configured
+        RubyLLM.logger.info "Refreshing models from #{configured.map(&:slug).join(', ')}" if configured.any?
+        RubyLLM.logger.info "Skipping #{skipped.map(&:slug).join(', ')} - providers not configured" if skipped.any?
+
+        # Store current models except from configured providers
+        current = instance.load_models
+        preserved = current.reject { |m| configured.map(&:slug).include?(m.provider) }
+
+        @instance = new(preserved + configured.flat_map(&:list_models))
+        @instance.save_models
+        @instance
       end
 
       def method_missing(method, ...)
@@ -52,10 +63,10 @@ def initialize(models = nil)
 
     # Load models from the JSON file
     def load_models
-      data = JSON.parse(File.read(self.class.models_file))
-      data.map { |model| ModelInfo.new(model.transform_keys(&:to_sym)) }
-    rescue Errno::ENOENT
-      [] # Return empty array if file doesn't exist yet
+      data = File.exist?(self.class.models_file) ? File.read(self.class.models_file) : '[]'
+      JSON.parse(data).map { |model| ModelInfo.new(model.transform_keys(&:to_sym)) }
+    rescue JSON::ParserError
+      []
     end
 
     def save_models

lib/ruby_llm/provider.rb

@@ -49,8 +49,32 @@ def paint(prompt, model:, size:)
         parse_image_response(response)
       end
 
+      def configured?
+        missing_configs.empty?
+      end
+
       private
 
+      def missing_configs
+        configuration_requirements.select do |key|
+          value = RubyLLM.config.send(key)
+          value.nil? || value.empty?
+        end
+      end
+
+      def ensure_configured!
+        return if configured?
+
+        config_block = <<~RUBY
+          RubyLLM.configure do |config|
+            #{missing_configs.map { |key| "config.#{key} = ENV['#{key.to_s.upcase}']" }.join("\n    ")}
+          end
+        RUBY
+
+        raise ConfigurationError,
+              "#{slug} provider is not configured. Add this to your initialization:\n\n#{config_block}"
+      end
+
       def sync_response(payload)
         response = post completion_url, payload
         parse_completion_response response
@@ -77,6 +101,8 @@ def post(url, payload)
       end
 
       def connection # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+        ensure_configured!
+
         @connection ||= Faraday.new(api_base) do |f| # rubocop:disable Metrics/BlockLength
           f.options.timeout = RubyLLM.config.request_timeout
 
@@ -178,6 +204,19 @@ def parse_data_uri(uri)
       nil
     end
 
+    def configured?
+      missing_configs = configuration_requirements.select do |key|
+        value = RubyLLM.config.send(key)
+        value.nil? || value.empty?
+      end
+
+      return true if missing_configs.empty?
+
+      required = missing_configs.map { |key| "config.#{key}" }.join(', ')
+      @configuration_error = "#{slug} provider is not configured. Please set: #{required}"
+      false
+    end
+
     class << self
       def extended(base)
         base.extend(Methods)
@@ -195,6 +234,10 @@ def for(model)
       def providers
         @providers ||= {}
       end
+
+      def configured_providers
+        providers.select { |_name, provider| provider.configured? }.values
+      end
     end
   end
 end

lib/ruby_llm/providers/anthropic.rb

@@ -33,6 +33,10 @@ def capabilities
       def slug
         'anthropic'
       end
+
+      def configuration_requirements
+        %i[anthropic_api_key]
+      end
     end
   end
 end

lib/ruby_llm/providers/deepseek.rb

@@ -25,6 +25,10 @@ def capabilities
       def slug
         'deepseek'
       end
+
+      def configuration_requirements
+        %i[deepseek_api_key]
+      end
     end
   end
 end

lib/ruby_llm/providers/gemini.rb

@@ -32,6 +32,10 @@ def capabilities
       def slug
         'gemini'
       end
+
+      def configuration_requirements
+        %i[gemini_api_key]
+      end
     end
   end
 end

lib/ruby_llm/providers/openai.rb

@@ -45,6 +45,10 @@ def capabilities
       def slug
         'openai'
       end
+
+      def configuration_requirements
+        %i[openai_api_key]
+      end
     end
   end
 end

lib/tasks/models.rake

@@ -68,10 +68,10 @@ namespace :models do # rubocop:disable Metrics/BlockLength
   task :update do
     # Configure API keys
     RubyLLM.configure do |config|
-      config.openai_api_key = ENV.fetch('OPENAI_API_KEY')
-      config.anthropic_api_key = ENV.fetch('ANTHROPIC_API_KEY')
-      config.gemini_api_key = ENV.fetch('GEMINI_API_KEY')
-      config.deepseek_api_key = ENV.fetch('DEEPSEEK_API_KEY')
+      config.openai_api_key = ENV.fetch('OPENAI_API_KEY', nil)
+      config.anthropic_api_key = ENV.fetch('ANTHROPIC_API_KEY', nil)
+      config.gemini_api_key = ENV.fetch('GEMINI_API_KEY', nil)
+      config.deepseek_api_key = ENV.fetch('DEEPSEEK_API_KEY', nil)
     end
 
     models = RubyLLM.models.refresh!

spec/spec_helper.rb

@@ -84,10 +84,10 @@
 RSpec.shared_context 'with configured RubyLLM' do
   before do
     RubyLLM.configure do |config|
-      config.openai_api_key = ENV.fetch('OPENAI_API_KEY')
-      config.anthropic_api_key = ENV.fetch('ANTHROPIC_API_KEY')
-      config.gemini_api_key = ENV.fetch('GEMINI_API_KEY')
-      config.deepseek_api_key = ENV.fetch('DEEPSEEK_API_KEY')
+      config.openai_api_key = ENV.fetch('OPENAI_API_KEY', 'test')
+      config.anthropic_api_key = ENV.fetch('ANTHROPIC_API_KEY', 'test')
+      config.gemini_api_key = ENV.fetch('GEMINI_API_KEY', 'test')
+      config.deepseek_api_key = ENV.fetch('DEEPSEEK_API_KEY', 'test')
       config.max_retries = 50
     end
   end