ruby_llm 1.5.0 → 1.6.0

data/lib/ruby_llm/providers/openai.rb

@@ -5,51 +5,39 @@ module RubyLLM
     # OpenAI API integration. Handles chat completion, function calling,
     # and OpenAI's unique streaming format. Supports GPT-4, GPT-3.5,
     # and other OpenAI models.
-    module OpenAI
-      extend Provider
-      extend OpenAI::Chat
-      extend OpenAI::Embeddings
-      extend OpenAI::Models
-      extend OpenAI::Streaming
-      extend OpenAI::Tools
-      extend OpenAI::Images
-      extend OpenAI::Media
-
-      def self.extended(base)
-        base.extend(Provider)
-        base.extend(OpenAI::Chat)
-        base.extend(OpenAI::Embeddings)
-        base.extend(OpenAI::Models)
-        base.extend(OpenAI::Streaming)
-        base.extend(OpenAI::Tools)
-        base.extend(OpenAI::Images)
-        base.extend(OpenAI::Media)
+    class OpenAI < Provider
+      include OpenAI::Chat
+      include OpenAI::Embeddings
+      include OpenAI::Models
+      include OpenAI::Streaming
+      include OpenAI::Tools
+      include OpenAI::Images
+      include OpenAI::Media
+
+      def api_base
+        @config.openai_api_base || 'https://api.openai.com/v1'
       end
 
-      module_function
-
-      def api_base(config)
-        config.openai_api_base || 'https://api.openai.com/v1'
-      end
-
-      def headers(config)
+      def headers
         {
-          'Authorization' => "Bearer #{config.openai_api_key}",
-          'OpenAI-Organization' => config.openai_organization_id,
-          'OpenAI-Project' => config.openai_project_id
+          'Authorization' => "Bearer #{@config.openai_api_key}",
+          'OpenAI-Organization' => @config.openai_organization_id,
+          'OpenAI-Project' => @config.openai_project_id
         }.compact
       end
 
-      def capabilities
-        OpenAI::Capabilities
+      def maybe_normalize_temperature(temperature, model_id)
+        OpenAI::Capabilities.normalize_temperature(temperature, model_id)
       end
 
-      def slug
-        'openai'
-      end
+      class << self
+        def capabilities
+          OpenAI::Capabilities
+        end
 
-      def configuration_requirements
-        %i[openai_api_key]
+        def configuration_requirements
+          %i[openai_api_key]
+        end
       end
     end
   end

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

@@ -2,7 +2,7 @@
 
 module RubyLLM
   module Providers
-    module OpenRouter
+    class OpenRouter
       # Models methods of the OpenRouter API integration
       module Models
         module_function

data/lib/ruby_llm/providers/openrouter.rb

@@ -3,28 +3,23 @@
 module RubyLLM
   module Providers
     # OpenRouter API integration.
-    module OpenRouter
-      extend OpenAI
-      extend OpenRouter::Models
+    class OpenRouter < OpenAI
+      include OpenRouter::Models
 
-      module_function
-
-      def api_base(_config)
+      def api_base
         'https://openrouter.ai/api/v1'
       end
 
-      def headers(config)
+      def headers
         {
-          'Authorization' => "Bearer #{config.openrouter_api_key}"
+          'Authorization' => "Bearer #{@config.openrouter_api_key}"
         }
       end
 
-      def slug
-        'openrouter'
-      end
-
-      def configuration_requirements
-        %i[openrouter_api_key]
+      class << self
+        def configuration_requirements
+          %i[openrouter_api_key]
+        end
       end
     end
   end

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

@@ -2,14 +2,11 @@
 
 module RubyLLM
   module Providers
-    module Perplexity
+    class Perplexity
       # Determines capabilities and pricing for Perplexity models
       module Capabilities
         module_function
 
-        # Returns the context window size for the given model ID
-        # @param model_id [String] the model identifier
-        # @return [Integer] the context window size in tokens
         def context_window_for(model_id)
           case model_id
           when /sonar-pro/ then 200_000
@@ -17,9 +14,6 @@ module RubyLLM
           end
         end
 
-        # Returns the maximum number of tokens that can be generated
-        # @param model_id [String] the model identifier
-        # @return [Integer] the maximum number of tokens
         def max_tokens_for(model_id)
           case model_id
           when /sonar-(?:pro|reasoning-pro)/ then 8_192
@@ -27,23 +21,14 @@ module RubyLLM
           end
         end
 
