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.

22.0 KB
Raw Blame
"""DRF serializers for today. Response shapes come from the facade contracts."""

from typing import Any

from rest_framework import serializers
from rest_framework_dataclasses.serializers import DataclassSerializer

from ..facade.contracts import (
    CodeFile,
    FigureMark,
    FigureQuote,
    HighlightItem,
    HighlightMetric,
    HighlightMover,
    HighlightPin,
    Highlights,
    HighlightValueFormat,
    ImpactNumber,
    ImpactWorking,
    KeyClause,
    PageLink,
    PreviewLine,
    PullRequestLink,
    PulsePin,
    PulsePins,
    PulseSlot,
    RecordingTarget,
    ReportKeyClauses,
    ReportPage,
    SignalPreview,
    SignalView,
)
from ..facade.enums import (
    CitedSource,
    FigureSourceKind,
    FigureText,
    HighlightInterval,
    HighlightLabel,
    HighlightMetricReason,
    HighlightPinStatus,
    HighlightPriority,
    HighlightsStatus,
    HighlightUnit,
    ImpactNumberKey,
    KeyClauseRole,
    PulseSlotStatus,
)


class ExcerptChoiceRequestSerializer(serializers.Serializer):
    finding = serializers.CharField(max_length=6000, help_text="The finding the code excerpts should show.")
    excerpts = serializers.ListField(
        child=serializers.CharField(max_length=2000),
        min_length=2,
        max_length=5,
        help_text="Candidate code excerpts, best scored first.",
    )


class ExcerptChoiceSerializer(serializers.Serializer):
    index = serializers.IntegerField(
        allow_null=True, help_text="The excerpt that shows what the finding describes, or null when unsure."
    )


class PullRequestLinkSerializer(DataclassSerializer):
    url = serializers.CharField(help_text="The pull request on GitHub.")
    number = serializers.IntegerField(help_text="The pull request number.")

    class Meta:
        dataclass = PullRequestLink


class CodeFileSerializer(DataclassSerializer):
    repo = serializers.CharField(help_text="The repository as owner/name.")
    path = serializers.CharField(help_text="The file path in the repository.")

    class Meta:
        dataclass = CodeFile


class PreviewLineSerializer(DataclassSerializer):
    text = serializers.CharField(help_text="One line of the preview block.")
    quiet = serializers.BooleanField(help_text="Whether the line is secondary, such as a stack frame.")

    class Meta:
        dataclass = PreviewLine


class PageLinkSerializer(DataclassSerializer):
    url = serializers.CharField(help_text="Where the link goes, outside PostHog.")
    text = serializers.CharField(help_text="The link text.")

    class Meta:
        dataclass = PageLink


class SignalPreviewSerializer(DataclassSerializer):
    hint = serializers.CharField(help_text="What expanding the signal shows, such as 'Show the stack trace'.")
    code = CodeFileSerializer(many=True, help_text="Repository files to quote, the finding's own file first.")
    block = PreviewLineSerializer(many=True, help_text="A preformatted block, such as a stack trace or a query.")
    text = serializers.CharField(help_text="The finding's text beyond its first sentence.")
    facts = serializers.ListField(child=serializers.CharField(), help_text="Short facts about the source.")
    link = PageLinkSerializer(allow_null=True, help_text="A link that replaces the signal's own destination.")
    link_label = serializers.CharField(
        allow_null=True, help_text="A label that replaces the label of the signal's own destination."
    )

    class Meta:
        dataclass = SignalPreview


class RecordingTargetSerializer(DataclassSerializer):
    session_id = serializers.CharField(help_text="The recording's session id.")
    start_at = serializers.DateTimeField(
        allow_null=True, help_text="Where the player starts, a few seconds before the finding."
    )
    offset = serializers.CharField(allow_null=True, help_text="The finding's time in the recording, as MM:SS.")
    seek_seconds = serializers.IntegerField(
        allow_null=True,
        help_text="Where the player starts, in seconds from the recording start. Null without an offset.",
    )

    class Meta:
        dataclass = RecordingTarget


