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(aio): trace view summary mode (#124365)

Carlos Marchal494287d1fb59
diff --git a/frontend/snapshots.yml b/frontend/snapshots.yml
index c573c2a85bc0..b5144d94caab 100644
--- a/frontend/snapshots.yml
+++ b/frontend/snapshots.yml
@@ -9574,6 +9574,42 @@ snapshots:
hash: v1.k794b7964.bda2d5985bf7439273c42268b1279aa6eb2fee37e1aaafb4c199e98b1a8b7e94.oySozMrViJSTs1dyaKsz_3EdiTOd9MBj91nk8MO71fc
scenes-app-ai-observability-trace-view-raw-event--no-trace-event--light:
hash: v1.k794b7964.4a4e729043d00b03247ce25fe10de02bc132f3811c6c288032abcd36ed2fea03.REnmV4U-vFpxUJB4Lfun1zLM9Tf8tvqFDafAwrTYKeo
+ scenes-app-ai-observability-trace-view-summary-mode--failed--dark:
+ hash: v1.k794b7964.4abf12b65d07c1688d5305420fcfd87486bc224fd7fe0b433836ae676cc142eb.YqxYGmoK_sCUVQrzcp1_CIU0VYJ25biVjgFTiFiotvE
+ scenes-app-ai-observability-trace-view-summary-mode--failed--light:
+ hash: v1.k794b7964.a5213ac93e4611f98384ddd81515c9bb40af72c7de94713a941b3d83d2a53242.Jrjrgj5esB7aAFMThC7ytyWQoSmP83-KToqa0fQUE9o
+ scenes-app-ai-observability-trace-view-summary-mode--load-error--dark:
+ hash: v1.k794b7964.fcf2773d64a5ec3c08fd876c115a8bfd8fd5a46dd2dcc425a4924b1b003ec45b.22nG5MxOpTy_sCKXCJPJb86pDEtBGwxgpH_8J8Xv-Io
+ scenes-app-ai-observability-trace-view-summary-mode--load-error--light:
+ hash: v1.k794b7964.98cfa77ad17e9d9beeb4120279dd767408bb2a0fba21c789a6e1b843837dce83.7zG6_stX6jMWR6KR_wjJOmZg5DglxG5FBrMNBq6stjs
+ scenes-app-ai-observability-trace-view-summary-mode--loading--dark:
+ hash: v1.k794b7964.846d9d00d8df94a46814b129925c35c45d4ee3f2e710bb5103ba3d13542c1413.RSAI9xxjVeXPT34ZUyX-WGDuYl7gOojOLjvboCcdMfM
+ scenes-app-ai-observability-trace-view-summary-mode--loading--light:
+ hash: v1.k794b7964.ab87160e754d92d0292e4998f23620ee22dfc804c02e07ed13e85e432f647ec1.e8q0LUzn1xLCXXtl4cCzv3eeVexRJcz9QcwsdtzYLsQ
+ scenes-app-ai-observability-trace-view-summary-mode--no-summary--dark:
+ hash: v1.k794b7964.4364c13ac5bcb86c4705d187be83bfd85dccca641df94c95bbc67572d9e937da.wg6e0o4kVdSn3TN7mKz3j4dFroGqeHa0h_qtlSGooOY
+ scenes-app-ai-observability-trace-view-summary-mode--no-summary--light:
+ hash: v1.k794b7964.56ec4eaf98d879e4662a87148005224b42502acd125700ef1140b6405703c508.5XIEYA4ltswgH0NnMiDudkKQr59_lwEa6dpE81Z1dDI
+ scenes-app-ai-observability-trace-view-summary-mode--no-summary-without-consent--dark:
+ hash: v1.k794b7964.a788c97790b33666465ec0c9d535c43d8c9b1fb440bd47136798176d8d808b9e.vlyV6DEZnNpWySz800U2K5MNzcirIaOqQ0_xMFxEl9Y
+ scenes-app-ai-observability-trace-view-summary-mode--no-summary-without-consent--light:
+ hash: v1.k794b7964.0c4bb02ddd8d00ea28151489faeda769975d99d5295c08e13c81879b6c4d904e.qIklV4bzd0VLAE4HaJqBZCXwqYNeTZS-8AL4rcCACkA
+ scenes-app-ai-observability-trace-view-summary-mode--pending--dark:
+ hash: v1.k794b7964.d70b67bed4c56d02f612eb0bf9fcfe24f690df1149a0a8294c59d7b9a3b8c1e4.kotoqFFS0aMbpd0mDGEVDqCzorGaNFkqFUcQLvHOjMc
+ scenes-app-ai-observability-trace-view-summary-mode--pending--light:
+ hash: v1.k794b7964.2c5c96090b2deda2d3b2aa90f3326db6e6aafbdabcfce33778373183903c12d1.PRvv71yDZvUizx4CiemMARgsT-ob6ddEyHnaRb0X0hA
+ scenes-app-ai-observability-trace-view-summary-mode--ready--dark:
+ hash: v1.k794b7964.8fb1323a5d8b032333576207fb6105d3f2210eba42360915ddbf8b0e1e9d26aa.Ra2ukbkyO7PQieh0X8Yupxwhhgyxh13c6SNFS744e6M
+ scenes-app-ai-observability-trace-view-summary-mode--ready--light:
+ hash: v1.k794b7964.b8de89b97b8120b24749949310e73e90d066213583d2348137d82687f2fb3dfb.lWt28eCCzuFclWBvc71qDWG7pzl10YQ07KmkcxUg4M8
+ scenes-app-ai-observability-trace-view-summary-mode--ready-narrow--dark:
+ hash: v1.k794b7964.dc65948ac96ca231a758c2b5112db46f16f90224d09c38401f29858246dac6b2._f-JvnmrA3VOn-_9z8ENIEc3fSa6pF-kvbwHaaOErj4
+ scenes-app-ai-observability-trace-view-summary-mode--ready-narrow--light:
+ hash: v1.k794b7964.4668180850679b174ae668cce3727d38e655f464ec7f0ef2707a7fdaa8da2ac1.4yvBhhTt5cWujb_w8Be6c2cb3plwl0dhR02va3Nkd48
+ scenes-app-ai-observability-trace-view-summary-mode--regenerate-throttled--dark:
+ hash: v1.k794b7964.1a1441eff53dded5d12c20b588a093321f3be1c3fc184ad153b2945a7e7ab769.Jlm1Q0_WdDc4OKI04J6mSJFyJW-EwjYh-mWUEnAUwdM
+ scenes-app-ai-observability-trace-view-summary-mode--regenerate-throttled--light:
+ hash: v1.k794b7964.c3b525e4fdc0531976644c4e4a0e18187d1a34f11fbf02a9a30f439f44f37d70.7iUDCUlU4crEiuBnz3jBp-wDO9L6Egy5NJLfJWkstLE
scenes-app-ai-observability-trace-view-thread--anthropic-thinking-and-tools--dark:
hash: v1.k794b7964.b3d0fe41e4ce3167d04d9c3f1fdb4b25414b9c27f3d9b26dc4122e5490b97663.rVseBKdzxKu43YsBqrE-cO9KxX7roQd9qLgsEj49jPo
scenes-app-ai-observability-trace-view-thread--anthropic-thinking-and-tools--light:
@@ -9651,9 +9687,9 @@ snapshots:
scenes-app-ai-observability-trace-view-trace-header--narrow--light:
hash: v1.k794b7964.9fca5efe3c2de8d82b73848a8d53c57cc8beb108f927b4243c83f5e16e6814db.dlDT_i8yO4AuXDskXau5HcG0BzAI_n0LYfiX8aENnIw
scenes-app-ai-observability-trace-view-trace-mode-tabs--default--dark:
- hash: v1.k794b7964.7cf093e59c368f216040a0f9b171d6b057d836cd6b4d7494c80afcd54b572236.zG0PO1xmIJKZL2YNOK6NgCIO7yYwaEwPKBIis66MOYs
+ hash: v1.k794b7964.c127014e07f56d9cc05464accffc054cd7fc158ecc05f68412286c1c68e52920.imWl_iWrNCNM_tSkxLW8WzC_8FKPDXmWuK1Jq2Bjopk
scenes-app-ai-observability-trace-view-trace-mode-tabs--default--light:
- hash: v1.k794b7964.abf38a7627d80aa64c4187501a9c6ad8dcc39e0b57402841cbf862df1a41a226.N9uBDDVrhCVpW_R4XVKjwUetTWFX-JKeukwde_hvsHQ
+ hash: v1.k794b7964.8c463d9853989ca1f4963cbe4537d059ab1bb411e924a2419a3005c7575bf7be.fWN4UhPWA9QTC39P0SQDKe4A3iqksw4pTrbvrWEQ_zk
scenes-app-ai-observability-trace-view-trace-split-view--narrow--dark:
hash: v1.k794b7964.7e4eef01f6f5dca0671db52b44959fdc401a61dec4d72ca3730a7276033c73ee.NS9WNST2qDaBnvQacs6Lnro9dedItLwYX7M40RNgJxo
scenes-app-ai-observability-trace-view-trace-split-view--narrow--light:
@@ -9763,17 +9799,17 @@ snapshots:
scenes-app-ai-observability-trace-view-trace-view--sample-anthropic-thinking-tool-use--light:
hash: v1.k794b7964.590a6eaff8315f61e7014dec10e6b76ad62e2276bd6b192a62752c9df92f38e7.Tx9-RxKj-RoPdf-KYfQQSu1g-oVRmwL8cLuk6C3jmLs
scenes-app-ai-observability-trace-view-trace-view--sample-claude-code-session--dark:
- hash: v1.k794b7964.8f2db49aff986042a4ce7e93a0d8af45438f8895c11750b832e4aab9b88b0f1f.kd3dJJiOAhDc9_UyGSPZQ9NtePjGHi6sntFdU8Dgjpo
+ hash: v1.k794b7964.4f299bbc25de783c019e346e13b7dff0bbdcb9c0afa384424502246d2200cb11.oFJCtJ9GaMcq36FXdtSfTqxktwXT4L9qgdNpYq1KFcs
scenes-app-ai-observability-trace-view-trace-view--sample-claude-code-session--light:
- hash: v1.k794b7964.918b029246c131d679792d600443866bea3a84d4ccf54b7436e171a891fdeae6.wOV-R0JOaigQwD5JZGj9LrWZ0WgmoPAtgMp7Pkd2J5M
+ hash: v1.k794b7964.667b0b5bf607288437fc42d6b2a87e12749e5e5431694034af87a030165f5382.5L9pc3B4k-1h1ORigHPuxnBoVMjWkKM2_mwC1NAxvEI
scenes-app-ai-observability-trace-view-trace-view--sample-lang-chain-image-error--dark:
- hash: v1.k794b7964.3d1f6c313a8f35a17bef5c0c1e6835e86ee2231a2653134c39778c8d288f5db3.nnh4BgR42aNDqtcIhGB9G1oD30coKun5HTU-wfVjznk
+ hash: v1.k794b7964.9438d2ccbef1be8ae87db81123cae1184342c55c811a3a06c4e76e903e3c980e.U8liqolfJijqkndiT5N8vO7_QuU9Fb7u63C6eLRlHco
scenes-app-ai-observability-trace-view-trace-view--sample-lang-chain-image-error--light:
- hash: v1.k794b7964.237023c556967dacce06dca0afc49697ff4dbd6afccc1248366feca2c21cc6cd.Bh4R1giQ-5gRwsPQUrV1kOO2ljZTLaIl80NMNSSwIzo
+ hash: v1.k794b7964.c4e68e4bc073acfd3526b31c9a6c30af8227b383cfe9c64c869a9085e2f21366.OW-LgHY5e0KMPR6d3J8lqdrhnjUBljeLruIIU4--5o8
scenes-app-ai-observability-trace-view-trace-view--sample-open-ai-agents-with-evals--dark:
- hash: v1.k794b7964.299785b9e5f10b28be2bccaf56e673a6f112f2d51dcdd4318afca90518dc5f4c.SFBeWI-nmkNEi2JGsCl6kG8y2e-ahRSo6FvJfdkPlf0
+ hash: v1.k794b7964.3b6cfa51d04e12c148f1da5f58a5e9f8f275a6c4e5b21d2ffd7882724e69212a.E-hiUUQTSRTbhyFBtQ84ROVaZPwc9Y8aiMf9a3PWHck
scenes-app-ai-observability-trace-view-trace-view--sample-open-ai-agents-with-evals--light:
- hash: v1.k794b7964.3357a3f15e82121ea28ee6bc90a3d0ffc6fd8807cfdd2e77329fc475eacae149.pRZlmnw9ls3z0dR2Ri4OLeLLUNKLE7pURFRi7cWKu98
+ hash: v1.k794b7964.da0833b682042c272451cdc1b879b3c355db96c7a1a08f4d7d932e5651a5045d.sfjWlM4sh7jLKWwOn6_6uANHQHh7pQzJHu1-JCor8Ro
scenes-app-ai-observability-trace-view-trace-view--span-selected--dark:
hash: v1.k794b7964.a627385c064141e6dcc1c4982b480253e078f86dadf70ed946b2053e6582eb3e.LqyOLP_eIAZNH0bQ6WAyzn-RWqWFqzv2HOutDpa8ziI
scenes-app-ai-observability-trace-view-trace-view--span-selected--light:
diff --git a/frontend/src/initKea.ts b/frontend/src/initKea.ts
index f46e86f5a4e2..1995beca51fc 100644
--- a/frontend/src/initKea.ts
+++ b/frontend/src/initKea.ts
@@ -137,6 +137,9 @@ const ERROR_FILTER_ALLOW_LIST_BY_LOGIC_PATH: Record<string, string> = {
updateProviderKey: 'products.ai_observability.settings.llmProviderKeysLogic',
deleteProviderKey: 'products.ai_observability.settings.llmProviderKeysLogic',
loadEvaluationResults: 'products.ai_observability.frontend.redesign.trace.traceViewLogic', // The trace view's Evals tab shows the error
+ // The trace view's Summary mode shows the error
+ loadSummary: 'products.ai_observability.frontend.redesign.trace.traceSummaryLogic',
+ requestSummary: 'products.ai_observability.frontend.redesign.trace.traceSummaryLogic',
}
// A keyed logic's path ends with its key, so match the owner path as a prefix.
diff --git a/posthog/management/commands/start_temporal_worker.py b/posthog/management/commands/start_temporal_worker.py
index c5f1da4cacf3..642190211ae3 100644
--- a/posthog/management/commands/start_temporal_worker.py
+++ b/posthog/management/commands/start_temporal_worker.py
@@ -163,6 +163,10 @@ from products.aeo.backend.facade.temporal import (
ACTIVITIES as AEO_BRAND_SENTIMENT_ACTIVITIES,
WORKFLOWS as AEO_BRAND_SENTIMENT_WORKFLOWS,
)
+from products.ai_observability.backend.facade.temporal import (
+ ACTIVITIES as AI_OBSERVABILITY_PRODUCT_ACTIVITIES,
+ WORKFLOWS as AI_OBSERVABILITY_PRODUCT_WORKFLOWS,
+)
from products.alerts.backend.facade.temporal import (
PLATFORM_AI_QUEUE_ACTIVITIES as INSIGHT_PLATFORM_AI_QUEUE_ACTIVITIES,
PLATFORM_EVALUATION_ACTIVITIES as INSIGHT_PLATFORM_EVALUATION_ACTIVITIES,
@@ -606,8 +610,8 @@ _task_queue_specs = [
),
(
settings.LLMA_TASK_QUEUE,
- LLM_ANALYTICS_WORKFLOWS,
- LLM_ANALYTICS_ACTIVITIES,
+ LLM_ANALYTICS_WORKFLOWS + AI_OBSERVABILITY_PRODUCT_WORKFLOWS,
+ LLM_ANALYTICS_ACTIVITIES + AI_OBSERVABILITY_PRODUCT_ACTIVITIES,
),
(
# MCP analytics clustering. MCPA_TASK_QUEUE defaults to the
diff --git a/posthog/management/commands/test/test_start_temporal_worker.py b/posthog/management/commands/test/test_start_temporal_worker.py
index b81f55abff39..696776822fda 100644
--- a/posthog/management/commands/test/test_start_temporal_worker.py
+++ b/posthog/management/commands/test/test_start_temporal_worker.py
@@ -20,9 +20,14 @@ from posthog.management.commands.start_temporal_worker import (
apply_hogql_shadow_sample_rate_override,
workflows_include_data_import_syncs,
)
+from posthog.temporal.ai_observability import BatchTraceSummarizationWorkflow
from posthog.temporal.usage_report.activities import aggregate_and_chunk_org_reports
from posthog.temporal.usage_report.workflow import RunUsageReportsWorkflow
+from products.ai_observability.backend.facade.temporal import (
+ ACTIVITIES as AI_OBSERVABILITY_ACTIVITIES,
+ WORKFLOWS as AI_OBSERVABILITY_WORKFLOWS,
+)
from products.alerts_platform.backend.facade.temporal import (
DELIVERY_ACTIVITIES,
DELIVERY_WORKFLOWS,
@@ -146,6 +151,21 @@ def test_ai_queue_registers_the_alert_evaluate_activity() -> None:
assert set(INSIGHT_PLATFORM_AI_QUEUE_ACTIVITIES) <= set(entries[0])
+# The facade starts the trace summary on the LLMA queue by name. Registered elsewhere, every request would stay
+# pending until its entry expired.
+def test_trace_summary_runs_on_the_llma_queue() -> None:
+ entries = [
+ (queue, workflows, activities)
+ for queue, workflows, activities in _task_queue_specs
+ if all(workflow in workflows for workflow in AI_OBSERVABILITY_WORKFLOWS)
+ ]
+
+ assert len(entries) == 1
+ queue, workflows, activities = entries[0]
+ assert queue == settings.LLMA_TASK_QUEUE and BatchTraceSummarizationWorkflow in workflows
+ assert all(activity in activities for activity in AI_OBSERVABILITY_ACTIVITIES)
+
+
@pytest.mark.parametrize(
"env_value, expected",
[
diff --git a/products/ai_observability/backend/facade/api.py b/products/ai_observability/backend/facade/api.py
index 92ccd5920aea..2ed63c2d42cc 100644
--- a/products/ai_observability/backend/facade/api.py
+++ b/products/ai_observability/backend/facade/api.py
@@ -22,11 +22,24 @@ from ..logic.traces.evaluation_summary import EvaluationSummary
from ..logic.traces.events_fallback import fallback_window
from ..logic.traces.git import GitRef
from ..logic.traces.node import NodeEvent
+from ..logic.traces.summary import (
+ AIDataProcessingNotApprovedError as AIDataProcessingNotApprovedError,
+ FailedSummary,
+ PendingSummary,
+ ReadySummary,
+ SummaryEntry,
+ SummaryItem,
+ TraceSummaryNotFoundError as TraceSummaryNotFoundError,
+ TraceSummaryRetryableError as TraceSummaryRetryableError,
+)
+from ..logic.traces.summary_generation import generate_summary
+from ..logic.traces.summary_store import fail_abandoned_summary, request_summary, viewer_summary
from ..logic.traces.timeline import TimelineRow
from ..logic.traces.trace import Trace
from ..logic.traces.trace_queries import load_trace, load_trace_node, load_trace_root
from ..logic.traces.tree import TreeNode
from ..logic.traces.usage import Usage
+from ..temporal.trace_summary_client import start_trace_summary
from . import contracts
@@ -306,3 +319,49 @@ def get_evaluation_score_distribution(
if meta.scale is None or buckets is None:
raise NoScoreScaleError(evaluation_id)
return load_score_distribution(team, user, evaluation_id, period, meta.scale, buckets)
+
+
+def get_trace_summary(team: Team, user: User, trace_id: str) -> contracts.TraceSummary:
+ """Raises `AIDataProcessingNotApprovedError`, or `TraceSummaryNotFoundError` when this viewer has no summary."""
+ return _to_trace_summary(viewer_summary(team, user, trace_id))
+
+
+def request_trace_summary(
+ team: Team, user: User, trace_id: str, timestamp_hint: datetime | None, *, regenerate: bool
+) -> contracts.TraceSummary:
+ """A ready summary, or the pending one a job now writes. Raises `AIDataProcessingNotApprovedError`."""
+ return _to_trace_summary(request_summary(team, user, trace_id, timestamp_hint, regenerate, start_trace_summary))
+
+
+def generate_trace_summary(job: contracts.TraceSummaryJob, *, final_attempt: bool) -> contracts.TraceSummaryRun | None:
+ """The trace summary job's body, or None when its entry no longer waits for it. Raises
+ `TraceSummaryRetryableError` when a later attempt can succeed."""
+ return generate_summary(job, final_attempt=final_attempt)
+
+
+def fail_trace_summary(job: contracts.TraceSummaryJob) -> None:
+ """Mark the job's summary failed when the job ended without writing it."""
+ fail_abandoned_summary(job)
+
+
+def _to_summary_items(items: tuple[SummaryItem, ...]) -> list[contracts.TraceSummaryItem]:
+ return [contracts.TraceSummaryItem(text=item.text, node_id=item.node_id) for item in items]
+
+
+def _to_trace_summary(entry: SummaryEntry) -> contracts.TraceSummary:
+ match entry:
+ case PendingSummary():
+ return contracts.TraceSummary(status="pending", content=None, failure=None)
+ case ReadySummary():
+ content = contracts.TraceSummaryContent(
+ title=entry.title,
+ bullets=_to_summary_items(entry.bullets),
+ notes=_to_summary_items(entry.notes),
+ flow=entry.flow,
+ model=entry.model,
+ generated_at=entry.generated_at,
+ )
+ return contracts.TraceSummary(status="ready", content=content, failure=None)
+ case FailedSummary():
+ failure = contracts.TraceSummaryFailure(reason=entry.reason, message=entry.message)
+ return contracts.TraceSummary(status="failed", content=None, failure=failure)
diff --git a/products/ai_observability/backend/facade/contracts.py b/products/ai_observability/backend/facade/contracts.py
index bad7344392e8..b1e3166d8352 100644
--- a/products/ai_observability/backend/facade/contracts.py
+++ b/products/ai_observability/backend/facade/contracts.py
@@ -4,6 +4,8 @@ from typing import Annotated, Any, Literal, get_args
from pydantic import BaseModel, ConfigDict, Field
from pydantic.alias_generators import to_camel
+from posthog.dataclasses import frozen
+
class Contract(BaseModel):
# Without `json_schema_serialization_defaults_required`, fields with defaults generate as optional in TypeScript.
@@ -167,6 +169,64 @@ class TraceEvaluationResults(Contract):
summary: TraceEvaluationSummary
+TraceSummaryStatus = Literal["pending", "ready", "failed"]
+TraceSummaryFailureReason = Literal[
+ "trace_not_found", "too_large", "timeout", "provider_error", "not_approved", "access_changed", "error"
+]
+
+
+@frozen
+class TraceSummaryJob:
+ """What the trace summary job needs to write one summary. Ids only, so the workflow history stays small.
+ `requested_at` is when the pending entry the job fills was written."""
+
+ team_id: int
+ trace_id: str
+ timestamp_hint: datetime | None
+ fingerprint: str
+ requester_id: int
+ requested_at: datetime
+
+
+class TraceSummaryItem(Contract):
+ text: str
+ node_id: str | None = Field(description="The step the item refers to, or null when it names none.")
+
+
+class TraceSummaryContent(Contract):
+ title: str
+ bullets: list[TraceSummaryItem]
+ notes: list[TraceSummaryItem] = Field(description="Details worth a second look, or empty.")
+ flow: str = Field(description="The main steps of the trace as a small text diagram.")
+ model: str = Field(description="The model that wrote the summary.")
+ generated_at: datetime
+
+
+class TraceSummaryFailure(Contract):
+ reason: TraceSummaryFailureReason
+ message: str = Field(description="Why the summary failed, ready to show to the user.")
+
+
+class TraceSummary(Contract):
+ status: TraceSummaryStatus = Field(description="`pending` while the summary is written, then `ready` or `failed`.")
+ content: TraceSummaryContent | None = Field(description="The summary when `status` is `ready`, else null.")
+ failure: TraceSummaryFailure | None = Field(description="Why it failed when `status` is `failed`, else null.")
+
+
+@frozen
+class TraceSummaryRun:
+ """What one run of the trace summary job did, for usage reporting."""
+
+ status: Literal["ready", "failed"]
+ failure_reason: TraceSummaryFailureReason | None
+ duration_ms: int
+ input_characters: int
+ model: str
+ was_sampled: bool
+ distinct_id: str
+ groups: dict[str, str]
+
+
AttentionReason = Literal["errored", "silent", "worse"]
BucketStatus = Literal["none", "dip", "normal"]
Interval = Literal["hour", "day"]
diff --git a/products/ai_observability/backend/facade/temporal.py b/products/ai_observability/backend/facade/temporal.py
new file mode 100644
index 000000000000..5c85131955f5
--- /dev/null
+++ b/products/ai_observability/backend/facade/temporal.py
@@ -0,0 +1,9 @@
+"""Facade re-export for the AI observability Temporal surface.
+
+The worker registers ``WORKFLOWS``/``ACTIVITIES`` on the LLMA task queue. Isolated from ``facade/api.py`` so the
+workflow sandbox imports never land on the web request path.
+"""
+
+from products.ai_observability.backend.temporal.registry import ACTIVITIES, WORKFLOWS
+
+__all__ = ["ACTIVITIES", "WORKFLOWS"]
diff --git a/products/ai_observability/backend/logic/traces/node_contents_queries.py b/products/ai_observability/backend/logic/traces/node_contents_queries.py
new file mode 100644
index 000000000000..23e8cebe2ebf
--- /dev/null
+++ b/products/ai_observability/backend/logic/traces/node_contents_queries.py
@@ -0,0 +1,62 @@
+from collections.abc import Sequence
+from datetime import datetime
+
+from posthog.hogql import ast
+
+from posthog.models import Team, User
+
+from .trace_queries import (
+ _NODE_COLUMNS,
+ NODE_EVENT_NAMES,
+ TraceNodeRow,
+ _ai_events,
+ _event_in,
+ _filter_conditions,
+ _read_trace,
+ _trace_node_row,
+ canonical_uuid,
+)
+
+
+def _nodes_query(event_uuids: Sequence[str]) -> ast.SelectQuery:
+ return ast.SelectQuery(
+ select=[ast.Field(chain=[column]) for column in _NODE_COLUMNS],
+ select_from=_ai_events(),
+ where=ast.And(
+ exprs=[
+ _event_in(NODE_EVENT_NAMES),
+ ast.CompareOperation(
+ op=ast.CompareOperationOp.In,
+ left=ast.Field(chain=["uuid"]),
+ right=ast.Tuple(exprs=[ast.Constant(value=event_uuid) for event_uuid in event_uuids]),
+ ),
+ _filter_conditions(),
+ ]
+ ),
+ limit_by=ast.LimitByExpr(n=ast.Constant(value=1), exprs=[ast.Field(chain=["uuid"])]),
+ limit=ast.Constant(value=len(event_uuids)),
+ )
+
+
+def load_trace_nodes(
+ team: Team, user: User | None, trace_id: str, node_ids: Sequence[str], timestamp_hint: datetime | None
+) -> list[TraceNodeRow]:
+ """The content of each node of this trace in `node_ids`, in that order, skipping ids it does not hold.
+
+ One read per call, so callers batch the ids. Like the single node read, it never widens to the unhinted
+ events scan.
+ """
+ event_uuids = list(dict.fromkeys(uuid for node_id in node_ids if (uuid := canonical_uuid(node_id)) is not None))
+ if not event_uuids:
+ return []
+ results = _read_trace(
+ "ai_trace_nodes",
+ lambda: _nodes_query(event_uuids),
+ team,
+ user,
+ trace_id,
+ timestamp_hint,
+ widen_unhinted=False,
+ )
+ rows = {row.uuid: row for row in map(_trace_node_row, results)}
+ return [rows[event_uuid] for event_uuid in event_uuids if event_uuid in rows]
diff --git a/products/ai_observability/backend/logic/traces/summary.py b/products/ai_observability/backend/logic/traces/summary.py
new file mode 100644
index 000000000000..32b0a0bf1fc6
--- /dev/null
+++ b/products/ai_observability/backend/logic/traces/summary.py
@@ -0,0 +1,162 @@
+import re
+import hashlib
+from collections.abc import Sequence
+from datetime import datetime, timedelta
+from typing import Literal, Self
+
+from posthog.dataclasses import frozen
+from posthog.temporal.common.errors import NonReportableError
+
+from ...facade.contracts import TraceSummaryFailureReason, TraceSummaryJob
+from ...summarization.constants import SUMMARIZATION_TIMEOUT
+
+# The OpenAI client retries a failed call twice by default, each attempt with the full timeout.
+LLM_CALL_DEADLINE = timedelta(seconds=SUMMARIZATION_TIMEOUT * 3)
+ATTEMPT_DEADLINE = LLM_CALL_DEADLINE + timedelta(minutes=2)
+MAX_ATTEMPTS = 2
+RETRY_INITIAL_INTERVAL = timedelta(seconds=15)
+RETRY_BACKOFF = 2.0
+RETRY_MAX_INTERVAL = timedelta(seconds=60)
+HEARTBEAT_TIMEOUT = timedelta(seconds=60)
+JOB_DEADLINE = MAX_ATTEMPTS * ATTEMPT_DEADLINE + RETRY_MAX_INTERVAL
+# Marking an abandoned entry failed is one cache write, retried a few times.
+FAIL_DEADLINE = timedelta(minutes=2)
+WORKFLOW_DEADLINE = JOB_DEADLINE + FAIL_DEADLINE
+# A pending entry outlives the workflow, so a job lost before it writes its result expires and can be requested again.
+PENDING_TTL = WORKFLOW_DEADLINE + timedelta(minutes=1)
+READY_TTL = timedelta(hours=1)
+FAILED_TTL = timedelta(minutes=5)
+
+FAILURE_MESSAGES: dict[TraceSummaryFailureReason, str] = {
+ "trace_not_found": "We couldn't find this trace's events. They may have expired.",
+ "too_large": "This trace is too large to summarize.",
+ "timeout": "The model took too long to answer. Try again.",
+ "provider_error": "The model provider returned an error. Try again in a few minutes.",
+ "not_approved": "Your organization hasn't approved AI data processing.",
+ "access_changed": "Your data access changed while the summary was being written. Try again.",
+ "error": "Something went wrong while summarizing. Try again.",
+}
+
+_LINE_REF = re.compile(r"L(\d+)")
+
+
+class AIDataProcessingNotApprovedError(Exception):
+ pass
+
+
+class TraceSummaryNotFoundError(Exception):
+ pass
+
+
+# Not reported: a later attempt runs, and the final attempt reports the failure that costs the user their summary.
+class TraceSummaryRetryableError(NonReportableError):
+ def __init__(self, reason: TraceSummaryFailureReason) -> None:
+ super().__init__(reason)
+ self.reason = reason
+
+
+def require_ai_data_processing_approval(approved: bool | None) -> None:
+ if not approved:
+ raise AIDataProcessingNotApprovedError()
+
+
+def _sha256(value: str) -> str:
+ return hashlib.sha256(value.encode()).hexdigest()
+
+
+@frozen
+class SummaryKey:
+ team_id: int
+ trace_id: str
+ fingerprint: str
+
+ @classmethod
+ def for_job(cls, job: TraceSummaryJob) -> Self:
+ return cls(team_id=job.team_id, trace_id=job.trace_id, fingerprint=job.fingerprint)
+
+ @property
+ def cache_key(self) -> str:
+ # Hashing bounds the key for any trace id, and the version lets the entry shape change without reading old values.
+ return f"ai_observability:trace_summary:v1:{self.team_id}:{_sha256(self.trace_id)}:{self.fingerprint}"
+
+
+def workflow_id(job: TraceSummaryJob) -> str:
+ """One workflow per pending entry: requests that share an entry share its run, and a new entry gets a new run
+ even while the previous run is closing."""
+ pending = f"{SummaryKey.for_job(job).cache_key}:{job.requested_at.isoformat()}"
+ return f"ai-observability-trace-summary-{_sha256(pending)}"
+
+
+@frozen
+class SummaryItem:
+ text: str
+ node_id: str | None
+
+
+@frozen
+class PendingSummary:
+ requested_at: datetime
+ status: Literal["pending"] = "pending"
+
+
+@frozen
+class ReadySummary:
+ title: str
+ bullets: tuple[SummaryItem, ...]
+ notes: tuple[SummaryItem, ...]
+ flow: str
+ model: str
+ generated_at: datetime
+ status: Literal["ready"] = "ready"
+
+
+@frozen
+class FailedSummary:
+ reason: TraceSummaryFailureReason
+ failed_at: datetime
+ status: Literal["failed"] = "failed"
+
+ @property
+ def message(self) -> str:
+ return FAILURE_MESSAGES[self.reason]
+
+
+SummaryEntry = PendingSummary | ReadySummary | FailedSummary
+RequestPlan = Literal["return", "claim", "replace", "attach"]
+
+
+def plan_request(existing: SummaryEntry | None, regenerate: bool) -> RequestPlan:
+ match existing:
+ case None:
+ return "claim"
+ case PendingSummary():
+ return "attach"
+ case ReadySummary():
+ return "replace" if regenerate else "return"
+ case FailedSummary():
+ return "replace"
+
+
+def ttl_for(entry: SummaryEntry) -> timedelta:
+ match entry:
+ case PendingSummary():
+ return PENDING_TTL
+ case ReadySummary():
+ return READY_TTL
+ case FailedSummary():
+ return FAILED_TTL
+
+
+def line_number(ref: str) -> int | None:
+ match = _LINE_REF.fullmatch(ref)
+ return int(match.group(1)) if match else None
+
+
+def summary_items(items: Sequence[tuple[str, str]], line_owners: Sequence[str | None]) -> tuple[SummaryItem, ...]:
+ """Each `(text, line reference)` pair as an item linked to the step that owns the referenced line."""
+
+ def owner(ref: str) -> str | None:
+ number = line_number(ref)
+ return line_owners[number - 1] if number is not None and 0 < number <= len(line_owners) else None
+
+ return tuple(SummaryItem(text=text, node_id=owner(ref)) for text, ref in items)
diff --git a/products/ai_observability/backend/logic/traces/summary_generation.py b/products/ai_observability/backend/logic/traces/summary_generation.py
new file mode 100644
index 000000000000..c413ac318ff7
--- /dev/null
+++ b/products/ai_observability/backend/logic/traces/summary_generation.py
@@ -0,0 +1,169 @@
+import time
+from typing import Literal
+
+from django.utils import timezone
+
+from openai import APIStatusError, APITimeoutError
+from rest_framework import exceptions
+
+from posthog.dataclasses import frozen
+from posthog.event_usage import groups
+from posthog.exceptions_capture import capture_exception
+from posthog.models import Team, User
+
+from ...facade.contracts import TraceSummaryFailureReason, TraceSummaryJob, TraceSummaryRun
+from ...llm.errors import is_context_window_error_message
+from ...summarization.budget import text_repr_budget
+from ...summarization.constants import DEFAULT_MODEL_OPENAI
+from ...summarization.llm import summarize
+from ...summarization.llm.openai import SummarizationFailedError
+from ...summarization.models import SummarizationMode
+from ...text_repr.formatters import TraceTextRepr
+from .node_contents_queries import load_trace_nodes
+from .summary import FailedSummary, ReadySummary, SummaryKey, TraceSummaryRetryableError, summary_items
+from .summary_store import delete_summary, job_owns_entry, requester_fingerprint, write_summary
+from .summary_text import render_trace
+from .trace import Trace
+from .trace_queries import load_trace, load_trace_root
+
+# A provider answers these 4xx statuses for a transient condition, so a later attempt can succeed. 499 is a
+# cancellation.
+_TRANSIENT_CLIENT_STATUSES = frozenset({408, 409, 429, 499})
+_MODEL = str(DEFAULT_MODEL_OPENAI)
+
+
+@frozen
+class SummaryFailure:
+ reason: TraceSummaryFailureReason
+ retryable: bool
+
+
+def failure_of(error: Exception) -> SummaryFailure:
+ """Classify an error from the summarization call."""
+ if isinstance(error, exceptions.ValidationError):
+ return SummaryFailure(reason="provider_error", retryable=True)
+ # The summarization call raises its own error inside the handler of the provider's, which keeps it as context.
+ provider_error = error.__context__ if isinstance(error, SummarizationFailedError) else error
+ # The SDK retries a timeout before it raises, so another attempt would only add more of the same waits.
+ if isinstance(provider_error, APITimeoutError):
+ return SummaryFailure(reason="timeout", retryable=False)
+ if isinstance(provider_error, APIStatusError) and 400 <= provider_error.status_code < 500:
+ if provider_error.code == "context_length_exceeded" or is_context_window_error_message(provider_error.message):
+ return SummaryFailure(reason="too_large", retryable=False)
+ if provider_error.status_code not in _TRANSIENT_CLIENT_STATUSES:
+ return SummaryFailure(reason="provider_error", retryable=False)
+ return SummaryFailure(reason="provider_error", retryable=True)
+
+
+class _Run:
+ def __init__(self, job: TraceSummaryJob, team: Team, requester: User) -> None:
+ self.job = job
+ self.team = team
+ self.requester = requester
+ self.key = SummaryKey.for_job(job)
+ self.started = time.monotonic()
+
+ def ready(self, entry: ReadySummary, rendered: TraceTextRepr) -> TraceSummaryRun:
+ write_summary(self.key, entry)
+ return self._report("ready", None, rendered)
+
+ def failed(self, reason: TraceSummaryFailureReason, rendered: TraceTextRepr | None = None) -> TraceSummaryRun:
+ write_summary(self.key, FailedSummary(reason=reason, failed_at=timezone.now()))
+ return self._report("failed", reason, rendered)
+
+ def withdrawn(self) -> TraceSummaryRun:
+ # Nobody can read the entry while the organization has no approval, and a failure kept past a new approval
+ # would show a stale reason, so the entry goes and the next request starts over.
+ delete_summary(self.key)
+ return self._report("failed", "not_approved", None)
+
+ def access_changed(self) -> TraceSummaryRun:
+ # Every viewer with the request's fingerprint shares the entry, so a failure kept here would tell viewers whose
+ # access did not change that theirs did.
+ delete_summary(self.key)
+ return self._report("failed", "access_changed", None)
+
+ def _report(
+ self,
+ status: Literal["ready", "failed"],
+ reason: TraceSummaryFailureReason | None,
+ rendered: TraceTextRepr | None,
+ ) -> TraceSummaryRun:
+ return TraceSummaryRun(
+ status=status,
+ failure_reason=reason,
+ duration_ms=round((time.monotonic() - self.started) * 1000),
+ input_characters=len(rendered.text) if rendered else 0,
+ model=_MODEL,
+ was_sampled=rendered.was_sampled if rendered else False,
+ distinct_id=self.requester.distinct_id or str(self.team.uuid),
+ groups=groups(self.team.organization, self.team),
+ )
+
+
+def generate_summary(job: TraceSummaryJob, *, final_attempt: bool) -> TraceSummaryRun | None:
+ """Write the job's summary entry as `ready` or `failed` and report what the run did, or return None when the
+ entry no longer waits for this job.
+
+ Raises `TraceSummaryRetryableError`, leaving the entry `pending`, when a later attempt can still succeed.
+ An unexpected error is raised for Temporal to retry, and on the final attempt it writes `failed` instead."""
+ if not job_owns_entry(job):
+ return None
+ team = Team.objects.select_related("organization").get(pk=job.team_id)
+ run = _Run(job, team, User.objects.get(pk=job.requester_id))
+ try:
+ return _generate(run, final_attempt=final_attempt)
+ except TraceSummaryRetryableError:
+ raise
+ except Exception as error:
+ if not final_attempt:
+ raise
+ capture_exception(error, additional_properties={"team_id": job.team_id})
+ return run.failed("error")
+
+
+def _generate(run: _Run, *, final_attempt: bool) -> TraceSummaryRun:
+ job, team, requester = run.job, run.team, run.requester
+ if not team.organization.is_ai_data_processing_approved:
+ return run.withdrawn()
+ # The entry is keyed by the fingerprint the request saw, so content the requester can no longer read must not
+ # reach it.
+ if requester_fingerprint(team.pk, requester) != job.fingerprint:
+ return run.access_changed()
+ loaded = load_trace(team, requester, job.trace_id, job.timestamp_hint)
+ if not loaded.rows:
+ return run.failed("trace_not_found")
+ trace = Trace(job.trace_id, loaded.rows, loaded.person)
+ root = load_trace_root(team, requester, job.trace_id, trace.created_at)
+ step_ids = [event.id for event in trace.events if not event.is_trace_event and not event.is_annotation]
+ steps = load_trace_nodes(team, requester, job.trace_id, step_ids, trace.created_at)
+ # Each read applies the restrictions in force when it runs. A change during the reads could put content under
+ # an entry whose viewers may not read it.
+ if requester_fingerprint(team.pk, requester) != job.fingerprint:
+ return run.access_changed()
+ rendered = render_trace(trace, root.trace_event, steps, text_repr_budget())
+ try:
+ response = summarize(
+ rendered.text,
+ team.pk,
+ mode=SummarizationMode.MINIMAL,
+ user_id=requester.distinct_id,
+ flex=False,
+ final_attempt=final_attempt,
+ )
+ except (SummarizationFailedError, exceptions.ValidationError) as error:
+ failure = failure_of(error)
+ if failure.retryable and not final_attempt:
+ raise TraceSummaryRetryableError(failure.reason) from error
+ return run.failed(failure.reason, rendered)
+ return run.ready(
+ ReadySummary(
+ title=response.title,
+ bullets=summary_items([(b.text, b.line_refs) for b in response.summary_bullets], rendered.line_owners),
+ notes=summary_items([(n.text, n.line_refs) for n in response.interesting_notes], rendered.line_owners),
+ flow=response.flow_diagram,
+ model=_MODEL,
+ generated_at=timezone.now(),
+ ),
+ rendered,
+ )
diff --git a/products/ai_observability/backend/logic/traces/summary_store.py b/products/ai_observability/backend/logic/traces/summary_store.py
new file mode 100644
index 000000000000..45ff55895751
--- /dev/null
+++ b/products/ai_observability/backend/logic/traces/summary_store.py
@@ -0,0 +1,149 @@
+from collections.abc import Callable
+from datetime import datetime
+from typing import Annotated
+
+from django.core.cache import cache
+from django.utils import timezone
+
+from pydantic import Field, TypeAdapter, ValidationError
+
+from posthog.dataclasses import frozen
+from posthog.exceptions_capture import capture_exception
+from posthog.models import Team, User
+
+from products.access_control.backend.facade.api import get_restricted_properties_with_group_type_index_for_team
+from products.access_control.backend.facade.property_access import restriction_fingerprint
+
+from ...facade.contracts import TraceSummaryJob
+from .summary import (
+ FailedSummary,
+ PendingSummary,
+ SummaryEntry,
+ SummaryKey,
+ TraceSummaryNotFoundError,
+ plan_request,
+ require_ai_data_processing_approval,
+ ttl_for,
+)
+
+_ENTRY = TypeAdapter[SummaryEntry](Annotated[SummaryEntry, Field(discriminator="status")])
+
+
+def requester_fingerprint(team_id: int, user: User) -> str:
+ return restriction_fingerprint(get_restricted_properties_with_group_type_index_for_team(user=user, team_id=team_id))
+
+
+def summary_key(team: Team, user: User, trace_id: str) -> SummaryKey:
+ # Unlike the legacy summary key, an unrestricted user has a fingerprint too, so every key has one shape.
+ return SummaryKey(team_id=team.pk, trace_id=trace_id, fingerprint=requester_fingerprint(team.pk, user))
+
+
+def read_summary(key: SummaryKey) -> SummaryEntry | None:
+ value = cache.get(key.cache_key)
+ if not isinstance(value, str | bytes):
+ return None
+ try:
+ return _ENTRY.validate_json(value)
+ except ValidationError:
+ return None
+
+
+def _serialize(entry: SummaryEntry) -> str:
+ return _ENTRY.dump_json(entry).decode()
+
+
+def claim_summary(key: SummaryKey, entry: PendingSummary) -> bool:
+ return cache.add(key.cache_key, _serialize(entry), timeout=ttl_for(entry).total_seconds())
+
+
+def write_summary(key: SummaryKey, entry: SummaryEntry) -> None:
+ cache.set(key.cache_key, _serialize(entry), timeout=ttl_for(entry).total_seconds())
+
+
+def delete_summary(key: SummaryKey) -> None:
+ cache.delete(key.cache_key)
+
+
+def job_owns_entry(job: TraceSummaryJob) -> bool:
+ """Whether the job's entry is still the pending one it was started for. A result already written, a newer
+ request's entry, or an expired entry each mean the job has nothing left to do."""
+ entry = read_summary(SummaryKey.for_job(job))
+ return isinstance(entry, PendingSummary) and entry.requested_at == job.requested_at
+
+
+def fail_abandoned_summary(job: TraceSummaryJob) -> None:
+ """Mark the job's entry failed when the job ended without writing it, so it does not stay pending until it
+ expires. An entry a later request replaced is left alone."""
+ if job_owns_entry(job):
+ write_summary(SummaryKey.for_job(job), FailedSummary(reason="error", failed_at=timezone.now()))
+
+
+def viewer_summary(team: Team, user: User, trace_id: str) -> SummaryEntry:
+ """The summary this viewer may see. Raises `TraceSummaryNotFoundError` when there is none."""
+ require_ai_data_processing_approval(team.organization.is_ai_data_processing_approved)
+ entry = read_summary(summary_key(team, user, trace_id))
+ if entry is None:
+ raise TraceSummaryNotFoundError(trace_id)
+ return entry
+
+
+@frozen
+class _RequestEntry:
+ entry: SummaryEntry
+ written: bool
+
+
+def _entry_for_request(key: SummaryKey, regenerate: bool) -> _RequestEntry:
+ """The entry a request leaves behind: a ready summary to return, or the pending entry a job fills in."""
+ existing = read_summary(key)
+ plan = plan_request(existing, regenerate)
+ if existing is not None and plan in ("return", "attach"):
+ return _RequestEntry(entry=existing, written=False)
+ pending = PendingSummary(requested_at=timezone.now())
+ if plan == "claim":
+ if claim_summary(key, pending):
+ return _RequestEntry(entry=pending, written=True)
+ # Another request claimed the key first, so its entry decides this one.
+ winner = read_summary(key)
+ if winner is not None and plan_request(winner, regenerate) in ("return", "attach"):
+ return _RequestEntry(entry=winner, written=False)
+ write_summary(key, pending)
+ return _RequestEntry(entry=pending, written=True)
+
+
+def request_summary(
+ team: Team,
+ user: User,
+ trace_id: str,
+ timestamp_hint: datetime | None,
+ regenerate: bool,
+ start: Callable[[TraceSummaryJob], None],
+) -> SummaryEntry:
+ """Return a ready summary, or make sure a job is writing one and return its pending entry.
+
+ The entry is written before the job starts, so a fast job's result is never overwritten by `pending`."""
+ require_ai_data_processing_approval(team.organization.is_ai_data_processing_approved)
+ key = summary_key(team, user, trace_id)
+ request_entry = _entry_for_request(key, regenerate)
+ entry = request_entry.entry
+ if not isinstance(entry, PendingSummary):
+ return entry
+ job = TraceSummaryJob(
+ team_id=team.pk,
+ trace_id=trace_id,
+ timestamp_hint=timestamp_hint,
+ fingerprint=key.fingerprint,
+ requester_id=user.pk,
+ requested_at=entry.requested_at,
+ )
+ try:
+ start(job)
+ except Exception as error:
+ capture_exception(error, additional_properties={"team_id": team.pk})
+ # The job of a reused entry may still run and write its result, so only an entry this request wrote fails.
+ if not request_entry.written:
+ return entry
+ failed = FailedSummary(reason="error", failed_at=timezone.now())
+ write_summary(key, failed)
+ return failed
+ return entry
diff --git a/products/ai_observability/backend/logic/traces/summary_text.py b/products/ai_observability/backend/logic/traces/summary_text.py
new file mode 100644
index 000000000000..01513d8ef4e7
--- /dev/null
+++ b/products/ai_observability/backend/logic/traces/summary_text.py
@@ -0,0 +1,51 @@
+from collections.abc import Sequence
+from typing import Any
+
+from ...text_repr.formatters import FormatterOptions, TraceTextRepr, format_trace_text_repr_with_line_owners
+from .trace import Trace
+from .trace_queries import TraceNodeRow
+from .tree import TreeNode
+
+_TRACE_PROPERTIES = ("$ai_input_state", "$ai_output_state", "$ai_error")
+
+
+def render_trace(
+ trace: Trace, trace_event: TraceNodeRow | None, steps: Sequence[TraceNodeRow], budget: int
+) -> TraceTextRepr:
+ """The trace as the line-numbered text a summarization model reads, at most `budget` characters long.
+
+ `trace_event` is the trace's own `$ai_trace` event, when it has one, and `steps` hold the contents of its
+ nodes. A node without contents renders with its kind only."""
+ properties_by_id = {row.uuid: row.properties for row in steps}
+
+ def to_formatter_node(node: TreeNode) -> dict[str, Any]:
+ return {
+ "event": {
+ "id": node.event.id,
+ "event": node.event.row.event,
+ "properties": properties_by_id.get(node.event.id, {}),
+ "timestamp": node.event.row.timestamp.isoformat(),
+ },
+ "children": [to_formatter_node(child) for child in node.children],
+ }
+
+ trace_properties = trace_event.properties if trace_event is not None else {}
+ formatter_trace = {
+ "id": trace.id,
+ "properties": {
+ "$ai_trace_id": trace.id,
+ "$ai_span_name": trace.name,
+ "$ai_session_id": trace.session_id,
+ **{key: trace_properties[key] for key in _TRACE_PROPERTIES if trace_properties.get(key) is not None},
+ },
+ }
+ options: FormatterOptions = {
+ "include_line_numbers": True,
+ "truncated": False,
+ "include_markers": False,
+ "collapsed": False,
+ "max_length": budget,
+ }
+ return format_trace_text_repr_with_line_owners(
+ formatter_trace, [to_formatter_node(node) for node in trace.tree], options
+ )
diff --git a/products/ai_observability/backend/presentation/views.py b/products/ai_observability/backend/presentation/views.py
index 9ed9677e8865..db97ee0238b2 100644
--- a/products/ai_observability/backend/presentation/views.py
+++ b/products/ai_observability/backend/presentation/views.py
@@ -7,12 +7,18 @@ from drf_spectacular.utils import OpenApiParameter, OpenApiResponse
from rest_framework import serializers, status, viewsets
from rest_framework.decorators import action
from rest_framework.response import Response
+from rest_framework.throttling import BaseThrottle
from posthog.api.documentation import _FallbackSerializer
from posthog.api.mixins import ValidatedRequest, validated_request
from posthog.api.routing import TeamAndOrgViewSetMixin
from posthog.clickhouse.query_tagging import Feature, tag_queries
from posthog.models.user import User
+from posthog.rate_limit import (
+ AIObservabilitySummarizationBurstThrottle,
+ AIObservabilitySummarizationDailyThrottle,
+ AIObservabilitySummarizationSustainedThrottle,
+)
from ..facade import api, contracts
from .query_concurrency import query_concurrency_slots
@@ -44,11 +50,20 @@ NODE_ID_PARAMETER = OpenApiParameter(
description="The node id, sent as the unpadded base64url encoding of its UTF-8 bytes. The root node's id is the trace id.",
)
THROTTLED_RESPONSE = OpenApiResponse(description="Too many queries are running for the project or organization.")
+NOT_APPROVED_DETAIL = "AI data processing must be approved by your organization before using summaries."
+NOT_A_USER_DETAIL = "Summaries are only available to signed-in users and their personal API keys."
+
+
+class TraceSummaryRequestSerializer(serializers.Serializer):
+ regenerate = serializers.BooleanField(
+ default=False, help_text="Replace a ready summary with a new one. A pending summary is never replaced."
+ )
class TraceViewSet(TeamAndOrgViewSetMixin, viewsets.ViewSet):
scope_object = "llm_analytics"
- scope_object_read_actions = ["retrieve", "node", "evaluations"]
+ scope_object_read_actions = ["retrieve", "node", "evaluations", "summary"]
+ scope_object_write_actions = ["request_summary"]
# Traces are project-wide data, so a grant on a single llm_analytics object must not open them.
requires_resource_level_access = True
serializer_class = _FallbackSerializer
@@ -128,3 +143,84 @@ class TraceViewSet(TeamAndOrgViewSetMixin, viewsets.ViewSet):
return Response({"detail": "Malformed encoded trace id."}, status=status.HTTP_400_BAD_REQUEST)
results = self._read(request, lambda user, _hint: api.get_trace_evaluation_results(self.team, user, trace_id))
return Response(results.model_dump(mode="json", by_alias=True))
+
+ def get_throttles(self) -> list[BaseThrottle]:
+ # Shares the legacy summary endpoint's scopes, so a user has one summarization budget. Reads poll, so only
+ # requests spend it.
+ if self.action == "request_summary":
+ return [
+ *super().get_throttles(),
+ AIObservabilitySummarizationBurstThrottle(),
+ AIObservabilitySummarizationSustainedThrottle(),
+ AIObservabilitySummarizationDailyThrottle(),
+ ]
+ return super().get_throttles()
+
+ @validated_request(
+ parameters=[TRACE_ID_PARAMETER],
+ responses={
+ 200: OpenApiResponse(response=contracts.TraceSummary),
+ 400: OpenApiResponse(description="The encoded trace id is malformed."),
+ 403: OpenApiResponse(description="The organization has not approved AI data processing."),
+ 404: OpenApiResponse(description="No summary of this trace that this user may see."),
+ },
+ operation_id="ai_observability_traces_summary_retrieve",
+ )
+ @action(detail=True, methods=["GET"], url_path="summary")
+ def summary(self, request: ValidatedRequest, pk: str, **kwargs: Any) -> Response:
+ """The trace's AI summary: pending while it is written, then ready with links to its steps, or failed with the reason. A summary is kept for an hour and shown only to users whose property access matches the requester's."""
+ return self._summary_response(
+ request, pk, lambda user, trace_id: api.get_trace_summary(self.team, user, trace_id)
+ )
+
+ @validated_request(
+ request_serializer=TraceSummaryRequestSerializer,
+ query_serializer=TraceQuerySerializer,
+ parameters=[TRACE_ID_PARAMETER],
+ responses={
+ 200: OpenApiResponse(response=contracts.TraceSummary, description="A ready or failed summary."),
+ 202: OpenApiResponse(response=contracts.TraceSummary, description="The summary is being written."),
+ 400: OpenApiResponse(description="The timestamp hint or the encoded trace id is malformed."),
+ 403: OpenApiResponse(description="The organization has not approved AI data processing."),
+ 429: OpenApiResponse(description="Too many summaries requested."),
+ },
+ operation_id="ai_observability_traces_summary_create",
+ )
+ @summary.mapping.post
+ def request_summary(self, request: ValidatedRequest, pk: str, **kwargs: Any) -> Response:
+ """Request an AI summary of the trace. A ready summary is returned as is unless `regenerate` is set; otherwise a job starts writing one, or the request joins the job already writing it."""
+ return self._summary_response(
+ request,
+ pk,
+ lambda user, trace_id: api.request_trace_summary(
+ self.team,
+ user,
+ trace_id,
+ request.validated_query_data.get("timestamp_hint"),
+ regenerate=request.validated_data["regenerate"],
+ ),
+ pending_status=status.HTTP_202_ACCEPTED,
+ )
+
+ def _summary_response(
+ self,
+ request: ValidatedRequest,
+ pk: str,
+ call: Callable[[User, str], contracts.TraceSummary],
+ *,
+ pending_status: int = status.HTTP_200_OK,
+ ) -> Response:
+ try:
+ trace_id = decode_trace_id_segment(pk)
+ except MalformedTraceIdSegmentError:
+ return Response({"detail": "Malformed encoded trace id."}, status=status.HTTP_400_BAD_REQUEST)
+ if not isinstance(request.user, User):
+ return Response({"detail": NOT_A_USER_DETAIL}, status=status.HTTP_403_FORBIDDEN)
+ try:
+ summary = call(request.user, trace_id)
+ except api.AIDataProcessingNotApprovedError:
+ return Response({"detail": NOT_APPROVED_DETAIL}, status=status.HTTP_403_FORBIDDEN)
+ except api.TraceSummaryNotFoundError:
+ return Response({"detail": "No summary yet."}, status=status.HTTP_404_NOT_FOUND)
+ response_status = pending_status if summary.status == "pending" else status.HTTP_200_OK
+ return Response(summary.model_dump(mode="json", by_alias=True), status=response_status)
diff --git a/products/ai_observability/backend/temporal/__init__.py b/products/ai_observability/backend/temporal/__init__.py
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/products/ai_observability/backend/temporal/registry.py b/products/ai_observability/backend/temporal/registry.py
new file mode 100644
index 000000000000..27123a93e760
--- /dev/null
+++ b/products/ai_observability/backend/temporal/registry.py
@@ -0,0 +1,4 @@
+from .trace_summary import TraceSummaryWorkflow, fail_trace_summary_activity, generate_trace_summary_activity
+
+WORKFLOWS = [TraceSummaryWorkflow]
+ACTIVITIES = [generate_trace_summary_activity, fail_trace_summary_activity]
diff --git a/products/ai_observability/backend/temporal/trace_summary.py b/products/ai_observability/backend/temporal/trace_summary.py
new file mode 100644
index 000000000000..bf145d78b550
--- /dev/null
+++ b/products/ai_observability/backend/temporal/trace_summary.py
@@ -0,0 +1,87 @@
+from temporalio import activity, workflow
+from temporalio.common import RetryPolicy
+from temporalio.exceptions import ActivityError
+
+from posthog.temporal.common.base import PostHogWorkflow
+
+with workflow.unsafe.imports_passed_through():
+ from posthog.ph_client import ph_background_capture
+ from posthog.temporal.ai_observability.retries import is_last_attempt
+ from posthog.temporal.common.heartbeat import Heartbeater
+ from posthog.temporal.common.utils import on_asyncify_pool
+
+ from ..facade import api
+ from ..facade.contracts import TraceSummaryJob
+ from ..logic.traces.summary import (
+ ATTEMPT_DEADLINE,
+ FAIL_DEADLINE,
+ HEARTBEAT_TIMEOUT,
+ JOB_DEADLINE,
+ MAX_ATTEMPTS,
+ RETRY_BACKOFF,
+ RETRY_INITIAL_INTERVAL,
+ RETRY_MAX_INTERVAL,
+ )
+ from .trace_summary_client import TRACE_SUMMARY_WORKFLOW_NAME
+
+GENERATE_TRACE_SUMMARY_ACTIVITY_NAME = "ai-observability-generate-trace-summary"
+FAIL_TRACE_SUMMARY_ACTIVITY_NAME = "ai-observability-fail-trace-summary"
+
+
[email protected](name=GENERATE_TRACE_SUMMARY_ACTIVITY_NAME)
+async def generate_trace_summary_activity(job: TraceSummaryJob) -> None:
+ async with Heartbeater():
+ run = await on_asyncify_pool(api.generate_trace_summary)(job, final_attempt=is_last_attempt())
+ if run is None:
+ return
+ properties: dict[str, object] = {
+ "duration_ms": run.duration_ms,
+ "input_characters": run.input_characters,
+ "model": run.model,
+ "was_sampled": run.was_sampled,
+ }
+ if run.status == "failed":
+ properties["failure_reason"] = run.failure_reason
+ ph_background_capture()(
+ distinct_id=run.distinct_id,
+ event=f"llma trace view summary {'completed' if run.status == 'ready' else 'failed'}",
+ properties=properties,
+ groups=run.groups,
+ )
+
+
[email protected](name=FAIL_TRACE_SUMMARY_ACTIVITY_NAME)
+async def fail_trace_summary_activity(job: TraceSummaryJob) -> None:
+ await on_asyncify_pool(api.fail_trace_summary)(job)
+
+
[email protected](name=TRACE_SUMMARY_WORKFLOW_NAME)
+class TraceSummaryWorkflow(PostHogWorkflow):
+ inputs_cls = TraceSummaryJob
+
+ @workflow.run
+ async def run(self, job: TraceSummaryJob) -> None:
+ try:
+ await workflow.execute_activity(
+ generate_trace_summary_activity,
+ job,
+ start_to_close_timeout=ATTEMPT_DEADLINE,
+ schedule_to_close_timeout=JOB_DEADLINE,
+ heartbeat_timeout=HEARTBEAT_TIMEOUT,
+ retry_policy=RetryPolicy(
+ maximum_attempts=MAX_ATTEMPTS,
+ initial_interval=RETRY_INITIAL_INTERVAL,
+ backoff_coefficient=RETRY_BACKOFF,
+ maximum_interval=RETRY_MAX_INTERVAL,
+ ),
+ )
+ except ActivityError:
+ # The last attempt raised or timed out before writing a result, so the entry would stay pending.
+ await workflow.execute_activity(
+ fail_trace_summary_activity,
+ job,
+ start_to_close_timeout=FAIL_DEADLINE / 4,
+ schedule_to_close_timeout=FAIL_DEADLINE,
+ retry_policy=RetryPolicy(maximum_attempts=3),
+ )
+ raise
diff --git a/products/ai_observability/backend/temporal/trace_summary_client.py b/products/ai_observability/backend/temporal/trace_summary_client.py
new file mode 100644
index 000000000000..efb4bd28bdf5
--- /dev/null
+++ b/products/ai_observability/backend/temporal/trace_summary_client.py
@@ -0,0 +1,33 @@
+from django.conf import settings
+
+from asgiref.sync import async_to_sync
+from temporalio.client import Client
+from temporalio.common import RetryPolicy, WorkflowIDConflictPolicy
+
+from posthog.temporal.common.client import async_connect
+
+from ..facade.contracts import TraceSummaryJob
+from ..logic.traces.summary import WORKFLOW_DEADLINE, workflow_id
+
+TRACE_SUMMARY_WORKFLOW_NAME = "ai-observability-trace-summary"
+
+
+async def start_trace_summary_workflow(client: Client, job: TraceSummaryJob) -> str | None:
+ """Start the job's workflow, or attach to the run already writing this summary. Returns the run id."""
+ handle = await client.start_workflow(
+ TRACE_SUMMARY_WORKFLOW_NAME,
+ job,
+ id=workflow_id(job),
+ task_queue=settings.LLMA_TASK_QUEUE,
+ id_conflict_policy=WorkflowIDConflictPolicy.USE_EXISTING,
+ execution_timeout=WORKFLOW_DEADLINE,
+ retry_policy=RetryPolicy(maximum_attempts=1),
+ )
+ return handle.result_run_id
+
+
+def start_trace_summary(job: TraceSummaryJob) -> None:
+ async def start() -> None:
+ await start_trace_summary_workflow(await async_connect(), job)
+
+ async_to_sync(start)()
diff --git a/products/ai_observability/backend/tests/logic/traces/test_node_contents_queries.py b/products/ai_observability/backend/tests/logic/traces/test_node_contents_queries.py
new file mode 100644
index 000000000000..c95008bc7e00
--- /dev/null
+++ b/products/ai_observability/backend/tests/logic/traces/test_node_contents_queries.py
@@ -0,0 +1,75 @@
+from datetime import datetime
+
+from posthog.test.base import BaseTest, ClickhouseTestMixin
+
+from parameterized import parameterized
+
+from posthog.models import User
+from posthog.models.ai_events.test_util import bulk_create_ai_events
+from posthog.models.event.util import bulk_create_events
+
+from products.ai_observability.backend.logic.traces.node_contents_queries import load_trace_nodes
+
+from ...property_access import hide_event_property
+from .test_trace_queries import T0, TraceEventsMixin
+
+SPAN = "00000000-0000-0000-0000-000000000001"
+GENERATION = "00000000-0000-0000-0000-000000000002"
+TRACE_EVENT = "00000000-0000-0000-0000-000000000003"
+FEEDBACK = "00000000-0000-0000-0000-000000000004"
+OTHER_TRACE_SPAN = "00000000-0000-0000-0000-000000000005"
+QUESTION = [{"role": "user", "content": "Can I change my delivery address?"}]
+
+
+class TestLoadTraceNodes(TraceEventsMixin, ClickhouseTestMixin, BaseTest):
+ def _seed(self) -> None:
+ bulk_create_ai_events(
+ [
+ self._event(SPAN, properties={"$ai_span_name": "plan"}),
+ self._event(GENERATION, event="$ai_generation", properties={"$ai_input": QUESTION}),
+ self._event(TRACE_EVENT, event="$ai_trace"),
+ self._event(FEEDBACK, event="$ai_feedback"),
+ self._event(OTHER_TRACE_SPAN, trace_id="trace-2"),
+ ]
+ )
+
+ def test_reads_the_requested_steps_in_order_with_their_contents(self) -> None:
+ self._seed()
+
+ rows = load_trace_nodes(
+ self.team,
+ None,
+ "trace-1",
+ [GENERATION, TRACE_EVENT, FEEDBACK, OTHER_TRACE_SPAN, "not-a-uuid", SPAN.upper()],
+ None,
+ )
+
+ assert [row.uuid for row in rows] == [GENERATION, SPAN]
+ assert rows[0].properties["$ai_input"] == QUESTION
+
+ def test_restricted_input_is_masked_for_the_reader(self) -> None:
+ reader = User.objects.create_and_join(self.organization, "[email protected]", "testtest")
+ hide_event_property(self.team, reader, "$ai_input")
+ self._seed()
+
+ [owner_row] = load_trace_nodes(self.team, self.user, "trace-1", [GENERATION], None)
+ [reader_row] = load_trace_nodes(self.team, reader, "trace-1", [GENERATION], None)
+
+ assert owner_row.properties["$ai_input"] == QUESTION
+ assert "$ai_input" not in reader_row.properties
+
+ @parameterized.expand(
+ [
+ ("with a hint", [SPAN], T0, [SPAN]),
+ ("without a hint", [SPAN], None, []),
+ ("no ids", [], T0, []),
+ ]
+ )
+ def test_falls_back_to_events_only_with_a_hint(
+ self, _name: str, node_ids: list[str], timestamp_hint: datetime | None, expected: list[str]
+ ) -> None:
+ bulk_create_events([self._event(SPAN, properties={"$ai_span_name": "old"})])
+
+ rows = load_trace_nodes(self.team, None, "trace-1", node_ids, timestamp_hint)
+
+ assert [row.uuid for row in rows] == expected
diff --git a/products/ai_observability/backend/tests/logic/traces/test_summary.py b/products/ai_observability/backend/tests/logic/traces/test_summary.py
new file mode 100644
index 000000000000..a03fe7a86a67
--- /dev/null
+++ b/products/ai_observability/backend/tests/logic/traces/test_summary.py
@@ -0,0 +1,93 @@
+from datetime import UTC, datetime, timedelta
+
+from parameterized import parameterized
+
+from products.ai_observability.backend.facade.contracts import TraceSummaryJob
+from products.ai_observability.backend.logic.traces.summary import (
+ ATTEMPT_DEADLINE,
+ JOB_DEADLINE,
+ LLM_CALL_DEADLINE,
+ MAX_ATTEMPTS,
+ WORKFLOW_DEADLINE,
+ FailedSummary,
+ PendingSummary,
+ ReadySummary,
+ RequestPlan,
+ SummaryEntry,
+ SummaryItem,
+ SummaryKey,
+ plan_request,
+ summary_items,
+ ttl_for,
+ workflow_id,
+)
+
+T0 = datetime(2026, 9, 1, 10, 0, tzinfo=UTC)
+PENDING = PendingSummary(requested_at=T0)
+READY = ReadySummary(title="Refund request", bullets=(), notes=(), flow="ask → answer", model="m", generated_at=T0)
+FAILED = FailedSummary(reason="provider_error", failed_at=T0)
+
+
+ [
+ ("nothing stored", None, False, "claim"),
+ ("ready, no regenerate", READY, False, "return"),
+ ("ready, regenerate", READY, True, "replace"),
+ ("failed, retried without regenerate", FAILED, False, "replace"),
+ ("pending, regenerate", PENDING, True, "attach"),
+ ]
+)
+def test_plan_request(_name: str, existing: SummaryEntry | None, regenerate: bool, expected: RequestPlan) -> None:
+ assert plan_request(existing, regenerate) == expected
+
+
+def _job(
+ team_id: int = 1, trace_id: str = "trace-1", fingerprint: str = "a", requested_at: datetime = T0
+) -> TraceSummaryJob:
+ return TraceSummaryJob(
+ team_id=team_id,
+ trace_id=trace_id,
+ timestamp_hint=None,
+ fingerprint=fingerprint,
+ requester_id=7,
+ requested_at=requested_at,
+ )
+
+
+def test_keys_and_runs_differ_by_team_trace_fingerprint_and_request_and_stay_bounded() -> None:
+ jobs = [
+ _job(),
+ _job(team_id=2),
+ _job(trace_id="trace-2"),
+ _job(fingerprint="b"),
+ _job(requested_at=T0 + timedelta(seconds=1)),
+ ]
+ long_job = _job(trace_id="t" * 5000, fingerprint="a" * 64)
+
+ assert len({SummaryKey.for_job(job).cache_key for job in jobs}) == 4
+ assert len({workflow_id(job) for job in jobs}) == 5
+ assert workflow_id(_job()) == workflow_id(_job())
+ assert len(SummaryKey.for_job(long_job).cache_key) < 200 and len(workflow_id(long_job)) < 200
+
+
+ [
+ ("zero padded", "L045", "gen-b"),
+ ("unpadded", "L3", "gen-a"),
+ ("a header line", "L1", None),
+ ("past the end", "L999", None),
+ ("line zero", "L0", None),
+ ("no reference", "", None),
+ ]
+)
+def test_summary_items_link_each_line_to_its_step(_name: str, ref: str, node_id: str | None) -> None:
+ owners = [None, None, "gen-a", *["gen-b"] * 50]
+
+ assert summary_items([("text", ref)], owners) == (SummaryItem(text="text", node_id=node_id),)
+
+
+def test_a_lost_job_expires_before_it_can_be_requested_again() -> None:
+ assert ATTEMPT_DEADLINE > LLM_CALL_DEADLINE
+ assert JOB_DEADLINE >= MAX_ATTEMPTS * ATTEMPT_DEADLINE
+ assert WORKFLOW_DEADLINE > JOB_DEADLINE
+ assert ttl_for(PENDING) > WORKFLOW_DEADLINE
diff --git a/products/ai_observability/backend/tests/logic/traces/test_summary_generation.py b/products/ai_observability/backend/tests/logic/traces/test_summary_generation.py
new file mode 100644
index 000000000000..51512a6917a0
--- /dev/null
+++ b/products/ai_observability/backend/tests/logic/traces/test_summary_generation.py
@@ -0,0 +1,271 @@
+import re
+from datetime import timedelta
+from typing import Any
+
+import pytest
+from posthog.test.base import BaseTest, ClickhouseTestMixin
+from unittest.mock import MagicMock, patch
+
+import httpx
+import openai
+from parameterized import parameterized
+
+from posthog.models import User
+from posthog.models.ai_events.test_util import bulk_create_ai_events
+
+from products.ai_observability.backend.facade.contracts import TraceSummaryFailureReason, TraceSummaryJob
+from products.ai_observability.backend.logic.traces.node_contents_queries import (
+ load_trace_nodes as real_load_trace_nodes,
+)
+from products.ai_observability.backend.logic.traces.summary import (
+ FailedSummary,
+ PendingSummary,
+ ReadySummary,
+ SummaryItem,
+ SummaryKey,
+ TraceSummaryRetryableError,
+)
+from products.ai_observability.backend.logic.traces.summary_generation import generate_summary
+from products.ai_observability.backend.logic.traces.summary_store import (
+ delete_summary,
+ read_summary,
+ requester_fingerprint,
+ write_summary,
+)
+from products.ai_observability.backend.summarization.llm import summarize as real_summarize
+from products.ai_observability.backend.summarization.llm.schema import (
+ InterestingNote,
+ SummarizationResponse,
+ SummaryBullet,
+)
+
+from ...property_access import hide_event_property
+from .rows import T0
+
+SPAN = "00000000-0000-0000-0000-000000000001"
+GENERATION = "00000000-0000-0000-0000-000000000002"
+QUESTION = "How do I export my invoices as CSV?"
+PRIVATE_NOTE = "account manager notes: renewal at risk"
+REQUEST = httpx.Request("POST", "https://gateway.example.com/v1/chat/completions")
+
+
+def _status_error(status: int, code: str | None = None, message: str = "provider error") -> openai.APIStatusError:
+ return openai.APIStatusError(
+ message, response=httpx.Response(status, request=REQUEST), body={"code": code} if code else None
+ )
+
+
+READY = ReadySummary(title="Invoice export", bullets=(), notes=(), flow="ask → answer", model="m", generated_at=T0)
+
+
+def _response(bullet_ref: str) -> SummarizationResponse:
+ return SummarizationResponse(
+ title="Invoice export question",
+ flow_diagram="question → answer",
+ summary_bullets=[
+ SummaryBullet(text="The user asks about CSV exports.", line_refs=bullet_ref),
+ SummaryBullet(text="The answer points to settings.", line_refs=""),
+ ],
+ interesting_notes=[InterestingNote(text="No follow-up.", line_refs="")],
+ )
+
+
+class TestGenerateSummary(ClickhouseTestMixin, BaseTest):
+ def setUp(self) -> None:
+ super().setUp()
+ patcher = patch("products.ai_observability.backend.logic.traces.summary_generation.summarize")
+ self.summarize = patcher.start()
+ self.addCleanup(patcher.stop)
+ self.organization.is_ai_data_processing_approved = True
+ self.organization.save()
+ bulk_create_ai_events(
+ [
+ {
+ "event": "$ai_span",
+ "event_uuid": SPAN,
+ "distinct_id": "user-1",
+ "team": self.team,
+ "timestamp": T0,
+ "properties": {"$ai_trace_id": "trace-1", "$ai_span_id": "span-1", "$ai_span_name": "answer"},
+ },
+ {
+ "event": "$ai_generation",
+ "event_uuid": GENERATION,
+ "distinct_id": "user-1",
+ "team": self.team,
+ "timestamp": T0,
+ "properties": {
+ "$ai_trace_id": "trace-1",
+ "$ai_parent_id": "span-1",
+ "$ai_model": "gpt-4.1-mini",
+ "$ai_input": [
+ {"role": "user", "content": QUESTION},
+ {"role": "system", "content": PRIVATE_NOTE},
+ ],
+ },
+ },
+ ]
+ )
+
+ def _job(self, user: User | None = None, *, trace_id: str = "trace-1") -> TraceSummaryJob:
+ requester = user or self.user
+ job = TraceSummaryJob(
+ team_id=self.team.pk,
+ trace_id=trace_id,
+ timestamp_hint=T0,
+ fingerprint=requester_fingerprint(self.team.pk, requester),
+ requester_id=requester.pk,
+ requested_at=T0,
+ )
+ write_summary(SummaryKey.for_job(job), PendingSummary(requested_at=T0))
+ return job
+
+ def _provider_fails_with(self, error: Exception) -> None:
+ # The real summarization call runs against a client that fails, so the test sees the error as that call
+ # wraps it.
+ client = MagicMock()
+ client.chat.completions.create.side_effect = error
+ self.enterContext(
+ patch("products.ai_observability.backend.summarization.llm.openai.build_openai_client", return_value=client)
+ )
+ self.summarize.side_effect = real_summarize
+
+ def test_writes_a_ready_summary_with_step_links(self) -> None:
+ def answer(text_repr: str, *args: Any, **kwargs: Any) -> SummarizationResponse:
+ question_line = next(line for line in text_repr.split("\n") if QUESTION in line)
+ ref = re.match(r"L\d+", question_line)
+ assert ref is not None
+ return _response(ref.group(0))
+
+ self.summarize.side_effect = answer
+ job = self._job()
+
+ run = generate_summary(job, final_attempt=True)
+
+ entry = read_summary(SummaryKey.for_job(job))
+ assert isinstance(entry, ReadySummary)
+ assert [item.node_id for item in entry.bullets] == [GENERATION, None]
+ assert entry.notes == (SummaryItem(text="No follow-up.", node_id=None),)
+ assert run is not None and (run.status, run.input_characters) == (
+ "ready",
+ len(self.summarize.call_args.args[0]),
+ )
+
+ def test_restricted_content_never_reaches_the_model(self) -> None:
+ self.summarize.return_value = _response("")
+ hide_event_property(self.team, self.user, "$ai_input")
+
+ generate_summary(self._job(), final_attempt=True)
+
+ text_repr = self.summarize.call_args.args[0]
+ assert "answer" in text_repr and PRIVATE_NOTE not in text_repr
+
+ def test_a_missing_trace_fails_without_calling_the_model(self) -> None:
+ job = self._job(trace_id="trace-2")
+
+ run = generate_summary(job, final_attempt=True)
+
+ self.summarize.assert_not_called()
+ entry = read_summary(SummaryKey.for_job(job))
+ assert run is not None and isinstance(entry, FailedSummary)
+ assert (entry.reason, run.failure_reason) == ("trace_not_found", "trace_not_found")
+
+ @parameterized.expand([("before the reads", False), ("during the reads", True)])
+ def test_an_access_change_drops_the_entry_without_calling_the_model(self, _name: str, during_reads: bool) -> None:
+ job = self._job()
+ if not during_reads:
+ hide_event_property(self.team, self.user, "$ai_input")
+
+ def hide_input_then_read(*args: Any, **kwargs: Any) -> Any:
+ if during_reads:
+ hide_event_property(self.team, self.user, "$ai_input")
+ return real_load_trace_nodes(*args, **kwargs)
+
+ with patch(
+ "products.ai_observability.backend.logic.traces.summary_generation.load_trace_nodes",
+ side_effect=hide_input_then_read,
+ ):
+ run = generate_summary(job, final_attempt=True)
+
+ self.summarize.assert_not_called()
+ assert read_summary(SummaryKey.for_job(job)) is None
+ assert run is not None and (run.status, run.failure_reason) == ("failed", "access_changed")
+
+ @parameterized.expand(
+ [
+ ("a result written before a retry", READY),
+ ("a newer request's entry", PendingSummary(requested_at=T0 + timedelta(seconds=5))),
+ ("an expired entry", None),
+ ]
+ )
+ def test_a_job_whose_entry_no_longer_waits_for_it_does_nothing(
+ self, _name: str, entry: PendingSummary | ReadySummary | None
+ ) -> None:
+ job = self._job()
+ if entry is None:
+ delete_summary(SummaryKey.for_job(job))
+ else:
+ write_summary(SummaryKey.for_job(job), entry)
+
+ run = generate_summary(job, final_attempt=True)
+
+ self.summarize.assert_not_called()
+ assert run is None and read_summary(SummaryKey.for_job(job)) == entry
+
+ def test_withdrawn_approval_drops_the_entry_without_calling_the_model(self) -> None:
+ job = self._job()
+ self.organization.is_ai_data_processing_approved = False
+ self.organization.save()
+
+ run = generate_summary(job, final_attempt=True)
+
+ self.summarize.assert_not_called()
+ assert read_summary(SummaryKey.for_job(job)) is None
+ assert run is not None and (run.status, run.failure_reason) == ("failed", "not_approved")
+
+ @parameterized.expand(
+ [
+ ("a bad request fails at once", _status_error(400), False, "provider_error"),
+ ("too long for the model", _status_error(400, "context_length_exceeded"), False, "too_large"),
+ (
+ "too long, said only in the message",
+ _status_error(400, message="This model's maximum context length is 128000 tokens."),
+ False,
+ "too_large",
+ ),
+ ("an outage on the last attempt", _status_error(503), True, "provider_error"),
+ ("a timeout fails at once", openai.APITimeoutError(request=REQUEST), False, "timeout"),
+ ]
+ )
+ def test_provider_failures(
+ self,
+ _name: str,
+ error: Exception,
+ final_attempt: bool,
+ expected: TraceSummaryFailureReason,
+ ) -> None:
+ self._provider_fails_with(error)
+ job = self._job()
+
+ run = generate_summary(job, final_attempt=final_attempt)
+
+ entry = read_summary(SummaryKey.for_job(job))
+ assert run is not None and isinstance(entry, FailedSummary)
+ assert (entry.reason, run.status) == (expected, "failed")
+
+ @parameterized.expand(
+ [
+ ("an outage", 503),
+ ("a rate limit", 429),
+ ("a cancelled request", 499),
+ ("a server timeout", 408),
+ ("a conflict", 409),
+ ]
+ )
+ def test_a_transient_failure_with_a_retry_left_keeps_the_entry_pending(self, _name: str, status: int) -> None:
+ self._provider_fails_with(_status_error(status))
+ job = self._job()
+
+ with pytest.raises(TraceSummaryRetryableError):
+ generate_summary(job, final_attempt=False)
+ assert isinstance(read_summary(SummaryKey.for_job(job)), PendingSummary)
diff --git a/products/ai_observability/backend/tests/logic/traces/test_summary_store.py b/products/ai_observability/backend/tests/logic/traces/test_summary_store.py
new file mode 100644
index 000000000000..700e5d566d50
--- /dev/null
+++ b/products/ai_observability/backend/tests/logic/traces/test_summary_store.py
@@ -0,0 +1,91 @@
+import uuid
+from datetime import UTC, datetime, timedelta
+
+from django.core.cache import cache
+from django.test import SimpleTestCase
+
+from parameterized import parameterized
+
+from products.ai_observability.backend.facade.contracts import TraceSummaryJob
+from products.ai_observability.backend.logic.traces.summary import (
+ FailedSummary,
+ PendingSummary,
+ ReadySummary,
+ SummaryEntry,
+ SummaryItem,
+ SummaryKey,
+)
+from products.ai_observability.backend.logic.traces.summary_store import (
+ claim_summary,
+ fail_abandoned_summary,
+ read_summary,
+ write_summary,
+)
+
+T0 = datetime(2026, 9, 1, 10, 0, tzinfo=UTC)
+READY = ReadySummary(
+ title="Refund request",
+ bullets=(SummaryItem(text="The user asks for a refund.", node_id="gen-1"),),
+ notes=(SummaryItem(text="No order number given.", node_id=None),),
+ flow="ask → refuse",
+ model="gpt-4.1-mini",
+ generated_at=T0,
+)
+
+
+class TestSummaryStore(SimpleTestCase):
+ def setUp(self) -> None:
+ self.key = SummaryKey(team_id=1, trace_id=str(uuid.uuid4()), fingerprint="f")
+
+ def tearDown(self) -> None:
+ cache.delete(self.key.cache_key)
+
+ @parameterized.expand(
+ [
+ ("pending", PendingSummary(requested_at=T0)),
+ ("ready", READY),
+ ("failed", FailedSummary(reason="too_large", failed_at=T0)),
+ ]
+ )
+ def test_round_trips_each_entry(self, _name: str, entry: SummaryEntry) -> None:
+ write_summary(self.key, entry)
+
+ assert read_summary(self.key) == entry
+
+ @parameterized.expand([("not json", "not json"), ("an unknown status", '{"status": "archived"}'), ("a dict", {})])
+ def test_an_unreadable_value_reads_as_no_summary(self, _name: str, value: object) -> None:
+ cache.set(self.key.cache_key, value)
+
+ assert read_summary(self.key) is None
+
+ def test_claim_never_overwrites(self) -> None:
+ first = PendingSummary(requested_at=T0)
+
+ assert claim_summary(self.key, first)
+ assert not claim_summary(self.key, PendingSummary(requested_at=datetime(2026, 9, 2, tzinfo=UTC)))
+ assert read_summary(self.key) == first
+
+ @parameterized.expand(
+ [
+ ("the job's pending entry fails", PendingSummary(requested_at=T0), "failed"),
+ ("a newer request's entry stays", PendingSummary(requested_at=T0 + timedelta(seconds=5)), "pending"),
+ ("a written result stays", READY, "ready"),
+ ]
+ )
+ def test_an_abandoned_job_fails_only_its_own_pending_entry(
+ self, _name: str, entry: SummaryEntry, expected_status: str
+ ) -> None:
+ write_summary(self.key, entry)
+ job = TraceSummaryJob(
+ team_id=self.key.team_id,
+ trace_id=self.key.trace_id,
+ timestamp_hint=None,
+ fingerprint=self.key.fingerprint,
+ requester_id=7,
+ requested_at=T0,
+ )
+
+ fail_abandoned_summary(job)
+
+ stored = read_summary(self.key)
+ assert stored is not None and stored.status == expected_status
diff --git a/products/ai_observability/backend/tests/logic/traces/test_summary_text.py b/products/ai_observability/backend/tests/logic/traces/test_summary_text.py
new file mode 100644
index 000000000000..729c99c17a8e
--- /dev/null
+++ b/products/ai_observability/backend/tests/logic/traces/test_summary_text.py
@@ -0,0 +1,67 @@
+from typing import Any
+
+from products.ai_observability.backend.logic.traces.summary_text import render_trace
+from products.ai_observability.backend.logic.traces.trace import Trace
+from products.ai_observability.backend.logic.traces.trace_queries import TraceNodeRow
+
+from .rows import T0, make_row
+
+SPAN = "span-uuid"
+GENERATION = "gen-uuid"
+TRACE_EVENT = "trace-event-uuid"
+QUESTION = "Which plan includes priority support?"
+
+
+def _contents(uuid: str, event: str, properties: dict[str, Any]) -> TraceNodeRow:
+ return TraceNodeRow(uuid=uuid, event=event, timestamp=T0, properties=properties)
+
+
+def _owners_of(text: str, owners: tuple[str | None, ...], needle: str) -> set[str | None]:
+ return {owner for line, owner in zip(text.split("\n"), owners) if needle in line}
+
+
+def test_each_step_owns_its_rendered_lines() -> None:
+ trace = Trace(
+ "trace-1",
+ [
+ make_row(uuid=SPAN, span_id="span-1", span_name="router"),
+ make_row(uuid=GENERATION, event="$ai_generation", parent_id="span-1", model="gpt-4.1-mini"),
+ ],
+ None,
+ )
+ steps = [
+ _contents(SPAN, "$ai_span", {"$ai_span_name": "router"}),
+ _contents(GENERATION, "$ai_generation", {"$ai_input": [{"role": "user", "content": QUESTION}]}),
+ ]
+
+ rendered = render_trace(trace, None, steps, budget=100_000)
+
+ assert _owners_of(rendered.text, rendered.line_owners, QUESTION) == {GENERATION}
+ assert _owners_of(rendered.text, rendered.line_owners, "router") == {SPAN}
+ assert rendered.line_owners[0] is None
+
+
+def test_a_trace_without_steps_renders_its_state() -> None:
+ trace = Trace("trace-1", [make_row(uuid=TRACE_EVENT, event="$ai_trace", span_name="lookup")], None)
+ trace_event = _contents(
+ TRACE_EVENT,
+ "$ai_trace",
+ {"$ai_input_state": {"order": "A-1042"}, "$ai_output_state": {"status": "shipped"}},
+ )
+
+ rendered = render_trace(trace, trace_event, [], budget=100_000)
+
+ assert "A-1042" in rendered.text and "shipped" in rendered.text
+ assert set(rendered.line_owners) == {None}
+
+
+def test_the_budget_samples_the_text() -> None:
+ generations = [make_row(uuid=f"gen-{index}", event="$ai_generation") for index in range(100)]
+ steps = [
+ _contents(f"gen-{index}", "$ai_generation", {"$ai_input": [{"role": "user", "content": QUESTION}]})
+ for index in range(100)
+ ]
+
+ rendered = render_trace(Trace("trace-1", generations, None), None, steps, budget=2_000)
+
+ assert rendered.was_sampled and len(rendered.text) <= 2_000
diff --git a/products/ai_observability/backend/tests/property_access.py b/products/ai_observability/backend/tests/property_access.py
new file mode 100644
index 000000000000..d6ca2ac91939
--- /dev/null
+++ b/products/ai_observability/backend/tests/property_access.py
@@ -0,0 +1,21 @@
+from posthog.constants import AvailableFeature
+from posthog.models import Team, User
+
+from products.access_control.backend.facade.contracts import PropertyAccessLevel
+from products.access_control.backend.models.property_access_control import PropertyAccessControl
+from products.event_definitions.backend.models.property_definition import PropertyDefinition
+
+
+def hide_event_property(team: Team, user: User, name: str) -> None:
+ organization = team.organization
+ organization.available_product_features = [
+ {"key": AvailableFeature.PROPERTY_ACCESS_CONTROL, "name": AvailableFeature.PROPERTY_ACCESS_CONTROL}
+ ]
+ organization.save()
+ definition, _ = PropertyDefinition.objects.get_or_create(team=team, name=name, type=PropertyDefinition.Type.EVENT)
+ PropertyAccessControl.objects.create(
+ team=team,
+ property_definition=definition,
+ organization_member=user.organization_memberships.get(organization=organization),
+ access_level=PropertyAccessLevel.NONE.value,
+ )
diff --git a/products/ai_observability/backend/tests/temporal/__init__.py b/products/ai_observability/backend/tests/temporal/__init__.py
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/products/ai_observability/backend/tests/temporal/test_trace_summary.py b/products/ai_observability/backend/tests/temporal/test_trace_summary.py
new file mode 100644
index 000000000000..51b62d133039
--- /dev/null
+++ b/products/ai_observability/backend/tests/temporal/test_trace_summary.py
@@ -0,0 +1,147 @@
+import asyncio
+import logging
+from collections.abc import Iterator
+from datetime import UTC, datetime, timedelta
+
+import pytest
+from unittest.mock import MagicMock, patch
+
+from django.conf import settings
+
+from temporalio import activity
+from temporalio.client import WorkflowFailureError
+from temporalio.exceptions import ApplicationError
+from temporalio.testing import ActivityEnvironment, WorkflowEnvironment
+from temporalio.worker import UnsandboxedWorkflowRunner, Worker
+
+from products.ai_observability.backend.facade.contracts import TraceSummaryJob, TraceSummaryRun
+from products.ai_observability.backend.logic.traces.summary import TraceSummaryRetryableError, workflow_id
+from products.ai_observability.backend.temporal import trace_summary
+from products.ai_observability.backend.temporal.trace_summary import (
+ FAIL_TRACE_SUMMARY_ACTIVITY_NAME,
+ GENERATE_TRACE_SUMMARY_ACTIVITY_NAME,
+ TraceSummaryWorkflow,
+ generate_trace_summary_activity,
+)
+from products.ai_observability.backend.temporal.trace_summary_client import start_trace_summary_workflow
+
+JOB = TraceSummaryJob(
+ team_id=1,
+ trace_id="trace-1",
+ timestamp_hint=datetime(2026, 9, 1, 10, 0, tzinfo=UTC),
+ fingerprint="f",
+ requester_id=7,
+ requested_at=datetime(2026, 9, 1, 10, 5, tzinfo=UTC),
+)
+FAILED_RUN = TraceSummaryRun(
+ status="failed",
+ failure_reason="provider_error",
+ duration_ms=1200,
+ input_characters=5000,
+ model="gpt-4.1-mini",
+ was_sampled=False,
+ distinct_id="user-7",
+ groups={"organization": "org-1"},
+)
+
+
[email protected](autouse=True)
+def temporal_loggers_at_info() -> Iterator[None]:
+ # A logging call with fields the stdlib logger rejects raises only at INFO, and then wedges the workflow.
+ loggers = [logging.getLogger("temporalio.activity"), logging.getLogger("temporalio.workflow")]
+ levels = [logger.level for logger in loggers]
+ for logger in loggers:
+ logger.setLevel(logging.INFO)
+ yield
+ for logger, level in zip(loggers, levels):
+ logger.setLevel(level)
+
+
+async def test_two_requests_while_a_job_runs_share_one_run() -> None:
+ received: list[TraceSummaryJob] = []
+ release = asyncio.Event()
+
+ @activity.defn(name=GENERATE_TRACE_SUMMARY_ACTIVITY_NAME)
+ async def fake_generate(job: TraceSummaryJob) -> None:
+ received.append(job)
+ await release.wait()
+
+ @activity.defn(name=FAIL_TRACE_SUMMARY_ACTIVITY_NAME)
+ async def fake_fail(job: TraceSummaryJob) -> None:
+ raise AssertionError("a finished job must not be marked failed")
+
+ async with await WorkflowEnvironment.start_time_skipping() as env:
+ async with Worker(
+ env.client,
+ task_queue=settings.LLMA_TASK_QUEUE,
+ workflows=[TraceSummaryWorkflow],
+ activities=[fake_generate, fake_fail],
+ workflow_runner=UnsandboxedWorkflowRunner(),
+ ):
+ first = await start_trace_summary_workflow(env.client, JOB)
+ second = await start_trace_summary_workflow(env.client, JOB)
+ release.set()
+ await env.client.get_workflow_handle(workflow_id(JOB)).result()
+
+ assert first is not None and first == second
+ assert received == [JOB]
+
+
+async def test_a_job_that_ends_without_a_result_marks_its_summary_failed() -> None:
+ attempts: list[TraceSummaryJob] = []
+ abandoned: list[TraceSummaryJob] = []
+
+ @activity.defn(name=GENERATE_TRACE_SUMMARY_ACTIVITY_NAME)
+ async def broken_generate(job: TraceSummaryJob) -> None:
+ attempts.append(job)
+ raise ApplicationError("boom", type="TypeError")
+
+ @activity.defn(name=FAIL_TRACE_SUMMARY_ACTIVITY_NAME)
+ async def record_fail(job: TraceSummaryJob) -> None:
+ abandoned.append(job)
+
+ # The test server does not skip the backoff between activity attempts.
+ with patch.object(trace_summary, "RETRY_INITIAL_INTERVAL", timedelta(milliseconds=10)):
+ async with await WorkflowEnvironment.start_time_skipping() as env:
+ async with Worker(
+ env.client,
+ task_queue=settings.LLMA_TASK_QUEUE,
+ workflows=[TraceSummaryWorkflow],
+ activities=[broken_generate, record_fail],
+ workflow_runner=UnsandboxedWorkflowRunner(),
+ ):
+ await start_trace_summary_workflow(env.client, JOB)
+ with pytest.raises(WorkflowFailureError):
+ await env.client.get_workflow_handle(workflow_id(JOB)).result()
+
+ assert len(attempts) == 2
+ assert abandoned == [JOB]
+
+
+async def test_activity_reports_a_finished_run() -> None:
+ capture = MagicMock()
+ with (
+ patch.object(trace_summary.api, "generate_trace_summary", return_value=FAILED_RUN),
+ patch.object(trace_summary, "ph_background_capture", return_value=capture),
+ ):
+ await ActivityEnvironment().run(generate_trace_summary_activity, JOB)
+
+ capture.assert_called_once()
+ kwargs = capture.call_args.kwargs
+ assert (kwargs["event"], kwargs["distinct_id"]) == ("llma trace view summary failed", "user-7")
+ assert kwargs["groups"] == {"organization": "org-1"}
+ assert kwargs["properties"]["failure_reason"] == "provider_error"
+
+
+async def test_activity_leaves_a_retryable_failure_to_temporal() -> None:
+ capture = MagicMock()
+ with (
+ patch.object(
+ trace_summary.api, "generate_trace_summary", side_effect=TraceSummaryRetryableError("provider_error")
+ ),
+ patch.object(trace_summary, "ph_background_capture", return_value=capture),
+ pytest.raises(TraceSummaryRetryableError),
+ ):
+ await ActivityEnvironment().run(generate_trace_summary_activity, JOB)
+
+ capture.assert_not_called()
diff --git a/products/ai_observability/backend/tests/test_facade_api.py b/products/ai_observability/backend/tests/test_facade_api.py
index b1acf6266b39..3a3b97ccd4a0 100644
--- a/products/ai_observability/backend/tests/test_facade_api.py
+++ b/products/ai_observability/backend/tests/test_facade_api.py
@@ -8,18 +8,42 @@ from unittest.mock import patch
from parameterized import parameterized
from posthog.constants import AvailableFeature
-from posthog.models import Team
+from posthog.models import Team, User
from posthog.models.event.util import bulk_create_events
from products.access_control.backend.models.access_control import AccessControl
-from products.ai_observability.backend.facade import api
+from products.ai_observability.backend.facade import api, contracts
+from products.ai_observability.backend.logic.traces.summary import (
+ FailedSummary,
+ PendingSummary,
+ ReadySummary,
+ SummaryEntry,
+ SummaryItem,
+ SummaryKey,
+ workflow_id,
+)
+from products.ai_observability.backend.logic.traces.summary_store import (
+ delete_summary,
+ read_summary,
+ summary_key,
+ write_summary,
+)
from products.ai_observability.backend.logic.traces.trace_queries import LoadedTrace
from products.ai_observability.backend.models.evaluations import Evaluation
from products.event_definitions.backend.models.property_definition import PropertyDefinition
from .logic.traces.rows import make_evaluation_result_event, make_row
+from .property_access import hide_event_property
T0 = datetime(2026, 9, 1, 10, 0, tzinfo=UTC)
+READY_SUMMARY = ReadySummary(
+ title="Refund request",
+ bullets=(SummaryItem(text="The user asks for a refund.", node_id="gen-1"),),
+ notes=(),
+ flow="ask → refuse",
+ model="gpt-4.1-mini",
+ generated_at=T0,
+)
def test_root_node_is_the_trace_and_nodes_keep_event_uuids() -> None:
@@ -175,3 +199,94 @@ class TestGetTraceEvaluationResults(ClickhouseTestMixin, BaseTest):
assert len(results.results) == 2
assert (results.summary.passed, results.summary.failed, results.summary.unrated) == (0, 1, 0)
assert [(node.node_id, node.outcome) for node in results.summary.nodes] == [("trace-1", "fail")]
+
+
+class TestTraceSummary(BaseTest):
+ def setUp(self) -> None:
+ super().setUp()
+ self.organization.is_ai_data_processing_approved = True
+ self.organization.save()
+ self.jobs: list[contracts.TraceSummaryJob] = []
+ delete_summary(summary_key(self.team, self.user, "trace-1"))
+ patcher = patch.object(api, "start_trace_summary", side_effect=self.jobs.append)
+ self.start = patcher.start()
+ self.addCleanup(patcher.stop)
+
+ def _request(self, *, regenerate: bool = False) -> contracts.TraceSummary:
+ return api.request_trace_summary(self.team, self.user, "trace-1", T0, regenerate=regenerate)
+
+ def _stored(self) -> SummaryEntry | None:
+ return read_summary(summary_key(self.team, self.user, "trace-1"))
+
+ def _store(self, entry: SummaryEntry) -> None:
+ write_summary(summary_key(self.team, self.user, "trace-1"), entry)
+
+ def test_a_new_request_writes_pending_and_starts_one_job(self) -> None:
+ assert self._request().status == "pending"
+
+ [job] = self.jobs
+ assert (job.trace_id, job.timestamp_hint, job.requester_id) == ("trace-1", T0, self.user.pk)
+ assert SummaryKey.for_job(job) == summary_key(self.team, self.user, "trace-1")
+ stored = self._stored()
+ assert isinstance(stored, PendingSummary) and job.requested_at == stored.requested_at
+
+ def test_a_repeat_while_pending_keeps_the_entry_and_attaches(self) -> None:
+ self._request()
+ stored = self._stored()
+
+ assert self._request(regenerate=True).status == "pending"
+ assert self._stored() == stored
+ assert len(self.jobs) == 2 and len({workflow_id(job) for job in self.jobs}) == 1
+
+ @parameterized.expand([("kept", False, "ready", 0), ("regenerated", True, "pending", 1)])
+ def test_ready_is_returned_unless_regenerate(
+ self, _name: str, regenerate: bool, expected_status: str, expected_starts: int
+ ) -> None:
+ self._store(READY_SUMMARY)
+
+ assert self._request(regenerate=regenerate).status == expected_status
+ assert len(self.jobs) == expected_starts
+
+ def test_retry_after_a_failure_starts_again(self) -> None:
+ self._store(FailedSummary(reason="provider_error", failed_at=T0))
+
+ assert self._request().status == "pending"
+ assert len(self.jobs) == 1
+
+ def test_a_job_that_cannot_start_reads_as_failed(self) -> None:
+ self.start.side_effect = ConnectionError("temporal is down")
+
+ summary = self._request()
+
+ assert summary.failure is not None and (summary.status, summary.failure.reason) == ("failed", "error")
+ assert api.get_trace_summary(self.team, self.user, "trace-1").status == "failed"
+
+ def test_a_failed_start_while_joining_a_running_job_keeps_its_entry(self) -> None:
+ self._request()
+ running = self._stored()
+ self.start.side_effect = ConnectionError("temporal is down")
+
+ assert self._request().status == "pending"
+ assert self._stored() == running
+
+ def test_get_hides_another_fingerprint(self) -> None:
+ restricted = User.objects.create_and_join(self.organization, "[email protected]", "testtest")
+ hide_event_property(self.team, restricted, "$ai_input")
+ self._store(READY_SUMMARY)
+
+ with pytest.raises(api.TraceSummaryNotFoundError):
+ api.get_trace_summary(self.team, restricted, "trace-1")
+ summary = api.get_trace_summary(self.team, self.user, "trace-1")
+ assert summary.content is not None and summary.content.bullets[0].node_id == "gen-1"
+
+ def test_consent_withdrawn_hides_a_ready_entry(self) -> None:
+ self._store(READY_SUMMARY)
+ self.organization.is_ai_data_processing_approved = False
+ self.organization.save()
+ self.team.refresh_from_db()
+
+ with pytest.raises(api.AIDataProcessingNotApprovedError):
+ api.get_trace_summary(self.team, self.user, "trace-1")
+ with pytest.raises(api.AIDataProcessingNotApprovedError):
+ self._request(regenerate=True)
+ assert self.jobs == []
diff --git a/products/ai_observability/backend/tests/test_trace_views.py b/products/ai_observability/backend/tests/test_trace_views.py
index 1df634c22cbd..cd73af7546e2 100644
--- a/products/ai_observability/backend/tests/test_trace_views.py
+++ b/products/ai_observability/backend/tests/test_trace_views.py
@@ -1,5 +1,6 @@
import base64
from datetime import UTC, datetime, timedelta
+from urllib.parse import urlencode
from posthog.test.base import APIBaseTest, ClickhouseTestMixin
from unittest.mock import patch
@@ -18,6 +19,8 @@ from posthog.models.user import User
from products.access_control.backend.facade.contracts import PropertyAccessLevel
from products.access_control.backend.models.access_control import AccessControl
from products.access_control.backend.models.property_access_control import PropertyAccessControl
+from products.ai_observability.backend.logic.traces.summary import ReadySummary, SummaryItem
+from products.ai_observability.backend.logic.traces.summary_store import summary_key, write_summary
from products.ai_observability.backend.models.review_queues import ReviewQueue
from products.event_definitions.backend.models.property_definition import PropertyDefinition
@@ -362,3 +365,88 @@ class TestTraceViewSetResourceLevelAccess(ClickhouseTestMixin, APIBaseTest):
response = self.client.get(f"/api/projects/{self.team.id}/ai_observability/traces/{_encode('trace-1')}/")
assert response.status_code == 403, response.content
+
+
+READY_SUMMARY = ReadySummary(
+ title="Refund request",
+ bullets=(SummaryItem(text="The user asks for a refund.", node_id=GENERATION),),
+ notes=(),
+ flow="ask → refuse",
+ model="gpt-4.1-mini",
+ generated_at=T0,
+)
+
+
+class TestTraceSummaryViews(APIBaseTest):
+ def setUp(self) -> None:
+ super().setUp()
+ self.organization.is_ai_data_processing_approved = True
+ self.organization.save()
+ self.start = self.enterContext(
+ patch("products.ai_observability.backend.facade.api.start_trace_summary", return_value=None)
+ )
+
+ def _url(self, segment: str = _encode("trace-1")) -> str:
+ return f"/api/projects/{self.team.id}/ai_observability/traces/{segment}/summary/"
+
+ def _store_ready(self) -> None:
+ write_summary(summary_key(self.team, self.user, "trace-1"), READY_SUMMARY)
+
+ @parameterized.expand(
+ [
+ ("no summary", "none", _encode("trace-1"), 404),
+ ("a ready summary", "ready", _encode("trace-1"), 200),
+ ("an organization without approval", "unapproved", _encode("trace-1"), 403),
+ ("a malformed id", "ready", "A", 400),
+ ]
+ )
+ def test_get_maps_each_outcome(self, _name: str, setup: str, segment: str, expected_status: int) -> None:
+ if setup != "none":
+ self._store_ready()
+ if setup == "unapproved":
+ self.organization.is_ai_data_processing_approved = False
+ self.organization.save()
+
+ response = self.client.get(self._url(segment))
+
+ assert response.status_code == expected_status
+ if expected_status == 200:
+ body = response.json()
+ assert body["status"] == "ready" and body["content"]["generatedAt"] is not None
+ assert body["content"]["bullets"][0]["nodeId"] == GENERATION
+
+ def test_post_returns_202_while_pending_and_200_for_a_ready_summary(self) -> None:
+ pending = self.client.post(f"{self._url()}?{urlencode({'timestamp_hint': T0.isoformat()})}", {}, format="json")
+ self.start.assert_called_once()
+ write_summary(summary_key(self.team, self.user, "trace-1"), READY_SUMMARY)
+ ready = self.client.post(self._url(), {}, format="json")
+
+ assert (pending.status_code, pending.json()["status"]) == (202, "pending")
+ assert self.start.call_args.args[0].timestamp_hint == T0
+ assert (ready.status_code, ready.json()["status"]) == (200, "ready")
+
+ @parameterized.expand(
+ [
+ ("a read key reads", "llm_analytics:read", "get", 200),
+ ("a read key cannot request", "llm_analytics:read", "post", 403),
+ ("a write key requests", "llm_analytics:write", "post", 200),
+ ]
+ )
+ def test_scopes(self, _name: str, scope: str, method: str, expected_status: int) -> None:
+ self._store_ready()
+ key = self.create_personal_api_key_with_scopes([scope])
+ self.client.logout()
+
+ send = self.client.get if method == "get" else self.client.post
+ response = send(self._url(), headers={"authorization": f"Bearer {key}"})
+
+ assert response.status_code == expected_status
+
+ @patch("posthog.rate_limit.AIObservabilitySummarizationBurstThrottle.rate", new="1/minute")
+ @patch("posthog.rate_limit.is_rate_limit_enabled", return_value=True)
+ def test_only_requests_are_throttled(self, _rate_limit_enabled: object) -> None:
+ self._store_ready()
+
+ assert self.client.post(self._url(), {}, format="json").status_code == 200
+ assert self.client.post(self._url(), {}, format="json").status_code == 429
+ assert self.client.get(self._url()).status_code == 200
diff --git a/products/ai_observability/backend/text_repr/formatters/__init__.py b/products/ai_observability/backend/text_repr/formatters/__init__.py
index 78711e04f4b0..eb5753cd4866 100644
--- a/products/ai_observability/backend/text_repr/formatters/__init__.py
+++ b/products/ai_observability/backend/text_repr/formatters/__init__.py
@@ -11,6 +11,7 @@ Main entry points:
`posthog.ai_events` directly — accepts the dedicated-column shape and
handles JSON decoding of heavy columns.
- format_trace_text_repr: Format full traces with hierarchy
+- format_trace_text_repr_with_line_owners: Same, plus the event that rendered each line
- llm_trace_to_formatter_format: Convert LLMTrace to format_trace_text_repr input format
"""
@@ -24,16 +25,23 @@ from .message_formatter import (
sanitize_surrogates,
truncate_by_line_sampling,
)
-from .trace_formatter import format_trace_text_repr, llm_trace_to_formatter_format
+from .trace_formatter import (
+ TraceTextRepr,
+ format_trace_text_repr,
+ format_trace_text_repr_with_line_owners,
+ llm_trace_to_formatter_format,
+)
__all__ = [
"EVENT_TEXT_MAX_CHARS",
"FormatterOptions",
"RenderBudgetExceeded",
+ "TraceTextRepr",
"add_line_numbers",
"format_event_text_repr",
"format_event_text_repr_from_ai_events_row",
"format_trace_text_repr",
+ "format_trace_text_repr_with_line_owners",
"llm_trace_to_formatter_format",
"reduce_by_uniform_sampling",
"sanitize_surrogates",
diff --git a/products/ai_observability/backend/text_repr/formatters/test/test_trace_formatter.py b/products/ai_observability/backend/text_repr/formatters/test/test_trace_formatter.py
index 174de5850d8f..5d95845b9629 100644
--- a/products/ai_observability/backend/text_repr/formatters/test/test_trace_formatter.py
+++ b/products/ai_observability/backend/text_repr/formatters/test/test_trace_formatter.py
@@ -21,6 +21,7 @@ from ..trace_formatter import (
_get_event_summary,
_render_tree,
format_trace_text_repr,
+ format_trace_text_repr_with_line_owners,
llm_trace_to_formatter_format,
)
@@ -896,3 +897,80 @@ class TestSurrogateSafety:
assert text.encode("utf-8")
assert "\ud83c" not in text
+
+
+PLAIN_NUMBERED: FormatterOptions = {
+ "include_markers": False,
+ "truncated": False,
+ "collapsed": False,
+ "include_line_numbers": True,
+}
+NESTED_TRACE = {"properties": {"$ai_span_name": "support-bot", "$ai_error": {"message": "boom", "code": 7}}}
+NESTED_HIERARCHY = [
+ {
+ "event": {"id": "span-1", "event": "$ai_span", "properties": {"$ai_span_name": "retrieve"}},
+ "children": [
+ {
+ "event": {
+ "id": "gen-1",
+ "event": "$ai_generation",
+ "properties": {
+ "$ai_model": "gpt-4.1-mini",
+ "$ai_input": [{"role": "user", "content": "Where is my parcel?\nIt was due Monday."}],
+ "$ai_output_choices": [{"role": "assistant", "content": "It ships tomorrow."}],
+ },
+ },
+ "children": [],
+ }
+ ],
+ }
+]
+STATE_ONLY_TRACE = {"properties": {"$ai_span_name": "lookup", "$ai_input_state": {"order": 12}}}
+
+
+class TestLineOwners:
+ @parameterized.expand(
+ [
+ ("nested plain numbered", NESTED_TRACE, NESTED_HIERARCHY, PLAIN_NUMBERED),
+ ("nested with markers", NESTED_TRACE, NESTED_HIERARCHY, {"include_markers": True}),
+ ("collapsed", NESTED_TRACE, NESTED_HIERARCHY, {"collapsed": True}),
+ ("state only", STATE_ONLY_TRACE, [], PLAIN_NUMBERED),
+ ("default options", NESTED_TRACE, NESTED_HIERARCHY, None),
+ ]
+ )
+ def test_line_owner_variant_renders_the_same_text(
+ self, _name: str, trace: dict[str, Any], hierarchy: list[dict[str, Any]], options: FormatterOptions | None
+ ) -> None:
+ rendered = format_trace_text_repr_with_line_owners(trace, hierarchy, options)
+
+ assert (rendered.text, rendered.was_sampled) == format_trace_text_repr(trace, hierarchy, options)
+
+ def test_line_owners_follow_each_step_through_nesting_and_multiline_entries(self) -> None:
+ rendered = format_trace_text_repr_with_line_owners(NESTED_TRACE, NESTED_HIERARCHY, PLAIN_NUMBERED)
+ lines = rendered.text.split("\n")
+
+ def owners_of(marker: str) -> set[str | None]:
+ return {owner for line, owner in zip(lines, rendered.line_owners) if marker in line}
+
+ assert len(rendered.line_owners) == len(lines)
+ assert owners_of("[GEN]") == {"gen-1"}
+ assert owners_of("[SPAN]") == {"span-1"}
+ assert owners_of("It was due Monday.") == {"gen-1"}
+ assert owners_of('"code": 7') == {None}
+ assert rendered.line_owners[0] is None
+
+ def test_line_owners_survive_sampling(self) -> None:
+ hierarchy = [
+ {"event": {"id": f"gen-{index}", "event": "$ai_generation", "properties": {"$ai_model": "m"}}}
+ for index in range(200)
+ ]
+ full = format_trace_text_repr_with_line_owners(NESTED_TRACE, hierarchy, PLAIN_NUMBERED)
+ sampled = format_trace_text_repr_with_line_owners(
+ NESTED_TRACE, hierarchy, {**PLAIN_NUMBERED, "max_length": len(full.text) // 3}
+ )
+ kept = [line for line in sampled.text.split("\n") if line.startswith("L") and ":" in line]
+
+ assert sampled.was_sampled and sampled.line_owners == full.line_owners
+ for line in kept:
+ number = int(line[1 : line.index(":")])
+ assert full.text.split("\n")[number - 1] == line
diff --git a/products/ai_observability/backend/text_repr/formatters/trace_formatter.py b/products/ai_observability/backend/text_repr/formatters/trace_formatter.py
index 3b0047b40f0e..91db59a5fc36 100644
--- a/products/ai_observability/backend/text_repr/formatters/trace_formatter.py
+++ b/products/ai_observability/backend/text_repr/formatters/trace_formatter.py
@@ -437,17 +437,23 @@ def _render_tree(
prefix: str = "",
is_last: bool = True,
depth: int = 0,
+ owners: list[str | None] | None = None,
) -> list[str]:
"""Render tree structure with ASCII art.
Creates expandable nodes using:
- <<<GEN_EXPANDABLE|eventId|displayText|encodedContent>>> for include_markers=True
- Plain text [+] indicators for include_markers=False
+
+ When `owners` is given, one entry per returned line is appended to it: the id of the event whose node
+ rendered that line, or None for the max depth marker.
"""
lines = FormatterLines(options)
if depth > MAX_TREE_DEPTH:
lines.append(f"{prefix} [... max depth reached]")
+ if owners is not None:
+ owners.append(None)
return lines
options = options or {}
@@ -468,16 +474,31 @@ def _render_tree(
event, summary, prefix, current_prefix, child_prefix, options, collapsed, include_markers
)
lines.extend(node_lines)
+ if owners is not None:
+ owners.extend([event.get("id")] * len(node_lines))
if children:
child_lines = _render_tree(
- children, options=options, prefix=prefix + child_prefix, is_last=is_last_node, depth=depth + 1
+ children,
+ options=options,
+ prefix=prefix + child_prefix,
+ is_last=is_last_node,
+ depth=depth + 1,
+ owners=owners,
)
lines.extend(child_lines)
return lines
+@frozen
+class TraceTextRepr:
+ text: str
+ was_sampled: bool
+ # `line_owners[n - 1]` is the id of the event whose node rendered line `n`, or None for a trace-level line.
+ line_owners: tuple[str | None, ...]
+
+
def format_trace_text_repr(
trace: dict[str, Any], hierarchy: list[dict[str, Any]], options: FormatterOptions | None = None
) -> tuple[str, bool]:
@@ -501,6 +522,15 @@ def format_trace_text_repr(
Returns:
Tuple of (formatted_text, was_sampled) - the text representation and whether uniform sampling was applied
"""
+ rendered = format_trace_text_repr_with_line_owners(trace, hierarchy, options)
+ return rendered.text, rendered.was_sampled
+
+
+def format_trace_text_repr_with_line_owners(
+ trace: dict[str, Any], hierarchy: list[dict[str, Any]], options: FormatterOptions | None = None
+) -> TraceTextRepr:
+ """`format_trace_text_repr`, plus the event that owns each line. With `include_line_numbers`, sampling keeps
+ the original line numbers, so the owners stay valid for a sampled text."""
lines = FormatterLines(options)
props = trace.get("properties", {})
@@ -522,6 +552,7 @@ def format_trace_text_repr(
else:
lines.append(json.dumps(error, indent=2))
+ tree_owners: list[str | None] = []
# Only show trace-level input/output if there are NO events in hierarchy
# When events exist, the hierarchy tells the full story
if not hierarchy:
@@ -547,8 +578,13 @@ def format_trace_text_repr(
lines.append("")
lines.append("TRACE HIERARCHY:")
lines.append("")
- lines.extend(_render_tree(hierarchy, options=options))
+ lines.extend(_render_tree(hierarchy, options=options, owners=tree_owners))
+ # The tree renders last, so every entry before it is a trace-level line.
+ trace_level_owners: list[str | None] = [None] * (len(lines) - len(tree_owners))
+ entry_owners = trace_level_owners + tree_owners
+ # An entry can hold several lines, such as an error rendered as indented JSON.
+ line_owners = tuple(owner for entry, owner in zip(lines, entry_owners) for _ in range(entry.count("\n") + 1))
formatted_text = "\n".join(lines)
# Add line numbers if requested
@@ -564,4 +600,4 @@ def format_trace_text_repr(
if max_length and len(formatted_text) > max_length:
formatted_text, was_sampled = reduce_by_uniform_sampling(formatted_text, max_length)
- return sanitize_surrogates(formatted_text), was_sampled
+ return TraceTextRepr(text=sanitize_surrogates(formatted_text), was_sampled=was_sampled, line_owners=line_owners)
diff --git a/products/ai_observability/frontend/generated/api.schemas.ts b/products/ai_observability/frontend/generated/api.schemas.ts
index 90cf96fabb03..5b02e6e5f5be 100644
--- a/products/ai_observability/frontend/generated/api.schemas.ts
+++ b/products/ai_observability/frontend/generated/api.schemas.ts
@@ -1527,6 +1527,65 @@ export interface TraceNodeDetailApi {
event: TraceNodeEventApi | null
}
+export type TraceSummaryStatusEnumApi = (typeof TraceSummaryStatusEnumApi)[keyof typeof TraceSummaryStatusEnumApi]
+
+export const TraceSummaryStatusEnumApi = {
+ Pending: 'pending',
+ Ready: 'ready',
+ Failed: 'failed',
+} as const
+
+export interface TraceSummaryItemApi {
+ text: string
+ /** The step the item refers to, or null when it names none. */
+ nodeId: string | null
+}
+
+export interface TraceSummaryContentApi {
+ title: string
+ bullets: TraceSummaryItemApi[]
+ /** Details worth a second look, or empty. */
+ notes: TraceSummaryItemApi[]
+ /** The main steps of the trace as a small text diagram. */
+ flow: string
+ /** The model that wrote the summary. */
+ model: string
+ generatedAt: string
+}
+
+export type TraceSummaryFailureReasonEnumApi =
+ (typeof TraceSummaryFailureReasonEnumApi)[keyof typeof TraceSummaryFailureReasonEnumApi]
+
+export const TraceSummaryFailureReasonEnumApi = {
+ TraceNotFound: 'trace_not_found',
+ TooLarge: 'too_large',
+ Timeout: 'timeout',
+ ProviderError: 'provider_error',
+ NotApproved: 'not_approved',
+ AccessChanged: 'access_changed',
+ Error: 'error',
+} as const
+
+export interface TraceSummaryFailureApi {
+ reason: TraceSummaryFailureReasonEnumApi
+ /** Why the summary failed, ready to show to the user. */
+ message: string
+}
+
+export interface TraceSummaryApi {
+ /** `pending` while the summary is written, then `ready` or `failed`. */
+ status: TraceSummaryStatusEnumApi
+ /** The summary when `status` is `ready`, else null. */
+ content: TraceSummaryContentApi | null
+ /** Why it failed when `status` is `failed`, else null. */
+ failure: TraceSummaryFailureApi | null
+}
+
+export interface TraceSummaryRequestApi {
+ /** Replace a ready summary with a new one. A pending summary is never replaced. */
+ regenerate?: boolean
+}
+
export type DatasetJSONValueApi = { [key: string]: unknown } | unknown[] | string | number | boolean
/**
@@ -5519,6 +5578,13 @@ export type AiObservabilityTracesNodesRetrieveParams = {
timestamp_hint?: string
}
+export type AiObservabilityTracesSummaryCreateParams = {
+ /**
+ * When the trace happened, as carried by links into it. Lets a trace older than the AI events retention load from the shared events table.
+ */
+ timestamp_hint?: string
+}
+
export type DatasetItemsListParams = {
/**
* Return archived items instead of active items.
diff --git a/products/ai_observability/frontend/generated/api.ts b/products/ai_observability/frontend/generated/api.ts
index 7b368ad694a5..29d70a5d6436 100644
--- a/products/ai_observability/frontend/generated/api.ts
+++ b/products/ai_observability/frontend/generated/api.ts
@@ -18,6 +18,7 @@ import type {
AiObservabilityOfflineScorersHistoryListParams,
AiObservabilityTracesNodesRetrieveParams,
AiObservabilityTracesRetrieveParams,
+ AiObservabilityTracesSummaryCreateParams,
BatchCheckRequestApi,
BatchCheckResponseApi,
ClusteringConfigApi,
@@ -153,6 +154,8 @@ import type {
TraceNodeDetailApi,
TraceReviewApi,
TraceReviewCreateApi,
+ TraceSummaryApi,
+ TraceSummaryRequestApi,
TranslateRequestApi,
UploadReceiptApi,
UploadSubmissionApi,
@@ -738,6 +741,62 @@ export const aiObservabilityTracesNodesRetrieve = async (
})
}
+export const getAiObservabilityTracesSummaryRetrieveUrl = (projectId: string, id: string) => {
+ return `/api/projects/${projectId}/ai_observability/traces/${id}/summary/`
+}
+
+/**
+ * The trace's AI summary: pending while it is written, then ready with links to its steps, or failed with the reason. A summary is kept for an hour and shown only to users whose property access matches the requester's.
+ */
+export const aiObservabilityTracesSummaryRetrieve = async (
+ projectId: string,
+ id: string,
+ options?: RequestInit
+): Promise<TraceSummaryApi> => {
+ return apiMutator<TraceSummaryApi>(getAiObservabilityTracesSummaryRetrieveUrl(projectId, id), {
+ ...options,
+ method: 'GET',
+ })
+}
+
+export const getAiObservabilityTracesSummaryCreateUrl = (
+ projectId: string,
+ id: string,
+ params?: AiObservabilityTracesSummaryCreateParams
+) => {
+ 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}/ai_observability/traces/${id}/summary/?${stringifiedParams}`
+ : `/api/projects/${projectId}/ai_observability/traces/${id}/summary/`
+}
+
+/**
+ * Request an AI summary of the trace. A ready summary is returned as is unless `regenerate` is set; otherwise a job starts writing one, or the request joins the job already writing it.
+ */
+export const aiObservabilityTracesSummaryCreate = async (
+ projectId: string,
+ id: string,
+ traceSummaryRequestApi?: TraceSummaryRequestApi,
+ params?: AiObservabilityTracesSummaryCreateParams,
+ options?: RequestInit
+): Promise<TraceSummaryApi> => {
+ return apiMutator<TraceSummaryApi>(getAiObservabilityTracesSummaryCreateUrl(projectId, id, params), {
+ ...options,
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json', ...options?.headers },
+ body: JSON.stringify(traceSummaryRequestApi),
+ })
+}
+
export const getDatasetItemsListUrl = (projectId: string, params: DatasetItemsListParams) => {
const normalizedParams = new URLSearchParams()
diff --git a/products/ai_observability/frontend/generated/api.zod.ts b/products/ai_observability/frontend/generated/api.zod.ts
index fb765b094829..7f11e919e857 100644
--- a/products/ai_observability/frontend/generated/api.zod.ts
+++ b/products/ai_observability/frontend/generated/api.zod.ts
@@ -310,6 +310,18 @@ export const AiObservabilityOfflineExperimentsUploadCreateBody = /* @__PURE__ */
.describe('One to 1,000 unique item\/scorer-version results. The entire request commits atomically.'),
})
+/**
+ * Request an AI summary of the trace. A ready summary is returned as is unless `regenerate` is set; otherwise a job starts writing one, or the request joins the job already writing it.
+ */
+export const aiObservabilityTracesSummaryCreateBodyRegenerateDefault = false
+
+export const AiObservabilityTracesSummaryCreateBody = /* @__PURE__ */ zod.object({
+ regenerate: zod
+ .boolean()
+ .default(aiObservabilityTracesSummaryCreateBodyRegenerateDefault)
+ .describe('Replace a ready summary with a new one. A pending summary is never replaced.'),
+})
+
/**
* Create an item and its first immutable version. An identical client item ID retry returns the existing item. A different payload or an archived match returns a conflict.
*/
diff --git a/products/ai_observability/frontend/redesign/trace/TraceScene.tsx b/products/ai_observability/frontend/redesign/trace/TraceScene.tsx
index a84837623e22..ccd4973e7348 100644
--- a/products/ai_observability/frontend/redesign/trace/TraceScene.tsx
+++ b/products/ai_observability/frontend/redesign/trace/TraceScene.tsx
@@ -4,7 +4,7 @@ import { aiObservabilityTraceLogic } from '../../aiObservabilityTraceLogic'
import { SaveToDatasetButton } from '../../datasets/SaveToDatasetButton'
import { traceViewAdapterLogic, traceViewAdapterLogicValues } from './adapter/traceViewAdapterLogic'
import { TraceView, TraceViewProps, TraceViewReadyProps } from './components/TraceView'
-import { NodeDetailTab, TraceMode } from './types'
+import { NodeDetailTab, SummaryItemKind, TraceMode } from './types'
type ReadyValues = Pick<
traceViewAdapterLogicValues,
@@ -22,6 +22,10 @@ type ReadyValues = Pick<
| 'evalsChip'
| 'evalOutcomesByNode'
| 'gitBranch'
+ | 'summaryState'
+ | 'summaryRequesting'
+ | 'summaryRequestError'
+ | 'summaryConsentGiven'
>
interface ReadyActions {
@@ -32,6 +36,10 @@ interface ReadyActions {
viewInThread: () => void
prefetchNode: (id: string) => void
showFailingEvals: () => void
+ summarize: () => void
+ regenerateSummary: () => void
+ loadSummary: () => void
+ summaryStepClicked: (nodeId: string, kind: SummaryItemKind) => void
}
function toReadyProps(values: ReadyValues, actions: ReadyActions): TraceViewReadyProps | null {
@@ -64,6 +72,16 @@ function toReadyProps(values: ReadyValues, actions: ReadyActions): TraceViewRead
thread: values.thread,
timeline: values.timeline,
evalOutcomes: values.evalOutcomesByNode,
+ summaryMode: {
+ state: values.summaryState,
+ requesting: values.summaryRequesting,
+ requestError: values.summaryRequestError,
+ consentGiven: values.summaryConsentGiven,
+ onRequest: actions.summarize,
+ onRegenerate: actions.regenerateSummary,
+ onReload: actions.loadSummary,
+ onSelectStep: actions.summaryStepClicked,
+ },
}
}
@@ -89,6 +107,10 @@ export function TraceScene(): JSX.Element {
evalsChip,
evalOutcomesByNode,
gitBranch,
+ summaryState,
+ summaryRequesting,
+ summaryRequestError,
+ summaryConsentGiven,
} = useValues(logic)
const actions = useActions(logic)
@@ -110,6 +132,10 @@ export function TraceScene(): JSX.Element {
evalsChip,
evalOutcomesByNode,
gitBranch,
+ summaryState,
+ summaryRequesting,
+ summaryRequestError,
+ summaryConsentGiven,
},
actions
)
diff --git a/products/ai_observability/frontend/redesign/trace/adapter/traceSceneWiring.test.tsx b/products/ai_observability/frontend/redesign/trace/adapter/traceSceneWiring.test.tsx
index f621ec78e0b1..711daa8a0857 100644
--- a/products/ai_observability/frontend/redesign/trace/adapter/traceSceneWiring.test.tsx
+++ b/products/ai_observability/frontend/redesign/trace/adapter/traceSceneWiring.test.tsx
@@ -34,6 +34,7 @@ const TRACE_URL = '/api/projects/:team_id/ai_observability/traces/:id/'
const NODE_URL = '/api/projects/:team_id/ai_observability/traces/:id/nodes/:node_id/'
const EVALUATIONS_URL = '/api/projects/:team_id/ai_observability/traces/:id/evaluations/'
const DATASETS_URL = '/api/projects/:team_id/datasets/'
+const SUMMARY_URL = '/api/projects/:team_id/ai_observability/traces/:id/summary/'
const answeredGeneration = makeNodeDetail({
id: 'gen-2',
properties: {
@@ -115,6 +116,39 @@ describe('TraceScene', () => {
await waitFor(() => expect(nodeRequests).toContain('span-1'))
})
+ it('the Summary tab shows a stored summary whose step link opens that step in spans', async () => {
+ useMocks({
+ get: {
+ [SUMMARY_URL]: () => [
+ 200,
+ {
+ status: 'ready',
+ content: {
+ title: 'Invoice question answered',
+ bullets: [{ text: 'Context is retrieved first.', nodeId: 'span-1' }],
+ notes: [],
+ flow: 'retrieve → answer',
+ model: 'gpt-4.1-mini',
+ generatedAt: '2026-09-01T10:20:00Z',
+ },
+ failure: null,
+ },
+ ],
+ },
+ })
+ const { container, findByText } = renderNewView()
+
+ fireEvent.click(await findByText('Summary'))
+ expect(await findByText('Context is retrieved first.')).toBeTruthy()
+ fireEvent.click(await findByText('View step'))
+
+ await waitFor(() =>
+ expect(
+ container.querySelector('[data-attr="trace-view-tree-node"][aria-current="true"]')?.textContent
+ ).toContain('span-1')
+ )
+ })
+
it('opens the failing step on its Evals tab from the evals chip', async () => {
useMocks({
get: {
diff --git a/products/ai_observability/frontend/redesign/trace/adapter/traceViewAdapterLogic.test.ts b/products/ai_observability/frontend/redesign/trace/adapter/traceViewAdapterLogic.test.ts
index f5d73fd618e2..bdf77b89f1a3 100644
--- a/products/ai_observability/frontend/redesign/trace/adapter/traceViewAdapterLogic.test.ts
+++ b/products/ai_observability/frontend/redesign/trace/adapter/traceViewAdapterLogic.test.ts
@@ -11,6 +11,7 @@ import { initKeaTests } from '~/test/init'
import { aiObservabilityTraceLogic } from '../../../aiObservabilityTraceLogic'
import type { TraceApi, TraceEvaluationResultsApi } from '../../../generated/api.schemas'
+import { traceSummaryLogic } from '../traceSummaryLogic'
import { decodeIdSegment, makeEvaluationResults, makeNodeDetail, makeTraceResource } from './testFixtures'
import { traceViewAdapterLogic } from './traceViewAdapterLogic'
@@ -19,6 +20,7 @@ jest.mock('~/queries/query', () => ({ ...jest.requireActual('~/queries/query'),
const TRACE_URL = '/api/projects/:team_id/ai_observability/traces/:id/'
const NODE_URL = '/api/projects/:team_id/ai_observability/traces/:id/nodes/:node_id/'
const EVALUATIONS_URL = '/api/projects/:team_id/ai_observability/traces/:id/evaluations/'
+const SUMMARY_URL = '/api/projects/:team_id/ai_observability/traces/:id/summary/'
const answeredGeneration = makeNodeDetail({
id: 'gen-2',
@@ -35,6 +37,7 @@ describe('traceViewAdapterLogic', () => {
let traceGate: Promise<void>
let nodeRequests: string[]
let failingNodeId: string | null
+ let summaryRequests: number
let evaluations: TraceEvaluationResultsApi
function mountAt(params: Record<string, string> = {}): void {
@@ -48,9 +51,17 @@ describe('traceViewAdapterLogic', () => {
traceGate = Promise.resolve()
nodeRequests = []
failingNodeId = null
+ summaryRequests = 0
evaluations = makeEvaluationResults()
useMocks({
+ post: {
+ [SUMMARY_URL]: () => {
+ summaryRequests += 1
+ return [202, { status: 'pending', content: null, failure: null }]
+ },
+ },
get: {
+ [SUMMARY_URL]: () => [404, { detail: 'No summary yet.' }],
[TRACE_URL]: async () => {
await traceGate
return [200, traceResource]
@@ -251,4 +262,38 @@ describe('traceViewAdapterLogic', () => {
await expectLogic(logic, () => logic.actions.selectNode(nodeId)).toMatchValues({ canViewInThread: expected })
})
+
+ it('the Summary mode reads the summary on open, and a step link leaves it for that step in spans', async () => {
+ const capture = jest.spyOn(posthog, 'capture')
+ mountAt()
+ await expectLogic(logic).toFinishAllListeners()
+ const summary = traceSummaryLogic({ traceId: 'trace-1' })
+
+ logic.actions.setMode('summary')
+ await expectLogic(summary).toDispatchActions([summary.actionCreators.openSummary('tab'), 'loadSummarySuccess'])
+ await expectLogic(logic, () => logic.actions.summaryStepClicked('gen-1', 'bullet')).toMatchValues({
+ mode: 'spans',
+ selectedNodeId: 'gen-1',
+ })
+
+ await expectLogic(summary).toDispatchActions(['closeSummary']).toMatchValues({ isOpen: false })
+ expect(capture).toHaveBeenCalledWith('llma trace view summary step clicked', { kind: 'bullet' })
+ })
+
+ it('a trace-level summary link opens the Summary mode without requesting a summary', async () => {
+ mountAt({ tab: 'summary' })
+ const summary = traceSummaryLogic({ traceId: 'trace-1' })
+
+ await expectLogic(summary).toDispatchActions([summary.actionCreators.openSummary('link'), 'loadSummarySuccess'])
+
+ expect(logic.values).toMatchObject({ mode: 'summary', summaryState: { status: 'none' } })
+ expect(summaryRequests).toBe(0)
+ })
+
+ it('a summary link that names a step opens that step instead of the Summary mode', async () => {
+ mountAt({ tab: 'summary', event: 'gen-1' })
+
+ await expectLogic(logic).toFinishAllListeners().toMatchValues({ mode: 'spans', selectedNodeId: 'gen-1' })
+ expect(traceSummaryLogic({ traceId: 'trace-1' }).values.isOpen).toBe(false)
+ })
})
diff --git a/products/ai_observability/frontend/redesign/trace/adapter/traceViewAdapterLogic.ts b/products/ai_observability/frontend/redesign/trace/adapter/traceViewAdapterLogic.ts
index acd4e8703975..813905818b36 100644
--- a/products/ai_observability/frontend/redesign/trace/adapter/traceViewAdapterLogic.ts
+++ b/products/ai_observability/frontend/redesign/trace/adapter/traceViewAdapterLogic.ts
@@ -1,9 +1,11 @@
import { MakeLogicType, actions, connect, kea, key, listeners, path, props, reducers, selectors } from 'kea'
import { router } from 'kea-router'
import { subscriptions } from 'kea-subscriptions'
+import posthog from 'posthog-js'
import { FEATURE_FLAGS } from 'lib/constants'
import { FeatureFlagsSet, featureFlagLogic } from 'lib/logic/featureFlagLogic'
+import { aiConsentLogic } from 'scenes/settings/organization/aiConsentLogic'
import { teamLogic } from 'scenes/teamLogic'
import { aiObservabilityTraceLogic } from '../../../aiObservabilityTraceLogic'
@@ -17,6 +19,7 @@ import type {
import { GitBranchChipProps } from '../components/GitBranchChip'
import { TraceHeaderProps } from '../components/TraceHeader'
import { TraceSummaryBarProps } from '../components/TraceSummaryBar'
+import { traceSummaryLogic } from '../traceSummaryLogic'
import { TraceViewStatus, traceViewLogic } from '../traceViewLogic'
import {
ConversationState,
@@ -25,6 +28,9 @@ import {
LabeledLink,
NodeDetailTab,
NodeLoad,
+ SummaryItemKind,
+ SummaryModeState,
+ SummaryRequestError,
TraceMode,
} from '../types'
import { toDatasetItemSource } from './toDatasetItemSource'
@@ -41,6 +47,7 @@ export interface TraceViewAdapterLogicProps {
// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface traceViewAdapterLogicValues {
+ summaryConsentGiven: boolean // aiConsentLogic
eventId: string | null // aiObservabilityTraceLogic
initialTab: string | null // aiObservabilityTraceLogic
newerTimestamp: string | null // aiObservabilityTraceLogic
@@ -50,6 +57,9 @@ export interface traceViewAdapterLogicValues {
featureFlags: FeatureFlagsSet // featureFlagLogic
searchParams: Record<string, any> // router
currentTeamId: number | null // teamLogic
+ summaryRequestError: SummaryRequestError | null // traceSummaryLogic
+ summaryRequesting: boolean // traceSummaryLogic
+ summaryState: SummaryModeState // traceSummaryLogic
createdAt: string | null // traceViewLogic
defaultNodeId: string // traceViewLogic
errorMessage: string // traceViewLogic
@@ -99,6 +109,16 @@ export interface traceViewAdapterLogicActions {
setEventId: (eventId: string | null) => {
eventId: string | null
} // aiObservabilityTraceLogic
+ closeSummary: () => {
+ value: true
+ } // traceSummaryLogic
+ loadSummary: (_?: void | undefined) => void // traceSummaryLogic
+ openSummary: (openedFrom: import('../traceSummaryLogic').SummaryOpenedFrom) => {
+ openedFrom: import('../traceSummaryLogic').SummaryOpenedFrom
+ } // traceSummaryLogic
+ requestSummary: (
+ args_0: import('../traceSummaryLogic').SummaryRequest
+ ) => import('../traceSummaryLogic').SummaryRequest // traceSummaryLogic
loadNode: (
nodeId: string,
trigger: import('../types').NodeLoadTrigger
@@ -113,9 +133,15 @@ export interface traceViewAdapterLogicActions {
payload?: any
trace: TraceApi
} // traceViewLogic
+ openSummaryFromLink: () => {
+ value: true
+ }
prefetchNode: (id: string) => {
id: string
}
+ regenerateSummary: () => {
+ value: true
+ }
selectAndShowSpans: (id: string) => {
id: string
}
@@ -131,6 +157,16 @@ export interface traceViewAdapterLogicActions {
showFailingEvals: () => {
value: true
}
+ summarize: () => {
+ value: true
+ }
+ summaryStepClicked: (
+ nodeId: string,
+ kind: SummaryItemKind
+ ) => {
+ kind: SummaryItemKind
+ nodeId: string
+ }
viewInThread: () => {
value: true
}
@@ -238,12 +274,18 @@ export const traceViewAdapterLogic = kea<traceViewAdapterLogicType>([
['searchParams'],
featureFlagLogic,
['featureFlags'],
+ traceSummaryLogic({ traceId: props.traceId }),
+ ['state as summaryState', 'requesting as summaryRequesting', 'requestError as summaryRequestError'],
+ aiConsentLogic,
+ ['dataProcessingAccepted as summaryConsentGiven'],
],
actions: [
aiObservabilityTraceLogic,
['setEventId', 'loadNeighbors'],
traceViewLogic({ traceId: props.traceId, timestampHint: props.timestampHint }),
['loadNode', 'loadTraceSuccess'],
+ traceSummaryLogic({ traceId: props.traceId }),
+ ['openSummary', 'closeSummary', 'requestSummary', 'loadSummary'],
],
})),
actions({
@@ -254,6 +296,10 @@ export const traceViewAdapterLogic = kea<traceViewAdapterLogicType>([
viewInThread: true,
prefetchNode: (id: string) => ({ id }),
showFailingEvals: true,
+ openSummaryFromLink: true,
+ summarize: true,
+ regenerateSummary: true,
+ summaryStepClicked: (nodeId: string, kind: SummaryItemKind) => ({ nodeId, kind }),
}),
reducers({
mode: [
@@ -262,6 +308,7 @@ export const traceViewAdapterLogic = kea<traceViewAdapterLogicType>([
setMode: (_, { mode }) => mode,
selectAndShowSpans: () => 'spans',
viewInThread: () => 'thread',
+ openSummaryFromLink: () => 'summary',
},
],
detailTab: ['messages' as NodeDetailTab, { setDetailTab: (_, { tab }) => tab }],
@@ -414,7 +461,7 @@ export const traceViewAdapterLogic = kea<traceViewAdapterLogicType>([
selectedNodeId === traceId || threadNodeIds.includes(selectedNodeId),
],
}),
- listeners(({ actions, values, props }) => {
+ listeners(({ actions, values, selectors, props }) => {
// The click's read starts before the selection moves, so the selectedNodeId subscription's navigation read
// for the same id is deduped and the load event reports a click. Selecting the node that is already
// selected changes no value and the subscription does not fire, so this read also retries a failed node.
@@ -422,14 +469,44 @@ export const traceViewAdapterLogic = kea<traceViewAdapterLogicType>([
actions.loadNode(id, 'selection')
actions.setEventId(id)
}
+ const syncSummary = (previousMode: TraceMode): void => {
+ const wasOpen = previousMode === 'summary'
+ if (values.mode === 'summary' && !wasOpen) {
+ actions.openSummary('tab')
+ } else if (values.mode !== 'summary' && wasOpen) {
+ actions.closeSummary()
+ }
+ }
+ const requestSummary = (regenerate: boolean): void => {
+ actions.requestSummary({ regenerate, timestampHint: values.createdAt })
+ }
return {
+ setMode: (_, __, ___, previousState) => syncSummary(selectors.mode(previousState)),
+ viewInThread: (_, __, ___, previousState) => syncSummary(selectors.mode(previousState)),
selectNode: select,
- selectAndShowSpans: select,
+ selectAndShowSpans: (payload, __, ___, previousState) => {
+ select(payload)
+ syncSummary(selectors.mode(previousState))
+ },
prefetchNode: async ({ id }, breakpoint) => {
await breakpoint(PREFETCH_DELAY_MS)
actions.loadNode(id, 'prefetch')
},
- loadTraceSuccess: ({ trace }) => actions.loadNeighbors(props.traceId, trace.createdAt),
+ loadTraceSuccess: ({ trace }) => {
+ actions.loadNeighbors(props.traceId, trace.createdAt)
+ // Cluster and session pages link to a trace with tab=summary. The mode opens without generating.
+ // A link that also names a step opens that step, because the Summary mode covers the whole trace.
+ if (values.initialTab === 'summary' && values.mode !== 'summary' && !values.eventId) {
+ actions.openSummaryFromLink()
+ }
+ },
+ openSummaryFromLink: () => actions.openSummary('link'),
+ summarize: () => requestSummary(false),
+ regenerateSummary: () => requestSummary(true),
+ summaryStepClicked: ({ nodeId, kind }) => {
+ posthog.capture('llma trace view summary step clicked', { kind })
+ actions.selectAndShowSpans(nodeId)
+ },
showFailingEvals: () => {
actions.selectAndShowSpans(firstFailingNodeId(values.tree, values.evalOutcomesByNode) ?? props.traceId)
actions.setDetailTab('evals')
diff --git a/products/ai_observability/frontend/redesign/trace/components/SummarizeButton.tsx b/products/ai_observability/frontend/redesign/trace/components/SummarizeButton.tsx
new file mode 100644
index 000000000000..18fc573d1b2a
--- /dev/null
+++ b/products/ai_observability/frontend/redesign/trace/components/SummarizeButton.tsx
@@ -0,0 +1,62 @@
+import { useState } from 'react'
+
+import { LemonButton } from '@posthog/lemon-ui'
+
+import { AccessControlAction } from 'lib/components/AccessControlAction'
+import { AIConsentPopoverWrapper } from 'scenes/settings/organization/AIConsentPopoverWrapper'
+
+import { AccessControlLevel, AccessControlResourceType } from '~/types'
+
+export interface SummarizeButtonProps {
+ label: string
+ onClick: () => void
+ loading: boolean
+ consentGiven: boolean
+ dataAttr: string
+ type: 'primary' | 'secondary'
+}
+
+export function SummarizeButton({
+ label,
+ onClick,
+ loading,
+ consentGiven,
+ dataAttr,
+ type,
+}: SummarizeButtonProps): JSX.Element {
+ const [consentRequested, setConsentRequested] = useState(false)
+ const button = (
+ <AccessControlAction
+ resourceType={AccessControlResourceType.LlmAnalytics}
+ minAccessLevel={AccessControlLevel.Editor}
+ >
+ <LemonButton
+ type={type}
+ size="small"
+ onClick={consentGiven ? onClick : () => setConsentRequested(true)}
+ loading={loading}
+ data-attr={dataAttr}
+ >
+ {label}
+ </LemonButton>
+ </AccessControlAction>
+ )
+ if (consentGiven) {
+ return button
+ }
+ // The popover opens on click, also after an earlier dismissal, and runs the request once approval is given.
+ return (
+ <AIConsentPopoverWrapper
+ showArrow
+ ignoreDismissal
+ hidden={!consentRequested || loading}
+ onApprove={() => {
+ setConsentRequested(false)
+ onClick()
+ }}
+ onDismiss={() => setConsentRequested(false)}
+ >
+ {button}
+ </AIConsentPopoverWrapper>
+ )
+}
diff --git a/products/ai_observability/frontend/redesign/trace/components/SummaryContent.tsx b/products/ai_observability/frontend/redesign/trace/components/SummaryContent.tsx
new file mode 100644
index 000000000000..bbd5af01047a
--- /dev/null
+++ b/products/ai_observability/frontend/redesign/trace/components/SummaryContent.tsx
@@ -0,0 +1,84 @@
+import { useState } from 'react'
+
+import { IconArrowRight } from '@posthog/icons'
+import { LemonButton } from '@posthog/lemon-ui'
+
+import { TZLabel } from 'lib/components/TZLabel'
+
+import type { TraceSummaryContentApi, TraceSummaryItemApi } from '../../../generated/api.schemas'
+import type { SummaryItemKind } from '../types'
+
+export interface SummaryContentProps {
+ summary: TraceSummaryContentApi
+ onSelectStep: (nodeId: string, kind: SummaryItemKind) => void
+ actions: JSX.Element
+}
+
+interface SummaryItemListProps {
+ items: TraceSummaryItemApi[]
+ kind: SummaryItemKind
+ onSelectStep: (nodeId: string, kind: SummaryItemKind) => void
+}
+
+function SummaryItemList({ items, kind, onSelectStep }: SummaryItemListProps): JSX.Element {
+ return (
+ <ul className="m-0 flex list-disc flex-col gap-1.5 pl-5">
+ {items.map(({ text, nodeId }, index) => (
+ <li key={index} className="break-words">
+ <span>{text}</span>
+ {nodeId ? (
+ <LemonButton
+ size="xsmall"
+ type="tertiary"
+ className="ml-1 inline-flex align-middle"
+ sideIcon={<IconArrowRight />}
+ onClick={() => onSelectStep(nodeId, kind)}
+ data-attr="trace-view-summary-step-link"
+ >
+ View step
+ </LemonButton>
+ ) : null}
+ </li>
+ ))}
+ </ul>
+ )
+}
+
+export function SummaryContent({ summary, onSelectStep, actions }: SummaryContentProps): JSX.Element {
+ const [flowShown, setFlowShown] = useState(false)
+ return (
+ <div className="flex flex-col gap-4">
+ <div className="flex flex-wrap items-start justify-between gap-2">
+ <h3 className="m-0 min-w-0 break-words text-base font-semibold">{summary.title}</h3>
+ <div className="flex flex-wrap items-center gap-2">
+ <span className="text-xs text-secondary">
+ Generated <TZLabel time={summary.generatedAt} />
+ </span>
+ {actions}
+ </div>
+ </div>
+ <SummaryItemList items={summary.bullets} kind="bullet" onSelectStep={onSelectStep} />
+ {summary.notes.length > 0 ? (
+ <div className="flex flex-col gap-1.5">
+ <h4 className="m-0 text-sm font-semibold">Notes</h4>
+ <SummaryItemList items={summary.notes} kind="note" onSelectStep={onSelectStep} />
+ </div>
+ ) : null}
+ <div className="flex flex-col items-start gap-1.5">
+ <LemonButton
+ size="xsmall"
+ type="secondary"
+ onClick={() => setFlowShown(!flowShown)}
+ data-attr="trace-view-summary-flow-toggle"
+ >
+ {flowShown ? 'Hide flow' : 'Show flow'}
+ </LemonButton>
+ {flowShown ? (
+ <pre className="m-0 max-w-full overflow-x-auto rounded border border-primary bg-surface-primary p-3 text-xs">
+ {summary.flow}
+ </pre>
+ ) : null}
+ </div>
+ </div>
+ )
+}
diff --git a/products/ai_observability/frontend/redesign/trace/components/SummaryModeView.stories.tsx b/products/ai_observability/frontend/redesign/trace/components/SummaryModeView.stories.tsx
new file mode 100644
index 000000000000..d2ffeebdfe43
--- /dev/null
+++ b/products/ai_observability/frontend/redesign/trace/components/SummaryModeView.stories.tsx
@@ -0,0 +1,52 @@
+import type { Meta, StoryObj } from '@storybook/react'
+
+import { FIXTURE_SUMMARY, withWidth } from '../storyFixtures'
+import { SummaryModeView } from './SummaryModeView'
+
+const meta: Meta<typeof SummaryModeView> = {
+ title: 'Scenes-App/AI observability/Trace view/Summary mode',
+ component: SummaryModeView,
+ args: {
+ requesting: false,
+ requestError: null,
+ consentGiven: true,
+ onRequest: () => {},
+ onRegenerate: () => {},
+ onReload: () => {},
+ onSelectStep: () => {},
+ },
+ decorators: [withWidth(900)],
+ parameters: { mockDate: '2026-09-01T10:45:00Z' },
+}
+export default meta
+
+type Story = StoryObj<typeof SummaryModeView>
+
+export const NoSummary: Story = { args: { state: { status: 'none' } } }
+export const NoSummaryWithoutConsent: Story = { args: { state: { status: 'none' }, consentGiven: false } }
+export const Pending: Story = {
+ args: { state: { status: 'pending' } },
+ parameters: { testOptions: { waitForLoadersToDisappear: false } },
+}
+export const Ready: Story = { args: { state: { status: 'ready', summary: FIXTURE_SUMMARY } } }
+export const ReadyNarrow: Story = {
+ args: { state: { status: 'ready', summary: FIXTURE_SUMMARY } },
+ decorators: [withWidth(520)],
+}
+export const RegenerateThrottled: Story = {
+ args: { state: { status: 'ready', summary: FIXTURE_SUMMARY }, requestError: 'throttled' },
+}
+export const Failed: Story = {
+ args: {
+ state: {
+ status: 'failed',
+ message: 'The model provider returned an error. Try again in a few minutes.',
+ retryable: true,
+ },
+ },
+}
+export const LoadError: Story = { args: { state: { status: 'error' } } }
+export const Loading: Story = {
+ args: { state: { status: 'loading' } },
+ parameters: { testOptions: { waitForLoadersToDisappear: false } },
+}
diff --git a/products/ai_observability/frontend/redesign/trace/components/SummaryModeView.tsx b/products/ai_observability/frontend/redesign/trace/components/SummaryModeView.tsx
new file mode 100644
index 000000000000..0a7b1dbb8435
--- /dev/null
+++ b/products/ai_observability/frontend/redesign/trace/components/SummaryModeView.tsx
@@ -0,0 +1,114 @@
+import { LemonBanner, LemonSkeleton, Spinner } from '@posthog/lemon-ui'
+
+import type { SummaryItemKind, SummaryModeState, SummaryRequestError } from '../types'
+import { SummarizeButton } from './SummarizeButton'
+import { SummaryContent } from './SummaryContent'
+
+export interface SummaryModeViewProps {
+ state: SummaryModeState
+ requesting: boolean
+ requestError: SummaryRequestError | null
+ consentGiven: boolean
+ onRequest: () => void
+ onRegenerate: () => void
+ onReload: () => void
+ onSelectStep: (nodeId: string, kind: SummaryItemKind) => void
+}
+
+const REQUEST_ERROR_MESSAGES: Record<SummaryRequestError, string> = {
+ throttled: "You've reached the limit for summaries. Try again later.",
+ failed: "We couldn't start the summary. Try again.",
+}
+
+export function SummaryModeView({
+ state,
+ requesting,
+ requestError,
+ consentGiven,
+ onRequest,
+ onRegenerate,
+ onReload,
+ onSelectStep,
+}: SummaryModeViewProps): JSX.Element {
+ const requestErrorBanner = requestError ? (
+ <LemonBanner type="error" className="w-full">
+ {REQUEST_ERROR_MESSAGES[requestError]}
+ </LemonBanner>
+ ) : null
+ switch (state.status) {
+ case 'loading':
+ return <LemonSkeleton repeat={4} className="h-5" />
+ case 'error':
+ return (
+ <LemonBanner
+ type="error"
+ action={{ children: 'Retry', onClick: onReload, 'data-attr': 'trace-view-summary-reload' }}
+ >
+ We couldn't load the summary.
+ </LemonBanner>
+ )
+ case 'none':
+ return (
+ <div className="flex flex-col items-start gap-3">
+ <p className="m-0 text-secondary">
+ Get a short summary of this trace, with links to the steps it mentions.
+ </p>
+ {requestErrorBanner}
+ <SummarizeButton
+ label="Summarize"
+ type="primary"
+ onClick={onRequest}
+ loading={requesting}
+ consentGiven={consentGiven}
+ dataAttr="trace-view-summarize"
+ />
+ </div>
+ )
+ case 'pending':
+ return (
+ <div className="flex items-center gap-2 text-secondary">
+ <Spinner />
+ <span>Summarizing this trace. This can take a minute.</span>
+ </div>
+ )
+ case 'failed':
+ return (
+ <div className="flex flex-col items-start gap-3">
+ <LemonBanner type="error" className="w-full">
+ {state.message}
+ </LemonBanner>
+ {requestErrorBanner}
+ {state.retryable && (
+ <SummarizeButton
+ label="Retry"
+ type="secondary"
+ onClick={onRequest}
+ loading={requesting}
+ consentGiven={consentGiven}
+ dataAttr="trace-view-summary-retry"
+ />
+ )}
+ </div>
+ )
+ case 'ready':
+ return (
+ <div className="flex flex-col gap-3">
+ {requestErrorBanner}
+ <SummaryContent
+ summary={state.summary}
+ onSelectStep={onSelectStep}
+ actions={
+ <SummarizeButton
+ label="Regenerate"
+ type="secondary"
+ onClick={onRegenerate}
+ loading={requesting}
+ consentGiven={consentGiven}
+ dataAttr="trace-view-summary-regenerate"
+ />
+ }
+ />
+ </div>
+ )
+ }
+}
diff --git a/products/ai_observability/frontend/redesign/trace/components/TraceModeTabs.tsx b/products/ai_observability/frontend/redesign/trace/components/TraceModeTabs.tsx
index e72c95152b83..5bf1dcf68c9b 100644
--- a/products/ai_observability/frontend/redesign/trace/components/TraceModeTabs.tsx
+++ b/products/ai_observability/frontend/redesign/trace/components/TraceModeTabs.tsx
@@ -17,6 +17,7 @@ export function TraceModeTabs({ mode, onModeChange }: TraceModeTabsProps): JSX.E
{ key: 'spans', label: 'Spans', 'data-attr': 'trace-view-mode-spans' },
{ key: 'thread', label: 'Thread', 'data-attr': 'trace-view-mode-thread' },
{ key: 'timeline', label: 'Timeline', 'data-attr': 'trace-view-mode-timeline' },
+ { key: 'summary', label: 'Summary', 'data-attr': 'trace-view-mode-summary' },
]}
/>
)
diff --git a/products/ai_observability/frontend/redesign/trace/components/TraceView.stories.tsx b/products/ai_observability/frontend/redesign/trace/components/TraceView.stories.tsx
index a09126a1e39c..f69627cd0b23 100644
--- a/products/ai_observability/frontend/redesign/trace/components/TraceView.stories.tsx
+++ b/products/ai_observability/frontend/redesign/trace/components/TraceView.stories.tsx
@@ -7,7 +7,7 @@ import { claudeCodePluginSession } from '../sampleFixtures/claudeCodePluginSessi
import { langchainCerebrasImageError } from '../sampleFixtures/langchainCerebrasImageError'
import { openaiAgentsWithEvals } from '../sampleFixtures/openaiAgentsWithEvals'
import { SampleTraceFixture } from '../sampleFixtures/sampleTraceFixture'
-import { FIXTURE_EVAL_OUTCOMES, FIXTURE_EVALS_CHIP, FIXTURE_TRACE, withWidth } from '../storyFixtures'
+import { FIXTURE_EVAL_OUTCOMES, FIXTURE_EVALS_CHIP, FIXTURE_SUMMARY, FIXTURE_TRACE, withWidth } from '../storyFixtures'
import { EvalRollupOutcome, EvalsChipData, NodeDetailTab, TraceMode } from '../types'
import { TraceView } from './TraceView'
@@ -87,6 +87,16 @@ function Playground({ fixture, initialMode, initialNodeId, evals, evalOutcomes =
thread={fixture.thread}
timeline={fixture.timeline}
evalOutcomes={evalOutcomes}
+ summaryMode={{
+ state: { status: 'ready', summary: FIXTURE_SUMMARY },
+ requesting: false,
+ requestError: null,
+ consentGiven: true,
+ onRequest: () => {},
+ onRegenerate: () => {},
+ onReload: () => {},
+ onSelectStep: selectAndShowSpans,
+ }}
/>
)
}
diff --git a/products/ai_observability/frontend/redesign/trace/components/TraceView.tsx b/products/ai_observability/frontend/redesign/trace/components/TraceView.tsx
index 61947a6592a7..911c9c2e413a 100644
--- a/products/ai_observability/frontend/redesign/trace/components/TraceView.tsx
+++ b/products/ai_observability/frontend/redesign/trace/components/TraceView.tsx
@@ -1,6 +1,7 @@
import type { TraceNodeApi, TraceTimelineRowApi } from '../../../generated/api.schemas'
import { ConversationState, EvalRollupOutcome, LabeledLink, TraceMode } from '../types'
import { NodeDetailProps } from './NodeDetail'
+import { SummaryModeView, SummaryModeViewProps } from './SummaryModeView'
import { Thread } from './Thread'
import { TraceHeader, TraceHeaderProps } from './TraceHeader'
import { TraceModeTabs } from './TraceModeTabs'
@@ -24,6 +25,7 @@ export interface TraceViewReadyProps {
thread: ConversationState
timeline: { rows: TraceTimelineRowApi[]; totalMs: number }
evalOutcomes: Record<string, EvalRollupOutcome>
+ summaryMode: SummaryModeViewProps
}
export type TraceViewProps =
@@ -54,6 +56,8 @@ export function TraceView(props: TraceViewProps): JSX.Element {
/>
) : props.mode === 'thread' ? (
<Thread conversation={props.thread} onSelectMessage={props.onSelectFromView} />
+ ) : props.mode === 'summary' ? (
+ <SummaryModeView {...props.summaryMode} />
) : (
<TraceTimeline
rows={props.timeline.rows}
diff --git a/products/ai_observability/frontend/redesign/trace/storyFixtures.tsx b/products/ai_observability/frontend/redesign/trace/storyFixtures.tsx
index 139e568cea4f..28f30e74440e 100644
--- a/products/ai_observability/frontend/redesign/trace/storyFixtures.tsx
+++ b/products/ai_observability/frontend/redesign/trace/storyFixtures.tsx
@@ -1,6 +1,11 @@
import type { Decorator } from '@storybook/react'
-import type { TraceNodeApi, TraceNodeStatsApi, TraceTimelineRowApi } from '../../generated/api.schemas'
+import type {
+ TraceNodeApi,
+ TraceNodeStatsApi,
+ TraceSummaryContentApi,
+ TraceTimelineRowApi,
+} from '../../generated/api.schemas'
import { SampleNodeDetail, SampleTraceFixture } from './sampleFixtures/sampleTraceFixture'
import {
ConversationTurn,
@@ -400,6 +405,25 @@ export const FIXTURE_TRACE: SampleTraceFixture = {
timeline: { rows: FIXTURE_TIMELINE_ROWS, totalMs: 2310 },
}
+export const FIXTURE_SUMMARY: TraceSummaryContentApi = {
+ title: 'Billing question answered from invoice history',
+ bullets: [
+ { text: 'The user asks why their latest invoice is higher than the one before.', nodeId: 'gen-answer' },
+ { text: 'The agent searches the billing records for seat changes in the period.', nodeId: 'span-search' },
+ {
+ text: 'Two seats were added mid-cycle, and the prorated charge for them explains the whole difference between the two invoices.',
+ nodeId: 'gen-answer',
+ },
+ { text: 'The answer cites the seat change dates.', nodeId: null },
+ ],
+ notes: [
+ { text: 'The retrieval step returned three documents but the answer uses only one.', nodeId: 'span-retrieve' },
+ ],
+ flow: 'question → retrieve-context → search-billing → answer\n └─→ 3 documents found ✓',
+ model: 'gpt-4.1-mini',
+ generatedAt: '2026-09-01T10:20:00Z',
+}
+
export function withWidth(px: number): Decorator {
return (Story) => (
<div className="border border-dashed border-primary" style={{ width: px }}>
diff --git a/products/ai_observability/frontend/redesign/trace/traceSummaryLogic.test.ts b/products/ai_observability/frontend/redesign/trace/traceSummaryLogic.test.ts
new file mode 100644
index 000000000000..ae3686f3577a
--- /dev/null
+++ b/products/ai_observability/frontend/redesign/trace/traceSummaryLogic.test.ts
@@ -0,0 +1,251 @@
+import posthog from 'posthog-js'
+
+import { resumeKeaLoadersErrors, silenceKeaLoadersErrors } from '~/initKea'
+import { useMocks } from '~/mocks/jest'
+import { initKeaTests } from '~/test/init'
+
+import type { TraceSummaryApi } from '../../generated/api.schemas'
+import { traceSummaryLogic } from './traceSummaryLogic'
+import type { SummaryModeState } from './types'
+
+const SUMMARY_URL = '/api/projects/:team_id/ai_observability/traces/:id/summary/'
+const PENDING: TraceSummaryApi = { status: 'pending', content: null, failure: null }
+const READY: TraceSummaryApi = {
+ status: 'ready',
+ content: {
+ title: 'Refund request',
+ bullets: [{ text: 'The user asks for a refund.', nodeId: 'gen-1' }],
+ notes: [],
+ flow: 'ask → refuse',
+ model: 'gpt-4.1-mini',
+ generatedAt: '2026-09-01T10:00:00Z',
+ },
+ failure: null,
+}
+const FAILED: TraceSummaryApi = {
+ status: 'failed',
+ content: null,
+ failure: { reason: 'too_large', message: 'This trace is too large to summarize.' },
+}
+const PROVIDER_FAILED: TraceSummaryApi = {
+ status: 'failed',
+ content: null,
+ failure: { reason: 'provider_error', message: 'The model provider returned an error.' },
+}
+
+type Answer = [number, TraceSummaryApi | { detail: string }]
+
+describe('traceSummaryLogic', () => {
+ let getAnswers: Answer[]
+ let getCount: number
+ let postBodies: unknown[]
+ let postAnswer: Answer
+ let postHints: (string | null)[]
+ let firstGetGate: Promise<void> | null
+
+ function answerGets(...answers: Answer[]): void {
+ getAnswers = answers
+ }
+
+ // The mocked API answers on timers too, so settling flushes them without moving the clock.
+ async function settle(): Promise<void> {
+ for (let i = 0; i < 10; i++) {
+ await jest.advanceTimersByTimeAsync(0)
+ }
+ }
+
+ async function advance(ms: number): Promise<void> {
+ await jest.advanceTimersByTimeAsync(ms)
+ await settle()
+ }
+
+ async function opened(): Promise<ReturnType<typeof traceSummaryLogic.build>> {
+ const logic = traceSummaryLogic({ traceId: 'trace-1' })
+ logic.mount()
+ logic.actions.openSummary('tab')
+ await settle()
+ return logic
+ }
+
+ beforeEach(() => {
+ jest.useFakeTimers()
+ getAnswers = []
+ getCount = 0
+ postBodies = []
+ postAnswer = [202, PENDING]
+ postHints = []
+ firstGetGate = null
+ useMocks({
+ get: {
+ [SUMMARY_URL]: async () => {
+ const call = getCount
+ getCount += 1
+ if (call === 0 && firstGetGate) {
+ await firstGetGate
+ }
+ return getAnswers[Math.min(call, getAnswers.length - 1)]
+ },
+ },
+ post: {
+ [SUMMARY_URL]: async ({ request }) => {
+ postBodies.push(await request.json())
+ postHints.push(new URL(request.url).searchParams.get('timestamp_hint'))
+ return postAnswer
+ },
+ },
+ })
+ initKeaTests()
+ })
+
+ afterEach(() => {
+ resumeKeaLoadersErrors()
+ jest.useRealTimers()
+ jest.restoreAllMocks()
+ })
+
+ it('opening shows the button when there is no summary', async () => {
+ answerGets([404, { detail: 'No summary yet.' }])
+ const capture = jest.spyOn(posthog, 'capture')
+
+ const logic = await opened()
+
+ expect(logic.values.state).toEqual({ status: 'none' })
+ expect(capture).toHaveBeenCalledWith('llma trace view summary viewed', {
+ has_summary: false,
+ status: 'none',
+ can_generate: expect.any(Boolean),
+ opened_from: 'tab',
+ })
+ })
+
+ it('a stored summary shows at once and is not polled', async () => {
+ answerGets([200, READY])
+ const capture = jest.spyOn(posthog, 'capture')
+
+ const logic = await opened()
+ await advance(30_000)
+
+ expect(logic.values.state).toEqual({ status: 'ready', summary: READY.content })
+ expect(capture).toHaveBeenCalledWith('llma trace view summary shown', { source: 'stored' })
+ expect(getCount).toBe(1)
+ })
+
+ it('a request polls with backoff until the summary is ready', async () => {
+ answerGets([404, { detail: 'No summary yet.' }], [200, PENDING], [200, READY])
+ const capture = jest.spyOn(posthog, 'capture')
+ const logic = await opened()
+
+ logic.actions.requestSummary({ regenerate: false, timestampHint: '2026-09-01T10:00:00Z' })
+ await settle()
+ expect(logic.values.state).toEqual({ status: 'pending' })
+ await advance(999)
+ expect(getCount).toBe(1)
+ await advance(1)
+ expect(getCount).toBe(2)
+ await advance(1499)
+ expect(getCount).toBe(2)
+ await advance(1)
+
+ expect(getCount).toBe(3)
+ expect(logic.values.state.status).toBe('ready')
+ expect(postBodies).toEqual([{ regenerate: false }])
+ expect(postHints).toEqual(['2026-09-01T10:00:00Z'])
+ expect(capture).toHaveBeenCalledWith('llma trace view summary requested', { regenerate: false })
+ expect(capture).toHaveBeenCalledWith('llma trace view summary shown', { source: 'just_generated' })
+ })
+
+ it('leaving the mode stops polling', async () => {
+ answerGets([200, PENDING])
+ const logic = await opened()
+
+ logic.actions.closeSummary()
+ await advance(30_000)
+
+ expect(getCount).toBe(1)
+ })
+
+ it('a summary that finished while the mode was closed counts as just generated on return', async () => {
+ answerGets([200, PENDING], [200, READY])
+ const capture = jest.spyOn(posthog, 'capture')
+ const logic = await opened()
+ logic.actions.closeSummary()
+ await advance(30_000)
+
+ logic.actions.openSummary('tab')
+ await settle()
+
+ expect(logic.values.state.status).toBe('ready')
+ expect(capture).toHaveBeenCalledWith('llma trace view summary shown', { source: 'just_generated' })
+ })
+
+ it('an expired pending entry shows the button again and stops polling', async () => {
+ answerGets([200, PENDING], [404, { detail: 'No summary yet.' }])
+ const logic = await opened()
+
+ await advance(1000)
+ await advance(30_000)
+
+ expect(logic.values.state).toEqual({ status: 'none' })
+ expect(getCount).toBe(2)
+ })
+
+ it.each<[string, Answer]>([
+ ['succeeds', [404, { detail: 'No summary yet.' }]],
+ ['fails', [500, { detail: 'boom' }]],
+ ])('a read from an earlier visit that %s late leaves a requested summary pending', async (_name, late) => {
+ silenceKeaLoadersErrors()
+ let releaseFirstGet = (): void => {}
+ firstGetGate = new Promise((resolve) => {
+ releaseFirstGet = resolve
+ })
+ answerGets(late, [404, { detail: 'No summary yet.' }])
+ const logic = await opened()
+ logic.actions.closeSummary()
+ logic.actions.openSummary('tab')
+ await settle()
+
+ logic.actions.requestSummary({ regenerate: false, timestampHint: null })
+ await settle()
+ releaseFirstGet()
+ await settle()
+
+ expect(logic.values.state).toEqual({ status: 'pending' })
+ })
+
+ it.each<[string, Answer, SummaryModeState]>([
+ ['a failed read shows the error state', [500, { detail: 'boom' }], { status: 'error' }],
+ [
+ 'a job that failed for good shows its message without a retry',
+ [200, FAILED],
+ { status: 'failed', message: 'This trace is too large to summarize.', retryable: false },
+ ],
+ [
+ 'a job that failed for now offers a retry',
+ [200, PROVIDER_FAILED],
+ { status: 'failed', message: 'The model provider returned an error.', retryable: true },
+ ],
+ ])('%s', async (_name, answer, expected) => {
+ silenceKeaLoadersErrors()
+ answerGets(answer)
+
+ const logic = await opened()
+
+ expect(logic.values.state).toEqual(expected)
+ })
+
+ it.each([
+ ['throttled', 429],
+ ['failed', 500],
+ ] as const)('a %s regenerate keeps the ready summary on screen and says why', async (expected, statusCode) => {
+ silenceKeaLoadersErrors()
+ answerGets([200, READY])
+ postAnswer = [statusCode, { detail: 'nope' }]
+ const logic = await opened()
+
+ logic.actions.requestSummary({ regenerate: true, timestampHint: null })
+ await settle()
+
+ expect(logic.values.state).toEqual({ status: 'ready', summary: READY.content })
+ expect(logic.values.requestError).toBe(expected)
+ })
+})
diff --git a/products/ai_observability/frontend/redesign/trace/traceSummaryLogic.ts b/products/ai_observability/frontend/redesign/trace/traceSummaryLogic.ts
new file mode 100644
index 000000000000..2af80649b0fb
--- /dev/null
+++ b/products/ai_observability/frontend/redesign/trace/traceSummaryLogic.ts
@@ -0,0 +1,305 @@
+import { MakeLogicType, actions, connect, kea, key, listeners, path, props, reducers, selectors } from 'kea'
+import { loaders } from 'kea-loaders'
+import posthog from 'posthog-js'
+
+import { ApiConfig, ApiError } from 'lib/api'
+import { userHasAccess } from 'lib/utils/accessControlUtils'
+import { aiConsentLogic } from 'scenes/settings/organization/aiConsentLogic'
+
+import { AccessControlLevel, AccessControlResourceType } from '~/types'
+
+import { aiObservabilityTracesSummaryCreate, aiObservabilityTracesSummaryRetrieve } from '../../generated/api'
+import type { TraceSummaryApi, TraceSummaryFailureReasonEnumApi } from '../../generated/api.schemas'
+import { encodeTraceIdSegment } from './traceIdSegment'
+import type { SummaryModeState, SummaryRequestError } from './types'
+
+export interface TraceSummaryLogicProps {
+ traceId: string
+}
+
+export type SummaryOpenedFrom = 'tab' | 'link'
+
+export interface SummaryRequest {
+ regenerate: boolean
+ timestampHint: string | null
+}
+
+const FINAL_FAILURE_REASONS: ReadonlySet<TraceSummaryFailureReasonEnumApi> = new Set(['too_large', 'trace_not_found'])
+const FIRST_POLL_DELAY_MS: number = 1000
+const POLL_BACKOFF = 1.5
+const MAX_POLL_DELAY_MS = 5000
+
+async function readSummary(traceId: string): Promise<TraceSummaryApi | null> {
+ try {
+ return await aiObservabilityTracesSummaryRetrieve(
+ String(ApiConfig.getCurrentProjectId()),
+ encodeTraceIdSegment(traceId)
+ )
+ } catch (error) {
+ // No summary for this viewer, or an organization without AI data processing approval: both show the
+ // button, whose consent popover covers the second.
+ if (error instanceof ApiError && (error.status === 404 || error.status === 403)) {
+ return null
+ }
+ throw error
+ }
+}
+
+// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
+export interface traceSummaryLogicValues {
+ dataProcessingAccepted: boolean // aiConsentLogic
+ canGenerate: boolean
+ entry: TraceSummaryApi | null
+ entryFailed: boolean
+ entryLoading: boolean
+ firstLoadDone: boolean
+ isOpen: boolean
+ openedFrom: SummaryOpenedFrom
+ pollDelayMs: number
+ requestError: SummaryRequestError | null
+ requesting: boolean
+ sawPending: boolean
+ shownGeneratedAt: string | null
+ state: SummaryModeState
+}
+
+// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
+export interface traceSummaryLogicActions {
+ closeSummary: () => {
+ value: true
+ }
+ loadSummary: (_: void) => void
+ loadSummaryFailure: (
+ error: string,
+ errorObject?: any
+ ) => {
+ error: string
+ errorObject?: any
+ }
+ loadSummarySuccess: (
+ entry: TraceSummaryApi | null,
+ payload?: void
+ ) => {
+ entry: TraceSummaryApi | null
+ payload?: void
+ }
+ openSummary: (openedFrom: SummaryOpenedFrom) => {
+ openedFrom: SummaryOpenedFrom
+ }
+ pollScheduled: () => {
+ value: true
+ }
+ requestSummary: ({ regenerate, timestampHint }: SummaryRequest) => SummaryRequest
+ requestSummaryFailure: (
+ error: string,
+ errorObject?: any
+ ) => {
+ error: string
+ errorObject?: any
+ }
+ requestSummarySuccess: (
+ entry: TraceSummaryApi,
+ payload?: SummaryRequest
+ ) => {
+ entry: TraceSummaryApi
+ payload?: SummaryRequest
+ }
+ summaryShownTracked: (generatedAt: string) => {
+ generatedAt: string
+ }
+}
+
+// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
+export interface traceSummaryLogicMeta {
+ key: string
+ __keaTypeGenInternalSelectorTypes: {
+ state: (entry: TraceSummaryApi | null, entryFailed: boolean, firstLoadDone: boolean) => SummaryModeState
+ canGenerate: (dataProcessingAccepted: boolean) => boolean
+ }
+}
+
+export type traceSummaryLogicType = MakeLogicType<
+ traceSummaryLogicValues,
+ traceSummaryLogicActions,
+ TraceSummaryLogicProps,
+ traceSummaryLogicMeta
+>
+
+export const traceSummaryLogic = kea<traceSummaryLogicType>([
+ props({} as TraceSummaryLogicProps),
+ key((props) => props.traceId),
+ path((key) => ['products', 'ai_observability', 'frontend', 'redesign', 'trace', 'traceSummaryLogic', key]),
+ connect(() => ({
+ values: [aiConsentLogic, ['dataProcessingAccepted']],
+ })),
+ actions({
+ openSummary: (openedFrom: SummaryOpenedFrom) => ({ openedFrom }),
+ closeSummary: true,
+ pollScheduled: true,
+ summaryShownTracked: (generatedAt: string) => ({ generatedAt }),
+ }),
+ loaders(({ props }) => ({
+ entry: [
+ null as TraceSummaryApi | null,
+ {
+ loadSummary: async (_: void, breakpoint): Promise<TraceSummaryApi | null> => {
+ const read = readSummary(props.traceId)
+ // A read from an earlier visit can land after a newer read and a request. Settling before the
+ // breakpoint drops it whether it succeeded or failed, so it never replaces a newer entry.
+ await read.catch(() => null)
+ breakpoint()
+ return await read
+ },
+ requestSummary: async ({ regenerate, timestampHint }: SummaryRequest): Promise<TraceSummaryApi> =>
+ await aiObservabilityTracesSummaryCreate(
+ String(ApiConfig.getCurrentProjectId()),
+ encodeTraceIdSegment(props.traceId),
+ { regenerate },
+ timestampHint ? { timestamp_hint: timestampHint } : undefined
+ ),
+ },
+ ],
+ })),
+ reducers({
+ isOpen: [false, { openSummary: () => true, closeSummary: () => false }],
+ openedFrom: ['tab' as SummaryOpenedFrom, { openSummary: (_, { openedFrom }) => openedFrom }],
+ pollDelayMs: [
+ FIRST_POLL_DELAY_MS,
+ {
+ openSummary: () => FIRST_POLL_DELAY_MS,
+ requestSummary: () => FIRST_POLL_DELAY_MS,
+ pollScheduled: (delay) => Math.min(delay * POLL_BACKOFF, MAX_POLL_DELAY_MS),
+ },
+ ],
+ // Cleared on an answer rather than on the request, so a reload keeps the error on screen until it lands.
+ entryFailed: [
+ false,
+ {
+ openSummary: () => false,
+ loadSummarySuccess: () => false,
+ loadSummaryFailure: () => true,
+ },
+ ],
+ // A failed request leaves the entry as it was, so the view keeps showing it next to this error.
+ requestError: [
+ null as SummaryRequestError | null,
+ {
+ openSummary: () => null,
+ requestSummary: () => null,
+ requestSummaryFailure: (_, { errorObject }) =>
+ errorObject instanceof ApiError && errorObject.status === 429 ? 'throttled' : 'failed',
+ },
+ ],
+ firstLoadDone: [
+ false,
+ {
+ openSummary: () => false,
+ loadSummarySuccess: () => true,
+ loadSummaryFailure: () => true,
+ },
+ ],
+ requesting: [
+ false,
+ {
+ requestSummary: () => true,
+ requestSummarySuccess: () => false,
+ requestSummaryFailure: () => false,
+ },
+ ],
+ // Kept across visits until a summary is shown, so one that finished while the mode was closed still counts
+ // as just generated.
+ sawPending: [
+ false,
+ {
+ summaryShownTracked: () => false,
+ loadSummarySuccess: (state, { entry }) => state || entry?.status === 'pending',
+ requestSummarySuccess: (state, { entry }) => state || entry?.status === 'pending',
+ },
+ ],
+ shownGeneratedAt: [null as string | null, { summaryShownTracked: (_, { generatedAt }) => generatedAt }],
+ }),
+ selectors({
+ state: [
+ (s) => [s.entry, s.entryFailed, s.firstLoadDone],
+ (entry: TraceSummaryApi | null, entryFailed: boolean, firstLoadDone: boolean): SummaryModeState => {
+ if (entryFailed) {
+ return { status: 'error' }
+ }
+ if (!firstLoadDone) {
+ return { status: 'loading' }
+ }
+ if (!entry) {
+ return { status: 'none' }
+ }
+ if (entry.status === 'ready' && entry.content) {
+ return { status: 'ready', summary: entry.content }
+ }
+ if (entry.status === 'failed' && entry.failure) {
+ return {
+ status: 'failed',
+ message: entry.failure.message,
+ retryable: !FINAL_FAILURE_REASONS.has(entry.failure.reason),
+ }
+ }
+ return entry.status === 'pending' ? { status: 'pending' } : { status: 'error' }
+ },
+ ],
+ canGenerate: [
+ (s) => [s.dataProcessingAccepted],
+ (dataProcessingAccepted: boolean): boolean =>
+ dataProcessingAccepted &&
+ userHasAccess(AccessControlResourceType.LlmAnalytics, AccessControlLevel.Editor),
+ ],
+ }),
+ listeners(({ actions, values, cache, selectors }) => {
+ const pollWhilePending = (): void => {
+ if (!values.isOpen || values.state.status !== 'pending') {
+ cache.disposables.dispose('summaryPoll')
+ return
+ }
+ const delay = values.pollDelayMs
+ actions.pollScheduled()
+ cache.disposables.add(() => {
+ const timeout = window.setTimeout(() => actions.loadSummary(), delay)
+ return () => window.clearTimeout(timeout)
+ }, 'summaryPoll')
+ }
+ const trackShown = (): void => {
+ const { state } = values
+ if (values.isOpen && state.status === 'ready' && state.summary.generatedAt !== values.shownGeneratedAt) {
+ posthog.capture('llma trace view summary shown', {
+ source: values.sawPending ? 'just_generated' : 'stored',
+ })
+ actions.summaryShownTracked(state.summary.generatedAt)
+ }
+ }
+ const answered = (): void => {
+ pollWhilePending()
+ trackShown()
+ }
+ return {
+ openSummary: () => {
+ cache.disposables.dispose('summaryPoll')
+ actions.loadSummary()
+ },
+ closeSummary: () => {
+ cache.disposables.dispose('summaryPoll')
+ },
+ loadSummarySuccess: (_, __, ___, previousState) => {
+ if (values.isOpen && !selectors.firstLoadDone(previousState)) {
+ posthog.capture('llma trace view summary viewed', {
+ has_summary: values.entry !== null,
+ status: values.state.status,
+ can_generate: values.canGenerate,
+ opened_from: values.openedFrom,
+ })
+ }
+ answered()
+ },
+ requestSummary: ({ regenerate }) => {
+ posthog.capture('llma trace view summary requested', { regenerate })
+ },
+ requestSummarySuccess: answered,
+ }
+ }),
+])
diff --git a/products/ai_observability/frontend/redesign/trace/types.ts b/products/ai_observability/frontend/redesign/trace/types.ts
index c9401e188121..c45339b484fd 100644
--- a/products/ai_observability/frontend/redesign/trace/types.ts
+++ b/products/ai_observability/frontend/redesign/trace/types.ts
@@ -3,11 +3,12 @@ import type {
TraceNodeApi,
TraceNodeDetailApi,
TraceNodeEvaluationRollupOutcomeEnumApi,
+ TraceSummaryContentApi,
} from '../../generated/api.schemas'
export type TraceNodeKind = TraceNodeApi['kind']
-export type TraceMode = 'spans' | 'thread' | 'timeline'
+export type TraceMode = 'spans' | 'thread' | 'timeline' | 'summary'
export type TraceViewChoice = 'new' | 'legacy'
@@ -122,3 +123,18 @@ export interface LabeledLink {
label: string
href: string
}
+
+export type SummaryItemKind = 'bullet' | 'note'
+
+/** Why a summary request failed. `throttled` means the user reached their summary limit. */
+export type SummaryRequestError = 'throttled' | 'failed'
+
+/** `none` means no summary this user may see exists yet, and `error` that reading it failed. A `failed` summary that
+ * is not `retryable` fails the same way on every new request. */
+export type SummaryModeState =
+ | { status: 'loading' }
+ | { status: 'none' }
+ | { status: 'pending' }
+ | { status: 'ready'; summary: TraceSummaryContentApi }
+ | { status: 'failed'; message: string; retryable: boolean }
+ | { status: 'error' }
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 3fe2ea03e745..7cec11fead22 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -121461,6 +121461,66 @@ export namespace Schemas {
queue_id?: string | null;
}
+ export type TraceSummaryStatusEnum = typeof TraceSummaryStatusEnum[keyof typeof TraceSummaryStatusEnum];
+
+
+ export const TraceSummaryStatusEnum = {
+ Pending: 'pending',
+ Ready: 'ready',
+ Failed: 'failed',
+ } as const;
+
+ export interface TraceSummaryItem {
+ text: string;
+ /** The step the item refers to, or null when it names none. */
+ nodeId: string | null;
+ }
+
+ export interface TraceSummaryContent {
+ title: string;
+ bullets: TraceSummaryItem[];
+ /** Details worth a second look, or empty. */
+ notes: TraceSummaryItem[];
+ /** The main steps of the trace as a small text diagram. */
+ flow: string;
+ /** The model that wrote the summary. */
+ model: string;
+ generatedAt: string;
+ }
+
+ export type TraceSummaryFailureReasonEnum = typeof TraceSummaryFailureReasonEnum[keyof typeof TraceSummaryFailureReasonEnum];
+
+
+ export const TraceSummaryFailureReasonEnum = {
+ TraceNotFound: 'trace_not_found',
+ TooLarge: 'too_large',
+ Timeout: 'timeout',
+ ProviderError: 'provider_error',
+ NotApproved: 'not_approved',
+ AccessChanged: 'access_changed',
+ Error: 'error',
+ } as const;
+
+ export interface TraceSummaryFailure {
+ reason: TraceSummaryFailureReasonEnum;
+ /** Why the summary failed, ready to show to the user. */
+ message: string;
+ }
+
+ export interface TraceSummary {
+ /** `pending` while the summary is written, then `ready` or `failed`. */
+ status: TraceSummaryStatusEnum;
+ /** The summary when `status` is `ready`, else null. */
+ content: TraceSummaryContent | null;
+ /** Why it failed when `status` is `failed`, else null. */
+ failure: TraceSummaryFailure | null;
+ }
+
+ export interface TraceSummaryRequest {
+ /** Replace a ready summary with a new one. A pending summary is never replaced. */
+ regenerate?: boolean;
+ }
+
/**
* One prior completed training run plus its full iteration trail.
*/
@@ -129954,6 +130014,13 @@ export namespace Schemas {
timestamp_hint?: string;
};
+ export type AiObservabilityTracesSummaryCreateParams = {
+ /**
+ * When the trace happened, as carried by links into it. Lets a trace older than the AI events retention load from the shared events table.
+ */
+ timestamp_hint?: string;
+ };
+
export type AlertsListParams = {
/**
* Optional. Restrict results to alerts created by the user with this UUID.