ruby_llm 1.9.2 → 1.11.0

data/lib/ruby_llm/streaming.rb

@@ -29,7 +29,7 @@ module RubyLLM
     end
 
     def handle_stream(&block)
-      to_json_stream do |data|
+      build_on_data_handler do |data|
         block.call(build_chunk(data)) if data
       end
     end
@@ -40,19 +40,15 @@ module RubyLLM
       Faraday::VERSION.start_with?('1')
     end
 
-    def to_json_stream(&)
+    def build_on_data_handler(&handler)
       buffer = +''
       parser = EventStreamParser::Parser.new
 
-      create_stream_processor(parser, buffer, &)
-    end
-
-    def create_stream_processor(parser, buffer, &)
-      if faraday_1?
-        legacy_stream_processor(parser, &)
-      else
-        stream_processor(parser, buffer, &)
-      end
+      FaradayHandlers.build(
+        faraday_v1: faraday_1?,
+        on_chunk: ->(chunk, env) { process_stream_chunk(chunk, parser, env, &handler) },
+        on_failed_response: ->(chunk, env) { handle_failed_response(chunk, buffer, env) }
+      )
     end
 
     def process_stream_chunk(chunk, parser, env, &)
@@ -67,22 +63,6 @@ module RubyLLM
       end
     end
 
-    def legacy_stream_processor(parser, &block)
-      proc do |chunk, _size|
-        process_stream_chunk(chunk, parser, nil, &block)
-      end
-    end
-
-    def stream_processor(parser, buffer, &block)
-      proc do |chunk, _bytes, env|
-        if env&.status == 200
-          process_stream_chunk(chunk, parser, env, &block)
-        else
-          handle_failed_response(chunk, buffer, env)
-        end
-      end
-    end
-
     def error_chunk?(chunk)
       chunk.start_with?('event: error')
     end
@@ -92,30 +72,18 @@ module RubyLLM
     end
 
     def handle_json_error_chunk(chunk, env)
-      parsed_data = JSON.parse(chunk)
-      status, _message = parse_streaming_error(parsed_data.to_json)
-      error_response = build_stream_error_response(parsed_data, env, status)
-      ErrorMiddleware.parse_error(provider: self, response: error_response)
-    rescue JSON::ParserError => e
-      RubyLLM.logger.debug "Failed to parse JSON error chunk: #{e.message}"
+      parse_error_from_json(chunk, env, 'Failed to parse JSON error chunk')
     end
 
     def handle_error_chunk(chunk, env)
       error_data = chunk.split("\n")[1].delete_prefix('data: ')
-      parsed_data = JSON.parse(error_data)
-      status, _message = parse_streaming_error(parsed_data.to_json)
-      error_response = build_stream_error_response(parsed_data, env, status)
-      ErrorMiddleware.parse_error(provider: self, response: error_response)
-    rescue JSON::ParserError => e
-      RubyLLM.logger.debug "Failed to parse error chunk: #{e.message}"
+      parse_error_from_json(error_data, env, 'Failed to parse error chunk')
     end
 
     def handle_failed_response(chunk, buffer, env)
       buffer << chunk
       error_data = JSON.parse(buffer)
-      status, _message = parse_streaming_error(error_data.to_json)
-      error_response = env.merge(body: error_data, status: status || env.status)
-      ErrorMiddleware.parse_error(provider: self, response: error_response)
+      handle_parsed_error(error_data, env)
     rescue JSON::ParserError
       RubyLLM.logger.debug "Accumulating error chunk: #{chunk}"
     end
@@ -135,20 +103,13 @@ module RubyLLM
       parsed = JSON.parse(data)
       return parsed unless parsed.is_a?(Hash) && parsed.key?('error')
 
-      status, _message = parse_streaming_error(parsed.to_json)
-      error_response = build_stream_error_response(parsed, env, status)
-      ErrorMiddleware.parse_error(provider: self, response: error_response)
+      handle_parsed_error(parsed, env)
     rescue JSON::ParserError => e
       RubyLLM.logger.debug "Failed to parse data chunk: #{e.message}"
     end
 
     def handle_error_event(data, env)
