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.

12.6 KB
Raw Blame
import uuid
from typing import Any, Literal, Self

from langchain_core.runnables import RunnableConfig
from pydantic import BaseModel, Field

from posthog.schema import ArtifactContentType, ArtifactSource, AssistantTool, AssistantToolCallMessage

from posthog.models import Team, User
from posthog.sync import database_sync_to_async

from products.notebooks.backend.facade import api as notebooks
from products.notebooks.backend.facade.contracts import NotebookCellLimitExceeded, NotebookContentEditNotAllowed
from products.notebooks.backend.facade.widget_catalog import format_notebook_widget_catalog_for_agents

from ee.hogai.context.context import AssistantContextManager
from ee.hogai.context.notebook.prompts import cell_guidance_prompt
from ee.hogai.tool import MaxTool, ToolMessagesArtifact
from ee.hogai.tools.create_notebook.helpers import (
    ArtifactStatus,
    NotebookEditNotAllowedError,
    create_or_update_notebook_artifact,
    notebook_exists_for_artifact,
    save_notebook_to_db,
)
from ee.hogai.utils.types.base import AssistantState, NodePath

NOTEBOOK_WIDGET_CATALOG_PROMPT = format_notebook_widget_catalog_for_agents()


def create_notebook_prompt(*, sql_v2_enabled: bool) -> str:
    """Build the tool description for one user.

    `sql_v2_enabled` follows the same flag the notebook run endpoint enforces. Without it the
    endpoint rejects a run, and the editor still renders the cell with a working-looking Run
    button, so an authored SQLV2 or PythonV2 cell gives the user a dead control and no
    explanation. Offer the ungated `<Query />` cell to those users instead.
    """
    cell_guidance = cell_guidance_prompt(sql_v2_enabled=sql_v2_enabled)
    return f"""
Use this tool to create a notebook document with rich content.

# Use this when:
- The user asks for a report, summary, or document
- You want to combine multiple insights with explanatory text
- The user requests a structured analysis or investigation summary
- You want to write a draft notebook for yourself, to review later

# Content vs Draft Content:
You must use EXACTLY ONE of these parameters:
- `content`: Use this when you want to show the notebook to the user immediately. The notebook will be streamed as you write it.
- `draft_content`: Use this when you want to save a draft without showing it to the user. Useful for writing a first version before it's ready, of for taking intermediate finding notes before writing the final version.

# When creating notebook content:
1. Use markdown headings to structure sections (# for main headings, ## for subsections)
2. Reference existing visualization artifacts using <insight>insight_id</insight> tags
3. Include explanatory text around insights to provide context
4. Use bullet points and numbered lists for clarity
5. Include code blocks with triple backticks if showing HogQL or other code

# How to use the <insight>insight_id</insight> tag:
You can use the <insight>insight_id</insight> tag to reference existing visualization insights.
Use the list_data tool with kind=artifacts to retrieve artifact ids, when in doubt.

# PostHog object widgets:
Add object widgets with component tags, for example `<FeatureFlag id={{123}} view="summary" />`.
Use the identity prop and view that fit the task:

{NOTEBOOK_WIDGET_CATALOG_PROMPT}

# Best practices:
The document should be structured as a series of sections, each with a heading and a body.
Try to use each section to answer a single question or provide a single insight.
Don't be verbose, get straight to the point. Data-heavy short documents are preferred over long documents.
Don't repeat yourself. If you've already mentioned an insight or artifact in a previous section, don't mention it again.

# Example content format:
```
# Weekly Analytics Report

## Key Metrics Overview

Here's the main trends insight showing our weekly active users:

<insight>abc123</insight>

As we can see, there's been a 15% increase week-over-week.

## Funnel Analysis

Our signup funnel shows the following conversion rates:

<insight>def456</insight>

### Recommendations

1. Focus on improving step 2 to 3 conversion
2. Consider A/B testing the signup flow
```

# Updating existing notebooks:
- If you want to update an existing notebook, use the `artifact_id` parameter to specify the ID of the existing artifact
- *IMPORTANT*: Updating a notebook will replace the existing content with the new content

# Editing a Markdown notebook v2 from inline AI:
- When the UI context includes a Markdown notebook with an inline response placeholder, use this tool with `content` when the user asks to clean up, rewrite, reorganize, or replace the whole notebook
- In that case, `content` must be the complete final markdown for the notebook, not just the text that replaces the inline prompt
- The editor applies the artifact to the open notebook. Do not save a separate notebook or call another notebook editing tool for the same change
- Do not include the inline placeholder text, empty `<Prompt question="" />` blocks, or the user's instruction prompt in the final markdown unless the user explicitly asks to keep them
- Use a direct assistant markdown response instead of this tool only for local answers or small insertions that should replace the inline response placeholder
{cell_guidance}

# Transient vs saved notebooks:
- By default, notebooks are created as transient artifacts visible only in this conversation. Do NOT share URLs or references to notebook pages for transient artifacts.
- Set save_to_notebook=True ONLY when the user explicitly asks to save, persist, or create a permanent notebook.
- When updating an artifact that is already saved to the database, the saved notebook is automatically updated too.
"""


