: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
import string
import secrets
from datetime import timedelta
from typing import TYPE_CHECKING, Optional
from django.db import IntegrityError, models
from django.utils import timezone
import structlog
from posthog.models.team.team import Team
from posthog.models.user import User
from posthog.models.utils import CreatedMetaFields, DeletedMetaFields, UpdatedMetaFields, UUIDModel, UUIDTModel
logger = structlog.get_logger(__name__)
if TYPE_CHECKING:
from products.tasks.backend.models import TaskRun
def generate_short_id() -> str:
"""Generate securely random 4 characters long alphanumeric ID.
With team-scoped uniqueness, 4 characters (62^4 = 14.7M combinations)
is sufficient to avoid collisions within a single team.
"""
return "".join(secrets.choice(string.ascii_letters + string.digits) for _ in range(4))
class Conversation(UUIDTModel, DeletedMetaFields):
TITLE_MAX_LENGTH = 250
class Meta:
indexes = [
models.Index(fields=["updated_at"]),
]
constraints = [
models.UniqueConstraint(
fields=["team", "slack_thread_key"],
name="unique_team_slack_thread_key",
condition=models.Q(slack_thread_key__isnull=False),
)
]
db_table = "ee_conversation"
class AgentRuntime(models.TextChoices):
LANGGRAPH = "langgraph", "LangGraph"
SANDBOX = "sandbox", "Sandbox"
class Status(models.TextChoices):
IDLE = "idle", "Idle"
IN_PROGRESS = "in_progress", "In progress"
CANCELING = "canceling", "Canceling"
class Type(models.TextChoices):
ASSISTANT = "assistant", "Assistant"
TOOL_CALL = "tool_call", "Tool call"
DEEP_RESEARCH = "deep_research", "Deep research"
SLACK = "slack", "Slack"
class Topic(models.TextChoices):
"""Product domain a conversation is about, classified from the first question (see title generator)."""
WEB_ANALYTICS = "web_analytics", "Web analytics"
PRODUCT_ANALYTICS = "product_analytics", "Product analytics"
SESSION_REPLAY = "session_replay", "Session replay"
SURVEYS = "surveys", "Surveys"
FEATURE_FLAGS = "feature_flags", "Feature flags"
EXPERIMENTS = "experiments", "Experiments"
ERROR_TRACKING = "error_tracking", "Error tracking"
DATA_WAREHOUSE = "data_warehouse", "Data warehouse"
OTHER = "other", "Other"
user = models.ForeignKey(User, on_delete=models.CASCADE, related_name="+")
team = models.ForeignKey(Team, on_delete=models.CASCADE, related_name="+")
created_at = models.DateTimeField(auto_now_add=True, null=True)
updated_at = models.DateTimeField(auto_now=True, null=True)
status = models.CharField(max_length=20, choices=Status, default=Status.IDLE)
type = models.CharField(max_length=20, choices=Type, default=Type.ASSISTANT)
title = models.CharField(
null=True,
blank=True,
help_text="Title of the conversation.",
max_length=TITLE_MAX_LENGTH,
)
topic = models.CharField(
null=True,
blank=True,
choices=Topic,
max_length=64,
help_text="Product domain the conversation is about, classified from the first question.",
)
is_internal = models.BooleanField(
null=True,
default=False,
help_text="Whether this conversation was created during an impersonated session (e.g., by support agents). Internal conversations are hidden from customers.",
)
slack_thread_key = models.CharField(
max_length=200,
null=True,
blank=True,
help_text="Unique key for Slack thread: '{workspace_id}:{channel}:{thread_ts}'",
)
slack_workspace_domain = models.CharField(
max_length=100,
null=True,
blank=True,
help_text="Slack workspace subdomain (e.g. 'posthog' for posthog.slack.com)",
)
approval_decisions = models.JSONField(
default=dict,
blank=True,
help_text="Stores approval card metadata for dangerous operations (payload lives in checkpoint). Format: {proposal_id: {decision_status: 'pending' | 'approved' | 'rejected' | 'auto_rejected', tool_name: str, preview: str, ...}}",
)
messages_json = models.JSONField(
null=True,
blank=True,
default=None,
help_text="Stored messages for non-LangGraph modes (e.g., sandbox).",
)
# Deprecated: legacy Redis-flow columns (migration 0039). Nothing reads or writes
# them on the sandbox path anymore — the `task` FK supersedes `sandbox_task_id`, and
# the current Run is derived (see `current_run`). Retained until a cleanup migration.
sandbox_task_id = models.UUIDField(
null=True,
blank=True,
help_text="Deprecated. Permanent link to Task for sandbox conversations.",
)
sandbox_run_id = models.UUIDField(
null=True,
blank=True,
help_text="Deprecated. Permanent link to current TaskRun for sandbox conversations.",
)
agent_runtime = models.CharField(
max_length=16,
choices=AgentRuntime.choices,
default=AgentRuntime.LANGGRAPH,
db_index=True,
help_text="Runtime that owns this conversation for its whole life. Stamped at create time from the phai-sandbox-mode flag; never re-evaluated.",
)
task = models.ForeignKey(
"tasks.Task",
null=True,
blank=True,
on_delete=models.SET_NULL,
related_name="+",
db_index=True,
help_text="The products/tasks Task backing a sandbox conversation. One Task per conversation for its whole life.",
)
@property
def current_run(self) -> Optional["TaskRun"]:
task = self.task
if task is None:
return None
return task.latest_run
class ConversationCheckpoint(UUIDTModel):
thread = models.ForeignKey(Conversation, on_delete=models.CASCADE, related_name="checkpoints")
checkpoint_ns = models.TextField(
default="",
help_text='Checkpoint namespace. Denotes the path to the subgraph node the checkpoint originates from, separated by `|` character, e.g. `"child|grandchild"`. Defaults to "" (root graph).',
)
parent_checkpoint = models.ForeignKey(
"self",
null=True,
on_delete=models.CASCADE,
related_name="children",
help_text="Parent checkpoint ID.",
)
checkpoint = models.JSONField(null=True, help_text="Serialized checkpoint data.")
metadata = models.JSONField(null=True, help_text="Serialized checkpoint metadata.")
class Meta:
constraints = [
models.UniqueConstraint(
fields=["id", "checkpoint_ns", "thread"],
name="unique_checkpoint",
)
]
db_table = "ee_conversationcheckpoint"
class ConversationCheckpointBlob(UUIDTModel):
checkpoint = models.ForeignKey(ConversationCheckpoint, on_delete=models.CASCADE, related_name="blobs")
"""
The checkpoint that created the blob. Do not use this field to query blobs.
"""
thread = models.ForeignKey(Conversation, on_delete=models.CASCADE, related_name="blobs", null=True)
checkpoint_ns = models.TextField(
default="",
help_text='Checkpoint namespace. Denotes the path to the subgraph node the checkpoint originates from, separated by `|` character, e.g. `"child|grandchild"`. Defaults to "" (root graph).',
)
channel = models.TextField(
help_text="An arbitrary string defining the channel name. For example, it can be a node name or a reserved LangGraph's enum."
)
version = models.TextField(help_text="Monotonically increasing version of the channel.")
type = models.TextField(null=True, help_text="Type of the serialized blob. For example, `json`.")
blob = models.BinaryField(null=True)
class Meta:
constraints = [
models.UniqueConstraint(
fields=["thread_id", "checkpoint_ns", "channel", "version"],
name="unique_checkpoint_blob",
)
]
db_table = "ee_conversationcheckpointblob"
class ConversationCheckpointWrite(UUIDTModel):
checkpoint = models.ForeignKey(ConversationCheckpoint, on_delete=models.CASCADE, related_name="writes")
task_id = models.UUIDField(help_text="Identifier for the task creating the checkpoint write.")
idx = models.IntegerField(
help_text="Index of the checkpoint write. It is an integer value where negative numbers are reserved for special cases, such as node interruption."
)
channel = models.TextField(
help_text="An arbitrary string defining the channel name. For example, it can be a node name or a reserved LangGraph's enum."
)
type = models.TextField(null=True, help_text="Type of the serialized blob. For example, `json`.")
blob = models.BinaryField(null=True)
class Meta:
constraints = [
models.UniqueConstraint(
fields=["checkpoint_id", "task_id", "idx"],
name="unique_checkpoint_write",
)
]
db_table = "ee_conversationcheckpointwrite"
MAX_ONBOARDING_QUESTIONS = 3
ONBOARDING_TIMEOUT_MINUTES = 10
CORE_MEMORY_MAX_CHARACTERS = 10_000
class CoreMemory(UUIDTModel):
class ScrapingStatus(models.TextChoices):
PENDING = "pending", "Pending"
COMPLETED = "completed", "Completed"
SKIPPED = "skipped", "Skipped"
team = models.OneToOneField(Team, on_delete=models.CASCADE)
text = models.TextField(
default="",
help_text="Dumped core memory where facts are separated by newlines.",
)
initial_text = models.TextField(default="", help_text="Scraped memory about the business.")
scraping_status = models.CharField(max_length=20, choices=ScrapingStatus, blank=True, null=True)
scraping_started_at = models.DateTimeField(null=True)
class Meta:
db_table = "ee_corememory"
async def achange_status_to_pending(self) -> None:
self.scraping_started_at = timezone.now()
self.scraping_status = CoreMemory.ScrapingStatus.PENDING
await self.asave()
async def achange_status_to_skipped(self) -> None:
self.scraping_status = CoreMemory.ScrapingStatus.SKIPPED
await self.asave()
@property
def is_scraping_pending(self) -> bool:
return self.scraping_status == CoreMemory.ScrapingStatus.PENDING and (
self.scraping_started_at is None
or (self.scraping_started_at + timedelta(minutes=ONBOARDING_TIMEOUT_MINUTES)) > timezone.now()
)
@property
def is_scraping_finished(self) -> bool:
return self.scraping_status in [
CoreMemory.ScrapingStatus.COMPLETED,
CoreMemory.ScrapingStatus.SKIPPED,
]
async def aappend_question_to_initial_text(self, text: str) -> None:
if self.initial_text != "":
self.initial_text += "\n"
self.initial_text += "Question: " + text + "\nAnswer:"
self.initial_text = self.initial_text.strip()
await self.asave()
async def aappend_answer_to_initial_text(self, text: str) -> None:
self.initial_text += " " + text
self.initial_text = self.initial_text.strip()
await self.asave()
async def aset_core_memory(self, text: str) -> None:
# Unlike append/replace, this path is fed raw model output (onboarding compression), so it clamps
# to the cap instead of rejecting. That keeps the stored row within the limit that the serializer,
# the textarea, and the /remember command all enforce, because an over-cap row can afterwards be
# neither saved nor edited through any of them.
if len(text) > CORE_MEMORY_MAX_CHARACTERS:
logger.warning(
"core_memory_set_truncated",
team_id=self.team_id,
length=len(text),
limit=CORE_MEMORY_MAX_CHARACTERS,
)
text = text[:CORE_MEMORY_MAX_CHARACTERS]
self.text = text
self.scraping_status = CoreMemory.ScrapingStatus.COMPLETED
await self.asave()
async def aappend_core_memory(self, text: str) -> None:
new_text = text if self.text == "" else self.text + "\n" + text
if len(new_text) > CORE_MEMORY_MAX_CHARACTERS:
raise ValueError(
f"Memory is full ({len(self.text)}/{CORE_MEMORY_MAX_CHARACTERS} characters used)."
" Please free up space in Settings → PostHog AI before adding new memories."
)
self.text = new_text
await self.asave()
async def areplace_core_memory(self, original_fragment: str, new_fragment: str) -> None:
if original_fragment not in self.text:
raise ValueError(f"Original fragment {original_fragment} not found in core memory")
new_text = self.text.replace(original_fragment, new_fragment)
if len(new_text) > CORE_MEMORY_MAX_CHARACTERS:
raise ValueError(
f"Replacement would exceed memory limit ({CORE_MEMORY_MAX_CHARACTERS} characters)."
" Please free up space in Settings → PostHog AI first."
)
self.text = new_text
await self.asave()
@property
def formatted_text(self) -> str:
if len(self.text) > 5000:
# If memory text exceeds 5000 characters, truncate it. For the user, the most important bits are at the start
# (i.e. foundational /init info) and at the end (i.e. freshest memories)
return self.text[:2500] + "…" + self.text[-2500:]
return self.text
@property
def answers_left(self) -> int:
answers_given = self.initial_text.count("\nAnswer:")
if self.initial_text.endswith("\nAnswer:"):
answers_given -= 1
return MAX_ONBOARDING_QUESTIONS - answers_given
class AgentArtifact(UUIDModel, CreatedMetaFields, UpdatedMetaFields, DeletedMetaFields):
class Type(models.TextChoices):
VISUALIZATION = "visualization", "Visualization"
NOTEBOOK = "notebook", "Notebook"
short_id = models.CharField(max_length=4, default=generate_short_id)
name = models.CharField(max_length=400)
type = models.CharField(max_length=50, choices=Type)
data = models.JSONField(help_text="Artifact content. Structure depends on artifact type.")
conversation = models.ForeignKey(Conversation, on_delete=models.CASCADE, related_name="artifacts")
team = models.ForeignKey(Team, on_delete=models.CASCADE, related_name="+")
class Meta:
indexes = [
models.Index(fields=["team", "short_id"]),
models.Index(fields=["team", "conversation", "created_at"]),
]
constraints = [
models.UniqueConstraint(fields=["team", "short_id"], name="unique_team_short_id"),
]
db_table = "ee_agentartifact"
def save(self, *args, **kwargs) -> None:
max_retries = 5
for attempt in range(max_retries):
try:
return super().save(*args, **kwargs)
except IntegrityError as e:
if "short_id" in str(e) and attempt < max_retries - 1:
self.short_id = generate_short_id()
else:
raise