-      parsed_data = JSON.parse(data)
-      status, _message = parse_streaming_error(parsed_data.to_json)
-      error_response = build_stream_error_response(parsed_data, env, status)
-      ErrorMiddleware.parse_error(provider: self, response: error_response)
-    rescue JSON::ParserError => e
-      RubyLLM.logger.debug "Failed to parse error event: #{e.message}"
+      parse_error_from_json(data, env, 'Failed to parse error event')
     end
 
     def parse_streaming_error(data)
@@ -159,6 +120,19 @@ module RubyLLM
       [500, "Failed to parse error: #{data}"]
     end
 
+    def handle_parsed_error(parsed_data, env)
+      status, _message = parse_streaming_error(parsed_data.to_json)
+      error_response = build_stream_error_response(parsed_data, env, status)
+      ErrorMiddleware.parse_error(provider: self, response: error_response)
+    end
+
+    def parse_error_from_json(data, env, error_message)
+      parsed_data = JSON.parse(data)
+      handle_parsed_error(parsed_data, env)
+    rescue JSON::ParserError => e
+      RubyLLM.logger.debug "#{error_message}: #{e.message}"
+    end
+
     def build_stream_error_response(parsed_data, env, status)
       error_status = status || env&.status || 500
 
@@ -168,5 +142,34 @@ module RubyLLM
         env.merge(body: parsed_data, status: error_status)
       end
     end
+
+    # Builds Faraday on_data handlers for different major versions.
+    module FaradayHandlers
+      module_function
+
+      def build(faraday_v1:, on_chunk:, on_failed_response:)
+        if faraday_v1
+          v1_on_data(on_chunk)
+        else
+          v2_on_data(on_chunk, on_failed_response)
+        end
+      end
+
+      def v1_on_data(on_chunk)
+        proc do |chunk, _size|
+          on_chunk.call(chunk, nil)
+        end
+      end
+
+      def v2_on_data(on_chunk, on_failed_response)
+        proc do |chunk, _bytes, env|
+          if env&.status == 200
+            on_chunk.call(chunk, env)
+          else
+            on_failed_response.call(chunk, env)
+          end
+        end
+      end
+    end
   end
 end

data/lib/ruby_llm/thinking.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Represents provider thinking output.
+  class Thinking
+    attr_reader :text, :signature
+
+    def initialize(text: nil, signature: nil)
+      @text = text
+      @signature = signature
+    end
+
+    def self.build(text: nil, signature: nil)
+      text = nil if text.is_a?(String) && text.empty?
+      signature = nil if signature.is_a?(String) && signature.empty?
+
+      return nil if text.nil? && signature.nil?
+
+      new(text: text, signature: signature)
+    end
+
+    def pretty_print(printer)
+      printer.object_group(self) do
+        printer.breakable
+        printer.text 'text='
+        printer.pp text
+        printer.comma_breakable
+        printer.text 'signature='
+        printer.pp(signature ? '[REDACTED]' : nil)
+      end
+    end
+  end
+
+  class Thinking
+    # Normalized config for thinking across providers.
+    class Config
+      attr_reader :effort, :budget
+
+      def initialize(effort: nil, budget: nil)
+        @effort = effort.is_a?(Symbol) ? effort.to_s : effort
+        @budget = budget
+      end
+
+      def enabled?
+        !effort.nil? || !budget.nil?
+      end
+    end
+  end
+end

data/lib/ruby_llm/tokens.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Represents token usage for a response.
+  class Tokens
+    attr_reader :input, :output, :cached, :cache_creation, :thinking
+
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(input: nil, output: nil, cached: nil, cache_creation: nil, thinking: nil, reasoning: nil)
+      @input = input
+      @output = output
+      @cached = cached
+      @cache_creation = cache_creation
+      @thinking = thinking || reasoning
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # rubocop:disable Metrics/ParameterLists
+    def self.build(input: nil, output: nil, cached: nil, cache_creation: nil, thinking: nil, reasoning: nil)
+      return nil if [input, output, cached, cache_creation, thinking, reasoning].all?(&:nil?)
+
+      new(
+        input: input,
+        output: output,
+        cached: cached,
+        cache_creation: cache_creation,
+        thinking: thinking,
+        reasoning: reasoning
+      )
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    def to_h
+      {
+        input_tokens: input,
+        output_tokens: output,
+        cached_tokens: cached,
+        cache_creation_tokens: cache_creation,
+        thinking_tokens: thinking
+      }.compact
+    end
+
+    def reasoning
+      thinking
+    end
+  end
+end

