:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
refactor(experiments): add facade capability modules and change signal (#125393)
Andersd0701d7f4b46
diff --git a/.agents/skills/analyzing-experiment-query-performance/SKILL.md b/.agents/skills/analyzing-experiment-query-performance/SKILL.mdindex 15d23369989e..8cba843a3d76 100644--- a/.agents/skills/analyzing-experiment-query-performance/SKILL.md+++ b/.agents/skills/analyzing-experiment-query-performance/SKILL.md@@ -190,7 +190,7 @@ Check enablement in the UI, or in code via `TeamExperimentsConfig.experiment_pre- `experiment_precompute_skip_reason` — set on reads that **never attempted** precompute:`override_direct`, `team_disabled`, `min_runtime`, `activation_config`, `cohort_not_calculated`,`data_warehouse`, `group_aggregation`- (the `PrecomputeSkipReason` enum in `products/experiments/backend/hogql_queries/types.py`).+ (the `PrecomputeSkipReason` enum in `products/experiments/backend/facade/enums.py`).**An empty skip reason on a `direct_scan` read means precompute was attempted but the data wasn't ready**(build failed or too slow) — that read paid for the build _and_ the full scan.This is the bucket to watch; it should stay near zero.diff --git a/frontend/src/scenes/settings/environment/ExperimentRecalculationTime.tsx b/frontend/src/scenes/settings/environment/ExperimentRecalculationTime.tsxindex 5d8e9756276c..7840ac8ecb1e 100644--- a/frontend/src/scenes/settings/environment/ExperimentRecalculationTime.tsx+++ b/frontend/src/scenes/settings/environment/ExperimentRecalculationTime.tsx@@ -14,7 +14,7 @@ import { teamLogic } from '~/scenes/teamLogic'import { experimentsConfigLogic } from './experimentsConfigLogic'const DEFAULT_RECALCULATION_UTC_TIME = '02:00:00'-// Must match MIN_RECALCULATION_GAP_HOURS in products/experiments/backend/models/team_experiments_config.py+// Must match MIN_RECALCULATION_GAP_HOURS in products/experiments/backend/facade/enums.pyconst MIN_RECALCULATION_GAP_HOURS = 6const utcHourFromTimeString = (utcTimeString: string): number => parseInt(utcTimeString.split(':')[0], 10)diff --git a/posthog/test/repo_invariants/setup_receivers_baseline.txt b/posthog/test/repo_invariants/setup_receivers_baseline.txtindex d776d5d1b54c..52609d5eff6b 100644--- a/posthog/test/repo_invariants/setup_receivers_baseline.txt+++ b/posthog/test/repo_invariants/setup_receivers_baseline.txt@@ -104,6 +104,7 @@ post_delete:products.cohorts.backend.models.cohort.cohort_people_changedpost_delete:products.cohorts.backend.models.dependencies.clear_team_cohort_dependency_cachepost_delete:products.cohorts.backend.models.dependencies.cohort_deletedpost_delete:products.event_definitions.backend.models.event_definition._invalidate_default_event_info_on_delete+post_delete:products.experiments.backend.facade.change_signals._notify_experiment_deletedpost_delete:products.feature_flags.backend.flags_cache.cohort_changed_flags_cachepost_delete:products.feature_flags.backend.flags_cache.evaluation_context_changed_flags_cachepost_delete:products.feature_flags.backend.flags_cache.experiment_changed_flags_cache@@ -223,6 +224,7 @@ post_save:products.data_warehouse.backend.models.revenue_analytics_config.createpost_save:products.early_access_features.backend.signals.create_waitlist_survey_on_concept_stagepost_save:products.event_definitions.backend.models.event_definition._invalidate_default_event_info_on_savepost_save:products.event_definitions.backend.models.property_definition._invalidate_has_person_email_on_save+post_save:products.experiments.backend.facade.change_signals._notify_experiment_savedpost_save:products.feature_flags.backend.flag_version_sync.bump_dependent_flag_versions_on_flag_definition_changepost_save:products.feature_flags.backend.flag_version_sync.bump_flag_versions_on_cohort_definition_changepost_save:products.feature_flags.backend.flags_cache.cohort_changed_flags_cachediff --git a/products/experiments/backend/apps.py b/products/experiments/backend/apps.pyindex 8ac6bc163d1e..44ee53940e74 100644--- a/products/experiments/backend/apps.py+++ b/products/experiments/backend/apps.py@@ -7,10 +7,11 @@ class ExperimentsConfig(AppConfig):label = "experiments"def ready(self) -> None:- # Registers activity signal receivers after the app registry is ready.+ # Registers the activity and change signal receivers after the app registry is ready.from posthog.models.file_system.unfiled_file_saver import register_mixin_model # noqa: PLC0415import products.experiments.backend.activity_logging # noqa: F401, PLC0415+ import products.experiments.backend.facade.change_signals # noqa: F401, PLC0415from products.experiments.backend.models.experiment import Experiment # noqa: PLC0415register_mixin_model("experiment", Experiment)diff --git a/products/experiments/backend/facade/change_signals.py b/products/experiments/backend/facade/change_signals.pynew file mode 100644index 000000000000..082d50b2ebc0--- /dev/null+++ b/products/experiments/backend/facade/change_signals.py@@ -0,0 +1,52 @@+from collections.abc import Callable+from typing import Any++from django.db.models.signals import post_delete, post_save+from django.dispatch import Signal++from products.experiments.backend.facade.contracts import ExperimentChanged+from products.experiments.backend.models.experiment import Experiment++# Sent with `change=`, an `ExperimentChanged`, after every save and delete of an experiment, so other products react+# to it without importing the experiments model.+experiment_changed = Signal()+++def connect_experiment_changed(receiver: Callable[..., object], *, dispatch_uid: str) -> None:+ """``receiver`` gets ``change=``, an ``ExperimentChanged``, after each save and each hard delete of an+ experiment. A soft delete is a save with ``change.deleted`` set.++ The receiver runs synchronously right after the row is written, inside the caller's transaction when there is+ one, like a ``post_save`` receiver. An exception it raises propagates out of ``save()`` or ``delete()``. Work that+ must wait for the commit goes through ``transaction.on_commit``."""+ experiment_changed.connect(receiver, dispatch_uid=dispatch_uid)+++def _change(experiment: Experiment, *, created: bool, deleted: bool) -> ExperimentChanged:+ return ExperimentChanged(+ team_id=experiment.team_id,+ experiment_id=experiment.id,+ created=created,+ deleted=deleted,+ name=experiment.name,+ description=experiment.description,+ archived=experiment.archived,+ created_at=experiment.created_at,+ updated_at=experiment.updated_at,+ )+++# Both receivers use `send`, not `send_robust`, so a receiver error propagates out of `save()` or `delete()`, as an+# error in a receiver of the model signal does.+def _notify_experiment_saved(sender: Any, instance: Experiment, created: bool, **kwargs: Any) -> None:+ # The column is nullable, and NULL reads as not deleted.+ change = _change(instance, created=created, deleted=bool(instance.deleted))+ experiment_changed.send(sender=ExperimentChanged, change=change)+++def _notify_experiment_deleted(sender: Any, instance: Experiment, **kwargs: Any) -> None:+ experiment_changed.send(sender=ExperimentChanged, change=_change(instance, created=False, deleted=True))+++post_save.connect(_notify_experiment_saved, sender=Experiment, dispatch_uid="experiments.experiment_changed.save")+post_delete.connect(_notify_experiment_deleted, sender=Experiment, dispatch_uid="experiments.experiment_changed.delete")diff --git a/products/experiments/backend/facade/contracts.py b/products/experiments/backend/facade/contracts.pyindex ae1ce8c0ffa3..e3d57444e5fb 100644--- a/products/experiments/backend/facade/contracts.py+++ b/products/experiments/backend/facade/contracts.py@@ -511,3 +511,22 @@ class RunningExperiment:name: strstarted_at: datetimeflag_key: str+++@frozen+class ExperimentChanged:+ """One save or delete of an experiment, as `connect_experiment_changed` receivers get it."""++ team_id: int+ experiment_id: int+ # True only on the save that inserted the row.+ created: bool+ # True on every save that leaves the experiment soft-deleted, and on every hard delete of the row.+ deleted: bool+ # The values the write left on the experiment, so a receiver that mirrors the experiment elsewhere, such as the+ # Vercel sync, does not read the row back.+ name: str+ description: str | None+ archived: bool+ created_at: datetime+ updated_at: datetimediff --git a/products/experiments/backend/facade/enums.py b/products/experiments/backend/facade/enums.pynew file mode 100644index 000000000000..4313903d6ae6--- /dev/null+++ b/products/experiments/backend/facade/enums.py@@ -0,0 +1,22 @@+"""Exported enums and constants for experiments."""++from enum import StrEnum++MAX_RECALCULATION_TIMES = 2+# frontend/src/scenes/settings/environment/ExperimentRecalculationTime.tsx repeats this value, so change both together.+MIN_RECALCULATION_GAP_HOURS = 6+++class PrecomputeSkipReason(StrEnum):+ """Why a metric read never attempted precompute. Tagged on the query as+ `experiment_precompute_skip_reason` and counted per reason by the+ `precompute_overview` staff endpoint, which iterates this enum. A reason+ missing here is invisible in the staff tooling."""++ OVERRIDE_DIRECT = "override_direct"+ TEAM_DISABLED = "team_disabled"+ MIN_RUNTIME = "min_runtime"+ ACTIVATION_CONFIG = "activation_config"+ COHORT_NOT_CALCULATED = "cohort_not_calculated"+ DATA_WAREHOUSE = "data_warehouse"+ GROUP_AGGREGATION = "group_aggregation"diff --git a/products/experiments/backend/facade/max_tools.py b/products/experiments/backend/facade/max_tools.pynew file mode 100644index 000000000000..fc778f4eaf63--- /dev/null+++ b/products/experiments/backend/facade/max_tools.py@@ -0,0 +1,13 @@+"""Facade re-exports for experiments Max tools.++The assistant's agent-mode presets register these tool classes. Re-exporting them in a+dedicated submodule keeps ``facade/api.py`` free of the heavy ``ee.hogai.tool`` import,+so config-only consumers don't drag it onto the ``django.setup()`` path.+"""++from products.experiments.backend.max_tools import CreateExperimentTool, ExperimentSummaryTool++__all__ = [+ "CreateExperimentTool",+ "ExperimentSummaryTool",+]diff --git a/products/experiments/backend/facade/queries.py b/products/experiments/backend/facade/queries.pynew file mode 100644index 000000000000..aa34d7df6f17--- /dev/null+++ b/products/experiments/backend/facade/queries.py@@ -0,0 +1,17 @@+"""Facade re-exports for experiments HogQL query runners.++Core's query-runner registry (``posthog/hogql_queries/query_runner.py``) dispatches+on query ``kind`` and constructs these runners by class identity, and the insight+actors runner checks for ``ExperimentQueryRunner`` with ``isinstance``. Re-exporting+the classes keeps that coupling at the facade boundary, while the heavy HogQL imports+stay out of ``facade/api.py`` so config-only consumers don't drag them onto the+``django.setup()`` path.+"""++from products.experiments.backend.hogql_queries.experiment_exposures_query_runner import ExperimentExposuresQueryRunner+from products.experiments.backend.hogql_queries.experiment_query_runner import ExperimentQueryRunner++__all__ = [+ "ExperimentExposuresQueryRunner",+ "ExperimentQueryRunner",+]diff --git a/products/experiments/backend/hogql_queries/experiment_query_runner.py b/products/experiments/backend/hogql_queries/experiment_query_runner.pyindex 9575609d61d8..bf2efe1cac5a 100644--- a/products/experiments/backend/hogql_queries/experiment_query_runner.py+++ b/products/experiments/backend/hogql_queries/experiment_query_runner.py@@ -41,6 +41,7 @@ from posthog.models.team.extensions import get_or_create_team_extensionfrom products.ai_observability.backend.facade.api import mentions_evaluation_pass_markersfrom products.analytics_platform.backend.lazy_computation.lazy_computation_executor import LazyComputationResult+from products.experiments.backend.facade.enums import PrecomputeSkipReasonfrom products.experiments.backend.hogql_queries import MULTIPLE_VARIANT_KEY, get_baseline_variant_keyfrom products.experiments.backend.hogql_queries.base_query_utils import experiment_window, experiment_window_endfrom products.experiments.backend.hogql_queries.cuped_config import get_cuped_config@@ -64,7 +65,6 @@ from products.experiments.backend.hogql_queries.precompute_policy import (ensure_exposures_precomputed,team_precompute_skip_reason,)-from products.experiments.backend.hogql_queries.types import PrecomputeSkipReasonfrom products.experiments.backend.hogql_queries.utils import (aggregate_variants_across_breakdowns,get_bayesian_experiment_result,diff --git a/products/experiments/backend/hogql_queries/precompute_policy.py b/products/experiments/backend/hogql_queries/precompute_policy.pyindex 7c04e947b9ae..9253e3fdc1cb 100644--- a/products/experiments/backend/hogql_queries/precompute_policy.py+++ b/products/experiments/backend/hogql_queries/precompute_policy.py@@ -22,9 +22,9 @@ from products.analytics_platform.backend.lazy_computation.lazy_computation_execuparse_ttl_schedule,)from products.cohorts.backend.models.cohort import Cohort+from products.experiments.backend.facade.enums import PrecomputeSkipReasonfrom products.experiments.backend.hogql_queries.experiment_query_builder import ExperimentQueryBuilderfrom products.experiments.backend.hogql_queries.exposure_query_logic import has_activation_config-from products.experiments.backend.hogql_queries.types import PrecomputeSkipReasonfrom products.experiments.backend.models.experiment import Experimentfrom products.experiments.backend.models.team_experiments_config import TeamExperimentsConfigdiff --git a/products/experiments/backend/hogql_queries/types.py b/products/experiments/backend/hogql_queries/types.pyindex a3b9332bdc85..a164abc8a7e1 100644--- a/products/experiments/backend/hogql_queries/types.py+++ b/products/experiments/backend/hogql_queries/types.py@@ -1,16 +1,3 @@-from enum import StrEnum+from products.experiments.backend.facade.enums import PrecomputeSkipReason--class PrecomputeSkipReason(StrEnum):- """Why a metric read never attempted precompute. Tagged on the query as- `experiment_precompute_skip_reason` and counted per reason by the- `precompute_overview` staff endpoint, which iterates this enum. A reason- missing here is invisible in the staff tooling."""-- OVERRIDE_DIRECT = "override_direct"- TEAM_DISABLED = "team_disabled"- MIN_RUNTIME = "min_runtime"- ACTIVATION_CONFIG = "activation_config"- COHORT_NOT_CALCULATED = "cohort_not_calculated"- DATA_WAREHOUSE = "data_warehouse"- GROUP_AGGREGATION = "group_aggregation"+__all__ = ["PrecomputeSkipReason"]diff --git a/products/experiments/backend/models/team_experiments_config.py b/products/experiments/backend/models/team_experiments_config.pyindex ec90ea77a0f1..892d23050380 100644--- a/products/experiments/backend/models/team_experiments_config.py+++ b/products/experiments/backend/models/team_experiments_config.py@@ -8,8 +8,7 @@ from posthog.models.activity_logging.model_activity import ModelActivityMixinfrom posthog.models.organization import Organizationfrom posthog.models.team import Team-MAX_RECALCULATION_TIMES = 2-MIN_RECALCULATION_GAP_HOURS = 6+from products.experiments.backend.facade.enums import MAX_RECALCULATION_TIMES, MIN_RECALCULATION_GAP_HOURSRECALCULATION_TIME_PATTERN = re.compile(r"^(?:[01]\d|2[0-3]):00:00$")diff --git a/products/experiments/backend/test/test_facade.py b/products/experiments/backend/test/test_facade.pyindex d692105c169e..ccba68e81bb0 100644--- a/products/experiments/backend/test/test_facade.py+++ b/products/experiments/backend/test/test_facade.py@@ -24,9 +24,11 @@ from posthog.models.user import Userfrom posthog.test.persons import create_personfrom products.experiments.backend.facade import api, count_running_experiments_on_feature_flag_called, create_experiment+from products.experiments.backend.facade.change_signals import connect_experiment_changed, experiment_changedfrom products.experiments.backend.facade.contracts import (CreateExperimentInput,EndedExperiment,+ ExperimentChanged,ExperimentValidationError,StoredPrimaryResult,)@@ -306,6 +308,51 @@ class TestHighlightFacts(BaseTest):assert [(e.name, e.flag_key) for e in found] == [(name, listed[name]) for name in expected]+@time_machine.travel("2026-10-28T12:00:00Z", tick=False)+class TestConnectExperimentChanged(BaseTest):+ def test_receiver_gets_every_save_and_delete_inside_the_transaction(self) -> None:+ received: list[ExperimentChanged] = []++ def receiver(*, change: ExperimentChanged, **kwargs: object) -> None:+ received.append(change)++ connect_experiment_changed(receiver, dispatch_uid="test_connect_experiment_changed")+ self.addCleanup(experiment_changed.disconnect, dispatch_uid="test_connect_experiment_changed")++ flag = FeatureFlag.objects.create(team=self.team, key="checkout-flag", created_by=self.user)+ experiment = Experiment.objects.create(+ team=self.team, name="Checkout", description="Shorter checkout", feature_flag=flag+ )+ experiment_id = experiment.id+ experiment.deleted = True+ experiment.save()+ experiment.deleted = False+ experiment.archived = True+ experiment.save()+ experiment.delete()++ def change(*, created: bool, deleted: bool, archived: bool) -> ExperimentChanged:+ return ExperimentChanged(+ team_id=self.team.id,+ experiment_id=experiment_id,+ created=created,+ deleted=deleted,+ name="Checkout",+ description="Shorter checkout",+ archived=archived,+ created_at=timezone.now(),+ updated_at=timezone.now(),+ )++ # BaseTest never commits, so a receiver deferred to the commit would leave this list empty.+ assert received == [+ change(created=True, deleted=False, archived=False),+ change(created=False, deleted=True, archived=False),+ change(created=False, deleted=False, archived=True),+ change(created=False, deleted=True, archived=True),+ ]++class TestCountEnrolledPeople(ClickhouseTestMixin, BaseTest):def _ago(self, days: int) -> datetime:return timezone.now() - timedelta(days=days)