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.3 KB
Raw Blame
"""Facade for warehouse_suggestions."""

from collections.abc import Sequence
from dataclasses import asdict
from typing import TYPE_CHECKING
from uuid import UUID

from posthog.paging import Page, PageRequest
from posthog.queryset_paging import select_page

from products.warehouse_sources.backend.facade.api import source_locations_for_tables
from products.warehouse_sources.backend.facade.contracts import TableSourceLocation

from ..logic import accept, assignment, suggestions
from ..logic.access import CATALOG_KINDS, SubjectAccess, readable_table_ids, visible_suggestions
from ..logic.analytics import SuggestionOutcome, report_outcomes
from ..logic.flags import is_warehouse_suggestions_enabled
from ..logic.payloads import payload_from_json, payload_view, source_table_ids
from ..logic.rules import RULES
from ..models import WarehouseSuggestion, WarehouseSuggestionTeamConfig
from .contracts import (
    AcceptOptions,
    CatalogEditAccessRequiredError,
    SubjectEditAccessRequiredError,
    SubjectKinds,
    Suggestion,
    SuggestionDraft,
    SuggestionNotFoundError,
    SuggestionPayloadView,
    SuggestionReviewer,
    SuggestionStatus,
)
from .enums import (
    WarehouseSuggestionAssetOutcome,
    WarehouseSuggestionDismissalReason,
    WarehouseSuggestionKind,
    WarehouseSuggestionStatus,
    WarehouseSuggestionSubjectKind,
    WarehouseSuggestionSurface,
)

if TYPE_CHECKING:
    from posthog.models import Team, User

    from products.access_control.backend.facade.user_access_control import UserAccessControl

__all__ = [
    "accept_suggestion",
    "assign_suggestion",
    "dismiss_suggestion",
    "get_suggestion",
    "is_warehouse_suggestions_enabled",
    "list_suggestions",
    "resume_suggestion",
    "suggestion_status",
    "upsert_suggestions",
]


def upsert_suggestions(team_id: int, drafts: Sequence[SuggestionDraft]) -> None:
    suggestions.upsert_suggestions(team_id, drafts)


def list_suggestions(
    team_id: int,
    user_access_control: "UserAccessControl",
    *,
    kind: WarehouseSuggestionKind | None,
    status: WarehouseSuggestionStatus | None,
    subject_id: UUID | None,
    assignee_id: int | None = None,
    subject_kinds: SubjectKinds,
    page: PageRequest,
) -> Page[Suggestion]:
    visible, access = visible_suggestions(
        team_id,
        user_access_control,
        kind=kind,
        status=status,
        subject_id=subject_id,
        assignee_id=assignee_id,
        subject_kinds=subject_kinds,
    )
    rows = select_page(visible, page)
    return Page(results=_to_contracts(team_id, user_access_control, rows.results, access), count=rows.count)


def suggestion_status(team_id: int) -> SuggestionStatus:
    config = WarehouseSuggestionTeamConfig.objects.filter(team_id=team_id).first() or WarehouseSuggestionTeamConfig()
    return SuggestionStatus(
        enabled=config.enabled,
        eligible=config.eligible,
        days_with_data=config.days_with_data,
        window_days=RULES.window_days,
        paused_reason=config.paused_reason,
        refreshed_at=config.last_run_at,
    )


def get_suggestion(
    team_id: int,
    user_access_control: "UserAccessControl",
    suggestion_id: UUID,
    *,
    subject_kinds: SubjectKinds,
) -> Suggestion:
    row, access = _visible_suggestion(team_id, user_access_control, suggestion_id, subject_kinds)
    return _single_contract(team_id, user_access_control, row, access)


def dismiss_suggestion(
    team: "Team",
    user_access_control: "UserAccessControl",
    suggestion_id: UUID,
    *,
    user: "User",
    reason: WarehouseSuggestionDismissalReason,
    note: str | None,
    subject_kinds: SubjectKinds,
    surface: WarehouseSuggestionSurface | None = None,
) -> Suggestion:
    row, access = _actionable_suggestion(team.pk, user_access_control, suggestion_id, subject_kinds)
    dismissed = suggestions.transition_to(
        row.id,
        team.pk,
        WarehouseSuggestionStatus.DISMISSED,
        user_id=user.id,
        reason=reason,
        note=note,
        transitions=suggestions.HUMAN_TRANSITIONS,
    )
    report_outcomes(SuggestionOutcome.DISMISSED, [dismissed], team=team, user=user, properties={"surface": surface})
    return _single_contract(team.pk, user_access_control, dismissed, access)


def resume_suggestion(
    team: "Team",
    user_access_control: "UserAccessControl",
    suggestion_id: UUID,
    *,
    user: "User",
    subject_kinds: SubjectKinds,
) -> Suggestion:
    row, access = _actionable_suggestion(team.pk, user_access_control, suggestion_id, subject_kinds)
    resumed = suggestions.transition_to(
        row.id, team.pk, WarehouseSuggestionStatus.PROPOSED, user_id=user.id, transitions=suggestions.HUMAN_TRANSITIONS
    )
    report_outcomes(SuggestionOutcome.RESUMED, [resumed], team=team, user=user)
    return _single_contract(team.pk, user_access_control, resumed, access)


