Skip to content

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

FEATURE: Scoped AI highlights to user-selected categories (#41506)

Natalie Taye2d1e8639873
diff --git a/plugins/discourse-ai/assets/javascripts/discourse/lib/ai-feature-setting-groups.js b/plugins/discourse-ai/assets/javascripts/discourse/lib/ai-feature-setting-groups.js
index 9af3a522a7b..342799e6b1f 100644
--- a/plugins/discourse-ai/assets/javascripts/discourse/lib/ai-feature-setting-groups.js
+++ b/plugins/discourse-ai/assets/javascripts/discourse/lib/ai-feature-setting-groups.js
@@ -86,6 +86,8 @@ export const AI_FEATURE_SETTING_GROUPS = {
settings: [
"ai_admin_dashboard_enabled",
"ai_admin_dashboard_highlights_agent",
+ "ai_admin_dashboard_highlights_category_scope",
+ "ai_admin_dashboard_highlights_categories",
],
},
],
diff --git a/plugins/discourse-ai/config/locales/server.en.yml b/plugins/discourse-ai/config/locales/server.en.yml
index d5213392599..7f8fe663f69 100644
--- a/plugins/discourse-ai/config/locales/server.en.yml
+++ b/plugins/discourse-ai/config/locales/server.en.yml
@@ -122,6 +122,8 @@ en:
ai_admin_dashboard_enabled: "Enable AI features on the admin dashboard."
ai_admin_dashboard_highlights_agent: "Agent that explains notable community shifts on the admin dashboard."
+ ai_admin_dashboard_highlights_category_scope: "Choose which categories AI highlights can use. Include and exclude options use {{setting:ai_admin_dashboard_highlights_categories}}. Personal messages are always excluded."
+ ai_admin_dashboard_highlights_categories: "Categories used when the AI highlights category scope is set to <strong>include</strong> or <strong>exclude</strong>."
ai_summarization_enabled: "Enable the summarize feature"
ai_summarization_agent: "Agent to use for summarize feature"
ai_pm_summarization_allowed_groups: "Groups allowed to create and view summaries in PMs."
diff --git a/plugins/discourse-ai/config/settings.yml b/plugins/discourse-ai/config/settings.yml
index a318f50e33a..c3338ddf30e 100644
--- a/plugins/discourse-ai/config/settings.yml
+++ b/plugins/discourse-ai/config/settings.yml
@@ -298,6 +298,27 @@ discourse_ai:
type: enum
enum: "DiscourseAi::Configuration::AgentEnumerator"
area: "ai-features/admin_dashboard"
+ ai_admin_dashboard_highlights_category_scope:
+ type: enum
+ default: "public"
+ enum: "CategoryScopeSiteSetting"
+ client: false
+ area: "ai-features/admin_dashboard"
+ ai_admin_dashboard_highlights_categories:
+ type: category_list
+ default: ""
+ client: false
+ area: "ai-features/admin_dashboard"
+ depends_on:
+ - ai_admin_dashboard_highlights_category_scope
+ depends_on_values:
+ ai_admin_dashboard_highlights_category_scope:
+ - include
+ - include_strict
+ - exclude
+ - exclude_strict
+ depends_behavior: "hidden"
+ dependent_setting_display: "inline"
ai_summarization_enabled:
default: false
client: true
diff --git a/plugins/discourse-ai/lib/admin_dashboard/admin_dashboard_facts.rb b/plugins/discourse-ai/lib/admin_dashboard/admin_dashboard_facts.rb
index 9623e31bbb7..5ef71dffbe1 100644
--- a/plugins/discourse-ai/lib/admin_dashboard/admin_dashboard_facts.rb
+++ b/plugins/discourse-ai/lib/admin_dashboard/admin_dashboard_facts.rb
@@ -125,20 +125,88 @@ module DiscourseAi
{ key: key, category: category, headline: headline, score: score }
end
+ def topic_category_join(topic_alias: "t", category_alias: "c")
+ "LEFT JOIN categories #{category_alias} ON #{category_alias}.id = #{topic_alias}.category_id"
+ end
+
+ def topic_conditions(topic_alias: "t", category_alias: "c")
+ <<~SQL
+ #{topic_alias}.deleted_at IS NULL
+ AND #{topic_alias}.visible = true
+ AND #{topic_alias}.archetype = 'regular'
+ #{category_scope_condition(topic_alias: topic_alias, category_alias: category_alias)}
+ SQL
+ end
+
+ def category_scope_condition(topic_alias:, category_alias:)
+ case SiteSetting.ai_admin_dashboard_highlights_category_scope
+ when "all"
+ ""
+ when "include"
+ return "AND 1 = 0" if category_ids_with_subcategories.blank?
+
+ "AND #{topic_alias}.category_id IN (:category_ids)"
+ when "include_strict"
+ return "AND 1 = 0" if category_ids.blank?
+
+ "AND #{topic_alias}.category_id IN (:category_ids)"
+ when "exclude"
+ return "" if category_ids_with_subcategories.blank?
+
+ "AND (#{topic_alias}.category_id IS NULL OR #{topic_alias}.category_id NOT IN (:category_ids))"
+ when "exclude_strict"
+ return "" if category_ids.blank?
+
+ "AND (#{topic_alias}.category_id IS NULL OR #{topic_alias}.category_id NOT IN (:category_ids))"
+ else
+ "AND (#{topic_alias}.category_id IS NULL OR #{category_alias}.read_restricted = false)"
+ end
+ end
+
+ def scoped_category_ids
+ case SiteSetting.ai_admin_dashboard_highlights_category_scope
+ when "include", "exclude"
+ category_ids_with_subcategories
+ else
+ category_ids
+ end
+ end
+
+ def category_ids
+ @category_ids ||=
+ SiteSetting
+ .ai_admin_dashboard_highlights_categories
+ .to_s
+ .split("|")
+ .filter_map { |category_id| category_id.presence&.to_i }
+ end
+
+ def category_ids_with_subcategories
+ @category_ids_with_subcategories ||=
+ category_ids.flat_map { |category_id| Category.subcategory_ids(category_id) }.uniq
+ end
+
# ---- internal signals --------------------------------------------------
def new_topics_count(start_date, end_date)
- DB.query_single(<<~SQL, start_date: start_date, end_date: end_date).first.to_i
+ DB
+ .query_single(
+ <<~SQL,
SELECT COUNT(*)
FROM topics t
+ #{topic_category_join}
JOIN users u ON u.id = t.user_id
WHERE t.created_at >= :start_date
AND t.created_at < (:end_date::date + 1)
- AND t.deleted_at IS NULL
- AND t.visible = true
- AND t.archetype = 'regular'
+ AND #{topic_conditions}
AND NOT (u.admin OR u.moderator)
SQL
+ start_date: start_date,
+ end_date: end_date,
+ category_ids: scoped_category_ids,
+ )
+ .first
+ .to_i
end
def topic_volume
@@ -159,31 +227,46 @@ module DiscourseAi
end
def hot_topic
- row = DB.query(<<~SQL, start_date: @start_date, end_date: @end_date).first
+ row =
+ DB.query(
+ <<~SQL,
SELECT t.id, t.title, COUNT(p.id) FILTER (WHERE p.post_number > 1) AS replies
FROM topics t
+ #{topic_category_join}
JOIN posts p ON p.topic_id = t.id AND p.deleted_at IS NULL AND p.post_type = 1
WHERE t.created_at >= :start_date
AND t.created_at < (:end_date::date + 1)
- AND t.deleted_at IS NULL
- AND t.visible = true
- AND t.archetype = 'regular'
+ AND #{topic_conditions}
GROUP BY t.id, t.title
ORDER BY replies DESC
LIMIT 1
SQL
+ start_date: @start_date,
+ end_date: @end_date,
+ category_ids: scoped_category_ids,
+ ).first
return if row.nil? || row.replies.to_i < 10
- avg = DB.query_single(<<~SQL, start_date: @start_date, end_date: @end_date).first.to_f
+ avg =
+ DB
+ .query_single(
+ <<~SQL,
SELECT AVG(reply_count) FROM (
SELECT COUNT(p.id) FILTER (WHERE p.post_number > 1) AS reply_count
FROM topics t
+ #{topic_category_join}
JOIN posts p ON p.topic_id = t.id AND p.deleted_at IS NULL AND p.post_type = 1
WHERE t.created_at >= :start_date AND t.created_at < (:end_date::date + 1)
- AND t.deleted_at IS NULL AND t.visible = true AND t.archetype = 'regular'
+ AND #{topic_conditions}
GROUP BY t.id
) per_topic
SQL
+ start_date: @start_date,
+ end_date: @end_date,
+ category_ids: scoped_category_ids,
+ )
+ .first
+ .to_f
return if avg.positive? && row.replies < (avg * 3)
signal(
@@ -195,18 +278,26 @@ module DiscourseAi
end
def unanswered_gap
- count = DB.query_single(<<~SQL, start_date: @start_date, end_date: @end_date).first.to_i
+ count =
+ DB
+ .query_single(
+ <<~SQL,
SELECT COUNT(*)
FROM topics t
+ #{topic_category_join}
JOIN users u ON u.id = t.user_id
WHERE t.created_at >= :start_date
AND t.created_at < (:end_date::date + 1)
AND t.posts_count = 1
- AND t.deleted_at IS NULL
- AND t.visible = true
- AND t.archetype = 'regular'
+ AND #{topic_conditions}
AND NOT (u.admin OR u.moderator)
SQL
+ start_date: @start_date,
+ end_date: @end_date,
+ category_ids: scoped_category_ids,
+ )
+ .first
+ .to_i
return if count < 5
total = new_topics_count(@start_date, @end_date)
@@ -225,18 +316,27 @@ module DiscourseAi
def staff_ratio
return if @period_days > MAX_STAFF_RATIO_DAYS
- row = DB.query(<<~SQL, start_date: @start_date, end_date: @end_date).first
+ row =
+ DB.query(
+ <<~SQL,
SELECT
COUNT(*) FILTER (WHERE u.admin OR u.moderator) AS staff,
COUNT(*) AS total
FROM posts p
+ JOIN topics t ON t.id = p.topic_id
+ #{topic_category_join}
JOIN users u ON u.id = p.user_id
WHERE p.created_at >= :start_date
AND p.created_at < (:end_date::date + 1)
AND p.deleted_at IS NULL
AND p.post_type = 1
AND u.id > 0
+ AND #{topic_conditions}
SQL
+ start_date: @start_date,
+ end_date: @end_date,
+ category_ids: scoped_category_ids,
+ ).first
return if row.nil? || row.total.to_i < 20
pct = ((row.staff.to_f / row.total) * 100).round
@@ -358,11 +458,13 @@ module DiscourseAi
SELECT e.topic_id, t.title, COUNT(*) AS visits
FROM browser_pageview_events e
JOIN topics t ON t.id = e.topic_id
+ #{topic_category_join}
WHERE e.created_at >= :start_date
AND e.created_at < (:end_date::date + 1)
AND e.topic_id IS NOT NULL
AND e.normalized_referrer IS NOT NULL
AND e.source = :source
+ AND #{topic_conditions}
GROUP BY e.topic_id, t.title
ORDER BY visits DESC
LIMIT 1
@@ -370,6 +472,7 @@ module DiscourseAi
start_date: @start_date,
end_date: @end_date,
source: BrowserPageviewEvent.rollup_source,
+ category_ids: scoped_category_ids,
).first
return if row.nil? || row.visits.to_i < 50
diff --git a/plugins/discourse-ai/lib/admin_dashboard/highlight_generator.rb b/plugins/discourse-ai/lib/admin_dashboard/highlight_generator.rb
index db7e71e384a..f30a4000150 100644
--- a/plugins/discourse-ai/lib/admin_dashboard/highlight_generator.rb
+++ b/plugins/discourse-ai/lib/admin_dashboard/highlight_generator.rb
@@ -38,7 +38,20 @@ module DiscourseAi
def cache_key
db = RailsMultisite::ConnectionManagement.current_db
agent_id = SiteSetting.ai_admin_dashboard_highlights_agent
- "ai_admin_dashboard_highlight:v#{CACHE_VERSION}:#{db}:#{agent_id}:#{period}:#{start_date}:#{end_date}:#{I18n.locale}"
+ "ai_admin_dashboard_highlight:v#{CACHE_VERSION}:#{db}:#{agent_id}:#{categories_cache_key}:#{period}:#{start_date}:#{end_date}:#{I18n.locale}"
+ end
+
+ def categories_cache_key
+ category_ids =
+ SiteSetting
+ .ai_admin_dashboard_highlights_categories
+ .to_s
+ .split("|")
+ .filter_map { |category_id| category_id.presence&.to_i }
+ .sort
+ .join("|")
+
+ "#{SiteSetting.ai_admin_dashboard_highlights_category_scope}:#{category_ids}"
end
def generate_highlight
diff --git a/plugins/discourse-ai/spec/lib/admin_dashboard/admin_dashboard_facts_spec.rb b/plugins/discourse-ai/spec/lib/admin_dashboard/admin_dashboard_facts_spec.rb
index 050d11cb237..089bf4c7619 100644
--- a/plugins/discourse-ai/spec/lib/admin_dashboard/admin_dashboard_facts_spec.rb
+++ b/plugins/discourse-ai/spec/lib/admin_dashboard/admin_dashboard_facts_spec.rb
@@ -105,6 +105,131 @@ RSpec.describe DiscourseAi::AdminDashboard::AdminDashboardFacts do
)
end
+ it "uses public categories for topic volume by default" do
+ start_date = Date.parse("2030-01-08")
+ end_date = Date.parse("2030-01-14")
+ private_category = Fabricate(:private_category, group: Fabricate(:group))
+
+ Fabricate(:topic, created_at: Date.parse("2030-01-01"))
+ Fabricate.times(6, :topic, category: private_category, created_at: start_date)
+ Fabricate.times(6, :private_message_topic, created_at: start_date)
+
+ topic_volume =
+ compute(start_date: start_date.to_s, end_date: end_date.to_s)
+ .fetch(:signals)
+ .find { |signal| signal[:key] == :topic_volume }
+
+ expect(topic_volume).to be_nil
+ end
+
+ it "uses all categories for topic volume when configured" do
+ start_date = Date.parse("2030-01-08")
+ end_date = Date.parse("2030-01-14")
+ private_category = Fabricate(:private_category, group: Fabricate(:group))
+ SiteSetting.ai_admin_dashboard_highlights_category_scope = "all"
+
+ Fabricate(:topic, created_at: Date.parse("2030-01-01"))
+ Fabricate.times(6, :topic, category: private_category, created_at: start_date)
+ Fabricate.times(6, :private_message_topic, created_at: start_date)
+
+ topic_volume =
+ compute(start_date: start_date.to_s, end_date: end_date.to_s)
+ .fetch(:signals)
+ .find { |signal| signal[:key] == :topic_volume }
+
+ expect(topic_volume).to include(
+ category: :participation,
+ headline: "New topics were up 500% versus the previous period",
+ )
+ end
+
+ it "includes subcategories in included topic volume" do
+ start_date = Date.parse("2030-01-08")
+ end_date = Date.parse("2030-01-14")
+ parent_category = Fabricate(:category)
+ subcategory = Fabricate(:category, parent_category: parent_category)
+ SiteSetting.ai_admin_dashboard_highlights_category_scope = "include"
+ SiteSetting.ai_admin_dashboard_highlights_categories = parent_category.id.to_s
+
+ Fabricate(:topic, category: subcategory, created_at: Date.parse("2030-01-01"))
+ Fabricate.times(6, :topic, category: subcategory, created_at: start_date)
+
+ topic_volume =
+ compute(start_date: start_date.to_s, end_date: end_date.to_s)
+ .fetch(:signals)
+ .find { |signal| signal[:key] == :topic_volume }
+
+ expect(topic_volume).to include(
+ category: :participation,
+ headline: "New topics were up 500% versus the previous period",
+ )
+ end
+
+ it "uses only included categories for strict topic volume" do
+ start_date = Date.parse("2030-01-08")
+ end_date = Date.parse("2030-01-14")
+ parent_category = Fabricate(:category)
+ subcategory = Fabricate(:category, parent_category: parent_category)
+ SiteSetting.ai_admin_dashboard_highlights_category_scope = "include_strict"
+ SiteSetting.ai_admin_dashboard_highlights_categories = parent_category.id.to_s
+
+ Fabricate(:topic, category: subcategory, created_at: Date.parse("2030-01-01"))
+ Fabricate.times(6, :topic, category: subcategory, created_at: start_date)
+
+ topic_volume =
+ compute(start_date: start_date.to_s, end_date: end_date.to_s)
+ .fetch(:signals)
+ .find { |signal| signal[:key] == :topic_volume }
+
+ expect(topic_volume).to be_nil
+ end
+
+ it "excludes categories and subcategories from all topic volume" do
+ start_date = Date.parse("2030-01-08")
+ end_date = Date.parse("2030-01-14")
+ parent_category = Fabricate(:category)
+ subcategory = Fabricate(:category, parent_category: parent_category)
+ private_category = Fabricate(:private_category, group: Fabricate(:group))
+ SiteSetting.ai_admin_dashboard_highlights_category_scope = "exclude"
+ SiteSetting.ai_admin_dashboard_highlights_categories = parent_category.id.to_s
+
+ Fabricate(:topic, created_at: Date.parse("2030-01-01"))
+ Fabricate.times(6, :topic, category: subcategory, created_at: start_date)
+ Fabricate.times(6, :topic, category: private_category, created_at: start_date)
+
+ topic_volume =
+ compute(start_date: start_date.to_s, end_date: end_date.to_s)
+ .fetch(:signals)
+ .find { |signal| signal[:key] == :topic_volume }
+
+ expect(topic_volume).to include(
+ category: :participation,
+ headline: "New topics were up 500% versus the previous period",
+ )
+ end
+
+ it "excludes only configured categories from strict topic volume" do
+ start_date = Date.parse("2030-01-08")
+ end_date = Date.parse("2030-01-14")
+ parent_category = Fabricate(:category)
+ subcategory = Fabricate(:category, parent_category: parent_category)
+ SiteSetting.ai_admin_dashboard_highlights_category_scope = "exclude_strict"
+ SiteSetting.ai_admin_dashboard_highlights_categories = parent_category.id.to_s
+
+ Fabricate(:topic, created_at: Date.parse("2030-01-01"))
+ Fabricate.times(6, :topic, category: subcategory, created_at: start_date)
+
+ topic_volume =
+ compute(start_date: start_date.to_s, end_date: end_date.to_s)
+ .fetch(:signals)
+ .find { |signal| signal[:key] == :topic_volume }
+
+ expect(topic_volume).to include(
+ category: :participation,
+ headline: "New topics were up 500% versus the previous period",
+ )
+ end
+
it "skips the raw landing-topic scan for long date ranges" do
queries =
track_sql_queries do
@@ -135,6 +260,49 @@ RSpec.describe DiscourseAi::AdminDashboard::AdminDashboardFacts do
)
end
+ it "reports landing topics from included categories only" do
+ unselected_category = Fabricate(:category)
+ private_category = Fabricate(:private_category, group: Fabricate(:group))
+ selected_topic = Fabricate(:topic, title: "Selected landing topic")
+ unselected_topic =
+ Fabricate(:topic, category: unselected_category, title: "Unselected landing topic")
+ private_topic = Fabricate(:topic, category: private_category, title: "Private landing topic")
+ SiteSetting.ai_admin_dashboard_highlights_category_scope = "include"
+ SiteSetting.ai_admin_dashboard_highlights_categories = selected_topic.category_id.to_s
+
+ Fabricate.times(
+ 50,
+ :browser_pageview_event,
+ topic_id: selected_topic.id,
+ normalized_referrer: "example.com",
+ created_at: 1.day.ago,
+ )
+ Fabricate.times(
+ 55,
+ :browser_pageview_event,
+ topic_id: unselected_topic.id,
+ normalized_referrer: "example.com",
+ created_at: 1.day.ago,
+ )
+ Fabricate.times(
+ 60,
+ :browser_pageview_event,
+ topic_id: private_topic.id,
+ normalized_referrer: "example.com",
+ created_at: 1.day.ago,
+ )
+
+ landing_topic =
+ compute(start_date: 3.months.ago.to_date.to_s, end_date: Date.current.to_s)
+ .fetch(:signals)
+ .find { |signal| signal[:key] == :landing_topic }
+
+ expect(landing_topic).to include(
+ category: :acquisition,
+ headline: 'External visitors mostly landed on "Selected landing topic" (50 visits)',
+ )
+ end
+
it "skips the raw staff-ratio post scan for long date ranges" do
queries =
track_sql_queries do
@@ -161,6 +329,24 @@ RSpec.describe DiscourseAi::AdminDashboard::AdminDashboardFacts do
)
end
+ it "uses public categories for staff ratio by default" do
+ admin = Fabricate(:admin)
+ user = Fabricate(:user)
+ private_category = Fabricate(:private_category, group: Fabricate(:group))
+ private_topic = Fabricate(:topic, category: private_category)
+
+ Fabricate.times(6, :post, topic: private_topic, user: admin, created_at: 1.day.ago)
+ Fabricate.times(8, :post, topic: private_topic, user: user, created_at: 1.day.ago)
+ Fabricate.times(6, :private_message_post, user: admin, created_at: 1.day.ago)
+
+ staff_ratio =
+ compute(start_date: 3.months.ago.to_date.to_s, end_date: Date.current.to_s)
+ .fetch(:signals)
+ .find { |signal| signal[:key] == :staff_ratio }
+
+ expect(staff_ratio).to be_nil
+ end
+
it "reports a traffic spike WITHOUT a source when no referrer dominates" do
base = 29.days.ago.to_date
base.upto(Date.current) do |date|
diff --git a/plugins/discourse-ai/spec/lib/admin_dashboard/highlight_generator_spec.rb b/plugins/discourse-ai/spec/lib/admin_dashboard/highlight_generator_spec.rb
index 1bd4766986c..fdf4c172991 100644
--- a/plugins/discourse-ai/spec/lib/admin_dashboard/highlight_generator_spec.rb
+++ b/plugins/discourse-ai/spec/lib/admin_dashboard/highlight_generator_spec.rb
@@ -69,6 +69,34 @@ RSpec.describe DiscourseAi::AdminDashboard::HighlightGenerator do
expect(again).to eq("Cached highlight.")
end
+ it "uses category settings in the cache key" do
+ category = Fabricate(:category)
+ responses = [
+ { highlight: "Highlight before category ids." }.to_json,
+ { highlight: "Highlight after category ids." }.to_json,
+ ]
+
+ result =
+ DiscourseAi::Completions::Llm.with_prepared_responses(responses) do
+ described_class.generate(
+ start_date: "2026-05-01",
+ end_date: "2026-06-01",
+ period: "last_30_days",
+ )
+
+ SiteSetting.ai_admin_dashboard_highlights_category_scope = "include"
+ SiteSetting.ai_admin_dashboard_highlights_categories = category.id.to_s
+
+ described_class.generate(
+ start_date: "2026-05-01",
+ end_date: "2026-06-01",
+ period: "last_30_days",
+ )
+ end
+
+ expect(result).to eq("Highlight after category ids.")
+ end
+
it "returns an empty string when there are no metrics" do
allow(AdminDashboardHighlights).to receive(:build).and_return({ kpis: [] })