:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(signals): let research tag reports (#120548)
posthog[bot]936de4f0c03e
diff --git a/products/signals/backend/models.py b/products/signals/backend/models.pyindex 68519c750780..9443836d6905 100644--- a/products/signals/backend/models.py+++ b/products/signals/backend/models.py@@ -442,9 +442,8 @@ class SignalReport(UUIDModel):# leaving a stale question beside fresh prose. The inbox offers them above the "Ask AI" box.# `db_default` alongside `default` for the reason spelled out on `charts`.suggested_prompts = models.JSONField(default=list, db_default=[], blank=True)- # Free-form slug tags (lowercase kebab-case) for grouping and filtering reports. Writers go- # through `report_tags.set_report_tags`, which normalizes and caps them; report_tags.py holds- # the lifecycle rules. `db_default` for the reason spelled out on `charts`.+ # Free-form slug tags (lowercase kebab-case) for grouping and filtering reports. Writers+ # normalize and cap them through report_tags.py, which also holds the lifecycle rules. `db_default` for the reason spelled out on `charts`.tags = ArrayField(models.CharField(max_length=MAX_TAG_LENGTH), default=list, db_default=[], blank=True)created_at = models.DateTimeField(auto_now_add=True)diff --git a/products/signals/backend/report_generation/AGENTS.md b/products/signals/backend/report_generation/AGENTS.mdindex ae8b65aaf50d..a62fcd90a9ef 100644--- a/products/signals/backend/report_generation/AGENTS.md+++ b/products/signals/backend/report_generation/AGENTS.md@@ -131,6 +131,13 @@ A figure with no event or action query behind it, such as a database statistic,The caller activity passes `has_business_knowledge=True` when the team's business knowledge product is both feature-flagged on and has at least one READY source (via `products.business_knowledge.backend.logic.is_available_for_team`). When true, the research prompt includes a `## Business knowledge` block that instructs the agent to search the team's curated knowledge base via MCP tools.+### Tags++The presentation step can also return `tags`, the report's whole slug tag set. The prompt shows the report's current tags and the team's most-used report tags (`report_tags.team_tag_vocabulary`, a query that reads only the team's newest 500 reports), so a run reuses a tag before it invents a near duplicate.++- **A bad tag never fails the run.** `ReportPresentationOutput` coerces `tags` through `report_tags.coerce_report_tags`: it drops each tag that does not normalize and keeps the first `SignalReport.MAX_TAGS`, with a warning. A value that is not a list reads as omitted.+- **Each pass replaces the whole set, atomically with the prose.** The ready and pending-input transitions write `tags` with the title and summary. `None` (an omitted field, the no-repo branch, or an older workflow history) keeps the stored set.+### Fleet steeringThe caller activity also passes `steering_section`, resolved by `report_steering.load_research_steering`. `build_initial_research_prompt` renders it verbatim under the research protocol, and renders nothing when it is empty, so a team with no notes pays no tokens for a heading.diff --git a/products/signals/backend/report_generation/research.py b/products/signals/backend/report_generation/research.pyindex d5d45f3e916e..bc2bc512d5fe 100644--- a/products/signals/backend/report_generation/research.py+++ b/products/signals/backend/report_generation/research.py@@ -54,6 +54,7 @@ from products.signals.backend.report_metrics import (REPORT_METRIC_GOAL_FIELDS,ReportMetric,)+from products.signals.backend.report_tags import coerce_report_tagsfrom products.signals.backend.supersession import NO_IMPLEMENTATION_CONTEXT, ImplementationResearchContext# Deferred: importing temporal.types here runs the signals temporal package __init__, which@@ -240,6 +241,30 @@ Hard rules:),)+ tags: list[str] | None = Field(+ default=None,+ description=(+ "The report's whole tag set: lowercase kebab-case slugs that group this report with related "+ "reports, such as the product area, the feature, or the affected entity (`session-replay`, "+ "`billing`, `ingestion`). At most 10. The list replaces the report's current tags, so return "+ "the current tags that still fit, and an empty list to clear them. Do not repeat the title type "+ "(fix, feat), the title scope, the signal source (error tracking, GitHub issue, scout), or the "+ "priority: other fields carry those."+ ),+ )++ @field_validator("tags", mode="before")+ @classmethod+ def coerce_tags(cls, v: object) -> list[str] | None:+ # The presentation turn has no retry, so a bad tag must not fail it. Invalid tags are dropped+ # with a warning, and a value that is not a list keeps the report's current tags.+ if v is None:+ return None+ if not isinstance(v, list):+ logger.warning("presentation: dropped tags that are not a list (%s)", type(v).__name__)+ return None+ return coerce_report_tags(v)+@field_validator("layers", mode="before")@classmethoddef drop_a_plan_with_a_layer_that_does_not_validate(cls, v: object) -> object:@@ -555,6 +580,10 @@ class ReportResearchOutput(BaseModel):title: str = Field(description="Generated report title.")summary: str = Field(description="Generated factual report summary.")checks_summary: str | None = Field(default=None, description="Summary to apply only with reconciled checks.")+ tags: list[str] | None = Field(+ default=None,+ description="The report's whole tag set, replaced with title and summary. `None` keeps the stored set.",+ )charts: list[ReportChart] = Field(default_factory=list,description="Charts the summary illustrates itself with. The report's whole set — the caller "@@ -1307,6 +1336,15 @@ Respond with JSON matching this schema:</jsonschema>"""+def _render_tags_guidance(current_tags: Sequence[str], team_tags: Sequence[str]) -> str:+ return f"""## Tag the report++Return `tags`, the report's whole tag set. Keep a current tag when it still fits, and drop it when it does not.+Prefer a tag from the team's most-used tags when one fits. Add a new tag only when none of them covers the concept.+Current tags on this report: {json.dumps(list(current_tags))}+The team's most-used report tags, most-used first: {json.dumps(list(team_tags))}"""++def build_report_presentation_prompt(total_signals: int,*,@@ -1318,6 +1356,8 @@ def build_report_presentation_prompt(metrics_enabled: bool = False,suggestable_products: Sequence[SuggestedSourceProduct] = (),reviewer_selection_enabled: bool = False,+ current_tags: Sequence[str] = (),+ team_tags: Sequence[str] = (),) -> str:schema_dict = ReportPresentationOutput.model_json_schema()if not suggestable_products:@@ -1392,6 +1432,7 @@ Do not edit report reviewers or GitHub assignments through tools. Return your de)if suggestable_products:visual_sections.append(_render_source_suggestion_guidance(suggestable_products))+ visual_sections.append(_render_tags_guidance(current_tags, team_tags))visual_context = "".join(f"\n\n{section}" for section in visual_sections)return f"""Now write the final **report title and summary** based on your research across all {total_signals} signal(s).@@ -1618,6 +1659,8 @@ async def run_multi_turn_research(steering_section: str = "",implementation_context: ImplementationResearchContext = NO_IMPLEMENTATION_CONTEXT,suggestable_products: Sequence[SuggestedSourceProduct] = (),+ current_tags: Sequence[str] = (),+ team_tags: Sequence[str] = (),) -> ReportResearchOutput:"""Orchestrate a multi-turn sandbox session that investigates each signal individually.@@ -1801,6 +1844,8 @@ async def run_multi_turn_research(previous_checks=previous_checks,suggestable_products=suggestable_products,reviewer_selection_enabled=reviewer_selection_enabled,+ current_tags=current_tags,+ team_tags=team_tags,)presentation_result = await session.send_followup(presentation_prompt,@@ -1920,6 +1965,7 @@ async def run_multi_turn_research(charts=presentation_result.charts,metrics=presentation_result.metrics if metrics_enabled else [],layers=presentation_result.layers,+ tags=presentation_result.tags,research_task_id=str(session.task.id),verification_note=verification_note,checks=checks,diff --git a/products/signals/backend/report_tags.py b/products/signals/backend/report_tags.pyindex 797f7ac8cd03..98962d1c8a23 100644--- a/products/signals/backend/report_tags.py+++ b/products/signals/backend/report_tags.py@@ -5,17 +5,31 @@- A merge gives the survivor the union of its own tags and the sources' tags (`union_report_tags`).- A stack plan layer starts with the plan's tags.- A report never takes tags from its signals' `extra.tags`.+- Research writes the whole set with the title and summary on each pass (`coerce_report_tags`). An+ invalid tag from the agent is dropped with a warning, so it never fails the run.Tags live in the `SignalReport.tags` column, not in the shared `TaggedItem` system. Every readerfilters one column with no join, `Tag` rows would show report tags in the tag picker for otherobjects, and a `TaggedItem` delete writes an activity log row on each replace."""+from collections import Counterfrom collections.abc import Sequence+import structlog+from products.signals.backend.models import SignalReportfrom products.signals.backend.scout_harness.tags import slugify_tag+logger = structlog.get_logger(__name__)++# The research prompt shows this many of the team's most-used tags, so a run reuses a tag before it+# invents a near duplicate.+TEAM_TAG_VOCABULARY_SIZE = 30+# The vocabulary query reads at most this many of the team's newest reports, so its cost does not+# grow with the team's report history.+TEAM_TAG_VOCABULARY_SAMPLE = 500+def normalize_report_tags(tags: list[str]) -> list[str]:"""Deduped kebab-case slugs in first-seen order, by the same rules as scout finding tags.@@ -37,6 +51,46 @@ def normalize_report_tags(tags: list[str]) -> list[str]:return normalized+def coerce_report_tags(tags: Sequence[object]) -> list[str]:+ """`normalize_report_tags` for agent output, which must never fail a research run.++ Drops each tag that does not normalize and keeps the first `SignalReport.MAX_TAGS`, with a warning+ for each loss instead of a `ValueError`.+ """+ kept: list[str] = []+ # Counts by reason only, never the tag text: agent output can carry customer data or secrets.+ rejected: Counter[str] = Counter()+ for raw in tags:+ slug = slugify_tag(raw) if isinstance(raw, str) else ""+ if not isinstance(raw, str):+ rejected["not_a_string"] += 1+ elif not slug:+ rejected["empty_after_normalization"] += 1+ elif len(slug) > SignalReport.MAX_TAG_LENGTH:+ rejected["too_long"] += 1+ elif slug not in kept:+ kept.append(slug)+ if len(kept) > SignalReport.MAX_TAGS:+ rejected["over_the_cap"] = len(kept) - SignalReport.MAX_TAGS+ kept = kept[: SignalReport.MAX_TAGS]+ if rejected:+ logger.warning("report tags: dropped tags", rejected=dict(rejected))+ return kept+++def team_tag_vocabulary(team_id: int) -> list[str]:+ """The team's most-used report tags, most-used first, counted over its newest reports."""+ # Limit first and filter in Python. A SQL filter on `tags` or `status` before the limit can walk+ # the team's whole history on the `(team, created_at)` index when few reports match.+ rows = (+ SignalReport.objects.filter(team_id=team_id)+ .order_by("-created_at")+ .values_list("tags", "status")[:TEAM_TAG_VOCABULARY_SAMPLE]+ )+ counts = Counter(tag for tags, status in rows if status != SignalReport.Status.DELETED for tag in tags)+ return [tag for tag, _ in counts.most_common(TEAM_TAG_VOCABULARY_SIZE)]++def set_report_tags(report: SignalReport, tags: list[str] | None) -> bool:"""Replace the report's tags with `normalize_report_tags(tags)`.diff --git a/products/signals/backend/temporal/agentic/report.py b/products/signals/backend/temporal/agentic/report.pyindex 00bf2841b435..01026ef05f0e 100644--- a/products/signals/backend/temporal/agentic/report.py+++ b/products/signals/backend/temporal/agentic/report.py@@ -70,6 +70,7 @@ from products.signals.backend.report_generation.select_repo import RepoSelectionfrom products.signals.backend.report_lifecycle import report_status_filterfrom products.signals.backend.report_metrics import REPORT_METRIC_GOAL_FIELDS, ReportMetric, metric_batch_errorfrom products.signals.backend.report_steering import ReportSteering, load_research_steering+from products.signals.backend.report_tags import team_tag_vocabularyfrom products.signals.backend.reviewer_rules import ReviewerProposal, ReviewerRules, StaleReviewerProposalfrom products.signals.backend.source_suggestions import unused_suggestable_productsfrom products.signals.backend.supersession import research_implementation_context@@ -146,6 +147,10 @@ class RunAgenticReportOutput:# that chose not to chart apart from one that was never allowed to, which would otherwise read# as the agent's charting rate moving on every rollout step. `None` predates the field.charts_enabled: bool | None = None+ # The report's whole tag set, already normalized. The transition activity writes it with the+ # matching title and summary. `None` keeps the stored set, which is also what an older workflow+ # history replays as.+ tags: list[str] | None = None_ArtefactContentT = TypeVar("_ArtefactContentT", bound=BaseModel)@@ -242,6 +247,17 @@ async def _load_previous_research(team_id: int, report_id: str) -> ReportResearc)+@frozen+class _TagContext:+ current_tags: list[str]+ team_tags: list[str]+++def _load_tag_context(team_id: int, report_id: str) -> _TagContext:+ current = SignalReport.objects.filter(team_id=team_id, id=report_id).values_list("tags", flat=True).first()+ return _TagContext(current_tags=list(current or []), team_tags=team_tag_vocabulary(team_id))++def _parse_stored_charts(raw: object, report_id: str) -> list[ReportChart]:"""Best-effort parse of a report's stored `charts` JSON into `ReportChart`s, skipping bad rows."""if not isinstance(raw, list):@@ -1200,6 +1216,9 @@ async def run_agentic_report_activity(input: RunAgenticReportInput) -> RunAgentiawait database_sync_to_async(_capture_research_steering_attached, thread_sensitive=False)(team_id=input.team_id, report_id=input.report_id, steering=steering)+ tag_context = await database_sync_to_async(_load_tag_context, thread_sensitive=False)(+ input.team_id, input.report_id+ )# 3. Run the agentic research in the sandbox# The report's current PR, when it has one. It keeps the in-flight check from reading# the report's own draft as somebody else's work, and it is what the supersede turn asks@@ -1226,6 +1245,8 @@ async def run_agentic_report_activity(input: RunAgenticReportInput) -> RunAgentiagent_checks_enabled=agent_checks_enabled,steering_section=steering.section,suggestable_products=suggestable_products,+ current_tags=tag_context.current_tags,+ team_tags=tag_context.team_tags,)# 4. Persist artefacts, avoid partial data from failed runsawait _persist_agentic_report_artefacts(@@ -1277,6 +1298,7 @@ async def run_agentic_report_activity(input: RunAgenticReportInput) -> RunAgentilayers=[layer.model_dump(mode="json") for layer in result.layers],research_task_id=result.research_task_id,charts_enabled=True,+ tags=result.tags,)except SandboxRunFailed as error:logger.exception(diff --git a/products/signals/backend/temporal/summary.py b/products/signals/backend/temporal/summary.pyindex cafc660aaa3b..ff9b6dd33416 100644--- a/products/signals/backend/temporal/summary.py+++ b/products/signals/backend/temporal/summary.py@@ -60,6 +60,7 @@ from products.signals.backend.report_generation.research import ActionabilityChofrom products.signals.backend.report_generation.select_repo import RepoSelectionResultfrom products.signals.backend.report_metric_query_access import query_filter_shape_allows_readfrom products.signals.backend.report_metrics import REPORT_METRIC_GOAL_FIELDS+from products.signals.backend.report_tags import coerce_report_tagsfrom products.signals.backend.spend import (begin_report_spend,finish_report_spend,@@ -210,6 +211,9 @@ class ReportDecision:# prompts about the old report under the new one. `None` for the no-repo branch, which keeps# the prose and so keeps the prompts too.suggested_prompts: list[str] | None = field(default_factory=list)+ # The report's whole tag set to store with the title/summary, or `None` to keep the stored set.+ # `None` for the no-repo branch, which does no research.+ tags: list[str] | None = None# Work-log note to append with the transition. The no-repo branch records its blocker here# instead of in the title/summary.note: str | None = None@@ -644,6 +648,7 @@ class SignalReportSummaryWorkflow:layers=agentic_result.layers or [],research_task_id=agentic_result.research_task_id,charts_enabled=agentic_result.charts_enabled,+ tags=agentic_result.tags,pending_reason="agent_requested",)if decision.choice == ActionabilityChoice.NOT_ACTIONABLE:@@ -690,6 +695,7 @@ class SignalReportSummaryWorkflow:checks_task_id=decision.research_task_id,suggested_prompts=decision.suggested_prompts,charts_enabled=decision.charts_enabled,+ tags=decision.tags,pending_reason=decision.pending_reason,note=decision.note,keep_existing_content=decision.keep_existing_content,@@ -721,6 +727,7 @@ class SignalReportSummaryWorkflow:layers=decision.layers,suggested_prompts=decision.suggested_prompts,charts_enabled=decision.charts_enabled,+ tags=decision.tags,),start_to_close_timeout=timedelta(minutes=1),retry_policy=RetryPolicy(maximum_attempts=3),@@ -1064,6 +1071,9 @@ class MarkReportReadyInput:suggested_prompts: list[str] | None = None# The chart rollout state the research run saw, for the completion event. Not persisted.charts_enabled: bool | None = None+ # The report's whole tag set, written alongside title/summary. `None` keeps the stored set, which+ # is also what an older workflow history replays as.+ tags: list[str] | None = Nonedef _observation_metrics(report: SignalReport, metrics: list[dict]) -> list[dict]:@@ -1170,6 +1180,9 @@ async def mark_report_ready_activity(input: MarkReportReadyInput) -> bool:if input.suggested_prompts is not None:report.suggested_prompts = input.suggested_promptsupdated_fields = [*updated_fields, "suggested_prompts"]+ if input.tags is not None:+ report.tags = coerce_report_tags(input.tags)+ updated_fields = [*updated_fields, "tags"]report.save(update_fields=updated_fields)# Loop to re-research only if the signals that arrived during the run carried the report# to its next bucket. Same predicate as the grouping promotion gate, so a signal landing@@ -1422,6 +1435,8 @@ class MarkReportPendingInput:suggested_prompts: list[str] | None = None# See MarkReportReadyInput.charts_enabled — reported, never stored.charts_enabled: bool | None = None+ # See MarkReportReadyInput.tags — same transaction, same replay-safe default.+ tags: list[str] | None = None# Coarse cause of the transition ("repo_selection_required" / "agent_requested"), see# ReportDecision.pending_reason.pending_reason: str | None = None@@ -1457,6 +1472,9 @@ async def mark_report_pending_input_activity(input: MarkReportPendingInput) -> Nif input.suggested_prompts is not None:report.suggested_prompts = input.suggested_promptsupdated_fields = [*updated_fields, "suggested_prompts"]+ if input.tags is not None:+ report.tags = coerce_report_tags(input.tags)+ updated_fields = [*updated_fields, "tags"]# Read by capture_status_change_analytics's post_save receiver (same instance, same# transaction) — not a model field, so it never persists past this save.report._pending_reason = input.pending_reason # type: ignore[attr-defined]diff --git a/products/signals/backend/test/test_agentic_report_activity.py b/products/signals/backend/test/test_agentic_report_activity.pyindex 3d001e461cf3..0399cefcf541 100644--- a/products/signals/backend/test/test_agentic_report_activity.py+++ b/products/signals/backend/test/test_agentic_report_activity.py@@ -1291,6 +1291,54 @@ async def test_mark_report_ready_activity_applies_charts(ateam, name, charts, exassert stored == [][email protected]("pending", [False, True])+ "tags,expected",+ [+ (["Session Replay", "!!!"], ["session-replay"]),+ ([], []),+ (None, ["billing", "api"]),+ ],+)+async def test_report_transition_replaces_tags_with_the_prose(ateam, pending, tags, expected):+ report = await database_sync_to_async(SignalReport.objects.create)(+ team=ateam,+ status=SignalReport.Status.IN_PROGRESS,+ signal_count=2,+ total_weight=1.3,+ tags=["billing", "api"],+ )++ if pending:+ await mark_report_pending_input_activity(+ MarkReportPendingInput(+ team_id=ateam.id,+ report_id=str(report.id),+ title="Title",+ summary="Summary",+ reason="Requires human input",+ tags=tags,+ )+ )+ else:+ await mark_report_ready_activity(+ MarkReportReadyInput(+ team_id=ateam.id,+ report_id=str(report.id),+ title="Title",+ summary="Summary",+ processed_signal_count=2,+ tags=tags,+ )+ )++ stored = await database_sync_to_async(lambda: SignalReport.objects.get(id=report.id))()+ assert stored.title == "Title"+ assert stored.tags == expected++@pytest.mark.asyncio@pytest.mark.django_db@pytest.mark.parametrize(diff --git a/products/signals/backend/test/test_report_tags.py b/products/signals/backend/test/test_report_tags.pyindex e630ddee471f..a1c44ed4359e 100644--- a/products/signals/backend/test/test_report_tags.py+++ b/products/signals/backend/test/test_report_tags.py@@ -5,8 +5,15 @@ from django.test import SimpleTestCasefrom parameterized import parameterized+from posthog.models import Team+from products.signals.backend.models import SignalReport-from products.signals.backend.report_tags import set_report_tags, union_report_tags+from products.signals.backend.report_tags import (+ coerce_report_tags,+ set_report_tags,+ team_tag_vocabulary,+ union_report_tags,+)class TestSetReportTags(BaseTest):@@ -49,3 +56,29 @@ class TestUnionReportTags(SimpleTestCase):source = ["own-0", "src-a", "src-b", "src-c"]assert union_report_tags(survivor, source) == [*survivor, "src-a", "src-b"]+++class TestCoerceReportTags(SimpleTestCase):+ @parameterized.expand(+ [+ ("normalizes_and_dedupes", ["Cost Spike", "cost_spike", "web"], ["cost-spike", "web"]),+ ("drops_invalid_entries", ["!!!", "x" * (SignalReport.MAX_TAG_LENGTH + 1), 7, None, "api"], ["api"]),+ (+ "keeps_the_first_entries_up_to_the_cap",+ [f"tag-{i}" for i in range(SignalReport.MAX_TAGS + 2)],+ [f"tag-{i}" for i in range(SignalReport.MAX_TAGS)],+ ),+ ]+ )+ def test_coerce_report_tags_never_raises(self, _name: str, tags: list, expected: list[str]):+ assert coerce_report_tags(tags) == expected+++class TestTeamTagVocabulary(BaseTest):+ def test_counts_tags_on_live_reports_most_used_first(self):+ SignalReport.objects.create(team=self.team, tags=["billing", "api"])+ SignalReport.objects.create(team=self.team, tags=["api"])+ SignalReport.objects.create(team=self.team, tags=["web"], status=SignalReport.Status.DELETED)+ SignalReport.objects.create(team=Team.objects.create(organization=self.organization), tags=["web"])++ assert team_tag_vocabulary(self.team.id) == ["api", "billing"]diff --git a/products/signals/backend/test/test_research_prompt.py b/products/signals/backend/test/test_research_prompt.pyindex 4a11805665ff..5d16bf26ef5d 100644--- a/products/signals/backend/test/test_research_prompt.py+++ b/products/signals/backend/test/test_research_prompt.py@@ -663,6 +663,31 @@ class TestReportPresentationOutputCharts:assert parsed.summary == "Signups fell 60% over the week."+class TestReportPresentationOutputTags:+ @pytest.mark.parametrize(+ "tags,expected",+ [+ (["Session Replay", "session_replay", "!!!", 3], ["session-replay"]),+ ("billing", None),+ (None, None),+ ],+ )+ def test_invalid_tags_are_dropped_and_the_prose_survives(self, tags: object, expected: list[str] | None):+ parsed = ReportPresentationOutput.model_validate(+ {"title": "fix(checkout): Handle the timeout", "summary": "Checkout times out.", "tags": tags}+ )++ assert parsed.tags == expected+ assert parsed.summary == "Checkout times out."++ def test_prompt_offers_current_and_team_tags(self) -> None:+ prompt = build_report_presentation_prompt(1, current_tags=["billing"], team_tags=["api", "billing"])++ assert 'Current tags on this report: ["billing"]' in prompt+ assert 'most-used first: ["api", "billing"]' in prompt+ assert "Do not repeat the title type" in prompt++class TestReportPresentationOutputSourceSuggestion:@pytest.mark.parametrize("suggestion",