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.

8.4 KB
Raw Blame
from collections.abc import Sequence
from enum import Enum
from typing import Any

from posthog.schema import MarkdownBlock

from posthog.models import Team, User

from products.access_control.backend.facade.user_access_control import UserAccessControl
from products.notebooks.backend.facade import (
    api as notebooks,
    collab,
)
from products.notebooks.backend.facade.content import (
    build_markdown_notebook_content,
    convert_notebook_content_to_markdown,
)
from products.notebooks.backend.facade.contracts import NotebookData
from products.posthog_ai.backend.models.assistant import AgentArtifact

from ee.hogai.artifacts.handlers.visualization import VisualizationHandler
from ee.hogai.artifacts.manager import ArtifactManager
from ee.hogai.artifacts.types import StoredBlock, StoredNotebookArtifactContent, VisualizationRefBlock
from ee.hogai.tools.create_notebook.parsing import parse_notebook_content_for_storage
from ee.hogai.tools.create_notebook.tiptap import blocks_to_tiptap_doc
from ee.hogai.utils.types.base import AssistantMessageUnion


class ArtifactStatus(Enum):
    CREATED = "created"
    UPDATED = "updated"
    FAILED_TO_UPDATE = "failed_to_update"


class NotebookEditNotAllowedError(Exception):
    """The user lacks editor access on the saved notebook this artifact would overwrite."""


MARKDOWN_NOTEBOOK_NODE_ID = "markdown-notebook-v2"
MARKDOWN_NOTEBOOK_NODE_TYPE = "ph-markdown-notebook"


def _get_markdown_notebook_node(content: Any) -> dict[str, Any] | None:
    if not isinstance(content, dict):
        return None

    nodes = content.get("content")
    if not isinstance(nodes, list) or len(nodes) != 1:
        return None

    node = nodes[0]
    if not isinstance(node, dict) or node.get("type") != MARKDOWN_NOTEBOOK_NODE_TYPE:
        return None

    return node


def _build_markdown_notebook_doc(markdown: str, existing_content: Any) -> dict[str, Any]:
    existing_node = _get_markdown_notebook_node(existing_content)
    existing_attrs = existing_node.get("attrs") if existing_node else None
    attrs: dict[str, Any] = existing_attrs.copy() if isinstance(existing_attrs, dict) else {}
    node_id = attrs.get("nodeId")
    if not isinstance(node_id, str) or not node_id:
        attrs["nodeId"] = MARKDOWN_NOTEBOOK_NODE_ID
    attrs["markdown"] = markdown

    return {
        "type": "doc",
        "content": [
            {
                "type": MARKDOWN_NOTEBOOK_NODE_TYPE,
                "attrs": attrs,
            }
        ],
    }


async def create_or_update_notebook_artifact(
    artifacts_manager: ArtifactManager,
    content: str,
    title: str,
    artifact_id: str | None = None,
) -> tuple[AgentArtifact, ArtifactStatus, list[StoredBlock]]:
    """
    Parse markdown content and create or update a notebook artifact.

    Returns:
        tuple of (artifact, status, parsed_blocks)
    """
    blocks = parse_notebook_content_for_storage(content, title=title)
    artifact_content = StoredNotebookArtifactContent(blocks=blocks, title=title)

    artifact = None
    status = ArtifactStatus.CREATED

    if artifact_id:
        try:
            artifact = await artifacts_manager.aupdate(artifact_id, artifact_content)
            status = ArtifactStatus.UPDATED
        except ValueError:
            status = ArtifactStatus.FAILED_TO_UPDATE

    if not artifact:
        artifact = await artifacts_manager.acreate(content=artifact_content, name=title)
        if status != ArtifactStatus.FAILED_TO_UPDATE:
            status = ArtifactStatus.CREATED

    return artifact, status, blocks