class SignalViewSerializer(DataclassSerializer):
    signal_id = serializers.CharField(help_text="The signal's id.")
    source_product = serializers.CharField(help_text="The product that emitted the signal.")
    source_type = serializers.CharField(help_text="The kind of signal within its product.")
    source_id = serializers.CharField(help_text="The id of the source object, such as an issue or a ticket.")
    content = serializers.CharField(help_text="The signal's text as emitted.")
    timestamp = serializers.DateTimeField(help_text="When the signal happened.")
    extra = serializers.DictField(
        child=serializers.JSONField(),
        help_text="The emitter's extra fields as it sent them, used to link to the source object. Values are any JSON.",
    )
    headline = serializers.CharField(help_text="The signal as one short line.")
    lead = serializers.CharField(help_text="The signal's first sentence.")
    meta = serializers.CharField(help_text="Identifiers such as a pull request or ticket number, joined by dots.")
    cited = serializers.ChoiceField(
        choices=CitedSource.choices, allow_null=True, help_text="What a scout finding cites: code or a Slack thread."
    )
    recording = RecordingTargetSerializer(allow_null=True, help_text="The recording the signal plays, if any.")
    link = PageLinkSerializer(allow_null=True, help_text="Where a scout finding links outside PostHog, if anywhere.")
    preview = SignalPreviewSerializer(allow_null=True, help_text="What expanding the signal shows, if anything.")

    class Meta:
        dataclass = SignalView


class ImpactWorkingSerializer(DataclassSerializer):
    expression = serializers.CharField(help_text="How the number is worked out, such as '120 ms × 30,000 calls'.")
    result = serializers.CharField(help_text="What the working comes to, such as '1.00 hours a day'.")

    class Meta:
        dataclass = ImpactWorking


class ImpactNumberSerializer(DataclassSerializer):
    key = serializers.ChoiceField(
        choices=ImpactNumberKey.choices,
        help_text="Which number this is: distinct support tickets or database hours a day.",
    )
    value = serializers.CharField(help_text="The number as shown, such as '2' or '1 hour'.")
    sentence = serializers.CharField(help_text="The sentence that follows the number.")
    signal = SignalViewSerializer(allow_null=True, help_text="The signal the number comes from, if one does.")
    values = serializers.ListField(
        child=serializers.CharField(), help_text="The figures in the signal's headline to mark."
    )
    working = ImpactWorkingSerializer(allow_null=True, help_text="How the number is worked out, if it is.")

    class Meta:
        dataclass = ImpactNumber


class ReportPageSerializer(DataclassSerializer):
    lead = serializers.CharField(help_text="The summary's opening paragraph, as markdown.")
    proposal = serializers.CharField(
        help_text="The proposed fix cut to whole sentences, as markdown. Empty when the report proposes none."
    )
    impact_sentence = serializers.CharField(
        help_text="The impact section cut to whole sentences, as markdown, when it states a measurement. Empty otherwise."
    )
    named_pull_request = PullRequestLinkSerializer(
        allow_null=True,
        help_text="The pull request the proposal names, or else the summary, when it names exactly one.",
    )
    solution_names_pull_request = serializers.BooleanField(help_text="Whether the proposal names any pull request.")
    evidence = SignalViewSerializer(
        many=True, help_text="The signals to show as evidence, at most 3, newest first, one per source first."
    )
    source_count = serializers.IntegerField(
        help_text="How many distinct source objects the report's newest 100 signals come from. The impact numbers and last seen use the same signals."
    )
    impact_numbers = ImpactNumberSerializer(
        many=True, help_text="Numbers the signals size the problem with, such as distinct support tickets."
    )
    last_seen = serializers.DateTimeField(
        allow_null=True, help_text="When the newest session, ticket or alert behind the report happened."
    )

    class Meta:
        dataclass = ReportPage


class KeyClausesQuerySerializer(serializers.Serializer):
    include_impact = serializers.BooleanField(
        default=True,
        help_text="Whether to mark the impact sentence. Pass false when the page shows an impact number instead.",
    )


