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.

6.9 KB
Raw Blame
"""
Contract types for wizard.

Frozen dataclasses that define what this product exposes.
No Django imports. Used by facade as inputs/outputs.
"""

from dataclasses import dataclass
from datetime import datetime, timedelta
from typing import Any, Literal
from uuid import UUID

from posthog.dataclasses import frozen

from .enums import (
    WizardRunArtifactType,
    WizardRunEnvironment,
    WizardRunStage,
    WizardRunStatus,
    WizardSessionRunPhase,
    WizardSessionTaskStatus,
    WizardTaskStatus,
)

STALE_AFTER = timedelta(minutes=10)


@dataclass(frozen=True)
class WizardTaskDTO:
    id: str
    title: str
    status: WizardSessionTaskStatus


@dataclass(frozen=True)
class WizardSessionUserDTO:
    id: int
    first_name: str
    email: str


@dataclass(frozen=True)
class WizardSessionDTO:
    session_id: str
    team_id: int
    workflow_id: str
    skill_id: str
    started_at: datetime
    run_phase: WizardSessionRunPhase
    tasks: tuple[WizardTaskDTO, ...]
    event_plan: dict[str, Any] | None
    error: dict[str, Any] | None
    pending_input: dict[str, Any] | None
    handoff_text: str | None
    created_by: WizardSessionUserDTO | None
    created_at: datetime
    updated_at: datetime
    is_stale: bool


@dataclass(frozen=True)
class UpsertWizardSessionRequest:
    """What the wizard CLI POSTs. team_id is derived from the URL, not the body."""

    session_id: str
    workflow_id: str
    skill_id: str
    started_at: datetime
    run_phase: WizardSessionRunPhase
    tasks: tuple[WizardTaskDTO, ...]
    event_plan: dict[str, Any] | None = None
    error: dict[str, Any] | None = None
    pending_input: dict[str, Any] | None = None
    handoff_text: str | None = None


@dataclass(frozen=True)
class UpsertWizardSessionInput:
    team_id: int
    session_id: str
    workflow_id: str
    skill_id: str
    started_at: datetime
    run_phase: WizardSessionRunPhase
    tasks: tuple[WizardTaskDTO, ...]
    event_plan: dict[str, Any] | None
    error: dict[str, Any] | None
    pending_input: dict[str, Any] | None
    handoff_text: str | None = None
    # Set on create only, never overwritten on later pushes for the same run.
    created_by_id: int | None = None


class WizardSessionOwnershipError(Exception):
    pass


@frozen
class LocalFolderWorkspace:
    project_name: str
    type: Literal["local_folder"] = "local_folder"


@frozen
class GitRepositoryWorkspace:
    repository: str
    # None means the repository's default branch.
    branch: str | None = None
    type: Literal["git_repository"] = "git_repository"


type WizardWorkspace = LocalFolderWorkspace | GitRepositoryWorkspace


@frozen
class WizardProgram:
    id: str
    name: str
    description: str
    wizard_version: str
    command: tuple[str, ...]
    tags: tuple[str, ...]
    required_programs: tuple[str, ...]
    supported_environments: tuple[WizardRunEnvironment, ...]


@frozen
class WizardRegistry:
    programs: tuple[WizardProgram, ...]
    version: Literal[1] = 1


@frozen
class CreateWizardRunInput:
    team_id: int
    created_by_id: int
    environment: WizardRunEnvironment
    workspace: WizardWorkspace
    program_id: str
    wizard_version: str | None = None
    idempotency_key: str | None = None


@frozen
class StartWizardInstallInput:
    """
    Starts the PostHog setup program in the cloud on a GitHub repository of the project.
    """

    team_id: int
    created_by_id: int
    repository: str
    branch: str | None = None
    idempotency_key: str | None = None


@frozen
class WizardRunCreationResult:
    run: "WizardRunDTO"
    created: bool


@frozen
class WizardRunCreatorDTO:
    id: int
    first_name: str
    last_name: str
    email: str


@frozen
class UpdateWizardRunTaskInput:
    """
    Payload used to update a single task of a WizardRun.
    """

    title: str
    status: WizardTaskStatus


@frozen
class UpdateWizardRunTaskListInput:
    """
    Payload used to update the list of tasks of a WizardRun.

    The Wizard's LLM generates and updates the task list, as a snaphost.
    This is why the input shape doesn't have timestamps. Those will computed
    server-side.
    """

    tasks: tuple[UpdateWizardRunTaskInput, ...]


@frozen
class WizardRunTaskDTO:
    """
    A single task of a WizardRun.

    Note: the datetimes are computed server-side,
          since the Wizard only sends the current list's snapshot.
          This is why it is only shown to the user.
    """

    title: str
    status: WizardTaskStatus
    created_at: datetime
    started_at: datetime | None
    completed_at: datetime | None
    failed_at: datetime | None
    error_message: str | None


@frozen
class WizardRunDTO:
    id: UUID
    team_id: int
    created_by_id: int | None
    environment: WizardRunEnvironment
    workspace: WizardWorkspace
    program: WizardProgram
    status: WizardRunStatus
    error_code: str | None
    error_message: str | None
    stage: WizardRunStage | None
    created_at: datetime
    updated_at: datetime | None
    started_at: datetime | None
    finished_at: datetime | None
    deadline_at: datetime | None
    created_by: WizardRunCreatorDTO | None = None
    tasks: tuple[WizardRunTaskDTO, ...] = ()


@frozen
class WizardInstallStatusDTO:
    run: WizardRunDTO
    pull_request_url: str | None
    next_step: str


@frozen
class ListWizardRunsInput:
    team_id: int
    statuses: tuple[WizardRunStatus, ...] = ()
    created_after: datetime | None = None
    created_by_id: int | None = None


@frozen
class CreatePullRequestArtifactInput:
    team_id: int
    run_id: UUID
    url: str
    number: int
    repository: str
    head_branch: str
    base_branch: str


@frozen
class WizardRunGitDiffArtifactDTO:
    id: UUID
    team_id: int
    run_id: UUID
    artifact_type: Literal[WizardRunArtifactType.GIT_DIFF]
    size_bytes: int
    content_hash: str
    additions: int | None
    removals: int | None
    created_at: datetime


@frozen
class WizardRunPullRequestArtifactDTO:
    id: UUID
    team_id: int
    run_id: UUID
    artifact_type: Literal[WizardRunArtifactType.PULL_REQUEST]
    url: str
    number: int
    repository: str
    head_branch: str
    base_branch: str
    created_at: datetime


type WizardRunArtifactDTO = WizardRunGitDiffArtifactDTO | WizardRunPullRequestArtifactDTO


@frozen
class WizardScanSignal:
    # Free-form so the wizard can add a signal type without a backend change.
    source: str
    name: str
    file: str | None


@frozen
class WizardScanTool:
    kind: str
    signals: tuple[WizardScanSignal, ...]


@frozen
class RecordWizardScanInput:
    team_id: int
    created_by_id: int | None
    session_id: str
    program: str
    wizard_version: str
    workspace_fingerprint: str
    scanned_at: datetime
    tools: tuple[WizardScanTool, ...]
    # False when the wizard could not walk the whole workspace, so a missing tool may not be gone.
    complete: bool = True


@frozen
class WizardScanResult:
    id: UUID
    # False when the session already reported this scan, so nothing was written.
    created: bool