Add additive chat callbacks

Author: crmne

docs/_core_features/agents.md

@@ -243,7 +243,8 @@ Delegated methods include:
 * `with_tool`, `with_tools`
 * `with_model`, `with_temperature`, `with_thinking`, `with_context`
 * `with_params`, `with_headers`, `with_schema`
-* `on_new_message`, `on_end_message`, `on_tool_call`, `on_tool_result`
+* `before_message`, `after_message`, `before_tool_call`, `after_tool_result` (v1.15+)
+* Deprecated replacing callbacks: `on_new_message`, `on_end_message`, `on_tool_call`, `on_tool_result`
 
 You can always access the wrapped chat object directly via `agent.chat`.
 

docs/_core_features/chat.md

@@ -653,18 +653,18 @@ You can register blocks to be called when certain events occur during the chat l
 
 ### Available Event Handlers
 
-RubyLLM provides four event handlers that cover the complete chat lifecycle:
+RubyLLM provides two callback styles. The `on_*` handlers replace any previously registered handler for the same event, which is useful when you want to override behavior. The Rails-style `before_*` and `after_*` callbacks are additive, so multiple registrations for the same event all run. Additive callbacks are available from v1.15+.
 
 ```ruby
 chat = RubyLLM.chat
 
 # Called at first chunk received from the assistant
-chat.on_new_message do
+chat.before_message do
   print "Assistant > "
 end
 
 # Called after the complete assistant message (including tool calls/results) is received
-chat.on_end_message do |message|
+chat.after_message do |message|
   puts "Response complete!"
   # Note: message might be nil if an error occurred during the request
   if message && message.output_tokens
@@ -673,19 +673,21 @@ chat.on_end_message do |message|
 end
 
 # Called when the AI decides to use a tool
-chat.on_tool_call do |tool_call|
+chat.before_tool_call do |tool_call|
   puts "AI is calling tool: #{tool_call.name} with arguments: #{tool_call.arguments}"
 end
 
 # Called after a tool returns its result
-chat.on_tool_result do |result|
+chat.after_tool_result do |result|
   puts "Tool returned: #{result}"
 end
 
 # These callbacks work for both streaming and non-streaming requests
 chat.ask "What is metaprogramming in Ruby?"
 ```
 
+The older `on_new_message`, `on_end_message`, `on_tool_call`, and `on_tool_result` handlers are still available and keep their replacing behavior. RubyLLM logs a deprecation warning when one of these handlers is used; prefer the additive Rails-style callbacks for new code.
+
 ## Raw Responses
 
 You can access the raw response from the API provider with `response.raw`.

docs/_core_features/tools.md

@@ -371,17 +371,17 @@ This entire multi-step process happens behind the scenes within a single `chat.a
 
 ## Monitoring Tool Calls with Callbacks
 
-You can monitor tool execution using event callbacks to track when tools are called and what they return:
+You can monitor tool execution using additive callbacks to track when tools are called and what they return. Available from v1.15+.
 
 ```ruby
 chat = RubyLLM.chat(model: '{{ site.models.openai_tools }}')
       .with_tool(Weather)
-      .on_tool_call do |tool_call|
+      .before_tool_call do |tool_call|
         # Called when the AI decides to use a tool
         puts "Calling tool: #{tool_call.name}"
         puts "Arguments: #{tool_call.arguments}"
       end
-      .on_tool_result do |result|
+      .after_tool_result do |result|
         # Called after the tool returns its result
         puts "Tool returned: #{result}"
       end
@@ -410,7 +410,7 @@ max_calls = 10
 
 chat = RubyLLM.chat(model: '{{ site.models.openai_tools }}')
       .with_tool(Weather)
-      .on_tool_call do |tool_call|
+      .before_tool_call do |tool_call|
         call_count += 1
         if call_count > max_calls
           raise "Tool call limit exceeded (#{max_calls} calls)"
