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.

fix(today): wait for first-load insight candidates (#124839)

Shy Alterd040242e0892
diff --git a/products/product_analytics/backend/facade/api.py b/products/product_analytics/backend/facade/api.py
index 41f919b017e7..3652707a47da 100644
--- a/products/product_analytics/backend/facade/api.py
+++ b/products/product_analytics/backend/facade/api.py
@@ -287,6 +287,7 @@ def get_insight_series(
short_id: str,
dashboard: InsightDashboardContext | None = None,
blocking: bool = False,
+ wait_until: float | None = None,
) -> InsightSeries | None:
insight = Insight.objects.filter(team__project_id=team.project_id, short_id=short_id, deleted=False).first()
if insight is None:
@@ -306,4 +307,5 @@ def get_insight_series(
query=insight.query or {},
dashboard=dashboard,
blocking=blocking,
+ wait_until=wait_until,
)
diff --git a/products/product_analytics/backend/insight_series.py b/products/product_analytics/backend/insight_series.py
index bdd0ca1a78ab..1a1ebe4afb8f 100644
--- a/products/product_analytics/backend/insight_series.py
+++ b/products/product_analytics/backend/insight_series.py
@@ -1,10 +1,12 @@
import json
from copy import deepcopy
from datetime import date
+from time import monotonic, sleep
from typing import Any
from pydantic import BaseModel
+from posthog.clickhouse.client.execute_async import get_query_status
from posthog.hogql_queries.apply_dashboard_filters import resolve_effective_dashboard_filters
from posthog.hogql_queries.query_runner import ExecutionMode
from posthog.hogql_queries.utils.result_series import (
@@ -52,6 +54,7 @@ def _run(
filters: dict[str, Any] | None,
variables: dict[str, Any] | None,
blocking: bool = False,
+ wait_until: float | None = None,
) -> dict[str, Any]:
from posthog.api.services.query import process_query_dict # noqa: PLC0415
@@ -60,10 +63,21 @@ def _run(
source,
dashboard_filters_json=filters,
variables_override_json=variables,
- execution_mode=BLOCKING_EXECUTION_MODE if blocking else EXECUTION_MODE,
+ execution_mode=BLOCKING_EXECUTION_MODE if blocking and wait_until is None else EXECUTION_MODE,
user=user,
)
- return response.model_dump() if isinstance(response, BaseModel) else response
+ result = response.model_dump() if isinstance(response, BaseModel) else response
+ if blocking and wait_until is not None and result.get("results") is None:
+ status = result.get("query_status") or {}
+ while status and not status.get("complete") and not status.get("error"):
+ remaining = wait_until - monotonic()
+ if remaining <= 0:
+ return result
+ sleep(min(0.25, remaining))
+ status = get_query_status(team_id=team.pk, query_id=status["id"]).model_dump()
+ if status.get("complete") and not status.get("error"):
+ return status["results"] if isinstance(status.get("results"), dict) else {}
+ return result
def _value_key(query: dict[str, Any], result: dict[str, Any], position: int) -> str:
@@ -128,13 +142,14 @@ def _sql_series(
filters: dict[str, Any],
variables: dict[str, Any] | None,
blocking: bool = False,
+ wait_until: float | None = None,
) -> InsightSeries | None:
settings = query.get("chartSettings") or {}
x_column = (settings.get("xAxis") or {}).get("column")
y_axes = [axis for axis in settings.get("yAxis") or [] if axis.get("column")]
if query.get("display") not in CHARTED_SQL_DISPLAYS or not x_column or not y_axes:
return None
- response = _run(team, user, query["source"], filters, variables, blocking)
+ response = _run(team, user, query["source"], filters, variables, blocking, wait_until)
if response.get("hasMore"):
return None
position = {column: index for index, column in enumerate(response.get("columns") or [])}
@@ -203,6 +218,7 @@ def insight_series(
query: dict[str, Any],
dashboard: InsightDashboardContext | None,
blocking: bool = False,
+ wait_until: float | None = None,
) -> InsightSeries | None:
dashboard_filters: dict[str, Any] = {}
variables: dict[str, Any] | None = None
@@ -223,6 +239,7 @@ def insight_series(
filters=filters,
variables=variables,
blocking=blocking,
+ wait_until=wait_until,
)
trends = source.get("trendsFilter") or {}
if source.get("kind") != "TrendsQuery" or trends.get("display") in UNCHARTED_DISPLAYS:
@@ -240,7 +257,7 @@ def insight_series(
dateRange={**kept, "date_from": LOOKBACK[interval], "excludeIncompletePeriods": True},
trendsFilter={**{k: v for k, v in trends.items() if k != "smoothingIntervals"}, "metricShowChange": False},
)
- response = _run(team, user, bounded, filters, variables, blocking)
+ response = _run(team, user, bounded, filters, variables, blocking, wait_until)
formula = bool(trends.get("formula") or trends.get("formulas") or trends.get("formulaNodes"))
several = len(source.get("series") or []) > 1
# `_run` executes the upgraded query, which stamps `kind` on series saved without one.
diff --git a/products/product_analytics/backend/tests/test_insight_series.py b/products/product_analytics/backend/tests/test_insight_series.py
index db977e17c275..552515131e61 100644
--- a/products/product_analytics/backend/tests/test_insight_series.py
+++ b/products/product_analytics/backend/tests/test_insight_series.py
@@ -1,4 +1,5 @@
from datetime import datetime, timedelta
+from types import SimpleNamespace
from typing import Any, cast
from posthog.test.base import BaseTest, ClickhouseTestMixin, _create_event, _create_person, flush_persons_and_events
@@ -9,6 +10,8 @@ from django.utils import timezone
from parameterized import parameterized
+from posthog.schema import QueryStatus
+
from posthog.constants import AvailableFeature
from posthog.hogql_queries.query_runner import ExecutionMode
from posthog.models import Team, User
@@ -23,6 +26,56 @@ from products.product_analytics.backend.insight_series import _visible
from products.product_analytics.backend.models.insight import Insight
+class TestBoundedInsightQuery(SimpleTestCase):
+ @parameterized.expand(
+ [
+ ("cached", True, False, False, 0.0, 0),
+ ("finishes", False, True, False, 0.0, 1),
+ ("fails", False, True, True, 0.0, 1),
+ ("still_running", False, False, False, 0.0, 3),
+ ("starts_near_deadline", False, False, False, 0.5, 1),
+ ("already_expired", False, False, False, 0.6, 0),
+ ]
+ )
+ def test_wait_returns_results_or_stops_at_the_shared_deadline(
+ self, _name: str, cached: bool, complete: bool, error: bool, start: float, polls: int
+ ) -> None:
+ clock = [start]
+ results = {"results": [_result("signed up")]}
+ pending = {"query_status": {"id": "query-1", "complete": False}}
+
+ def advance(seconds: float) -> None:
+ clock[0] += seconds
+
+ with (
+ patch("posthog.api.services.query.process_query_dict", return_value=results if cached else pending) as run,
+ patch.object(insight_series, "monotonic", side_effect=lambda: clock[0]),
+ patch.object(insight_series, "sleep", side_effect=advance),
+ patch.object(
+ insight_series,
+ "get_query_status",
+ return_value=QueryStatus(
+ id="query-1", team_id=1, complete=complete, error=error, results=results if complete else None
+ ),
+ ) as status,
+ ):
+ found = insight_series.insight_series(
+ cast(Team, SimpleNamespace(pk=1)),
+ cast(User, None),
+ short_id="abc",
+ name="Sign-ups",
+ query={"kind": "TrendsQuery", "series": [SIGNED_UP]},
+ dashboard=None,
+ blocking=True,
+ wait_until=0.6,
+ )
+
+ self.assertEqual(found is not None and bool(found.series), cached or (complete and not error))
+ self.assertEqual(status.call_count, polls)
+ self.assertLessEqual(clock[0], 0.6)
+ self.assertEqual(run.call_args.kwargs["execution_mode"], ExecutionMode.RECENT_CACHE_CALCULATE_ASYNC_IF_STALE)
+
+
class TestVisibleResults(SimpleTestCase):
@parameterized.expand(
[
diff --git a/products/today/backend/facade/enums.py b/products/today/backend/facade/enums.py
index 14e114bb2006..98b970a16dba 100644
--- a/products/today/backend/facade/enums.py
+++ b/products/today/backend/facade/enums.py
@@ -57,6 +57,7 @@ class HighlightMetricReason(LabeledStrEnum):
ROUTINE = "routine", "You open this often"
DASHBOARD = "dashboard", "On a dashboard you open often"
KEY_METRIC = "key_metric", "Project key metric"
+ POPULAR = "popular", "Opened often in this project"
class HighlightPinStatus(LabeledStrEnum):
diff --git a/products/today/backend/logic/highlights.py b/products/today/backend/logic/highlights.py
index a1e789f4795c..537297b920a7 100644
--- a/products/today/backend/logic/highlights.py
+++ b/products/today/backend/logic/highlights.py
@@ -24,7 +24,14 @@ from posthog.week_start_day import WeekStartDay
from ..facade import contracts
from ..facade.contracts import HighlightCandidate, HighlightFindings, HighlightSource
-from ..facade.enums import HighlightInterval, HighlightLabel, HighlightPinStatus, HighlightPriority, HighlightsStatus
+from ..facade.enums import (
+ HighlightInterval,
+ HighlightLabel,
+ HighlightMetricReason,
+ HighlightPinStatus,
+ HighlightPriority,
+ HighlightsStatus,
+)
from ..feature_flags import pulse_ranking
from ..models import TodayHighlights
from ..temporal.inputs import (
@@ -49,7 +56,7 @@ START_LOCK_SECONDS = 30
MAX_ITEMS = 6
MAX_PER_FAMILY = 2
MIN_SCORE = 0.2
-PULSE_TILES = 4
+PULSE_CANDIDATES = 6
URGENT_RISK_SCORE = 0.75
MINOR_OPPORTUNITY_SCORE = 0.4
@@ -217,7 +224,11 @@ def build_highlights(
offered.setdefault(metric.key, metric)
resolved = {**offered, **(pinned or {})}
chosen = [resolved[key] for key in pins if key in resolved]
- pulse = [*chosen, *(metric for key, metric in offered.items() if key not in pins)][:PULSE_TILES]
+ suggested = sorted(
+ (metric for key, metric in offered.items() if key not in pins),
+ key=lambda metric: metric.reason == HighlightMetricReason.POPULAR,
+ )
+ pulse = [*chosen, *suggested][:PULSE_CANDIDATES]
ranked = rank([replace(c, source=name) for name, result in found.items() for c in result.items])
return contracts.Highlights(
status=HighlightsStatus.READY,
diff --git a/products/today/backend/logic/today_highlights/routine.py b/products/today/backend/logic/today_highlights/routine.py
index eba2df707bab..9545e41133d6 100644
--- a/products/today/backend/logic/today_highlights/routine.py
+++ b/products/today/backend/logic/today_highlights/routine.py
@@ -1,7 +1,9 @@
-from collections.abc import Collection, Sequence
+from collections.abc import Collection, Iterator, Sequence
from datetime import date, timedelta
from functools import partial
+from time import monotonic
+from django.db.models import Count, Max
from django.utils import timezone
from posthog.dataclasses import frozen
@@ -36,7 +38,10 @@ ROUTINE_TILES = 2
FRECENCY_HALF_LIFE_DAYS = 14
FRECENCY_LOOKBACK_DAYS = VIEW_DAYS_KEPT
FRECENCY_CANDIDATES = 8
-FRECENCY_TILES = 4
+PULSE_CANDIDATES = 6
+BLOCKING_SECONDS = 20
+POPULAR_DAYS = 30
+POPULAR_CANDIDATES = 8
DASHBOARD_TILES_TRIED = 6
OPENED_DAYS_WINDOW = 14
MOVERS_SHOWN = 4
@@ -47,11 +52,12 @@ class ViewedItem:
kind: str
ref: str
days: frozenset[date]
+ popular: bool = False
def find(context: Context) -> Found:
pinned = context.pinned
- budget = FRECENCY_TILES - len(pinned)
+ budget = PULSE_CANDIDATES - len(pinned)
ranking = pulse_ranking(context.user, context.team)
if ranking in (FRECENCY_RANKING, RECENCY_RANKING):
return Found(pulse=tuple(_frecent_metrics(context, ranking, pinned, budget)))
@@ -109,17 +115,48 @@ def frecency(view_days: Collection[date], today: date) -> float:
def _frecent_metrics(
context: Context, ranking: str, excluded: Collection[str], budget: int
) -> list[contracts.HighlightMetric]:
+ if budget <= 0:
+ return []
+ deadline = monotonic() + BLOCKING_SECONDS
+ candidates: list[tuple[ViewedItem, contracts.HighlightMetric | None]] = []
+ available: set[str] = set()
+ for item in _candidates(context, _frecent_views(context, ranking)[:FRECENCY_CANDIDATES]):
+ shown = frozenset([*excluded, *available])
+ metric = context.guard(
+ f"frecent {item.kind} {item.ref}",
+ partial(_frecent_metric, context, item, shown, deadline, wait=False),
+ None,
+ )
+ candidates.append((item, metric))
+ if metric is not None:
+ available.add(metric.key)
+ if len(available) >= budget:
+ break
+
metrics: list[contracts.HighlightMetric] = []
- for item in _frecent_views(context, ranking)[:FRECENCY_CANDIDATES]:
+ for item, metric in candidates:
if len(metrics) >= budget:
break
shown = frozenset([*excluded, *(metric.key for metric in metrics)])
- metric = context.guard(f"frecent {item.kind} {item.ref}", partial(_frecent_metric, context, item, shown), None)
+ if metric is None or metric.key in shown:
+ metric = context.guard(
+ f"frecent {item.kind} {item.ref}", partial(_frecent_metric, context, item, shown, deadline), None
+ )
if metric is not None:
metrics.append(metric)
return metrics
+def _candidates(context: Context, own: list[ViewedItem]) -> Iterator[ViewedItem]:
+ yield from own
+ known = {item.ref for item in own if item.kind == "insight"}
+ popular: list[str] = context.guard(
+ "popular insights", partial(context.daily, "popular_insights", partial(_popular_refs, context)), []
+ )
+ for ref in [ref for ref in popular if ref not in known][:POPULAR_CANDIDATES]:
+ yield ViewedItem(kind="insight", ref=ref, days=frozenset(), popular=True)
+
+
def _frecent_views(context: Context, ranking: str) -> list[ViewedItem]:
views = FileSystemViewLog.objects.filter(
team=context.team,
@@ -140,9 +177,35 @@ def _frecent_views(context: Context, ranking: str) -> list[ViewedItem]:
return [item for score, _last, item in scored if score > 0]
-def _frecent_metric(context: Context, item: ViewedItem, shown: frozenset[str]) -> contracts.HighlightMetric | None:
+def _popular_refs(context: Context) -> list[str]:
+ rows = (
+ FileSystemViewLog.objects.filter(
+ team=context.team, type="insight", viewed_at__gte=timezone.now() - timedelta(days=POPULAR_DAYS)
+ )
+ .values("ref")
+ .annotate(viewers=Count("user_id", distinct=True), last_viewed=Max("viewed_at"))
+ .order_by("-viewers", "-last_viewed", "ref")[: POPULAR_CANDIDATES + FRECENCY_CANDIDATES]
+ )
+ return [row["ref"] for row in rows]
+
+
+def _frecent_metric(
+ context: Context, item: ViewedItem, shown: frozenset[str], deadline: float, *, wait: bool = True
+) -> contracts.HighlightMetric | None:
if item.kind == "insight":
- return None if f"insight:{item.ref}" in shown else insight_metric(context, item.ref, viewed=item)
+ if f"insight:{item.ref}" in shown:
+ return None
+ if item.popular:
+ return insight_metric(
+ context,
+ item.ref,
+ reason=HighlightMetricReason.POPULAR,
+ blocking=wait and monotonic() < deadline,
+ wait_until=deadline,
+ )
+ return insight_metric(
+ context, item.ref, viewed=item, blocking=wait and monotonic() < deadline, wait_until=deadline
+ )
if not item.ref.isdigit():
return None
dashboard = dashboard_insights(
@@ -155,7 +218,15 @@ def _frecent_metric(context: Context, item: ViewedItem, shown: frozenset[str]) -
continue
metric = context.guard(
f"dashboard {item.ref} tile {tile.insight_short_id}",
- partial(_tile_metric, context, dashboard, tile, viewed=item),
+ partial(
+ _tile_metric,
+ context,
+ dashboard,
+ tile,
+ viewed=item,
+ blocking=wait and monotonic() < deadline,
+ wait_until=deadline,
+ ),
None,
)
if metric is not None:
@@ -181,6 +252,7 @@ def _tile_metric(
*,
viewed: ViewedItem | None = None,
blocking: bool = False,
+ wait_until: float | None = None,
) -> contracts.HighlightMetric | None:
return insight_metric(
context,
@@ -193,6 +265,7 @@ def _tile_metric(
dashboard_name=dashboard.name,
dashboard_id=dashboard.dashboard_id,
blocking=blocking,
+ wait_until=wait_until,
)
@@ -205,10 +278,17 @@ def insight_metric(
url: str | None = None,
dashboard_name: str | None = None,
dashboard_id: int | None = None,
+ reason: HighlightMetricReason | None = None,
blocking: bool = False,
+ wait_until: float | None = None,
) -> contracts.HighlightMetric | None:
insight = get_insight_series(
- team=context.team, user=context.user, short_id=short_id, dashboard=dashboard, blocking=blocking
+ team=context.team,
+ user=context.user,
+ short_id=short_id,
+ dashboard=dashboard,
+ blocking=blocking,
+ wait_until=wait_until,
)
if insight is None:
return None
@@ -252,7 +332,7 @@ def insight_metric(
interval=HighlightInterval(period),
url=url or f"/insights/{short_id}",
value_format=value_format,
- reason=HighlightMetricReason.ROUTINE if dashboard is None else HighlightMetricReason.DASHBOARD,
+ reason=reason or (HighlightMetricReason.ROUTINE if dashboard is None else HighlightMetricReason.DASHBOARD),
dashboard_name=dashboard_name,
dashboard_id=dashboard_id,
opened_days=_opened_days(viewed, context.today) if viewed else None,
diff --git a/products/today/backend/presentation/serializers.py b/products/today/backend/presentation/serializers.py
index f6e0280d48a5..cf117f4e8843 100644
--- a/products/today/backend/presentation/serializers.py
+++ b/products/today/backend/presentation/serializers.py
@@ -367,7 +367,7 @@ class HighlightMetricSerializer(DataclassSerializer):
reason = serializers.ChoiceField(
choices=HighlightMetricReason.choices,
allow_null=True,
- help_text="Why the pulse suggests the metric: `routine` for an insight the person opens often, `dashboard` for a tile of a dashboard they open often, `key_metric` for a key metric of the project. Null for a number the person pinned, which `pins` lists, and for metrics computed before this field existed.",
+ help_text="Why the pulse suggests the metric: `routine` for an insight the person opens often, `dashboard` for a tile of a dashboard they open often, `key_metric` for a key metric of the project, `popular` for an insight that many people in the project open. Null for metrics computed before this field existed.",
)
dashboard_name = serializers.CharField(
allow_null=True,
diff --git a/products/today/backend/tests/test_highlight_insights.py b/products/today/backend/tests/test_highlight_insights.py
index c6e44e4eede8..1e48d152ca29 100644
--- a/products/today/backend/tests/test_highlight_insights.py
+++ b/products/today/backend/tests/test_highlight_insights.py
@@ -7,11 +7,12 @@ import time_machine
from posthog.test.base import BaseTest
from unittest.mock import patch
+from django.core.cache import cache
from django.test import SimpleTestCase
from parameterized import parameterized
-from posthog.models import FileSystemViewLog
+from posthog.models import FileSystemViewLog, User
from products.dashboards.backend.facade.api import DashboardInsights, DashboardInsightTile
from products.product_analytics.backend.facade.contracts import InsightDashboardContext, InsightSeries
@@ -253,6 +254,10 @@ class TestHomeTiles(SimpleTestCase):
class TestRoutineInsights(BaseTest):
+ def setUp(self) -> None:
+ super().setUp()
+ cache.clear()
+
@time_machine.travel("2026-10-13T12:00:00Z", tick=False)
def test_an_insight_opened_most_days_shows_its_last_week_in_the_pulse(self) -> None:
FileSystemViewLog.objects.create(
@@ -401,30 +406,106 @@ class TestRoutineInsights(BaseTest):
self.assertEqual([m.key for m in pulse], expected)
+ @parameterized.expand(
+ [
+ ("first_insight", "a", ["b", "c", "d"]),
+ ("dashboard_tile", "slow", ["a", "b", "c", "d"]),
+ ]
+ )
@time_machine.travel("2026-10-13T12:00:00Z", tick=False)
- def test_suggestions_skip_pinned_insights_and_leave_their_places_free(self) -> None:
- for ref in ("pinned", "first", "second", "third"):
+ def test_suggestions_skip_pins_and_keep_fast_results_when_an_earlier_query_uses_the_deadline(
+ self, _name: str, slow_ref: str, expected: list[str]
+ ) -> None:
+ for age, (kind, ref) in enumerate(
+ (("insight", "pinned"), ("insight", "a"), ("dashboard", "7"), ("insight", "c"), ("insight", "d")), start=1
+ ):
FileSystemViewLog.objects.create(
team=self.team,
user=self.user,
- type="insight",
+ type=kind,
ref=ref,
- view_days=[TODAY - timedelta(days=1)],
- viewed_at=datetime.combine(TODAY - timedelta(days=1), time(12), tzinfo=UTC),
+ view_days=[TODAY - timedelta(days=age)],
+ viewed_at=datetime.combine(TODAY - timedelta(days=age), time(12), tzinfo=UTC),
)
+ growth = DashboardInsights(
+ dashboard_id=7,
+ name="Growth",
+ filters={},
+ variables=None,
+ tiles=(
+ DashboardInsightTile(insight_short_id="slow", filters_overrides=None),
+ DashboardInsightTile(insight_short_id="b", filters_overrides=None),
+ ),
+ )
points = [(TODAY - timedelta(days=d), 2.0 if d <= 7 else 1.0) for d in range(14, 0, -1)]
- queried: list[str] = []
+ queried: list[tuple[str, bool, float | None, float]] = []
+ started: set[str] = set()
+ clock = [0.0]
- def series(**kwargs: Any) -> InsightSeries:
- queried.append(kwargs["short_id"])
- return insight({"opened": points}, short_id=kwargs["short_id"], name=kwargs["short_id"])
+ def series(**kwargs: Any) -> InsightSeries | None:
+ ref = kwargs["short_id"]
+ queried.append((ref, kwargs["blocking"], kwargs["wait_until"], clock[0]))
+ if ref not in started:
+ started.add(ref)
+ return None
+ if ref == slow_ref and kwargs["blocking"]:
+ clock[0] = 30.0
+ if ref in ("slow", slow_ref):
+ return None
+ return insight({"opened": points}, short_id=ref, name=ref)
with (
- patch.object(routine, "pulse_ranking", return_value="frecency"),
+ patch.object(routine, "pulse_ranking", return_value="recency"),
+ patch.object(routine, "dashboard_insights", return_value=growth),
patch.object(routine, "get_insight_series", side_effect=series),
+ patch.object(routine, "monotonic", side_effect=lambda: clock[0]),
):
pulse = routine.find(
Context(self.team, self.user, TODAY, pinned=frozenset({"insight:pinned", "signup_event"}))
).pulse
- self.assertEqual((len(pulse), "pinned" in queried), (2, False))
+ self.assertEqual([metric.key for metric in pulse], [f"insight:{ref}" for ref in expected])
+ self.assertEqual({ref for ref, _, _, _ in queried}, {"a", "slow", "b", "c", "d"})
+ self.assertTrue(all(deadline == 20.0 for _, _, deadline, _ in queried))
+ self.assertTrue(any(blocking for _, blocking, _, _ in queried))
+ self.assertTrue(all(not blocking for _, blocking, _, at in queried if at >= 30.0))
+
+ @time_machine.travel("2026-10-13T12:00:00Z", tick=False)
+ def test_a_person_with_few_views_also_sees_the_insights_the_project_opens_most(self) -> None:
+ others = [User.objects.create_and_join(self.organization, f"viewer{i}@example.com", None) for i in range(2)]
+ for user, ref, age in (
+ (self.user, "mine", 1),
+ (others[0], "mine", 1),
+ (others[0], "shared", 1),
+ (others[1], "shared", 2),
+ (others[1], "once", 1),
+ (others[0], "stale", 40),
+ ):
+ FileSystemViewLog.objects.create(
+ team=self.team,
+ user=user,
+ type="insight",
+ ref=ref,
+ view_days=[TODAY - timedelta(days=age)],
+ viewed_at=datetime.combine(TODAY - timedelta(days=age), time(12), tzinfo=UTC),
+ )
+ points = [(TODAY - timedelta(days=d), 2.0 if d <= 7 else 1.0) for d in range(14, 0, -1)]
+
+ with (
+ patch.object(routine, "pulse_ranking", return_value="recency"),
+ patch.object(
+ routine,
+ "get_insight_series",
+ side_effect=lambda **kwargs: insight({"opened": points}, short_id=kwargs["short_id"], name="Opened"),
+ ),
+ ):
+ pulse = routine.find(Context(self.team, self.user, TODAY)).pulse
+
+ self.assertEqual(
+ [(m.key, m.reason, m.last_opened) for m in pulse],
+ [
+ ("insight:mine", "routine", TODAY - timedelta(days=1)),
+ ("insight:shared", "popular", None),
+ ("insight:once", "popular", None),
+ ],
+ )
diff --git a/products/today/backend/tests/test_highlights.py b/products/today/backend/tests/test_highlights.py
index 8d5e2925beb0..f6fece3544f1 100644
--- a/products/today/backend/tests/test_highlights.py
+++ b/products/today/backend/tests/test_highlights.py
@@ -30,6 +30,7 @@ from products.today.backend.facade.contracts import (
from products.today.backend.facade.enums import (
HighlightInterval,
HighlightLabel,
+ HighlightMetricReason,
HighlightPriority,
HighlightsStatus,
HighlightUnit,
@@ -135,7 +136,7 @@ class TestHighlightRanking(SimpleTestCase):
class TestBuildHighlights(SimpleTestCase):
- def test_the_pulse_follows_the_source_order_and_the_items_follow_priority(self) -> None:
+ def test_the_pulse_follows_the_source_order_with_popular_tiles_last_and_the_items_follow_priority(self) -> None:
sources = (
HighlightSource(name="key_metrics", find=lambda _c: HighlightFindings(), pulse_order=2),
HighlightSource(name="routine", find=lambda _c: HighlightFindings(), pulse_order=1),
@@ -144,7 +145,9 @@ class TestBuildHighlights(SimpleTestCase):
)
found = {
"key_metrics": HighlightFindings(pulse=(metric("k1"), metric("k2"), metric("k3"))),
- "routine": HighlightFindings(pulse=(metric("r1"), metric("r2"))),
+ "routine": HighlightFindings(
+ pulse=(metric("r1"), replace(metric("p1"), reason=HighlightMetricReason.POPULAR), metric("r2"))
+ ),
"experiments": HighlightFindings(
items=(replace(candidate("win", "experiments", 0.9), label=HighlightLabel.OPPORTUNITY),)
),
@@ -161,7 +164,7 @@ class TestBuildHighlights(SimpleTestCase):
built.refresh_at,
),
(
- ["r1", "r2", "k1", "k2"],
+ ["r1", "r2", "k1", "k2", "k3", "p1"],
[("alert", "alerts", HighlightPriority.P2), ("win", "experiments", HighlightPriority.P3)],
DAY,
datetime(2026, 10, 14, tzinfo=ZoneInfo("Europe/Prague")),
diff --git a/products/today/frontend/generated/api.schemas.ts b/products/today/frontend/generated/api.schemas.ts
index 0e33722c4c35..76bd8aa5798e 100644
--- a/products/today/frontend/generated/api.schemas.ts
+++ b/products/today/frontend/generated/api.schemas.ts
@@ -96,6 +96,7 @@ export interface HighlightValueFormatApi {
* * `routine` - You open this often
* * `dashboard` - On a dashboard you open often
* * `key_metric` - Project key metric
+ * * `popular` - Opened often in this project
*/
export type HighlightMetricReasonEnumApi =
(typeof HighlightMetricReasonEnumApi)[keyof typeof HighlightMetricReasonEnumApi]
@@ -104,6 +105,7 @@ export const HighlightMetricReasonEnumApi = {
Routine: 'routine',
Dashboard: 'dashboard',
KeyMetric: 'key_metric',
+ Popular: 'popular',
} as const
export interface HighlightMoverApi {
@@ -153,11 +155,12 @@ export interface HighlightMetricApi {
value_format: HighlightValueFormatApi | null
/** The first day of the period each value in `series` covers, in the project's timezone. Same length and order as `series`. */
period_starts: string[]
- /** Why the pulse suggests the metric: `routine` for an insight the person opens often, `dashboard` for a tile of a dashboard they open often, `key_metric` for a key metric of the project. Null for a number the person pinned, which `pins` lists, and for metrics computed before this field existed.
+ /** Why the pulse suggests the metric: `routine` for an insight the person opens often, `dashboard` for a tile of a dashboard they open often, `key_metric` for a key metric of the project, `popular` for an insight that many people in the project open. Null for metrics computed before this field existed.
*
* * `routine` - You open this often
* * `dashboard` - On a dashboard you open often
- * * `key_metric` - Project key metric */
+ * * `key_metric` - Project key metric
+ * * `popular` - Opened often in this project */
reason: HighlightMetricReasonEnumApi | null
/**
* Name of the dashboard the tile comes from when `reason` is `dashboard`, else null.
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index a901e70be8e7..af46e53b4b66 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -58758,6 +58758,7 @@ export namespace Schemas {
* * `routine` - You open this often
* * `dashboard` - On a dashboard you open often
* * `key_metric` - Project key metric
+ * * `popular` - Opened often in this project
*/
export type HighlightMetricReasonEnum = typeof HighlightMetricReasonEnum[keyof typeof HighlightMetricReasonEnum];
@@ -58766,6 +58767,7 @@ export namespace Schemas {
Routine: 'routine',
Dashboard: 'dashboard',
KeyMetric: 'key_metric',
+ Popular: 'popular',
} as const;
export interface HighlightMover {
@@ -58815,11 +58817,12 @@ export namespace Schemas {
value_format: HighlightValueFormat | null;
/** The first day of the period each value in `series` covers, in the project's timezone. Same length and order as `series`. */
period_starts: string[];
- /** Why the pulse suggests the metric: `routine` for an insight the person opens often, `dashboard` for a tile of a dashboard they open often, `key_metric` for a key metric of the project. Null for a number the person pinned, which `pins` lists, and for metrics computed before this field existed.
+ /** Why the pulse suggests the metric: `routine` for an insight the person opens often, `dashboard` for a tile of a dashboard they open often, `key_metric` for a key metric of the project, `popular` for an insight that many people in the project open. Null for metrics computed before this field existed.
*
* * `routine` - You open this often
* * `dashboard` - On a dashboard you open often
- * * `key_metric` - Project key metric */
+ * * `key_metric` - Project key metric
+ * * `popular` - Opened often in this project */
reason: HighlightMetricReasonEnum | null;
/**
* Name of the dashboard the tile comes from when `reason` is `dashboard`, else null.