-        # Returns the price per million tokens for input
-        # @param model_id [String] the model identifier
-        # @return [Float] the price per million tokens in USD
         def input_price_for(model_id)
           PRICES.dig(model_family(model_id), :input) || 1.0
         end
 
-        # Returns the price per million tokens for output
-        # @param model_id [String] the model identifier
-        # @return [Float] the price per million tokens in USD
         def output_price_for(model_id)
           PRICES.dig(model_family(model_id), :output) || 1.0
         end
 
-        # Determines if the model supports vision capabilities
-        # @param model_id [String] the model identifier
-        # @return [Boolean] true if the model supports vision
         def supports_vision?(model_id)
           case model_id
           when /sonar-reasoning-pro/, /sonar-reasoning/, /sonar-pro/, /sonar/ then true
@@ -51,21 +36,14 @@ module RubyLLM
           end
         end
 
-        # Determines if the model supports function calling
-        # @param model_id [String] the model identifier
-        # @return [Boolean] true if the model supports functions
         def supports_functions?(_model_id)
           false
         end
 
-        # Determines if the model supports JSON mode
         def supports_json_mode?(_model_id)
           true
         end
 
-        # Formats the model ID into a human-readable display name
-        # @param model_id [String] the model identifier
-        # @return [String] the formatted display name
         def format_display_name(model_id)
           case model_id
           when 'sonar' then 'Sonar'
@@ -80,16 +58,10 @@ module RubyLLM
           end
         end
 
-        # Returns the model type
-        # @param model_id [String] the model identifier
-        # @return [String] the model type (e.g., 'chat')
         def model_type(_model_id)
           'chat'
         end
 
-        # Returns the model family
-        # @param model_id [String] the model identifier
-        # @return [Symbol] the model family
         def model_family(model_id)
           case model_id
           when 'sonar' then :sonar
@@ -123,7 +95,6 @@ module RubyLLM
             output_per_million: prices[:output]
           }
 
-          # Add special pricing if available
           standard_pricing[:citation_per_million] = prices[:citation] if prices[:citation]
           standard_pricing[:reasoning_per_million] = prices[:reasoning] if prices[:reasoning]
           standard_pricing[:search_per_thousand] = prices[:search_queries] if prices[:search_queries]

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

@@ -2,7 +2,7 @@
 
 module RubyLLM
   module Providers
-    module Perplexity
+    class Perplexity
       # Chat formatting for Perplexity provider
       module Chat
         module_function

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

@@ -2,7 +2,7 @@
 
 module RubyLLM
   module Providers
-    module Perplexity
+    class Perplexity
       # Models methods of the Perplexity API integration
       module Models
         def list_models(**)

data/lib/ruby_llm/providers/perplexity.rb

@@ -3,34 +3,29 @@
 module RubyLLM
   module Providers
     # Perplexity API integration.
-    module Perplexity
-      extend OpenAI
-      extend Perplexity::Chat
-      extend Perplexity::Models
+    class Perplexity < OpenAI
+      include Perplexity::Chat
+      include Perplexity::Models
 
-      module_function
-
-      def api_base(_config)
+      def api_base
         'https://api.perplexity.ai'
       end
 
-      def headers(config)
+      def headers
         {
-          'Authorization' => "Bearer #{config.perplexity_api_key}",
+          'Authorization' => "Bearer #{@config.perplexity_api_key}",
           'Content-Type' => 'application/json'
         }
       end
 
-      def capabilities
-        Perplexity::Capabilities
-      end
-
-      def slug
-        'perplexity'
-      end
+      class << self
+        def capabilities
+          Perplexity::Capabilities
+        end
 
-      def configuration_requirements
-        %i[perplexity_api_key]
+        def configuration_requirements
+          %i[perplexity_api_key]
+        end
       end
 
       def parse_error(response)

data/lib/ruby_llm/stream_accumulator.rb

@@ -16,7 +16,7 @@ module RubyLLM
     end
 
     def add(chunk)
-      RubyLLM.logger.debug chunk.inspect
+      RubyLLM.logger.debug chunk.inspect if RubyLLM.config.log_stream_debug
       @model_id ||= chunk.model_id
 
       if chunk.tool_call?
@@ -26,7 +26,7 @@ module RubyLLM
       end
 
       count_tokens chunk
-      RubyLLM.logger.debug inspect
+      RubyLLM.logger.debug inspect if RubyLLM.config.log_stream_debug
     end
 
     def to_message(response)
@@ -62,7 +62,7 @@ module RubyLLM
     end
 
     def accumulate_tool_calls(new_tool_calls)