@@ -421,7 +421,7 @@ chat = RubyLLM.chat(model: '{{ site.models.openai_tools }}')
 chat.ask("Check weather for every major city...")
 ```
 
-> Raising an exception in `on_tool_call` breaks the conversation flow - the LLM expects a tool response after requesting a tool call. This can leave the chat in an inconsistent state. Consider using better models or clearer tool descriptions to prevent loops instead of hard limits.
+> Raising an exception in `before_tool_call` breaks the conversation flow - the LLM expects a tool response after requesting a tool call. This can leave the chat in an inconsistent state. Consider using better models or clearer tool descriptions to prevent loops instead of hard limits.
 {: .warning }
 
 ## Advanced Tool Metadata

lib/ruby_llm/active_record/acts_as_legacy.rb

@@ -160,27 +160,33 @@ def with_schema(...)
         self
       end
 
-      def on_new_message(&block)
-        to_llm
+      def on_new_message(&)
+        to_llm.on_new_message(&)
+        self
+      end
 
-        existing_callback = @chat.instance_variable_get(:@on)[:new_message]
+      def on_end_message(&)
+        to_llm.on_end_message(&)
+        self
+      end
 
-        @chat.on_new_message do
-          existing_callback&.call
-          block&.call
-        end
+      def before_message(...)
+        to_llm.before_message(...)
         self
       end
 
-      def on_end_message(&block)
-        to_llm
+      def after_message(...)
+        to_llm.after_message(...)
+        self
+      end
 
-        existing_callback = @chat.instance_variable_get(:@on)[:end_message]
+      def before_tool_call(...)
+        to_llm.before_tool_call(...)
+        self
+      end
 
-        @chat.on_end_message do |msg|
-          existing_callback&.call(msg)
-          block&.call(msg)
-        end
+      def after_tool_result(...)
+        to_llm.after_tool_result(...)
         self
       end
 
@@ -319,8 +325,8 @@ def reapply_runtime_instructions(chat)
       def setup_persistence_callbacks
         return @chat if @chat.instance_variable_get(:@_persistence_callbacks_setup)
 
-        @chat.on_new_message { persist_new_message }
-        @chat.on_end_message { |msg| persist_message_completion(msg) }
+        @chat.before_message { persist_new_message }
+        @chat.after_message { |msg| persist_message_completion(msg) }
 
         @chat.instance_variable_set(:@_persistence_callbacks_setup, true)
         @chat

lib/ruby_llm/active_record/chat_methods.rb

@@ -154,27 +154,33 @@ def with_schema(...)
         self
       end
 
-      def on_new_message(&block)
-        to_llm
+      def on_new_message(&)
+        to_llm.on_new_message(&)
+        self
+      end
 
-        existing_callback = @chat.instance_variable_get(:@on)[:new_message]
+      def on_end_message(&)
+        to_llm.on_end_message(&)
+        self
+      end
 
-        @chat.on_new_message do
-          existing_callback&.call
-          block&.call
-        end
+      def before_message(...)
+        to_llm.before_message(...)
         self
       end
 
-      def on_end_message(&block)
-        to_llm
+      def after_message(...)
+        to_llm.after_message(...)
+        self
+      end
 
-        existing_callback = @chat.instance_variable_get(:@on)[:end_message]
+      def before_tool_call(...)
+        to_llm.before_tool_call(...)
+        self
+      end
 
-        @chat.on_end_message do |msg|
-          existing_callback&.call(msg)
-          block&.call(msg)
-        end
+      def after_tool_result(...)
+        to_llm.after_tool_result(...)
         self
       end
 
@@ -258,8 +264,8 @@ def cleanup_orphaned_tool_results # rubocop:disable Metrics/PerceivedComplexity
       def setup_persistence_callbacks
         return @chat if @chat.instance_variable_get(:@_persistence_callbacks_setup)
 
-        @chat.on_new_message { persist_new_message }
-        @chat.on_end_message { |msg| persist_message_completion(msg) }
+        @chat.before_message { persist_new_message }
+        @chat.after_message { |msg| persist_message_completion(msg) }
 
         @chat.instance_variable_set(:@_persistence_callbacks_setup, true)
         @chat

lib/ruby_llm/agent.rb

@@ -359,7 +359,8 @@ def initialize(chat: nil, inputs: nil, persist_instructions: true, **kwargs)
 
     def_delegators :chat, :model, :messages, :tools, :params, :headers, :schema, :ask, :say, :with_tool, :with_tools,
                    :with_model, :with_temperature, :with_thinking, :with_context, :with_params, :with_headers,
-                   :with_schema, :on_new_message, :on_end_message, :on_tool_call, :on_tool_result, :each, :complete,
-                   :add_message, :reset_messages!
+                   :with_schema, :on_new_message, :on_end_message, :on_tool_call, :on_tool_result, :before_message,
+                   :after_message, :before_tool_call, :after_tool_result, :each, :complete, :add_message,
+                   :reset_messages!
   end
 end

lib/ruby_llm/chat.rb

@@ -30,6 +30,7 @@ def initialize(model: nil, provider: nil, assume_model_exists: false, context: n
         tool_call: nil,
         tool_result: nil
       }
+      @callbacks = Hash.new { |callbacks, name| callbacks[name] = [] }
     end
 
     def ask(message = nil, with: nil, &)
@@ -112,31 +113,43 @@ def with_schema(schema)
       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 before_message(&)
+      add_callback(:before_message, &)
+    end
+
+    def after_message(&)
+      add_callback(:after_message, &)
+    end
+
+    def before_tool_call(&)
+      add_callback(:before_tool_call, &)
+    end
+
+    def after_tool_result(&)
+      add_callback(:after_tool_result, &)
     end
 
     def each(&)
       messages.each(&)
     end
 
-    def complete(&) # rubocop:disable Metrics/PerceivedComplexity
+    def complete(&)
       response = @provider.complete(
         messages,
         tools: @tools,
@@ -150,7 +163,7 @@ def complete(&) # rubocop:disable Metrics/PerceivedComplexity
         &wrap_streaming_block(&)
       )
 
-      @on[:new_message]&.call unless block_given?
+      run_callbacks(:before_message, :new_message) unless block_given?
 
       if @schema && response.content.is_a?(String) && !response.tool_call?
         begin
@@ -161,7 +174,7 @@ def complete(&) # rubocop:disable Metrics/PerceivedComplexity
       end
 
       add_message response
-      @on[:end_message]&.call(response)
+      run_callbacks(:after_message, :end_message, response)
 
       if response.tool_call?
         handle_tool_calls(response, &)
@@ -221,28 +234,52 @@ def sanitize_schema_name(name)
       sanitized.empty? ? 'response' : sanitized
     end
 
+    def add_callback(name, &block)
+      @callbacks[name] << block if block
+      self
+    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.logger.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 = nil
 
       response.tool_calls.each_value do |tool_call|
-        @on[:new_message]&.call
-        @on[:tool_call]&.call(tool_call)
+        run_callbacks(:before_message, :new_message)
+        run_callbacks(:before_tool_call, :tool_call, tool_call)
         result = execute_tool tool_call
-        @on[:tool_result]&.call(result)
+        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
-        @on[:end_message]&.call(message)
+        run_callbacks(:after_message, :end_message, message)
 
         halt_result = result if result.is_a?(Tool::Halt)
       end