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.

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.md
index 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.tsx
index 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.py
const MIN_RECALCULATION_GAP_HOURS = 6
const 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.txt
index 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_changed
post_delete:products.cohorts.backend.models.dependencies.clear_team_cohort_dependency_cache
post_delete:products.cohorts.backend.models.dependencies.cohort_deleted
post_delete:products.event_definitions.backend.models.event_definition._invalidate_default_event_info_on_delete
+post_delete:products.experiments.backend.facade.change_signals._notify_experiment_deleted
post_delete:products.feature_flags.backend.flags_cache.cohort_changed_flags_cache
post_delete:products.feature_flags.backend.flags_cache.evaluation_context_changed_flags_cache
post_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.create
post_save:products.early_access_features.backend.signals.create_waitlist_survey_on_concept_stage
post_save:products.event_definitions.backend.models.event_definition._invalidate_default_event_info_on_save
post_save:products.event_definitions.backend.models.property_definition._invalidate_has_person_email_on_save
+post_save:products.experiments.backend.facade.change_signals._notify_experiment_saved
post_save:products.feature_flags.backend.flag_version_sync.bump_dependent_flag_versions_on_flag_definition_change
post_save:products.feature_flags.backend.flag_version_sync.bump_flag_versions_on_cohort_definition_change
post_save:products.feature_flags.backend.flags_cache.cohort_changed_flags_cache
diff --git a/products/experiments/backend/apps.py b/products/experiments/backend/apps.py
index 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: PLC0415
import products.experiments.backend.activity_logging # noqa: F401, PLC0415
+ import products.experiments.backend.facade.change_signals # noqa: F401, PLC0415
from products.experiments.backend.models.experiment import Experiment # noqa: PLC0415
register_mixin_model("experiment", Experiment)
diff --git a/products/experiments/backend/facade/change_signals.py b/products/experiments/backend/facade/change_signals.py
new file mode 100644
index 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.py
index ae1ce8c0ffa3..e3d57444e5fb 100644
--- a/products/experiments/backend/facade/contracts.py
+++ b/products/experiments/backend/facade/contracts.py
@@ -511,3 +511,22 @@ class RunningExperiment:
name: str
started_at: datetime
flag_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: datetime
diff --git a/products/experiments/backend/facade/enums.py b/products/experiments/backend/facade/enums.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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_extension
from products.ai_observability.backend.facade.api import mentions_evaluation_pass_markers
from products.analytics_platform.backend.lazy_computation.lazy_computation_executor import LazyComputationResult
+from products.experiments.backend.facade.enums import PrecomputeSkipReason
from products.experiments.backend.hogql_queries import MULTIPLE_VARIANT_KEY, get_baseline_variant_key
from products.experiments.backend.hogql_queries.base_query_utils import experiment_window, experiment_window_end
from 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 PrecomputeSkipReason
from 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.py
index 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_execu
parse_ttl_schedule,
)
from products.cohorts.backend.models.cohort import Cohort
+from products.experiments.backend.facade.enums import PrecomputeSkipReason
from products.experiments.backend.hogql_queries.experiment_query_builder import ExperimentQueryBuilder
from products.experiments.backend.hogql_queries.exposure_query_logic import has_activation_config
-from products.experiments.backend.hogql_queries.types import PrecomputeSkipReason
from products.experiments.backend.models.experiment import Experiment
from products.experiments.backend.models.team_experiments_config import TeamExperimentsConfig
diff --git a/products/experiments/backend/hogql_queries/types.py b/products/experiments/backend/hogql_queries/types.py
index 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.py
index 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 ModelActivityMixin
from posthog.models.organization import Organization
from 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_HOURS
RECALCULATION_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.py
index 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 User
from posthog.test.persons import create_person
from 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_changed
from 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)