class KeyClauseSerializer(DataclassSerializer):
    start = serializers.IntegerField(help_text="Where the clause starts in its text, as the reader sees it.")
    end = serializers.IntegerField(help_text="Where the clause ends in its text.")
    role = serializers.ChoiceField(choices=KeyClauseRole.choices, help_text="What the clause tells the reader.")
    expansion = serializers.ListField(
        child=serializers.CharField(), help_text="Sentences from the report that explain the clause further."
    )

    class Meta:
        dataclass = KeyClause


class ReportKeyClausesSerializer(DataclassSerializer):
    lead = KeyClauseSerializer(many=True, help_text="The clauses that state the problem or its cause in the lead.")
    impact = KeyClauseSerializer(
        many=True, help_text="The clauses that state the problem or its cause in the impact sentence."
    )
    proposal = KeyClauseSerializer(many=True, help_text="The clause that states the fix in the proposal.")

    class Meta:
        dataclass = ReportKeyClauses


class FigureQuoteSerializer(DataclassSerializer):
    kind = serializers.ChoiceField(
        choices=FigureSourceKind.choices, help_text="Where the number comes from: a signal or the agent's research."
    )
    signal = SignalViewSerializer(
        allow_null=True, help_text="The signal that states the number. Null when the agent's research states it."
    )
    at = serializers.DateTimeField(help_text="When the source was written.")
    sentence = serializers.CharField(help_text="The source sentence that states the number.")
    start = serializers.IntegerField(help_text="Where the number starts in the sentence.")
    end = serializers.IntegerField(help_text="Where the number ends in the sentence.")

    class Meta:
        dataclass = FigureQuote


class FigureMarkSerializer(DataclassSerializer):
    text = serializers.ChoiceField(
        choices=FigureText.choices, help_text="The page text the number is in: the lead or the impact sentence."
    )
    start = serializers.IntegerField(help_text="Where the number starts in that text, as the reader sees it.")
    end = serializers.IntegerField(help_text="Where the number ends in that text.")
    figure = serializers.CharField(help_text="The number as the page shows it.")
    quote = FigureQuoteSerializer(help_text="The sentence that states the same result.")

    class Meta:
        dataclass = FigureMark


class FigureMarksSerializer(serializers.Serializer):
    marks = FigureMarkSerializer(many=True, help_text="The numbers to mark, at most 4, each with its source.")


class HighlightValueFormatSerializer(DataclassSerializer):
    format = serializers.CharField(
        allow_null=True, help_text="Number format of the insight, for example numeric, percentage or currency."
    )
    prefix = serializers.CharField(allow_null=True, help_text="Text the insight shows before each value.")
    postfix = serializers.CharField(allow_null=True, help_text="Text the insight shows after each value.")
    decimal_places = serializers.IntegerField(allow_null=True, help_text="Most decimal places the insight shows.")

    class Meta:
        dataclass = HighlightValueFormat


class HighlightMoverSerializer(DataclassSerializer):
    label = serializers.CharField(  # type: ignore[assignment]
        help_text="Name of one series of the insight, for example a breakdown value."
    )
    value = serializers.FloatField(help_text="Value of the series for the last complete period.")
    change_pct = serializers.FloatField(
        allow_null=True,
        help_text="Change of the series against the period before, in percent. Null when the period before is 0.",
    )

    class Meta:
        dataclass = HighlightMover


class PulsePinSerializer(DataclassSerializer):
    key = serializers.CharField(
        max_length=200,
        help_text="Key of the number to keep: a key metric setting such as signup_event, or insight:<short_id>.",
    )
    name = serializers.CharField(
        max_length=400, help_text="Name to show for the number until the highlights compute its value."
    )
    dashboard_id = serializers.IntegerField(
        required=False,
        allow_null=True,
        default=None,
        help_text="For an insight pinned from a dashboard tile, the dashboard whose filters it keeps. Null otherwise.",
    )

    class Meta:
        dataclass = PulsePin


MAX_PINS_IN_REQUEST = 20