-      RubyLLM.logger.debug "Accumulating tool calls: #{new_tool_calls}"
+      RubyLLM.logger.debug "Accumulating tool calls: #{new_tool_calls}" if RubyLLM.config.log_stream_debug
       new_tool_calls.each_value do |tool_call|
         if tool_call.id
           tool_call_id = tool_call.id.empty? ? SecureRandom.uuid : tool_call.id

data/lib/ruby_llm/streaming.rb

@@ -8,10 +8,12 @@ module RubyLLM
   module Streaming
     module_function
 
-    def stream_response(connection, payload, &block)
+    def stream_response(connection, payload, additional_headers = {}, &block)
       accumulator = StreamAccumulator.new
 
       response = connection.post stream_url, payload do |req|
+        # Merge additional headers, with existing headers taking precedence
+        req.headers = additional_headers.merge(req.headers) unless additional_headers.empty?
         if req.options.respond_to?(:on_data)
           # Handle Faraday 2.x streaming with on_data method
           req.options.on_data = handle_stream do |chunk|
@@ -27,7 +29,9 @@ module RubyLLM
         end
       end
 
-      accumulator.to_message(response)
+      message = accumulator.to_message(response)
+      RubyLLM.logger.debug "Stream completed: #{message.inspect}"
+      message
     end
 
     def handle_stream(&block)
@@ -56,7 +60,7 @@ module RubyLLM
     end
 
     def process_stream_chunk(chunk, parser, env, &)
-      RubyLLM.logger.debug "Received chunk: #{chunk}"
+      RubyLLM.logger.debug "Received chunk: #{chunk}" if RubyLLM.config.log_stream_debug
 
       if error_chunk?(chunk)
         handle_error_chunk(chunk, env)
@@ -145,5 +149,14 @@ module RubyLLM
     rescue JSON::ParserError => e
       RubyLLM.logger.debug "Failed to parse error event: #{e.message}"
     end
+
+    # Default implementation - providers should override this method
+    def parse_streaming_error(data)
+      error_data = JSON.parse(data)
+      [500, error_data['message'] || 'Unknown streaming error']
+    rescue JSON::ParserError => e
+      RubyLLM.logger.debug "Failed to parse streaming error: #{e.message}"
+      [500, "Failed to parse error: #{data}"]
+    end
   end
 end

data/lib/ruby_llm/tool.rb

@@ -32,6 +32,19 @@ module RubyLLM
   #       end
   #    end
   class Tool
+    # Stops conversation continuation after tool execution
+    class Halt
+      attr_reader :content
+
+      def initialize(content)
+        @content = content
+      end
+
+      def to_s
+        @content.to_s
+      end
+    end
+
     class << self
       def description(text = nil)
         return @description unless text
@@ -77,5 +90,11 @@ module RubyLLM
     def execute(...)
       raise NotImplementedError, 'Subclasses must implement #execute'
     end
+
+    protected
+
+    def halt(message)
+      Halt.new(message)
+    end
   end
 end

data/lib/ruby_llm/utils.rb

@@ -24,6 +24,18 @@ module RubyLLM
       end
     end
 
+    def to_time(value)
+      return unless value
+
+      value.is_a?(Time) ? value : Time.parse(value.to_s)
+    end
+
+    def to_date(value)
+      return unless value
+
+      value.is_a?(Date) ? value : Date.parse(value.to_s)
+    end
+
     def deep_merge(params, payload)
       params.merge(payload) do |_key, params_value, payload_value|
         if params_value.is_a?(Hash) && payload_value.is_a?(Hash)

data/lib/ruby_llm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  VERSION = '1.5.0'
+  VERSION = '1.6.0'
 end

data/lib/tasks/models_docs.rake

@@ -12,8 +12,8 @@ namespace :models do
     output = generate_models_markdown
 
     # Write the output
-    File.write('docs/available-models.md', output)
-    puts 'Generated docs/available-models.md'
+    File.write('docs/_reference/available-models.md', output)
+    puts 'Generated docs/_reference/available-models.md'
   end
 end
 
@@ -22,15 +22,16 @@ def generate_models_markdown
     ---
     layout: default
     title: Available Models
-    nav_order: 5
-    permalink: /available-models
+    nav_order: 1
     description: Browse hundreds of AI models from every major provider. Always up-to-date, automatically generated.
+    redirect_from:
+      - /guides/available-models
     ---
 
-    # Available Models
+    # {{ page.title }}
     {: .no_toc }
 
-    Every model, every provider, always current. Your complete AI model reference.
+    {{ page.description }}
     {: .fs-6 .fw-300 }
 
     ## Table of contents
