A platform for community discussion. Free, open, simple.
FEATURE: Add review queue tools for AI agents (#38928)
Rafael dos Santos Silva93ed2ad08e18
diff --git a/plugins/discourse-ai/config/locales/server.en.yml b/plugins/discourse-ai/config/locales/server.en.ymlindex 9ab25d752e3..e3f3a27b471 100644--- a/plugins/discourse-ai/config/locales/server.en.yml+++ b/plugins/discourse-ai/config/locales/server.en.yml@@ -566,6 +566,8 @@ en:set_slow_mode: "Set slow mode"move_posts: "Move posts"grant_badge: "Grant badge"+ list_reviewables: "List review queue"+ perform_reviewable_action: "Review queue action"assign: "Assign topic"mark_as_solved: "Mark as solved"search: "Search"@@ -609,6 +611,8 @@ en:set_slow_mode: "Enable or disable slow mode on a topic"move_posts: "Move posts to a new or existing topic"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"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"@@ -652,6 +656,8 @@ en:set_slow_mode: "Setting slow mode on topic %{topic_id} (%{slow_mode_seconds}s)"move_posts: "Moving posts %{post_ids} from topic %{topic_id}"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}"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>"@@ -808,6 +814,26 @@ en:action_failed: "Failed to update the solved status."success: "Solved status updated successfully."+ list_reviewables:+ errors:+ not_allowed: "You are not allowed to view the review queue"+ invalid_type: "Invalid reviewable type"+ invalid_status: "Invalid status. Must be one of: pending, approved, rejected, ignored, deleted, reviewed, all."+ empty: "No review queue items found matching the given filters"+ found:+ one: "Found %{count} review queue item"+ other: "Found %{count} review queue items"++ perform_reviewable_action:+ errors:+ not_allowed: "You are not allowed to access the review queue"+ not_found: "Review queue item not found"+ no_reason: "A reason is required to perform an action on a review queue item"+ invalid_action: "Invalid action '%{action}'. Available actions: %{available}"+ conflict: "This review queue item was updated by someone else. Please try again"+ action_failed: "Failed to perform the action"+ success: "Successfully performed '%{action}' on 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.rbindex 3ebabe70ba9..aea6de12d2d 100644--- a/plugins/discourse-ai/lib/agents/agent.rb+++ b/plugins/discourse-ai/lib/agents/agent.rb@@ -133,6 +133,8 @@ module DiscourseAiTools::SetSlowMode,Tools::MovePosts,Tools::GrantBadge,+ Tools::ListReviewables,+ Tools::PerformReviewableAction,Tools::DbSchema,Tools::SearchSettings,Tools::SettingContext,diff --git a/plugins/discourse-ai/lib/agents/tools/list_reviewables.rb b/plugins/discourse-ai/lib/agents/tools/list_reviewables.rbnew file mode 100644index 00000000000..46abe2412b2--- /dev/null+++ b/plugins/discourse-ai/lib/agents/tools/list_reviewables.rb@@ -0,0 +1,200 @@+# frozen_string_literal: true++module DiscourseAi+ module Agents+ module Tools+ class ListReviewables < Tool+ MAX_RESULTS = 20++ def self.signature+ {+ name: name,+ description:+ "Lists pending review queue items. Can filter by reviewable type and age. Returns a summary of each item including its ID, type, score, creation date, target details, and available actions.",+ parameters: [+ {+ name: "type",+ description:+ "Filter by reviewable type: ReviewableFlaggedPost, ReviewableQueuedPost, ReviewableUser, ReviewablePost. Leave blank for all types.",+ type: "string",+ },+ {+ name: "min_hours_old",+ description:+ "Only return items that have been in the queue for at least this many hours",+ type: "integer",+ },+ {+ name: "max_hours_old",+ description:+ "Only return items that have been in the queue for at most this many hours",+ type: "integer",+ },+ { name: "category_id", description: "Filter by category ID", type: "integer" },+ {+ name: "status",+ description:+ "Filter by status: pending (default), approved, rejected, ignored, deleted",+ type: "string",+ },+ ],+ }+ end++ def self.name+ "list_reviewables"+ end++ def self.requires_approval?+ false+ end++ def invoke+ if !guardian.can_see_review_queue?+ return(+ error_response(I18n.t("discourse_ai.ai_bot.list_reviewables.errors.not_allowed"))+ )+ end++ status = (parameters[:status] || "pending").to_sym+ allowed_statuses = Reviewable.statuses.symbolize_keys.keys + %i[reviewed all]+ if !allowed_statuses.include?(status)+ return(+ error_response(I18n.t("discourse_ai.ai_bot.list_reviewables.errors.invalid_status"))+ )+ end++ filters = { status: status, limit: MAX_RESULTS }++ if parameters[:type].present?+ unless Reviewable.valid_type?(parameters[:type])+ return(+ error_response(I18n.t("discourse_ai.ai_bot.list_reviewables.errors.invalid_type"))+ )+ end+ filters[:type] = parameters[:type]+ end++ filters[:category_id] = parameters[:category_id] if parameters[:category_id].present?++ if parameters[:min_hours_old].present?+ filters[:to_date] = parameters[:min_hours_old].to_i.hours.ago+ end++ if parameters[:max_hours_old].present?+ filters[:from_date] = parameters[:max_hours_old].to_i.hours.ago+ end++ reviewables = Reviewable.list_for(guardian.user, **filters).to_a++ if reviewables.empty?+ return(+ {+ status: "success",+ message: I18n.t("discourse_ai.ai_bot.list_reviewables.empty"),+ reviewables: [],+ }+ )+ end++ rows = reviewables.map { |r| serialize_reviewable(r) }++ {+ status: "success",+ message: I18n.t("discourse_ai.ai_bot.list_reviewables.found", count: rows.size),+ reviewables: rows,+ }+ end++ def description_args+ { type: parameters[:type] || "all", count: 0 }+ end++ private++ def serialize_reviewable(reviewable)+ result = {+ id: reviewable.id,+ type: reviewable.type,+ status: reviewable.status,+ score: reviewable.score.to_f.round(1),+ created_at: reviewable.created_at.iso8601,+ hours_old: ((::Time.zone.now - reviewable.created_at) / 1.hour).round(1),+ category_id: reviewable.category_id,+ topic_id: reviewable.topic_id,+ }++ if reviewable.target_created_by+ result[:target_created_by] = reviewable.target_created_by.username+ end++ result[:created_by] = reviewable.created_by.username if reviewable.created_by++ result[:available_actions] = available_action_ids(reviewable)++ case reviewable+ when ReviewableFlaggedPost+ serialize_flagged_post(result, reviewable)+ when ReviewableQueuedPost+ serialize_queued_post(result, reviewable)+ when ReviewableUser+ serialize_user(result, reviewable)+ when ReviewablePost+ serialize_post(result, reviewable)+ end++ result[:scores] = reviewable.reviewable_scores.map do |score|+ {+ reason: score.reason,+ score: score.score.to_f.round(1),+ status: score.status,+ user: score.user&.username,+ }+ end++ result+ end++ def available_action_ids(reviewable)+ actions = reviewable.actions_for(guardian)+ actions.bundles.flat_map { |bundle| bundle.actions.map { |a| a.server_action } }+ end++ def serialize_flagged_post(result, reviewable)+ post = reviewable.post+ return unless post++ result[:post_id] = post.id+ result[:post_number] = post.post_number+ result[:post_excerpt] = post.excerpt(300, strip_links: true, text_entities: true)+ result[:topic_title] = post.topic&.title+ end++ def serialize_queued_post(result, reviewable)+ payload = reviewable.payload || {}+ result[:queued_title] = payload["title"]+ result[:queued_raw_excerpt] = payload["raw"].to_s.truncate(300)+ result[:queued_tags] = payload["tags"]+ end++ def serialize_user(result, reviewable)+ target = reviewable.target+ return unless target++ result[:username] = target.username+ result[:user_id] = target.id+ end++ def serialize_post(result, reviewable)+ post = reviewable.target+ return unless post.is_a?(Post)++ result[:post_id] = post.id+ result[:post_number] = post.post_number+ result[:post_excerpt] = post.excerpt(300, strip_links: true, text_entities: true)+ result[:topic_title] = post.topic&.title+ end+ end+ end+ end+enddiff --git a/plugins/discourse-ai/lib/agents/tools/perform_reviewable_action.rb b/plugins/discourse-ai/lib/agents/tools/perform_reviewable_action.rbnew file mode 100644index 00000000000..10fac26cbee--- /dev/null+++ b/plugins/discourse-ai/lib/agents/tools/perform_reviewable_action.rb@@ -0,0 +1,141 @@+# frozen_string_literal: true++module DiscourseAi+ module Agents+ module Tools+ class PerformReviewableAction < Tool+ def self.signature+ {+ name: name,+ description:+ "Performs an action on a review queue item. Use list_reviewables first to discover available actions for each item. Common actions include: agree_and_keep, agree_and_hide, disagree, ignore_and_do_nothing, delete_and_agree, approve_post, reject_post, approve_user, delete_user.",+ parameters: [+ {+ name: "reviewable_id",+ description: "The ID of the reviewable item to act on",+ type: "integer",+ required: true,+ },+ {+ name: "action_id",+ description:+ "The action to perform (e.g. agree_and_keep, agree_and_hide, disagree, ignore_and_do_nothing, delete_and_agree, approve_post, reject_post, approve_user, delete_user)",+ type: "string",+ required: true,+ },+ {+ name: "reason",+ description: "Short explanation of why this action is being taken",+ type: "string",+ required: true,+ },+ ],+ }+ end++ def self.name+ "perform_reviewable_action"+ end++ def self.requires_approval?+ false+ end++ def invoke+ if !guardian.can_see_review_queue?+ return(+ error_response(+ I18n.t("discourse_ai.ai_bot.perform_reviewable_action.errors.not_allowed"),+ )+ )+ end++ if reason.blank?+ return(+ error_response(+ I18n.t("discourse_ai.ai_bot.perform_reviewable_action.errors.no_reason"),+ )+ )+ end++ reviewable = Reviewable.viewable_by(guardian.user).find_by(id: parameters[:reviewable_id])+ if !reviewable+ return(+ error_response(+ I18n.t("discourse_ai.ai_bot.perform_reviewable_action.errors.not_found"),+ )+ )+ end++ action_id = parameters[:action_id].to_s.to_sym+ available_actions = reviewable.actions_for(guardian)+ valid_action_ids =+ available_actions.bundles.flat_map do |bundle|+ bundle.actions.map { |a| a.server_action.to_sym }+ end++ if !valid_action_ids.include?(action_id)+ return(+ error_response(+ I18n.t(+ "discourse_ai.ai_bot.perform_reviewable_action.errors.invalid_action",+ action: action_id,+ available: valid_action_ids.join(", "),+ ),+ )+ )+ end++ reviewable.reviewable_notes.create!(user: acting_user, content: reason)++ begin+ result =+ reviewable.perform(+ acting_user,+ action_id,+ version: reviewable.version,+ guardian: guardian,+ )+ rescue Reviewable::InvalidAction+ return(+ error_response(+ I18n.t(+ "discourse_ai.ai_bot.perform_reviewable_action.errors.invalid_action",+ action: action_id,+ available: valid_action_ids.join(", "),+ ),+ )+ )+ rescue Reviewable::UpdateConflict+ return(+ error_response(+ I18n.t("discourse_ai.ai_bot.perform_reviewable_action.errors.conflict"),+ )+ )+ end++ if result.success?+ {+ status: "success",+ message:+ I18n.t(+ "discourse_ai.ai_bot.perform_reviewable_action.success",+ action: action_id,+ reviewable_id: reviewable.id,+ ),+ }+ else+ error_response(+ result.errors&.full_messages&.join(", ").presence ||+ I18n.t("discourse_ai.ai_bot.perform_reviewable_action.errors.action_failed"),+ )+ end+ end++ def description_args+ { reviewable_id: parameters[:reviewable_id], action: parameters[:action_id] }+ end+ end+ end+ end+enddiff --git a/plugins/discourse-ai/spec/lib/agents/tools/list_reviewables_spec.rb b/plugins/discourse-ai/spec/lib/agents/tools/list_reviewables_spec.rbnew file mode 100644index 00000000000..8008a37983f--- /dev/null+++ b/plugins/discourse-ai/spec/lib/agents/tools/list_reviewables_spec.rb@@ -0,0 +1,122 @@+# frozen_string_literal: true++RSpec.describe DiscourseAi::Agents::Tools::ListReviewables 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({}, user: regular_user).invoke++ expect(result[:status]).to eq("error")+ expect(result[:error]).to include("not allowed")+ end++ it "returns empty result when no reviewables exist" do+ result = tool({}).invoke++ expect(result[:status]).to eq("success")+ expect(result[:reviewables]).to eq([])+ end++ context "with pending reviewables" do+ fab!(:post)+ fab!(:flagged_reviewable) do+ ReviewableFlaggedPost.needs_review!(+ target: post,+ created_by: Discourse.system_user,+ reviewable_by_moderator: true,+ )+ end++ it "lists pending reviewables" do+ result = tool({}).invoke++ expect(result[:status]).to eq("success")+ expect(result[:reviewables].size).to eq(1)++ item = result[:reviewables].first+ expect(item[:id]).to eq(flagged_reviewable.id)+ expect(item[:type]).to eq("ReviewableFlaggedPost")+ expect(item[:status]).to eq("pending")+ expect(item[:post_id]).to eq(post.id)+ end++ it "filters by type" do+ result = tool(type: "ReviewableUser").invoke++ expect(result[:status]).to eq("success")+ expect(result[:reviewables]).to be_empty+ end++ it "returns error for invalid type" do+ result = tool(type: "InvalidType").invoke++ expect(result[:status]).to eq("error")+ expect(result[:error]).to include("Invalid")+ end++ it "returns error for invalid status" do+ result = tool(status: "bogus").invoke++ expect(result[:status]).to eq("error")+ expect(result[:error]).to include("Invalid status")+ end++ it "filters by min_hours_old" do+ flagged_reviewable.update!(created_at: 5.hours.ago)++ result = tool(min_hours_old: 3).invoke+ expect(result[:reviewables].size).to eq(1)++ result = tool(min_hours_old: 10).invoke+ expect(result[:reviewables]).to be_empty+ end++ it "filters by max_hours_old" do+ flagged_reviewable.update!(created_at: 5.hours.ago)++ result = tool(max_hours_old: 10).invoke+ expect(result[:reviewables].size).to eq(1)++ result = tool(max_hours_old: 3).invoke+ expect(result[:reviewables]).to be_empty+ end++ it "includes available actions" do+ result = tool({}).invoke++ item = result[:reviewables].first+ expect(item[:available_actions]).to be_present+ expect(item[:available_actions]).to include("agree_and_hide")+ end++ it "includes score details" do+ flagged_reviewable.add_score(+ Discourse.system_user,+ ReviewableScore.types[:needs_approval],+ reason: "test reason",+ force_review: true,+ )++ result = tool({}).invoke++ item = result[:reviewables].first+ expect(item[:scores]).to be_present+ expect(item[:scores].first[:user]).to eq("system")+ end+ end+enddiff --git a/plugins/discourse-ai/spec/lib/agents/tools/perform_reviewable_action_spec.rb b/plugins/discourse-ai/spec/lib/agents/tools/perform_reviewable_action_spec.rbnew file mode 100644index 00000000000..1727fea3e28--- /dev/null+++ b/plugins/discourse-ai/spec/lib/agents/tools/perform_reviewable_action_spec.rb@@ -0,0 +1,153 @@+# frozen_string_literal: true++RSpec.describe DiscourseAi::Agents::Tools::PerformReviewableAction 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, action_id: "agree_and_keep", reason: "test" },+ user: regular_user,+ ).invoke++ expect(result[:status]).to eq("error")+ expect(result[:error]).to include("not allowed")+ end++ it "returns an error when reason is blank" do+ result = tool(reviewable_id: 1, action_id: "agree_and_keep", reason: " ").invoke++ expect(result[:status]).to eq("error")+ expect(result[:error]).to include("reason")+ end++ it "returns an error when reviewable is not found" do+ result = tool(reviewable_id: -1, action_id: "agree_and_keep", reason: "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 "returns an error for invalid action" do+ result =+ tool(+ reviewable_id: flagged_reviewable.id,+ action_id: "nonexistent_action",+ reason: "test",+ ).invoke++ expect(result[:status]).to eq("error")+ expect(result[:error]).to include("Invalid action")+ end++ it "successfully performs agree_and_keep" do+ result =+ tool(+ reviewable_id: flagged_reviewable.id,+ action_id: "agree_and_keep",+ reason: "Confirmed violation",+ ).invoke++ expect(result[:status]).to eq("success")+ expect(flagged_reviewable.reload.status).to eq("approved")+ end++ it "persists the reason as a reviewable note" do+ tool(+ reviewable_id: flagged_reviewable.id,+ action_id: "agree_and_keep",+ reason: "AI determined this violates policy",+ ).invoke++ note = flagged_reviewable.reviewable_notes.last+ expect(note).to be_present+ expect(note.content).to eq("AI determined this violates policy")+ end++ it "successfully performs agree_and_hide" do+ PostActionCreator.inappropriate(Fabricate(:user, refresh_auto_groups: true), post)++ result =+ tool(+ reviewable_id: flagged_reviewable.id,+ action_id: "agree_and_hide",+ reason: "Hiding inappropriate content",+ ).invoke++ expect(result[:status]).to eq("success")+ expect(flagged_reviewable.reload.status).to eq("approved")+ expect(post.reload.hidden).to eq(true)+ end++ it "successfully performs disagree" do+ result =+ tool(+ reviewable_id: flagged_reviewable.id,+ action_id: "disagree",+ reason: "Post is fine",+ ).invoke++ expect(result[:status]).to eq("success")+ expect(flagged_reviewable.reload.status).to eq("rejected")+ end++ it "successfully performs ignore" do+ result =+ tool(+ reviewable_id: flagged_reviewable.id,+ action_id: "ignore_and_do_nothing",+ reason: "Not sure, deferring",+ ).invoke++ expect(result[:status]).to eq("success")+ expect(flagged_reviewable.reload.status).to eq("ignored")+ end+ end++ context "with a queued post" do+ fab!(:queued_reviewable) do+ Fabricate(+ :reviewable_queued_post_topic,+ created_by: Fabricate(:user),+ status: Reviewable.statuses[:pending],+ )+ end++ it "successfully approves a queued post" do+ result =+ tool(+ reviewable_id: queued_reviewable.id,+ action_id: "approve_post",+ reason: "Looks good",+ ).invoke++ expect(result[:status]).to eq("success")+ expect(queued_reviewable.reload.status).to eq("approved")+ end+ end+end