data/lib/ruby_llm/tool_call.rb

@@ -4,19 +4,22 @@ module RubyLLM
   # Represents a function call from an AI model to a Tool.
   class ToolCall
     attr_reader :id, :name, :arguments
+    attr_accessor :thought_signature
 
-    def initialize(id:, name:, arguments: {})
+    def initialize(id:, name:, arguments: {}, thought_signature: nil)
       @id = id
       @name = name
       @arguments = arguments
+      @thought_signature = thought_signature
     end
 
     def to_h
       {
         id: @id,
         name: @name,
-        arguments: @arguments
-      }
+        arguments: @arguments,
+        thought_signature: @thought_signature
+      }.compact
     end
   end
 end

data/lib/ruby_llm/version.rb

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

data/lib/ruby_llm.rb

@@ -13,19 +13,20 @@ require 'zeitwerk'
 
 loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect(
-  'ruby_llm' => 'RubyLLM',
-  'llm' => 'LLM',
-  'openai' => 'OpenAI',
+  'UI' => 'UI',
   'api' => 'API',
-  'deepseek' => 'DeepSeek',
-  'perplexity' => 'Perplexity',
   'bedrock' => 'Bedrock',
-  'openrouter' => 'OpenRouter',
+  'deepseek' => 'DeepSeek',
   'gpustack' => 'GPUStack',
+  'llm' => 'LLM',
   'mistral' => 'Mistral',
-  'vertexai' => 'VertexAI',
+  'openai' => 'OpenAI',
+  'openrouter' => 'OpenRouter',
   'pdf' => 'PDF',
-  'UI' => 'UI'
+  'perplexity' => 'Perplexity',
+  'ruby_llm' => 'RubyLLM',
+  'vertexai' => 'VertexAI',
+  'xai' => 'XAI'
 )
 loader.ignore("#{__dir__}/tasks")
 loader.ignore("#{__dir__}/generators")
@@ -100,6 +101,7 @@ RubyLLM::Provider.register :openai, RubyLLM::Providers::OpenAI
 RubyLLM::Provider.register :openrouter, RubyLLM::Providers::OpenRouter
 RubyLLM::Provider.register :perplexity, RubyLLM::Providers::Perplexity
 RubyLLM::Provider.register :vertexai, RubyLLM::Providers::VertexAI
+RubyLLM::Provider.register :xai, RubyLLM::Providers::XAI
 
 if defined?(Rails::Railtie)
   require 'ruby_llm/railtie'

data/lib/tasks/models.rake

@@ -45,6 +45,7 @@ def configure_from_env
     config.deepseek_api_key = ENV.fetch('DEEPSEEK_API_KEY', nil)
     config.perplexity_api_key = ENV.fetch('PERPLEXITY_API_KEY', nil)
     config.openrouter_api_key = ENV.fetch('OPENROUTER_API_KEY', nil)
+    config.xai_api_key = ENV.fetch('XAI_API_KEY', nil)
     config.mistral_api_key = ENV.fetch('MISTRAL_API_KEY', nil)
     config.vertexai_location = ENV.fetch('GOOGLE_CLOUD_LOCATION', nil)
     config.vertexai_project_id = ENV.fetch('GOOGLE_CLOUD_PROJECT', nil)
@@ -61,7 +62,8 @@ def configure_bedrock(config)
 end
 
 def refresh_models
-  initial_count = RubyLLM.models.all.size
+  existing_models = RubyLLM::Models.read_from_json
+  initial_count = existing_models.size
   puts "Refreshing models (#{initial_count} cached)..."
 
   models = RubyLLM.models.refresh!
@@ -69,19 +71,29 @@ def refresh_models
   if models.all.empty? && initial_count.zero?
     puts 'Error: Failed to fetch models.'
     exit(1)
-  elsif models.all.size == initial_count && initial_count.positive?
-    puts 'Warning: Model list unchanged.'
   else
-    puts 'Validating models...'
-    validate_models!(models)
+    existing_data = sorted_models_data(existing_models)
+    new_data = sorted_models_data(models.all)
 
-    puts "Saving models.json (#{models.all.size} models)"
-    models.save_to_json
+    if new_data == existing_data && 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_to_json
+    end
   end
 
   @models = models
 end
 
