: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(replay-vision): count themes and groups and filter observations to them (#126999)
Tue Haulund6b67638450ce
diff --git a/products/replay_vision/backend/api/filters.py b/products/replay_vision/backend/api/filters.pyindex 0a050f22626a..63f03e2c00cf 100644--- a/products/replay_vision/backend/api/filters.py+++ b/products/replay_vision/backend/api/filters.py@@ -5,8 +5,19 @@ from typing import Anyfrom django.db.models import F, Q, QuerySetimport django_filters+from rest_framework import serializersfrom rest_framework.exceptions import ValidationError+from products.replay_vision.backend.search import parse_date_bound+++def validate_date_bound(value: str) -> str:+ try:+ parse_date_bound(value, None, end_of_range=False)+ except ValueError as e:+ raise serializers.ValidationError(str(e))+ return value+def split_csv(value: str) -> list[str]:"""Split a CSV string on commas, strip each entry, drop empties."""diff --git a/products/replay_vision/backend/api/observations.py b/products/replay_vision/backend/api/observations.pyindex a57a66f38df9..357051deddf7 100644--- a/products/replay_vision/backend/api/observations.py+++ b/products/replay_vision/backend/api/observations.py@@ -52,6 +52,7 @@ from products.replay_vision.backend.api.filters import (ordering_enum,split_csv,validate_csv_choices,+ validate_date_bound,)from products.replay_vision.backend.api.observation_progress import stream_observation_progressfrom products.replay_vision.backend.api.observation_stats import compute_observation_stats@@ -87,6 +88,7 @@ from products.replay_vision.backend.scanner_access import (accessible_observations,can_read_targeted_experiment,readable_observation_scanner_ids,+ readable_scanner_ids_in_scope,scanner_for_reading_observations,)from products.replay_vision.backend.scanning import RetryOutcome, retry_observation@@ -102,6 +104,7 @@ from products.replay_vision.backend.search import (search_observations,warm_query_vectors,)+from products.replay_vision.backend.semantic_clusters import ClusterKind, cluster_membersfrom products.replay_vision.backend.temporal.constants import VISION_SIGNALS_SOURCE_PRODUCT, VISION_SIGNALS_SOURCE_TYPEfrom products.replay_vision.backend.temporal.scanners.monitor import MonitorVerdictfrom products.replay_vision.backend.temporal.types import ScannerResult, ScannerSnapshot@@ -793,6 +796,25 @@ class ReplayObservationFilter(django_filters.FilterSet):"failure, struggle, revenue). Pair it with `watch_group` and the feed's `categories`."),)+ theme = django_filters.UUIDFilter(+ method="_filter_theme",+ help_text=(+ "Only issue observations in this search theme, an `id` from the themes list. "+ "Pair it with the same `date_from` and `date_to` to list the observations the theme counted."+ ),+ )+ group = django_filters.UUIDFilter(+ method="_filter_group",+ help_text=(+ "Only issue observations in this group of near duplicates, an `id` from the groups list. "+ "Pair it with the same `date_from`, `date_to`, `include_routine` and `variant` to list the observations "+ "the group counted."+ ),+ )+ include_routine = django_filters.BooleanFilter(+ method="_filter_include_routine",+ help_text="With `group`, also list the group's routine observations, as the groups list does with the same flag.",+ )date_from = django_filters.CharFilter(method="_filter_date_from",help_text=(@@ -843,9 +865,13 @@ class ReplayObservationFilter(django_filters.FilterSet):return [OpenApiParameter(name,- # Numeric filters must not surface as strings, or the generated clients type them+ # Numeric and boolean filters must not surface as strings, or the generated clients type them# differently here than on the list endpoint drf-spectacular discovers on its own.- float if isinstance(field, django_filters.NumberFilter) else str,+ float+ if isinstance(field, django_filters.NumberFilter)+ else bool+ if isinstance(field, django_filters.BooleanFilter)+ else str,OpenApiParameter.QUERY,required=False,description=str(field.extra.get("help_text", "")),@@ -908,6 +934,27 @@ class ReplayObservationFilter(django_filters.FilterSet):q |= Q(scanner_result__model_output__tags_freeform__contains=[tag])return queryset.filter(q)+ def _filter_theme(+ self, queryset: QuerySet[ReplayObservation], _name: str, value: uuid.UUID+ ) -> QuerySet[ReplayObservation]:+ if self._team is None:+ return queryset.none()+ return cluster_members(queryset, self._team.id, ClusterKind.THEME, value)++ def _filter_group(+ self, queryset: QuerySet[ReplayObservation], _name: str, value: uuid.UUID+ ) -> QuerySet[ReplayObservation]:+ include_routine = self.form.cleaned_data.get("include_routine") is True+ if self._team is None:+ return queryset.none()+ return cluster_members(queryset, self._team.id, ClusterKind.GROUP, value, include_routine=include_routine)++ def _filter_include_routine(+ self, queryset: QuerySet[ReplayObservation], _name: str, _value: bool | None+ ) -> QuerySet[ReplayObservation]:+ # Read by `_filter_group`; on its own it narrows nothing.+ return queryset+def _filter_watch_group(self, queryset: QuerySet[ReplayObservation], _name: str, value: uuid.UUID) -> QuerySet[ReplayObservation]:@@ -1540,14 +1587,6 @@ class ReplayObservationViewSet(return Response(ReplayObservationLabelSerializer(label).data)-def _validate_date_bound(value: str) -> str:- try:- parse_date_bound(value, None, end_of_range=False)- except ValueError as e:- raise serializers.ValidationError(str(e))- return value--class ObservationSearchQuerySerializer(serializers.Serializer):q = serializers.CharField(max_length=2000,@@ -1596,10 +1635,10 @@ class ObservationSearchQuerySerializer(serializers.Serializer):)def validate_date_from(self, value: str) -> str:- return _validate_date_bound(value)+ return validate_date_bound(value)def validate_date_to(self, value: str) -> str:- return _validate_date_bound(value)+ return validate_date_bound(value)def validate_verdict(self, value: str) -> str:# Same contract as the list endpoint's verdict filter: an unknown verdict is a 400, not a silent empty result.@@ -1742,7 +1781,7 @@ class SessionReplayObservationViewSet(ReplayObservationViewSet):params.is_valid(raise_exception=True)validated = params.validated_data- scanner_ids = self._searchable_scanner_ids(validated.get("scanner_id"))+ scanner_ids = readable_scanner_ids_in_scope(self.user_access_control, self.team_id, validated.get("scanner_id"))if not scanner_ids:return self._search_response([])# Gate before the embedding call so an opted-out org gets an actionable 400, not an opaque failure.@@ -1796,7 +1835,9 @@ class SessionReplayObservationViewSet(ReplayObservationViewSet):embedding consumer named from recent issue observations. Reads only, with no side effect."""params = SearchSuggestionsQuerySerializer(data=request.query_params)params.is_valid(raise_exception=True)- scanner_ids = self._searchable_scanner_ids(params.validated_data.get("scanner_id"))+ scanner_ids = readable_scanner_ids_in_scope(+ self.user_access_control, self.team_id, params.validated_data.get("scanner_id")+ )queries = theme_suggestions(self.team_id, scanner_ids, now())return Response(SearchSuggestionsResponseSerializer({"queries": queries}).data)@@ -1812,7 +1853,9 @@ class SessionReplayObservationViewSet(ReplayObservationViewSet):It embeds text, so it is a POST rather than part of the read."""params = SearchSuggestionsQuerySerializer(data=request.data)params.is_valid(raise_exception=True)- scanner_ids = self._searchable_scanner_ids(params.validated_data.get("scanner_id"))+ scanner_ids = readable_scanner_ids_in_scope(+ self.user_access_control, self.team_id, params.validated_data.get("scanner_id")+ )# The phrases derive from recordings, so they reach the embedding service only with AI data processing on.if is_ai_data_processing_approved(self.team.id):warm_query_vectors(self.team, theme_suggestions(self.team_id, scanner_ids, now()))@@ -1826,22 +1869,6 @@ class SessionReplayObservationViewSet(ReplayObservationViewSet):)return Response(serializer.data)- def _searchable_scanner_ids(self, scanner_id: uuid.UUID | None) -> list[str]:- # Observations expose recording-derived output, so searching them requires session_recording read.- if not self.user_access_control.check_access_level_for_resource("session_recording", required_level="viewer"):- raise PermissionDenied("Searching replay observations requires session_recording read access.")- if scanner_id is not None:- scanner = scanner_for_reading_observations(self.team_id, scanner_id)- # Not-found doubles as no-access so the response never leaks the scanner or its experiment.- if (- scanner is None- or not self.user_access_control.check_access_level_for_object(scanner, "viewer")- or not can_read_targeted_experiment(self.user_access_control, self.team_id, scanner)- ):- raise NotFound("Scanner not found.")- return [str(scanner.id)]- return [str(sid) for sid in readable_observation_scanner_ids(self.user_access_control, self.team_id)]-@extend_schema(exclude=True)@action(detail=True, methods=["GET"], url_path="progress", renderer_classes=[ServerSentEventRenderer])def progress(self, request: Request, **kwargs: Any) -> HttpResponseBase:diff --git a/products/replay_vision/backend/scanner_access.py b/products/replay_vision/backend/scanner_access.pyindex a269aad60aab..59d1fe5036dd 100644--- a/products/replay_vision/backend/scanner_access.py+++ b/products/replay_vision/backend/scanner_access.py@@ -266,3 +266,21 @@ def scanner_for_recording_derived_read(if not can_read_targeted_experiment(viewset.user_access_control, viewset.team_id, scanner):raise NotFound()return scanner+++def readable_scanner_ids_in_scope(access: UserAccessControl, team_id: int, scanner_id: uuid.UUID | None) -> list[str]:+ """The one scanner asked for, or every scanner the caller may read observations of."""+ # Observations expose recording-derived output, so reading them across scanners requires session_recording read.+ if not access.check_access_level_for_resource("session_recording", required_level="viewer"):+ raise PermissionDenied("Reading replay observations requires session_recording read access.")+ if scanner_id is not None:+ scanner = scanner_for_reading_observations(team_id, scanner_id)+ # Not-found doubles as no-access so the response never leaks the scanner or its experiment.+ if (+ scanner is None+ or not access.check_access_level_for_object(scanner, "viewer")+ or not can_read_targeted_experiment(access, team_id, scanner)+ ):+ raise NotFound("Scanner not found.")+ return [str(scanner.id)]+ return [str(sid) for sid in readable_observation_scanner_ids(access, team_id)]diff --git a/products/replay_vision/backend/semantic_clusters.py b/products/replay_vision/backend/semantic_clusters.pynew file mode 100644index 000000000000..bde9b161c659--- /dev/null+++ b/products/replay_vision/backend/semantic_clusters.py@@ -0,0 +1,385 @@+"""Search themes and feed groups over a time window, for the themes and groups endpoints.++Every count comes live from the rank rows, which carry each ranked observation's group, theme, category, person+and experiment. Variants and examples join the observations of the clusters on the page only.+"""++import uuid+from datetime import datetime, timedelta+from typing import Any, cast++from django.db import models+from django.db.models import CharField, Count, Exists, F, Max, Min, OuterRef, Q, QuerySet, Value, Window+from django.db.models.fields.json import KeyTextTransform+from django.db.models.functions import Coalesce, RowNumber++from posthog.dataclasses import frozen++from products.access_control.backend.facade.user_access_control import UserAccessControl+from products.replay_vision.backend.experiment_variants import UNATTRIBUTED_VARIANT+from products.replay_vision.backend.highlight_builds import ISSUE_CODES+from products.replay_vision.backend.models.replay_observation import ReplayObservation+from products.replay_vision.backend.models.replay_observation_rank import ReplayObservationRank+from products.replay_vision.backend.models.replay_scanner_semantics import (+ ReplayScannerFeedGroup,+ ReplayScannerSearchTheme,+)+from products.replay_vision.backend.observation_formatting import summarize_observation+from products.replay_vision.backend.scanner_access import readable_experiment_ids+from products.replay_vision.backend.watch_rank import current_ranks++EXAMPLES_PER_CLUSTER = 3++# A cluster with no member before this is still forming, and one with none in twice this long is dormant.+STATUS_WEEK = timedelta(days=7)+# Last week's members below this share of the week before's mean the problem is fading.+FADING_SHARE = 0.5+++class ClusterKind(models.TextChoices):+ THEME = "theme"+ GROUP = "group"+++class ClusterOrder(models.TextChoices):+ PEOPLE = "people"+ OBSERVATIONS = "observations"+ GROWTH = "growth"+ RECENT = "recent"+++class ClusterStatus(models.TextChoices):+ EMERGING = "emerging"+ ACTIVE = "active"+ FADING = "fading"+ DORMANT = "dormant"+++_MEMBER_COLUMN = {ClusterKind.GROUP: "feed_group_id", ClusterKind.THEME: "search_theme_id"}+_CLUSTER_MODEL: dict[ClusterKind, type[ReplayScannerFeedGroup] | type[ReplayScannerSearchTheme]] = {+ ClusterKind.GROUP: ReplayScannerFeedGroup,+ ClusterKind.THEME: ReplayScannerSearchTheme,+}+++@frozen+class ClusterWindow:+ date_from: datetime+ date_to: datetime++ @property+ def previous_from(self) -> datetime:+ return self.date_from - (self.date_to - self.date_from)+++@frozen+class ClusterScope:+ include_routine: bool = False+ variants: tuple[str, ...] = ()+++@frozen+class VariantCount:+ key: str+ observation_count: int+ people_count: int+++@frozen+class ClusterSummary:+ id: uuid.UUID+ scanner_id: uuid.UUID+ scanner_name: str+ name: str | None+ status: ClusterStatus+ observation_count: int+ people_count: int+ previous_observation_count: int+ first_seen: datetime+ last_seen: datetime+ example_observation_ids: list[uuid.UUID]+ example_summary: str+ variants: list[VariantCount]+++@frozen+class ClusterPage:+ results: list[ClusterSummary]+ has_more: bool+++def cluster_status(*, last_week: int, week_before: int, has_older_member: bool) -> ClusterStatus:+ """From the counted members of the last two weeks and whether any came before last week."""+ if last_week + week_before == 0:+ return ClusterStatus.DORMANT+ if not has_older_member:+ return ClusterStatus.EMERGING+ if week_before > 0 and last_week < week_before * FADING_SHARE:+ return ClusterStatus.FADING+ return ClusterStatus.ACTIVE+++def summarize_clusters(+ *,+ kind: ClusterKind,+ team_id: int,+ access: UserAccessControl,+ scanner_ids: list[str],+ window: ClusterWindow,+ order: ClusterOrder,+ limit: int,+ offset: int,+ scope: ClusterScope,+ by_variant: bool,+ cluster_id: uuid.UUID | None = None,+ now: datetime,+) -> ClusterPage:+ """One page of clusters with members in the window, counted over the rows the caller may read."""+ if not scanner_ids:+ return ClusterPage(results=[], has_more=False)+ column = _MEMBER_COLUMN[kind]+ rows = _readable_ranks(kind, team_id, access, scanner_ids, scope)+ # A pruned cluster's members keep its id, so they are left out before ranking rather than leaving a short page.+ live = _CLUSTER_MODEL[kind].objects.for_team(team_id).filter(scanner_id__in=scanner_ids).values("id")+ # nosemgrep: semgrep.rules.security.orm-field-injection -- column comes from the fixed _MEMBER_COLUMN map, never from input+ rows = rows.filter(**{f"{column}__in": live})+ if cluster_id is not None:+ rows = rows.filter(**{column: cluster_id})+ # Only growth ranks on the window before, so the other orders read the window alone.+ since = window.previous_from if order == ClusterOrder.GROWTH else window.date_from+ in_window = Q(created_at__gte=window.date_from)+ ranked = (+ rows.filter(created_at__gte=since, created_at__lt=window.date_to)+ .values(cluster=F(column))+ .annotate(+ window_count=Count("pk", filter=in_window),+ previous_count=Count("pk", filter=~in_window),+ people=Count("person_key", filter=in_window, distinct=True),+ first_seen=Min("created_at", filter=in_window),+ last_seen=Max("created_at", filter=in_window),+ )+ .filter(window_count__gt=0)+ .annotate(growth=F("window_count") - F("previous_count"))+ )+ ordering = {+ ClusterOrder.PEOPLE: ("-people", "-window_count", "cluster"),+ ClusterOrder.OBSERVATIONS: ("-window_count", "-people", "cluster"),+ ClusterOrder.GROWTH: ("-growth", "-window_count", "cluster"),+ ClusterOrder.RECENT: ("-last_seen", "-window_count", "cluster"),+ }[order]+ page = list(ranked.order_by(*ordering)[offset : offset + limit + 1])+ has_more = len(page) > limit+ page = page[:limit]+ if not page:+ return ClusterPage(results=[], has_more=False)++ cluster_ids = [row["cluster"] for row in page]+ clusters = {+ cluster["id"]: cluster+ for cluster in _CLUSTER_MODEL[kind]+ .objects.for_team(team_id)+ .filter(id__in=cluster_ids)+ .values(+ "id",+ "scanner_id",+ *(["name"] if kind == ClusterKind.THEME else []),+ scanner_name=F("scanner__name"),+ )+ }+ # nosemgrep: semgrep.rules.security.orm-field-injection -- column comes from the fixed _MEMBER_COLUMN map, never from input+ members = rows.filter(**{f"{column}__in": cluster_ids})+ activity = _activity(kind, team_id, cluster_ids, members, column, now)+ previous = (+ {row["cluster"]: row["previous_count"] for row in page}+ if order == ClusterOrder.GROWTH+ else _counts(members.filter(created_at__gte=window.previous_from, created_at__lt=window.date_from), column)+ )+ window_members = members.filter(created_at__gte=window.date_from, created_at__lt=window.date_to)+ examples = _examples(team_id, window_members, column)+ unnameable = _themes_with_unreadable_members(team_id, cluster_ids, access) if kind == ClusterKind.THEME else set()+ variants = _variant_counts(window_members, column) if by_variant else {}++ results = []+ for row in page:+ cluster = clusters.get(row["cluster"])+ cluster_activity = activity.get(row["cluster"])+ if cluster is None or cluster_activity is None:+ continue+ example_ids, example_summary = examples.get(row["cluster"], ([], ""))+ results.append(+ ClusterSummary(+ id=row["cluster"],+ scanner_id=cluster["scanner_id"],+ scanner_name=cluster["scanner_name"] or "",+ name=None if row["cluster"] in unnameable else cluster.get("name") or None,+ status=cluster_status(**cluster_activity),+ observation_count=row["window_count"],+ people_count=row["people"],+ previous_observation_count=previous.get(row["cluster"], 0),+ first_seen=row["first_seen"],+ last_seen=row["last_seen"],+ example_observation_ids=example_ids,+ example_summary=example_summary,+ variants=variants.get(row["cluster"], []),+ )+ )+ return ClusterPage(results=results, has_more=has_more)+++def cluster_members(+ queryset: QuerySet[ReplayObservation],+ team_id: int,+ kind: ClusterKind,+ cluster_id: uuid.UUID,+ *,+ include_routine: bool = False,+) -> QuerySet[ReplayObservation]:+ """The observations a cluster counts, in the same scope as its summary."""+ ranks = current_ranks(team_id).filter(**{_MEMBER_COLUMN[kind]: cluster_id})+ if not include_routine:+ ranks = ranks.filter(category__in=ISSUE_CODES)+ return queryset.filter(id__in=ranks.values("observation_id"))+++def cluster_scanner_id(kind: ClusterKind, team_id: int, cluster_id: uuid.UUID) -> uuid.UUID | None:+ """The scanner the cluster belongs to, or None when the team has no such cluster."""+ return (+ _CLUSTER_MODEL[kind]+ .objects.for_team(team_id)+ .filter(id=cluster_id)+ .values_list("scanner_id", flat=True)+ .first()+ )+++def _readable_ranks(+ kind: ClusterKind, team_id: int, access: UserAccessControl, scanner_ids: list[str], scope: ClusterScope+) -> QuerySet[ReplayObservationRank]:+ column = _MEMBER_COLUMN[kind]+ # Members scanned for an experiment the caller can't open stay out of every count.+ rows = current_ranks(team_id).filter(+ scanner_id__in=scanner_ids,+ experiment_id__in={0, *readable_experiment_ids(access, team_id)},+ **{f"{column}__isnull": False},+ )+ if not scope.include_routine:+ rows = rows.filter(category__in=ISSUE_CODES)+ if scope.variants:+ # Joined through the rank rows, so the variant is read only for rows already in scope.+ rows = cast(+ QuerySet[ReplayObservationRank],+ rows.alias(variant=_variant_key("observation__scanner_result")).filter(variant__in=scope.variants),+ )+ return rows+++def _themes_with_unreadable_members(+ team_id: int, theme_ids: list[uuid.UUID], access: UserAccessControl+) -> set[uuid.UUID]:+ """Themes whose name may come from members the caller can't read, since naming samples every member."""+ rows = (+ ReplayObservationRank.objects.for_team(team_id)+ .filter(search_theme_id__in=theme_ids)+ .exclude(experiment_id__in={0, *readable_experiment_ids(access, team_id)})+ .values_list("search_theme_id", flat=True)+ .distinct()+ )+ return {theme_id for theme_id in rows if theme_id is not None}+++def _variant_key(result_field: str) -> Coalesce:+ # `->>` reads a missing key and a JSON null alike as SQL NULL, so both land in the unattributed bucket.+ return Coalesce(+ KeyTextTransform("experiment_variant", result_field), Value(UNATTRIBUTED_VARIANT), output_field=CharField()+ )+++def _counts(members: QuerySet[ReplayObservationRank], column: str) -> dict[uuid.UUID, int]:+ return {row["cluster"]: row["n"] for row in members.values(cluster=F(column)).annotate(n=Count("pk"))}+++def _activity(+ kind: ClusterKind,+ team_id: int,+ cluster_ids: list[uuid.UUID],+ members: QuerySet[ReplayObservationRank],+ column: str,+ now: datetime,+) -> dict[uuid.UUID, dict[str, Any]]:+ """Each cluster's counted members over the last two weeks, and whether any came before last week."""+ week_ago = now - STATUS_WEEK+ weeks: dict[uuid.UUID, tuple[int, int]] = {+ row["cluster"]: (row["last_week"], row["week_before"])+ for row in members.filter(created_at__gte=now - 2 * STATUS_WEEK)+ .values(cluster=F(column))+ .annotate(+ last_week=Count("pk", filter=Q(created_at__gte=week_ago)),+ week_before=Count("pk", filter=Q(created_at__lt=week_ago)),+ )+ }+ # An existence check stops at the first older member, so a long-lived cluster costs no more than a new one.+ older = (+ _CLUSTER_MODEL[kind]+ .objects.for_team(team_id)+ .annotate(+ has_older_member=Exists(+ # nosemgrep: semgrep.rules.security.orm-field-injection -- column comes from the fixed _MEMBER_COLUMN map, never from input+ members.filter(**{column: OuterRef("id")}, created_at__lt=week_ago)+ )+ )+ )+ return {+ cluster_id: {+ "last_week": weeks.get(cluster_id, (0, 0))[0],+ "week_before": weeks.get(cluster_id, (0, 0))[1],+ "has_older_member": has_older_member,+ }+ for cluster_id, has_older_member in older.filter(id__in=cluster_ids).values_list("id", "has_older_member")+ }+++def _examples(+ team_id: int, members: QuerySet[ReplayObservationRank], column: str+) -> dict[uuid.UUID, tuple[list[uuid.UUID], str]]:+ """Each cluster's highest-scoring members, and the best one's summary as the fallback label."""+ best = list(+ members.annotate(+ example_cluster=F(column),+ example_rank=Window(+ RowNumber(), partition_by=[F(column)], order_by=[F("contrast").desc(), F("observation_id").desc()]+ ),+ )+ .filter(example_rank__lte=EXAMPLES_PER_CLUSTER)+ .order_by("example_cluster", "example_rank")+ .values_list("example_cluster", "observation_id")+ )+ observations = {+ observation.id: observation+ for observation in ReplayObservation.objects.filter(+ team_id=team_id, id__in=[observation_id for _, observation_id in best]+ ).only("id", "status", "scanner_result", "scanner_snapshot", "error_reason")+ }+ examples: dict[uuid.UUID, tuple[list[uuid.UUID], str]] = {}+ for cluster, observation_id in best:+ observation = observations.get(observation_id)+ if observation is None:+ continue+ ids, summary = examples.get(cluster, ([], ""))+ examples[cluster] = ([*ids, observation_id], summary or summarize_observation(observation))+ return examples+++def _variant_counts(members: QuerySet[ReplayObservationRank], column: str) -> dict[uuid.UUID, list[VariantCount]]:+ rows: Any = (+ members.values(variant_cluster=F(column), variant=_variant_key("observation__scanner_result"))+ .annotate(observation_count=Count("pk"), people_count=Count("person_key", distinct=True))+ .order_by("variant_cluster", "-observation_count", "variant")+ )+ counts: dict[uuid.UUID, list[VariantCount]] = {}+ for row in rows:+ counts.setdefault(row["variant_cluster"], []).append(+ VariantCount(+ key=row["variant"], observation_count=row["observation_count"], people_count=row["people_count"]+ )+ )+ return countsdiff --git a/products/replay_vision/backend/tests/test_api.py b/products/replay_vision/backend/tests/test_api.pyindex 2f94753aab7f..b62e580a65c9 100644--- a/products/replay_vision/backend/tests/test_api.py+++ b/products/replay_vision/backend/tests/test_api.py@@ -52,6 +52,7 @@ from products.replay_vision.backend.models.replay_observation import ()from products.replay_vision.backend.models.replay_observation_feed_impression import ReplayObservationFeedImpressionfrom products.replay_vision.backend.models.replay_observation_label import ReplayObservationLabel+from products.replay_vision.backend.models.replay_observation_rank import ReplayObservationRankfrom products.replay_vision.backend.models.replay_observation_usage import ReplayObservationUsagefrom products.replay_vision.backend.models.replay_scanner import (ReplayScanner,@@ -61,7 +62,11 @@ from products.replay_vision.backend.models.replay_scanner import (ScannerType,)from products.replay_vision.backend.models.replay_scanner_backfill import ReplayScannerBackfill-from products.replay_vision.backend.models.replay_scanner_semantics import ReplayScannerSearchTheme+from products.replay_vision.backend.models.replay_scanner_semantics import (+ ReplayScannerFeedGroup,+ ReplayScannerSearchTheme,+)+from products.replay_vision.backend.observation_ranks import CATEGORY_CODESfrom products.replay_vision.backend.queries import ESTIMATE_STALE_AFTER, SAVE_ESTIMATE_BUDGETfrom products.replay_vision.backend.queries.scanner_candidate_query import SETTLE_INTERVALfrom products.replay_vision.backend.queries.scanner_volume_estimate import estimate_scanner_session_volume@@ -69,6 +74,7 @@ from products.replay_vision.backend.quota import BillingPeriod, _current_period_from products.replay_vision.backend.scanner_access import recording_viewer_accessfrom products.replay_vision.backend.scanner_draft import DraftError, ScannerDraftfrom products.replay_vision.backend.search import ObservationMatch+from products.replay_vision.backend.semantic_clusters import cluster_statusfrom products.replay_vision.backend.semantic_space import SEMANTIC_DIMENSIONS, packfrom products.replay_vision.backend.temporal.constants import (APPLY_SCANNER_EXECUTION_TIMEOUT,@@ -5873,3 +5879,122 @@ class TestScannerActivityLogging(_VisionAPITestCase):def test_every_machine_owned_field_is_excluded(self) -> None:# A machine-written column that misses the registry turns every sweep into an audit row.self.assertEqual(set(ReplayScanner._MACHINE_OWNED_FIELDS) - set(replay_scanner_machine_fields), set())+++class TestClusterMembers(_VisionAPITestCase):+ def setUp(self) -> None:+ super().setUp()+ self.checkout = self._create_scanner(name="checkout")+ self.hidden = self._create_scanner(name="hidden")+ now = timezone.now()+ self.big, self.growing, self.secret = (uuid.uuid4() for _ in range(3))+ # Themes get their own ids, so a theme id sent to the groups endpoint finds nothing.+ self.theme_of = {cluster: uuid.uuid4() for cluster in (self.big, self.growing, self.secret)}+ for cluster, scanner, age_days in [+ (self.big, self.checkout, 30),+ (self.growing, self.checkout, 3),+ (self.secret, self.hidden, 3),+ ]:+ ReplayScannerSearchTheme.objects.for_team(self.team.id).create(+ id=self.theme_of[cluster],+ team=self.team,+ scanner=scanner,+ vector_sum=b"",+ name="coupon rejected" if cluster == self.big else "",+ last_member_at=now,+ )+ ReplayScannerFeedGroup.objects.for_team(self.team.id).create(+ id=cluster, team=self.team, scanner=scanner, vector_sum=b"", last_member_at=now+ )+ ReplayScannerSearchTheme.objects.for_team(self.team.id).filter(id=self.theme_of[cluster]).update(+ created_at=now - timedelta(days=age_days)+ )+ ReplayScannerFeedGroup.objects.for_team(self.team.id).filter(id=cluster).update(+ created_at=now - timedelta(days=age_days)+ )+ for session, scanner, cluster, person, age_days, category, variant, experiment in [+ # Two people in the window, one of them twice, plus one member in the window before it.+ ("big-1", self.checkout, self.big, 1, 1, "failure", "test", 0),+ ("big-2", self.checkout, self.big, 1, 2, "failure", "test", 0),+ ("big-3", self.checkout, self.big, 2, 3, "failure", None, 0),+ ("big-prev", self.checkout, self.big, 3, 40, "failure", "control", 0),+ ("big-routine", self.checkout, self.big, 4, 1, "routine", "control", 0),+ # Scanned for an experiment nobody here can open.+ ("big-restricted", self.checkout, self.big, 5, 1, "failure", "test", 999_999),+ ("growing-1", self.checkout, self.growing, 6, 1, "struggle", None, 0),+ ("growing-2", self.checkout, self.growing, 7, 2, "struggle", None, 0),+ ("growing-3", self.checkout, self.growing, 8, 3, "struggle", None, 0),+ ("secret-1", self.hidden, self.secret, 9, 1, "failure", None, 0),+ ]:+ created_at = now - timedelta(days=age_days)+ row = ReplayObservation.objects.create(+ scanner=scanner,+ session_id=session,+ scanner_snapshot={+ **_snapshot_for(scanner),+ **({"experiment_targeting": {"experiment_id": experiment}} if experiment else {}),+ },+ triggered_by=ObservationTrigger.SCHEDULE,+ status=ObservationStatus.SUCCEEDED,+ completed_at=created_at,+ scanner_result={"experiment_variant": variant} if variant else {},+ )+ ReplayObservation.objects.filter(id=row.id).update(created_at=created_at)+ ReplayObservationRank.objects.for_team(self.team.id).create(+ observation=row,+ team=self.team,+ scanner=scanner,+ created_at=created_at,+ anchor_version=ANCHOR_VERSION,+ contrast=0.3,+ category=CATEGORY_CODES[category],+ feed_group_id=cluster,+ search_theme_id=self.theme_of[cluster],+ person_key=person,+ experiment_id=experiment,+ )+ self.organization.available_product_features = [+ {"key": AvailableFeature.ACCESS_CONTROL, "name": AvailableFeature.ACCESS_CONTROL}+ ]+ self.organization.save()+ AccessControl.objects.create(+ team=self.team, resource="replay_scanner", resource_id=str(self.hidden.id), access_level="none"+ )++ @parameterized.expand(+ [+ ("theme", {"theme": "big"}, {"big-1", "big-2", "big-3"}),+ ("group", {"group": "big"}, {"big-1", "big-2", "big-3"}),+ (+ "group_with_routine",+ {"group": "big", "include_routine": "true"},+ {"big-1", "big-2", "big-3", "big-routine"},+ ),+ ]+ )+ def test_observation_list_filters_to_the_members_a_cluster_counts(+ self, _name: str, params: dict[str, str], expected: set[str]+ ) -> None:+ big = {"theme": self.theme_of[self.big], "group": self.big}+ query = {key: str(big[key]) if value == "big" else value for key, value in params.items()}++ resp = self.client.get(self.observations_url(str(self.checkout.id)), {**query, "date_from": "-7d"})++ self.assertEqual(resp.status_code, 200)+ self.assertEqual({r["session_id"] for r in resp.json()["results"]}, expected)+++class TestClusterStatus(SimpleTestCase):+ @parameterized.expand(+ [+ ("dormant_with_no_member_in_two_weeks", 0, 0, True, "dormant"),+ ("emerging_with_no_member_before_last_week", 5, 0, False, "emerging"),+ ("fading_under_half_the_week_before", 2, 5, True, "fading"),+ ("active_at_half_the_week_before", 3, 6, True, "active"),+ ]+ )+ def test_status_from_member_activity(+ self, _name: str, last_week: int, week_before: int, has_older_member: bool, expected: str+ ) -> None:+ status = cluster_status(last_week=last_week, week_before=week_before, has_older_member=has_older_member)+ self.assertEqual(status, expected)diff --git a/products/replay_vision/frontend/generated/api.schemas.ts b/products/replay_vision/frontend/generated/api.schemas.tsindex d9b722f4992d..1f9869c0ad64 100644--- a/products/replay_vision/frontend/generated/api.schemas.ts+++ b/products/replay_vision/frontend/generated/api.schemas.ts@@ -3150,10 +3150,18 @@ export type VisionObservationsRetrieveParams = {* Only observations created at or before this time. Accepts ISO 8601, a relative date like `-1d`, or `now` for the current time; omit it to query through the current time. Date-only values include the whole day, interpreted in the project's timezone.*/date_to?: string+ /**+ * Only issue observations in this group of near duplicates, an `id` from the groups list. Pair it with the same `date_from`, `date_to`, `include_routine` and `variant` to list the observations the group counted.+ */+ group?: string+ /**+ * With `group`, also list the group's routine observations, as the groups list does with the same flag.+ */+ include_routine?: boolean/*** When true, return only observations that have a shared label (thumbs up or down); when false, only unlabeled observations.*/- labeled?: string+ labeled?: boolean/*** Filter scorer observations to those scoring at or below this value. Rows with no numeric score (other scanner types, failed or in-flight runs) are excluded.*/@@ -3182,6 +3190,10 @@ export type VisionObservationsRetrieveParams = {* Filter classifier observations whose fixed or freeform tags include any of the given values (comma-separated). Matches if the tag appears in either `tags` or `tags_freeform`.*/tags?: string+ /**+ * Only issue observations in this search theme, an `id` from the themes list. Pair it with the same `date_from` and `date_to` to list the observations the theme counted.+ */+ theme?: string/*** Filter by trigger source (schedule, on_demand, retry, or backfill). Accepts a comma-separated list.*/@@ -3393,6 +3405,14 @@ export type VisionScannersObservationsListParams = {* Only observations created at or before this time. Accepts ISO 8601, a relative date like `-1d`, or `now` for the current time; omit it to query through the current time. Date-only values include the whole day, interpreted in the project's timezone.*/date_to?: string+ /**+ * Only issue observations in this group of near duplicates, an `id` from the groups list. Pair it with the same `date_from`, `date_to`, `include_routine` and `variant` to list the observations the group counted.+ */+ group?: string+ /**+ * With `group`, also list the group's routine observations, as the groups list does with the same flag.+ */+ include_routine?: boolean/*** When true, return only observations that have a shared label (thumbs up or down); when false, only unlabeled observations.*/@@ -3433,6 +3453,10 @@ export type VisionScannersObservationsListParams = {* Filter classifier observations whose fixed or freeform tags include any of the given values (comma-separated). Matches if the tag appears in either `tags` or `tags_freeform`.*/tags?: string+ /**+ * Only issue observations in this search theme, an `id` from the themes list. Pair it with the same `date_from` and `date_to` to list the observations the theme counted.+ */+ theme?: string/*** Filter by trigger source (schedule, on_demand, retry, or backfill). Accepts a comma-separated list.*/@@ -3468,10 +3492,18 @@ export type VisionScannersObservationsRetrieveParams = {* Only observations created at or before this time. Accepts ISO 8601, a relative date like `-1d`, or `now` for the current time; omit it to query through the current time. Date-only values include the whole day, interpreted in the project's timezone.*/date_to?: string+ /**+ * Only issue observations in this group of near duplicates, an `id` from the groups list. Pair it with the same `date_from`, `date_to`, `include_routine` and `variant` to list the observations the group counted.+ */+ group?: string+ /**+ * With `group`, also list the group's routine observations, as the groups list does with the same flag.+ */+ include_routine?: boolean/*** When true, return only observations that have a shared label (thumbs up or down); when false, only unlabeled observations.*/- labeled?: string+ labeled?: boolean/*** Filter scorer observations to those scoring at or below this value. Rows with no numeric score (other scanner types, failed or in-flight runs) are excluded.*/@@ -3500,6 +3532,10 @@ export type VisionScannersObservationsRetrieveParams = {* Filter classifier observations whose fixed or freeform tags include any of the given values (comma-separated). Matches if the tag appears in either `tags` or `tags_freeform`.*/tags?: string+ /**+ * Only issue observations in this search theme, an `id` from the themes list. Pair it with the same `date_from` and `date_to` to list the observations the theme counted.+ */+ theme?: string/*** Filter by trigger source (schedule, on_demand, retry, or backfill). Accepts a comma-separated list.*/@@ -3535,6 +3571,14 @@ export type VisionScannersObservationsSignalReportsListParams = {* Only observations created at or before this time. Accepts ISO 8601, a relative date like `-1d`, or `now` for the current time; omit it to query through the current time. Date-only values include the whole day, interpreted in the project's timezone.*/date_to?: string+ /**+ * Only issue observations in this group of near duplicates, an `id` from the groups list. Pair it with the same `date_from`, `date_to`, `include_routine` and `variant` to list the observations the group counted.+ */+ group?: string+ /**+ * With `group`, also list the group's routine observations, as the groups list does with the same flag.+ */+ include_routine?: boolean/*** When true, return only observations that have a shared label (thumbs up or down); when false, only unlabeled observations.*/@@ -3567,6 +3611,10 @@ export type VisionScannersObservationsSignalReportsListParams = {* Filter classifier observations whose fixed or freeform tags include any of the given values (comma-separated). Matches if the tag appears in either `tags` or `tags_freeform`.*/tags?: string+ /**+ * Only issue observations in this search theme, an `id` from the themes list. Pair it with the same `date_from` and `date_to` to list the observations the theme counted.+ */+ theme?: string/*** Filter by trigger source (schedule, on_demand, retry, or backfill). Accepts a comma-separated list.*/@@ -3626,10 +3674,18 @@ export type VisionScannersObservationsStatsRetrieveParams = {* Only observations created at or before this time. Accepts ISO 8601, a relative date like `-1d`, or `now` for the current time; omit it to query through the current time. Date-only values include the whole day, interpreted in the project's timezone.*/date_to?: string+ /**+ * Only issue observations in this group of near duplicates, an `id` from the groups list. Pair it with the same `date_from`, `date_to`, `include_routine` and `variant` to list the observations the group counted.+ */+ group?: string+ /**+ * With `group`, also list the group's routine observations, as the groups list does with the same flag.+ */+ include_routine?: boolean/*** When true, return only observations that have a shared label (thumbs up or down); when false, only unlabeled observations.*/- labeled?: string+ labeled?: boolean/*** Filter scorer observations to those scoring at or below this value. Rows with no numeric score (other scanner types, failed or in-flight runs) are excluded.*/@@ -3658,6 +3714,10 @@ export type VisionScannersObservationsStatsRetrieveParams = {* Filter classifier observations whose fixed or freeform tags include any of the given values (comma-separated). Matches if the tag appears in either `tags` or `tags_freeform`.*/tags?: string+ /**+ * Only issue observations in this search theme, an `id` from the themes list. Pair it with the same `date_from` and `date_to` to list the observations the theme counted.+ */+ theme?: string/*** Filter by trigger source (schedule, on_demand, retry, or backfill). Accepts a comma-separated list.*/diff --git a/products/replay_vision/frontend/observations/replayObservationLogic.ts b/products/replay_vision/frontend/observations/replayObservationLogic.tsindex c39db39a00a5..df9681b3b16d 100644--- a/products/replay_vision/frontend/observations/replayObservationLogic.ts+++ b/products/replay_vision/frontend/observations/replayObservationLogic.ts@@ -142,7 +142,7 @@ export function observationParentBreadcrumb(}/** Canonical link to an observation's detail page, carrying list filters so prev/next honors them. */-export function observationDetailUrl(id: string, filterParams: Record<string, string | number>): string {+export function observationDetailUrl(id: string, filterParams: Record<string, string | number | boolean>): string {return combineUrl(urls.replayVisionObservation(id), filterParams).url}diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.tsindex 5cb0250a1065..5b9e58a97eaf 100644--- a/services/mcp/src/api/generated.ts+++ b/services/mcp/src/api/generated.ts@@ -144155,10 +144155,18 @@ export namespace Schemas {* Only observations created at or before this time. Accepts ISO 8601, a relative date like `-1d`, or `now` for the current time; omit it to query through the current time. Date-only values include the whole day, interpreted in the project's timezone.*/date_to?: string;+ /**+ * Only issue observations in this group of near duplicates, an `id` from the groups list. Pair it with the same `date_from`, `date_to`, `include_routine` and `variant` to list the observations the group counted.+ */+ group?: string;+ /**+ * With `group`, also list the group's routine observations, as the groups list does with the same flag.+ */+ include_routine?: boolean;/*** When true, return only observations that have a shared label (thumbs up or down); when false, only unlabeled observations.*/- labeled?: string;+ labeled?: boolean;/*** Filter scorer observations to those scoring at or below this value. Rows with no numeric score (other scanner types, failed or in-flight runs) are excluded.*/@@ -144187,6 +144195,10 @@ export namespace Schemas {* Filter classifier observations whose fixed or freeform tags include any of the given values (comma-separated). Matches if the tag appears in either `tags` or `tags_freeform`.*/tags?: string;+ /**+ * Only issue observations in this search theme, an `id` from the themes list. Pair it with the same `date_from` and `date_to` to list the observations the theme counted.+ */+ theme?: string;/*** Filter by trigger source (schedule, on_demand, retry, or backfill). Accepts a comma-separated list.*/@@ -144397,6 +144409,14 @@ export namespace Schemas {* Only observations created at or before this time. Accepts ISO 8601, a relative date like `-1d`, or `now` for the current time; omit it to query through the current time. Date-only values include the whole day, interpreted in the project's timezone.*/date_to?: string;+ /**+ * Only issue observations in this group of near duplicates, an `id` from the groups list. Pair it with the same `date_from`, `date_to`, `include_routine` and `variant` to list the observations the group counted.+ */+ group?: string;+ /**+ * With `group`, also list the group's routine observations, as the groups list does with the same flag.+ */+ include_routine?: boolean;/*** When true, return only observations that have a shared label (thumbs up or down); when false, only unlabeled observations.*/@@ -144437,6 +144457,10 @@ export namespace Schemas {* Filter classifier observations whose fixed or freeform tags include any of the given values (comma-separated). Matches if the tag appears in either `tags` or `tags_freeform`.*/tags?: string;+ /**+ * Only issue observations in this search theme, an `id` from the themes list. Pair it with the same `date_from` and `date_to` to list the observations the theme counted.+ */+ theme?: string;/*** Filter by trigger source (schedule, on_demand, retry, or backfill). Accepts a comma-separated list.*/@@ -144472,10 +144496,18 @@ export namespace Schemas {* Only observations created at or before this time. Accepts ISO 8601, a relative date like `-1d`, or `now` for the current time; omit it to query through the current time. Date-only values include the whole day, interpreted in the project's timezone.*/date_to?: string;+ /**+ * Only issue observations in this group of near duplicates, an `id` from the groups list. Pair it with the same `date_from`, `date_to`, `include_routine` and `variant` to list the observations the group counted.+ */+ group?: string;+ /**+ * With `group`, also list the group's routine observations, as the groups list does with the same flag.+ */+ include_routine?: boolean;/*** When true, return only observations that have a shared label (thumbs up or down); when false, only unlabeled observations.*/- labeled?: string;+ labeled?: boolean;/*** Filter scorer observations to those scoring at or below this value. Rows with no numeric score (other scanner types, failed or in-flight runs) are excluded.*/@@ -144504,6 +144536,10 @@ export namespace Schemas {* Filter classifier observations whose fixed or freeform tags include any of the given values (comma-separated). Matches if the tag appears in either `tags` or `tags_freeform`.*/tags?: string;+ /**+ * Only issue observations in this search theme, an `id` from the themes list. Pair it with the same `date_from` and `date_to` to list the observations the theme counted.+ */+ theme?: string;/*** Filter by trigger source (schedule, on_demand, retry, or backfill). Accepts a comma-separated list.*/@@ -144539,6 +144575,14 @@ export namespace Schemas {* Only observations created at or before this time. Accepts ISO 8601, a relative date like `-1d`, or `now` for the current time; omit it to query through the current time. Date-only values include the whole day, interpreted in the project's timezone.*/date_to?: string;+ /**+ * Only issue observations in this group of near duplicates, an `id` from the groups list. Pair it with the same `date_from`, `date_to`, `include_routine` and `variant` to list the observations the group counted.+ */+ group?: string;+ /**+ * With `group`, also list the group's routine observations, as the groups list does with the same flag.+ */+ include_routine?: boolean;/*** When true, return only observations that have a shared label (thumbs up or down); when false, only unlabeled observations.*/@@ -144571,6 +144615,10 @@ export namespace Schemas {* Filter classifier observations whose fixed or freeform tags include any of the given values (comma-separated). Matches if the tag appears in either `tags` or `tags_freeform`.*/tags?: string;+ /**+ * Only issue observations in this search theme, an `id` from the themes list. Pair it with the same `date_from` and `date_to` to list the observations the theme counted.+ */+ theme?: string;/*** Filter by trigger source (schedule, on_demand, retry, or backfill). Accepts a comma-separated list.*/@@ -144630,10 +144678,18 @@ export namespace Schemas {* Only observations created at or before this time. Accepts ISO 8601, a relative date like `-1d`, or `now` for the current time; omit it to query through the current time. Date-only values include the whole day, interpreted in the project's timezone.*/date_to?: string;+ /**+ * Only issue observations in this group of near duplicates, an `id` from the groups list. Pair it with the same `date_from`, `date_to`, `include_routine` and `variant` to list the observations the group counted.+ */+ group?: string;+ /**+ * With `group`, also list the group's routine observations, as the groups list does with the same flag.+ */+ include_routine?: boolean;/*** When true, return only observations that have a shared label (thumbs up or down); when false, only unlabeled observations.*/- labeled?: string;+ labeled?: boolean;/*** Filter scorer observations to those scoring at or below this value. Rows with no numeric score (other scanner types, failed or in-flight runs) are excluded.*/@@ -144662,6 +144718,10 @@ export namespace Schemas {* Filter classifier observations whose fixed or freeform tags include any of the given values (comma-separated). Matches if the tag appears in either `tags` or `tags_freeform`.*/tags?: string;+ /**+ * Only issue observations in this search theme, an `id` from the themes list. Pair it with the same `date_from` and `date_to` to list the observations the theme counted.+ */+ theme?: string;/*** Filter by trigger source (schedule, on_demand, retry, or backfill). Accepts a comma-separated list.*/diff --git a/services/mcp/src/generated/replay_vision/api.ts b/services/mcp/src/generated/replay_vision/api.tsindex 80ff8c97ce7b..04192b52d86b 100644--- a/services/mcp/src/generated/replay_vision/api.ts+++ b/services/mcp/src/generated/replay_vision/api.ts@@ -458,9 +458,21 @@ export const VisionObservationsRetrieveQueryParams = () => zod.object({.describe("Only observations created at or before this time. Accepts ISO 8601, a relative date like `-1d`, or `now` for the current time; omit it to query through the current time. Date-only values include the whole day, interpreted in the project's timezone."),- labeled: zod+ group: zod.string().optional()+ .describe(+ 'Only issue observations in this group of near duplicates, an `id` from the groups list. Pair it with the same `date_from`, `date_to`, `include_routine` and `variant` to list the observations the group counted.'+ ),+ include_routine: zod+ .boolean()+ .optional()+ .describe(+ "With `group`, also list the group's routine observations, as the groups list does with the same flag."+ ),+ labeled: zod+ .boolean()+ .optional().describe('When true, return only observations that have a shared label (thumbs up or down); when false, only unlabeled observations.'),@@ -497,6 +509,12 @@ export const VisionObservationsRetrieveQueryParams = () => zod.object({.describe('Filter classifier observations whose fixed or freeform tags include any of the given values (comma-separated). Matches if the tag appears in either `tags` or `tags_freeform`.'),+ theme: zod+ .string()+ .optional()+ .describe(+ 'Only issue observations in this search theme, an `id` from the themes list. Pair it with the same `date_from` and `date_to` to list the observations the theme counted.'+ ),triggered_by: zod.string().optional()@@ -1550,6 +1568,18 @@ export const VisionScannersObservationsListQueryParams = () => zod.object({.describe("Only observations created at or before this time. Accepts ISO 8601, a relative date like `-1d`, or `now` for the current time; omit it to query through the current time. Date-only values include the whole day, interpreted in the project's timezone."),+ group: zod+ .string()+ .optional()+ .describe(+ 'Only issue observations in this group of near duplicates, an `id` from the groups list. Pair it with the same `date_from`, `date_to`, `include_routine` and `variant` to list the observations the group counted.'+ ),+ include_routine: zod+ .boolean()+ .optional()+ .describe(+ "With `group`, also list the group's routine observations, as the groups list does with the same flag."+ ),labeled: zod.boolean().optional()@@ -1591,6 +1621,12 @@ export const VisionScannersObservationsListQueryParams = () => zod.object({.describe('Filter classifier observations whose fixed or freeform tags include any of the given values (comma-separated). Matches if the tag appears in either `tags` or `tags_freeform`.'),+ theme: zod+ .string()+ .optional()+ .describe(+ 'Only issue observations in this search theme, an `id` from the themes list. Pair it with the same `date_from` and `date_to` to list the observations the theme counted.'+ ),triggered_by: zod.string().optional()@@ -1648,9 +1684,21 @@ export const VisionScannersObservationsRetrieveQueryParams = () => zod.object({.describe("Only observations created at or before this time. Accepts ISO 8601, a relative date like `-1d`, or `now` for the current time; omit it to query through the current time. Date-only values include the whole day, interpreted in the project's timezone."),- labeled: zod+ group: zod.string().optional()+ .describe(+ 'Only issue observations in this group of near duplicates, an `id` from the groups list. Pair it with the same `date_from`, `date_to`, `include_routine` and `variant` to list the observations the group counted.'+ ),+ include_routine: zod+ .boolean()+ .optional()+ .describe(+ "With `group`, also list the group's routine observations, as the groups list does with the same flag."+ ),+ labeled: zod+ .boolean()+ .optional().describe('When true, return only observations that have a shared label (thumbs up or down); when false, only unlabeled observations.'),@@ -1687,6 +1735,12 @@ export const VisionScannersObservationsRetrieveQueryParams = () => zod.object({.describe('Filter classifier observations whose fixed or freeform tags include any of the given values (comma-separated). Matches if the tag appears in either `tags` or `tags_freeform`.'),+ theme: zod+ .string()+ .optional()+ .describe(+ 'Only issue observations in this search theme, an `id` from the themes list. Pair it with the same `date_from` and `date_to` to list the observations the theme counted.'+ ),triggered_by: zod.string().optional()@@ -1743,9 +1797,21 @@ export const VisionScannersObservationsStatsRetrieveQueryParams = () => zod.obje.describe("Only observations created at or before this time. Accepts ISO 8601, a relative date like `-1d`, or `now` for the current time; omit it to query through the current time. Date-only values include the whole day, interpreted in the project's timezone."),- labeled: zod+ group: zod.string().optional()+ .describe(+ 'Only issue observations in this group of near duplicates, an `id` from the groups list. Pair it with the same `date_from`, `date_to`, `include_routine` and `variant` to list the observations the group counted.'+ ),+ include_routine: zod+ .boolean()+ .optional()+ .describe(+ "With `group`, also list the group's routine observations, as the groups list does with the same flag."+ ),+ labeled: zod+ .boolean()+ .optional().describe('When true, return only observations that have a shared label (thumbs up or down); when false, only unlabeled observations.'),@@ -1782,6 +1848,12 @@ export const VisionScannersObservationsStatsRetrieveQueryParams = () => zod.obje.describe('Filter classifier observations whose fixed or freeform tags include any of the given values (comma-separated). Matches if the tag appears in either `tags` or `tags_freeform`.'),+ theme: zod+ .string()+ .optional()+ .describe(+ 'Only issue observations in this search theme, an `id` from the themes list. Pair it with the same `date_from` and `date_to` to list the observations the theme counted.'+ ),triggered_by: zod.string().optional()diff --git a/services/mcp/src/tools/generated/replay_vision.ts b/services/mcp/src/tools/generated/replay_vision.tsindex b1097b942d64..e8c45c6953da 100644--- a/services/mcp/src/tools/generated/replay_vision.ts+++ b/services/mcp/src/tools/generated/replay_vision.ts@@ -380,6 +380,8 @@ const visionObservationsGet = (): ToolBase<backfill_id: params.backfill_id,date_from: params.date_from,date_to: params.date_to,+ group: params.group,+ include_routine: params.include_routine,labeled: params.labeled,max_score: params.max_score,min_score: params.min_score,@@ -388,6 +390,7 @@ const visionObservationsGet = (): ToolBase<session_id: params.session_id,status: params.status,tags: params.tags,+ theme: params.theme,triggered_by: params.triggered_by,variant: params.variant,verdict: params.verdict,@@ -1307,6 +1310,8 @@ const visionScannersObservationsGet = (): ToolBase<backfill_id: params.backfill_id,date_from: params.date_from,date_to: params.date_to,+ group: params.group,+ include_routine: params.include_routine,labeled: params.labeled,max_score: params.max_score,min_score: params.min_score,@@ -1315,6 +1320,7 @@ const visionScannersObservationsGet = (): ToolBase<session_id: params.session_id,status: params.status,tags: params.tags,+ theme: params.theme,triggered_by: params.triggered_by,variant: params.variant,verdict: params.verdict,@@ -1353,6 +1359,8 @@ const visionScannersObservationsList = (): ToolBase<backfill_id: params.backfill_id,date_from: params.date_from,date_to: params.date_to,+ group: params.group,+ include_routine: params.include_routine,labeled: params.labeled,limit: params.limit,max_score: params.max_score,@@ -1363,6 +1371,7 @@ const visionScannersObservationsList = (): ToolBase<session_id: params.session_id,status: params.status,tags: params.tags,+ theme: params.theme,triggered_by: params.triggered_by,variant: params.variant,verdict: params.verdict,@@ -1415,6 +1424,8 @@ const visionScannersObservationsStats = (): ToolBase<backfill_id: params.backfill_id,date_from: params.date_from,date_to: params.date_to,+ group: params.group,+ include_routine: params.include_routine,labeled: params.labeled,max_score: params.max_score,min_score: params.min_score,@@ -1423,6 +1434,7 @@ const visionScannersObservationsStats = (): ToolBase<session_id: params.session_id,status: params.status,tags: params.tags,+ theme: params.theme,triggered_by: params.triggered_by,variant: params.variant,verdict: params.verdict,diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-observations-get.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-observations-get.jsonindex 416fc963ce57..686d0ef329c2 100644--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-observations-get.json+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-observations-get.json@@ -13,13 +13,21 @@"description": "Only observations created at or before this time. Accepts ISO 8601, a relative date like `-1d`, or `now` for the current time; omit it to query through the current time. Date-only values include the whole day, interpreted in the project's timezone.","type": "string"},+ "group": {+ "description": "Only issue observations in this group of near duplicates, an `id` from the groups list. Pair it with the same `date_from`, `date_to`, `include_routine` and `variant` to list the observations the group counted.",+ "type": "string"+ },"id": {"description": "A UUID string identifying this replay observation.","type": "string"},+ "include_routine": {+ "description": "With `group`, also list the group's routine observations, as the groups list does with the same flag.",+ "type": "boolean"+ },"labeled": {"description": "When true, return only observations that have a shared label (thumbs up or down); when false, only unlabeled observations.",- "type": "string"+ "type": "boolean"},"max_score": {"description": "Filter scorer observations to those scoring at or below this value. Rows with no numeric score (other scanner types, failed or in-flight runs) are excluded.",@@ -49,6 +57,10 @@"description": "Filter classifier observations whose fixed or freeform tags include any of the given values (comma-separated). Matches if the tag appears in either `tags` or `tags_freeform`.","type": "string"},+ "theme": {+ "description": "Only issue observations in this search theme, an `id` from the themes list. Pair it with the same `date_from` and `date_to` to list the observations the theme counted.",+ "type": "string"+ },"triggered_by": {"description": "Filter by trigger source (schedule, on_demand, retry, or backfill). Accepts a comma-separated list.","type": "string"diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-observations-get.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-observations-get.jsonindex 9980e9a7310c..e8edb3215ba6 100644--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-observations-get.json+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-observations-get.json@@ -13,13 +13,21 @@"description": "Only observations created at or before this time. Accepts ISO 8601, a relative date like `-1d`, or `now` for the current time; omit it to query through the current time. Date-only values include the whole day, interpreted in the project's timezone.","type": "string"},+ "group": {+ "description": "Only issue observations in this group of near duplicates, an `id` from the groups list. Pair it with the same `date_from`, `date_to`, `include_routine` and `variant` to list the observations the group counted.",+ "type": "string"+ },"id": {"description": "A UUID string identifying this replay observation.","type": "string"},+ "include_routine": {+ "description": "With `group`, also list the group's routine observations, as the groups list does with the same flag.",+ "type": "boolean"+ },"labeled": {"description": "When true, return only observations that have a shared label (thumbs up or down); when false, only unlabeled observations.",- "type": "string"+ "type": "boolean"},"max_score": {"description": "Filter scorer observations to those scoring at or below this value. Rows with no numeric score (other scanner types, failed or in-flight runs) are excluded.",@@ -52,6 +60,10 @@"description": "Filter classifier observations whose fixed or freeform tags include any of the given values (comma-separated). Matches if the tag appears in either `tags` or `tags_freeform`.","type": "string"},+ "theme": {+ "description": "Only issue observations in this search theme, an `id` from the themes list. Pair it with the same `date_from` and `date_to` to list the observations the theme counted.",+ "type": "string"+ },"triggered_by": {"description": "Filter by trigger source (schedule, on_demand, retry, or backfill). Accepts a comma-separated list.","type": "string"diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-observations-list.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-observations-list.jsonindex ccfffbb2a6b0..40e7c1aaba85 100644--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-observations-list.json+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-observations-list.json@@ -13,6 +13,14 @@"description": "Only observations created at or before this time. Accepts ISO 8601, a relative date like `-1d`, or `now` for the current time; omit it to query through the current time. Date-only values include the whole day, interpreted in the project's timezone.","type": "string"},+ "group": {+ "description": "Only issue observations in this group of near duplicates, an `id` from the groups list. Pair it with the same `date_from`, `date_to`, `include_routine` and `variant` to list the observations the group counted.",+ "type": "string"+ },+ "include_routine": {+ "description": "With `group`, also list the group's routine observations, as the groups list does with the same flag.",+ "type": "boolean"+ },"labeled": {"description": "When true, return only observations that have a shared label (thumbs up or down); when false, only unlabeled observations.","type": "boolean"@@ -56,6 +64,10 @@"description": "Filter classifier observations whose fixed or freeform tags include any of the given values (comma-separated). Matches if the tag appears in either `tags` or `tags_freeform`.","type": "string"},+ "theme": {+ "description": "Only issue observations in this search theme, an `id` from the themes list. Pair it with the same `date_from` and `date_to` to list the observations the theme counted.",+ "type": "string"+ },"triggered_by": {"description": "Filter by trigger source (schedule, on_demand, retry, or backfill). Accepts a comma-separated list.","type": "string"diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-observations-stats.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-observations-stats.jsonindex cb2993a4d2fb..d71430a29ebe 100644--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-observations-stats.json+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-observations-stats.json@@ -13,9 +13,17 @@"description": "Only observations created at or before this time. Accepts ISO 8601, a relative date like `-1d`, or `now` for the current time; omit it to query through the current time. Date-only values include the whole day, interpreted in the project's timezone.","type": "string"},+ "group": {+ "description": "Only issue observations in this group of near duplicates, an `id` from the groups list. Pair it with the same `date_from`, `date_to`, `include_routine` and `variant` to list the observations the group counted.",+ "type": "string"+ },+ "include_routine": {+ "description": "With `group`, also list the group's routine observations, as the groups list does with the same flag.",+ "type": "boolean"+ },"labeled": {"description": "When true, return only observations that have a shared label (thumbs up or down); when false, only unlabeled observations.",- "type": "string"+ "type": "boolean"},"max_score": {"description": "Filter scorer observations to those scoring at or below this value. Rows with no numeric score (other scanner types, failed or in-flight runs) are excluded.",@@ -48,6 +56,10 @@"description": "Filter classifier observations whose fixed or freeform tags include any of the given values (comma-separated). Matches if the tag appears in either `tags` or `tags_freeform`.","type": "string"},+ "theme": {+ "description": "Only issue observations in this search theme, an `id` from the themes list. Pair it with the same `date_from` and `date_to` to list the observations the theme counted.",+ "type": "string"+ },"triggered_by": {"description": "Filter by trigger source (schedule, on_demand, retry, or backfill). Accepts a comma-separated list.","type": "string"