class CreateNotebookToolArgs(BaseModel):
    content: str | None = Field(
        default=None,
        description="The notebook content in markdown format. Use this to show the notebook to the user immediately (it will be streamed). Use <insight>artifact_id</insight> tags to reference existing visualization artifacts.",
    )
    draft_content: str | None = Field(
        default=None,
        description="The notebook content in markdown format for a draft. Use this to save a draft without showing it to the user. Use <insight>artifact_id</insight> tags to reference existing visualization artifacts.",
    )
    title: str = Field(description="A descriptive title for the notebook.")
    artifact_id: str | None = Field(
        default=None, description="The ID of an existing notebook artifact that you want to update."
    )
    save_to_notebook: bool = Field(
        default=False,
        description="Set to true ONLY when the user explicitly asks to save/persist the notebook to the database.",
    )


class CreateNotebookTool(MaxTool):
    name: Literal[AssistantTool.CREATE_NOTEBOOK] = AssistantTool.CREATE_NOTEBOOK
    args_schema: type[BaseModel] = CreateNotebookToolArgs
    # Fail closed: a caller that skips `create_tool_class` gets the description that authors no
    # cell the user may be unable to run.
    description: str = create_notebook_prompt(sql_v2_enabled=False)

    @classmethod
    async def create_tool_class(
        cls,
        *,
        team: Team,
        user: User,
        node_path: tuple[NodePath, ...] | None = None,
        state: AssistantState | None = None,
        config: RunnableConfig | None = None,
        context_manager: AssistantContextManager | None = None,
    ) -> Self:
        # The flag lookup reads `user.organization`, so it needs a thread with a database
        # connection rather than this coroutine.
        sql_v2_enabled = await database_sync_to_async(notebooks.is_sql_v2_enabled)(user)
        return cls(
            team=team,
            user=user,
            node_path=node_path,
            state=state,
            config=config,
            context_manager=context_manager,
            description=create_notebook_prompt(sql_v2_enabled=sql_v2_enabled),
        )

    async def _arun_impl(
        self,
        title: str,
        content: str | None = None,
        draft_content: str | None = None,
        artifact_id: str | None = None,
        save_to_notebook: bool = False,
    ) -> tuple[str, Any]:
        if content is not None and draft_content is not None:
            return "Error: Cannot provide both 'content' and 'draft_content'. Use exactly one.", None

        if content is None and draft_content is None:
            return "Error: Either 'content' or 'draft_content' must be provided.", None

        is_draft = draft_content is not None
        notebook_content = draft_content if is_draft else content
        assert notebook_content is not None

        ui_context = self._context_manager.get_ui_context(self._state)
        inline_notebook = (
            next(
                (notebook for notebook in (ui_context.notebooks or []) if notebook.insertion_placeholder_block_id),
                None,
            )
            if ui_context
            else None
        )

        artifact, status, blocks = await create_or_update_notebook_artifact(
            artifacts_manager=self._context_manager.artifacts,
            content=notebook_content,
            title=title,
            artifact_id=artifact_id,
        )

        # Check if this artifact already has a saved notebook
        is_already_saved = await notebook_exists_for_artifact(self._team, artifact.short_id)

        # Save to DB if explicitly requested or if updating an already-saved notebook
        # The inline editor owns the save, including the user's retained prompt and unsaved edits.
        should_save = (save_to_notebook or is_already_saved) and inline_notebook is None
        if should_save:
            try:
                await save_notebook_to_db(
                    team=self._team,
                    user=self._user,
                    artifact=artifact,
                    blocks=blocks,
                    title=title,
                    state_messages=self._state.messages,
                    markdown_content=notebook_content,
                )
            except NotebookEditNotAllowedError:
                return (
                    f"Error: The user does not have permission to edit the saved notebook {artifact.short_id}, "
                    "so it was not changed.",
                    None,
                )
            except (NotebookCellLimitExceeded, NotebookContentEditNotAllowed) as err:
                # Deterministic: the same save fails again, so say so rather than letting the
                # model spend turns retrying it.
                return (
                    f"Error: {err} The notebook was not changed, so do not retry this save.",
                    None,
                )

        # Build response message
        if inline_notebook is not None:
            message = (
                f"The notebook artifact is for the open notebook {inline_notebook.id}. "
                "The editor applies it there when streamed. No separate notebook was saved. "
                "Do not save another copy or repeat this edit with another notebook tool."
            )
        elif should_save:
            if status == ArtifactStatus.UPDATED:
                message = f"The notebook artifact and saved notebook have been updated (short_id: {artifact.short_id})."
            else:
                message = f"The notebook has been saved with short_id: {artifact.short_id}. It is accessible at /notebooks/{artifact.short_id}."
        else:
            message = (
                f"The notebook artifact has been created with artifact_id: {artifact.short_id}. "
                "This is a transient artifact visible only in this conversation. "
                "The user can save it by clicking 'Create notebook' in the UI, or ask you to save it."
            )
            if status == ArtifactStatus.FAILED_TO_UPDATE:
                message = (
                    f"Failed to update the existing notebook artifact. "
                    f"A new artifact has been created with artifact_id: {artifact.short_id}. "
                    "This is a transient artifact visible only in this conversation."
                )
            elif status == ArtifactStatus.UPDATED:
                message = f"The notebook artifact with artifact_id {artifact_id} has been updated."

        if is_draft:
            return message, None

        artifact_message = self._context_manager.artifacts.create_message(
            artifact_id=artifact.short_id,
            source=ArtifactSource.ARTIFACT,
            content_type=ArtifactContentType.NOTEBOOK,
        )

        return "", ToolMessagesArtifact(
            messages=[
                artifact_message,
                AssistantToolCallMessage(content=message, tool_call_id=self.tool_call_id, id=str(uuid.uuid4())),
            ]
        )