ruby_llm 1.14.1 → 1.16.0

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
@@ -30,6 +33,7 @@ module RubyLLM
         tool_call: nil,
         tool_result: nil
       }
+      @callbacks = Hash.new { |callbacks, name| callbacks[name] = [] }
     end
 
     def ask(message = nil, with: nil, &)
@@ -51,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
 
@@ -112,62 +118,48 @@ module RubyLLM
       self
     end
 
-    def on_new_message(&block)
-      @on[:new_message] = block
-      self
+    def on_new_message(&)
+      set_legacy_callback(:new_message, :on_new_message, :before_message, &)
     end
 
-    def on_end_message(&block)
-      @on[:end_message] = block
-      self
+    def on_end_message(&)
+      set_legacy_callback(:end_message, :on_end_message, :after_message, &)
     end
 
-    def on_tool_call(&block)
-      @on[:tool_call] = block
-      self
+    def on_tool_call(&)
+      set_legacy_callback(:tool_call, :on_tool_call, :before_tool_call, &)
     end
 
-    def on_tool_result(&block)
-      @on[:tool_result] = block
-      self
+    def on_tool_result(&)
+      set_legacy_callback(:tool_result, :on_tool_result, :after_tool_result, &)
     end
 
-    def each(&)
-      messages.each(&)
+    def before_message(&)
+      add_callback(:before_message, &)
     end
 
-    def complete(&) # rubocop:disable Metrics/PerceivedComplexity
-      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(&)
-      )
+    def after_message(&)
+      add_callback(:after_message, &)
+    end
 
-      @on[:new_message]&.call unless block_given?
+    def before_tool_call(&)
+      add_callback(:before_tool_call, &)
+    end
 
-      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
+    def after_tool_result(&)
+      add_callback(:after_tool_result, &)
+    end
 
-      add_message response
-      @on[:end_message]&.call(response)
+    def each(&)
+      messages.each(&)
+    end
 
-      if response.tool_call?
-        handle_tool_calls(response, &)
-      else
-        response
-      end
+    def cost
+      Cost.aggregate(messages.map { |message| message.cost(model: message.model_info || model) })
+    end
+
+    def complete(&)
+      instrument_completion(&)
     end
 
     def add_message(message_or_attributes)
@@ -176,6 +168,7 @@ module RubyLLM
       message
     end
 
+    # Mutates this chat by removing all in-memory messages.
     def reset_messages!
       @messages.clear
     end
@@ -221,34 +214,176 @@ module RubyLLM
       sanitized.empty? ? 'response' : sanitized
     end
 
+    def add_callback(name, &block)
+      @callbacks[name] << block if block
+      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
+
+      @on[name] = block
+      self
+    end
+
+    def warn_legacy_callback_deprecation(legacy_name, additive_name)
+      RubyLLM.deprecator.warn(
+        "`#{legacy_name}` is deprecated and will be removed in RubyLLM 2.0. " \
+        "Use `#{additive_name}` instead."
+      )
+    end
+
+    def run_callbacks(name, legacy_name, *args)
+      @callbacks[name].each { |callback| callback.call(*args) }
+      @on[legacy_name]&.call(*args)
+    end
+
     def wrap_streaming_block(&block)
       return nil unless block_given?
 
-      @on[:new_message]&.call
+      run_callbacks(:before_message, :new_message)
 
       proc do |chunk|
         block.call chunk
       end
     end
 
-    def handle_tool_calls(response, &) # rubocop:disable Metrics/PerceivedComplexity
+    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|
-        @on[:new_message]&.call
-        @on[:tool_call]&.call(tool_call)
-        result = execute_tool tool_call
-        @on[:tool_result]&.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
-        @on[:end_message]&.call(message)
+      tool_calls.each_value do |tool_call|
+        run_callbacks(:before_message, :new_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)
@@ -261,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:)
@@ -279,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)