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.

10.1 KB
Raw Blame
from django.core.exceptions import ValidationError
from django.db import models

from posthog.models.scoping.root_mixin import TeamScopedRootMixin
from posthog.models.utils import CreatedMetaFields, UpdatedMetaFields, UUIDModel


def default_period() -> dict:
    # Default lookback: the brief covers the last 7 days, compared against the 7 days before.
    return {"type": "last_n_days", "days": 7}


class ResourceType(models.TextChoices):
    INSIGHT = "insight"
    DASHBOARD = "dashboard"
    ANNOTATION = "annotation"
    EXPERIMENT = "experiment"
    ALERT = "alert"
    SUBSCRIPTION = "subscription"
    # Events have no Django model, so an event link carries only the cached columns (no FK).
    EVENT = "event"


class ActionType(models.TextChoices):
    ADVISORY = "advisory"
    CREATE_PR = "create_pr"
    INSTRUMENT_EVENT = "instrument_event"
    CREATE_INSIGHT = "create_insight"


class ActionStatus(models.TextChoices):
    PROPOSED = "proposed"
    EXECUTING = "executing"
    DONE = "done"
    FAILED = "failed"


def default_action() -> dict:
    # Forward-compatible envelope for a future action executor. The model emits only a summary
    # today; persist wraps it via build_action, so every opportunity starts as a proposed advisory.
    return {"type": ActionType.ADVISORY.value, "summary": "", "params": {}, "status": ActionStatus.PROPOSED.value}


def build_action(summary: str) -> dict:
    """Wrap the LLM's free-text next step in the structured advisory envelope."""
    return {
        "type": ActionType.ADVISORY.value,
        "summary": summary,
        "params": {},
        "status": ActionStatus.PROPOSED.value,
    }


class PulseModel(TeamScopedRootMixin, CreatedMetaFields, UpdatedMetaFields, UUIDModel):
    """Abstract base for pulse models: fail-closed team scoping + lock-free hot-table FKs."""

    # `objects` (TeamScopedManager) inherited from TeamScopedRootMixin stays fail-closed for
    # explicit user code. `all_teams` is the unscoped sibling for Django framework internals
    # (admin querysets, related-object access, prefetch_related) that must not filter by team;
    # `default_manager_name` routes `_default_manager` / `_base_manager` there.
    all_teams = models.Manager()  # noqa: DJ012

    # FKs to the hot posthog_team / posthog_user tables use db_constraint=False so creating the
    # tables takes no lock on those parents. created_by overrides CreatedMetaFields for the same reason.
    team = models.ForeignKey("posthog.Team", on_delete=models.CASCADE, db_constraint=False)
    created_by = models.ForeignKey(
        "posthog.User", on_delete=models.SET_NULL, null=True, blank=True, db_constraint=False
    )

    class Meta:
        abstract = True
        default_manager_name = "all_teams"


class BriefConfig(PulseModel):
    name = models.CharField(max_length=400)
    # Free text steering the LLM; capped because it is interpolated into the synthesis prompt.
    focus_prompt = models.TextField(blank=True, default="", max_length=2000)
    # Shape: BriefAnchorsSerializer (api/brief.py) — {"dashboards": [int], "insights": [short_id str]}
    anchors = models.JSONField(default=dict)
    # Per-config tunables overriding config.py defaults; shape/ranges: config.BriefSettings.
    settings = models.JSONField(default=dict)
    enabled = models.BooleanField(default=True)
    # Soft delete: configs are recoverable and brief history keeps pointing at them.
    deleted = models.BooleanField(default=False)


class ProductBrief(PulseModel):
    class Status(models.TextChoices):
        GENERATING = "generating"
        READY = "ready"
        QUIET = "quiet"
        FAILED = "failed"

    class Trigger(models.TextChoices):
        ON_DEMAND = "on_demand"
        SCHEDULED = "scheduled"

    # Configs soft-delete in normal operation; a hard delete (e.g. via admin) is deliberate and
    # cascades to the briefs generated for that config rather than orphaning them.
    config = models.ForeignKey(BriefConfig, on_delete=models.CASCADE, null=True, blank=True)
    status = models.CharField(max_length=20, choices=Status.choices, default=Status.GENERATING)
    trigger = models.CharField(max_length=20, choices=Trigger.choices)
    # Period spec resolved to explicit dates in-activity; shape: {"type": "last_n_days", "days": 7}
    # or {"type": "since_last_run"}. See temporal/activities.resolve_period.
    period = models.JSONField(default=default_period)
    # Shape: list[SectionOut] — see generation/schemas.py (the LLM structured-output schema).
    sections = models.JSONField(default=list)
    sources_used = models.JSONField(default=list)
    error = models.TextField(null=True, blank=True)
    feedback = models.JSONField(default=dict)

    class Meta(PulseModel.Meta):
        # The stale-brief reaper sweeps GENERATING rows cross-team every few minutes on an
        # append-only table; a partial index keeps that O(stranded rows), not O(all briefs ever).
        indexes = [
            models.Index(
                fields=["updated_at"],
                name="pulse_brief_generating_idx",
                condition=models.Q(status="generating"),
            )
        ]


