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(signals): keep a version history of activity summaries (#121355)

posthog[bot]9e9c942327be
diff --git a/.semgrep/rules/security/idor-team-scoped-models.yaml b/.semgrep/rules/security/idor-team-scoped-models.yaml
index 2ee314924565..bd0ad20faf4e 100644
--- a/.semgrep/rules/security/idor-team-scoped-models.yaml
+++ b/.semgrep/rules/security/idor-team-scoped-models.yaml
@@ -461,6 +461,7 @@ rules:
|TracingView
|UploadedMedia
|UserInterview
+ |UserActivitySummaryVersion
|UserInterviewTopic
|UserRepoPreference
|VisionAlertConfiguration
@@ -927,6 +928,7 @@ rules:
|TracingView
|UploadedMedia
|UserInterview
+ |UserActivitySummaryVersion
|UserInterviewTopic
|UserRepoPreference
|VisionAlertConfiguration
diff --git a/products/signals/backend/activity_summary/config.py b/products/signals/backend/activity_summary/config.py
index a8980c525423..0003aff3a618 100644
--- a/products/signals/backend/activity_summary/config.py
+++ b/products/signals/backend/activity_summary/config.py
@@ -14,7 +14,7 @@ import structlog
from posthog.dataclasses import frozen
-from products.signals.backend.activity_summary.logic import MIN_UNITS, MIN_UPDATE_INTERVAL
+from products.signals.backend.activity_summary.logic import MAX_VERSIONS, MIN_UNITS, MIN_UPDATE_INTERVAL
from products.signals.backend.activity_summary.render import DEFAULT_LIMITS, RenderLimits
from products.signals.backend.scout_harness.team_limits import read_flag_payload
@@ -37,6 +37,7 @@ class ActivitySummaryConfig:
max_concurrency: int = 4
min_units: int = MIN_UNITS
min_update_interval_hours: float = MIN_UPDATE_INTERVAL.total_seconds() / 3600
+ max_versions: int = MAX_VERSIONS
emit_embeddings: bool = True
capture_events: bool = True
limits: RenderLimits = DEFAULT_LIMITS
@@ -115,6 +116,7 @@ def parse_config(payload: Any) -> ActivitySummaryConfig:
min_update_interval_hours=_positive_number(
payload.get("min_update_interval_hours"), defaults.min_update_interval_hours
),
+ max_versions=_positive_int(payload.get("max_versions"), defaults.max_versions),
emit_embeddings=_bool(payload.get("emit_embeddings"), defaults.emit_embeddings),
capture_events=_bool(payload.get("capture_events"), defaults.capture_events),
limits=parse_limits(payload.get("limits")),
diff --git a/products/signals/backend/activity_summary/logic.py b/products/signals/backend/activity_summary/logic.py
index d9373fd40031..1dbc3bb8a868 100644
--- a/products/signals/backend/activity_summary/logic.py
+++ b/products/signals/backend/activity_summary/logic.py
@@ -5,6 +5,7 @@ import dataclasses
from enum import StrEnum
from typing import Any, Protocol
+from django.db import transaction
from django.db.models import Value
from django.db.models.functions import Coalesce
from django.utils import timezone
@@ -28,11 +29,13 @@ from products.signals.backend.activity_summary.summaries import (
gateway_client,
summarize,
)
-from products.signals.backend.models import UserActivitySummary
+from products.signals.backend.models import UserActivitySummary, UserActivitySummaryVersion
# Fewer rendered lines than this since the last update say too little to change the summary.
MIN_UNITS = 3
MIN_UPDATE_INTERVAL = datetime.timedelta(days=1)
+# The `UserActivitySummaryVersion` rows kept per summary. An update deletes the older ones.
+MAX_VERSIONS = 30
# A pair that skipped or failed waits this long, so it does not take the queue head on every tick.
RETRY_BACKOFF = datetime.timedelta(hours=6)
# The error prefixes of an update that raised before it stored a result, before and after the model call.
@@ -115,6 +118,45 @@ def _back_off(
)
+# The fields of a successful update that `UserActivitySummaryVersion` keeps.
+_VERSION_FIELDS = (
+ "summary",
+ "summary_text",
+ "generated_at",
+ "model",
+ "prompt_version",
+ "render_version",
+ "input_watermark",
+ "inputs_used",
+ "tokens_in",
+ "tokens_out",
+ "cost_usd",
+)
+
+
+def _store_version(team_id: int, user_id: int, fields: dict[str, Any], max_versions: int) -> None:
+ """Write a successful update to the summary row and append it as the next version, in one transaction."""
+ with transaction.atomic():
+ # The row lock orders concurrent updates of one pair, so each one takes the next version number.
+ row, _ = (
+ UserActivitySummary.objects.for_team(team_id)
+ .select_for_update()
+ .get_or_create(team_id=team_id, user_id=user_id, defaults={"status": UserActivitySummary.Status.OK})
+ )
+ for name, value in fields.items():
+ setattr(row, name, value)
+ row.version += 1
+ row.save()
+ versions = UserActivitySummaryVersion.objects.for_team(team_id)
+ versions.create(
+ team_id=team_id,
+ summary_row=row,
+ version=row.version,
+ **{name: fields[name] for name in _VERSION_FIELDS},
+ )
+ versions.filter(summary_row=row, version__lte=row.version - max_versions).delete()
+
+
def record_update_exception(team_id: int, user_id: int, error: BaseException) -> ActivitySummaryUpdate:
"""Store an update that raised as failed, keep the stored summary and watermark, and back the pair off.
@@ -175,6 +217,7 @@ def update_activity_summary(
min_update_interval: datetime.timedelta = MIN_UPDATE_INTERVAL,
limits: RenderLimits = DEFAULT_LIMITS,
rebuild_before: datetime.datetime | None = None,
+ max_versions: int = MAX_VERSIONS,
) -> ActivitySummaryUpdate:
"""Update the stored activity summary of one user in one project.
@@ -183,6 +226,7 @@ def update_activity_summary(
update records the error and keeps the stored summary and the watermark. With `dry_run`, the
model is still called but nothing is written. `force` ignores `next_eligible_at`.
A skip for too few units and a failed update set `next_eligible_at` to `RETRY_BACKOFF` from now.
+ A successful update also appends a `UserActivitySummaryVersion` and keeps the latest `max_versions`.
"""
team = Team.objects.select_related("organization").get(id=team_id)
if team.organization.is_ai_data_processing_approved is not True:
@@ -274,10 +318,10 @@ def update_activity_summary(
)
return result
- UserActivitySummary.objects.for_team(team_id).update_or_create(
- team_id=team_id,
- user_id=user_id,
- defaults={
+ _store_version(
+ team_id,
+ user_id,
+ {
**accounting,
"status": UserActivitySummary.Status.OK,
"summary": outcome.summary,
@@ -289,6 +333,7 @@ def update_activity_summary(
"input_watermark": watermark,
"next_eligible_at": now + min_update_interval,
},
+ max_versions,
)
return result
except Exception as error:
diff --git a/products/signals/backend/activity_summary/tick.py b/products/signals/backend/activity_summary/tick.py
index 24cba59571cf..07b72a61e97b 100644
--- a/products/signals/backend/activity_summary/tick.py
+++ b/products/signals/backend/activity_summary/tick.py
@@ -27,6 +27,7 @@ from posthog.temporal.common.utils import close_db_connections
from products.signals.backend.activity_summary.config import read_config
from products.signals.backend.activity_summary.logic import (
+ MAX_VERSIONS,
ActivitySummaryUpdate,
UpdateAfterModelCallError,
UpdateStatus,
@@ -89,6 +90,7 @@ class ActivitySummaryTickPlan:
# A default, so a plan that a workflow history recorded before this field existed still decodes.
limits: RenderLimits = DEFAULT_LIMITS
rebuild_before: datetime.datetime | None = None
+ max_versions: int = MAX_VERSIONS
@frozen
@@ -102,6 +104,8 @@ class ActivitySummaryPairInput:
# A default, so a pair input that a tick queued before this field existed still decodes.
limits: RenderLimits = DEFAULT_LIMITS
rebuild_before: datetime.datetime | None = None
+ # Has a default, so the pair input of a workflow in flight during a deploy still decodes.
+ max_versions: int = MAX_VERSIONS
@frozen
@@ -160,6 +164,7 @@ def plan_tick(limit: int | None, now: datetime.datetime) -> ActivitySummaryTickP
limits=config.limits,
stop_reason=stop_reason,
rebuild_before=config.rebuild_before,
+ max_versions=config.max_versions,
)
@@ -224,6 +229,7 @@ def run_pair(input: ActivitySummaryPairInput, *, last_attempt: bool = True) -> A
min_update_interval=datetime.timedelta(hours=input.min_update_interval_hours),
limits=input.limits,
rebuild_before=input.rebuild_before,
+ max_versions=input.max_versions,
)
called_model = update.status in (UpdateStatus.OK, UpdateStatus.FAILED)
except Exception as error:
@@ -339,6 +345,7 @@ class ActivitySummaryTickWorkflow:
capture_events=plan.capture_events,
limits=plan.limits,
rebuild_before=plan.rebuild_before,
+ max_versions=plan.max_versions,
),
start_to_close_timeout=_PAIR_TIMEOUT,
heartbeat_timeout=_PAIR_HEARTBEAT_TIMEOUT,
diff --git a/products/signals/backend/migrations/0191_useractivitysummaryversion.py b/products/signals/backend/migrations/0191_useractivitysummaryversion.py
new file mode 100644
index 000000000000..0da5cff8b8ea
--- /dev/null
+++ b/products/signals/backend/migrations/0191_useractivitysummaryversion.py
@@ -0,0 +1,79 @@
+# Generated by Django 5.2.18 on 2026-10-21 16:05
+
+import django.db.models.manager
+import django.db.models.deletion
+from django.db import migrations, models
+
+import posthog.uuidt
+
+
+class Migration(migrations.Migration):
+ dependencies = [
+ ("posthog", "1406_file_system_team_text_trgm_index"),
+ ("signals", "0190_monitoring_fallback_expiry"),
+ ]
+
+ operations = [
+ migrations.AddField(
+ model_name="useractivitysummary",
+ name="version",
+ field=models.PositiveIntegerField(db_default=0, default=0),
+ ),
+ migrations.CreateModel(
+ name="UserActivitySummaryVersion",
+ fields=[
+ (
+ "id",
+ models.UUIDField(
+ default=posthog.uuidt.uuid7,
+ editable=False,
+ primary_key=True,
+ serialize=False,
+ ),
+ ),
+ ("version", models.PositiveIntegerField()),
+ ("summary", models.JSONField()),
+ ("summary_text", models.TextField()),
+ ("generated_at", models.DateTimeField()),
+ ("model", models.CharField(max_length=100)),
+ ("prompt_version", models.PositiveSmallIntegerField()),
+ ("render_version", models.PositiveSmallIntegerField()),
+ ("input_watermark", models.DateTimeField()),
+ ("inputs_used", models.JSONField(blank=True, default=dict)),
+ ("tokens_in", models.IntegerField(blank=True, null=True)),
+ ("tokens_out", models.IntegerField(blank=True, null=True)),
+ ("cost_usd", models.FloatField(blank=True, null=True)),
+ ("created_at", models.DateTimeField(auto_now_add=True)),
+ (
+ "summary_row",
+ models.ForeignKey(
+ db_index=False,
+ on_delete=django.db.models.deletion.CASCADE,
+ related_name="versions",
+ to="signals.useractivitysummary",
+ ),
+ ),
+ (
+ "team",
+ models.ForeignKey(
+ db_constraint=False,
+ on_delete=django.db.models.deletion.CASCADE,
+ related_name="+",
+ to="posthog.team",
+ ),
+ ),
+ ],
+ options={
+ "default_manager_name": "all_teams",
+ "constraints": [
+ models.UniqueConstraint(
+ fields=("summary_row", "version"),
+ name="signals_activity_summary_version_unique",
+ )
+ ],
+ },
+ managers=[
+ ("all_teams", django.db.models.manager.Manager()),
+ ],
+ ),
+ ]
diff --git a/products/signals/backend/migrations/max_migration.txt b/products/signals/backend/migrations/max_migration.txt
index cb61b9ee3e41..2eda61cec820 100644
--- a/products/signals/backend/migrations/max_migration.txt
+++ b/products/signals/backend/migrations/max_migration.txt
@@ -1 +1 @@
-0190_monitoring_fallback_expiry
+0191_useractivitysummaryversion
diff --git a/products/signals/backend/models.py b/products/signals/backend/models.py
index 05d10cc55922..2e61c8b2df55 100644
--- a/products/signals/backend/models.py
+++ b/products/signals/backend/models.py
@@ -3861,6 +3861,9 @@ class UserActivitySummary(TeamScopedRootMixin, UUIDModel):
# The newest input timestamp the stored summary includes. The next update reads only later rows.
input_watermark = models.DateTimeField(null=True, blank=True)
next_eligible_at = models.DateTimeField(null=True, blank=True)
+ # The number of the latest successful update, and of its `UserActivitySummaryVersion` row. 0 before the first.
+ # `db_default` lets a pod on the earlier release insert a row without this column during a deploy.
+ version = models.PositiveIntegerField(default=0, db_default=0)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
@@ -3870,3 +3873,42 @@ class UserActivitySummary(TeamScopedRootMixin, UUIDModel):
constraints = [
models.UniqueConstraint(fields=["team", "user"], name="signals_activity_summary_team_user"),
]
+
+
+class UserActivitySummaryVersion(TeamScopedRootMixin, UUIDModel):
+ """One successful update of a `UserActivitySummary`, kept so that versions can be compared.
+
+ Append-only. `update_activity_summary` writes one row per successful update and keeps only the
+ latest `max_versions` rows per summary. It does not store the rendered input.
+ """
+
+ # See SignalReportRefund.all_teams for rationale.
+ all_teams = models.Manager() # noqa: DJ012
+
+ team = models.ForeignKey("posthog.Team", on_delete=models.CASCADE, db_constraint=False, related_name="+")
+ # Deleting the summary row (opt-out, user or team deletion) deletes its history.
+ # The unique constraint leads with this column, so the key needs no index of its own.
+ summary_row = models.ForeignKey(
+ UserActivitySummary, on_delete=models.CASCADE, related_name="versions", db_index=False
+ )
+ version = models.PositiveIntegerField()
+
+ summary = models.JSONField()
+ summary_text = models.TextField()
+ generated_at = models.DateTimeField()
+ model = models.CharField(max_length=100)
+ prompt_version = models.PositiveSmallIntegerField()
+ render_version = models.PositiveSmallIntegerField()
+ input_watermark = models.DateTimeField()
+ inputs_used = models.JSONField(default=dict, blank=True)
+ tokens_in = models.IntegerField(null=True, blank=True)
+ tokens_out = models.IntegerField(null=True, blank=True)
+ cost_usd = models.FloatField(null=True, blank=True)
+
+ created_at = models.DateTimeField(auto_now_add=True)
+
+ class Meta:
+ default_manager_name = "all_teams"
+ constraints = [
+ models.UniqueConstraint(fields=["summary_row", "version"], name="signals_activity_summary_version_unique"),
+ ]
diff --git a/products/signals/backend/test/test_activity_summary_tick.py b/products/signals/backend/test/test_activity_summary_tick.py
index ed693a183ae7..3d1b56e6bb93 100644
--- a/products/signals/backend/test/test_activity_summary_tick.py
+++ b/products/signals/backend/test/test_activity_summary_tick.py
@@ -87,6 +87,7 @@ _CONFIG_CASES: list[tuple[str, Any, ActivitySummaryConfig]] = [
"max_concurrency": "8",
"min_units": None,
"min_update_interval_hours": 0,
+ "max_versions": -3,
"emit_embeddings": "no",
"rebuild_before": "not a time",
},
@@ -99,6 +100,7 @@ _CONFIG_CASES: list[tuple[str, Any, ActivitySummaryConfig]] = [
"max_pairs_per_tick": 5,
"max_cost_usd_per_day": 1,
"min_update_interval_hours": 12,
+ "max_versions": 5,
"capture_events": False,
"rebuild_before": "2026-10-01T00:00:00",
},
@@ -107,6 +109,7 @@ _CONFIG_CASES: list[tuple[str, Any, ActivitySummaryConfig]] = [
max_pairs_per_tick=5,
max_cost_usd_per_day=1.0,
min_update_interval_hours=12.0,
+ max_versions=5,
capture_events=False,
rebuild_before=datetime.datetime(2026, 10, 1, tzinfo=datetime.UTC),
),
diff --git a/products/signals/backend/test/test_activity_summary_update.py b/products/signals/backend/test/test_activity_summary_update.py
index 0cefbd6304fc..a94e8f9f473c 100644
--- a/products/signals/backend/test/test_activity_summary_update.py
+++ b/products/signals/backend/test/test_activity_summary_update.py
@@ -17,7 +17,7 @@ from products.signals.backend.activity_summary.inputs import user_activity
from products.signals.backend.activity_summary.logic import ActivitySummaryUpdate, UpdateStatus, update_activity_summary
from products.signals.backend.activity_summary.prompt import PROMPT_VERSION
from products.signals.backend.activity_summary.render import RENDER_VERSION, RenderLimits
-from products.signals.backend.models import UserActivitySummary
+from products.signals.backend.models import UserActivitySummary, UserActivitySummaryVersion
from products.signals.backend.test.test_activity_summary_render import FakeLLM
NOW = datetime.datetime(2026, 10, 19, 12, tzinfo=datetime.UTC)
@@ -62,6 +62,14 @@ class TestUpdateActivitySummary(BaseTest):
def _stored(self) -> UserActivitySummary | None:
return UserActivitySummary.objects.for_team(self.team.id).filter(user_id=self.user.id).first()
+ def _versions(self) -> list[int]:
+ return list(
+ UserActivitySummaryVersion.objects.for_team(self.team.id)
+ .filter(summary_row__user_id=self.user.id)
+ .order_by("version")
+ .values_list("version", flat=True)
+ )
+
def test_a_successful_update_stores_the_summary_and_advances_the_watermark(self) -> None:
self._changes(2, days_ago=2)
self._change("Signup funnel", days_ago=1, intent=f"Post the funnel to {PATH_SECRET}")
@@ -89,6 +97,11 @@ class TestUpdateActivitySummary(BaseTest):
next_sent = json.dumps(next_llm.requests[0]["messages"])
assert "Signup funnel" not in next_sent.split("Recent activity")[1]
assert "Builds the signup funnel." in next_sent
+ latest = self._stored()
+ assert latest is not None and latest.version == 2
+ assert self._versions() == [1, 2]
+ first = UserActivitySummaryVersion.objects.for_team(self.team.id).get(summary_row=latest, version=1)
+ assert (first.summary_text, first.input_watermark) == (stored.summary_text, stored.input_watermark)
def test_a_person_who_only_reads_gets_a_summary_from_what_they_opened(self) -> None:
other = User.objects.create_and_join(self.organization, "[email protected]", None)
@@ -211,6 +224,19 @@ class TestUpdateActivitySummary(BaseTest):
assert (after.summary, after.input_watermark) == (before.summary, before.input_watermark)
assert (after.tokens_in, after.tokens_out, after.cost_usd) == (None, None, None)
assert after.next_eligible_at == NOW + datetime.timedelta(hours=6)
+ assert after.version == before.version == 1
+ assert self._versions() == [1]
+
+ def test_keeps_the_latest_max_versions_and_deletes_them_with_the_summary(self) -> None:
+ for update in range(3):
+ self._changes(3, days_ago=2 - update / 2)
+ assert self._update(FakeLLM([ANSWER]), force=True, max_versions=2).status == UpdateStatus.OK
+
+ assert self._versions() == [2, 3]
+ stored = self._stored()
+ assert stored is not None and stored.version == 3
+ stored.delete()
+ assert self._versions() == []
@parameterized.expand(
[