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.

36.4 KB
Raw Blame
import hashlib
from base64 import urlsafe_b64encode
from typing import Any, Literal, TypedDict, cast

from django.db import transaction
from django.http import HttpRequest

import structlog
from pydantic import BaseModel, Field
from rest_framework.exceptions import PermissionDenied, ValidationError
from rest_framework.request import Request

from posthog.schema import (
    DataTableNode,
    DataVisualizationNode,
    HogQLQuery,
    HogQLVariable,
    InsightVizNode,
    QuerySchemaRoot,
)

from posthog.api.sharing_publish_gate import check_can_add_insight_to_dashboard
from posthog.event_usage import EventSource, report_user_action
from posthog.sync import database_sync_to_async
from posthog.utils import pluralize

from products.dashboards.backend.api.dashboard import DashboardSerializer
from products.dashboards.backend.models.dashboard import Dashboard
from products.dashboards.backend.models.dashboard_tile import DashboardTile
from products.product_analytics.backend.facade.api import (
    get_or_create_saved_insight,
    insight_variables_for_team,
    insights_including_soft_deleted_for_team,
)
from products.product_analytics.backend.facade.models import Insight

from ee.hogai.artifacts.types import ModelArtifactResult, VisualizationWithSourceResult
from ee.hogai.context.dashboard.context import DashboardContext, DashboardInsightContext
from ee.hogai.context.insight.context import InsightContext
from ee.hogai.tool import MaxTool
from ee.hogai.tool_errors import MaxToolAccessDeniedError, MaxToolFatalError, MaxToolRetryableError
from ee.hogai.tools.upsert_dashboard.prompts import (
    CREATE_NO_INSIGHTS_PROMPT,
    DASHBOARD_NOT_FOUND_PROMPT,
    MISSING_INSIGHT_IDS_PROMPT,
    PERMISSION_REQUEST_PROMPT,
    UNKNOWN_VARIABLES_PROMPT,
    UPDATE_NO_CHANGES_PROMPT,
    UPSERT_DASHBOARD_CONTEXT_PROMPT_TEMPLATE,
    UPSERT_DASHBOARD_TOOL_PROMPT,
)
from ee.hogai.utils.prompt import format_prompt_string

logger = structlog.get_logger(__name__)


class CreateDashboardToolArgs(BaseModel):
    """Schema to create a new dashboard with provided insights."""

    action: Literal["create"] = "create"
    insight_ids: list[str] = Field(
        description="The IDs of the insights to be included in the dashboard. It might be a mix of existing and new insights."
    )
    name: str = Field(
        description="A short and concise (3-7 words) name of the dashboard. It will be displayed as a header in the dashboard tile."
    )
    description: str = Field(description="A short and concise description of the dashboard.")


class UpdateDashboardToolArgs(BaseModel):
    """Schema to update an existing dashboard with provided insights."""

    action: Literal["update"] = "update"
    dashboard_id: str = Field(description="Provide the ID of the dashboard to be update it.")
    insight_ids: list[str] | None = Field(
        description="The IDs of the insights for the dashboard. Replaces all existing insights.",
        default=None,
    )
    layout_mode: Literal["preserve_existing", "reflow_all"] = Field(
        description="How to handle existing tile layouts when insight_ids are provided. Use preserve_existing by default. Use reflow_all only when the user explicitly asks to rearrange or reorder tiles.",
        default="preserve_existing",
    )
    name: str | None = Field(
        description="A short and concise (3-7 words) name of the dashboard. If not provided, the dashboard name will not be updated.",
        default=None,
    )
    description: str | None = Field(
        description="A short and concise description of the dashboard. If not provided, the dashboard description will not be updated.",
        default=None,
    )


class AddDashboardInsightsToolArgs(BaseModel):
    """Schema to add insights to an existing dashboard without removing its tiles."""

    action: Literal["add_insights"] = "add_insights"
    dashboard_id: str = Field(description="Provide the ID of the dashboard to add insights to.")
    insight_ids: list[str] = Field(description="The IDs of the insights to add to the dashboard.")