def assign_suggestion(
    team: "Team",
    user_access_control: "UserAccessControl",
    suggestion_id: UUID,
    *,
    user: "User",
    assignee_id: int | None,
    subject_kinds: SubjectKinds,
) -> Suggestion:
    row, access = _actionable_suggestion(team.pk, user_access_control, suggestion_id, subject_kinds)
    result = assignment.assign(team, row.id, assignee_id, assigned_by=user)
    if result.changed:
        report_outcomes(
            SuggestionOutcome.ASSIGNED,
            [result.suggestion],
            team=team,
            user=user,
            properties={"unassigned": assignee_id is None, "self_assigned": assignee_id == user.id},
        )
    return _single_contract(team.pk, user_access_control, result.suggestion, access)


def accept_suggestion(
    team: "Team",
    user_access_control: "UserAccessControl",
    suggestion_id: UUID,
    *,
    user: "User",
    options: AcceptOptions,
    was_impersonated: bool,
    subject_kinds: SubjectKinds,
    surface: WarehouseSuggestionSurface | None = None,
) -> Suggestion:
    row, access = _actionable_suggestion(team.pk, user_access_control, suggestion_id, subject_kinds)
    if not options.delete_view:
        _require_catalog_edit_access(row, user_access_control)
    outcome = accept.accept(
        team.pk,
        row.id,
        accept.AcceptRequest(team=team, user=user, options=options, was_impersonated=was_impersonated),
    )
    if outcome.newly_accepted:
        report_outcomes(
            SuggestionOutcome.ACCEPTED,
            [outcome.suggestion],
            team=team,
            user=user,
            properties={"changed_fields": list(outcome.changed_fields), "surface": surface, **asdict(outcome.savings)},
        )
    return _single_contract(team.pk, user_access_control, outcome.suggestion, access)


def _actionable_suggestion(
    team_id: int,
    user_access_control: "UserAccessControl",
    suggestion_id: UUID,
    subject_kinds: SubjectKinds,
) -> tuple[WarehouseSuggestion, SubjectAccess]:
    row, access = _visible_suggestion(team_id, user_access_control, suggestion_id, subject_kinds)
    if not access.can_act_on(row):
        raise SubjectEditAccessRequiredError(WarehouseSuggestionSubjectKind(row.subject_kind))
    return row, access


def _require_catalog_edit_access(row: WarehouseSuggestion, user_access_control: "UserAccessControl") -> None:
    if row.kind not in CATALOG_KINDS:
        return
    if not user_access_control.check_access_level_for_resource("data_catalog", required_level="editor"):
        raise CatalogEditAccessRequiredError()


def _single_contract(
    team_id: int, user_access_control: "UserAccessControl", row: WarehouseSuggestion, access: SubjectAccess
) -> Suggestion:
    (suggestion,) = _to_contracts(team_id, user_access_control, [row], access)
    return suggestion


def _visible_suggestion(
    team_id: int,
    user_access_control: "UserAccessControl",
    suggestion_id: UUID,
    subject_kinds: SubjectKinds,
) -> tuple[WarehouseSuggestion, SubjectAccess]:
    visible, access = visible_suggestions(
        team_id, user_access_control, suggestion_id=suggestion_id, subject_kinds=subject_kinds
    )
    row = visible.first()
    if row is None:
        raise SuggestionNotFoundError(suggestion_id)
    return row, access


def _to_contracts(
    team_id: int,
    user_access_control: "UserAccessControl",
    rows: list[WarehouseSuggestion],
    access: SubjectAccess,
) -> list[Suggestion]:
    stored = {
        row.id: payload_from_json(WarehouseSuggestionKind(row.kind), row.payload_version, row.payload) for row in rows
    }
    readable = readable_table_ids(team_id, user_access_control, source_table_ids(stored.values()))
    table_ids = {row.subject_id for row in rows if row.subject_kind == WarehouseSuggestionSubjectKind.TABLE}
    locations = source_locations_for_tables(team_id, table_ids)
    return [
        _to_contract(row, access, payload_view(stored[row.id], readable), locations.get(row.subject_id)) for row in rows
    ]


def _to_contract(
    row: WarehouseSuggestion,
    access: SubjectAccess,
    payload: SuggestionPayloadView,
    location: TableSourceLocation | None,
) -> Suggestion:
    return Suggestion(
        id=row.id,
        kind=WarehouseSuggestionKind(row.kind),
        subject_kind=WarehouseSuggestionSubjectKind(row.subject_kind),
        subject_id=row.subject_id,
        payload=payload,
        payload_version=row.payload_version,
        evidence=row.evidence,
        evidence_window_start=row.evidence_window_start,
        evidence_window_end=row.evidence_window_end,
        last_seen_at=row.last_seen_at,
        status=WarehouseSuggestionStatus(row.status),
        surfaced_at=row.surfaced_at,
        reviewed_by=_to_user(row.reviewed_by),
        reviewed_at=row.reviewed_at,
        dismissal_reason=WarehouseSuggestionDismissalReason(row.dismissal_reason) if row.dismissal_reason else None,
        dismissal_note=row.dismissal_note,
        created_asset=row.created_asset,
        asset_outcome=WarehouseSuggestionAssetOutcome(row.asset_outcome) if row.asset_outcome else None,
        realized_seconds_saved_per_month=row.realized_seconds_saved_per_month,
        realized_bytes_saved_per_month=row.realized_bytes_saved_per_month,
        can_act=access.can_act_on(row),
        subject_source_id=location.source_id if location else None,
        subject_schema_id=location.schema_id if location else None,
        assignee=_to_user(row.assignee),
    )


def _to_user(user: "User | None") -> SuggestionReviewer | None:
    if user is None:
        return None
    return SuggestionReviewer(id=user.id, first_name=user.first_name, email=user.email)