: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
"""
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