class Opportunity(PulseModel):
    class Kind(models.TextChoices):
        BUILD = "build"
        FIX = "fix"
        INSTRUMENT = "instrument"

    class Status(models.TextChoices):
        OPEN = "open"
        DISMISSED = "dismissed"
        ACTED = "acted"
        RESOLVED = "resolved"

    # persist always sets this; a hard-deleted brief cascades to the opportunities it first surfaced.
    first_seen_brief = models.ForeignKey(ProductBrief, on_delete=models.CASCADE)
    kind = models.CharField(max_length=20, choices=Kind.choices)
    status = models.CharField(max_length=20, choices=Status.choices, default=Status.OPEN)
    title = models.CharField(max_length=400)
    summary = models.TextField()
    # Structured action envelope; shape: default_action(). Advisory-only today; forward-compatible
    # for a future executor. The LLM still emits a free-text summary (OpportunityOut.suggested_action)
    # that persist wraps via build_action.
    action = models.JSONField(default=default_action)
    # {"insight_short_id": str, "series_index": int} | null
    metric_ref = models.JSONField(null=True, blank=True)
    # snapshot of metric value(s) at creation, for the future impact loop
    baseline = models.JSONField(null=True, blank=True)
    fingerprint = models.CharField(max_length=512)
    feedback = models.JSONField(default=dict)

    class Meta(PulseModel.Meta):
        # Dedup race guard: concurrent persists can't double-insert a fingerprint (persist
        # bulk_creates with ignore_conflicts). The unique index doubles as the lookup index.
        constraints = [models.UniqueConstraint(fields=["team", "fingerprint"], name="pulse_opp_team_fp_unique")]


class ResourceLink(PulseModel):
    """Evidence link from an opportunity to a PostHog resource it cites.

    One opportunity has many links. Per-type nullable FKs (not a GenericForeignKey, which is
    rejected repo-wide) point at the cited resource; the cached `resource_type`/`ref`/`label`/`url`
    columns keep the link meaningful for events (no Django model) and after a FK nulls.
    """

    # A hard-deleted brief cascades to its opportunities, which cascade to their links.
    opportunity = models.ForeignKey(Opportunity, on_delete=models.CASCADE, related_name="resource_links")

    # Deliberately SET_NULL, not CASCADE or an exactly-one constraint like DashboardTile: an
    # opportunity's evidence history must survive the cited resource being deleted. These target
    # non-hot tables, so real DB constraints are fine (no db_constraint=False).
    insight = models.ForeignKey(
        "product_analytics.Insight", on_delete=models.SET_NULL, null=True, blank=True, related_name="+"
    )
    dashboard = models.ForeignKey(
        "dashboards.Dashboard", on_delete=models.SET_NULL, null=True, blank=True, related_name="+"
    )
    annotation = models.ForeignKey(
        "annotations.Annotation", on_delete=models.SET_NULL, null=True, blank=True, related_name="+"
    )
    experiment = models.ForeignKey(
        "experiments.Experiment", on_delete=models.SET_NULL, null=True, blank=True, related_name="+"
    )
    alert = models.ForeignKey(
        "alerts.AlertConfiguration", on_delete=models.SET_NULL, null=True, blank=True, related_name="+"
    )
    subscription = models.ForeignKey(
        "subscriptions.Subscription", on_delete=models.SET_NULL, null=True, blank=True, related_name="+"
    )

    resource_type = models.CharField(max_length=20, choices=ResourceType.choices)
    # short_id (insight), id (dashboard/annotation/experiment), or event name.
    ref = models.CharField(max_length=400)
    label = models.CharField(max_length=400)
    # Deep link into the app; "" when the ref has no navigable target.
    url = models.CharField(max_length=1000, blank=True, default="")

    # Single source of truth mapping each DB-modeled resource_type to the FK field it populates;
    # EvidenceRef.fk_field and clean() both route through fk_field_for so the mapping lives once.
    _FK_FIELD_BY_TYPE = {
        ResourceType.INSIGHT: "insight",
        ResourceType.DASHBOARD: "dashboard",
        ResourceType.ANNOTATION: "annotation",
        ResourceType.EXPERIMENT: "experiment",
        ResourceType.ALERT: "alert",
        ResourceType.SUBSCRIPTION: "subscription",
    }

    @classmethod
    def fk_field_for(cls, resource_type: "ResourceType | str") -> str | None:
        """The FK field a resource_type must populate, or None if it has no model (events)."""
        return cls._FK_FIELD_BY_TYPE.get(ResourceType(resource_type)) if resource_type else None

    def clean(self) -> None:
        # No hard CheckConstraint: SET_NULL nulls the FK when a resource is deleted, which would
        # violate an "FK-matching-resource_type is set" constraint even though the link is still
        # valid history. So this is enforced at write time (creation), not by the DB forever.
        super().clean()
        fk_field = self.fk_field_for(self.resource_type)
        if fk_field is not None and getattr(self, f"{fk_field}_id") is None:
            raise ValidationError(f"resource_type '{self.resource_type}' requires the '{fk_field}' FK to be set.")