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(business-knowledge): learn from past support tickets (#129088)

Alex V473b0aaec67b
diff --git a/frontend/snapshots.yml b/frontend/snapshots.yml
index 4f70797c9e6e..6fcacea7846d 100644
--- a/frontend/snapshots.yml
+++ b/frontend/snapshots.yml
@@ -15623,17 +15623,17 @@ snapshots:
scenes-app-settings-environment--settings-environment-autocapture--light:
hash: v1.k794b7964.43e1ac49d53e4a7cd9e5bba06aa31b4555b7f3e10a07a5f52267dad5bbbec620.aBNlBBYECi6IENWwb7ZrA_Hx9X24hhX6FE8N13VctOY
scenes-app-settings-environment--settings-environment-business-knowledge--dark:
- hash: v1.k794b7964.39b6c69fc41ef520175f40ca239773dba3457b5d0c3ec5b6a897f75a8059577d.qDHHcm28b4nlP4ujj3OMu66zSguoPjq-8q8Le-_-u8g
+ hash: v1.k794b7964.228d2385f3647a8b0186fb62ccb6f06dddc05136160dbebedca6c0780b49a081.6k8tSnexmnS08sACFI71MiU6WtR4BoJxhGVzdUxO3cw
scenes-app-settings-environment--settings-environment-business-knowledge--light:
- hash: v1.k794b7964.397def700712688887aeea7409b08c455d9a6e7289e0aebd65d0b4903286eb20.WrBFBDJXt2APcYL0Wa8Yr-j4PQCIC76fCEWeN7piBUY
+ hash: v1.k794b7964.049219f38ffedb7c20a0a475145deba53396e4b80660d72359e214350f333628.9od5s1lSGl-_rf6DmDhAv5f4QldyNfKTL5sYOU3t1cw
scenes-app-settings-environment--settings-environment-business-knowledge-learning-on-support-off--dark:
- hash: v1.k794b7964.d1eee15ccade419de09192b21760cc27ef15adccb180f0af374a51cad613818f.XjyKPhYxdO4SwyVWXv9reVrYqP1qiUCQwH0R26RxPHM
+ hash: v1.k794b7964.1b31dff659624097be32753067a051ecebd4076e89fbff09fa5575ecae9d81ec.M-LpaZq4Zb3rp-tF1FP-nDDNASzDTLeQUrhfqG72_Hk
scenes-app-settings-environment--settings-environment-business-knowledge-learning-on-support-off--light:
- hash: v1.k794b7964.12b58a0c92b4b16f37e79ffcb77d828b3491e476032112e1ea585b3f9dc7d631.SHLVYkfpdIBUzwtHOvMIF5J-ecDCo7z8GICVymEerAs
+ hash: v1.k794b7964.75c29c02894b0fc24a1c2da01875d70b7b6fda1820e8b7a6dbe9e8dd32695b11.2z1t3ofM5K57z1P0GfOviCdcZ2P2luC6IgjvnRfMQPk
scenes-app-settings-environment--settings-environment-business-knowledge-support-off--dark:
- hash: v1.k794b7964.d13fdf926e2c31d6b8c5634e321a404567154a0bc1921f5bb0f6513f552e279a.7ys4rmgnsW86Z6mp4X8ar-pKFRf30vrea2uJzxv9X90
+ hash: v1.k794b7964.a17188a389fcdbe752867ce7ba3e0f5081d090c58589c7141ef73bde07544b52.Pi3yTxZObLzmdRcQpNmAoiLI8CDsBMTFEGscR-2Uv2s
scenes-app-settings-environment--settings-environment-business-knowledge-support-off--light:
- hash: v1.k794b7964.f280471359ee4c1c189a4fa14fd851b9e44fbf399df0309a03a81e1111748700.2KjmPYyDg28tHSrbR2DJZGc0opZeHQ2223kHLTT3MeU
+ hash: v1.k794b7964.460071090ee031790f199b023ff5fc85417389c21d165f57e8290862afc32f94.NCgqXMQiXMjQUlXaNzP8TGT7cFx76k006iaI2QxJLz0
scenes-app-settings-environment--settings-environment-csp-reporting--dark:
hash: v1.k794b7964.f4130d62e5a1c5b36195dd5a385c21ce2a3e2393dd6433a47cd9a63cc442aebd.yqAfOtmiNR03sFk6E7Y0lNXgQMaiNYO32yNyc1_xZQo
scenes-app-settings-environment--settings-environment-csp-reporting--light:
diff --git a/frontend/src/scenes/settings/SettingsMap.tsx b/frontend/src/scenes/settings/SettingsMap.tsx
index f574c790a537..1538424574e9 100644
--- a/frontend/src/scenes/settings/SettingsMap.tsx
+++ b/frontend/src/scenes/settings/SettingsMap.tsx
@@ -1706,7 +1706,7 @@ export const SETTINGS_MAP: SettingSection[] = [
'When on, PostHog learns reusable answers from public human replies on resolved support tickets.',
component: <LearnFromSupportSetting />,
docsUrl: 'https://posthog.com/docs/business-knowledge/learn-from-support',
- keywords: ['business', 'knowledge', 'support', 'learn', 'ticket', 'resolved'],
+ keywords: ['business', 'knowledge', 'support', 'learn', 'ticket', 'resolved', 'past', 'backfill'],
},
{
id: 'business-knowledge-github-repos',
diff --git a/frontend/src/scenes/settings/stories/SettingsEnvironment.stories.tsx b/frontend/src/scenes/settings/stories/SettingsEnvironment.stories.tsx
index e8b520f9c20a..40e89c9162fe 100644
--- a/frontend/src/scenes/settings/stories/SettingsEnvironment.stories.tsx
+++ b/frontend/src/scenes/settings/stories/SettingsEnvironment.stories.tsx
@@ -303,6 +303,35 @@ export const SettingsEnvironmentBusinessKnowledgeLearningOnSupportOff: Story = {
],
}
+export const SettingsEnvironmentBusinessKnowledgeLearningFromPastTickets: Story = {
+ args: { sectionId: 'environment-business-knowledge' },
+ parameters: { testOptions: { snapshotBrowsers: [] } },
+ decorators: [
+ mswDecorator({
+ get: {
+ '/api/projects/:id/business_knowledge/settings/': {
+ learn_from_support_enabled: true,
+ support_enabled: true,
+ learning_backfill: {
+ status: 'running',
+ started_at: '2023-05-24T22:00:00Z',
+ finished_at: null,
+ tickets_read: 42,
+ tickets_in_progress: 3,
+ knowledge_created: 7,
+ },
+ },
+ '/api/projects/:id/business_knowledge/repositories/status/': {
+ connected: false,
+ integration_id: null,
+ integration_name: '',
+ repos: [],
+ },
+ },
+ }),
+ ],
+}
+
const codexSubscriptionMocks = (codex: Record<string, unknown>): Record<string, Record<string, unknown>> => ({
get: {
'/api/users/@me/integrations/codex/': codex,
diff --git a/products/business_knowledge/backend/api/serializers.py b/products/business_knowledge/backend/api/serializers.py
index a2daa71d8305..497505c207b7 100644
--- a/products/business_knowledge/backend/api/serializers.py
+++ b/products/business_knowledge/backend/api/serializers.py
@@ -26,6 +26,7 @@ from ..models import (
EmbeddingStatus,
KnowledgeLibrarySource,
KnowledgeSource,
+ LearningBackfillStatus,
RefreshInterval,
SafetyVerdict,
SourceType,
@@ -679,6 +680,24 @@ class GapTopicActionResultSerializer(serializers.Serializer):
# ---------------------------------------------------------------------------
+class LearningBackfillProgressSerializer(serializers.Serializer):
+ status = serializers.ChoiceField(
+ choices=LearningBackfillStatus.choices,
+ help_text="`running` while PostHog reads past tickets. `completed` once every ticket in the window is read.",
+ )
+ started_at = serializers.DateTimeField(help_text="When someone started learning from past tickets.")
+ finished_at = serializers.DateTimeField(
+ allow_null=True, help_text="When every past ticket was read. Null while the run continues."
+ )
+ tickets_read = serializers.IntegerField(
+ help_text="Tickets analyzed since the run started, including tickets from the regular 7-day pass."
+ )
+ tickets_in_progress = serializers.IntegerField(help_text="Tickets that are being analyzed now.")
+ knowledge_created = serializers.IntegerField(
+ help_text="Analyzed tickets that added a learned source to business knowledge."
+ )
+
+
@extend_schema_serializer(component_name="BusinessKnowledgeSettings")
class BusinessKnowledgeSettingsSerializer(serializers.Serializer):
learn_from_support_enabled = serializers.BooleanField(
@@ -691,6 +710,11 @@ class BusinessKnowledgeSettingsSerializer(serializers.Serializer):
read_only=True,
help_text="Whether Support is enabled for this environment. Learning cannot be turned on while this is false.",
)
+ learning_backfill = LearningBackfillProgressSerializer(
+ read_only=True,
+ allow_null=True,
+ help_text="The last run of learning from past tickets. Null when none ran since learning was turned on.",
+ )
class BusinessKnowledgeSettingsUpdateSerializer(serializers.Serializer):
diff --git a/products/business_knowledge/backend/api/settings.py b/products/business_knowledge/backend/api/settings.py
index 7810ffe69a42..6b54a1bcd299 100644
--- a/products/business_knowledge/backend/api/settings.py
+++ b/products/business_knowledge/backend/api/settings.py
@@ -3,6 +3,7 @@ from typing import Any, cast
from drf_spectacular.utils import OpenApiResponse, extend_schema
from rest_framework.decorators import action
+from rest_framework.exceptions import ValidationError
from rest_framework.permissions import BasePermission, IsAuthenticated
from rest_framework.request import Request
from rest_framework.response import Response
@@ -17,6 +18,7 @@ from posthog.rate_limit import BurstRateThrottle, SustainedRateThrottle
from products.access_control.backend.facade.user_access_control import UserAccessControl
from .. import learning_settings
+from ..models import TeamBusinessKnowledgeConfig
from .serializers import BusinessKnowledgeSettingsSerializer, BusinessKnowledgeSettingsUpdateSerializer
@@ -61,7 +63,7 @@ class BusinessKnowledgeSettingsViewSet(TeamAndOrgViewSetMixin, ViewSet):
posthog_feature_flag = "product-business-knowledge"
throttle_classes = [BurstRateThrottle, SustainedRateThrottle]
pagination_class = None
- http_method_names = ["get", "patch", "head", "options"]
+ http_method_names = ["get", "patch", "post", "head", "options"]
@cached_property
def user_access_control(self) -> UserAccessControl:
@@ -79,11 +81,12 @@ class BusinessKnowledgeSettingsViewSet(TeamAndOrgViewSetMixin, ViewSet):
return ["business_knowledge:write"]
return ["business_knowledge:read"]
- def _serialize(self, *, learn_from_support_enabled: bool) -> dict[str, bool]:
+ def _serialize(self, config: TeamBusinessKnowledgeConfig) -> dict[str, Any]:
return BusinessKnowledgeSettingsSerializer(
{
- "learn_from_support_enabled": learn_from_support_enabled,
+ "learn_from_support_enabled": config.learn_from_support_enabled,
"support_enabled": bool(self.team.conversations_enabled),
+ "learning_backfill": learning_settings.get_learning_backfill_progress(config),
}
).data
@@ -126,4 +129,34 @@ class BusinessKnowledgeSettingsViewSet(TeamAndOrgViewSetMixin, ViewSet):
)
else:
config = learning_settings.get_team_business_knowledge_config(self.team)
- return Response(self._serialize(learn_from_support_enabled=config.learn_from_support_enabled))
+ return Response(self._serialize(config))
+
+ @extend_schema(
+ request=None,
+ responses={
+ 200: OpenApiResponse(
+ response=BusinessKnowledgeSettingsSerializer,
+ description="The updated Business knowledge learning settings.",
+ ),
+ 400: OpenApiResponse(description="Learn from support is off."),
+ },
+ summary="Learn from past support tickets",
+ description=(
+ "Start learning from resolved support tickets of the last 90 days. Tickets that were already "
+ "analyzed are skipped. The work runs in the background in small batches and can take a few hours."
+ ),
+ )
+ @action(
+ detail=False,
+ methods=["POST"],
+ url_path="learning_backfill",
+ url_name="learning_backfill",
+ required_scopes=["business_knowledge:write"],
+ )
+ def learning_backfill(self, request: Request, **kwargs: Any) -> Response:
+ config = learning_settings.get_team_business_knowledge_config(self.team)
+ if not config.learn_from_support_enabled:
+ raise ValidationError("Turn on Learn from support to learn from past tickets.")
+ if not self.team.conversations_enabled:
+ raise ValidationError("Turn on Support to learn from resolved tickets.")
+ return Response(self._serialize(learning_settings.start_learning_backfill(self.team)))
diff --git a/products/business_knowledge/backend/learning_settings.py b/products/business_knowledge/backend/learning_settings.py
index 0436d206930c..da2c93bbcb22 100644
--- a/products/business_knowledge/backend/learning_settings.py
+++ b/products/business_knowledge/backend/learning_settings.py
@@ -1,7 +1,30 @@
+from datetime import datetime, timedelta
+
+from django.db.models import Count, Q
+from django.utils import timezone
+
+from posthog.dataclasses import frozen
from posthog.models.team import Team
from posthog.models.team.extensions import get_or_create_team_extension
-from .models import TeamBusinessKnowledgeConfig
+from .models import (
+ KnowledgeLearningRun,
+ LearningBackfillStatus,
+ LearningRunResult,
+ LearningRunStatus,
+ TeamBusinessKnowledgeConfig,
+)
+from .temporal.learning.constants import ANALYSIS_VERSION, LEARNING_MAX_LOOKBACK_DAYS
+
+
+@frozen
+class LearningBackfillProgress:
+ status: LearningBackfillStatus
+ started_at: datetime
+ finished_at: datetime | None
+ tickets_read: int
+ tickets_in_progress: int
+ knowledge_created: int
def canonical_team_for_config(team: Team) -> Team:
@@ -22,5 +45,62 @@ def get_environment_business_knowledge_config(team: Team) -> TeamBusinessKnowled
def set_learn_from_support_enabled(team: Team, enabled: bool) -> TeamBusinessKnowledgeConfig:
config = get_team_business_knowledge_config(team)
config.learn_from_support_enabled = enabled
- config.save(update_fields=["learn_from_support_enabled"])
+ update_fields = ["learn_from_support_enabled"]
+ if not enabled:
+ # A paused backfill must not restart by surprise when someone turns learning back on.
+ config.learning_backfill_since = None
+ config.learning_backfill_started_at = None
+ config.learning_backfill_finished_at = None
+ config.learning_backfill_cursor = {}
+ update_fields += [
+ "learning_backfill_since",
+ "learning_backfill_started_at",
+ "learning_backfill_finished_at",
+ "learning_backfill_cursor",
+ ]
+ config.save(update_fields=update_fields)
+ return config
+
+
+def start_learning_backfill(team: Team) -> TeamBusinessKnowledgeConfig:
+ config = get_team_business_knowledge_config(team)
+ now = timezone.now()
+ config.learning_backfill_since = now - timedelta(days=LEARNING_MAX_LOOKBACK_DAYS)
+ config.learning_backfill_started_at = now
+ config.learning_backfill_finished_at = None
+ config.learning_backfill_cursor = {}
+ config.save(
+ update_fields=[
+ "learning_backfill_since",
+ "learning_backfill_started_at",
+ "learning_backfill_finished_at",
+ "learning_backfill_cursor",
+ ]
+ )
return config
+
+
+def get_learning_backfill_progress(config: TeamBusinessKnowledgeConfig) -> LearningBackfillProgress | None:
+ started_at = config.learning_backfill_started_at
+ if started_at is None:
+ return None
+ finished_at = None if config.learning_backfill_since is not None else config.learning_backfill_finished_at
+ # Runs carry no origin, so ticket analyses from the regular 7-day pass in this time range count too.
+ runs = KnowledgeLearningRun.objects.for_team(config.team_id).filter(
+ analysis_version=ANALYSIS_VERSION, created_at__gte=started_at
+ )
+ if finished_at is not None:
+ runs = runs.filter(created_at__lte=finished_at)
+ counts = runs.aggregate(
+ tickets_read=Count("id", filter=Q(status=LearningRunStatus.COMPLETED)),
+ tickets_in_progress=Count("id", filter=Q(status__in=[LearningRunStatus.PENDING, LearningRunStatus.RUNNING])),
+ knowledge_created=Count("id", filter=Q(result=LearningRunResult.KNOWLEDGE_CREATED)),
+ )
+ return LearningBackfillProgress(
+ status=LearningBackfillStatus.COMPLETED if finished_at is not None else LearningBackfillStatus.RUNNING,
+ started_at=started_at,
+ finished_at=finished_at,
+ tickets_read=counts["tickets_read"],
+ tickets_in_progress=counts["tickets_in_progress"],
+ knowledge_created=counts["knowledge_created"],
+ )
diff --git a/products/business_knowledge/backend/migrations/0026_team_bk_config_learning_backfill.py b/products/business_knowledge/backend/migrations/0026_team_bk_config_learning_backfill.py
new file mode 100644
index 000000000000..78c61b1dd2de
--- /dev/null
+++ b/products/business_knowledge/backend/migrations/0026_team_bk_config_learning_backfill.py
@@ -0,0 +1,49 @@
+# Generated by Django 6.1.3 on 2026-11-04 13:28
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+ dependencies = [
+ ("business_knowledge", "0025_knowledge_usage_record"),
+ ]
+
+ operations = [
+ migrations.AddField(
+ model_name="teambusinessknowledgeconfig",
+ name="learning_backfill_cursor",
+ field=models.JSONField(
+ blank=True,
+ db_default={},
+ default=dict,
+ help_text="Backfill scan position per '<source team id>:<provider>'. The coordinator never moves it past a ticket that still waits for analysis or a retry.",
+ ),
+ ),
+ migrations.AddField(
+ model_name="teambusinessknowledgeconfig",
+ name="learning_backfill_finished_at",
+ field=models.DateTimeField(
+ blank=True,
+ help_text="When the last backfill read every past ticket. Null while it runs or when none ran.",
+ null=True,
+ ),
+ ),
+ migrations.AddField(
+ model_name="teambusinessknowledgeconfig",
+ name="learning_backfill_since",
+ field=models.DateTimeField(
+ blank=True,
+ help_text="When set, learning also reads resolved tickets back to this time, not only the default lookback window. Null when no backfill is in progress.",
+ null=True,
+ ),
+ ),
+ migrations.AddField(
+ model_name="teambusinessknowledgeconfig",
+ name="learning_backfill_started_at",
+ field=models.DateTimeField(
+ blank=True,
+ help_text="When someone last started learning from past tickets. Null when no backfill ran since learning was turned on.",
+ null=True,
+ ),
+ ),
+ ]
diff --git a/products/business_knowledge/backend/migrations/0027_knowledgelearningrun_team_created_index.py b/products/business_knowledge/backend/migrations/0027_knowledgelearningrun_team_created_index.py
new file mode 100644
index 000000000000..f1e53c8dc42e
--- /dev/null
+++ b/products/business_knowledge/backend/migrations/0027_knowledgelearningrun_team_created_index.py
@@ -0,0 +1,21 @@
+from django.db import migrations, models
+
+from posthog.migration_helpers import SafeAddIndexConcurrently
+
+
+class Migration(migrations.Migration):
+ atomic = False
+
+ dependencies = [
+ ("business_knowledge", "0026_team_bk_config_learning_backfill"),
+ ]
+
+ operations = [
+ SafeAddIndexConcurrently(
+ model_name="knowledgelearningrun",
+ index=models.Index(
+ fields=["team", "analysis_version", "created_at"],
+ name="bk_learn_run_team_created",
+ ),
+ ),
+ ]
diff --git a/products/business_knowledge/backend/migrations/max_migration.txt b/products/business_knowledge/backend/migrations/max_migration.txt
index 8e9da83fb846..3e9db68526b3 100644
--- a/products/business_knowledge/backend/migrations/max_migration.txt
+++ b/products/business_knowledge/backend/migrations/max_migration.txt
@@ -1 +1 @@
-0025_knowledge_usage_record
+0027_knowledgelearningrun_team_created_index
diff --git a/products/business_knowledge/backend/models/__init__.py b/products/business_knowledge/backend/models/__init__.py
index f2012a8b248a..948da4aa93f8 100644
--- a/products/business_knowledge/backend/models/__init__.py
+++ b/products/business_knowledge/backend/models/__init__.py
@@ -4,6 +4,7 @@ from .constants import (
CrawlMode,
EmbeddingStatus,
GapStatus,
+ LearningBackfillStatus,
LearningProvider,
LearningRunResult,
LearningRunStatus,
@@ -42,6 +43,7 @@ __all__ = [
"KnowledgeSource",
"KnowledgeUsageKey",
"KnowledgeUsageRecord",
+ "LearningBackfillStatus",
"LearningProvider",
"PlaygroundChat",
"PlaygroundTurn",
diff --git a/products/business_knowledge/backend/models/constants.py b/products/business_knowledge/backend/models/constants.py
index ccd0865f7462..c4f1ee0e0bc4 100644
--- a/products/business_knowledge/backend/models/constants.py
+++ b/products/business_knowledge/backend/models/constants.py
@@ -122,6 +122,11 @@ class LearningRunStatus(models.TextChoices):
FAILED = "failed", "Failed"
+class LearningBackfillStatus(models.TextChoices):
+ RUNNING = "running", "Reading past tickets"
+ COMPLETED = "completed", "Read every past ticket"
+
+
class LearningRunResult(models.TextChoices):
KNOWLEDGE_CREATED = "knowledge_created", "Knowledge created"
NO_KNOWLEDGE = "no_knowledge", "No knowledge"
diff --git a/products/business_knowledge/backend/models/knowledge_learning_run.py b/products/business_knowledge/backend/models/knowledge_learning_run.py
index dc590f420904..fd8156125228 100644
--- a/products/business_knowledge/backend/models/knowledge_learning_run.py
+++ b/products/business_knowledge/backend/models/knowledge_learning_run.py
@@ -65,6 +65,8 @@ class KnowledgeLearningRun(TeamScopedRootMixin, UUIDModel):
]
indexes = [
models.Index(fields=["team", "status", "analysis_version"], name="bk_learn_run_team_status"),
+ # Bounds the backfill progress count to runs in its time range.
+ models.Index(fields=["team", "analysis_version", "created_at"], name="bk_learn_run_team_created"),
]
def __str__(self) -> str:
diff --git a/products/business_knowledge/backend/models/team_business_knowledge_config.py b/products/business_knowledge/backend/models/team_business_knowledge_config.py
index 4b61ccc0aea4..b897a52e6b7f 100644
--- a/products/business_knowledge/backend/models/team_business_knowledge_config.py
+++ b/products/business_knowledge/backend/models/team_business_knowledge_config.py
@@ -18,6 +18,35 @@ class TeamBusinessKnowledgeConfig(models.Model):
"support tickets. Requires Support to be enabled for this environment."
),
)
+ # Lives on the canonical parent with learn_from_support_enabled. The coordinator clears it once
+ # a pass finds no unprocessed ticket left in the window.
+ learning_backfill_since = models.DateTimeField(
+ null=True,
+ blank=True,
+ help_text=(
+ "When set, learning also reads resolved tickets back to this time, not only the default "
+ "lookback window. Null when no backfill is in progress."
+ ),
+ )
+ learning_backfill_started_at = models.DateTimeField(
+ null=True,
+ blank=True,
+ help_text="When someone last started learning from past tickets. Null when no backfill ran since learning was turned on.",
+ )
+ learning_backfill_finished_at = models.DateTimeField(
+ null=True,
+ blank=True,
+ help_text="When the last backfill read every past ticket. Null while it runs or when none ran.",
+ )
+ learning_backfill_cursor = models.JSONField(
+ default=dict,
+ db_default={},
+ blank=True,
+ help_text=(
+ "Backfill scan position per '<source team id>:<provider>'. The coordinator never moves it past "
+ "a ticket that still waits for analysis or a retry."
+ ),
+ )
# Environment-scoped, unlike learn_from_support_enabled. A GitHub App installation belongs to
# this environment, so a child environment must not inherit the parent's repository allowlist.
github_integration_id = models.IntegerField(
diff --git a/products/business_knowledge/backend/temporal/learning/activities/collect.py b/products/business_knowledge/backend/temporal/learning/activities/collect.py
index 366853cf0dff..f62898a64d2f 100644
--- a/products/business_knowledge/backend/temporal/learning/activities/collect.py
+++ b/products/business_knowledge/backend/temporal/learning/activities/collect.py
@@ -28,6 +28,8 @@ from products.business_knowledge.backend.models import (
from ..constants import (
ANALYSIS_VERSION,
+ LEARNING_BACKFILL_RETRY_HOURS,
+ LEARNING_BACKFILL_REWIND_ROWS,
LEARNING_COORDINATOR_INTERVAL_MINUTES,
LEARNING_MAX_ITEMS_PER_TEAM,
LEARNING_MAX_ITEMS_PER_TICK,
@@ -49,7 +51,9 @@ class _EvidenceIdentity:
evidence_key: str
-def _canonical_teams(input: LearningCoordinatorInput, now: datetime) -> Iterable[tuple[Team, int | None]]:
+def _canonical_teams(
+ input: LearningCoordinatorInput, now: datetime
+) -> Iterable[tuple[TeamBusinessKnowledgeConfig, int | None]]:
if input.team_id is None:
configs = (
TeamBusinessKnowledgeConfig.objects.filter(
@@ -68,7 +72,7 @@ def _canonical_teams(input: LearningCoordinatorInput, now: datetime) -> Iterable
configs[:start].iterator(chunk_size=100),
)
for config in rotated_configs:
- yield config.team, None
+ yield config, None
return
requested_team = Team.objects.select_related("organization").get(pk=input.team_id)
@@ -84,7 +88,7 @@ def _canonical_teams(input: LearningCoordinatorInput, now: datetime) -> Iterable
if selected_config is None:
return
source_team_id = requested_team.id if requested_team.parent_team_id else None
- yield selected_config.team, source_team_id
+ yield selected_config, source_team_id
def _source_team_ids(canonical_team: Team, requested_source_team_id: int | None) -> list[int]:
@@ -281,6 +285,146 @@ def _collect_team_refs(
return refs
+@frozen
+class _BackfillScan:
+ refs: list[EvidenceRef]
+ cursor: int
+ # True only when the scan reached the end of the window and every revision before it is settled.
+ exhausted: bool
+
+
+@frozen
+class _BackfillProgress:
+ refs: list[EvidenceRef]
+ cursor: dict[str, int]
+ finished: bool
+
+
+def _backfill_run_settled(run: KnowledgeLearningRun, ref: EvidenceRef, now: datetime) -> bool:
+ if run.source_team_id != ref.source_team_id or run.status == LearningRunStatus.COMPLETED:
+ return True
+ # A revision that keeps failing must not hold the backfill open forever.
+ return run.status == LearningRunStatus.FAILED and run.created_at <= now - timedelta(
+ hours=LEARNING_BACKFILL_RETRY_HOURS
+ )
+
+
+def _scan_backfill(
+ canonical_team: Team,
+ *,
+ source_team_id: int,
+ provider: LearningEvidenceProvider,
+ since: datetime,
+ settle_cutoff: datetime,
+ now: datetime,
+ selected: set[_EvidenceIdentity],
+ limit: int,
+ offset: int,
+) -> _BackfillScan:
+ # The cursor moves only past settled revisions, so a running or failed one is scanned again next tick.
+ # Provider order is newest first: new activity pushes old tickets back, and the cursor re-reads them.
+ refs: list[EvidenceRef] = []
+ cursor = offset
+ settled_prefix = True
+ position = offset
+ scan_end = offset + LEARNING_PROVIDER_MAX_SCAN_LIMIT
+ while position < scan_end:
+ page_limit = min(LEARNING_PROVIDER_SCAN_LIMIT, scan_end - position)
+ try:
+ collected = provider.collect(source_team_id, since=since, limit=page_limit, offset=position)
+ except Exception:
+ logger.exception(
+ "business_knowledge.learning.backfill_collection_failed",
+ team_id=canonical_team.id,
+ source_team_id=source_team_id,
+ provider=provider.name,
+ )
+ return _BackfillScan(refs=refs, cursor=cursor, exhausted=False)
+ existing = _existing_runs(canonical_team.id, collected)
+ for ref in collected:
+ position += 1
+ identity = _EvidenceIdentity(provider=ref.provider, evidence_key=ref.evidence_key)
+ run = existing.get(identity)
+ settled = False
+ if ref.provider != provider.name or ref.source_team_id != source_team_id:
+ settled = True
+ elif run is not None and _backfill_run_settled(run, ref, now):
+ settled = True
+ elif (
+ ref.revision_at <= settle_cutoff
+ and identity not in selected
+ and (run is None or _run_can_start(run, ref, now))
+ and len(refs) < limit
+ ):
+ refs.append(ref)
+ selected.add(identity)
+
+ if not settled:
+ settled_prefix = False
+ elif settled_prefix:
+ cursor = position
+ if not settled_prefix and len(refs) >= limit:
+ return _BackfillScan(refs=refs, cursor=cursor, exhausted=False)
+ if len(collected) < page_limit:
+ return _BackfillScan(refs=refs, cursor=cursor, exhausted=settled_prefix)
+ return _BackfillScan(refs=refs, cursor=cursor, exhausted=False)
+
+
+def _collect_backfill_refs(
+ config: TeamBusinessKnowledgeConfig,
+ *,
+ since: datetime,
+ settle_cutoff: datetime,
+ now: datetime,
+ selected: set[_EvidenceIdentity],
+ limit: int,
+) -> _BackfillProgress:
+ canonical_team = config.team
+ stored_cursor = config.learning_backfill_cursor if isinstance(config.learning_backfill_cursor, dict) else {}
+ cursor: dict[str, int] = {}
+ refs: list[EvidenceRef] = []
+ finished = True
+ for source_team_id in _source_team_ids(canonical_team, None):
+ for provider in get_learning_providers():
+ key = f"{source_team_id}:{provider.name}"
+ offset = stored_cursor.get(key, 0)
+ if len(refs) >= limit:
+ # The team's work budget is full, so this scan waits for the next tick.
+ cursor[key] = offset if isinstance(offset, int) else 0
+ finished = False
+ continue
+ # Offsets shift when a ticket ahead of the cursor leaves the resolved list, for example when
+ # it is reopened. Settled rows are cheap to read again, so start one margin early.
+ offset = max(offset - LEARNING_BACKFILL_REWIND_ROWS, 0) if isinstance(offset, int) else 0
+ scan = _scan_backfill(
+ canonical_team,
+ source_team_id=source_team_id,
+ provider=provider,
+ since=since,
+ settle_cutoff=settle_cutoff,
+ now=now,
+ selected=selected,
+ limit=limit - len(refs),
+ offset=offset,
+ )
+ refs.extend(scan.refs)
+ cursor[key] = scan.cursor
+ finished = finished and scan.exhausted
+ return _BackfillProgress(refs=refs, cursor=cursor, finished=finished)
+
+
+def _save_backfill_progress(config: TeamBusinessKnowledgeConfig, progress: _BackfillProgress, *, now: datetime) -> None:
+ # Match the stored start so a backfill restarted during this tick keeps its fresh state.
+ match = TeamBusinessKnowledgeConfig.objects.filter(
+ team_id=config.team_id, learning_backfill_since=config.learning_backfill_since
+ )
+ if progress.finished:
+ match.update(learning_backfill_since=None, learning_backfill_cursor={}, learning_backfill_finished_at=now)
+ logger.info("business_knowledge.learning.backfill_completed", team_id=config.team_id)
+ elif progress.cursor != config.learning_backfill_cursor:
+ match.update(learning_backfill_cursor=progress.cursor)
+
+
def collect_learning_evidence(input: LearningCoordinatorInput) -> CollectLearningEvidenceOutput:
if input.lookback_days <= 0 or input.lookback_days > LEARNING_MAX_LOOKBACK_DAYS:
raise ValueError(f"lookback_days must be between 1 and {LEARNING_MAX_LOOKBACK_DAYS}")
@@ -290,9 +434,10 @@ def collect_learning_evidence(input: LearningCoordinatorInput) -> CollectLearnin
settle_cutoff = now - timedelta(minutes=LEARNING_SETTLE_MINUTES)
items: list[LearningWorkItem] = []
- for canonical_team, requested_source_team_id in _canonical_teams(input, now):
+ for config, requested_source_team_id in _canonical_teams(input, now):
if len(items) >= LEARNING_MAX_ITEMS_PER_TICK:
break
+ canonical_team = config.team
if not canonical_team.organization.is_ai_data_processing_approved or not logic.has_feature_flag(canonical_team):
continue
@@ -304,6 +449,18 @@ def collect_learning_evidence(input: LearningCoordinatorInput) -> CollectLearnin
ticket_id=ticket_id,
now=now,
)
+ # Manual runs can target one environment or ticket, so only scheduled ticks move a backfill.
+ if config.learning_backfill_since is not None and input.team_id is None and ticket_id is None:
+ backfill = _collect_backfill_refs(
+ config,
+ since=config.learning_backfill_since,
+ settle_cutoff=settle_cutoff,
+ now=now,
+ selected={_EvidenceIdentity(provider=ref.provider, evidence_key=ref.evidence_key) for ref in refs},
+ limit=LEARNING_MAX_ITEMS_PER_TEAM - len(refs),
+ )
+ refs.extend(backfill.refs)
+ _save_backfill_progress(config, backfill, now=now)
existing = _existing_runs(canonical_team.id, refs)
selected_for_team = 0
for ref in refs:
diff --git a/products/business_knowledge/backend/temporal/learning/constants.py b/products/business_knowledge/backend/temporal/learning/constants.py
index 6f524f42fc8e..f0533703c6eb 100644
--- a/products/business_knowledge/backend/temporal/learning/constants.py
+++ b/products/business_knowledge/backend/temporal/learning/constants.py
@@ -7,6 +7,8 @@ LEARNING_MAX_ITEMS_PER_TICK = 50
LEARNING_SETTLE_MINUTES = 5
LEARNING_RETRY_BACKOFF_MINUTES = 60
LEARNING_RUNNING_STALE_MINUTES = 120
+LEARNING_BACKFILL_RETRY_HOURS = 24
+LEARNING_BACKFILL_REWIND_ROWS = 250
LEARNING_PROVIDER_SCAN_LIMIT = 250
LEARNING_PROVIDER_MAX_SCAN_LIMIT = 5_000
LEARNING_MODEL = "claude-haiku-4-5"
diff --git a/products/business_knowledge/backend/tests/test_learning_coordinator.py b/products/business_knowledge/backend/tests/test_learning_coordinator.py
index fd59d42dd21c..591394521386 100644
--- a/products/business_knowledge/backend/tests/test_learning_coordinator.py
+++ b/products/business_knowledge/backend/tests/test_learning_coordinator.py
@@ -77,6 +77,8 @@ class _Provider:
def __init__(self) -> None:
self.refs_by_team: dict[int, list[EvidenceRef]] = {}
self.calls: list[tuple[int, datetime, int, int, UUID | None]] = []
+ self.error: Exception | None = None
+ self.filter_by_since = False
def collect(
self,
@@ -88,7 +90,11 @@ class _Provider:
ticket_id: UUID | None = None,
) -> list[EvidenceRef]:
self.calls.append((team_id, since, limit, offset, ticket_id))
+ if self.error is not None:
+ raise self.error
refs = self.refs_by_team.get(team_id, [])
+ if self.filter_by_since:
+ refs = [ref for ref in refs if ref.revision_at >= since]
if ticket_id is not None:
refs = [ref for ref in refs if ref.ticket_id == ticket_id]
return refs[offset : offset + limit]
@@ -208,6 +214,120 @@ class TestCollectLearningEvidence(BaseTest):
assert result.items[0].run_id == str(failed_run.id)
assert immediate_retry.items == []
+ def _old_evidence(self, seed: int) -> EvidenceRef:
+ self.provider.filter_by_since = True
+ return _evidence(self.team.id, seed, revision_at=datetime.now(UTC) - timedelta(days=30))
+
+ def _backfill_state(self) -> tuple[datetime | None, dict]:
+ config = learning_settings.get_team_business_knowledge_config(self.team)
+ return config.learning_backfill_since, config.learning_backfill_cursor
+
+ def _run_for(self, ref: EvidenceRef, status: str, *, age: timedelta = timedelta(0)) -> KnowledgeLearningRun:
+ run = KnowledgeLearningRun.objects.for_team(self.team.id).create(
+ team=self.team,
+ provider=ref.provider,
+ evidence_key=ref.evidence_key,
+ source_team_id=self.team.id,
+ analysis_version=ANALYSIS_VERSION,
+ status=status,
+ )
+ KnowledgeLearningRun.objects.for_team(self.team.id).filter(id=run.id).update(
+ created_at=timezone.now() - age, updated_at=timezone.now() - age
+ )
+ return run
+
+ @patch(f"{COLLECT_MODULE}.logic.has_feature_flag", return_value=True)
+ def test_backfill_reads_old_tickets_and_waits_for_their_runs_to_complete(self, _feature_flag) -> None:
+ old_ref = self._old_evidence(7)
+ self.provider.refs_by_team[self.team.id] = [old_ref]
+
+ assert collect_learning_evidence(LearningCoordinatorInput()).items == []
+
+ learning_settings.start_learning_backfill(self.team)
+ first = collect_learning_evidence(LearningCoordinatorInput())
+ while_running = collect_learning_evidence(LearningCoordinatorInput())
+
+ assert [item.evidence for item in first.items] == [old_ref]
+ assert while_running.items == []
+ assert self._backfill_state()[0] is not None
+
+ KnowledgeLearningRun.objects.for_team(self.team.id).update(status=LearningRunStatus.COMPLETED)
+ collect_learning_evidence(LearningCoordinatorInput())
+
+ assert self._backfill_state() == (None, {})
+ progress = learning_settings.get_learning_backfill_progress(
+ learning_settings.get_team_business_knowledge_config(self.team)
+ )
+ assert progress is not None
+ assert (progress.status, progress.tickets_read) == ("completed", 1)
+
+ @patch(f"{COLLECT_MODULE}.logic.has_feature_flag", return_value=True)
+ def test_backfill_survives_a_collection_failure(self, _feature_flag) -> None:
+ self.provider.refs_by_team[self.team.id] = []
+ learning_settings.start_learning_backfill(self.team)
+ self.provider.error = RuntimeError("provider unavailable")
+
+ collect_learning_evidence(LearningCoordinatorInput())
+
+ assert self._backfill_state()[0] is not None
+
+ @patch(f"{COLLECT_MODULE}.LEARNING_BACKFILL_REWIND_ROWS", 1)
+ @patch(f"{COLLECT_MODULE}.LEARNING_PROVIDER_MAX_SCAN_LIMIT", 2)
+ @patch(f"{COLLECT_MODULE}.LEARNING_PROVIDER_SCAN_LIMIT", 2)
+ @patch(f"{COLLECT_MODULE}.logic.has_feature_flag", return_value=True)
+ def test_backfill_resumes_past_settled_tickets_beyond_the_scan_budget(self, _feature_flag) -> None:
+ completed_ref, gave_up_ref, unread_ref = (self._old_evidence(seed) for seed in (8, 9, 10))
+ self.provider.refs_by_team[self.team.id] = [completed_ref, gave_up_ref, unread_ref]
+ self._run_for(completed_ref, LearningRunStatus.COMPLETED)
+ self._run_for(gave_up_ref, LearningRunStatus.FAILED, age=timedelta(hours=25))
+ learning_settings.start_learning_backfill(self.team)
+
+ first = collect_learning_evidence(LearningCoordinatorInput())
+ second = collect_learning_evidence(LearningCoordinatorInput())
+
+ assert first.items == []
+ assert self._backfill_state()[0] is not None
+ assert [item.evidence for item in second.items] == [unread_ref]
+
+ @patch(f"{COLLECT_MODULE}.LEARNING_BACKFILL_REWIND_ROWS", 2)
+ @patch(f"{COLLECT_MODULE}.LEARNING_PROVIDER_MAX_SCAN_LIMIT", 2)
+ @patch(f"{COLLECT_MODULE}.LEARNING_PROVIDER_SCAN_LIMIT", 2)
+ @patch(f"{COLLECT_MODULE}.logic.has_feature_flag", return_value=True)
+ def test_backfill_does_not_skip_a_ticket_when_an_earlier_one_is_reopened(self, _feature_flag) -> None:
+ first_ref, second_ref, unread_ref = (self._old_evidence(seed) for seed in (11, 12, 13))
+ self.provider.refs_by_team[self.team.id] = [first_ref, second_ref, unread_ref]
+ self._run_for(first_ref, LearningRunStatus.COMPLETED)
+ self._run_for(second_ref, LearningRunStatus.COMPLETED)
+ learning_settings.start_learning_backfill(self.team)
+
+ assert collect_learning_evidence(LearningCoordinatorInput()).items == []
+ self.provider.refs_by_team[self.team.id] = [second_ref, unread_ref]
+ resumed = collect_learning_evidence(LearningCoordinatorInput())
+
+ assert [item.evidence for item in resumed.items] == [unread_ref]
+
+ @patch(f"{COLLECT_MODULE}.logic.has_feature_flag", return_value=True)
+ def test_backfill_defers_other_environments_when_the_team_budget_is_full(self, _feature_flag) -> None:
+ child = Team.objects.create(
+ organization=self.organization,
+ project=self.project,
+ parent_team=self.team,
+ name="Child environment",
+ conversations_enabled=True,
+ )
+ self.provider.refs_by_team[self.team.id] = [
+ self._old_evidence(seed) for seed in range(20, 20 + LEARNING_MAX_ITEMS_PER_TEAM)
+ ]
+ self.provider.refs_by_team[child.id] = [
+ _evidence(child.id, 40, revision_at=datetime.now(UTC) - timedelta(days=30))
+ ]
+ backfill_since = learning_settings.start_learning_backfill(self.team).learning_backfill_since
+
+ collect_learning_evidence(LearningCoordinatorInput())
+
+ assert child.id not in {call[0] for call in self.provider.calls if call[1] == backfill_since}
+ assert self._backfill_state()[0] is not None
+
@patch(f"{COLLECT_MODULE}.timezone.now", return_value=datetime(2026, 9, 12, tzinfo=UTC))
@patch(f"{COLLECT_MODULE}.logic.has_feature_flag", return_value=True)
def test_fresh_revision_waits_for_settle_window(self, _feature_flag, _now) -> None:
diff --git a/products/business_knowledge/backend/tests/test_settings_api.py b/products/business_knowledge/backend/tests/test_settings_api.py
index 9f1f7b83ffc8..b50e1bf8e6fb 100644
--- a/products/business_knowledge/backend/tests/test_settings_api.py
+++ b/products/business_knowledge/backend/tests/test_settings_api.py
@@ -22,11 +22,15 @@ from products.business_knowledge.backend.api.serializers import BusinessKnowledg
from products.business_knowledge.backend.api.settings import BusinessKnowledgeSettingsViewSet
from products.business_knowledge.backend.libraries import create_library, replace_library_sources
from products.business_knowledge.backend.models import (
+ KnowledgeLearningRun,
KnowledgeLibrary,
KnowledgeLibrarySource,
KnowledgeSource,
+ LearningRunResult,
+ LearningRunStatus,
TeamBusinessKnowledgeConfig,
)
+from products.business_knowledge.backend.temporal.learning.constants import ANALYSIS_VERSION
SUPPORT_OFF_ERROR = "Turn on Support to learn from resolved tickets."
@@ -99,6 +103,7 @@ class TestBusinessKnowledgeSettingsAPI(APIBaseTest):
assert response.json() == {
"learn_from_support_enabled": False,
"support_enabled": False,
+ "learning_backfill": None,
}
def test_patch_round_trips(self, _ff) -> None:
@@ -109,10 +114,12 @@ class TestBusinessKnowledgeSettingsAPI(APIBaseTest):
assert enabled.json() == {
"learn_from_support_enabled": True,
"support_enabled": True,
+ "learning_backfill": None,
}
assert self.client.get(self.url).json() == {
"learn_from_support_enabled": True,
"support_enabled": True,
+ "learning_backfill": None,
}
disabled = self.client.patch(self.url, {"learn_from_support_enabled": False}, format="json")
@@ -140,8 +147,46 @@ class TestBusinessKnowledgeSettingsAPI(APIBaseTest):
assert response.json() == {
"learn_from_support_enabled": False,
"support_enabled": False,
+ "learning_backfill": None,
}
+ def test_learning_backfill_reports_progress_and_stops_when_learning_is_turned_off(self, _ff) -> None:
+ backfill_url = f"/api/projects/{self.team.id}/business_knowledge/learning_backfill/"
+ self._enable_support()
+
+ refused = self.client.post(backfill_url)
+ assert refused.status_code == status.HTTP_400_BAD_REQUEST, refused.content
+
+ self.client.patch(self.url, {"learn_from_support_enabled": True}, format="json")
+ started = self.client.post(backfill_url)
+ assert started.status_code == status.HTTP_200_OK, started.content
+ assert started.json()["learning_backfill"]["status"] == "running"
+
+ for index, (run_status, result) in enumerate(
+ [
+ (LearningRunStatus.COMPLETED, LearningRunResult.KNOWLEDGE_CREATED),
+ (LearningRunStatus.COMPLETED, LearningRunResult.NO_KNOWLEDGE),
+ (LearningRunStatus.RUNNING, ""),
+ ]
+ ):
+ KnowledgeLearningRun.objects.for_team(self.team.id).create(
+ team=self.team,
+ evidence_key=f"ticket-{index}",
+ source_team_id=self.team.id,
+ analysis_version=ANALYSIS_VERSION,
+ status=run_status,
+ result=result,
+ )
+ progress = self.client.get(self.url).json()["learning_backfill"]
+ assert {key: progress[key] for key in ("tickets_read", "tickets_in_progress", "knowledge_created")} == {
+ "tickets_read": 2,
+ "tickets_in_progress": 1,
+ "knowledge_created": 1,
+ }
+
+ self.client.patch(self.url, {"learn_from_support_enabled": False}, format="json")
+ assert self.client.get(self.url).json()["learning_backfill"] is None
+
def test_empty_patch_is_a_noop(self, _ff) -> None:
response = self.client.patch(self.url, {}, format="json")
@@ -169,6 +214,7 @@ class TestBusinessKnowledgeSettingsAPI(APIBaseTest):
assert self.client.get(f"/api/projects/{child.id}/business_knowledge/settings/").json() == {
"learn_from_support_enabled": True,
"support_enabled": True,
+ "learning_backfill": None,
}
assert get_or_create_team_extension(self.team, TeamBusinessKnowledgeConfig).learn_from_support_enabled is True
assert get_or_create_team_extension(child, TeamBusinessKnowledgeConfig).learn_from_support_enabled is False
@@ -192,6 +238,7 @@ class TestBusinessKnowledgeSettingsAPI(APIBaseTest):
assert response.json() == {
"learn_from_support_enabled": True,
"support_enabled": False,
+ "learning_backfill": None,
}
def test_child_cannot_enable_when_its_support_is_off(self, _ff) -> None:
diff --git a/products/business_knowledge/frontend/generated/api.schemas.ts b/products/business_knowledge/frontend/generated/api.schemas.ts
index f876a726f4b0..2802d8b8d524 100644
--- a/products/business_knowledge/frontend/generated/api.schemas.ts
+++ b/products/business_knowledge/frontend/generated/api.schemas.ts
@@ -120,6 +120,48 @@ export interface GapTopicActionResultApi {
readonly updated: number
}
+/**
+ * * `running` - Reading past tickets
+ * * `completed` - Read every past ticket
+ */
+export type LearningBackfillStatusEnumApi =
+ (typeof LearningBackfillStatusEnumApi)[keyof typeof LearningBackfillStatusEnumApi]
+
+export const LearningBackfillStatusEnumApi = {
+ Running: 'running',
+ Completed: 'completed',
+} as const
+
+export interface LearningBackfillProgressApi {
+ /** `running` while PostHog reads past tickets. `completed` once every ticket in the window is read.
+ *
+ * * `running` - Reading past tickets
+ * * `completed` - Read every past ticket */
+ status: LearningBackfillStatusEnumApi
+ /** When someone started learning from past tickets. */
+ started_at: string
+ /**
+ * When every past ticket was read. Null while the run continues.
+ * @nullable
+ */
+ finished_at: string | null
+ /** Tickets analyzed since the run started, including tickets from the regular 7-day pass. */
+ tickets_read: number
+ /** Tickets that are being analyzed now. */
+ tickets_in_progress: number
+ /** Analyzed tickets that added a learned source to business knowledge. */
+ knowledge_created: number
+}
+
+export interface BusinessKnowledgeSettingsApi {
+ /** When true, PostHog learns reusable knowledge from public human replies on resolved support tickets. Requires Support to be enabled for this environment. */
+ learn_from_support_enabled: boolean
+ /** Whether Support is enabled for this environment. Learning cannot be turned on while this is false. */
+ readonly support_enabled: boolean
+ /** The last run of learning from past tickets. Null when none ran since learning was turned on. */
+ readonly learning_backfill: LearningBackfillProgressApi | null
+}
+
export interface KnowledgeLibraryApi {
/** Library id. */
id: string
@@ -393,13 +435,6 @@ export interface SandboxRunStartedApi {
run_id: string
}
-export interface BusinessKnowledgeSettingsApi {
- /** When true, PostHog learns reusable knowledge from public human replies on resolved support tickets. Requires Support to be enabled for this environment. */
- learn_from_support_enabled: boolean
- /** Whether Support is enabled for this environment. Learning cannot be turned on while this is false. */
- readonly support_enabled: boolean
-}
-
export interface PatchedBusinessKnowledgeSettingsUpdateApi {
/** When true, PostHog learns reusable knowledge from public human replies on resolved support tickets. Rejected when Support is off for this environment. */
learn_from_support_enabled?: boolean
diff --git a/products/business_knowledge/frontend/generated/api.ts b/products/business_knowledge/frontend/generated/api.ts
index 74b7fd92562f..b95ea9a4ba3b 100644
--- a/products/business_knowledge/frontend/generated/api.ts
+++ b/products/business_knowledge/frontend/generated/api.ts
@@ -266,6 +266,24 @@ export const businessKnowledgeGapSuggestionsDismissTopicCreate = async (
})
}
+export const getBusinessKnowledgeLearningBackfillCreateUrl = (projectId: string) => {
+ return `/api/projects/${projectId}/business_knowledge/learning_backfill/`
+}
+
+/**
+ * Start learning from resolved support tickets of the last 90 days. Tickets that were already analyzed are skipped. The work runs in the background in small batches and can take a few hours.
+ * @summary Learn from past support tickets
+ */
+export const businessKnowledgeLearningBackfillCreate = async (
+ projectId: string,
+ options?: RequestInit
+): Promise<BusinessKnowledgeSettingsApi> => {
+ return apiMutator<BusinessKnowledgeSettingsApi>(getBusinessKnowledgeLearningBackfillCreateUrl(projectId), {
+ ...options,
+ method: 'POST',
+ })
+}
+
export const getBusinessKnowledgeLibrariesListUrl = (projectId: string) => {
return `/api/projects/${projectId}/business_knowledge/libraries/`
}
diff --git a/products/business_knowledge/frontend/scenes/settings/LearnFromPastTicketsSetting.tsx b/products/business_knowledge/frontend/scenes/settings/LearnFromPastTicketsSetting.tsx
new file mode 100644
index 000000000000..d508b0ac54e9
--- /dev/null
+++ b/products/business_knowledge/frontend/scenes/settings/LearnFromPastTicketsSetting.tsx
@@ -0,0 +1,75 @@
+import { useActions, useValues } from 'kea'
+
+import { LemonBanner, LemonButton, Spinner } from '@posthog/lemon-ui'
+
+import { dayjs } from 'lib/dayjs'
+import { pluralize } from 'lib/utils/strings'
+
+import type { LearningBackfillProgressApi } from '../../generated/api.schemas'
+import { businessKnowledgeSettingsLogic } from './businessKnowledgeSettingsLogic'
+
+function progressSummary(progress: LearningBackfillProgressApi): string {
+ return `${pluralize(progress.tickets_read, 'ticket')} read, ${progress.knowledge_created} added as knowledge`
+}
+
+export function LearnFromPastTicketsSetting(): JSX.Element | null {
+ const { settings, learningBackfillStarting } = useValues(businessKnowledgeSettingsLogic)
+ const { startLearningBackfill } = useActions(businessKnowledgeSettingsLogic)
+
+ // The Self-learning setting renders this block only after settings load.
+ if (!settings) {
+ return null
+ }
+
+ const progress = settings.learning_backfill ?? null
+ const running = progress?.status === 'running'
+ const disabledReason = !settings.support_enabled
+ ? 'Turn on Support to learn from resolved tickets'
+ : !settings.learn_from_support_enabled
+ ? 'Turn on Learn from support first'
+ : running
+ ? 'Already reading past tickets'
+ : undefined
+
+ return (
+ <div className="flex flex-col items-start gap-2 max-w-xl">
+ <div className="flex flex-col gap-1">
+ <h4 className="m-0 font-semibold">Learn from past tickets</h4>
+ <p className="m-0 text-secondary">
+ Learn from support tickets resolved in the last 90 days, not only from new ones. Tickets that were
+ already read are skipped. PostHog reads them in the background, which can take a few hours.
+ </p>
+ </div>
+ <LemonBanner type="info" className="w-full">
+ Knowledge learned from past tickets counts toward your Business knowledge ingestion usage, the same as
+ sources you add yourself.
+ </LemonBanner>
+ {progress && running ? (
+ <div className="flex flex-col gap-1">
+ <div className="flex items-center gap-2">
+ <Spinner textColored />
+ <span>{`Reading past tickets. Started ${dayjs(progress.started_at).fromNow()}.`}</span>
+ </div>
+ <span className="text-secondary">
+ {`${progressSummary(progress)}, ${progress.tickets_in_progress} being read now.`}
+ </span>
+ </div>
+ ) : progress?.finished_at ? (
+ <span className="text-secondary">
+ {`Read every past ticket ${dayjs(progress.finished_at).fromNow()}: ${progressSummary(progress)}.`}
+ </span>
+ ) : null}
+ <LemonButton
+ type="secondary"
+ size="small"
+ onClick={startLearningBackfill}
+ loading={learningBackfillStarting}
+ disabledReason={disabledReason}
+ // data-attr is a frozen autocapture / Playwright key. Do not rename.
+ data-attr="business-knowledge-learn-from-past-tickets"
+ >
+ Learn from past tickets
+ </LemonButton>
+ </div>
+ )
+}
diff --git a/products/business_knowledge/frontend/scenes/settings/LearnFromSupportSetting.tsx b/products/business_knowledge/frontend/scenes/settings/LearnFromSupportSetting.tsx
index f6f099c22c2d..b079e1ae223d 100644
--- a/products/business_knowledge/frontend/scenes/settings/LearnFromSupportSetting.tsx
+++ b/products/business_knowledge/frontend/scenes/settings/LearnFromSupportSetting.tsx
@@ -5,6 +5,7 @@ import { LemonSkeleton, LemonSwitch, Link } from '@posthog/lemon-ui'
import { urls } from 'scenes/urls'
import { businessKnowledgeSettingsLogic } from './businessKnowledgeSettingsLogic'
+import { LearnFromPastTicketsSetting } from './LearnFromPastTicketsSetting'
export function LearnFromSupportSetting(): JSX.Element {
const { settings, settingsLoading, settingsSaving } = useValues(businessKnowledgeSettingsLogic)
@@ -25,22 +26,25 @@ export function LearnFromSupportSetting(): JSX.Element {
const cannotEnable = supportOff && !settings.learn_from_support_enabled
return (
- <div className="flex flex-col gap-2">
- <LemonSwitch
- bordered
- checked={settings.learn_from_support_enabled}
- onChange={setLearnFromSupportEnabled}
- loading={settingsSaving}
- disabledReason={cannotEnable ? 'Turn on Support to learn from resolved tickets' : undefined}
- label="Learn from support"
- // data-attr is a frozen autocapture / Playwright key. Do not rename.
- data-attr="business-knowledge-learn-from-support"
- />
- {supportOff ? (
- <Link to={urls.settings('environment-conversations')}>
- Turn on Support to learn from resolved tickets
- </Link>
- ) : null}
+ <div className="flex flex-col gap-4">
+ <div className="flex flex-col gap-2">
+ <LemonSwitch
+ bordered
+ checked={settings.learn_from_support_enabled}
+ onChange={setLearnFromSupportEnabled}
+ loading={settingsSaving}
+ disabledReason={cannotEnable ? 'Turn on Support to learn from resolved tickets' : undefined}
+ label="Learn from support"
+ // data-attr is a frozen autocapture / Playwright key. Do not rename.
+ data-attr="business-knowledge-learn-from-support"
+ />
+ {supportOff ? (
+ <Link to={urls.settings('environment-conversations')}>
+ Turn on Support to learn from resolved tickets
+ </Link>
+ ) : null}
+ </div>
+ <LearnFromPastTicketsSetting />
</div>
)
}
diff --git a/products/business_knowledge/frontend/scenes/settings/businessKnowledgeSettingsLogic.test.ts b/products/business_knowledge/frontend/scenes/settings/businessKnowledgeSettingsLogic.test.ts
index c108c0c732df..174bc6b9c5f8 100644
--- a/products/business_knowledge/frontend/scenes/settings/businessKnowledgeSettingsLogic.test.ts
+++ b/products/business_knowledge/frontend/scenes/settings/businessKnowledgeSettingsLogic.test.ts
@@ -4,7 +4,11 @@ import { resumeKeaLoadersErrors, silenceKeaLoadersErrors } from '~/initKea'
import { initKeaTests } from '~/test/init'
import { expectLogic } from '~/test/keaTestUtils'
-import { businessKnowledgeSettingsPartialUpdate, businessKnowledgeSettingsRetrieve } from '../../generated/api'
+import {
+ businessKnowledgeLearningBackfillCreate,
+ businessKnowledgeSettingsPartialUpdate,
+ businessKnowledgeSettingsRetrieve,
+} from '../../generated/api'
import { businessKnowledgeSettingsLogic } from './businessKnowledgeSettingsLogic'
jest.mock('lib/api', () => {
@@ -32,6 +36,7 @@ jest.mock('lib/lemon-ui/LemonToast/LemonToast', () => ({
jest.mock('../../generated/api', () => ({
businessKnowledgeSettingsRetrieve: jest.fn(),
businessKnowledgeSettingsPartialUpdate: jest.fn(),
+ businessKnowledgeLearningBackfillCreate: jest.fn(),
}))
describe('businessKnowledgeSettingsLogic', () => {
@@ -125,4 +130,84 @@ describe('businessKnowledgeSettingsLogic', () => {
expect(logic.values.settings?.learn_from_support_enabled).toBe(false)
})
+
+ it('unlocks the past tickets button and says why when the backfill is refused', async () => {
+ const { ApiError } = jest.requireMock('lib/api')
+ ;(businessKnowledgeLearningBackfillCreate as jest.Mock).mockRejectedValue(
+ new ApiError('Bad Request', 400, undefined, {
+ detail: 'Turn on Learn from support to learn from past tickets.',
+ })
+ )
+ await mountLogic()
+
+ logic.actions.startLearningBackfill()
+ expect(logic.values.learningBackfillStarting).toBe(true)
+ await expectLogic(logic).toFinishAllListeners()
+
+ expect(logic.values.learningBackfillStarting).toBe(false)
+ expect(lemonToast.error).toHaveBeenCalledWith('Turn on Learn from support to learn from past tickets.')
+ })
+
+ it.each([
+ { status: 'running', expectedLoads: 2 },
+ { status: 'completed', expectedLoads: 1 },
+ ])('reloads progress only while past tickets are being read ($status)', async ({ status, expectedLoads }) => {
+ jest.useFakeTimers()
+ try {
+ ;(businessKnowledgeSettingsRetrieve as jest.Mock).mockResolvedValue({
+ learn_from_support_enabled: true,
+ support_enabled: true,
+ learning_backfill: {
+ status,
+ started_at: '2026-11-01T00:00:00Z',
+ finished_at: status === 'completed' ? '2026-11-02T00:00:00Z' : null,
+ tickets_read: 1,
+ tickets_in_progress: 0,
+ knowledge_created: 0,
+ },
+ })
+ initKeaTests()
+ logic = businessKnowledgeSettingsLogic()
+ logic.mount()
+ await jest.advanceTimersByTimeAsync(0)
+
+ await jest.advanceTimersByTimeAsync(30_000)
+
+ expect(businessKnowledgeSettingsRetrieve).toHaveBeenCalledTimes(expectedLoads)
+ } finally {
+ jest.useRealTimers()
+ }
+ })
+
+ it('keeps reloading progress after a failed reload', async () => {
+ jest.useFakeTimers()
+ try {
+ const { ApiError } = jest.requireMock('lib/api')
+ ;(businessKnowledgeSettingsRetrieve as jest.Mock)
+ .mockResolvedValueOnce({
+ learn_from_support_enabled: true,
+ support_enabled: true,
+ learning_backfill: {
+ status: 'running',
+ started_at: '2026-11-01T00:00:00Z',
+ finished_at: null,
+ tickets_read: 1,
+ tickets_in_progress: 0,
+ knowledge_created: 0,
+ },
+ })
+ .mockRejectedValueOnce(new ApiError('Server Error', 500, undefined, { detail: 'unavailable' }))
+ initKeaTests()
+ logic = businessKnowledgeSettingsLogic()
+ logic.mount()
+ await jest.advanceTimersByTimeAsync(0)
+
+ await jest.advanceTimersByTimeAsync(30_000)
+ await jest.advanceTimersByTimeAsync(30_000)
+
+ expect(businessKnowledgeSettingsRetrieve).toHaveBeenCalledTimes(3)
+ } finally {
+ jest.useRealTimers()
+ }
+ })
})
diff --git a/products/business_knowledge/frontend/scenes/settings/businessKnowledgeSettingsLogic.ts b/products/business_knowledge/frontend/scenes/settings/businessKnowledgeSettingsLogic.ts
index f7d7d8476830..42f7692c05a2 100644
--- a/products/business_knowledge/frontend/scenes/settings/businessKnowledgeSettingsLogic.ts
+++ b/products/business_knowledge/frontend/scenes/settings/businessKnowledgeSettingsLogic.ts
@@ -8,8 +8,11 @@ import { lemonToast } from 'lib/lemon-ui/LemonToast/LemonToast'
import * as api from '../../generated/api'
import type { BusinessKnowledgeSettingsApi } from '../../generated/api.schemas'
+const LEARNING_BACKFILL_POLL_MS = 30_000
+
// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface businessKnowledgeSettingsLogicValues {
+ learningBackfillStarting: boolean
settings: BusinessKnowledgeSettingsApi | null
settingsLoading: boolean
settingsSaving: boolean
@@ -32,9 +35,18 @@ export interface businessKnowledgeSettingsLogicActions {
settings: BusinessKnowledgeSettingsApi
payload?: any
}
+ scheduleLearningBackfillPoll: () => {
+ value: true
+ }
setLearnFromSupportEnabled: (enabled: boolean) => {
enabled: boolean
}
+ startLearningBackfill: () => {
+ value: true
+ }
+ startLearningBackfillDone: () => {
+ value: true
+ }
}
export type businessKnowledgeSettingsLogicType = MakeLogicType<
@@ -46,6 +58,9 @@ export const businessKnowledgeSettingsLogic = kea<businessKnowledgeSettingsLogic
path(['products', 'business_knowledge', 'frontend', 'settings', 'businessKnowledgeSettingsLogic']),
actions({
setLearnFromSupportEnabled: (enabled: boolean) => ({ enabled }),
+ startLearningBackfill: true,
+ startLearningBackfillDone: true,
+ scheduleLearningBackfillPoll: true,
}),
loaders(() => ({
settings: [
@@ -72,8 +87,37 @@ export const businessKnowledgeSettingsLogic = kea<businessKnowledgeSettingsLogic
loadSettingsFailure: () => false,
},
],
+ learningBackfillStarting: [
+ false,
+ {
+ startLearningBackfill: () => true,
+ startLearningBackfillDone: () => false,
+ },
+ ],
}),
- listeners(({ actions, values }) => ({
+ listeners(({ actions, values, cache }) => ({
+ loadSettingsSuccess: () => {
+ actions.scheduleLearningBackfillPoll()
+ },
+ loadSettingsFailure: () => {
+ // A failed poll must not end polling, or the block keeps a stale running state.
+ actions.scheduleLearningBackfillPoll()
+ },
+ scheduleLearningBackfillPoll: () => {
+ if (values.settings?.learning_backfill?.status !== 'running') {
+ cache.disposables.dispose('learningBackfillPoll')
+ return
+ }
+ cache.disposables.add(() => {
+ const timer = window.setTimeout(() => {
+ // A poll during a switch write would undo its optimistic value. The write reloads on its own.
+ if (!values.settingsSaving) {
+ actions.loadSettings()
+ }
+ }, LEARNING_BACKFILL_POLL_MS)
+ return () => window.clearTimeout(timer)
+ }, 'learningBackfillPoll')
+ },
setLearnFromSupportEnabled: async ({ enabled }) => {
// Reducers run first, so `values.settings` is already the optimistic value.
const previous =
@@ -95,6 +139,22 @@ export const businessKnowledgeSettingsLogic = kea<businessKnowledgeSettingsLogic
}
posthog.capture('business knowledge learn from support toggled', { enabled })
},
+ startLearningBackfill: async () => {
+ try {
+ const updated = await api.businessKnowledgeLearningBackfillCreate(String(ApiConfig.getCurrentTeamId()))
+ actions.loadSettingsSuccess(updated)
+ } catch (error) {
+ lemonToast.error(
+ (error instanceof ApiError && error.detail) ||
+ 'Could not start learning from past tickets. Try again.'
+ )
+ return
+ } finally {
+ actions.startLearningBackfillDone()
+ }
+ lemonToast.success('Learning from past tickets. New knowledge shows up in your sources as it is found.')
+ posthog.capture('business knowledge learning backfill started')
+ },
})),
afterMount(({ actions, values }) => {
if (!values.settings) {
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index ae39e1f2feba..6c020a0cbfd7 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -21398,11 +21398,46 @@ export namespace Schemas {
Zip: 'zip',
} as const;
+ /**
+ * * `running` - Reading past tickets
+ * * `completed` - Read every past ticket
+ */
+ export type LearningBackfillStatusEnum = typeof LearningBackfillStatusEnum[keyof typeof LearningBackfillStatusEnum];
+
+
+ export const LearningBackfillStatusEnum = {
+ Running: 'running',
+ Completed: 'completed',
+ } as const;
+
+ export interface LearningBackfillProgress {
+ /** `running` while PostHog reads past tickets. `completed` once every ticket in the window is read.
+ *
+ * * `running` - Reading past tickets
+ * * `completed` - Read every past ticket */
+ status: LearningBackfillStatusEnum;
+ /** When someone started learning from past tickets. */
+ started_at: string;
+ /**
+ * When every past ticket was read. Null while the run continues.
+ * @nullable
+ */
+ finished_at: string | null;
+ /** Tickets analyzed since the run started, including tickets from the regular 7-day pass. */
+ tickets_read: number;
+ /** Tickets that are being analyzed now. */
+ tickets_in_progress: number;
+ /** Analyzed tickets that added a learned source to business knowledge. */
+ knowledge_created: number;
+ }
+
export interface BusinessKnowledgeSettings {
/** When true, PostHog learns reusable knowledge from public human replies on resolved support tickets. Requires Support to be enabled for this environment. */
learn_from_support_enabled: boolean;
/** Whether Support is enabled for this environment. Learning cannot be turned on while this is false. */
readonly support_enabled: boolean;
+ /** The last run of learning from past tickets. Null when none ran since learning was turned on. */
+ readonly learning_backfill: LearningBackfillProgress | null;
}
/**