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.

7.7 KB
Raw Blame
from __future__ import annotations

from collections.abc import Sequence
from typing import Any, cast

from pydantic import ValidationError

from posthog.schema import ArtifactContentType, ArtifactSource, VisualizationArtifactContent, VisualizationMessage

from posthog.models import Team

from products.posthog_ai.backend.models.assistant import AgentArtifact
from products.product_analytics.backend.facade.models import Insight

from ee.hogai.artifacts.handlers.base import ArtifactHandler, EnrichmentContext, register_handler
from ee.hogai.artifacts.types import (
    DatabaseArtifactResult,
    ModelArtifactResult,
    StateArtifactResult,
    VisualizationWithSourceResult,
)
from ee.hogai.context.insight.context import InsightContext
from ee.hogai.utils.types.base import AssistantMessageUnion


@register_handler
class VisualizationHandler(ArtifactHandler[VisualizationArtifactContent, VisualizationArtifactContent]):
    """
    Handler for visualization artifacts.

    Visualizations can come from three sources:
    - STATE: In-memory VisualizationMessage in conversation state
    - ARTIFACT: Saved in AgentArtifact table
    - INSIGHT: Saved as Insight model

    No enrichment needed - stored content is already in final form.
    """

    content_class = VisualizationArtifactContent
    enriched_class = VisualizationArtifactContent  # Same, no enrichment
    db_type = AgentArtifact.Type.VISUALIZATION
    content_type = ArtifactContentType.VISUALIZATION

    async def alist(
        self,
        team: Team,
        ids: list[str],
        state_messages: Sequence[AssistantMessageUnion] | None = None,
    ) -> list[VisualizationWithSourceResult | None]:
        """
        Fetch visualizations with source tracking and Insight models.

        Returns ordered list matching input IDs (None for missing IDs).
        """
        if not ids:
            return []

        results_map: dict[str, VisualizationWithSourceResult] = {}
        remaining = set(ids)

        # 1. Check state messages first
        if state_messages:
            for artifact_id in list(remaining):
                content = self._from_state(artifact_id, state_messages)
                if content is not None:
                    results_map[artifact_id] = StateArtifactResult(content=content)
                    remaining.discard(artifact_id)

        # 2. Check artifact DB
        if remaining:
            db_contents = await self._from_db(list(remaining), team)
            for artifact_id, content in db_contents.items():
                results_map[artifact_id] = DatabaseArtifactResult(content=content)
                remaining.discard(artifact_id)

        # 3. Check insights table - get both content AND model in single query
        if remaining:
            insight_results = await self._from_insights_with_models(list(remaining), team)
            for artifact_id, (content, model) in insight_results.items():
                results_map[artifact_id] = ModelArtifactResult(
                    source=ArtifactSource.INSIGHT,
                    content=content,
                    model=model,
                )

        # Return ordered list matching input
        return [results_map.get(artifact_id) for artifact_id in ids]

    async def aenrich(
        self,
        content: VisualizationArtifactContent,
        context: EnrichmentContext,
    ) -> VisualizationArtifactContent:
        """No enrichment needed for visualizations."""
        return content

    def get_metadata(self, content: VisualizationArtifactContent) -> dict[str, Any]:
        return {
            "name": content.name,
            "description": content.description,
        }

    def _from_state(
        self, artifact_id: str, messages: Sequence[AssistantMessageUnion]
    ) -> VisualizationArtifactContent | None:
        """
        Extract content from a VisualizationMessage in state.

        Field mappings from VisualizationMessage to VisualizationArtifactContent:
        - answer -> query: The actual query object (e.g., TrendsQuery)
        - query -> name: The user's original query text (used as chart title)
        - plan -> description: The agent's plan/explanation
        """
        for msg in messages:
            if isinstance(msg, VisualizationMessage) and msg.id == artifact_id:
                # msg.answer is already validated by VisualizationMessage, so use
                # model_construct to avoid redundant re-validation against the large
                # VisualizationArtifactContent.query union (which fails for older schemas).
                return VisualizationArtifactContent.model_construct(
                    query=msg.answer,
                    name="Insight",
                    plan=msg.plan,
                )
        return None

    async def _from_db(self, artifact_ids: list[str], team: Team) -> dict[str, VisualizationArtifactContent]:
        """Fetch visualization contents from AgentArtifact table."""
        if not artifact_ids:
            return {}

        artifacts = AgentArtifact.objects.filter(
            short_id__in=artifact_ids,
            team=team,
            type=AgentArtifact.Type.VISUALIZATION,
        )
        result: dict[str, VisualizationArtifactContent] = {}
        async for artifact in artifacts:
            try:
                result[artifact.short_id] = VisualizationArtifactContent.model_validate(artifact.data)
            except ValidationError:
                # Skip invalid data
                continue
        return result

    async def _from_insights_with_models(
        self, insight_ids: list[str], team: Team
    ) -> dict[str, tuple[VisualizationArtifactContent, Insight]]:
        """Fetch visualization contents along with their Insight models (single query)."""
        if not insight_ids:
            return {}

        insights = Insight.objects.filter(
            short_id__in=insight_ids,
            team=team,
            deleted=False,
            saved=True,
        )
        result: dict[str, tuple[VisualizationArtifactContent, Insight]] = {}
        async for insight in insights:
            query_obj = InsightContext.extract_query(insight)
            if query_obj is None:
                continue
            content = VisualizationArtifactContent(
                query=query_obj,
                name=insight.name or insight.derived_name,
                description=insight.description,
            )
            result[insight.short_id] = (content, insight)
        return result


class VisualizationArtifactManagerMixin:
    """
    Mixin providing visualization-specific artifact retrieval methods.

    Mix into ArtifactManager to add type-safe visualization fetching.
    """

    # These are provided by ArtifactManager
    _team: Team

    async def aget_visualizations(
        self,
        state_messages: Sequence[AssistantMessageUnion],
        artifact_ids: list[str],
    ) -> list[VisualizationWithSourceResult | None]:
        """
        Fetch visualizations by IDs.

        Checks sources in priority order: STATE, ARTIFACT, INSIGHT.
        Returns ordered list matching input artifact_ids (None for missing IDs).
        """
        if not artifact_ids:
            return []
        handler = VisualizationHandler()
        return cast(
            list[VisualizationWithSourceResult | None],
            await handler.alist(self._team, artifact_ids, state_messages),
        )

    async def aget_visualization(
        self,
        state_messages: Sequence[AssistantMessageUnion],
        artifact_id: str,
    ) -> VisualizationWithSourceResult | None:
        """
        Fetch a single visualization by ID.

        Checks sources in priority order: STATE, ARTIFACT, INSIGHT.
        """
        results = await self.aget_visualizations(state_messages, [artifact_id])
        return results[0] if results else None