async def save_notebook_to_db(
    team: Team,
    user: User,
    artifact: AgentArtifact,
    blocks: Sequence[StoredBlock],
    title: str,
    state_messages: Sequence[AssistantMessageUnion],
    markdown_content: str | None = None,
) -> NotebookData:
    """
    Save or update a real Notebook record with the same short_id as the artifact.

    If a Notebook with the artifact's short_id already exists, update its content.
    Otherwise, create a new Notebook.

    Raises NotebookEditNotAllowedError when a notebook exists and the user does not
    have editor access to it — Max acts on the user's behalf and must not overwrite
    notebooks the user couldn't edit themselves.
    """
    existing_notebook = await notebooks.aget_notebook(team.id, artifact.short_id, include_deleted=True)
    if existing_notebook is not None:
        access_control = UserAccessControl(user=user, team=team)
        if not await notebooks.acan_user_edit_notebook(team.id, artifact.short_id, user_access_control=access_control):
            raise NotebookEditNotAllowedError(
                f"User {user.id} does not have editor access to notebook {existing_notebook.short_id}"
            )

    if existing_notebook and markdown_content is not None and _get_markdown_notebook_node(existing_notebook.content):
        previous_content = existing_notebook.content
        next_content = _build_markdown_notebook_doc(markdown_content, previous_content)
        updated_notebook = await notebooks.aupdate_notebook_content(
            team.id,
            artifact.short_id,
            content=next_content,
            title=title,
            text_content=markdown_content,
            user=user,
        )
        if updated_notebook is None:
            raise RuntimeError(f"Notebook {artifact.short_id} disappeared during content update")
        # The base_crc inside the diff lets receivers detect a racing concurrent edit
        # (this path has no version CAS) and fall back to a reload instead of misapplying.
        await collab.apublish_notebook_update(
            team.id,
            str(updated_notebook.short_id),
            updated_notebook.version,
            diff=collab.build_markdown_update_diff(previous_content, next_content),
        )
        return updated_notebook

    # Resolve viz refs through the unified handler (state → AgentArtifact → Insight),
    # matching the chat preview. A direct AgentArtifact query misses state-only charts.
    ref_ids = [block.artifact_id for block in blocks if isinstance(block, VisualizationRefBlock)]
    viz_lookup: dict[str, dict] = {}
    if ref_ids:
        viz_handler = VisualizationHandler()
        results = await viz_handler.alist(team, ref_ids, state_messages)
        for ref_id, result in zip(ref_ids, results):
            if result is None or result.content.query is None:
                continue
            query = result.content.query.model_dump(mode="json", exclude_none=True)
            kind = query.get("kind", "")
            if kind == "DataVisualizationNode":
                # Already a top-level SQL chart node, do not double-wrap.
                notebook_query = query
            elif kind == "HogQLQuery" or "HogQL" in kind:
                notebook_query = {"kind": "DataVisualizationNode", "source": query}
            else:
                notebook_query = {"kind": "InsightVizNode", "source": query}
            viz_lookup[ref_id] = {"query": notebook_query, "name": result.content.name}

    def resolve_visualization(artifact_id: str) -> dict | None:
        return viz_lookup.get(artifact_id)

    tiptap_doc = blocks_to_tiptap_doc(blocks, title=title, resolve_visualization=resolve_visualization)

    # New notebooks are always markdown. Existing TipTap notebooks keep their stored
    # format so open editors don't flip formats mid-session.
    content: dict[str, Any] = tiptap_doc
    text_content: str | None = None
    if existing_notebook is None:
        # Markdown blocks can contain live MDX cells that the TipTap parser treats as plain text.
        markdown = "\n\n".join(
            [f"# {title}"]
            + [
                block.content
                if isinstance(block, MarkdownBlock)
                else convert_notebook_content_to_markdown(
                    blocks_to_tiptap_doc([block], resolve_visualization=resolve_visualization)
                )
                for block in blocks
            ]
        )
        content = build_markdown_notebook_content(markdown)
        text_content = markdown

    notebook, created = await notebooks.aupsert_notebook(
        team.id,
        artifact.short_id,
        created_by_id=user.id,
        user=user,
        title=title,
        content=content,
        text_content=text_content,
    )
    if not created:
        await collab.apublish_notebook_update(team.id, str(notebook.short_id), notebook.version)

    return notebook


async def notebook_exists_for_artifact(team: Team, short_id: str) -> bool:
    return await notebooks.anotebook_exists(team.id, short_id)