class DuplicateDashboardToolArgs(BaseModel):
    """Schema to copy an existing dashboard with its variables, filters, tiles, and insight display settings."""

    action: Literal["duplicate"] = "duplicate"
    dashboard_id: str = Field(description="The ID of the dashboard to copy.")
    name: str = Field(description="A short and concise (3-7 words) name of the new dashboard.")
    description: str | None = Field(
        description="A short description of the new dashboard. If not provided, the source description is kept.",
        default=None,
    )
    variable_values: dict[str, Any] | None = Field(
        description=(
            "New values for SQL variables on the copy, keyed by the variable code name, "
            'for example {"subscription_id": "sub_123"}. Variables that are not listed keep the source values.'
        ),
        default=None,
    )


UpsertDashboardAction = (
    CreateDashboardToolArgs | UpdateDashboardToolArgs | AddDashboardInsightsToolArgs | DuplicateDashboardToolArgs
)


class UpsertDashboardToolArgs(BaseModel):
    action: UpsertDashboardAction = Field(
        description="The action to perform. Either create a new dashboard or update an existing one.",
        discriminator="action",
    )


class UpdateDiff(TypedDict):
    created: list[VisualizationWithSourceResult]
    deleted: list[DashboardTile]


class ReflowRowItem(TypedDict):
    tile: DashboardTile
    h: int
    w: int


class ReflowTileLayoutUpdate(TypedDict):
    tile: DashboardTile
    layouts: dict[str, dict[str, int]]


