: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
feat(insights): classify what caused each moment on a chart with Jeeves (#125481)
Sam Pennington47d1f40e9ed6
diff --git a/posthog/rate_limit.py b/posthog/rate_limit.pyindex de99e63ff5ba..21a38b0416bc 100644--- a/posthog/rate_limit.py+++ b/posthog/rate_limit.py@@ -992,6 +992,17 @@ class AIObservabilitySummarizationDailyThrottle(PersonalApiKeyOrUserRateThrottlerate = "500/day"+class InsightExplainBurstThrottle(PersonalApiKeyOrUserRateThrottle):+ # A decision model call costs a small fraction of a summarization call, so it gets its own, higher limits.+ scope = "insight_explain_burst"+ rate = "120/minute"+++class InsightExplainDailyThrottle(PersonalApiKeyOrUserRateThrottle):+ scope = "insight_explain_daily"+ rate = "5000/day"++class AIObservabilityBackfillEstimateThrottle(_UserBucketRateThrottle):"""`estimate` runs a synchronous ClickHouse count, so a caller could otherwise saturate thequery pool by resubmitting wide windows. Its own bucket keeps the call the UI makes on everydiff --git a/products/product_analytics/backend/presentation/insight.py b/products/product_analytics/backend/presentation/insight.pyindex bea1258dfb85..d6c1a66d043f 100644--- a/products/product_analytics/backend/presentation/insight.py+++ b/products/product_analytics/backend/presentation/insight.py@@ -87,6 +87,7 @@ from posthog.hogql_queries.query_runner import ExecutionMode, enforce_api_queriefrom posthog.hogql_queries.refresh_policy import ComputeSurface, resolve_execution_modefrom posthog.hogql_queries.utils.result_series import get_response_action_namesfrom posthog.kafka_client.topics import KAFKA_METRICS_TIME_TO_SEE_DATA+from posthog.llm.system_one import SystemOneNotConfigured, SystemOneRequestFailedfrom posthog.models import Userfrom posthog.models.activity_logging.activity_log import (Change,@@ -121,6 +122,8 @@ from posthog.rate_limit import (AIObservabilitySummarizationSustainedThrottle,ClickHouseBurstRateThrottle,ClickHouseSustainedRateThrottle,+ InsightExplainBurstThrottle,+ InsightExplainDailyThrottle,)from posthog.renderers import SafeJSONRendererfrom posthog.resource_limits import LimitKey, check_count_limit@@ -196,6 +199,7 @@ from products.product_analytics.backend.facade.enums import (InsightDataChecksStatus,)from products.product_analytics.backend.facade.models import Insight, resolve_insight_by_id_or_short_id+from products.product_analytics.backend.presentation.insight_explain import ChartCause, ExplainFacts, explain_chartfrom products.product_analytics.backend.presentation.insight_metadata import (InsightMetadataTimeoutError,generate_insight_metadata,@@ -1648,6 +1652,84 @@ class InsightViewedRequestSerializer(serializers.Serializer):)+INSIGHT_EXPLAIN_MAX_CHAPTERS = 8+INSIGHT_EXPLAIN_MAX_FINDINGS = 6+++class InsightExplainChapterFactsSerializer(serializers.Serializer):+ id = serializers.CharField(+ max_length=64, help_text="Identifier of the chapter. The response returns the chapter under the same one."+ )+ title = serializers.CharField(+ max_length=200, help_text="What the chapter is about, for example 'A peak on October 2'."+ )+ summary = serializers.CharField(+ max_length=600,+ help_text="The computed facts of the chapter in one or two sentences, with their numbers and dates.",+ )+ evidence = serializers.ListField(+ child=serializers.CharField(max_length=600),+ required=False,+ default=list,+ max_length=INSIGHT_EXPLAIN_MAX_FINDINGS,+ help_text=(+ "Findings about the cause of the chapter, one sentence each. "+ f"Empty when nothing was found. At most {INSIGHT_EXPLAIN_MAX_FINDINGS}."+ ),+ )+++class InsightExplainRequestSerializer(serializers.Serializer):+ series_label = serializers.CharField(max_length=200, help_text="Name of the series that the explanation follows.")+ insight_name = serializers.CharField(+ max_length=400,+ required=False,+ allow_blank=True,+ default="",+ help_text="Name of the insight. Blank for an insight that has no name yet.",+ )+ overview = serializers.CharField(+ max_length=600,+ required=False,+ allow_blank=True,+ default="",+ help_text="The computed facts of the whole chart, such as its typical level, its range and how it ends.",+ )+ chapters = serializers.ListField(+ child=InsightExplainChapterFactsSerializer(),+ max_length=INSIGHT_EXPLAIN_MAX_CHAPTERS,+ help_text=(+ f"The chapters of the explanation in reading order. At most {INSIGHT_EXPLAIN_MAX_CHAPTERS}. "+ "Empty when nothing stands out on the chart."+ ),+ )+++class InsightExplainChapterSerializer(serializers.Serializer):+ id = serializers.CharField(help_text="Identifier of the chapter, as it was sent.")+ cause = serializers.ChoiceField(+ choices=ChartCause.choices,+ help_text=(+ "What most likely caused the chapter: outside traffic, a real change in usage, one person or a test "+ "account, a tracking change, the usual weekly pattern, or unclear when no cause fits the facts."+ ),+ )+ confidence = serializers.FloatField(help_text="How sure the model is of the cause, from 0 to 1.")+++class InsightExplainUnavailable(APIException):+ status_code = status.HTTP_503_SERVICE_UNAVAILABLE+ default_detail = "The decision model is not available right now. Try again in a moment."+ default_code = "insight_explain_unavailable"+++class InsightExplainSerializer(serializers.Serializer):+ chapters = InsightExplainChapterSerializer(+ many=True,+ help_text="The likely cause of each chapter the model answered, in the order they were sent.",+ )++INSIGHT_BULK_DELETE_MAX_IDS = 1000@@ -2111,13 +2193,15 @@ class InsightViewSet(parser_classes = (QuerySchemaParser,)def get_throttles(self):- """Apply LLM-specific throttles to the AI metadata endpoint."""+ """Apply LLM-specific throttles to the endpoints that call a model."""if self.action == "generate_metadata":return [AIObservabilitySummarizationBurstThrottle(),AIObservabilitySummarizationSustainedThrottle(),AIObservabilitySummarizationDailyThrottle(),]+ if self.action == "explain":+ return [InsightExplainBurstThrottle(), InsightExplainDailyThrottle()]return super().get_throttles()def _validate_ai_feature_access(self) -> None:@@ -2630,6 +2714,36 @@ When set, the specified dashboard's filters and date range override will be applreturn Response({"name": metadata.name, "description": metadata.description})+ @validated_request(+ request_serializer=InsightExplainRequestSerializer,+ responses={+ 200: OpenApiResponse(response=InsightExplainSerializer, description="The explanation of the chart."),+ 503: OpenApiResponse(description="The decision model failed or timed out."),+ },+ description=(+ "Classify what most likely caused each moment on a chart. The caller sends chapters of facts that it "+ "computed from the chart's data, and gets back one cause from a fixed list for each chapter, with a "+ "confidence. The numbers stay with the caller: this endpoint runs no query and reads no insight. "+ "Without a decision model on the instance, the list is empty. "+ "The organization must approve AI data processing."+ ),+ )+ @action(methods=["POST"], detail=False, required_scopes=["insight:read"])+ def explain(self, request: ValidatedRequest, **kwargs: Any) -> Response:+ self._validate_ai_feature_access()++ try:+ causes = explain_chart(ExplainFacts.model_validate(request.validated_data), team_id=self.team.pk)+ except SystemOneNotConfigured:+ causes = []+ except SystemOneRequestFailed as error:+ # The page shows its own text without the causes, so a slow or failed model is a "not now", not an error.+ logger.warning("insight_explain_unavailable", team_id=self.team.pk, reason=type(error).__name__)+ raise InsightExplainUnavailable() from error++ chapters = [{"id": c.id, "cause": c.cause.value, "confidence": c.confidence} for c in causes]+ return Response(InsightExplainSerializer({"chapters": chapters}).data)+# ******************************************# /projects/:id/insights/viewed# Creates or updates InsightViewed objects for the user/insight combo(s)diff --git a/products/product_analytics/backend/presentation/insight_explain.py b/products/product_analytics/backend/presentation/insight_explain.pynew file mode 100644index 000000000000..20e7319b172e--- /dev/null+++ b/products/product_analytics/backend/presentation/insight_explain.py@@ -0,0 +1,117 @@+"""Asks the decision model which cause from a fixed list fits each moment on a chart."""++from django.db import models++import structlog+from pydantic import BaseModel++from posthog.dataclasses import frozen+from posthog.llm.managed_decision_model import DEFAULT_DECISION_MODEL+from posthog.llm.system_one import ChoiceAnswer, ChoiceQuestion, JsonValue+from posthog.llm.system_one_client import build_system_one_client++logger = structlog.get_logger(__name__)++EXPLAIN_AI_PRODUCT = "insight_explain"+# The explanation already shows its facts while it waits, so a slow answer only delays the likely causes.+EXPLAIN_TIMEOUT_SECONDS = 10.0+++class ChartCause(models.TextChoices):+ OUTSIDE_TRAFFIC = "outside_traffic", "Outside traffic"+ USAGE = "usage", "Usage"+ ONE_PERSON = "one_person", "One person"+ TRACKING = "tracking", "Tracking"+ WEEKLY_PATTERN = "weekly_pattern", "Weekly pattern"+ UNCLEAR = "unclear", "Unclear"+++CAUSE_CRITERIA: dict[str, str] = {+ ChartCause.OUTSIDE_TRAFFIC: (+ "More or fewer people arrived from outside the product, for example from a launch, a post, an email, "+ "an ad or a search engine."+ ),+ ChartCause.USAGE: (+ "A real change in how people use the product, for example a new feature, a release, a changed flow, "+ "or people coming back more or less often."+ ),+ ChartCause.ONE_PERSON: "One person, a bot, a script or a test account caused most of the change.",+ ChartCause.TRACKING: (+ "A change in how the data is collected or processed, not in what people do: tracking added, removed or "+ "broken, an event renamed or sent twice, an SDK upgrade, ad blockers or consent, a changed filter or "+ "definition, or data arriving late."+ ),+ ChartCause.WEEKLY_PATTERN: "The usual weekly or seasonal rhythm, such as quieter weekends or holidays.",+ ChartCause.UNCLEAR: (+ "None of the other causes fits the facts, or the facts are not enough to tell. For example a feature "+ "flag, an experiment, an incident or a release that the facts do not mention."+ ),+}+++class ExplainChapterFacts(BaseModel):+ id: str+ title: str+ summary: str+ evidence: list[str]+++class ExplainFacts(BaseModel):+ series_label: str+ insight_name: str+ overview: str = ""+ chapters: list[ExplainChapterFacts]+++@frozen+class ChapterCause:+ id: str+ cause: ChartCause+ confidence: float+++def _chapter_key(index: int) -> str:+ return f"chapter_{index + 1}"+++def _state(facts: ExplainFacts) -> JsonValue:+ return {+ "chart": {"series": facts.series_label, "insight": facts.insight_name, "overview": facts.overview},+ "chapters": {+ _chapter_key(index): {"title": chapter.title, "summary": chapter.summary, "evidence": chapter.evidence}+ for index, chapter in enumerate(facts.chapters)+ },+ }+++def _question(key: str) -> ChoiceQuestion:+ # The chapter is named by its key in the state, so no text from the chart reaches the instructions.+ return ChoiceQuestion(+ instructions=(+ f"The state holds facts computed from a chart of product data. What most likely caused {key} in "+ "chapters? Read its title, its summary and its evidence, and the chart overview."+ ),+ criteria=CAUSE_CRITERIA,+ )+++def explain_chart(facts: ExplainFacts, *, team_id: int) -> list[ChapterCause]:+ """The likely cause of each chapter that the model answered. Raises the System One errors."""+ if not facts.chapters:+ return []+ keys = [_chapter_key(index) for index in range(len(facts.chapters))]+ client = build_system_one_client(+ model=DEFAULT_DECISION_MODEL,+ ai_product=EXPLAIN_AI_PRODUCT,+ team_id=team_id,+ timeout=EXPLAIN_TIMEOUT_SECONDS,+ )+ result = client.decide(state=_state(facts), questions={key: _question(key) for key in keys})+ causes: list[ChapterCause] = []+ for key, chapter in zip(keys, facts.chapters):+ answer = result.answers.get(key)+ if not isinstance(answer, ChoiceAnswer) or answer.choice not in CAUSE_CRITERIA:+ logger.info("insight_explain_unanswered", team_id=team_id, chapter=key, reason=type(answer).__name__)+ continue+ causes.append(ChapterCause(id=chapter.id, cause=ChartCause(answer.choice), confidence=answer.confidence))+ return causesdiff --git a/products/product_analytics/backend/tests/api/test_insight_explain.py b/products/product_analytics/backend/tests/api/test_insight_explain.pynew file mode 100644index 000000000000..3a9f68d5f0f6--- /dev/null+++ b/products/product_analytics/backend/tests/api/test_insight_explain.py@@ -0,0 +1,97 @@+from posthog.test.base import APIBaseTest+from unittest.mock import MagicMock, patch++from parameterized import parameterized+from rest_framework import status++from posthog.llm.system_one import (+ ChoiceAnswer,+ RefusalAnswer,+ SystemOneNotConfigured,+ SystemOneRequestFailed,+ SystemOneResult,+)++CLIENT_PATH = "products.product_analytics.backend.presentation.insight_explain.build_system_one_client"++FACTS = {+ "series_label": "Sign-ups",+ "insight_name": "Sign-ups",+ "overview": "A typical day is 50.",+ "chapters": [+ {"id": "peak-14", "title": "A peak on October 2", "summary": "498 on October 2.", "evidence": ["x"]},+ {"id": "dip-3", "title": "A dip on September 24", "summary": "4 on September 24.", "evidence": []},+ ],+}+++def _client_answering(answers: dict) -> MagicMock:+ client = MagicMock()+ client.decide.return_value = SystemOneResult(model="jeeves", answers=answers, input_tokens=None)+ return client+++def _patch_client(outcome: dict | Exception):+ if isinstance(outcome, SystemOneNotConfigured):+ return patch(CLIENT_PATH, side_effect=outcome)+ if isinstance(outcome, Exception):+ return patch(CLIENT_PATH, return_value=MagicMock(decide=MagicMock(side_effect=outcome)))+ return patch(CLIENT_PATH, return_value=_client_answering(outcome))+++class TestInsightExplain(APIBaseTest):+ def setUp(self):+ super().setUp()+ self.organization.is_ai_data_processing_approved = True+ self.organization.save()+ self.url = f"/api/projects/{self.team.id}/insights/explain/"++ @parameterized.expand(+ [+ (+ "answers_map_to_the_chapters_sent",+ {+ "chapter_1": ChoiceAnswer(choice="outside_traffic", confidence=0.9, probabilities={}),+ "chapter_2": ChoiceAnswer(choice="unclear", confidence=0.7, probabilities={}),+ },+ status.HTTP_200_OK,+ [("peak-14", "outside_traffic"), ("dip-3", "unclear")],+ ),+ (+ "refused_and_unknown_answers_are_dropped",+ {+ "chapter_1": RefusalAnswer(),+ "chapter_2": ChoiceAnswer(choice="aliens", confidence=0.9, probabilities={}),+ },+ status.HTTP_200_OK,+ [],+ ),+ ("no_decision_model_on_the_instance", SystemOneNotConfigured(), status.HTTP_200_OK, []),+ ("decision_model_failed", SystemOneRequestFailed("down"), status.HTTP_503_SERVICE_UNAVAILABLE, None),+ ]+ )+ def test_explain_returns_a_cause_per_answered_chapter(self, _name, outcome, expected_status, expected_causes):+ with _patch_client(outcome):+ response = self.client.post(self.url, FACTS, format="json")++ assert response.status_code == expected_status+ if expected_causes is not None:+ assert [(c["id"], c["cause"]) for c in response.json()["chapters"]] == expected_causes++ def test_a_chart_where_nothing_stands_out_asks_the_model_nothing(self):+ with patch(CLIENT_PATH) as build_client:+ response = self.client.post(self.url, {**FACTS, "chapters": []}, format="json")++ assert response.status_code == status.HTTP_200_OK+ assert response.json() == {"chapters": []}+ build_client.assert_not_called()++ def test_an_organization_without_ai_approval_sends_nothing_to_the_model(self):+ self.organization.is_ai_data_processing_approved = False+ self.organization.save()++ with patch(CLIENT_PATH) as build_client:+ response = self.client.post(self.url, FACTS, format="json")++ assert response.status_code == status.HTTP_403_FORBIDDEN+ build_client.assert_not_called()diff --git a/products/product_analytics/frontend/generated/api.schemas.ts b/products/product_analytics/frontend/generated/api.schemas.tsindex baa9e757933d..9e15239beb77 100644--- a/products/product_analytics/frontend/generated/api.schemas.ts+++ b/products/product_analytics/frontend/generated/api.schemas.ts@@ -9691,6 +9691,93 @@ export interface InsightDataChecksRequestApi {depth?: InsightDataChecksDepthEnumApi}+export interface InsightExplainChapterFactsApi {+ /**+ * Identifier of the chapter. The response returns the chapter under the same one.+ * @maxLength 64+ */+ id: string+ /**+ * What the chapter is about, for example 'A peak on October 2'.+ * @maxLength 200+ */+ title: string+ /**+ * The computed facts of the chapter in one or two sentences, with their numbers and dates.+ * @maxLength 600+ */+ summary: string+ /**+ * Findings about the cause of the chapter, one sentence each. Empty when nothing was found. At most 6.+ * @maxItems 6+ * @items.maxLength 600+ */+ evidence?: string[]+}++export interface InsightExplainRequestApi {+ /**+ * Name of the series that the explanation follows.+ * @maxLength 200+ */+ series_label: string+ /**+ * Name of the insight. Blank for an insight that has no name yet.+ * @maxLength 400+ */+ insight_name?: string+ /**+ * The computed facts of the whole chart, such as its typical level, its range and how it ends.+ * @maxLength 600+ */+ overview?: string+ /**+ * The chapters of the explanation in reading order. At most 8. Empty when nothing stands out on the chart.+ * @maxItems 8+ */+ chapters: InsightExplainChapterFactsApi[]+}++/**+ * * `outside_traffic` - Outside traffic+ * * `usage` - Usage+ * * `one_person` - One person+ * * `tracking` - Tracking+ * * `weekly_pattern` - Weekly pattern+ * * `unclear` - Unclear+ */+export type ChartCauseEnumApi = (typeof ChartCauseEnumApi)[keyof typeof ChartCauseEnumApi]++export const ChartCauseEnumApi = {+ OutsideTraffic: 'outside_traffic',+ Usage: 'usage',+ OnePerson: 'one_person',+ Tracking: 'tracking',+ WeeklyPattern: 'weekly_pattern',+ Unclear: 'unclear',+} as const++export interface InsightExplainChapterApi {+ /** Identifier of the chapter, as it was sent. */+ id: string+ /** What most likely caused the chapter: outside traffic, a real change in usage, one person or a test account, a tracking change, the usual weekly pattern, or unclear when no cause fits the facts.+ *+ * * `outside_traffic` - Outside traffic+ * * `usage` - Usage+ * * `one_person` - One person+ * * `tracking` - Tracking+ * * `weekly_pattern` - Weekly pattern+ * * `unclear` - Unclear */+ cause: ChartCauseEnumApi+ /** How sure the model is of the cause, from 0 to 1. */+ confidence: number+}++export interface InsightExplainApi {+ /** The likely cause of each chapter the model answered, in the order they were sent. */+ chapters: InsightExplainChapterApi[]+}+/*** Insight enriched with view-count and recent-viewer fields, used by the trending action.*/@@ -10242,6 +10329,17 @@ export const InsightsDataChecksCreateFormat = {Json: 'json',} as const+export type InsightsExplainCreateParams = {+ format?: InsightsExplainCreateFormat+}++export type InsightsExplainCreateFormat = (typeof InsightsExplainCreateFormat)[keyof typeof InsightsExplainCreateFormat]++export const InsightsExplainCreateFormat = {+ Csv: 'csv',+ Json: 'json',+} as const+export type InsightsGenerateMetadataCreateParams = {format?: InsightsGenerateMetadataCreateFormat}diff --git a/products/product_analytics/frontend/generated/api.ts b/products/product_analytics/frontend/generated/api.tsindex 4c5ef0be3fec..067fbdb5af58 100644--- a/products/product_analytics/frontend/generated/api.ts+++ b/products/product_analytics/frontend/generated/api.ts@@ -30,6 +30,8 @@ import type {InsightBulkSetTestAccountFilterResponseApi,InsightDataChecksApi,InsightDataChecksRequestApi,+ InsightExplainApi,+ InsightExplainRequestApi,InsightViewedRequestApi,InsightsActivityRetrieveParams,InsightsAllActivityRetrieveParams,@@ -42,6 +44,7 @@ import type {InsightsDataChecksCreateParams,InsightsDataChecksRetrieveParams,InsightsDestroyParams,+ InsightsExplainCreateParams,InsightsGenerateMetadataCreateParams,InsightsListParams,InsightsMyLastViewedRetrieveParams,@@ -927,6 +930,39 @@ export const insightsDataChecksCreate = async (})}+export const getInsightsExplainCreateUrl = (projectId: string, params?: InsightsExplainCreateParams) => {+ const normalizedParams = new URLSearchParams()++ Object.entries(params || {}).forEach(([key, value]) => {+ if (value !== undefined) {+ normalizedParams.append(key, value === null ? 'null' : String(value))+ }+ })++ const stringifiedParams = normalizedParams.toString()++ return stringifiedParams.length > 0+ ? `/api/projects/${projectId}/insights/explain/?${stringifiedParams}`+ : `/api/projects/${projectId}/insights/explain/`+}++/**+ * Classify what most likely caused each moment on a chart. The caller sends chapters of facts that it computed from the chart's data, and gets back one cause from a fixed list for each chapter, with a confidence. The numbers stay with the caller: this endpoint runs no query and reads no insight. Without a decision model on the instance, the list is empty. The organization must approve AI data processing.+ */+export const insightsExplainCreate = async (+ projectId: string,+ insightExplainRequestApi: InsightExplainRequestApi,+ params?: InsightsExplainCreateParams,+ options?: RequestInit+): Promise<InsightExplainApi> => {+ return apiMutator<InsightExplainApi>(getInsightsExplainCreateUrl(projectId, params), {+ ...options,+ method: 'POST',+ headers: { 'Content-Type': 'application/json', ...options?.headers },+ body: JSON.stringify(insightExplainRequestApi),+ })+}+export const getInsightsGenerateMetadataCreateUrl = (projectId: string,params?: InsightsGenerateMetadataCreateParamsdiff --git a/products/product_analytics/frontend/generated/api.zod.ts b/products/product_analytics/frontend/generated/api.zod.tsindex c8e1417efcd7..dfb21689d25f 100644--- a/products/product_analytics/frontend/generated/api.zod.ts+++ b/products/product_analytics/frontend/generated/api.zod.ts@@ -323,6 +323,76 @@ export const InsightsDataChecksCreateBody = /* @__PURE__ */ zod.record(zod.string(), zod.unknown()).describe('Deep\/recursive schema (opaque in Zod — use TypeScript types for full shape)')+/**+ * Classify what most likely caused each moment on a chart. The caller sends chapters of facts that it computed from the chart's data, and gets back one cause from a fixed list for each chapter, with a confidence. The numbers stay with the caller: this endpoint runs no query and reads no insight. Without a decision model on the instance, the list is empty. The organization must approve AI data processing.+ */+export const insightsExplainCreateBodySeriesLabelMax = 200++export const insightsExplainCreateBodyInsightNameDefault = ``+export const insightsExplainCreateBodyInsightNameMax = 400++export const insightsExplainCreateBodyOverviewDefault = ``+export const insightsExplainCreateBodyOverviewMax = 600++export const insightsExplainCreateBodyChaptersItemIdMax = 64++export const insightsExplainCreateBodyChaptersItemTitleMax = 200++export const insightsExplainCreateBodyChaptersItemSummaryMax = 600++export const insightsExplainCreateBodyChaptersItemEvidenceItemMax = 600++export const insightsExplainCreateBodyChaptersItemEvidenceMax = 6++export const insightsExplainCreateBodyChaptersMax = 8++export const InsightsExplainCreateBody = /* @__PURE__ */ zod.object({+ series_label: zod+ .string()+ .max(insightsExplainCreateBodySeriesLabelMax)+ .describe('Name of the series that the explanation follows.'),+ insight_name: zod+ .string()+ .max(insightsExplainCreateBodyInsightNameMax)+ .default(insightsExplainCreateBodyInsightNameDefault)+ .describe('Name of the insight. Blank for an insight that has no name yet.'),+ overview: zod+ .string()+ .max(insightsExplainCreateBodyOverviewMax)+ .default(insightsExplainCreateBodyOverviewDefault)+ .describe('The computed facts of the whole chart, such as its typical level, its range and how it ends.'),+ chapters: zod+ .array(+ zod.object({+ id: zod+ .string()+ .max(insightsExplainCreateBodyChaptersItemIdMax)+ .describe('Identifier of the chapter. The response returns the chapter under the same one.'),+ title: zod+ .string()+ .max(insightsExplainCreateBodyChaptersItemTitleMax)+ .describe("What the chapter is about, for example 'A peak on October 2'."),+ summary: zod+ .string()+ .max(insightsExplainCreateBodyChaptersItemSummaryMax)+ .describe(+ 'The computed facts of the chapter in one or two sentences, with their numbers and dates.'+ ),+ evidence: zod+ .array(zod.string().max(insightsExplainCreateBodyChaptersItemEvidenceItemMax))+ .max(insightsExplainCreateBodyChaptersItemEvidenceMax)+ .optional()+ .describe(+ 'Findings about the cause of the chapter, one sentence each. Empty when nothing was found. At most 6.'+ ),+ })+ )+ .max(insightsExplainCreateBodyChaptersMax)+ .describe(+ 'The chapters of the explanation in reading order. At most 8. Empty when nothing stands out on the chart.'+ ),+})+/*** Generate an AI-suggested name and description for an insight based on its query configuration.*/diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.tsindex 39f49a66d683..8a4828570efd 100644--- a/services/mcp/src/api/generated.ts+++ b/services/mcp/src/api/generated.ts@@ -24248,6 +24248,26 @@ export namespace Schemas {star?: boolean;}+ /**+ * * `outside_traffic` - Outside traffic+ * * `usage` - Usage+ * * `one_person` - One person+ * * `tracking` - Tracking+ * * `weekly_pattern` - Weekly pattern+ * * `unclear` - Unclear+ */+ export type ChartCauseEnum = typeof ChartCauseEnum[keyof typeof ChartCauseEnum];+++ export const ChartCauseEnum = {+ OutsideTraffic: 'outside_traffic',+ Usage: 'usage',+ OnePerson: 'one_person',+ Tracking: 'tracking',+ WeeklyPattern: 'weekly_pattern',+ Unclear: 'unclear',+ } as const;+/*** * `author_scout` - author_scout* * `fleet_overview` - fleet_overview@@ -65506,6 +65526,74 @@ export namespace Schemas {depth?: InsightDataChecksDepthEnum;}+ export interface InsightExplainChapter {+ /** Identifier of the chapter, as it was sent. */+ id: string;+ /** What most likely caused the chapter: outside traffic, a real change in usage, one person or a test account, a tracking change, the usual weekly pattern, or unclear when no cause fits the facts.+ *+ * * `outside_traffic` - Outside traffic+ * * `usage` - Usage+ * * `one_person` - One person+ * * `tracking` - Tracking+ * * `weekly_pattern` - Weekly pattern+ * * `unclear` - Unclear */+ cause: ChartCauseEnum;+ /** How sure the model is of the cause, from 0 to 1. */+ confidence: number;+ }++ export interface InsightExplain {+ /** The likely cause of each chapter the model answered, in the order they were sent. */+ chapters: InsightExplainChapter[];+ }++ export interface InsightExplainChapterFacts {+ /**+ * Identifier of the chapter. The response returns the chapter under the same one.+ * @maxLength 64+ */+ id: string;+ /**+ * What the chapter is about, for example 'A peak on October 2'.+ * @maxLength 200+ */+ title: string;+ /**+ * The computed facts of the chapter in one or two sentences, with their numbers and dates.+ * @maxLength 600+ */+ summary: string;+ /**+ * Findings about the cause of the chapter, one sentence each. Empty when nothing was found. At most 6.+ * @maxItems 6+ * @items.maxLength 600+ */+ evidence?: string[];+ }++ export interface InsightExplainRequest {+ /**+ * Name of the series that the explanation follows.+ * @maxLength 200+ */+ series_label: string;+ /**+ * Name of the insight. Blank for an insight that has no name yet.+ * @maxLength 400+ */+ insight_name?: string;+ /**+ * The computed facts of the whole chart, such as its typical level, its range and how it ends.+ * @maxLength 600+ */+ overview?: string;+ /**+ * The chapters of the explanation in reading order. At most 8. Empty when nothing stands out on the chart.+ * @maxItems 8+ */+ chapters: InsightExplainChapterFacts[];+ }+/*** The anomaly detector the alert uses in place of its threshold, or null for a threshold alert. It can't change through this API.*/@@ -137713,6 +137801,18 @@ export namespace Schemas {Json: 'json',} as const;+ export type InsightsExplainCreateParams = {+ format?: InsightsExplainCreateFormat;+ };++ export type InsightsExplainCreateFormat = typeof InsightsExplainCreateFormat[keyof typeof InsightsExplainCreateFormat];+++ export const InsightsExplainCreateFormat = {+ Csv: 'csv',+ Json: 'json',+ } as const;+export type InsightsGenerateMetadataCreateParams = {format?: InsightsGenerateMetadataCreateFormat;};