class PulsePinsSerializer(DataclassSerializer):
    pins = PulsePinSerializer(
        many=True,
        help_text=f"Numbers the person keeps at the start of the key numbers, in order. Suggestions fill the free places. Only the first 4 distinct keys are kept. At most {MAX_PINS_IN_REQUEST} entries.",
    )

    class Meta:
        dataclass = PulsePins

    def to_internal_value(self, data: Any) -> PulsePins:
        if isinstance(data, dict) and isinstance(data.get("pins"), list) and len(data["pins"]) > MAX_PINS_IN_REQUEST:
            raise serializers.ValidationError({"pins": [f"Send at most {MAX_PINS_IN_REQUEST} pins."]})
        return super().to_internal_value(data)


class HighlightMetricSerializer(DataclassSerializer):
    key = serializers.CharField(
        help_text="Stable key of the metric: a key metric setting such as signup_event, or insight:<short_id>."
    )
    name = serializers.CharField(help_text="Name of the key metric or of the insight, for example Sign-ups.")
    value = serializers.FloatField(
        help_text="Value for the last complete period: the last 7 complete days, or the last complete week or month."
    )
    unit = serializers.ChoiceField(
        choices=HighlightUnit.choices,
        help_text="`events` for a count of events, `people` for unique people, `number` for an insight value.",
    )
    change_pct = serializers.FloatField(
        allow_null=True,
        help_text="Change against the period before, in percent. Null when the period before is 0.",
    )
    series = serializers.ListField(
        child=serializers.FloatField(),
        help_text="Values oldest first: daily for the last 28 complete days, or one value per week or month.",
    )
    interval = serializers.ChoiceField(
        choices=HighlightInterval.choices, help_text="What one value in `series` covers: a day, a week or a month."
    )
    url = serializers.CharField(
        allow_null=True,
        help_text="Path of the insight the metric comes from. For a key metric, a new trends insight of the same days.",
    )
    value_format = HighlightValueFormatSerializer(
        allow_null=True,
        help_text="How the insight formats its values. Null for a key metric and for an insight with plain numbers.",
    )
    period_starts = serializers.ListField(
        child=serializers.DateField(),
        help_text="The first day of the period each value in `series` covers, in the project's timezone. Same length and order as `series`.",
    )
    reason = serializers.ChoiceField(
        choices=HighlightMetricReason.choices,
        allow_null=True,
        help_text="Why the pulse suggests the metric: `routine` for an insight the person opens often, `dashboard` for a tile of a dashboard they open often, `key_metric` for a key metric of the project, `popular` for an insight that many people in the project open, `watched` for an insight the person gets an alert or a subscription for, `built` for an insight the person created or edited recently. Null for metrics computed before this field existed.",
    )
    dashboard_name = serializers.CharField(
        allow_null=True,
        help_text="Name of the dashboard the tile comes from when `reason` is `dashboard`, else null.",
    )
    dashboard_id = serializers.IntegerField(
        allow_null=True,
        help_text="Id of the dashboard the tile comes from, with its filters applied. Pass it when pinning the tile. Null otherwise.",
    )
    opened_days = serializers.IntegerField(
        allow_null=True,
        help_text="On how many of the last 14 days the person opened the insight, or the dashboard of the tile. Null for a key metric.",
    )
    last_opened = serializers.DateField(
        allow_null=True,
        help_text="The last day the person opened the insight, or the dashboard of the tile, in the project's timezone. Null for a key metric.",
    )
    previous_value = serializers.FloatField(
        allow_null=True,
        help_text="Value for the period before the last complete one, the base of `change_pct`. Null when unknown.",
    )
    movers = HighlightMoverSerializer(
        many=True,
        help_text="For an insight with several series, the series that changed most last period, biggest change first. Empty otherwise.",
    )

    class Meta:
        dataclass = HighlightMetric