class UpsertDashboardTool(MaxTool):
    name: Literal["upsert_dashboard"] = "upsert_dashboard"
    description: str = UPSERT_DASHBOARD_TOOL_PROMPT
    context_prompt_template: str = UPSERT_DASHBOARD_CONTEXT_PROMPT_TEMPLATE
    args_schema: type[BaseModel] = UpsertDashboardToolArgs
    _cached_update_diff: UpdateDiff | None = None

    def get_required_resource_access(self):
        return [("dashboard", "editor")]

    async def is_dangerous_operation(self, *, action: UpsertDashboardAction, **kwargs) -> bool:
        """Update operations that delete existing insights are dangerous."""
        if isinstance(action, UpdateDashboardToolArgs) and action.insight_ids:
            dashboard = await self._get_dashboard(action.dashboard_id)
            sorted_tiles = await self._get_dashboard_sorted_tiles(dashboard)
            diff = await self._get_update_diff(sorted_tiles, action.insight_ids)
            return len(diff["deleted"]) > 0
        return False

    async def format_dangerous_operation_preview(self, *, action: UpsertDashboardAction, **kwargs) -> str:
        """
        Build a rich preview showing dashboard details and what will be modified.
        """
        if not isinstance(action, UpdateDashboardToolArgs):
            raise MaxToolFatalError("Only dashboard updates can require a dangerous operation preview.")

        dashboard = await self._get_dashboard(action.dashboard_id)
        sorted_tiles = await self._get_dashboard_sorted_tiles(dashboard)
        diff = await self._get_update_diff(sorted_tiles, action.insight_ids or [])

        def get_insight_name(insight: Insight) -> str:
            return insight.name or insight.derived_name or f"Insight #{insight.short_id or insight.id}"

        def get_artifact_name(artifact: VisualizationWithSourceResult) -> str:
            return artifact.content.name or "Insight"

        def join(items: list[str]) -> str:
            return "\n".join(f"- {item}" for item in items)

        created_list = [get_artifact_name(artifact) for artifact in diff["created"]]
        deleted_list = [get_insight_name(tile.insight) for tile in diff["deleted"] if tile.insight is not None]

        return format_prompt_string(
            PERMISSION_REQUEST_PROMPT,
            dashboard_name=dashboard.name or f"Dashboard #{dashboard.id}",
            new_dashboard_name=action.name,
            new_dashboard_description=action.description,
            deleted_insights=join(deleted_list),
            deleted_count=pluralize(len(deleted_list), "insight"),
            new_insights=join(created_list),
            added_count=pluralize(len(created_list), "insight"),
        )

    async def _arun_impl(self, action: UpsertDashboardAction) -> tuple[str, dict | None]:
        if isinstance(action, CreateDashboardToolArgs):
            return await self._handle_create(action)
        if isinstance(action, UpdateDashboardToolArgs):
            return await self._handle_update(action)
        if isinstance(action, DuplicateDashboardToolArgs):
            return await self._handle_duplicate(action)
        return await self._handle_add_insights(action)

    async def _handle_create(self, action: CreateDashboardToolArgs) -> tuple[str, dict | None]:
        """Handle CREATE action: create a new dashboard with insights."""
        artifacts = await self._context_manager.artifacts.aget_visualizations(self._state.messages, action.insight_ids)

        missing_ids = [insight_id for insight_id, artifact in zip(action.insight_ids, artifacts) if artifact is None]
        if missing_ids:
            raise MaxToolRetryableError(format_prompt_string(MISSING_INSIGHT_IDS_PROMPT, missing_ids=missing_ids))

        validated_artifacts = cast(list[VisualizationWithSourceResult], artifacts)
        insights = self._resolve_insights(validated_artifacts)

        if not insights:
            return CREATE_NO_INSIGHTS_PROMPT, None

        dashboard = await self._create_dashboard_with_tiles(action.name, action.description, insights)
        # AI dashboards are always built from scratch (no template, no duplicate); set the same provenance
        # props the serializer create() path emits so `from_template`/`duplicated` filters include AI traffic.
        await self._report_dashboard_action(
            dashboard,
            "dashboard created",
            {
                "from_template": False,
                "template_key": None,
                "duplicated": False,
                "duplicated_from_dashboard_id": None,
            },
        )
        await self._report_new_insights(validated_artifacts, insights)
        output = await self._format_dashboard_output(dashboard, insights)

        return output, {"dashboard_id": dashboard.id}

    async def _handle_update(self, action: UpdateDashboardToolArgs) -> tuple[str, dict | None]:
        """Handle UPDATE action: update an existing dashboard."""
        dashboard = await self._get_dashboard(action.dashboard_id)
        has_changes = action.insight_ids or action.name is not None or action.description is not None
        if not has_changes:
            return UPDATE_NO_CHANGES_PROMPT, None

        insight_ids = action.insight_ids or []
        artifacts = await self._get_visualization_artifacts(insight_ids) if insight_ids else []

        try:
            dashboard, resolved_insights = await self._update_dashboard_with_tiles(
                dashboard,
                action.name,
                action.description,
                insight_ids,
                artifacts,
                action.layout_mode,
            )
        except ValidationError as error:
            raise MaxToolRetryableError(str(error.detail)) from error
        await self._report_dashboard_action(dashboard, "dashboard updated")

        if artifacts:
            await self._report_new_insights(cast(list[VisualizationWithSourceResult], artifacts), resolved_insights)

        # Re-fetch sorted tiles to get the latest state
        sorted_tiles = await self._get_dashboard_sorted_tiles(dashboard)
        insights = [tile.insight for tile in sorted_tiles if tile.insight is not None]

        output = await self._format_dashboard_output(dashboard, insights)

        return output, {"dashboard_id": dashboard.id}

    async def _handle_add_insights(self, action: AddDashboardInsightsToolArgs) -> tuple[str, dict | None]:
        """Add insights to an existing dashboard while preserving current tiles."""
        dashboard = await self._get_dashboard(action.dashboard_id)
        insight_ids = list(dict.fromkeys(action.insight_ids))
        artifacts = await self._get_visualization_artifacts(insight_ids)
        try:
            created_insights = await self._add_dashboard_insights(dashboard, insight_ids, artifacts)
        except ValidationError as error:
            raise MaxToolRetryableError(str(error.detail)) from error
        await self._report_dashboard_action(dashboard, "dashboard updated", {"operation": "add_insights"})
        for artifact, insight in created_insights:
            await self._report_new_insights([artifact], [insight])

        sorted_tiles = await self._get_dashboard_sorted_tiles(dashboard)
        insights = [tile.insight for tile in sorted_tiles if tile.insight is not None]
        output = await self._format_dashboard_output(dashboard, insights)

        return output, {"dashboard_id": dashboard.id}

    async def _handle_duplicate(self, action: DuplicateDashboardToolArgs) -> tuple[str, dict | None]:
        """Copy a dashboard as it is, so SQL variables and insight chart settings survive the copy."""
        source = await self._get_dashboard(action.dashboard_id, required_level="viewer")
        variables = await database_sync_to_async(self._resolve_duplicate_variables)(
            source.variables or {}, action.variable_values or {}
        )
        dashboard = await self._duplicate_dashboard(
            source,
            action.name,
            source.description if action.description is None else action.description,
            variables,
        )

        sorted_tiles = await self._get_dashboard_sorted_tiles(dashboard)
        insights = [tile.insight for tile in sorted_tiles if tile.insight is not None]
        output = await self._format_dashboard_output(dashboard, insights)

        return output, {"dashboard_id": dashboard.id}

    def _resolve_duplicate_variables(
        self, source_variables: dict[str, Any], variable_values: dict[str, Any]
    ) -> dict[str, Any]:
        variables = {key: dict(value) for key, value in source_variables.items() if isinstance(value, dict)}
        if not variable_values:
            return variables

        team_variables = {
            variable.code_name: variable for variable in insight_variables_for_team(self._team.id) if variable.code_name
        }
        unknown = [code_name for code_name in variable_values if code_name not in team_variables]
        if unknown:
            raise MaxToolRetryableError(
                format_prompt_string(
                    UNKNOWN_VARIABLES_PROMPT,
                    unknown_variables=", ".join(unknown),
                    available_variables=", ".join(sorted(team_variables)) or "none",
                )
            )

        for code_name, value in variable_values.items():
            variable_id = str(team_variables[code_name].id)
            variables[variable_id] = HogQLVariable(
                variableId=variable_id, code_name=code_name, value=value, isNull=value is None
            ).model_dump(exclude_none=True)
        return variables

    @database_sync_to_async
    @transaction.atomic
    def _duplicate_dashboard(
        self, source: Dashboard, name: str, description: str, variables: dict[str, Any]
    ) -> Dashboard:
        http_request = HttpRequest()
        http_request.method = "GET"
        request = Request(http_request)
        request.user = self._user
        request.auth = None
        cast(Any, request)._authenticator = None
        serializer = DashboardSerializer(
            data={
                "use_dashboard": source.id,
                "duplicate_tiles": True,
                "name": name,
                "description": description,
            },
            context={
                "request": request,
                "team_id": self._team.id,
                "get_team": lambda: self._team,
                "insight_variables": insight_variables_for_team(self._team.id),
                "creation_event_properties": {"source": EventSource.POSTHOG_AI},
            },
        )
        try:
            serializer.is_valid(raise_exception=True)
            dashboard = serializer.save()
        except PermissionDenied as error:
            raise MaxToolAccessDeniedError("insight", "viewer", action="read") from error
        except ValidationError as error:
            raise MaxToolRetryableError(str(error.detail)) from error
        dashboard.variables = variables
        dashboard.save(update_fields=["variables"])
        return dashboard

    def _resolve_insights(self, artifacts: list[VisualizationWithSourceResult]) -> list[Insight]:
        """
        Resolve insight_ids using VisualizationHandler.
        Returns (resolved_insights, missing_ids) in same order as input.

        For State/Artifact sources, creates and saves new Insights before adding to dashboard.
        """
        resolved: list[Insight] = []

        for result in artifacts:
            if isinstance(result, ModelArtifactResult):
                resolved.append(result.model)
            else:
                # State or Artifact source - need to create and save insight from artifact content
                content = result.content
                # Coerce query to the QuerySchema union
                coerced_query = QuerySchemaRoot.model_validate(content.query.model_dump(mode="json")).root
                if isinstance(coerced_query, DataVisualizationNode):
                    # SQL-backed insight: already a top-level query node, keep its display/chart settings as-is.
                    converted = coerced_query.model_dump(exclude_none=True)
                elif isinstance(coerced_query, HogQLQuery):
                    converted = DataTableNode(source=coerced_query).model_dump(exclude_none=True)
                else:
                    converted = InsightVizNode(source=coerced_query).model_dump(exclude_none=True)

                insight = Insight(
                    team=self._team,
                    created_by=self._user,
                    name=(content.name or "Untitled")[:400],
                    description=(content.description or "")[:400],
                    query=converted,
                    saved=True,
                )
                resolved.append(insight)

        return resolved

    async def _report_dashboard_action(
        self, dashboard: Dashboard, event: str, extra_properties: dict[str, Any] | None = None
    ) -> None:
        await database_sync_to_async(report_user_action)(
            self._user,
            event,
            {
                **await database_sync_to_async(dashboard.get_analytics_metadata)(),
                "source": EventSource.POSTHOG_AI,
                **(extra_properties or {}),
            },
            team=self._team,
        )

    async def _report_new_insights(
        self, artifacts: list[VisualizationWithSourceResult], insights: list[Insight]
    ) -> None:
        for artifact, insight in zip(artifacts, insights):
            if not isinstance(artifact, ModelArtifactResult):
                await database_sync_to_async(report_user_action)(
                    self._user,
                    "insight created",
                    {
                        "insight_id": insight.short_id,
                        **insight.get_analytics_query_kinds(),
                        **insight.get_analytics_query_metadata(),
                        "source": EventSource.POSTHOG_AI,
                    },
                    team=self._team,
                )

    def _create_resolved_insights(self, results: list[Insight]) -> list[Insight]:
        """
        Create insights that are not yet saved.
        """
        for insight in results:
            if getattr(insight, "pk", None):
                continue
            insight.save()
        return results

    @database_sync_to_async
    @transaction.atomic
    def _create_dashboard_with_tiles(self, name: str, description: str, insights: list[Insight]) -> Dashboard:
        """Create a new dashboard with tiles for the given insights."""
        dashboard = Dashboard.objects.create(
            name=name,
            description=description,
            team=self._team,
            created_by=self._user,
        )
        insights = self._create_resolved_insights(insights)
        DashboardTile.objects.bulk_create(
            [
                DashboardTile(dashboard=dashboard, team_id=dashboard.team_id, insight=insight, layouts={})
                for insight in insights
            ]
        )
        return dashboard

    @database_sync_to_async
    @transaction.atomic
    def _add_dashboard_insights(
        self, dashboard: Dashboard, insight_ids: list[str], artifacts: list[VisualizationWithSourceResult]
    ) -> list[tuple[VisualizationWithSourceResult, Insight]]:
        """Add or restore insight tiles without changing any other dashboard tiles."""
        created_insights: list[tuple[VisualizationWithSourceResult, Insight]] = []
        for artifact_id, artifact, insight in zip(insight_ids, artifacts, self._resolve_insights(artifacts)):
            if not isinstance(artifact, ModelArtifactResult):
                # Stable IDs let the database deduplicate artifact retries, including concurrent calls.
                identity = f"dashboard:{dashboard.id}:{artifact.source.value}:{artifact_id}"
                short_id = urlsafe_b64encode(hashlib.sha256(identity.encode()).digest()[:9]).decode()
                insight_pk, created = get_or_create_saved_insight(
                    team_id=self._team.id,
                    user_id=self._user.id,
                    short_id=short_id,
                    name=insight.name,
                    description=insight.description,
                    query=insight.query,
                )
                insight = insights_including_soft_deleted_for_team(team_id=self._team.id, insight_ids=[insight_pk])[0]
                if created:
                    created_insights.append((artifact, insight))

            check_can_add_insight_to_dashboard(self._user, dashboard, insight.query, self.user_access_control)

            tile, created = DashboardTile.objects_including_soft_deleted.get_or_create(
                dashboard=dashboard,
                insight=insight,
                defaults={"team_id": dashboard.team_id, "layouts": {}},
            )
            if not created and tile.deleted:
                tile.deleted = False
                tile.save(update_fields=["deleted"])

        return created_insights

    @database_sync_to_async
    @transaction.atomic
    def _update_dashboard_with_tiles(
        self,
        dashboard: Dashboard,
        name: str | None,
        description: str | None,
        insight_ids: list[str],
        artifacts: list[VisualizationWithSourceResult],
        layout_mode: Literal["preserve_existing", "reflow_all"],
    ) -> tuple[Dashboard, list[Insight]]:
        """Update dashboard tiles based on provided insight IDs.

        Args:
            dashboard: The dashboard to update
            name: New dashboard name (if provided)
            description: New dashboard description (if provided)
            insight_ids: Ordered list of insight IDs for the dashboard
            artifacts: Resolved visualization artifacts matching insight_ids order
            layout_mode: Layout strategy for existing tiles

        Returns:
            Tuple of (dashboard, resolved_insights) where resolved_insights
            corresponds 1:1 with artifacts in the same order.
        """
        if name is not None:
            dashboard.name = name
        if description is not None:
            dashboard.description = description
        if name is not None or description is not None:
            dashboard.save(update_fields=["name", "description"])

        if not insight_ids:
            return dashboard, []

        # 1. Get all existing tiles including soft deleted
        all_tiles = list(
            DashboardTile.objects_including_soft_deleted.filter(dashboard=dashboard).select_related("insight")
        )

        # Build lookup: short_id -> tile (for matching by artifact ID)
        short_id_to_tile: dict[str, DashboardTile] = {}
        for tile in all_tiles:
            if tile.insight and tile.insight.short_id:
                short_id_to_tile[tile.insight.short_id] = tile

        # Resolve artifacts to insights
        resolved_insights = self._create_resolved_insights(self._resolve_insights(artifacts))

        # Track tiles that will be active after update
        active_tile_ids: set[int] = set()
        tiles_to_update: list[DashboardTile] = []
        restored_tile_ids: list[int] = []

        # 2. Create new tiles or restore soft deleted
        for insight_id, insight in zip(insight_ids, resolved_insights):
            existing_tile = short_id_to_tile.get(insight_id)
            becomes_live = existing_tile is None or existing_tile.deleted
            if becomes_live:
                check_can_add_insight_to_dashboard(self._user, dashboard, insight.query, self.user_access_control)

            if existing_tile:
                # Restore if soft deleted
                if existing_tile.deleted:
                    existing_tile.deleted = False
                    restored_tile_ids.append(existing_tile.id)
                active_tile_ids.add(existing_tile.id)
                tiles_to_update.append(existing_tile)
            else:
                # Create new tile
                new_tile = DashboardTile.objects.create(
                    dashboard=dashboard,
                    team_id=dashboard.team_id,
                    insight=insight,
                    layouts={},
                )
                active_tile_ids.add(new_tile.id)
                tiles_to_update.append(new_tile)

        # 3. Soft delete insight tiles not in the new list (preserve text tiles)
        tiles_to_delete = [
            t.id for t in all_tiles if t.id not in active_tile_ids and not t.deleted and t.insight_id is not None
        ]
        if tiles_to_delete:
            # nosemgrep: idor-lookup-without-team
            DashboardTile.objects.filter(id__in=tiles_to_delete).update(deleted=True)

        if layout_mode == "preserve_existing":
            if restored_tile_ids:
                DashboardTile.objects_including_soft_deleted.filter(id__in=restored_tile_ids).update(deleted=False)
            return dashboard, resolved_insights

        fixed_non_insight_vertical_spans: list[tuple[int, int]] = []
        for tile in all_tiles:
            if tile.deleted or tile.insight_id is not None:
                continue
            sm_layout = (tile.layouts or {}).get("sm", {})
            raw_y = sm_layout.get("y")
            raw_h = sm_layout.get("h")
            if not isinstance(raw_y, int | float) or not isinstance(raw_h, int | float):
                continue
            y_start = int(raw_y)
            height = int(raw_h)
            if y_start < 0 or height <= 0:
                continue
            fixed_non_insight_vertical_spans.append((y_start, y_start + height))

        # 4. Reflow insight tile layouts when requested.
        layout_updates = self._compute_reflow_layout_updates(tiles_to_update, fixed_non_insight_vertical_spans)
        for layout_update in layout_updates:
            row_tile = layout_update["tile"]
            row_tile.layouts = layout_update["layouts"]
            row_tile.save(update_fields=["layouts", "deleted"])

        return dashboard, resolved_insights

    @staticmethod
    def _compute_reflow_layout_updates(
        tiles_to_update: list[DashboardTile], fixed_non_insight_vertical_spans: list[tuple[int, int]]
    ) -> list[ReflowTileLayoutUpdate]:
        # Reflow is intentionally row-based and simple:
        # - preserve tile order
        # - normalize row heights
        # - fill row gaps using equal widths
        # - allow local adaptation for inserted middle tiles
        # - avoid vertical overlap with fixed non-insight tiles (e.g. text)
        column_count = 12
        xs_y = 0  # For xs breakpoint (single column)
        rows: list[list[ReflowRowItem]] = []
        current_row: list[ReflowRowItem] = []
        current_row_width = 0

        for tile in tiles_to_update:
            sm_layout = (tile.layouts or {}).get("sm", {})

            # Use original sizes as the baseline, falling back to defaults.
            raw_h = sm_layout.get("h")
            raw_w = sm_layout.get("w")

            h = int(raw_h) if isinstance(raw_h, int | float) and raw_h > 0 else 5
            w = int(raw_w) if isinstance(raw_w, int | float) and raw_w > 0 else 6
            w = min(w, column_count)

            if current_row and current_row_width + w > column_count:
                # Generic local adaptation for insert/reorder:
                # If the row starts with a small tile, we can keep an overflowing
                # tile in this row only when equal-splitting still respects the
                # smallest baseline tile width in the proposed row.
                proposed_row_widths = [int(item["w"]) for item in current_row] + [w]
                proposed_tile_count = len(proposed_row_widths)
                proposed_equalized_base_width = column_count // proposed_tile_count
                smallest_baseline_width = min(proposed_row_widths)
                row_is_already_full = current_row_width >= column_count
                can_adapt_overflow_in_row = (
                    current_row[0]["w"] <= column_count // 2
                    and w < column_count
                    and proposed_equalized_base_width >= smallest_baseline_width
                    and not (row_is_already_full and len(current_row) >= 3)
                )
                has_single_full_width_tile = len(current_row) == 1 and current_row[0]["w"] == column_count

                if not has_single_full_width_tile and can_adapt_overflow_in_row:
                    # Keep this tile in the same row; widths will be equalized later.
                    current_row.append({"tile": tile, "h": h, "w": w})
                    current_row_width += w
                    continue

                rows.append(current_row)
                current_row = []
                current_row_width = 0

            current_row.append({"tile": tile, "h": h, "w": w})
            current_row_width += w

        if current_row:
            rows.append(current_row)

        def _find_next_row_y(candidate_y: int, row_height: int) -> int:
            """Push a row down until it no longer overlaps fixed non-insight tiles."""
            y_position = candidate_y
            while True:
                conflicting_bottom: int | None = None
                row_bottom = y_position + row_height
                for span_start, span_end in fixed_non_insight_vertical_spans:
                    if y_position < span_end and row_bottom > span_start:
                        conflicting_bottom = (
                            span_end if conflicting_bottom is None else max(conflicting_bottom, span_end)
                        )
                if conflicting_bottom is None:
                    return y_position
                y_position = conflicting_bottom

        y = 0
        layout_updates: list[ReflowTileLayoutUpdate] = []
        for row in rows:
            row_height = max(item["h"] for item in row)
            row_width = sum(item["w"] for item in row)
            has_single_full_width_tile = len(row) == 1 and row[0]["w"] == column_count
            y = _find_next_row_y(y, row_height)

            target_widths: list[int]
            if has_single_full_width_tile:
                target_widths = [row[0]["w"]]
            elif row_width != column_count:
                tile_count = len(row)
                base_width = column_count // tile_count
                remainder = column_count % tile_count
                target_widths = [base_width + (1 if index < remainder else 0) for index in range(tile_count)]
            else:
                target_widths = [item["w"] for item in row]

            x = 0

            for item, target_width in zip(row, target_widths):
                row_tile = item["tile"]
                h = item["h"] if has_single_full_width_tile else row_height
                w = target_width
                raw_xs_h = ((row_tile.layouts or {}).get("xs") or {}).get("h")
                # Keep existing mobile height for existing tiles; default only for new/invalid layouts.
                xs_h = int(raw_xs_h) if isinstance(raw_xs_h, int | float) and raw_xs_h > 0 else 5
                layouts = {
                    "sm": {"h": h, "w": w, "x": x, "y": y, "minH": 1, "minW": 1},
                    "xs": {"h": xs_h, "w": 1, "x": 0, "y": xs_y, "minH": 1, "minW": 1},
                }
                layout_updates.append({"tile": row_tile, "layouts": layouts})
                x += w
                xs_y += xs_h
            y += row_height

        return layout_updates

    async def _format_dashboard_output(
        self,
        dashboard: Dashboard,
        insights: list[Insight],
    ) -> str:
        """Format dashboard output using DashboardContext for consistency."""
        insights_data: list[DashboardInsightContext] = []
        for insight in insights:
            query_obj = InsightContext.extract_query(insight)
            if query_obj is None:
                continue
            insights_data.append(
                DashboardInsightContext(
                    query=query_obj,
                    name=insight.name or insight.derived_name,
                    description=insight.description,
                    short_id=insight.short_id,
                    db_id=insight.id,
                )
            )

        context = DashboardContext(
            team=self._team,
            insights_data=insights_data,
            user=self._user,
            name=dashboard.name,
            description=dashboard.description,
            dashboard_id=str(dashboard.id),
        )

        return await context.format_schema()

    async def _get_dashboard(
        self, dashboard_id: Any, required_level: Literal["viewer", "editor"] = "editor"
    ) -> Dashboard:
        """Get the dashboard and sorted tiles for the given dashboard ID."""
        # LLMs sometimes output IDs as floats (e.g., "642161.0"), so we parse to int
        try:
            parsed_id = int(float(dashboard_id))
        except (ValueError, TypeError):
            raise MaxToolFatalError(DASHBOARD_NOT_FOUND_PROMPT.format(dashboard_id=dashboard_id))
        try:
            dashboard = await Dashboard.objects.aget(id=parsed_id, team=self._team, deleted=False)
        except Dashboard.DoesNotExist:
            raise MaxToolFatalError(DASHBOARD_NOT_FOUND_PROMPT.format(dashboard_id=dashboard_id))

        await self.check_object_access(
            dashboard, required_level, action="edit" if required_level == "editor" else "read"
        )

        return dashboard

    async def _get_dashboard_sorted_tiles(self, dashboard: Dashboard) -> list[DashboardTile]:
        """
        Get the sorted tiles for the given dashboard.
        """
        sorted_tiles = DashboardTile.sort_tiles_by_layout(
            [tile async for tile in DashboardTile.objects.filter(dashboard=dashboard).select_related("insight")]
        )
        return sorted_tiles

    async def _get_update_diff(self, dashboard_tiles: list[DashboardTile], insight_ids: list[str]) -> UpdateDiff:
        """
        Get the update diff for the given dashboard tiles and insight IDs. Returns a list of deleted tiles, created insights, and replaced tiles with their corresponding visualization artifacts.
        """
        if self._cached_update_diff is not None:
            return self._cached_update_diff

        if not insight_ids:
            return UpdateDiff(
                deleted=[],
                created=[],
            )

        existing_ids = {tile.insight.short_id for tile in dashboard_tiles if tile.insight is not None}
        new_ids = set(insight_ids)
        deleted_ids = list(existing_ids - new_ids)
        created_ids = list(new_ids - existing_ids)

        self._cached_update_diff = UpdateDiff(
            deleted=[
                tile for tile in dashboard_tiles if tile.insight is not None and tile.insight.short_id in deleted_ids
            ],
            created=await self._get_visualization_artifacts(created_ids),
        )

        return self._cached_update_diff

    async def _get_visualization_artifacts(self, insight_ids: list[str]) -> list[VisualizationWithSourceResult]:
        """
        Fetch and validate visualization artifacts for the given insight IDs.
        """
        artifacts = await self._context_manager.artifacts.aget_visualizations(self._state.messages, insight_ids)
        not_found = [insight_id for insight_id, artifact in zip(insight_ids, artifacts) if artifact is None]
        if not_found:
            raise MaxToolRetryableError(format_prompt_string(MISSING_INSIGHT_IDS_PROMPT, missing_ids=not_found))
        return cast(list[VisualizationWithSourceResult], artifacts)