: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
from typing import Any
from drf_spectacular.utils import extend_schema_field
from rest_framework import serializers
from posthog.api.pagination import PageLinksSerializer
from products.notebooks.backend.facade.widgets import (
DEFAULT_WIDGET_MODEL,
MAX_WIDGET_EFFECTIVE_PROMPT_LENGTH,
MAX_WIDGET_PROMPT_LENGTH,
WIDGET_MODEL_CHOICES,
LifecycleStatus,
)
class WidgetGenerateRequestSerializer(serializers.Serializer):
prompt = serializers.CharField(
max_length=MAX_WIDGET_EFFECTIVE_PROMPT_LENGTH,
trim_whitespace=False,
error_messages={
"max_length": f"Keep widget instructions to {MAX_WIDGET_EFFECTIVE_PROMPT_LENGTH:,} characters or fewer."
},
help_text=(
"Instructions for the generated widget. Initial and improvement instructions accept up to 20,000 "
"characters; regeneration accepts complete instructions up to 50,000 characters."
),
)
generation_id = serializers.UUIDField(help_text="Idempotency key for this generation job.")
model = serializers.ChoiceField(
choices=WIDGET_MODEL_CHOICES,
default=DEFAULT_WIDGET_MODEL,
help_text="AI model used to generate the widget.",
)
generation_operation = serializers.ChoiceField(
choices=["initial", "regenerate", "improve"],
default="regenerate",
help_text="Whether to generate from scratch or improve the current source.",
)
expected_current_version_id = serializers.UUIDField(
required=False,
help_text="Current widget version the improvement is based on. Required for improve operations.",
)
def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
operation = attrs["generation_operation"]
prompt = attrs["prompt"].strip()
if operation != "regenerate" and len(prompt) > MAX_WIDGET_PROMPT_LENGTH:
raise serializers.ValidationError(
{"prompt": f"Keep widget instructions to {MAX_WIDGET_PROMPT_LENGTH:,} characters or fewer."}
)
if operation == "improve" and "expected_current_version_id" not in attrs:
raise serializers.ValidationError({"expected_current_version_id": "Reload the widget before improving it."})
return attrs
class WidgetCancelRequestSerializer(serializers.Serializer):
generation_id = serializers.UUIDField(help_text="Generation job to cancel.")
class WidgetPinRequestSerializer(serializers.Serializer):
version_id = serializers.UUIDField(
allow_null=True,
help_text="Immutable version to pin, or null to follow the reusable widget's latest version.",
)
class WidgetJobSerializer(serializers.Serializer):
id = serializers.UUIDField(help_text="Generation job identifier.")
status = serializers.ChoiceField(
choices=["queued", "generating", "publishing"],
help_text="Current durable job state.",
)
phase = serializers.CharField(help_text="Current generation phase.")
model = serializers.CharField(help_text="AI model processing the job.")
created_at = serializers.DateTimeField(help_text="When the job was queued.")
started_at = serializers.DateTimeField(allow_null=True, help_text="When a worker started the job.")
class WidgetSecurityFindingSerializer(serializers.Serializer):
severity = serializers.ChoiceField(
choices=["low", "medium", "high", "critical"],
help_text="Severity of this potential security issue.",
)
title = serializers.CharField(help_text="Short description of the potential security issue.")
details = serializers.CharField(help_text="Why the source may be unsafe and what it could do.")
class WidgetSecurityReviewSerializer(serializers.Serializer):
severity = serializers.ChoiceField(
choices=["none", "low", "medium", "high", "critical"],
help_text="Highest severity found, or none when the review found no issues.",
)
summary = serializers.CharField(help_text="Concise result from the automated security review.")
findings = WidgetSecurityFindingSerializer(many=True, help_text="Potential security issues found in the source.")
model = serializers.CharField(help_text="Fast AI model used for the security review.")
review_version = serializers.CharField(help_text="Version of the security review instructions and parser.")
reviewed_at = serializers.DateTimeField(help_text="When this exact widget source was reviewed.")
@extend_schema_field(
{
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"source": {"type": "string"},
"hog": {"type": "string"},
},
"required": ["source"],
},
}
)
class WidgetInputBindingsField(serializers.DictField):
pass
class WidgetInputContractColumnSerializer(serializers.Serializer):
name = serializers.CharField(help_text="Column name expected by the reusable widget.")
type = serializers.CharField(help_text="Column type expected by the reusable widget.")
class WidgetInputContractItemSerializer(serializers.Serializer):
slot = serializers.CharField(help_text="Stable logical input name used by the reusable widget.")
sourceName = serializers.CharField(help_text="Original dataframe name when the widget was published.")
columns = WidgetInputContractColumnSerializer(
many=True,
required=False,
default=list,
help_text="Columns the notebook-local binding must produce after its optional Hog mapping.",
)
schemaHash = serializers.CharField(help_text="Hash of the expected column schema.")
class WidgetStatusSerializer(serializers.Serializer):
lifecycle_status = serializers.ChoiceField(
choices=LifecycleStatus.choices,
help_text="Current widget and preview state.",
)
error_detail = serializers.CharField(required=False, allow_null=True, help_text="Actionable failure detail.")
error_code = serializers.CharField(
required=False,
allow_null=True,
help_text="Stable failure code for support and diagnostics.",
)
failure_phase = serializers.ChoiceField(
choices=["generating_source", "reviewing_source", "publishing_source", "unknown"],
required=False,
allow_null=True,
help_text="Generation step that failed, if a generation job failed.",
)
artifact_url = serializers.URLField(
required=False,
allow_null=True,
help_text="Short-lived URL for the selected widget version's preview.",
)
frame_names = serializers.ListField(
child=serializers.CharField(),
help_text="Logical dataframe slots available to the selected version.",
)
input_bindings = WidgetInputBindingsField(
help_text="Notebook-local mapping from each logical widget input slot to a dataframe and optional Hog transform.",
)
input_contract = WidgetInputContractItemSerializer(
many=True,
help_text="Logical dataframe slots and output schemas required by the selected widget version.",
)
current_version_id = serializers.UUIDField(allow_null=True, help_text="Selected immutable widget version.")
pinned_version_id = serializers.UUIDField(
allow_null=True,
help_text="Version explicitly pinned for this notebook placement, or null when it follows the latest version.",
)
widget_id = serializers.UUIDField(allow_null=True, help_text="Reusable widget identity.")
instance_id = serializers.UUIDField(allow_null=True, help_text="Placement in this notebook.")
has_versions = serializers.BooleanField(help_text="Whether the widget has generated history.")
active_job = WidgetJobSerializer(allow_null=True, help_text="Active generation job, if any.")
security_review = WidgetSecurityReviewSerializer(
allow_null=True,
help_text="Automated review for the selected source, or null for a legacy unreviewed version.",
)
is_reusable = serializers.BooleanField(
help_text="Whether this widget identity is published in the reusable widget catalog.",
)
build_hash = serializers.CharField(
allow_null=True,
help_text="Hex SHA-256 over the exact immutable artifact manifest selected for display.",
)
class WidgetVersionSerializer(serializers.Serializer):
generation_cost_usd = serializers.DecimalField(
max_digits=12,
decimal_places=6,
allow_null=True,
required=False,
help_text="Estimated generation charge in USD, including retries, security review, and the AI credit markup. Null when unavailable.",
)
id = serializers.UUIDField(help_text="Immutable widget version identifier.")
parent_version_id = serializers.UUIDField(allow_null=True, help_text="Version this one was based on.")
version = serializers.IntegerField(min_value=1, help_text="One-based version number.")
version_operation = serializers.ChoiceField(
source="operation",
choices=["initial", "regenerate", "improve", "revert"],
help_text="Action that created this version.",
)
prompt_delta = serializers.CharField(help_text="Instructions added by this version.")
effective_prompt = serializers.CharField(
max_length=MAX_WIDGET_EFFECTIVE_PROMPT_LENGTH,
help_text="Complete instructions represented by this version, up to 50,000 characters.",
)
model = serializers.CharField(allow_null=True, help_text="AI model, or null when this version did not run a model.")
created_at = serializers.DateTimeField(help_text="When this version was created.")
build_status = serializers.ChoiceField(
choices=["queued", "building", "ready", "failed"],
allow_null=True,
help_text="Preview build state.",
)
artifact_url = serializers.URLField(allow_null=True, help_text="Preview URL when retained and ready.")
frame_names = serializers.ListField(
child=serializers.CharField(), help_text="Logical dataframe slots available to this version."
)
is_current = serializers.BooleanField(help_text="Whether this notebook instance currently displays this version.")
security_review = WidgetSecurityReviewSerializer(
allow_null=True,
help_text="Automated review for this source, or null for a legacy unreviewed version.",
)
build_hash = serializers.CharField(
allow_null=True,
help_text="Hex SHA-256 over this version's exact immutable artifact manifest.",
)
class WidgetVersionPageSerializer(PageLinksSerializer):
results = WidgetVersionSerializer(many=True, help_text="Versions ordered newest first.")
count = serializers.IntegerField(min_value=0, help_text="Total versions.")
next_offset = serializers.IntegerField(allow_null=True, help_text="Offset for the next page.")
class WidgetVersionQuerySerializer(serializers.Serializer):
offset = serializers.IntegerField(default=0, min_value=0, help_text="Zero-based version offset.")
limit = serializers.IntegerField(default=25, min_value=1, max_value=100, help_text="Maximum versions to return.")
class WidgetSourceSerializer(serializers.Serializer):
source = serializers.CharField( # type: ignore[assignment] # field named `source` shadows DRF Field.source
help_text="Read-only source code for the current widget version."
)
class WidgetSourceQuerySerializer(serializers.Serializer):
version_id = serializers.UUIDField(
required=False,
help_text="Immutable widget version whose source should be returned. Defaults to the displayed version.",
)
class WidgetRevertRequestSerializer(serializers.Serializer):
version_id = serializers.UUIDField(help_text="Earlier version to restore as a new version.")
expected_current_version_id = serializers.UUIDField(help_text="Current version used for optimistic concurrency.")
class WidgetFrameQuerySerializer(serializers.Serializer):
version_id = serializers.UUIDField(required=False, help_text="Version requesting the data.")
run_id = serializers.UUIDField(required=False, help_text="Completed run selected by the first page request.")
offset = serializers.IntegerField(default=0, min_value=0, help_text="Zero-based row offset.")
limit = serializers.IntegerField(default=100, min_value=1, max_value=500, help_text="Maximum rows in this page.")
class WidgetFrameColumnSerializer(serializers.Serializer):
name = serializers.CharField(help_text="Column name.")
type = serializers.CharField(help_text="Column type reported by the completed notebook run.")
class WidgetFrameSerializer(serializers.Serializer):
name = serializers.CharField(help_text="Logical dataframe name.")
runId = serializers.UUIDField(help_text="Completed notebook run used for every page in this iframe load.")
columns = WidgetFrameColumnSerializer(many=True, help_text="Dataframe columns in display order.")
rows = serializers.ListField(
child=serializers.ListField(child=serializers.JSONField()), help_text="Requested page of dataframe rows."
)
totalRowCount = serializers.IntegerField(min_value=0, help_text="Rows available in the completed run.")
includedRowCount = serializers.IntegerField(min_value=0, help_text="Rows returned in this response.")
offset = serializers.IntegerField(min_value=0, help_text="Zero-based offset of this page.")
nextOffset = serializers.IntegerField(min_value=0, allow_null=True, help_text="Offset for the next page, if any.")
truncated = serializers.BooleanField(help_text="Whether more rows exist after this page.")
class WidgetErrorSerializer(serializers.Serializer):
code = serializers.CharField(help_text="Stable machine-readable error code.")
detail = serializers.CharField(help_text="Actionable error detail.")