ruby_llm 1.14.1 → 1.16.0

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Perplexity
+      # Handles Perplexity Sonar media content.
+      module Media
+        module_function
+
+        SUPPORTED_DOCUMENT_EXTENSIONS = %w[pdf doc docx txt rtf].freeze
+
+        def format_content(content) # rubocop:disable Metrics/PerceivedComplexity
+          if content.is_a?(RubyLLM::Content::Raw)
+            value = content.value
+            return value.is_a?(Hash) ? value.to_json : value
+          end
+          return content.to_json if content.is_a?(Hash) || content.is_a?(Array)
+          return content unless content.is_a?(Content)
+
+          parts = []
+          parts << OpenAI::Media.format_text(content.text) if content.text
+
+          content.attachments.each do |attachment|
+            case attachment.type
+            when :image
+              parts << OpenAI::Media.format_image(attachment)
+            when :pdf, :document
+              parts << format_document(attachment)
+            when :text
+              parts << format_text_attachment(attachment)
+            else
+              raise UnsupportedAttachmentError, attachment.mime_type
+            end
+          end
+
+          parts
+        end
+
+        def format_document(attachment)
+          raise UnsupportedAttachmentError, attachment.mime_type unless supported_file?(attachment)
+
+          {
+            type: 'file_url',
+            file_url: {
+              url: attachment.url? ? attachment.source.to_s : attachment.encoded
+            }
+          }
+        end
+
+        def format_text_attachment(attachment)
+          OpenAI::Media.format_text_file(attachment)
+        end
+
+        def supported_file?(attachment)
+          return true if attachment.pdf?
+
+          SUPPORTED_DOCUMENT_EXTENSIONS.include?(attachment.extension)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/perplexity.rb

@@ -8,7 +8,7 @@ module RubyLLM
       include Perplexity::Models
 
       def api_base
-        'https://api.perplexity.ai'
+        @config.perplexity_api_base || 'https://api.perplexity.ai'
       end
 
       def headers
@@ -24,7 +24,7 @@ module RubyLLM
         end
 
         def configuration_options
-          %i[perplexity_api_key]
+          %i[perplexity_api_key perplexity_api_base]
         end
 
         def configuration_requirements

data/lib/ruby_llm/providers/vertexai.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'stringio'
+
 module RubyLLM
   module Providers
     # Google Vertex AI implementation
@@ -21,6 +23,8 @@ module RubyLLM
       end
 
       def api_base
+        return @config.vertexai_api_base if @config.vertexai_api_base
+
         if @config.vertexai_location.to_s == 'global'
           'https://aiplatform.googleapis.com/v1beta1'
         else
@@ -41,7 +45,7 @@ module RubyLLM
 
       class << self
         def configuration_options
-          %i[vertexai_project_id vertexai_location vertexai_service_account_key]
+          %i[vertexai_project_id vertexai_location vertexai_service_account_key vertexai_api_base]
         end
 
         def configuration_requirements

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

@@ -9,6 +9,15 @@ module RubyLLM
         def format_role(role)
           role.to_s
         end
+
+        def format_content(content)
+          OpenAI::Media.format_content(
+            content,
+            document_attachments: :none,
+            image_attachments: true,
+            audio_attachments: false
+          )
+        end
       end
     end
   end

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

@@ -7,23 +7,6 @@ module RubyLLM
       module Models
         module_function
 
-        IMAGE_MODELS = %w[grok-2-image-1212].freeze
-        VISION_MODELS = %w[
-          grok-2-vision-1212
-          grok-4-0709
-          grok-4-fast-non-reasoning
-          grok-4-fast-reasoning
-          grok-4-1-fast-non-reasoning
-          grok-4-1-fast-reasoning
-        ].freeze
-        REASONING_MODELS = %w[
-          grok-3-mini
-          grok-4-0709
-          grok-4-fast-reasoning
-          grok-4-1-fast-reasoning
-          grok-code-fast-1
-        ].freeze
-
         def parse_list_models_response(response, slug, _capabilities)
           Array(response.body['data']).map do |model_data|
             model_id = model_data['id']
@@ -48,27 +31,32 @@ module RubyLLM
         end
 
         def modalities_for(model_id)
-          if IMAGE_MODELS.include?(model_id)
-            { input: ['text'], output: ['image'] }
+          if image_model?(model_id)
+            { input: %w[text image], output: ['image'] }
+          elsif video_model?(model_id)
+            { input: %w[text image video], output: ['video'] }
           else
-            input = ['text']
-            input << 'image' if VISION_MODELS.include?(model_id)
-            { input: input, output: ['text'] }
+            { input: ['text'], output: ['text'] }
           end
         end
 
         def capabilities_for(model_id)
-          return [] if IMAGE_MODELS.include?(model_id)
+          return ['vision'] if image_model?(model_id) || video_model?(model_id)
 
-          capabilities = %w[streaming function_calling structured_output]
-          capabilities << 'reasoning' if REASONING_MODELS.include?(model_id)
-          capabilities << 'vision' if VISION_MODELS.include?(model_id)
-          capabilities
+          ['streaming']
         end
 
         def format_display_name(model_id)
           model_id.tr('-', ' ').split.map(&:capitalize).join(' ')
         end
+
+        def image_model?(model_id)
+          model_id.match?(/\Agrok-(?:2-)?imagine-image/) || model_id == 'grok-2-image-1212'
+        end
+
+        def video_model?(model_id)
+          model_id.match?(/\Agrok-(?:2-)?imagine-video/)
+        end
       end
     end
   end

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,8 +10,18 @@ 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'
+          require 'ruby_llm/active_record/chat_methods'
+          require 'ruby_llm/active_record/message_methods'
+          require 'ruby_llm/active_record/model_methods'
+          require 'ruby_llm/active_record/tool_call_methods'
+
           if RubyLLM.config.use_new_acts_as
             require 'ruby_llm/active_record/acts_as'
             ::ActiveRecord::Base.include RubyLLM::ActiveRecord::ActsAs
@@ -19,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/tokens.rb

@@ -43,5 +43,13 @@ module RubyLLM
     def reasoning
       thinking
     end
+
+    def cache_read
+      cached
+    end
+
+    def cache_write
+      cache_creation
+    end
   end
 end

data/lib/ruby_llm/tool.rb

@@ -7,10 +7,10 @@ module RubyLLM
   class Parameter
     attr_reader :name, :type, :description, :required
 
-    def initialize(name, type: 'string', desc: nil, required: true)
+    def initialize(name, type: 'string', desc: nil, description: nil, required: true)
       @name = name
       @type = type
-      @description = desc
+      @description = desc || description
       @required = required
     end
   end
@@ -30,6 +30,8 @@ module RubyLLM
       end
     end
 
+    POSITIONAL_PARAMETER_KINDS = %i[req opt rest].freeze
+
     class << self
       attr_reader :params_schema_definition
 
@@ -38,6 +40,7 @@ module RubyLLM
 
         @description = text
       end
+      alias desc description
 
       def param(name, **options)
         parameters[name] = Parameter.new(name, **options)
@@ -94,6 +97,8 @@ module RubyLLM
           definition.json_schema
         elsif parameters.any?
           SchemaDefinition.from_parameters(parameters)&.json_schema
+        else
+          SchemaDefinition.from_parameters(inferred_parameters, allow_empty: true)&.json_schema
         end
       end
     end
@@ -127,9 +132,10 @@ module RubyLLM
     end
 
     def validate_keyword_arguments(arguments)
-      required_keywords, optional_keywords, accepts_extra_keywords = execute_keyword_signature
+      required_keywords, optional_keywords, accepts_extra_keywords, accepts_positional_arguments =
+        execute_keyword_signature
 
-      return nil if required_keywords.empty? && optional_keywords.empty?
+      return nil if required_keywords.empty? && optional_keywords.empty? && accepts_positional_arguments
 
       argument_keys = arguments.keys
       missing_keyword = first_missing_keyword(required_keywords, argument_keys)
@@ -148,8 +154,11 @@ module RubyLLM
       required_keywords = keyword_signature.filter_map { |kind, name| name if kind == :keyreq }
       optional_keywords = keyword_signature.filter_map { |kind, name| name if kind == :key }
       accepts_extra_keywords = keyword_signature.any? { |kind, _| kind == :keyrest }
+      accepts_positional_arguments = keyword_signature.any? do |kind, _|
+        POSITIONAL_PARAMETER_KINDS.include?(kind)
+      end
 
-      [required_keywords, optional_keywords, accepts_extra_keywords]
+      [required_keywords, optional_keywords, accepts_extra_keywords, accepts_positional_arguments]
     end
 
     def first_missing_keyword(required_keywords, argument_keys)
@@ -160,11 +169,19 @@ module RubyLLM
       (argument_keys - allowed_keywords).first
     end
 
+    def inferred_parameters
+      required_keywords, optional_keywords, = execute_keyword_signature
+
+      (required_keywords + optional_keywords).to_h do |name|
+        [name, Parameter.new(name, required: required_keywords.include?(name))]
+      end
+    end
+
     # Wraps schema handling for tool parameters, supporting JSON Schema hashes,
     # RubyLLM::Schema instances/classes, and DSL blocks.
     class SchemaDefinition
-      def self.from_parameters(parameters)
-        return nil if parameters.nil? || parameters.empty?
+      def self.from_parameters(parameters, allow_empty: false)
+        return nil if parameters.nil? || (parameters.empty? && !allow_empty)
 
         properties = parameters.to_h do |name, param|
           schema = {

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.14.1'
+  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(
@@ -33,14 +34,21 @@ loader.inflector.inflect(
 )
 loader.ignore("#{__dir__}/tasks")
 loader.ignore("#{__dir__}/generators")
+loader.ignore("#{__dir__}/ruby_llm/active_record")
 loader.ignore("#{__dir__}/ruby_llm/railtie.rb")
 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?
@@ -107,7 +115,4 @@ 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'
-  require 'ruby_llm/active_record/acts_as'
-end
+require 'ruby_llm/railtie' if defined?(Rails::Railtie)