Introducing chat.with_instructions("instructions", replace: true)

Author: crmne

README.md

@@ -136,7 +136,7 @@ chat.ask "Tell me a story about a Ruby programmer" do |chunk|
 end
 
 # Set personality or behavior with instructions (aka system prompts)
-chat.with_instructions("You are a friendly Ruby expert who loves to help beginners")
+chat.with_instructions "You are a friendly Ruby expert who loves to help beginners"
 
 # Understand content in multiple forms
 chat.ask "Compare these diagrams", with: { image: ["diagram1.png", "diagram2.png"] }
@@ -169,10 +169,10 @@ class ToolCall < ApplicationRecord
 end
 
 # In a background job
-chat = Chat.create!(model_id: "gpt-4o-mini")
+chat = Chat.create! model_id: "gpt-4o-mini"
 
 # Set personality or behavior with instructions (aka system prompts) - they're persisted too!
-chat.with_instructions("You are a friendly Ruby expert who loves to help beginners")
+chat.with_instructions "You are a friendly Ruby expert who loves to help beginners"
 
 chat.ask("What's your favorite Ruby gem?") do |chunk|
   Turbo::StreamsChannel.broadcast_append_to(

docs/guides/rails.md

@@ -162,6 +162,37 @@ Instructions are great for:
 3. Enforcing specific response formats
 4. Creating specialized assistants
 
+### Managing Instructions
+
+You can add multiple instructions or replace existing ones:
+
+```ruby
+# Add initial instructions
+chat.with_instructions("Be a helpful Ruby expert")
+
+# Add another instruction (keeps the first one)
+chat.with_instructions("Always include code examples")
+
+# Replace all previous instructions
+chat.with_instructions("Be a concise Ruby expert who always shows examples", replace: true)
+```
+
+This is particularly useful in controllers:
+
+```ruby
+def update_instructions
+  @chat = Chat.find(params[:id])
+
+  # Replace existing instructions with new ones
+  @chat.with_instructions(params[:instructions], replace: true)
+
+  respond_to do |format|
+    format.html { redirect_to @chat }
+    format.turbo_stream
+  end
+end
+```
+
 ## Streaming Responses
 
 You can stream responses while still persisting the final result:

lib/ruby_llm/active_record/acts_as.rb

@@ -79,8 +79,18 @@ def to_llm
              .on_end_message { |msg| persist_message_completion(msg) }
       end
 
-      def with_instructions(instructions)
-        messages.create!(role: :system, content: instructions)
+      def with_instructions(instructions, replace: false)
+        transaction do
+          # If replace is true, remove existing system messages
+          messages.where(role: :system).destroy_all if replace
+
+          # Create the new system message
+          messages.create!(
+            role: :system,
+            content: instructions
+          )
+        end
+        to_llm.with_instructions(instructions)
         self
       end
 

spec/ruby_llm/active_record/acts_as_spec.rb

@@ -152,5 +152,22 @@ def execute(expression:)
       expect(chat.messages.first.role).to eq('system')
       expect(chat.messages.first.content).to eq('You are a Ruby expert')
     end
+
+    it 'optionally replaces existing system messages' do # rubocop:disable RSpec/ExampleLength,RSpec/MultipleExpectations
+      chat = Chat.create!(model_id: 'gpt-4o-mini')
+
+      # Add first instruction
+      chat.with_instructions('Be helpful')
+      expect(chat.messages.where(role: 'system').count).to eq(1)
+
+      # Add second instruction without replace
+      chat.with_instructions('Be concise')
+      expect(chat.messages.where(role: 'system').count).to eq(2)
+
+      # Replace all instructions
+      chat.with_instructions('Be awesome', replace: true)
+      expect(chat.messages.where(role: 'system').count).to eq(1)
+      expect(chat.messages.find_by(role: 'system').content).to eq('Be awesome')
+    end
   end
 end