fix(rails): Clean up empty assistant message on API failure in acts_as_chat

Previously, API errors during a chat turn would leave an orphaned, empty assistant message record. This caused issues, notably with Gemini rejecting subsequent requests containing empty messages.

Fixes #118

Author: crmne

docs/guides/rails.md

@@ -139,10 +139,20 @@ chat_record = Chat.create!(model_id: 'gpt-4.1-nano', user: current_user)
 # The `model_id` should typically be a valid identifier known to RubyLLM.
 # See the [Working with Models Guide]({% link guides/models.md %}) for details.
 
-# Ask a question. This automatically:
-# 1. Saves the user message ("What is the capital...")
-# 2. Makes the API call with history
-# 3. Saves the assistant message (the response)
+# Ask a question. This automatically handles persistence:
+# 1. Saves the user message ("What is the capital of France?") to the database.
+# 2. Creates an *empty* assistant message record. This allows real-time UI
+#    updates (e.g., using Turbo Streams with `after_create_commit` on the
+#    Message model) by providing a target DOM ID *before* the API call.
+# 3. Makes the API call to the provider with the conversation history.
+# 4. **On Success:** Updates the previously created assistant message record
+#    with the actual content, token counts, and any tool call information.
+# 5. **On Failure:** If the API call raises an error (e.g., network issue,
+#    invalid key, provider error), the empty assistant message record created
+#    in step 2 is **automatically destroyed**. This prevents orphaned empty
+#    messages in your database.
+# 6. Returns the final `RubyLLM::Message` object on success, or raises the
+#    `RubyLLM::Error` on failure.
 response = chat_record.ask "What is the capital of France?"
 
 # `response` is the RubyLLM::Message object from the API call.

lib/ruby_llm/active_record/acts_as.rb

@@ -20,8 +20,7 @@ def acts_as_chat(message_class: 'Message', tool_call_class: 'ToolCall')
                    class_name: @message_class,
                    dependent: :destroy
 
-          delegate :complete,
-                   :add_message,
+          delegate :add_message,
                    to: :to_llm
         end
 
@@ -94,40 +93,50 @@ def with_instructions(instructions, replace: false)
         self
       end
 
-      def with_tool(tool)
-        to_llm.with_tool(tool)
+      def with_tool(...)
+        to_llm.with_tool(...)
         self
       end
 
-      def with_tools(*tools)
-        to_llm.with_tools(*tools)
+      def with_tools(...)
+        to_llm.with_tools(...)
         self
       end
 
-      def with_model(model_id, provider: nil)
-        to_llm.with_model(model_id, provider: provider)
+      def with_model(...)
+        to_llm.with_model(...)
         self
       end
 
-      def with_temperature(temperature)
-        to_llm.with_temperature(temperature)
+      def with_temperature(...)
+        to_llm.with_temperature(...)
         self
       end
 
-      def on_new_message(&)
-        to_llm.on_new_message(&)
+      def on_new_message(...)
+        to_llm.on_new_message(...)
         self
       end
 
-      def on_end_message(&)
-        to_llm.on_end_message(&)
+      def on_end_message(...)
+        to_llm.on_end_message(...)
         self
       end
 
       def ask(message, &)
         message = { role: :user, content: message }
         messages.create!(**message)
-        to_llm.complete(&)
+        complete(&)
+      end
+
+      def complete(...)
+        to_llm.complete(...)
+      rescue RubyLLM::Error => e
+        if @message&.persisted? && @message.content.blank?
+          RubyLLM.logger.debug "RubyLLM: API call failed, destroying message: #{@message.id}"
+          @message.destroy
+        end
+        raise e
       end
 
       alias say ask

lib/ruby_llm/chat.rb

@@ -31,9 +31,9 @@ def initialize(model: nil, provider: nil, assume_model_exists: false, context: n
       }
     end
 
-    def ask(message = nil, with: {}, &block)
+    def ask(message = nil, with: {}, &)
       add_message role: :user, content: Content.new(message, with)
-      complete(&block)
+      complete(&)
     end
 
     alias say ask

lib/ruby_llm/providers/openai/chat.rb

@@ -5,12 +5,12 @@ module Providers
     module OpenAI
       # Chat methods of the OpenAI API integration
       module Chat
-        module_function
-
         def completion_url
           'chat/completions'
         end
 
+        module_function
+
         def render_payload(messages, tools:, temperature:, model:, stream: false) # rubocop:disable Metrics/MethodLength
           {
             model: model,

spec/ruby_llm/active_record/acts_as_spec.rb

@@ -170,4 +170,31 @@ def execute(expression:)
       expect(chat.messages.find_by(role: 'system').content).to eq('Be awesome')
     end
   end
+
+  describe 'acts_as_chat error handling' do
+    let!(:chat_record) { Chat.create!(model_id: 'gpt-4.1-nano') }
+    let(:provider_instance) { RubyLLM::Provider.for(chat_record.model_id) }
+    let(:api_base) { provider_instance.api_base(RubyLLM.config) }
+    let(:completion_url_regex) { %r{#{api_base}/#{provider_instance.completion_url}} }
+
+    before do
+      stub_request(:post, completion_url_regex)
+        .to_return(
+          status: 500,
+          body: { error: { message: 'API go boom' } }.to_json,
+          headers: { 'Content-Type' => 'application/json' }
+        )
+    end
+
+    it 'destroys the empty assistant message record on API failure' do # rubocop:disable RSpec/ExampleLength,RSpec/MultipleExpectations
+      expect do
+        chat_record.ask('This one will fail')
+      end.to raise_error(RubyLLM::ServerError, /API go boom/)
+      expect(Message.where(chat_id: chat_record.id).count).to eq(1)
+      remaining_message = Message.find_by(chat_id: chat_record.id)
+      expect(remaining_message.role).to eq('user')
+      expect(remaining_message.content).to eq('This one will fail')
+      expect(Message.where(chat_id: chat_record.id, role: 'assistant').count).to eq(0)
+    end
+  end
 end