+def sorted_models_data(models)
+  models.map(&:to_h)
+        .sort_by { |model| [model[:provider].to_s, model[:id].to_s] }
+end
+
 def validate_models!(models)
   schema_path = RubyLLM::Models.schema_file
   models_data = models.all.map(&:to_h)
@@ -154,11 +166,7 @@ def generate_models_markdown
 
     ---
 
-    ## Model Data Sources
-
-    - **OpenAI, Anthropic, DeepSeek, Gemini, VertexAI**: Enriched by [models.dev](https://models.dev/) *([LLM metadata API](https://models.dev/api.json))*
-    - **OpenRouter**: Direct API
-    - **Others**: Local capabilities files
+    _Model information enriched by [models.dev](https://models.dev) and our custom code._
 
     ## Last Updated
     {: .d-inline-block }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm
 version: !ruby/object:Gem::Version
-  version: 1.9.2
+  version: 1.11.0
 platform: ruby
 authors:
 - Carmine Paolino
@@ -52,7 +52,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 1.10.0
 - !ruby/object:Gem::Dependency
-  name: faraday-multipart
+  name: faraday-retry
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -66,7 +66,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1'
 - !ruby/object:Gem::Dependency
-  name: faraday-net_http
+  name: faraday-multipart
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -80,7 +80,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1'
 - !ruby/object:Gem::Dependency
-  name: faraday-retry
+  name: faraday-net_http
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -180,6 +180,8 @@ files:
 - lib/generators/ruby_llm/install/templates/message_model.rb.tt
 - lib/generators/ruby_llm/install/templates/model_model.rb.tt
 - lib/generators/ruby_llm/install/templates/tool_call_model.rb.tt
+- lib/generators/ruby_llm/upgrade_to_v1_10/templates/add_v1_10_message_columns.rb.tt
+- lib/generators/ruby_llm/upgrade_to_v1_10/upgrade_to_v1_10_generator.rb
 - lib/generators/ruby_llm/upgrade_to_v1_7/templates/migration.rb.tt
 - lib/generators/ruby_llm/upgrade_to_v1_7/upgrade_to_v1_7_generator.rb
 - lib/generators/ruby_llm/upgrade_to_v1_9/templates/add_v1_9_message_columns.rb.tt
@@ -271,10 +273,13 @@ files:
 - lib/ruby_llm/providers/openai/models.rb
 - lib/ruby_llm/providers/openai/moderation.rb
 - lib/ruby_llm/providers/openai/streaming.rb
+- lib/ruby_llm/providers/openai/temperature.rb
 - lib/ruby_llm/providers/openai/tools.rb
 - lib/ruby_llm/providers/openai/transcription.rb
 - lib/ruby_llm/providers/openrouter.rb
+- lib/ruby_llm/providers/openrouter/chat.rb
 - lib/ruby_llm/providers/openrouter/models.rb
+- lib/ruby_llm/providers/openrouter/streaming.rb
 - lib/ruby_llm/providers/perplexity.rb
 - lib/ruby_llm/providers/perplexity/capabilities.rb
 - lib/ruby_llm/providers/perplexity/chat.rb
@@ -285,9 +290,14 @@ files:
 - lib/ruby_llm/providers/vertexai/models.rb
 - lib/ruby_llm/providers/vertexai/streaming.rb
 - lib/ruby_llm/providers/vertexai/transcription.rb
+- lib/ruby_llm/providers/xai.rb
+- lib/ruby_llm/providers/xai/chat.rb
+- lib/ruby_llm/providers/xai/models.rb
 - lib/ruby_llm/railtie.rb
 - lib/ruby_llm/stream_accumulator.rb
 - lib/ruby_llm/streaming.rb
+- lib/ruby_llm/thinking.rb
+- lib/ruby_llm/tokens.rb
 - lib/ruby_llm/tool.rb
 - lib/ruby_llm/tool_call.rb
 - lib/ruby_llm/transcription.rb
@@ -309,7 +319,7 @@ metadata:
   funding_uri: https://github.com/sponsors/crmne
   rubygems_mfa_required: 'true'
 post_install_message: |
-  Upgrading from RubyLLM <= 1.8.x? Check the upgrade guide for new features and migration instructions
+  Upgrading from RubyLLM < 1.10.x? Check the upgrade guide for new features and migration instructions
   --> https://rubyllm.com/upgrading/
 rdoc_options: []
 require_paths: