ruby_llm 1.15.0 → 1.16.0

data/lib/ruby_llm/attachment.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'base64'
 require 'pathname'
 require 'uri'
 
@@ -8,6 +9,16 @@ module RubyLLM
   class Attachment
     attr_reader :source, :filename, :mime_type
 
+    DOCUMENT_EXTENSIONS = %w[
+      doc docx dot key numbers odp ods odt pages pot pps ppt pptx rtf xls xlsx
+    ].freeze
+    ACTIVE_STORAGE_CLASS_NAMES = %w[
+      ActiveStorage::Blob
+      ActiveStorage::Attachment
+      ActiveStorage::Attached::One
+      ActiveStorage::Attached::Many
+    ].freeze
+
     def initialize(source, filename: nil)
       @source = source
       @source = source_type_cast
@@ -29,12 +40,7 @@ module RubyLLM
     end
 
     def active_storage?
-      return false unless defined?(ActiveStorage)
-
-      @source.is_a?(ActiveStorage::Blob) ||
-        @source.is_a?(ActiveStorage::Attachment) ||
-        @source.is_a?(ActiveStorage::Attached::One) ||
-        @source.is_a?(ActiveStorage::Attached::Many)
+      ACTIVE_STORAGE_CLASS_NAMES.any? { |class_name| source_is_a?(class_name) }
     end
 
     def content
@@ -83,6 +89,7 @@ module RubyLLM
       return :audio if audio?
       return :pdf if pdf?
       return :text if text?
+      return :document if document?
 
       :unknown
     end
@@ -114,6 +121,17 @@ module RubyLLM
       RubyLLM::MimeType.pdf? mime_type
     end
 
+    def document?
+      return false if pdf? || text?
+
+      RubyLLM::MimeType.document?(mime_type) || DOCUMENT_EXTENSIONS.include?(extension)
+    end
+
+    def extension
+      extension = File.extname(filename.to_s).delete_prefix('.').downcase
+      extension.empty? ? nil : extension
+    end
+
     def text?
       RubyLLM::MimeType.text? mime_type
     end
@@ -147,8 +165,6 @@ module RubyLLM
     end
 
     def load_content_from_active_storage
-      return unless defined?(ActiveStorage)
-
       @content = active_storage_blob&.download
     end
 
@@ -185,23 +201,24 @@ module RubyLLM
     end
 
     def extract_filename_from_active_storage
-      return 'attachment' unless defined?(ActiveStorage)
-
       active_storage_blob&.filename&.to_s || 'attachment'
     end
 
     def active_storage_content_type
-      return unless defined?(ActiveStorage)
-
       active_storage_blob&.content_type
     end
 
     def active_storage_blob
-      case @source
-      when ActiveStorage::Blob then @source
-      when ActiveStorage::Attachment, ActiveStorage::Attached::One then @source.blob
-      when ActiveStorage::Attached::Many then @source.blobs.first
-      end
+      return @source if source_is_a?('ActiveStorage::Blob')
+      return @source.blob if source_is_a?('ActiveStorage::Attachment')
+      return @source.blob if source_is_a?('ActiveStorage::Attached::One')
+
+      @source.blobs.first if source_is_a?('ActiveStorage::Attached::Many')
+    end
+
+    def source_is_a?(class_name)
+      klass = RubyLLM::Utils.safe_constantize(class_name)
+      klass ? @source.is_a?(klass) : false
     end
   end
 end

data/lib/ruby_llm/chat.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module RubyLLM
   # Represents a conversation with an AI model
   class Chat
     include Enumerable
 
-    attr_reader :model, :messages, :tools, :tool_prefs, :params, :headers, :schema
+    attr_reader :model, :messages, :tools, :tool_prefs, :params, :headers, :schema, :concurrency
 
     def initialize(model: nil, provider: nil, assume_model_exists: false, context: nil)
       if assume_model_exists && !provider
@@ -20,6 +22,7 @@ module RubyLLM
       @messages = []
       @tools = {}
       @tool_prefs = { choice: nil, calls: nil }
+      @concurrency = normalize_tool_concurrency(@config.tool_concurrency)
       @params = {}
       @headers = {}
       @schema = nil
@@ -52,19 +55,21 @@ module RubyLLM
       self
     end
 
-    def with_tool(tool, choice: nil, calls: nil)
+    def with_tool(tool, choice: nil, calls: nil, concurrency: @concurrency)
       unless tool.nil?
         tool_instance = tool.is_a?(Class) ? tool.new : tool
         @tools[tool_instance.name.to_sym] = tool_instance
       end
       update_tool_options(choice:, calls:)
+      update_tool_concurrency(concurrency)
       self
     end
 
-    def with_tools(*tools, replace: false, choice: nil, calls: nil)
+    def with_tools(*tools, replace: false, choice: nil, calls: nil, concurrency: @concurrency)
       @tools.clear if replace
       tools.compact.each { |tool| with_tool tool }
       update_tool_options(choice:, calls:)
+      update_tool_concurrency(concurrency)
       self
     end
 
@@ -150,41 +155,11 @@ module RubyLLM
     end
 
     def cost
-      Cost.aggregate(messages.map(&:cost))
+      Cost.aggregate(messages.map { |message| message.cost(model: message.model_info || model) })
     end
 
     def complete(&)
-      response = @provider.complete(
-        messages,
-        tools: @tools,
-        tool_prefs: @tool_prefs,
-        temperature: @temperature,
-        model: @model,
-        params: @params,
-        headers: @headers,
-        schema: @schema,
-        thinking: @thinking,
-        &wrap_streaming_block(&)
-      )
-
-      run_callbacks(:before_message, :new_message) unless block_given?
-
-      if @schema && response.content.is_a?(String) && !response.tool_call?
-        begin
-          response.content = JSON.parse(response.content)
-        rescue JSON::ParserError
-          # If parsing fails, keep content as string
-        end
-      end
-
-      add_message response
-      run_callbacks(:after_message, :end_message, response)
-
-      if response.tool_call?
-        handle_tool_calls(response, &)
-      else
-        response
-      end
+      instrument_completion(&)
     end
 
     def add_message(message_or_attributes)
@@ -193,6 +168,7 @@ module RubyLLM
       message
     end
 
+    # Mutates this chat by removing all in-memory messages.
     def reset_messages!
       @messages.clear
     end
@@ -243,6 +219,87 @@ module RubyLLM
       self
     end
 
+    def complete_once(&)
+      response = provider_completion(&)
+
+      run_callbacks(:before_message, :new_message) unless block_given?
+
+      normalize_schema_response(response)
+
+      add_message response
+      run_callbacks(:after_message, :end_message, response)
+
+      if response.tool_call?
+        handle_tool_calls(response, &)
+      else
+        response
+      end
+    end
+
+    def instrument_completion(&block)
+      result = nil
+      streaming = block_given?
+      payload = {
+        chat: self,
+        provider: @provider.slug,
+        provider_class: @provider.class.name,
+        model: @model.id,
+        model_info: @model,
+        input_messages: messages.dup,
+        message_count: messages.size,
+        tools: tools.keys,
+        tool_choice: tool_prefs[:choice],
+        tool_call_limit: tool_prefs[:calls],
+        temperature: @temperature,
+        params: params,
+        schema: schema,
+        thinking: @thinking,
+        streaming: streaming
+      }
+
+      RubyLLM.instrument('chat.ruby_llm', payload, config: @config) do |event|
+        result = complete_once(&block)
+        event[:response] = result
+        event[:messages_after] = messages.dup
+        event[:response_role] = result.role if result.respond_to?(:role)
+
+        if result.respond_to?(:tool_call?)
+          event[:response_model] = result.model_id
+          event[:tool_call] = result.tool_call?
+          event[:tool_calls] = result.tool_calls
+          event[:input_tokens] = result.input_tokens
+          event[:output_tokens] = result.output_tokens
+          event[:cached_tokens] = result.cached_tokens
+          event[:cache_creation_tokens] = result.cache_creation_tokens
+          event[:thinking_tokens] = result.thinking_tokens
+        end
+      end
+      result
+    end
+
+    def provider_completion(&)
+      @provider.complete(
+        messages,
+        tools: @tools,
+        tool_prefs: @tool_prefs,
+        temperature: @temperature,
+        model: @model,
+        params: @params,
+        headers: @headers,
+        schema: @schema,
+        thinking: @thinking,
+        &wrap_streaming_block(&)
+      )
+    end
+
+    def normalize_schema_response(response)
+      return unless @schema && response.content.is_a?(String) && !response.tool_call?
+
+      response.content = JSON.parse(response.content)
+    rescue JSON::ParserError
+      # If parsing fails, keep content as string.
+    end
+
     def set_legacy_callback(name, legacy_name, additive_name, &block)
       warn_legacy_callback_deprecation(legacy_name, additive_name) if block
 
@@ -251,7 +308,7 @@ module RubyLLM
     end
 
     def warn_legacy_callback_deprecation(legacy_name, additive_name)
-      RubyLLM.logger.warn(
+      RubyLLM.deprecator.warn(
         "`#{legacy_name}` is deprecated and will be removed in RubyLLM 2.0. " \
         "Use `#{additive_name}` instead."
       )
@@ -273,23 +330,60 @@ module RubyLLM
     end
 
     def handle_tool_calls(response, &)
+      halt_result = if concurrency
+                      handle_concurrent_tool_calls(response.tool_calls)
+                    else
+                      handle_sequential_tool_calls(response.tool_calls)
+                    end
+
+      reset_tool_choice if forced_tool_choice?
+      halt_result || complete(&)
+    end
+
+    def handle_sequential_tool_calls(tool_calls)
       halt_result = nil
 
-      response.tool_calls.each_value do |tool_call|
+      tool_calls.each_value do |tool_call|
         run_callbacks(:before_message, :new_message)
-        run_callbacks(:before_tool_call, :tool_call, tool_call)
-        result = execute_tool tool_call
-        run_callbacks(:after_tool_result, :tool_result, result)
-        tool_payload = result.is_a?(Tool::Halt) ? result.content : result
-        content = content_like?(tool_payload) ? tool_payload : tool_payload.to_s
-        message = add_message role: :tool, content:, tool_call_id: tool_call.id
-        run_callbacks(:after_message, :end_message, message)
+        result = execute_tool_with_callbacks(tool_call)
+        add_tool_result_message(tool_call, result)
+        halt_result = result if result.is_a?(Tool::Halt)
+      end
 
+      halt_result
+    end
+
+    def handle_concurrent_tool_calls(tool_calls)
+      halt_result = nil
+
+      execute_tools_concurrently(tool_calls) do |tool_call, result|
+        run_callbacks(:before_message, :new_message)
+        add_tool_result_message(tool_call, result)
         halt_result = result if result.is_a?(Tool::Halt)
       end
 
-      reset_tool_choice if forced_tool_choice?
-      halt_result || complete(&)
+      halt_result
+    end
+
+    def execute_tools_concurrently(tool_calls, &on_result)
+      ToolConcurrency.run(concurrency, tool_calls, on_result:) do |tool_call|
+        execute_tool_with_callbacks(tool_call)
+      end
+    end
+
+    def execute_tool_with_callbacks(tool_call)
+      run_callbacks(:before_tool_call, :tool_call, tool_call)
+      result = execute_tool tool_call
+      run_callbacks(:after_tool_result, :tool_result, result)
+      result
+    end
+
+    def add_tool_result_message(tool_call, result)
+      tool_payload = result.is_a?(Tool::Halt) ? result.content : result
+      content = content_like?(tool_payload) ? tool_payload : tool_payload.to_s
+      message = add_message role: :tool, content:, tool_call_id: tool_call.id
+      run_callbacks(:after_message, :end_message, message)
+      message
     end
 
     def execute_tool(tool_call)
@@ -302,7 +396,26 @@ module RubyLLM
       end
 
       args = tool_call.arguments
-      tool.call(args)
+      payload = {
+        chat: self,
+        provider: @provider.slug,
+        provider_class: @provider.class.name,
+        model: @model.id,
+        model_info: @model,
+        tool: tool,
+        tool_call: tool_call,
+        tool_name: tool.name,
+        tool_arguments: args,
+        tool_call_id: tool_call.id
+      }
+
+      RubyLLM.instrument('tool_call.ruby_llm', payload, config: @config) do |event|
+        result = tool.call(args)
+        event[:result] = result
+        event[:result_content] = result.is_a?(Tool::Halt) ? result.content : result
+        event[:result_class] = result.class.name
+        result
+      end
     end
 
     def update_tool_options(choice:, calls:)
@@ -320,6 +433,22 @@ module RubyLLM
       @tool_prefs[:calls] = normalize_calls(calls) unless calls.nil?
     end
 
+    def update_tool_concurrency(concurrency)
+      @concurrency = normalize_tool_concurrency(concurrency)
+    end
+
+    def normalize_tool_concurrency(concurrency)
+      return nil if concurrency.nil? || concurrency == false
+      return :threads if concurrency == true
+
+      normalized = concurrency.to_sym
+      return normalized if ToolConcurrency.supported?(normalized)
+
+      raise ArgumentError,
+            "Unknown tool concurrency: #{concurrency.inspect}. " \
+            "Available modes: #{ToolConcurrency.modes.join(', ')}"
+    end
+
     def normalize_calls(calls)
       case calls
       when :many, 'many'

data/lib/ruby_llm/configuration.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'logger'
+
 module RubyLLM
   # Global configuration for RubyLLM
   class Configuration
@@ -9,7 +11,13 @@ module RubyLLM
         key = key.to_sym
         return if options.include?(key)
 
-        send(:attr_accessor, key)
+        attr_reader key
+
+        define_method("#{key}=") do |value|
+          value = nil if value.is_a?(String) && value.strip.empty?
+          instance_variable_set(:"@#{key}", value)
+        end
+
         option_keys << key
         defaults[key] = default
       end
@@ -42,6 +50,7 @@ module RubyLLM
     option :model_registry_class, 'Model'
 
     option :use_new_acts_as, false
+    option :model_registry_source, nil
 
     option :request_timeout, 300
     option :max_retries, 3
@@ -49,8 +58,12 @@ module RubyLLM
     option :retry_backoff_factor, 2
     option :retry_interval_randomness, 0.5
     option :http_proxy, nil
+    option :tool_concurrency, false
 
     option :logger, nil
+    option :instrumenter, nil
+    option :deprecation_behavior, :warn
+    option :faraday_adapter, :net_http
     option :log_file, -> { $stdout }
     option :log_level, -> { ENV['RUBYLLM_DEBUG'] ? Logger::DEBUG : Logger::INFO }
     option :log_stream_debug, -> { ENV['RUBYLLM_STREAM_DEBUG'] == 'true' }

data/lib/ruby_llm/connection.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
+require 'faraday'
+require 'faraday/multipart'
+require 'faraday/retry'
+require 'ruby_llm/error_middleware'
+require 'timeout'
+
 module RubyLLM
   # Connection class for managing API connections to various providers.
   class Connection
@@ -33,16 +39,20 @@ module RubyLLM
     end
 
     def post(url, payload, &)
-      @connection.post url, payload do |req|
-        req.headers.merge! @provider.headers if @provider.respond_to?(:headers)
-        yield req if block_given?
+      instrument_request(:post, url) do
+        @connection.post url, payload do |req|
+          req.headers.merge! provider_headers
+          yield req if block_given?
+        end
       end
     end
 
     def get(url, &)
-      @connection.get url do |req|
-        req.headers.merge! @provider.headers if @provider.respond_to?(:headers)
-        yield req if block_given?
+      instrument_request(:get, url) do
+        @connection.get url do |req|
+          req.headers.merge! provider_headers
+          yield req if block_given?
+        end
       end
     end
 
@@ -52,6 +62,24 @@ module RubyLLM
 
     private
 
+    def provider_headers
+      @provider.respond_to?(:headers) ? @provider.headers : {}
+    end
+
+    def instrument_request(method, url)
+      payload = {
+        provider: @provider.respond_to?(:slug) ? @provider.slug : @provider.class.name,
+        method: method,
+        url: url
+      }
+
+      RubyLLM.instrument('request.ruby_llm', payload, config: @config) do
+        response = yield
+        payload[:status] = response.status if response.respond_to?(:status)
+        response
+      end
+    end
+
     def setup_timeout(faraday)
       faraday.options.timeout = @config.request_timeout
     end
@@ -89,7 +117,8 @@ module RubyLLM
       faraday.request :multipart
       faraday.request :json
       faraday.response :json
-      faraday.adapter :net_http
+      adapter = @config.respond_to?(:faraday_adapter) ? @config.faraday_adapter : :net_http
+      faraday.adapter(adapter || :net_http)
       faraday.use :llm_errors, provider: @provider
     end
 

data/lib/ruby_llm/content.rb

@@ -14,7 +14,7 @@ module RubyLLM
     end
 
     def add_attachment(source, filename: nil)
-      @attachments << Attachment.new(source, filename:)
+      @attachments << build_attachment(source, filename:)
       self
     end
 
@@ -26,6 +26,10 @@ module RubyLLM
       end
     end
 
+    def empty?
+      attachments.empty? && (@text.nil? || (@text.respond_to?(:empty?) && @text.empty?))
+    end
+
     # For Rails serialization
     def to_h
       { text: @text, attachments: @attachments.map(&:to_h) }
@@ -33,6 +37,16 @@ module RubyLLM
 
     private
 
+    def build_attachment(source, filename: nil)
+      if source.is_a?(Attachment)
+        return source unless filename
+
+        return Attachment.new(source.source, filename:)
+      end
+
+      Attachment.new(source, filename:)
+    end
+
     def process_attachments_array_or_string(attachments)
       Utils.to_safe_array(attachments).each do |file|
         next if blank_attachment_entry?(file)

data/lib/ruby_llm/deprecator.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Owns RubyLLM deprecation warnings so applications and tests can decide how
+  # aggressively to handle compatibility paths.
+  class Deprecator
+    def warn(message)
+      case RubyLLM.config.deprecation_behavior
+      when :silence
+        nil
+      when :raise
+        raise DeprecationError, message
+      else
+        RubyLLM.logger.warn(message)
+      end
+    end
+
+    def deprecate(name, replacement:, removal:)
+      warn("#{name} is deprecated and will be removed in RubyLLM #{removal}. Use #{replacement} instead.")
+    end
+  end
+
+  class DeprecationError < StandardError; end
+end

data/lib/ruby_llm/embedding.rb

@@ -23,7 +23,37 @@ module RubyLLM
                                                        config: config)
       model_id = model.id
 
-      provider_instance.embed(text, model: model_id, dimensions:)
+      payload = {
+        provider: provider_instance.slug,
+        provider_class: provider_instance.class.name,
+        model: model_id,
+        model_info: model,
+        input: text,
+        dimensions: dimensions
+      }
+
+      RubyLLM.instrument('embedding.ruby_llm', payload, config: config) do |event|
+        result = provider_instance.embed(text, model: model_id, dimensions:)
+        event[:result] = result
+        event[:response_model] = result.model
+        event[:input_tokens] = result.input_tokens
+        event[:embedding_dimensions] = vector_dimensions(result.vectors)
+        event[:embedding_count] = embedding_count(result.vectors)
+        result
+      end
+    end
+
+    def self.vector_dimensions(vectors)
+      return unless vectors.is_a?(Array)
+
+      vector = vectors.first.is_a?(Array) ? vectors.first : vectors
+      vector.length if vector.respond_to?(:length)
+    end
+
+    def self.embedding_count(vectors)
+      return unless vectors.is_a?(Array)
+
+      vectors.first.is_a?(Array) ? vectors.size : 1
     end
   end
 end