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.

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.py
index de99e63ff5ba..21a38b0416bc 100644
--- a/posthog/rate_limit.py
+++ b/posthog/rate_limit.py
@@ -992,6 +992,17 @@ class AIObservabilitySummarizationDailyThrottle(PersonalApiKeyOrUserRateThrottle
rate = "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 the
query pool by resubmitting wide windows. Its own bucket keeps the call the UI makes on every
diff --git a/products/product_analytics/backend/presentation/insight.py b/products/product_analytics/backend/presentation/insight.py
index 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_querie
from posthog.hogql_queries.refresh_policy import ComputeSurface, resolve_execution_mode
from posthog.hogql_queries.utils.result_series import get_response_action_names
from posthog.kafka_client.topics import KAFKA_METRICS_TIME_TO_SEE_DATA
+from posthog.llm.system_one import SystemOneNotConfigured, SystemOneRequestFailed
from posthog.models import User
from 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 SafeJSONRenderer
from 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_chart
from 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 appl
return 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.py
new file mode 100644
index 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 causes
diff --git a/products/product_analytics/backend/tests/api/test_insight_explain.py b/products/product_analytics/backend/tests/api/test_insight_explain.py
new file mode 100644
index 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.ts
index 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.ts
index 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?: InsightsGenerateMetadataCreateParams
diff --git a/products/product_analytics/frontend/generated/api.zod.ts b/products/product_analytics/frontend/generated/api.zod.ts
index 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.ts
index 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;
};