@@ -41,6 +42,13 @@ def generate_models_markdown
 
     ---
 
+    After reading this guide, you will know:
+
+    * How RubyLLM's model registry works and where data comes from
+    * How to find models by provider, capability, or purpose
+    * What information is available for each model
+    * How to use model aliases for simpler configuration
+
     ## How Model Data Works
 
     RubyLLM's model registry combines data from multiple sources:
@@ -78,12 +86,12 @@ def generate_models_markdown
 end
 
 def generate_provider_sections
-  RubyLLM::Provider.providers.keys.map do |provider|
+  RubyLLM::Provider.providers.map do |provider, provider_class|
     models = RubyLLM.models.by_provider(provider)
     next if models.none?
 
     <<~PROVIDER
-      ### #{provider.to_s.capitalize} (#{models.count})
+      ### #{provider_class.name} (#{models.count})
 
       #{models_table(models)}
     PROVIDER
@@ -167,15 +175,14 @@ end
 def models_table(models)
   return '*No models found*' if models.none?
 
-  headers = ['Model', 'ID', 'Provider', 'Context', 'Max Output', 'Standard Pricing (per 1M tokens)']
-  alignment = [':--', ':--', ':--', '--:', '--:', ':--']
+  headers = ['Model', 'Provider', 'Context', 'Max Output', 'Standard Pricing (per 1M tokens)']
+  alignment = [':--', ':--', '--:', '--:', ':--']
 
   rows = models.sort_by { |m| [m.provider, m.name] }.map do |model|
     # Format pricing information
     pricing = standard_pricing_display(model)
 
     [
-      model.name,
       model.id,
       model.provider,
       model.context_window || '-',

data/lib/tasks/models_update.rake

@@ -2,6 +2,7 @@
 
 require 'dotenv/load'
 require 'ruby_llm'
+require 'json-schema'
 
 task default: ['models:update']
 
@@ -49,6 +50,9 @@ def refresh_models
   elsif models.all.size == initial_count && initial_count.positive?
     puts 'Warning: Model list unchanged.'
   else
+    puts 'Validating models...'
+    validate_models!(models)
+
     puts "Saving models.json (#{models.all.size} models)"
     models.save_models
   end
@@ -56,12 +60,34 @@ def refresh_models
   @models = models
 end
 
+def validate_models!(models)
+  schema_path = File.expand_path('../ruby_llm/models_schema.json', __dir__)
+  models_data = models.all.map(&:to_h)
+
+  validation_errors = JSON::Validator.fully_validate(schema_path, models_data)
+
+  unless validation_errors.empty?
+    # Save failed models for inspection
+    failed_path = File.expand_path('../ruby_llm/models.failed.json', __dir__)
+    File.write(failed_path, JSON.pretty_generate(models_data))
+
+    puts 'ERROR: Models validation failed:'
+    puts "\nValidation errors:"
+    validation_errors.first(10).each { |error| puts "  - #{error}" }
+    puts "  ... and #{validation_errors.size - 10} more errors" if validation_errors.size > 10
+    puts "-> Failed models saved to: #{failed_path}"
+    exit(1)
+  end
+
+  puts '✓ Models validation passed'
+end
+
 def display_model_stats
   puts "\nModel count:"
   provider_counts = @models.all.group_by(&:provider).transform_values(&:count)
 
-  RubyLLM::Provider.providers.each_key do |sym|
-    name = sym.to_s.capitalize
+  RubyLLM::Provider.providers.each do |sym, provider_class|
+    name = provider_class.name
     count = provider_counts[sym.to_s] || 0
     status = status(sym)
     puts "  #{name}: #{count} models #{status}"
@@ -71,9 +97,10 @@ def display_model_stats
 end
 
 def status(provider_sym)
-  if RubyLLM::Provider.providers[provider_sym].local?
+  provider_class = RubyLLM::Provider.providers[provider_sym]
+  if provider_class.local?
     ' (LOCAL - SKIP)'
-  elsif RubyLLM::Provider.providers[provider_sym].configured?
+  elsif provider_class.configured?(RubyLLM.config)
     ' (OK)'
   else
     ' (NOT CONFIGURED)'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Carmine Paolino
@@ -168,6 +168,7 @@ files:
 - lib/ruby_llm/model/pricing_tier.rb
 - lib/ruby_llm/models.json
 - lib/ruby_llm/models.rb
+- lib/ruby_llm/models_schema.json
 - lib/ruby_llm/provider.rb
 - lib/ruby_llm/providers/anthropic.rb
 - lib/ruby_llm/providers/anthropic/capabilities.rb