ruby_llm 1.15.0 → 1.16.0

data/lib/ruby_llm/providers/xai.rb

@@ -8,7 +8,7 @@ module RubyLLM
       include XAI::Models
 
       def api_base
-        'https://api.x.ai/v1'
+        @config.xai_api_base || 'https://api.x.ai/v1'
       end
 
       def headers
@@ -20,7 +20,7 @@ module RubyLLM
 
       class << self
         def configuration_options
-          %i[xai_api_key]
+          %i[xai_api_key xai_api_base]
         end
 
         def configuration_requirements

data/lib/ruby_llm/railtie.rb

@@ -10,6 +10,10 @@ if defined?(Rails::Railtie)
         end
       end
 
+      initializer 'ruby_llm.instrumentation' do
+        RubyLLM.config.instrumenter ||= ActiveSupport::Notifications
+      end
+
       initializer 'ruby_llm.active_record' do
         ActiveSupport.on_load :active_record do
           require 'ruby_llm/active_record/payload_helpers'
@@ -25,7 +29,7 @@ if defined?(Rails::Railtie)
             require 'ruby_llm/active_record/acts_as_legacy'
             ::ActiveRecord::Base.include RubyLLM::ActiveRecord::ActsAsLegacy
 
-            Rails.logger.warn(
+            RubyLLM.deprecator.warn(
               "\n!!! RubyLLM's legacy acts_as API is deprecated and will be removed in RubyLLM 2.0.0. " \
               "Please consult the migration guide at https://rubyllm.com/upgrading-to-1-7/\n"
             )

data/lib/ruby_llm/stream_accumulator.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'json'
+require 'securerandom'
+
 module RubyLLM
   # Assembles streaming responses from LLMs into complete messages.
   class StreamAccumulator
@@ -18,6 +21,7 @@ module RubyLLM
       @inside_think_tag = false
       @pending_think_tag = +''
       @latest_tool_call_id = nil
+      @tool_call_ids_by_index = {}
     end
 
     def add(chunk)
@@ -72,43 +76,54 @@ module RubyLLM
       end
     end
 
-    def accumulate_tool_calls(new_tool_calls) # rubocop:disable Metrics/PerceivedComplexity
+    def accumulate_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|
+      new_tool_calls.each do |stream_key, tool_call|
         if tool_call.id
-          tool_call_id = tool_call.id.empty? ? SecureRandom.uuid : tool_call.id
-          tool_call_arguments = tool_call.arguments
-          if tool_call_arguments.nil? || (tool_call_arguments.respond_to?(:empty?) && tool_call_arguments.empty?)
-            tool_call_arguments = +''
-          end
-          @tool_calls[tool_call.id] = ToolCall.new(
-            id: tool_call_id,
-            name: tool_call.name,
-            arguments: tool_call_arguments,
-            thought_signature: tool_call.thought_signature
-          )
-          @latest_tool_call_id = tool_call.id
+          start_tool_call(stream_key, tool_call)
         else
-          existing = @tool_calls[@latest_tool_call_id]
-          if existing
-            fragment = tool_call.arguments
-            fragment = '' if fragment.nil?
-            existing.arguments << fragment
-            if tool_call.thought_signature && existing.thought_signature.nil?
-              existing.thought_signature = tool_call.thought_signature
-            end
-          end
+          append_tool_call_fragment(stream_key, tool_call)
         end
       end
     end
 
-    def find_tool_call(tool_call_id)
-      if tool_call_id.nil?
-        @tool_calls[@latest_tool_call]
-      else
-        @latest_tool_call_id = tool_call_id
-        @tool_calls[tool_call_id]
-      end
+    def start_tool_call(stream_key, tool_call)
+      tool_call_id = tool_call.id.empty? ? SecureRandom.uuid : tool_call.id
+      tool_call_key = tool_call.id
+
+      @tool_calls[tool_call_key] = ToolCall.new(
+        id: tool_call_id,
+        name: tool_call.name,
+        arguments: initial_tool_call_arguments(tool_call),
+        thought_signature: tool_call.thought_signature
+      )
+      @tool_call_ids_by_index[stream_key] = tool_call_key unless stream_key.nil?
+      @latest_tool_call_id = tool_call_key
+    end
+
+    def initial_tool_call_arguments(tool_call)
+      arguments = tool_call.arguments
+      return +'' if arguments.nil? || (arguments.respond_to?(:empty?) && arguments.empty?)
+
+      arguments
+    end
+
+    def append_tool_call_fragment(stream_key, tool_call)
+      existing = find_tool_call(stream_key)
+      return unless existing
+
+      fragment = tool_call.arguments
+      fragment = '' if fragment.nil?
+      existing.arguments << fragment
+      return unless tool_call.thought_signature && existing.thought_signature.nil?
+
+      existing.thought_signature = tool_call.thought_signature
+    end
+
+    def find_tool_call(stream_key)
+      return @tool_calls[@latest_tool_call_id] if stream_key.nil?
+
+      @tool_calls[@tool_call_ids_by_index[stream_key]] || @tool_calls[stream_key]
     end
 
     def count_tokens(chunk)

data/lib/ruby_llm/streaming.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require 'event_stream_parser'
+require 'faraday'
+require 'json'
+
 module RubyLLM
   # Handles streaming responses from AI providers.
   module Streaming

data/lib/ruby_llm/tool_concurrency.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Runs multiple tool calls concurrently with Ruby's built-in threads or optional fibers.
+  module ToolConcurrency
+    MODES = %i[threads fibers].freeze
+    Result = Struct.new(:index, :tool_call, :value, :error, keyword_init: true)
+
+    module_function
+
+    def modes
+      MODES
+    end
+
+    def supported?(name)
+      MODES.include?(name)
+    end
+
+    def run(mode, tool_calls, on_result: nil, &)
+      case mode
+      when :threads
+        run_with_threads(tool_calls, on_result:, &)
+      when :fibers
+        run_with_fibers(tool_calls, on_result:, &)
+      end
+    end
+
+    def run_with_threads(tool_calls, on_result:, &execute)
+      executor = rails_executor
+      queue = Queue.new
+      threads = tool_calls.each_value.with_index.map do |tool_call, index|
+        thread = Thread.new { queue << capture_result(index, tool_call, executor, execute) }
+        thread.report_on_exception = false
+        thread
+      end
+
+      collect_results(queue, threads.size, on_result:)
+    ensure
+      threads&.each(&:join)
+    end
+
+    def run_with_fibers(tool_calls, on_result:, &execute)
+      begin
+        require 'async'
+        require 'async/queue'
+      rescue LoadError
+        raise LoadError, "The 'async' gem is required for concurrent tool execution with fibers. " \
+                         "Add `gem 'async'` to your Gemfile or use `concurrency: :threads`."
+      end
+
+      executor = rails_executor
+      Async do |task|
+        queue = Async::Queue.new
+        tasks = tool_calls.each_value.with_index.map do |tool_call, index|
+          task.async { queue << capture_result(index, tool_call, executor, execute) }
+        end
+
+        collect_results(queue, tasks.size, on_result:)
+      ensure
+        tasks&.each(&:wait)
+      end.wait
+    end
+
+    def collect_results(queue, count, on_result:)
+      results = Array.new(count)
+      errors = []
+
+      count.times do
+        result = queue.pop
+        if result.error
+          errors << result.error
+        else
+          results[result.index] = [result.tool_call, result.value]
+          on_result&.call(result.tool_call, result.value)
+        end
+      end
+
+      raise errors.first if errors.any?
+
+      results
+    end
+
+    def capture_result(index, tool_call, rails_executor, execute)
+      tool_call, value = run_tool_call(tool_call, rails_executor, execute)
+      Result.new(index:, tool_call:, value:)
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      Result.new(index:, tool_call:, error: e)
+    end
+
+    def run_tool_call(tool_call, rails_executor, execute)
+      if rails_executor
+        rails_executor.wrap { [tool_call, execute.call(tool_call)] }
+      else
+        [tool_call, execute.call(tool_call)]
+      end
+    end
+
+    def rails_executor
+      defined?(Rails) && Rails.respond_to?(:application) && Rails.application&.executor
+    end
+
+    private_class_method :run_with_threads, :run_with_fibers, :collect_results, :capture_result, :run_tool_call,
+                         :rails_executor
+  end
+end

data/lib/ruby_llm/transcription.rb

@@ -3,7 +3,7 @@
 module RubyLLM
   # Represents a transcription of audio content.
   class Transcription
-    attr_reader :text, :model, :language, :duration, :segments, :input_tokens, :output_tokens
+    attr_reader :text, :model, :language, :duration, :segments, :words, :input_tokens, :output_tokens
 
     def initialize(text:, model:, **attributes)
       @text = text
@@ -11,6 +11,7 @@ module RubyLLM
       @language = attributes[:language]
       @duration = attributes[:duration]
       @segments = attributes[:segments]
+      @words = attributes[:words]
       @input_tokens = attributes[:input_tokens]
       @output_tokens = attributes[:output_tokens]
     end

data/lib/ruby_llm/utils.rb

@@ -32,6 +32,45 @@ module RubyLLM
       value.is_a?(Date) ? value : Date.parse(value.to_s)
     end
 
+    def safe_constantize(name)
+      parts = name.to_s.split('::').reject(&:empty?)
+      return if parts.empty?
+
+      namespace = Object
+      until parts.empty?
+        const_name = parts.shift
+        return unless namespace.const_defined?(const_name, false)
+
+        namespace = namespace.const_get(const_name, false)
+      end
+      namespace
+    rescue NameError
+      nil
+    end
+
+    def parse_iso_date_prefix(value)
+      return value if value.is_a?(Date)
+
+      date = value.to_s.strip
+      return if date.empty?
+
+      case date
+      when /\A\d{4}-\d{2}-\d{2}\z/
+        Date.iso8601(date)
+      when /\A\d{4}-\d{2}\z/
+        Date.iso8601("#{date}-01")
+      when /\A\d{4}\z/
+        Date.iso8601("#{date}-01-01")
+      end
+    rescue ArgumentError
+      nil
+    end
+
+    def iso_date_prefix_to_utc_midnight_string(value)
+      date = parse_iso_date_prefix(value)
+      "#{date.strftime('%Y-%m-%d')} 00:00:00 UTC" if date
+    end
+
     def deep_merge(original, overrides)
       original.merge(overrides) do |_key, original_value, overrides_value|
         if original_value.is_a?(Hash) && overrides_value.is_a?(Hash)

data/lib/ruby_llm/version.rb

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

data/lib/ruby_llm.rb

@@ -12,6 +12,7 @@ require 'securerandom'
 require 'date'
 require 'time'
 require 'zeitwerk'
+require 'ruby_llm/error'
 
 loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect(
@@ -39,9 +40,15 @@ loader.setup
 
 # A delightful Ruby interface to modern AI language models.
 module RubyLLM
-  class Error < StandardError; end
-
   class << self
+    def deprecator
+      @deprecator ||= Deprecator.new
+    end
+
+    def instrument(...)
+      Instrumentation.instrument(...)
+    end
+
     def context
       context_config = config.dup
       yield context_config if block_given?

data/lib/tasks/models.rake

@@ -348,7 +348,7 @@ def pricing_part(pricing_data, key, label)
   "#{label}: $#{format('%.2f', pricing_data[key])}"
 end
 
-def generate_aliases # rubocop:disable Metrics/PerceivedComplexity
+def generate_aliases # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
   models = Hash.new { |h, k| h[k] = [] }
 
   RubyLLM.models.all.each do |model|
@@ -467,12 +467,40 @@ def generate_aliases # rubocop:disable Metrics/PerceivedComplexity
     }
   end
 
+  add_xai_aliases(aliases, models['xai'])
+
   sorted_aliases = aliases.sort.to_h
   File.write(RubyLLM::Aliases.aliases_file, JSON.pretty_generate(sorted_aliases))
 
   puts "Generated #{sorted_aliases.size} aliases"
 end
 
+def add_xai_aliases(aliases, xai_models)
+  return unless xai_models.include?('grok-4.3')
+
+  %w[
+    grok-latest
+    grok-3
+    grok-3-latest
+    grok-3-mini
+    grok-3-mini-latest
+    grok-4
+    grok-4-latest
+    grok-4-fast
+    grok-4-fast-reasoning
+    grok-4-fast-reasoning-latest
+    grok-4-fast-non-reasoning
+    grok-4-fast-non-reasoning-latest
+    grok-4-1-fast
+    grok-4-1-fast-reasoning
+    grok-4-1-fast-reasoning-latest
+    grok-4-1-fast-non-reasoning
+    grok-4-1-fast-non-reasoning-latest
+  ].each do |alias_key|
+    aliases[alias_key] ||= { 'xai' => 'grok-4.3' }
+  end
+end
+
 def group_anthropic_models_by_base_name(anthropic_models)
   grouped = Hash.new { |h, k| h[k] = [] }
 
@@ -519,12 +547,12 @@ def find_best_bedrock_model(anthropic_model, bedrock_models) # rubocop:disable M
                  when 'claude-instant-v1', 'claude-instant'
                    'claude-instant'
                  else
-                   extract_base_name(anthropic_model)
+                   anthropic_model
                  end
 
   matching_models = bedrock_models.select do |bedrock_model|
-    model_without_prefix = bedrock_model.sub(/^(?:us\.)?anthropic\./, '')
-    model_without_prefix.start_with?(base_pattern)
+    model_without_prefix = bedrock_model.sub(/^(?:(?:[a-z]{2}|global)\.)?anthropic\./, '')
+    model_without_prefix.match?(/\A#{Regexp.escape(base_pattern)}(?:-v\d+|:\d+k|$)/)
   end
 
   return nil if matching_models.empty?

data/lib/tasks/release.rake

@@ -1,5 +1,48 @@
 # frozen_string_literal: true
 
+require 'time'
+require 'yaml'
+
+# Shared helpers for release-related Rake tasks.
+module ReleaseTasks
+  module_function
+
+  def cassette_recorded_at_times(cassette)
+    data = YAML.safe_load_file(cassette, aliases: true)
+
+    Array(data['http_interactions']).filter_map do |interaction|
+      Time.parse(interaction['recorded_at'])
+    rescue ArgumentError, TypeError
+      nil
+    end
+  rescue Psych::Exception => e
+    abort "Could not parse VCR cassette #{cassette}: #{e.message}"
+  end
+
+  def cassette_recorded_at(cassette)
+    recorded_at_times = cassette_recorded_at_times(cassette)
+
+    abort "No recorded_at timestamps found in VCR cassette #{cassette}" if recorded_at_times.empty?
+
+    recorded_at_times.min
+  end
+
+  def find_stale_cassettes(cassette_dir, max_age_days)
+    Dir.glob("#{cassette_dir}/**/*.yml").filter_map do |cassette|
+      recorded_at = cassette_recorded_at(cassette)
+      age_days = (Time.now - recorded_at) / 86_400
+
+      next unless age_days > max_age_days
+
+      {
+        path: cassette,
+        file: File.basename(cassette),
+        age: age_days.round(1)
+      }
+    end
+  end
+end
+
 namespace :release do # rubocop:disable Metrics/BlockLength
   desc 'Prepare for release'
   task :prepare do
@@ -13,18 +56,15 @@ namespace :release do # rubocop:disable Metrics/BlockLength
     max_age_days = 1
     cassette_dir = 'spec/fixtures/vcr_cassettes'
 
-    stale_count = 0
-    Dir.glob("#{cassette_dir}/**/*.yml").each do |cassette|
-      age_days = (Time.now - File.mtime(cassette)) / 86_400
-      next unless age_days > max_age_days
+    stale_cassettes = ReleaseTasks.find_stale_cassettes(cassette_dir, max_age_days)
 
-      puts "Removing stale cassette: #{File.basename(cassette)} (#{age_days.round(1)} days old)"
-      File.delete(cassette)
-      stale_count += 1
+    stale_cassettes.each do |cassette|
+      puts "Removing stale cassette: #{cassette[:file]} (#{cassette[:age]} days old)"
+      File.delete(cassette[:path])
     end
 
-    if stale_count.positive?
-      puts "\n🗑️  Removed #{stale_count} stale cassettes"
+    if stale_cassettes.any?
+      puts "\n🗑️  Removed #{stale_cassettes.size} stale cassettes"
       puts '🔄 Re-recording cassettes...'
       run_test_queue_rspec || exit(1)
       puts '✅ Cassettes refreshed!'
@@ -37,25 +77,12 @@ namespace :release do # rubocop:disable Metrics/BlockLength
   task :verify_cassettes do
     max_age_days = 1
     cassette_dir = 'spec/fixtures/vcr_cassettes'
-    stale_cassettes = []
-
-    Dir.glob("#{cassette_dir}/**/*.yml").each do |cassette|
-      age_days = (Time.now - File.mtime(cassette)) / 86_400
-
-      next unless age_days > max_age_days
-
-      stale_cassettes << {
-        file: File.basename(cassette),
-        age: age_days.round(1)
-      }
-    end
+    stale_cassettes = ReleaseTasks.find_stale_cassettes(cassette_dir, max_age_days)
 
     if stale_cassettes.any?
       puts "\n❌ Found stale cassettes (older than #{max_age_days} days):"
-      stale_files = []
       stale_cassettes.each do |c|
         puts "   - #{c[:file]} (#{c[:age]} days old)"
-        stale_files << File.join(cassette_dir, '**', c[:file])
       end
 
       puts "\nRun locally: bundle exec rake release:refresh_stale_cassettes"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm
 version: !ruby/object:Gem::Version
-  version: 1.15.0
+  version: 1.16.0
 platform: ruby
 authors:
 - Carmine Paolino
@@ -135,13 +135,13 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2'
-description: One beautiful Ruby API for GPT, Claude, Gemini, and more. Easily build
-  chatbots, AI agents, RAG applications, and content generators. Features chat (text,
-  images, audio, PDFs), image generation, embeddings, tools (function calling), structured
-  output, Rails integration, and streaming. Works with OpenAI, Anthropic, Google Gemini,
-  AWS Bedrock, DeepSeek, Mistral, Ollama (local models), OpenRouter, Perplexity, GPUStack,
-  and any OpenAI-compatible API. Minimal dependencies - just Faraday, Zeitwerk, and
-  Marcel.
+description: A single, beautiful Ruby framework for all major AI providers. Easily
+  build chatbots, AI agents, RAG applications, content generators, and every AI workflow
+  you can think of. Features chat (text, images, audio, PDFs), image generation, embeddings,
+  tools (function calling), structured output, Rails integration, and streaming. Works
+  with OpenAI, Anthropic, Google Gemini, AWS Bedrock, DeepSeek, Mistral, Ollama (local
+  models), OpenRouter, Perplexity, GPUStack, and any OpenAI-compatible API. Minimal
+  dependencies - just Faraday, Zeitwerk, and Marcel.
 email:
 - carmine@paolino.me
 executables: []
@@ -241,9 +241,12 @@ files:
 - lib/ruby_llm/content.rb
 - lib/ruby_llm/context.rb
 - lib/ruby_llm/cost.rb
+- lib/ruby_llm/deprecator.rb
 - lib/ruby_llm/embedding.rb
 - lib/ruby_llm/error.rb
+- lib/ruby_llm/error_middleware.rb
 - lib/ruby_llm/image.rb
+- lib/ruby_llm/instrumentation.rb
 - lib/ruby_llm/message.rb
 - lib/ruby_llm/mime_type.rb
 - lib/ruby_llm/model.rb
@@ -252,6 +255,7 @@ files:
 - lib/ruby_llm/model/pricing.rb
 - lib/ruby_llm/model/pricing_category.rb
 - lib/ruby_llm/model/pricing_tier.rb
+- lib/ruby_llm/model_registry.rb
 - lib/ruby_llm/models.json
 - lib/ruby_llm/models.rb
 - lib/ruby_llm/models_schema.json
@@ -299,6 +303,7 @@ files:
 - lib/ruby_llm/providers/mistral/capabilities.rb
 - lib/ruby_llm/providers/mistral/chat.rb
 - lib/ruby_llm/providers/mistral/embeddings.rb
+- lib/ruby_llm/providers/mistral/media.rb
 - lib/ruby_llm/providers/mistral/models.rb
 - lib/ruby_llm/providers/ollama.rb
 - lib/ruby_llm/providers/ollama/capabilities.rb
@@ -325,6 +330,7 @@ files:
 - lib/ruby_llm/providers/perplexity.rb
 - lib/ruby_llm/providers/perplexity/capabilities.rb
 - lib/ruby_llm/providers/perplexity/chat.rb
+- lib/ruby_llm/providers/perplexity/media.rb
 - lib/ruby_llm/providers/perplexity/models.rb
 - lib/ruby_llm/providers/vertexai.rb
 - lib/ruby_llm/providers/vertexai/chat.rb
@@ -342,6 +348,7 @@ files:
 - lib/ruby_llm/tokens.rb
 - lib/ruby_llm/tool.rb
 - lib/ruby_llm/tool_call.rb
+- lib/ruby_llm/tool_concurrency.rb
 - lib/ruby_llm/transcription.rb
 - lib/ruby_llm/utils.rb
 - lib/ruby_llm/version.rb
@@ -391,7 +398,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
-summary: One beautiful Ruby API for GPT, Claude, Gemini, and more.
+summary: A single, beautiful Ruby framework for all major AI providers.
 test_files: []