class HighlightItemSerializer(DataclassSerializer):
    key = serializers.CharField(help_text="Stable key of the item for this person and day.")
    label = serializers.ChoiceField(  # type: ignore[assignment]
        choices=HighlightLabel.choices,
        help_text="`risk` when something got worse or broke, `opportunity` when the person can act to gain.",
    )
    priority = serializers.ChoiceField(
        choices=HighlightPriority.choices,
        help_text="Priority on the same scale as report priorities. `P1` for a risk with a score of 0.75 or more, `P2` for another risk, `P3` for an opportunity with a score of 0.4 or more, `P4` for another opportunity.",
    )
    title = serializers.CharField(help_text="One sentence that says what happened, with numbers.")
    detail = serializers.CharField(help_text="One or two short sentences with the comparison and the next action.")
    url = serializers.CharField(allow_null=True, help_text="Path in the app to open, relative to the project.")
    series = serializers.ListField(
        child=serializers.FloatField(),
        allow_null=True,
        help_text="Values behind the item for a small trend line, oldest first. Null when the item has no trend.",
    )
    score = serializers.FloatField(help_text="Importance weighted by relevance, from 0 to 1.")

    class Meta:
        dataclass = HighlightItem
        extra_kwargs = {
            "source": {"help_text": "Name of the highlight source that found the item, for example alerts."},
            "product": {
                "help_text": "Product that declares the source, for example feature_flags. Null for items stored before this field existed and for sources that no product declares any more."
            },
        }


class HighlightPinSerializer(DataclassSerializer):
    key = serializers.CharField(help_text="Key of a number the person keeps on their home.")
    status = serializers.ChoiceField(
        choices=HighlightPinStatus.choices,
        help_text="`ready` when the number is in `pulse`. `unavailable` when it has no number to show, for example a deleted insight, one that is not a trend, or a query that failed or did not finish in time. A pin missing from this list was added after these highlights were computed.",
    )

    class Meta:
        dataclass = HighlightPin


class PulseSlotSerializer(DataclassSerializer):
    reason = serializers.ChoiceField(
        choices=HighlightMetricReason.choices,
        allow_null=True,
        required=False,
        help_text="Why this number is selected, when known before its value arrives.",
    )
    key = serializers.CharField(help_text="Stable key of the selected number.")
    name = serializers.CharField(help_text="Title available before the number is computed.")
    status = serializers.ChoiceField(choices=PulseSlotStatus.choices, help_text="Loading state of this number.")
    url = serializers.CharField(allow_null=True, help_text="Path to the source, relative to the project.")
    interval = serializers.ChoiceField(
        choices=HighlightInterval.choices, allow_null=True, help_text="Measurement interval, when known."
    )

    class Meta:
        dataclass = PulseSlot


class HighlightsQuerySerializer(serializers.Serializer):
    refresh = serializers.BooleanField(
        default=False,
        help_text="Retry failed sources. An active computation is reused.",
    )


class HighlightsSerializer(DataclassSerializer):
    status = serializers.ChoiceField(
        choices=HighlightsStatus.choices,
        help_text="`ready` when the content is fresh. `computing` while new highlights are being computed: the content includes available results and, when enabled, pending number details. Otherwise it is the last ready highlights of the day, or empty. Poll again every 2 seconds until the status changes. `failed` when the last computation failed: the content is the last ready highlights of the day, or empty.",
    )
    generated_at = serializers.DateTimeField(
        allow_null=True, help_text="When the content was computed. Null when no highlights were computed yet today."
    )
    day = serializers.DateField(help_text="The day the highlights are for, in the project's timezone.")
    refresh_at = serializers.DateTimeField(
        help_text="Midnight at the end of `day` in the project's timezone, when the next day's highlights start. Load them again then."
    )
    pulse = HighlightMetricSerializer(many=True, help_text="Key metrics of the project from its settings.")
    pulse_slots = PulseSlotSerializer(
        many=True,
        allow_null=True,
        required=False,
        help_text="Selected numbers in stable display order, including unfinished numbers. Ready values are in pulse. Null for clients using complete results.",
    )
    items = HighlightItemSerializer(
        many=True,
        help_text="Up to 6 items, the highest scores across sources, in display order: by `priority`, then by `score`, highest first.",
    )
    pins = HighlightPinSerializer(
        many=True,
        help_text="The numbers the person keeps, in their order, with the state of each one. Pinned numbers lead `pulse`.",
    )

    class Meta:
        dataclass = Highlights