Skip to content

A platform for community discussion. Free, open, simple.

FEATURE: Allow AI agents to add notes to reviewables (#40807)

Rafael dos Santos Silvab5ba10eb5f35
diff --git a/plugins/discourse-ai/config/locales/server.en.yml b/plugins/discourse-ai/config/locales/server.en.yml
index 150e93bfecd..4b46ab3b162 100644
--- a/plugins/discourse-ai/config/locales/server.en.yml
+++ b/plugins/discourse-ai/config/locales/server.en.yml
@@ -594,6 +594,7 @@ en:
grant_badge: "Grant badge"
list_reviewables: "List review queue"
perform_reviewable_action: "Review queue action"
+ add_reviewable_note: "Add review queue note"
assign: "Assign topic"
mark_as_solved: "Mark as solved"
search: "Search"
@@ -639,6 +640,7 @@ en:
grant_badge: "Grant a badge to a user"
list_reviewables: "List pending review queue items with optional filtering"
perform_reviewable_action: "Perform an action on a review queue item"
+ add_reviewable_note: "Add a note to a review queue item"
assign: "Assign or unassign a topic to a user or group"
mark_as_solved: "Mark or unmark a post as the accepted solution"
search: "Search all public topics on the forum"
@@ -684,6 +686,7 @@ en:
grant_badge: "Granting badge '%{badge_name}' to %{username}"
list_reviewables: "Listing review queue items (type: %{type})"
perform_reviewable_action: "Performing %{action} on reviewable %{reviewable_id}"
+ add_reviewable_note: "Adding note to reviewable %{reviewable_id}"
assign: "Assigning topic %{topic_id} (assigned: %{assigned})"
mark_as_solved: "Marking post %{post_id} as solved (solved: %{solved})"
read: "Reading: <a href='%{url}'>%{title}</a>"
@@ -860,6 +863,14 @@ en:
action_failed: "Failed to perform the action"
success: "Successfully performed '%{action}' on review queue item %{reviewable_id}"
+ add_reviewable_note:
+ errors:
+ not_allowed: "You are not allowed to access the review queue"
+ not_found: "Review queue item not found"
+ no_note: "A note is required to add a note to a review queue item"
+ failed: "Failed to add the note"
+ success: "Successfully added a note to review queue item %{reviewable_id}"
+
reviewables:
ai_tool_action:
title: "AI Tool Action"
diff --git a/plugins/discourse-ai/lib/agents/agent.rb b/plugins/discourse-ai/lib/agents/agent.rb
index b3b1494640c..75bb0a26f1d 100644
--- a/plugins/discourse-ai/lib/agents/agent.rb
+++ b/plugins/discourse-ai/lib/agents/agent.rb
@@ -109,6 +109,7 @@ module DiscourseAi
Tools::GrantBadge,
Tools::ListReviewables,
Tools::PerformReviewableAction,
+ Tools::AddReviewableNote,
Tools::DbSchema,
Tools::SearchSettings,
Tools::SettingContext,
diff --git a/plugins/discourse-ai/lib/agents/tools/add_reviewable_note.rb b/plugins/discourse-ai/lib/agents/tools/add_reviewable_note.rb
new file mode 100644
index 00000000000..7f43eff973e
--- /dev/null
+++ b/plugins/discourse-ai/lib/agents/tools/add_reviewable_note.rb
@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module DiscourseAi
+ module Agents
+ module Tools
+ class AddReviewableNote < Tool
+ def self.signature
+ {
+ name: name,
+ description:
+ "Adds a note to a review queue item without changing its status. Use this to record an assessment or judgment about a reviewable so human moderators can see it. Use list_reviewables first to find items and their existing notes.",
+ parameters: [
+ {
+ name: "reviewable_id",
+ description: "The ID of the reviewable item to add a note to",
+ type: "integer",
+ required: true,
+ },
+ {
+ name: "note",
+ description: "The note content to add to the reviewable item",
+ type: "string",
+ required: true,
+ },
+ ],
+ }
+ end
+
+ def self.name
+ "add_reviewable_note"
+ end
+
+ def self.requires_approval?
+ false
+ end
+
+ def invoke
+ if !guardian.can_see_review_queue?
+ return(
+ error_response(I18n.t("discourse_ai.ai_bot.add_reviewable_note.errors.not_allowed"))
+ )
+ end
+
+ if note_content.blank?
+ return(error_response(I18n.t("discourse_ai.ai_bot.add_reviewable_note.errors.no_note")))
+ end
+
+ reviewable = Reviewable.viewable_by(guardian.user).find_by(id: parameters[:reviewable_id])
+ if !reviewable
+ return(
+ error_response(I18n.t("discourse_ai.ai_bot.add_reviewable_note.errors.not_found"))
+ )
+ end
+
+ note = reviewable.reviewable_notes.build(content: note_content, user: acting_user)
+
+ if note.save
+ {
+ status: "success",
+ message:
+ I18n.t(
+ "discourse_ai.ai_bot.add_reviewable_note.success",
+ reviewable_id: reviewable.id,
+ ),
+ note_id: note.id,
+ }
+ else
+ error_response(
+ note.errors.full_messages.join(", ").presence ||
+ I18n.t("discourse_ai.ai_bot.add_reviewable_note.errors.failed"),
+ )
+ end
+ end
+
+ def description_args
+ { reviewable_id: parameters[:reviewable_id] }
+ end
+
+ private
+
+ def note_content
+ parameters[:note].to_s.strip
+ end
+ end
+ end
+ end
+end
diff --git a/plugins/discourse-ai/lib/agents/tools/list_reviewables.rb b/plugins/discourse-ai/lib/agents/tools/list_reviewables.rb
index 46abe2412b2..60ac3733f53 100644
--- a/plugins/discourse-ai/lib/agents/tools/list_reviewables.rb
+++ b/plugins/discourse-ai/lib/agents/tools/list_reviewables.rb
@@ -37,6 +37,12 @@ module DiscourseAi
"Filter by status: pending (default), approved, rejected, ignored, deleted",
type: "string",
},
+ {
+ name: "has_notes",
+ description:
+ "Filter by whether the item already has notes. Set to false to only return items that have no notes yet, true to only return items that already have notes.",
+ type: "boolean",
+ },
],
}
end
@@ -85,7 +91,26 @@ module DiscourseAi
filters[:from_date] = parameters[:max_hours_old].to_i.hours.ago
end
- reviewables = Reviewable.list_for(guardian.user, **filters).to_a
+ relation = Reviewable.list_for(guardian.user, **filters)
+
+ if parameters.key?(:has_notes) && !parameters[:has_notes].nil?
+ notes_exists = <<~SQL
+ EXISTS(
+ SELECT 1 FROM reviewable_notes
+ WHERE reviewable_notes.reviewable_id = reviewables.id
+ )
+ SQL
+ relation =
+ (
+ if ActiveModel::Type::Boolean.new.cast(parameters[:has_notes])
+ relation.where(notes_exists)
+ else
+ relation.where("NOT #{notes_exists}")
+ end
+ )
+ end
+
+ reviewables = relation.to_a
if reviewables.empty?
return(
@@ -152,6 +177,15 @@ module DiscourseAi
}
end
+ result[:notes] = reviewable.reviewable_notes.map do |note|
+ {
+ id: note.id,
+ content: note.content,
+ user: note.user&.username,
+ created_at: note.created_at.iso8601,
+ }
+ end
+
result
end
diff --git a/plugins/discourse-ai/spec/lib/agents/tools/add_reviewable_note_spec.rb b/plugins/discourse-ai/spec/lib/agents/tools/add_reviewable_note_spec.rb
new file mode 100644
index 00000000000..2d453ad52f9
--- /dev/null
+++ b/plugins/discourse-ai/spec/lib/agents/tools/add_reviewable_note_spec.rb
@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+RSpec.describe DiscourseAi::Agents::Tools::AddReviewableNote do
+ fab!(:llm_model)
+ let(:bot_user) { DiscourseAi::AiBot::EntryPoint.find_user_from_model(llm_model.name) }
+ let(:llm) { DiscourseAi::Completions::Llm.proxy(llm_model) }
+ fab!(:admin)
+
+ before do
+ enable_current_plugin
+ SiteSetting.ai_bot_enabled = true
+ end
+
+ def tool(params = nil, user: admin, **kwargs)
+ params ||= kwargs
+ ctx = DiscourseAi::Agents::BotContext.new(user: user)
+ described_class.new(params, bot_user: bot_user, llm: llm, context: ctx)
+ end
+
+ it "returns an error when user cannot see review queue" do
+ regular_user = Fabricate(:user, trust_level: TrustLevel[0])
+ result = tool({ reviewable_id: 1, note: "test" }, user: regular_user).invoke
+
+ expect(result[:status]).to eq("error")
+ expect(result[:error]).to include("not allowed")
+ end
+
+ it "returns an error when note is blank" do
+ result = tool(reviewable_id: 1, note: " ").invoke
+
+ expect(result[:status]).to eq("error")
+ expect(result[:error]).to include("note")
+ end
+
+ it "returns an error when reviewable is not found" do
+ result = tool(reviewable_id: -1, note: "test").invoke
+
+ expect(result[:status]).to eq("error")
+ expect(result[:error]).to include("not found")
+ end
+
+ context "with a flagged post" do
+ fab!(:post)
+ fab!(:flagged_reviewable) do
+ ReviewableFlaggedPost.needs_review!(
+ target: post,
+ created_by: Discourse.system_user,
+ reviewable_by_moderator: true,
+ )
+ end
+
+ it "adds a note to the reviewable without changing its status" do
+ result = tool(reviewable_id: flagged_reviewable.id, note: "This looks like spam to me").invoke
+
+ expect(result[:status]).to eq("success")
+
+ note = flagged_reviewable.reload.reviewable_notes.last
+ expect(note).to be_present
+ expect(note.content).to eq("This looks like spam to me")
+ expect(note.user).to be_present
+ expect(result[:note_id]).to eq(note.id)
+ expect(flagged_reviewable.status).to eq("pending")
+ end
+ end
+end
diff --git a/plugins/discourse-ai/spec/lib/agents/tools/list_reviewables_spec.rb b/plugins/discourse-ai/spec/lib/agents/tools/list_reviewables_spec.rb
index 8008a37983f..d6b2e3ab0cf 100644
--- a/plugins/discourse-ai/spec/lib/agents/tools/list_reviewables_spec.rb
+++ b/plugins/discourse-ai/spec/lib/agents/tools/list_reviewables_spec.rb
@@ -118,5 +118,36 @@ RSpec.describe DiscourseAi::Agents::Tools::ListReviewables do
expect(item[:scores]).to be_present
expect(item[:scores].first[:user]).to eq("system")
end
+
+ it "includes existing notes" do
+ flagged_reviewable.reviewable_notes.create!(user: admin, content: "Earlier judgment")
+
+ result = tool({}).invoke
+
+ item = result[:reviewables].first
+ expect(item[:notes].size).to eq(1)
+ expect(item[:notes].first[:content]).to eq("Earlier judgment")
+ expect(item[:notes].first[:user]).to eq(admin.username)
+ end
+
+ it "filters out items with notes when has_notes is false" do
+ result = tool(has_notes: false).invoke
+ expect(result[:reviewables].size).to eq(1)
+
+ flagged_reviewable.reviewable_notes.create!(user: admin, content: "Reviewed")
+
+ result = tool(has_notes: false).invoke
+ expect(result[:reviewables]).to be_empty
+ end
+
+ it "returns only items with notes when has_notes is true" do
+ result = tool(has_notes: true).invoke
+ expect(result[:reviewables]).to be_empty
+
+ flagged_reviewable.reviewable_notes.create!(user: admin, content: "Reviewed")
+
+ result = tool(has_notes: true).invoke
+ expect(result[:reviewables].size).to eq(1)
+ end
end
end