Skip to content

: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.

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.py
index 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 Any
from django.db.models import F, Q, QuerySet
import django_filters
+from rest_framework import serializers
from 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.py
index 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_progress
from 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_members
from products.replay_vision.backend.temporal.constants import VISION_SIGNALS_SOURCE_PRODUCT, VISION_SIGNALS_SOURCE_TYPE
from products.replay_vision.backend.temporal.scanners.monitor import MonitorVerdict
from 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.py
index 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.py
new file mode 100644
index 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 counts
diff --git a/products/replay_vision/backend/tests/test_api.py b/products/replay_vision/backend/tests/test_api.py
index 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 ReplayObservationFeedImpression
from products.replay_vision.backend.models.replay_observation_label import ReplayObservationLabel
+from products.replay_vision.backend.models.replay_observation_rank import ReplayObservationRank
from products.replay_vision.backend.models.replay_observation_usage import ReplayObservationUsage
from 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_CODES
from products.replay_vision.backend.queries import ESTIMATE_STALE_AFTER, SAVE_ESTIMATE_BUDGET
from products.replay_vision.backend.queries.scanner_candidate_query import SETTLE_INTERVAL
from 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_access
from products.replay_vision.backend.scanner_draft import DraftError, ScannerDraft
from products.replay_vision.backend.search import ObservationMatch
+from products.replay_vision.backend.semantic_clusters import cluster_status
from products.replay_vision.backend.semantic_space import SEMANTIC_DIMENSIONS, pack
from 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.json
index 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.json
index 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.json
index 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.json
index 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"