: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 __future__ import annotations
from collections.abc import Sequence
from typing import Any, cast
from pydantic import ValidationError
from posthog.schema import ArtifactContentType, ErrorBlock, NotebookArtifactContent, VisualizationBlock
from posthog.models import Team
from products.notebooks.backend.facade import api as notebooks
from products.posthog_ai.backend.models.assistant import AgentArtifact
from ee.hogai.artifacts.handlers.base import (
ArtifactHandler,
EnrichmentContext,
get_handler_for_content_type,
register_handler,
)
from ee.hogai.artifacts.types import (
DatabaseArtifactResult,
EnrichedBlock,
NotebookWithSourceResult,
StoredNotebookArtifactContent,
VisualizationRefBlock,
)
from ee.hogai.context.insight.query_executor import is_supported_query
from ee.hogai.utils.types.base import AssistantMessageUnion
@register_handler
class NotebookHandler(ArtifactHandler[StoredNotebookArtifactContent, NotebookArtifactContent]):
"""
Handler for notebook artifacts.
Notebooks are only stored in the ARTIFACT source (AgentArtifact table).
They contain VisualizationRefBlock references that need to be enriched
to full VisualizationBlock content when streaming.
"""
content_class = StoredNotebookArtifactContent
enriched_class = NotebookArtifactContent
db_type = AgentArtifact.Type.NOTEBOOK
content_type = ArtifactContentType.NOTEBOOK
async def alist(
self,
team: Team,
ids: list[str],
state_messages: Sequence[AssistantMessageUnion] | None = None,
) -> list[NotebookWithSourceResult | None]:
"""
Fetch notebook content by IDs from AgentArtifact table.
Returns ordered list matching input IDs (None for missing artifacts).
"""
if not ids:
return []
artifacts = AgentArtifact.objects.filter(
short_id__in=ids,
team=team,
type=AgentArtifact.Type.NOTEBOOK,
)
result: dict[str, NotebookWithSourceResult] = {}
async for artifact in artifacts:
try:
content = StoredNotebookArtifactContent.model_validate(artifact.data)
result[artifact.short_id] = DatabaseArtifactResult(content=content)
except ValidationError:
# Skip invalid data
continue
return [result.get(artifact_id) for artifact_id in ids]
async def aenrich(
self,
content: StoredNotebookArtifactContent,
context: EnrichmentContext,
) -> NotebookArtifactContent:
"""
Enrich notebook by resolving VisualizationRefBlock references.
Converts VisualizationRefBlock → VisualizationBlock (with full query data)
or ErrorBlock (if artifact not found).
"""
# Collect all artifact IDs from VisualizationRefBlock
viz_ids = [block.artifact_id for block in content.blocks if isinstance(block, VisualizationRefBlock)]
# Fetch visualization contents using the visualization handler
viz_contents = await self._list_visualization_contents(viz_ids, context.team, context.state_messages)
# Build enriched blocks
enriched_blocks: list[EnrichedBlock] = []
for block in content.blocks:
if isinstance(block, VisualizationRefBlock):
viz_content = viz_contents.get(block.artifact_id)
if viz_content is None:
# Artifact not found - generate error block
enriched_blocks.append(
ErrorBlock(
message=f"Visualization not found: {block.artifact_id}",
artifact_id=block.artifact_id,
)
)
elif not is_supported_query(viz_content.query):
# Query type not supported for rendering
enriched_blocks.append(
ErrorBlock(
message=f"Unsupported query type: {type(viz_content.query).__name__}",
artifact_id=block.artifact_id,
)
)
else:
# Valid visualization - cast is safe now after runtime validation
enriched_blocks.append(
VisualizationBlock(
query=cast(Any, viz_content.query),
title=block.title or viz_content.name,
)
)
else:
# Pass through other block types unchanged
enriched_blocks.append(block)
is_saved = False
if context.artifact_id:
is_saved = await notebooks.anotebook_exists(context.team.id, context.artifact_id)
return NotebookArtifactContent(
blocks=enriched_blocks,
title=content.title,
is_saved=is_saved,
)
def get_metadata(self, content: StoredNotebookArtifactContent) -> dict[str, Any]:
return {
"title": content.title,
}
async def _list_visualization_contents(
self,
artifact_ids: list[str],
team: Team,
state_messages: Sequence[AssistantMessageUnion] | None = None,
):
"""
Fetch visualization contents for ref block artifact IDs.
Uses the VisualizationHandler (via registry) to handle fetching from all sources.
Returns dict mapping artifact_id -> content for easy lookup during enrichment.
"""
if not artifact_ids:
return {}
viz_handler = get_handler_for_content_type(ArtifactContentType.VISUALIZATION)
if viz_handler is None:
return {}
# list returns result wrappers, extract content for lookup
results = await viz_handler.alist(team, artifact_ids, state_messages)
return {artifact_id: result.content for artifact_id, result in zip(artifact_ids, results) if result is not None}
class NotebookArtifactManagerMixin:
"""
Mixin providing notebook-specific artifact retrieval methods.
Mix into ArtifactManager to add type-safe notebook fetching.
"""
# These are provided by ArtifactManager
_team: Team
async def aget_notebooks(
self,
state_messages: Sequence[AssistantMessageUnion],
artifact_ids: list[str],
) -> list[NotebookWithSourceResult | None]:
"""
Fetch notebooks by IDs.
Notebooks are only stored in the ARTIFACT source.
Returns ordered list matching input artifact_ids (None for missing IDs).
"""
if not artifact_ids:
return []
handler = NotebookHandler()
return cast(
list[NotebookWithSourceResult | None],
await handler.alist(self._team, artifact_ids, state_messages),
)
async def aget_notebook(
self,
state_messages: Sequence[AssistantMessageUnion],
artifact_id: str,
) -> NotebookWithSourceResult | None:
"""
Fetch a single notebook by ID.
"""
results = await self.aget_notebooks(state_messages, [artifact_id])
return results[0] if results else None