Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

fix(topics): guide setup and scope processing controls (#18858)

Lysander Kiesela0a7ebad7416
diff --git a/packages/shared/AGENTS.md b/packages/shared/AGENTS.md
index 5cf2159109..bba10c8c92 100644
--- a/packages/shared/AGENTS.md
+++ b/packages/shared/AGENTS.md
@@ -85,9 +85,15 @@
definitions retain their original creation run.
- `clickhouse.ts`: current summaries/assignments and immutable definitions.
Source identity prefers `traceId`; `sessionId` may carry parent context.
- Facet versions use `(projectId, facetId, version)`. Reads require a time
- range; replacement includes the source minute, with run/origin suffixes
- for assignments. Definition bounds retain original creation dates on reuse.
+ Facet versions use `(projectId, facetId, version)`. Data reads require a time
+ range; `hasStoredTopicSummaries(projectId)` checks project onboarding
+ readiness across all stored trace summaries without loading their contents.
+ A positive result is cached per project in Redis for 30 minutes, skipping
+ subsequent ClickHouse probes; cache failures fall back to ClickHouse.
+ Negative results are cached for 30 seconds, bounding the onboarding delay
+ after the first summaries arrive while avoiding repeated empty-project scans.
+ Replacement includes the source minute, with run/origin suffixes for assignments. Definition bounds
+ retain original creation dates on reuse.
`getLatestFacetSummaries` returns display fields; processing reads use
`listTopicSummaries` or `getTopicClusteringSummaries` for complete summaries.
- `execution-store.ts`: one BatchAction per request, compact counters and run references.
diff --git a/packages/shared/src/server/topics/clickhouse.test.ts b/packages/shared/src/server/topics/clickhouse.test.ts
index 26478c13b1..f4504096f1 100644
--- a/packages/shared/src/server/topics/clickhouse.test.ts
+++ b/packages/shared/src/server/topics/clickhouse.test.ts
@@ -19,6 +19,7 @@ import {
writeTopicSummaries,
getTopicDefinitions,
writeTopicDefinitions,
+ hasStoredTopicSummaries,
} from "./clickhouse";
const mocks = vi.hoisted(() => ({
@@ -26,9 +27,16 @@ const mocks = vi.hoisted(() => ({
exec: vi.fn(),
query: vi.fn(),
publishedRuns: vi.fn(),
+ cacheGet: vi.fn(),
+ cacheSet: vi.fn(),
}));
vi.mock("../../db", () => ({
- prisma: { topicClusteringRun: { findMany: mocks.publishedRuns } },
+ prisma: {
+ topicClusteringRun: { findMany: mocks.publishedRuns },
+ },
+}));
+vi.mock("../redis/redis", () => ({
+ redis: { get: mocks.cacheGet, set: mocks.cacheSet },
}));
vi.mock("../clickhouse/client", () => ({
clickhouseClient: () => ({ insert: mocks.insert, exec: mocks.exec }),
@@ -38,12 +46,58 @@ vi.mock("../clickhouse/queryTags", () => ({
buildClickHouseLogComment: () => "{}",
}));
vi.mock("../repositories/clickhouse", () => ({ queryClickhouse: mocks.query }));
+vi.mock("../instrumentation", () => ({ traceException: vi.fn() }));
+vi.mock("../logger", () => ({ logger: { warn: vi.fn() } }));
beforeEach(() => {
vi.resetAllMocks();
mocks.query.mockResolvedValue([]);
mocks.exec.mockImplementation(async () => ({ stream: Readable.from([]) }));
mocks.publishedRuns.mockResolvedValue([{ id: "published-run" }]);
+ mocks.cacheGet.mockResolvedValue(null);
+});
+
+describe("Topics summary readiness", () => {
+ it("returns ClickHouse readiness even when Redis reads and writes fail", async () => {
+ mocks.cacheGet.mockRejectedValue(new Error("Redis unavailable"));
+ mocks.cacheSet.mockRejectedValue(new Error("Redis unavailable"));
+ mocks.query.mockResolvedValue([{ found: 1 }]);
+
+ expect(await hasStoredTopicSummaries("project-a")).toBe(true);
+ expect(mocks.query).toHaveBeenCalledOnce();
+ });
+
+ it("skips ClickHouse once a project has collected summaries", async () => {
+ mocks.cacheGet.mockResolvedValue("1");
+
+ expect(await hasStoredTopicSummaries("project-a")).toBe(true);
+ expect(mocks.query).not.toHaveBeenCalled();
+ });
+
+ it("caches empty projects briefly and detects summaries after the cache expires", async () => {
+ expect(await hasStoredTopicSummaries("project-a")).toBe(false);
+ expect(mocks.cacheSet).toHaveBeenCalledWith(
+ "langfuse:topics:has-summaries:project-a",
+ "0",
+ "EX",
+ 30,
+ );
+
+ mocks.cacheGet.mockResolvedValue("0");
+ expect(await hasStoredTopicSummaries("project-a")).toBe(false);
+ expect(mocks.query).toHaveBeenCalledTimes(1);
+
+ mocks.cacheGet.mockResolvedValue(null);
+ mocks.query.mockResolvedValue([{ found: 1 }]);
+ expect(await hasStoredTopicSummaries("project-a")).toBe(true);
+ expect(mocks.query).toHaveBeenCalledTimes(2);
+ expect(mocks.cacheSet).toHaveBeenCalledWith(
+ "langfuse:topics:has-summaries:project-a",
+ "1",
+ "EX",
+ 1800,
+ );
+ });
});
const clickhouseNumberMap = (values: Record<string, number>) =>
diff --git a/packages/shared/src/server/topics/clickhouse.ts b/packages/shared/src/server/topics/clickhouse.ts
index dfdddc384c..9908cee2b9 100644
--- a/packages/shared/src/server/topics/clickhouse.ts
+++ b/packages/shared/src/server/topics/clickhouse.ts
@@ -14,6 +14,9 @@ import type {
} from "../../topics";
import { topicSourceSchema, topicTimeRangeSchema } from "../../topics";
import { prisma } from "../../db";
+import { logger } from "../logger";
+import { traceException } from "../instrumentation";
+import { redis } from "../redis/redis";
import { chunk } from "lodash";
import { Readable } from "node:stream";
import { finished } from "node:stream/promises";
@@ -470,6 +473,55 @@ export async function hasTopicEmbeddings(projectId: string): Promise<boolean> {
return rows.length > 0;
}
+/** Project onboarding readiness, cached for 30 minutes when ready and 30 seconds when empty. */
+export async function hasStoredTopicSummaries(
+ projectId: string,
+): Promise<boolean> {
+ const cacheKey = `langfuse:topics:has-summaries:${projectId}`;
+ try {
+ const cached = await redis?.get(cacheKey);
+ if (cached === "1") return true;
+ if (cached === "0") return false;
+ } catch (error) {
+ traceException(error);
+ logger.warn("Failed to read cached Topics summary readiness", {
+ projectId,
+ error,
+ });
+ }
+ const rows = await queryClickhouse<{ found: number }>({
+ query: `SELECT 1 AS found FROM topic_facet_summaries
+ WHERE project_id = {projectId:String}
+ AND trace_id != '' AND processing_state = 'complete'
+ AND NOT startsWith(environment, {internalEnvironmentPrefix:String})
+ AND environment != {publicLlmJudgeEnvironment:String}
+ LIMIT 1`,
+ params: {
+ projectId,
+ internalEnvironmentPrefix: INTERNAL_EVAL_ENVIRONMENT_PREFIX,
+ publicLlmJudgeEnvironment: PUBLIC_LLM_JUDGE_ENVIRONMENT,
+ },
+ tags: { route: "topics-has-summaries", projectId },
+ clickhouseSettings: { max_threads: 1 },
+ });
+ const hasSummaries = rows.length > 0;
+ try {
+ await redis?.set(
+ cacheKey,
+ hasSummaries ? "1" : "0",
+ "EX",
+ hasSummaries ? 1800 : 30,
+ );
+ } catch (error) {
+ traceException(error);
+ logger.warn("Failed to cache Topics summary readiness", {
+ projectId,
+ error,
+ });
+ }
+ return hasSummaries;
+}
+
/** Count current compatible summaries without loading summary text or vectors. */
export async function getTopicSummaryCounts(
projectId: string,
diff --git a/web/src/__tests__/server/unit/topics.servertest.ts b/web/src/__tests__/server/unit/topics.servertest.ts
index 8cb203684a..184c15f552 100644
--- a/web/src/__tests__/server/unit/topics.servertest.ts
+++ b/web/src/__tests__/server/unit/topics.servertest.ts
@@ -20,6 +20,7 @@ const mocks = vi.hoisted(() => ({
listTopicFacets: vi.fn(),
readLatestTopicAssignments: vi.fn(),
getLatestFacetSummaries: vi.fn(),
+ hasStoredTopicSummaries: vi.fn(),
getPublishedTopicRun: vi.fn(),
getTopicFacetVersion: vi.fn(),
createTopicFacet: vi.fn(),
@@ -94,11 +95,16 @@ const input: Extract<TopicExecutionInput, { operation: "process" }> = {
}),
};
-function caller(role: "ADMIN" | "VIEWER" = "ADMIN", langfuseTopics = true) {
+function caller(
+ role: "ADMIN" | "VIEWER" = "ADMIN",
+ langfuseTopics = true,
+ admin = false,
+) {
const session = {
expires: "1",
user: {
id: "user-a",
+ admin,
featureFlags: testFeatureFlags({ langfuseTopics }),
organizations: [
{
@@ -205,6 +211,7 @@ beforeEach(() => {
});
mocks.readTopicExecutionSummary.mockResolvedValue(execution());
mocks.getLatestFacetSummaries.mockResolvedValue([summary]);
+ mocks.hasStoredTopicSummaries.mockResolvedValue(false);
mocks.readTopicExecutionTraceErrors.mockResolvedValue({
errors: [],
expired: false,
@@ -829,6 +836,14 @@ describe("Topics local execution access and publication", () => {
expect(mocks.getTopicSummaryCounts).not.toHaveBeenCalled();
});
+ it("blocks transcript debugging for project admins who are not Langfuse admins", async () => {
+ await expect(caller().inspect(inspectInput)).rejects.toMatchObject({
+ code: "FORBIDDEN",
+ });
+ expect(mocks.listTopicSummaries).not.toHaveBeenCalled();
+ expect(mocks.loadTopicTranscript).not.toHaveBeenCalled();
+ });
+
it.each([
{ ...summary, projectId: "foreign-project" },
{ ...summary, facetId: "another-facet" },
@@ -837,7 +852,9 @@ describe("Topics local execution access and publication", () => {
{ ...summary, traceId: null, sessionId: "session-a" },
])("rejects a foreign or invalid trace summary", async (invalidSummary) => {
mocks.listTopicSummaries.mockResolvedValue([invalidSummary]);
- await expect(caller().inspect(inspectInput)).rejects.toMatchObject({
+ await expect(
+ caller("ADMIN", true, true).inspect(inspectInput),
+ ).rejects.toMatchObject({
code: "NOT_FOUND",
});
expect(mocks.loadTopicTranscript).not.toHaveBeenCalled();
@@ -855,7 +872,9 @@ describe("Topics local execution access and publication", () => {
const traceId = "client/session:trace 1";
mocks.listTopicSummaries.mockResolvedValue([{ ...summary, traceId }]);
mocks.loadTopicTranscript.mockResolvedValue(source);
- expect(await caller().inspect({ ...inspectInput, traceId })).toEqual({
+ expect(
+ await caller("ADMIN", true, true).inspect({ ...inspectInput, traceId }),
+ ).toEqual({
model: summary.summaryModel,
transcript: source.transcript,
});
@@ -882,7 +901,7 @@ describe("Topics local execution access and publication", () => {
...source,
transcript: null,
});
- expect(await caller().inspect(inspectInput)).toEqual({
+ expect(await caller("ADMIN", true, true).inspect(inspectInput)).toEqual({
model: summary.summaryModel,
transcript: null,
});
@@ -892,7 +911,7 @@ describe("Topics local execution access and publication", () => {
mocks.loadTopicTranscript.mockRejectedValue(
new Error("Trace no longer exists"),
);
- expect(await caller().inspect(inspectInput)).toEqual({
+ expect(await caller("ADMIN", true, true).inspect(inspectInput)).toEqual({
model: summary.summaryModel,
transcript: null,
});
@@ -1013,6 +1032,58 @@ describe("Topics local execution access and publication", () => {
});
describe("Topics current results", () => {
+ beforeEach(() => mocks.hasStoredTopicSummaries.mockResolvedValue(true));
+
+ it("skips per-facet result reads while the project has no stored summaries", async () => {
+ mocks.listTopicFacets.mockResolvedValue([
+ { id: facetId, name: "Intent", versions: [{ version: facetVersion }] },
+ {
+ id: "other-facet",
+ name: "Outcome",
+ versions: [{ version: facetVersion }],
+ },
+ ]);
+ mocks.hasStoredTopicSummaries.mockResolvedValue(false);
+ expect(
+ await caller("VIEWER").currentResults({ projectId, timeRange }),
+ ).toEqual({ hasStoredSummaries: false, facets: [] });
+ expect(mocks.hasStoredTopicSummaries).toHaveBeenCalledExactlyOnceWith(
+ projectId,
+ );
+ expect(mocks.getLatestFacetSummaries).not.toHaveBeenCalled();
+ expect(mocks.readLatestTopicAssignments).not.toHaveBeenCalled();
+ expect(mocks.getPublishedTopicRun).not.toHaveBeenCalled();
+ });
+ it("checks project readiness once across facets even when summaries are outside the selected range", async () => {
+ mocks.listTopicFacets.mockResolvedValue([
+ { id: facetId, name: "Intent", versions: [{ version: facetVersion }] },
+ {
+ id: "other-facet",
+ name: "Outcome",
+ versions: [{ version: facetVersion }],
+ },
+ ]);
+ mocks.getLatestFacetSummaries.mockResolvedValue([]);
+ mocks.readLatestTopicAssignments.mockResolvedValue([]);
+ mocks.getPublishedTopicRun.mockResolvedValue(null);
+ mocks.hasStoredTopicSummaries.mockResolvedValue(true);
+
+ const result = await caller("VIEWER").currentResults({
+ projectId,
+ timeRange,
+ });
+ expect(result.hasStoredSummaries).toBe(true);
+ expect(result.facets).toHaveLength(2);
+ expect(result.facets[0]).toMatchObject({
+ rows: [],
+ usableCount: 0,
+ map: null,
+ });
+ expect(mocks.hasStoredTopicSummaries).toHaveBeenCalledExactlyOnceWith(
+ projectId,
+ );
+ });
+
it("retains published map descriptions when reprocessed traces await assignment", async () => {
mocks.listTopicFacets.mockResolvedValue([
{ id: facetId, name: "Intent", versions: [{ version: facetVersion }] },
@@ -1034,7 +1105,9 @@ describe("Topics current results", () => {
},
]);
- const [result] = await caller("VIEWER").currentResults({
+ const {
+ facets: [result],
+ } = await caller("VIEWER").currentResults({
projectId,
timeRange,
});
@@ -1115,7 +1188,9 @@ describe("Topics current results", () => {
],
})),
);
- const [result] = await caller("VIEWER").currentResults({
+ const {
+ facets: [result],
+ } = await caller("VIEWER").currentResults({
projectId,
timeRange,
});
@@ -1250,7 +1325,7 @@ describe("Topics current results", () => {
],
},
]);
- const result = await caller("VIEWER").currentResults({
+ const { facets: result } = await caller("VIEWER").currentResults({
projectId,
timeRange,
});
diff --git a/web/src/features/topics/AutomaticProcessingDialog.tsx b/web/src/features/topics/AutomaticProcessingDialog.tsx
index 55283fb9eb..d073f6b25b 100644
--- a/web/src/features/topics/AutomaticProcessingDialog.tsx
+++ b/web/src/features/topics/AutomaticProcessingDialog.tsx
@@ -11,7 +11,11 @@ import {
type TopicsModelSlotName,
} from "@langfuse/shared/topics";
+import { type FilterState } from "@langfuse/shared";
+import { TopicAutomaticTraceScope } from "./TopicAutomaticTraceScope";
+
type AutomaticProcessingDialogProps = {
+ projectId?: string;
initialEnabled: boolean;
initialSampling: number;
traceIdleMs: number;
@@ -28,6 +32,7 @@ const COST_NOTE =
/** Dialog content; render it from `AutomaticProcessingDialogController`. */
export function AutomaticProcessingDialog({
error,
+ projectId,
initialEnabled,
initialSampling,
models,
@@ -44,11 +49,13 @@ export function AutomaticProcessingDialog({
assignments: [],
}),
);
+ const [filters, setFilters] = useState<FilterState>([]);
const [enabled, setEnabled] = useState(initialEnabled);
const missingModel = TOPICS_MODEL_SLOTS.some((slot) => !models[slot]);
return (
<Dialog
title="Automatic processing"
+ size="lg"
actions={[
{
label: "Save",
@@ -61,6 +68,12 @@ export function AutomaticProcessingDialog({
>
<Dialog.Body>
<div className="flex flex-col gap-4">
+ <Alert variant="info" icon={Info}>
+ <Alert.Description>
+ Only traces from v4-ready ingestion are processed automatically.
+ Legacy ingestion is not included.
+ </Alert.Description>
+ </Alert>
<p className="text-sm">
New traces are summarized with your saved facets and models once
they have been idle for {idleTimeLabel(traceIdleMs)}. The sampling
@@ -82,12 +95,6 @@ export function AutomaticProcessingDialog({
</Alert.Description>
</Alert>
) : null}
- <Alert variant="info" icon={Info}>
- <Alert.Description>
- Only traces from v4-ready ingestion are processed automatically.
- Legacy ingestion is not included.
- </Alert.Description>
- </Alert>
<section className="flex flex-col gap-2">
<h3 className="text-sm font-bold">Models</h3>
<dl className="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1 text-sm">
@@ -108,6 +115,11 @@ export function AutomaticProcessingDialog({
description="The share of new traces Topics summarizes automatically."
tooltip="Topics summarizes this share of new traces. A lower rate costs less. For manual processing, you set the sampling for each run."
/>
+ <TopicAutomaticTraceScope
+ projectId={projectId}
+ filters={filters}
+ onFiltersChange={setFilters}
+ />
<SwitchInput
id="topics-automatic-processing"
aria-label="Automatic processing"
diff --git a/web/src/features/topics/AutomaticProcessingDialogController.tsx b/web/src/features/topics/AutomaticProcessingDialogController.tsx
index 8a1112368c..31db2c4574 100644
--- a/web/src/features/topics/AutomaticProcessingDialogController.tsx
+++ b/web/src/features/topics/AutomaticProcessingDialogController.tsx
@@ -8,6 +8,7 @@ import { automaticProcessingState } from "./useAutomaticProcessing";
type StoredSettings = RouterOutputs["topics"]["modelSettings"];
type AutomaticProcessingSettings = {
+ projectId: string;
rule: TopicRule | null;
stored: StoredSettings | undefined;
traceIdleMs: number | null;
@@ -47,6 +48,7 @@ export function AutomaticProcessingDialogController({
function AutomaticProcessingDialogContent({
closeDialog,
+ projectId,
initialEnabled,
rule,
save,
@@ -78,6 +80,7 @@ function AutomaticProcessingDialogContent({
return (
<AutomaticProcessingDialog
+ projectId={projectId}
initialEnabled={initialEnabled}
initialSampling={rule?.sampling ?? 1}
traceIdleMs={traceIdleMs ?? 600_000}
diff --git a/web/src/features/topics/ConfigureTopicsDialog.tsx b/web/src/features/topics/ConfigureTopicsDialog.tsx
index 9cc35d3dcf..f83ae959fc 100644
--- a/web/src/features/topics/ConfigureTopicsDialog.tsx
+++ b/web/src/features/topics/ConfigureTopicsDialog.tsx
@@ -1,4 +1,4 @@
-import { useId, useMemo, useState } from "react";
+import { useId, useState } from "react";
import { AlertTriangle, ExternalLinkIcon } from "lucide-react";
import { Dialog } from "@/src/components/design-system/Dialog/Dialog";
import DocPopup from "@/src/components/layouts/doc-popup";
@@ -11,36 +11,16 @@ import {
TooltipContent,
TooltipTrigger,
} from "@/src/components/ui/tooltip";
-import { ObservationFilterBuilder } from "@/src/features/evals/v2/components/Evaluators/Testing/components/SampleObservationSelectorBase/components/ObservationFilterBuilder/ObservationFilterBuilder";
-import { FilterModeToggle } from "@/src/features/evals/v2/components/Evaluators/Testing/components/SampleObservationSelectorBase/components/FilterModeToggle";
-import { RULE_FIELD_REGISTRY } from "@/src/features/evals/v2/constants/ruleSearchRegistry";
-import {
- EventsSearchBarRow,
- toObservedOptions,
- useEventsSearchBar,
-} from "@/src/features/search-bar";
-import { SectionHeader } from "@/src/features/evals/v2/components/Evaluators/Testing/components/SectionHeader/SectionHeader";
import { Tabs } from "@/src/components/design-system/Tabs/Tabs";
import { Badge } from "@/src/components/design-system/Badge/Badge";
import { Stepper } from "@/src/features/evals/v2/components/Stepper/Stepper";
-import type { EvaluatorFilterExperience } from "@/src/features/evals/v2/types/evaluatorFilterExperience";
import {
JudgeModelPicker,
JudgeModelPickerTrigger,
} from "@/src/features/evals/v2/components/Evaluators/JudgeModelPicker/JudgeModelPicker";
import { type JudgeModel } from "@/src/features/evals/v2/judgeModel";
-import { format } from "date-fns";
-import {
- eventsEvalFilterColumns,
- experimentEvalFilterColsWithOptions,
- observationEvalFilterColsWithOptions,
- type FilterState,
- type TimeFilter,
- type TracingSearchType,
-} from "@langfuse/shared";
-import { useEventsFilterOptions } from "@/src/features/events/hooks/useEventsFilterOptions";
-import { api, sendAsPostOption } from "@/src/utils/api";
-import { relativeTopicTimeRange } from "./time-range";
+import { type FilterState } from "@langfuse/shared";
+import { Alert } from "@/src/components/design-system/Alert/Alert";
type FacetDraft = {
id: string;
@@ -103,9 +83,6 @@ type ConfigureTopicsDialogProps = {
canWrite?: boolean;
saving?: boolean;
saveError?: string | null;
- projectId?: string;
- /** Storybook keeps the sample filter. The project page chooses traces when a run starts. */
- sampleScope?: boolean;
} & (
| { notice: "none" }
| {
@@ -144,10 +121,8 @@ export function ConfigureTopicsDialog(props: ConfigureTopicsDialogProps) {
onConfigureProviders,
onSave,
onSlotCommit,
- projectId,
providerGroups,
embeddingProviderGroups = providerGroups,
- sampleScope = true,
saveError = null,
saving = false,
slotChecks,
@@ -168,7 +143,6 @@ export function ConfigureTopicsDialog(props: ConfigureTopicsDialogProps) {
const [facets, setFacets] = useState(draft.facets);
const [browsing, setBrowsing] = useState(facets[0]?.id ?? ADD_FACET_TAB);
const [idleSeconds, setIdleSeconds] = useState(draft.idleSeconds);
- const [filters, setFilters] = useState(draft.filters);
const modelsReady = Boolean(summary && embedding && clustering);
const enabledFacets = facets.filter((facet) => facet.enabled);
const testsReady =
@@ -244,7 +218,7 @@ export function ConfigureTopicsDialog(props: ConfigureTopicsDialogProps) {
embeddingDimensions: dimensions,
clustering,
facets,
- filters,
+ filters: draft.filters,
idleSeconds,
}),
)
@@ -253,9 +227,12 @@ export function ConfigureTopicsDialog(props: ConfigureTopicsDialogProps) {
}}
>
<div className="flex min-h-0 flex-1 flex-col gap-4 overflow-y-auto px-4 pb-4">
- <p className="text-muted-foreground text-sm">
- Models, what to look for, and which traces to run.
- </p>
+ <Alert variant="info">
+ <Alert.Description>
+ These settings apply to the whole project. Choose which traces to
+ process in Automatic processing or for each manual batch.
+ </Alert.Description>
+ </Alert>
{paused ? (
<PausedNotice
shortLabel={paused.shortLabel}
@@ -339,8 +316,8 @@ export function ConfigureTopicsDialog(props: ConfigureTopicsDialogProps) {
</Stepper>
<Stepper
number={3}
- title="Run settings"
- description="Choose which traces to include and set the idle time."
+ title="Trace readiness"
+ description="Set when a trace is ready to be summarized across the project."
compactBottomSpacing
>
<div className="flex items-center gap-2">
@@ -359,13 +336,6 @@ export function ConfigureTopicsDialog(props: ConfigureTopicsDialogProps) {
the trace done and summarizing it.
</p>
</div>
- {sampleScope ? (
- <RuleScope
- projectId={projectId}
- filters={filters}
- onFiltersChange={setFilters}
- />
- ) : null}
</Stepper>
</div>
{saveError ? (
@@ -572,442 +542,6 @@ function FacetPicker({
);
}
-const SAMPLE_TRACES_IN_SCOPE = [
- {
- start: "2026-10-08 15:58:44",
- type: "GENERATION",
- name: "billing-question",
- input: '{"role":"user","content":"My subscription invoice..."}',
- },
- {
- start: "2026-10-08 15:58:43",
- type: "GENERATION",
- name: "weather-question",
- input: '{"role":"user","content":"I\'m visiting Lisbon this..."}',
- },
- {
- start: "2026-10-08 15:54:02",
- type: "SPAN",
- name: "weather-question",
- input: '{"role":"user","content":"What is the weather in..."}',
- },
-];
-
-const topicsFilterRegistry = {
- ...RULE_FIELD_REGISTRY,
- aiFilterPrompt: true,
- fields: RULE_FIELD_REGISTRY.fields.filter(
- (field) => field.id !== "isRootObservation",
- ),
- columns: RULE_FIELD_REGISTRY.columns.filter(
- (column) => column.id !== "isRootObservation",
- ),
-};
-
-const queryOnlyColumnIds = topicsFilterRegistry.fields
- .filter((field) => field.directFilter === false)
- .map((field) => field.filterColumn ?? field.id);
-
-const BUILDER_OPTION_COLUMNS = [
- "environment",
- "name",
- "traceTags",
- "traceName",
- "calledToolNames",
-] as const;
-
-function authoredTraceFilters(filters: FilterState): FilterState {
- return filters.flatMap((filter) => {
- if (filter.column === "isRootObservation") return [];
- if (filter.column === "tags")
- return [{ ...filter, column: "traceTags" as const }];
- return [filter];
- });
-}
-
-function matchCountLabel(count: number | null) {
- if (count === null) return null;
- const noun = count === 1 ? "match" : "matches";
- return `(${count} ${noun})`;
-}
-
-function previewStatus(
- pending: boolean,
- error: string | undefined,
- rowCount: number,
-) {
- if (pending) return "Loading traces…";
- if (error) return error;
- if (rowCount === 0) return "No traces match this filter in the last 7 days.";
- return null;
-}
-
-function RuleScope({
- projectId,
- filters,
- onFiltersChange,
-}: {
- projectId?: string;
- filters: FilterState;
- onFiltersChange: (filters: FilterState) => void;
-}) {
- if (!projectId)
- return (
- <SampleTraceScope filters={filters} onFiltersChange={onFiltersChange} />
- );
- return (
- <ProjectTraceScope
- projectId={projectId}
- filters={filters}
- onFiltersChange={onFiltersChange}
- />
- );
-}
-
-function SampleTraceScope({
- filters,
- onFiltersChange,
-}: {
- filters: FilterState;
- onFiltersChange: (filters: FilterState) => void;
-}) {
- return (
- <TraceScopeFrame
- projectId={undefined}
- filters={filters}
- onFiltersChange={onFiltersChange}
- countLabel="Sample"
- rows={SAMPLE_TRACES_IN_SCOPE}
- />
- );
-}
-
-function ProjectTraceScope({
- projectId,
- filters,
- onFiltersChange,
-}: {
- projectId: string;
- filters: FilterState;
- onFiltersChange: (filters: FilterState) => void;
-}) {
- const [range] = useState(() => relativeTopicTimeRange(7));
- const [mode, setMode] = useState<EvaluatorFilterExperience>("query");
- const [searchQuery, setSearchQuery] = useState<string | null>(null);
- const [searchType, setSearchType] = useState<TracingSearchType[]>([]);
- const startTimeFilter = useMemo<TimeFilter[]>(
- () => [
- {
- column: "startTime",
- type: "datetime",
- operator: ">=",
- value: range.from,
- },
- {
- column: "startTime",
- type: "datetime",
- operator: "<",
- value: range.to,
- },
- ],
- [range],
- );
- const authored = useMemo(() => authoredTraceFilters(filters), [filters]);
- const options = useEventsFilterOptions({
- projectId,
- startTimeFilter,
- refiningFilter: authored,
- isRootObservation: true,
- includeApproxCount: true,
- lazy: mode === "query",
- columns: mode === "query" ? undefined : [...BUILDER_OPTION_COLUMNS],
- enabled: true,
- });
- const observed = useMemo(
- () =>
- toObservedOptions(options.filterOptions, options.isFilterOptionsPending),
- [options.filterOptions, options.isFilterOptionsPending],
- );
- const previewFilters = useMemo<FilterState>(
- () => [
- ...authored,
- {
- column: "isRootObservation",
- type: "boolean",
- operator: "=",
- value: true,
- },
- ...startTimeFilter,
- ],
- [authored, startTimeFilter],
- );
- const preview = api.events.listCursor.useQuery({
- projectId,
- filter: previewFilters,
- searchQuery,
- searchType,
- limit: 10,
- });
- const observations = preview.data?.observations ?? [];
- const ioTargets = observations.flatMap((observation) =>
- observation.traceId
- ? [{ id: observation.id, traceId: observation.traceId }]
- : [],
- );
- const startTimes = observations.map((observation) =>
- observation.startTime.getTime(),
- );
- const io = api.events.batchIO.useQuery(
- {
- projectId,
- observations: ioTargets,
- minStartTime: new Date(
- startTimes.length > 0 ? Math.min(...startTimes) : 0,
- ),
- maxStartTime: new Date(
- startTimes.length > 0 ? Math.max(...startTimes) : 0,
- ),
- },
- {
- ...sendAsPostOption,
- enabled: preview.isSuccess && ioTargets.length > 0,
- },
- );
- const inputById = new Map((io.data ?? []).map((row) => [row.id, row.input]));
- const builderColumns = useMemo(
- () =>
- experimentEvalFilterColsWithOptions(
- options.filterOptions,
- observationEvalFilterColsWithOptions(
- {
- ...options.filterOptions,
- tags: options.filterOptions?.traceTags,
- },
- [...eventsEvalFilterColumns],
- ),
- ).flatMap((column) =>
- column.id === "isRootObservation" ? [] : [column],
- ),
- [options.filterOptions],
- );
- const rows = observations.map((observation) => ({
- id: observation.id,
- start: format(observation.startTime, "yyyy-MM-dd HH:mm:ss"),
- type: observation.type,
- name: observation.name ?? "—",
- input: inputById.get(observation.id) ?? (io.isPending ? "…" : ""),
- }));
- const status = previewStatus(
- preview.isPending,
- preview.error?.message,
- rows.length,
- );
-
- return (
- <TraceScopeFrame
- projectId={projectId}
- mode={mode}
- filters={filters}
- searchQuery={searchQuery}
- observed={observed}
- builderColumns={builderColumns}
- erroredColumns={options.erroredColumns}
- onRequestColumns={options.requestColumns}
- countLabel={matchCountLabel(options.approxTotalCount)}
- description="Root observations from the last 7 days. Topics summarizes the whole trace."
- tooltip="The same filter Topics uses when it selects traces, limited to the last 7 days. Only root observations are shown."
- rows={rows}
- status={status}
- searchType={searchType}
- onModeChange={setMode}
- onFiltersChange={onFiltersChange}
- onSearchQueryChange={setSearchQuery}
- onSearchTypeChange={setSearchType}
- />
- );
-}
-
-function TraceScopeFrame({
- projectId,
- mode: modeProp,
- filters: filtersProp,
- searchQuery: searchQueryProp,
- searchType: searchTypeProp,
- observed,
- builderColumns,
- erroredColumns,
- onRequestColumns,
- countLabel,
- description,
- tooltip,
- rows,
- status,
- onModeChange,
- onFiltersChange,
- onSearchQueryChange,
- onSearchTypeChange,
-}: {
- projectId?: string;
- mode?: EvaluatorFilterExperience;
- filters?: FilterState;
- searchQuery?: string | null;
- searchType?: TracingSearchType[];
- observed?: ReturnType<typeof toObservedOptions>;
- builderColumns?: ReturnType<typeof experimentEvalFilterColsWithOptions>;
- erroredColumns?: ReadonlySet<string>;
- onRequestColumns?: (columns: readonly string[]) => void;
- countLabel?: string | null;
- description?: string;
- tooltip?: string;
- rows: Array<{
- id?: string;
- start: string;
- type: string;
- name: string;
- input: string;
- }>;
- status?: string | null;
- onModeChange?: (mode: EvaluatorFilterExperience) => void;
- onFiltersChange?: (filters: FilterState) => void;
- onSearchQueryChange?: (query: string | null) => void;
- onSearchTypeChange?: (searchType: TracingSearchType[]) => void;
-}) {
- const [localMode, setLocalMode] =
- useState<EvaluatorFilterExperience>("query");
- const [localFilters, setLocalFilters] = useState<FilterState>([]);
- const [localSearchQuery, setLocalSearchQuery] = useState<string | null>(null);
- const [localSearchType, setLocalSearchType] = useState<TracingSearchType[]>(
- [],
- );
- const mode = modeProp ?? localMode;
- const filters = filtersProp ?? localFilters;
- const searchQuery = searchQueryProp ?? localSearchQuery;
- const searchType = searchTypeProp ?? localSearchType;
- const setMode = onModeChange ?? setLocalMode;
- const setFilters = onFiltersChange ?? setLocalFilters;
- const setSearchQuery = onSearchQueryChange ?? setLocalSearchQuery;
- const setSearchType = onSearchTypeChange ?? setLocalSearchType;
- const search = useEventsSearchBar({
- projectId,
- tableName: "topics-setup",
- enabled: true,
- filterState: filters,
- searchQuery,
- searchType,
- observed,
- setFilterState: setFilters,
- setSearchQuery,
- setSearchType,
- registry: topicsFilterRegistry,
- });
-
- return (
- <div className="flex flex-col gap-4">
- <section className="flex flex-col gap-2">
- <SectionHeader
- title="Filter traces"
- meta={<Badge text="Coming soon" color="blue" size="sm" />}
- description="Topics processes every trace for now; custom trace filters are coming soon."
- tooltip="Only traces matching this filter will be summarized. Topics always runs on whole traces."
- trailing={
- <div inert className="opacity-50">
- <FilterModeToggle
- mode={mode}
- onChange={(next) => {
- if (next === "builder" && searchQuery !== null)
- search.applyFilters(filters);
- setMode(next);
- }}
- />
- </div>
- }
- />
- <div inert aria-disabled className="opacity-50">
- {mode === "query" ? (
- <EventsSearchBarRow
- projectId={projectId}
- tableName="topics-setup"
- store={search.store}
- commit={search.commit}
- observed={observed}
- erroredColumns={erroredColumns}
- registry={topicsFilterRegistry}
- onApplyFilters={search.applyFilters}
- onRequestColumns={onRequestColumns}
- className="p-0"
- />
- ) : (
- <ObservationFilterBuilder
- columns={builderColumns ?? [...topicsFilterRegistry.columns]}
- filterState={filters}
- onChange={setFilters}
- queryOnlyColumnIds={queryOnlyColumnIds}
- />
- )}
- </div>
- </section>
- <section className="flex flex-col gap-2">
- <SectionHeader
- title="Matching traces"
- meta={
- countLabel ? (
- <span className="text-muted-foreground text-sm">
- {countLabel}
- </span>
- ) : null
- }
- description={
- description ?? "A sample of traces this setup would include."
- }
- tooltip={
- tooltip ??
- "A fixed sample. The filter is applied when traces are processed, not in this table."
- }
- trailing={null}
- />
- <div className="max-h-72 overflow-auto rounded-md border">
- <table className="w-full text-left text-sm">
- <thead className="text-muted-foreground bg-background sticky top-0">
- <tr className="border-b">
- <th className="px-3 py-2 font-normal">Start time</th>
- <th className="px-3 py-2 font-normal">Type</th>
- <th className="px-3 py-2 font-normal">Name</th>
- <th className="px-3 py-2 font-normal">Input</th>
- </tr>
- </thead>
- <tbody>
- {status ? (
- <tr>
- <td className="text-muted-foreground px-3 py-2" colSpan={4}>
- {status}
- </td>
- </tr>
- ) : (
- rows.map((row) => (
- <tr
- key={row.id ?? `${row.start}-${row.name}`}
- className="border-b last:border-b-0"
- >
- <td className="px-3 py-2 whitespace-nowrap">{row.start}</td>
- <td className="px-3 py-2">{row.type}</td>
- <td className="px-3 py-2">{row.name}</td>
- <td
- className="text-muted-foreground max-w-48 truncate px-3 py-2"
- title={row.input}
- >
- {row.input}
- </td>
- </tr>
- ))
- )}
- </tbody>
- </table>
- </div>
- </section>
- </div>
- );
-}
-
function PausedNotice({
message,
onConfigureProviders,
diff --git a/web/src/features/topics/ConfigureTopicsDialogController.tsx b/web/src/features/topics/ConfigureTopicsDialogController.tsx
index 1f9c0caffc..9173c3605a 100644
--- a/web/src/features/topics/ConfigureTopicsDialogController.tsx
+++ b/web/src/features/topics/ConfigureTopicsDialogController.tsx
@@ -255,7 +255,6 @@ function ConfigureTopicsSettings({
return (
<ConfigureTopicsDialog
- projectId={projectId}
providerGroups={providerGroups}
embeddingProviderGroups={embeddingGroups}
draft={draft}
diff --git a/web/src/features/topics/CurrentTopics.clienttest.ts b/web/src/features/topics/CurrentTopics.clienttest.ts
index 5984bd69cc..08e530d1f4 100644
--- a/web/src/features/topics/CurrentTopics.clienttest.ts
+++ b/web/src/features/topics/CurrentTopics.clienttest.ts
@@ -45,7 +45,9 @@ describe("current Topics query", () => {
awaitingCount: 0,
usableCount: 0,
};
- fetchResults.mockReset().mockResolvedValue([facet]);
+ fetchResults
+ .mockReset()
+ .mockResolvedValue({ hasStoredSummaries: false, facets: [facet] });
const props = {
projectId: "project",
running: true,
@@ -59,9 +61,17 @@ describe("current Topics query", () => {
});
await act(() => vi.advanceTimersByTimeAsync(0));
expect(fetchResults).toHaveBeenCalledOnce();
- expect(view.result.current.data).toEqual([facet]);
+ expect(view.result.current.data).toEqual({
+ hasStoredSummaries: false,
+ facets: [facet],
+ });
- let finishOldPoll: ((rows: (typeof facet)[]) => void) | undefined;
+ let finishOldPoll:
+ | ((rows: {
+ hasStoredSummaries: boolean;
+ facets: (typeof facet)[];
+ }) => void)
+ | undefined;
fetchResults.mockImplementationOnce(
() =>
new Promise((resolve) => {
@@ -87,15 +97,21 @@ describe("current Topics query", () => {
],
},
];
- fetchResults.mockResolvedValue(completed);
+ fetchResults.mockResolvedValue({
+ hasStoredSummaries: true,
+ facets: completed,
+ });
vi.setSystemTime(Date.now() + 1000);
view.rerender({ ...props, running: false, refreshAfter: Date.now() });
await act(async () => {
- finishOldPoll?.([facet]);
+ finishOldPoll?.({ hasStoredSummaries: false, facets: [facet] });
});
await act(() => vi.advanceTimersByTimeAsync(3001));
expect(fetchResults).toHaveBeenCalledTimes(3);
- expect(view.result.current.data).toEqual(completed);
+ expect(view.result.current.data).toEqual({
+ hasStoredSummaries: true,
+ facets: completed,
+ });
await act(() => vi.advanceTimersByTimeAsync(9000));
expect(fetchResults).toHaveBeenCalledTimes(3);
@@ -110,4 +126,29 @@ describe("current Topics query", () => {
});
expect(fetchResults).toHaveBeenCalledTimes(4);
});
+ it("polls waiting automatic processing at ten seconds and stops once ready", async () => {
+ fetchResults
+ .mockReset()
+ .mockResolvedValue({ hasStoredSummaries: false, facets: [] });
+ renderHook(__test.useCurrentTopics, {
+ initialProps: {
+ projectId: "project",
+ running: false,
+ pollForSummaries: true,
+ refreshAfter: 0,
+ timeRange,
+ },
+ wrapper: ({ children }: { children: ReactNode }) =>
+ createElement(QueryClientProvider, { client }, children),
+ });
+ await act(() => vi.advanceTimersByTimeAsync(0));
+ expect(fetchResults).toHaveBeenCalledOnce();
+ await act(() => vi.advanceTimersByTimeAsync(9999));
+ expect(fetchResults).toHaveBeenCalledOnce();
+ fetchResults.mockResolvedValue({ hasStoredSummaries: true, facets: [] });
+ await act(() => vi.advanceTimersByTimeAsync(1));
+ expect(fetchResults).toHaveBeenCalledTimes(2);
+ await act(() => vi.advanceTimersByTimeAsync(30000));
+ expect(fetchResults).toHaveBeenCalledTimes(2);
+ });
});
diff --git a/web/src/features/topics/CurrentTopics.tsx b/web/src/features/topics/CurrentTopics.tsx
index 04bd4b6f70..dab70d0b99 100644
--- a/web/src/features/topics/CurrentTopics.tsx
+++ b/web/src/features/topics/CurrentTopics.tsx
@@ -1,3 +1,4 @@
+import { useSession } from "next-auth/react";
import type { TopicTimeRange } from "@langfuse/shared/topics";
import { Alert } from "@/src/components/design-system/Alert/Alert";
import { cn } from "@/src/utils/tailwind";
@@ -19,11 +20,14 @@ export function CurrentTopics({
selectedFacetId,
tracePanelRef,
traceFilters,
+ onGenerateTopics,
+ canGenerateTopics,
}: CurrentTopicsProps) {
- const selectedFacet = result.data?.find(
+ const selectedFacet = result.data?.facets.find(
(facet) => facet.facetId === selectedFacetId,
);
- const empty = !result.isLoading && !result.error && result.data?.length === 0;
+ const empty =
+ !result.isLoading && !result.error && result.data?.facets.length === 0;
return (
<section
className={cn(
@@ -47,6 +51,8 @@ export function CurrentTopics({
timeRange={timeRange}
tracePanelRef={tracePanelRef}
traceFilters={traceFilters}
+ onGenerateTopics={onGenerateTopics}
+ canGenerateTopics={canGenerateTopics}
/>
)}
</section>
@@ -59,7 +65,10 @@ function CurrentFacet({
timeRange,
tracePanelRef,
traceFilters,
+ onGenerateTopics,
+ canGenerateTopics,
}: CurrentFacetProps) {
+ const { data: session } = useSession();
const mapResult = useCurrentTopicMap(projectId, facet.map?.runId, timeRange);
const peekNavigation = usePeekNavigation({
tableName: "topics-traces",
@@ -93,7 +102,10 @@ function CurrentFacet({
mapResult={mapResult}
tracePanelRef={tracePanelRef}
traceFilters={traceFilters}
+ onGenerateTopics={onGenerateTopics}
+ canGenerateTopics={canGenerateTopics}
onOpenTrace={peekNavigation.openPeek}
+ canInspectTranscript={session?.user?.admin === true}
onInspectTranscript={openDialog}
peekView={peekView}
/>
@@ -105,11 +117,13 @@ function CurrentFacet({
export function useCurrentTopics({
projectId,
running,
+ pollForSummaries = false,
refreshAfter,
timeRange,
}: {
projectId: string;
running: boolean;
+ pollForSummaries?: boolean;
refreshAfter: number;
timeRange: TopicTimeRange;
}) {
@@ -127,7 +141,12 @@ export function useCurrentTopics({
queryFn: ({ signal }) =>
client.topics.currentResults.query({ projectId, timeRange }, { signal }),
placeholderData: keepPreviousData,
- refetchInterval: running ? 3000 : false,
+ refetchInterval: (query) => {
+ if (running) return 3000;
+ return pollForSummaries && !query.state.data?.hasStoredSummaries
+ ? 10000
+ : false;
+ },
enabled: isValidTopicTimeRange(timeRange),
meta: { toastOperation: "topics.load" },
});
@@ -154,6 +173,8 @@ type CurrentTopicsProps = {
selectedFacetId: string | undefined;
tracePanelRef?: (element: HTMLElement | null) => void;
traceFilters: ReturnType<typeof useTopicTraceFilters>;
+ onGenerateTopics: () => void;
+ canGenerateTopics: boolean;
};
type CurrentFacetProps = {
@@ -162,9 +183,11 @@ type CurrentFacetProps = {
timeRange: TopicTimeRange;
tracePanelRef?: (element: HTMLElement | null) => void;
traceFilters: ReturnType<typeof useTopicTraceFilters>;
+ onGenerateTopics: () => void;
+ canGenerateTopics: boolean;
};
-type Facet = RouterOutputs["topics"]["currentResults"][number];
+type Facet = RouterOutputs["topics"]["currentResults"]["facets"][number];
type SummarySource = Pick<
Facet["rows"][number],
"traceId" | "facetVersion" | "unitStartTime"
diff --git a/web/src/features/topics/CurrentTopicsView.stories.tsx b/web/src/features/topics/CurrentTopicsView.stories.tsx
index 8ec454b5e5..95f99c2627 100644
--- a/web/src/features/topics/CurrentTopicsView.stories.tsx
+++ b/web/src/features/topics/CurrentTopicsView.stories.tsx
@@ -60,7 +60,10 @@ const defaultArgs: ComponentProps<typeof CurrentTopicsView> = {
setSearchQuery: fn(),
},
onOpenTrace: fn(),
+ onGenerateTopics: fn(),
+ canGenerateTopics: true,
onInspectTranscript: fn(),
+ canInspectTranscript: false,
peekView: {
itemType: "TRACE",
tableName: "topics-current-traces",
@@ -261,3 +264,63 @@ async function afterPaint() {
}
type ControlledTopicsProps = ComponentProps<typeof CurrentTopicsView>;
+
+export const SummariesWithoutTopics = meta.story({
+ name: "(Test) Summaries without topics open generation",
+ args: {
+ facet: {
+ ...facet,
+ map: null,
+ topics: [],
+ rows: rows.map((row) => ({
+ ...row,
+ topicId: null,
+ topicName: null,
+ outcome: "awaiting_map",
+ })),
+ },
+ },
+ play: async ({ canvasElement, args }) => {
+ const canvas = within(canvasElement);
+ await expect(
+ canvas.queryByRole("button", { name: "Debug transcript" }),
+ ).not.toBeInTheDocument();
+ await expect(
+ canvas.getByRole("region", { name: "Topic traces" }),
+ ).toBeVisible();
+ await userEvent.click(
+ canvas.getByRole("button", { name: "Generate topics" }),
+ );
+ await expect(args.onGenerateTopics).toHaveBeenCalledOnce();
+ },
+});
+
+export const InternalAdminTranscript = meta.story({
+ name: "(Test) Langfuse admins can debug transcripts",
+ args: { canInspectTranscript: true },
+ play: async ({ canvasElement, args }) => {
+ const canvas = within(canvasElement);
+ await userEvent.click(
+ canvas.getAllByRole("button", { name: "Debug transcript" })[0],
+ );
+ await expect(args.onInspectTranscript).toHaveBeenCalledWith({
+ traceId: "trace-0",
+ facetVersion: 1,
+ unitStartTime: "2026-10-01T00:00:00.000Z",
+ });
+ },
+});
+
+export const ExistingTopicsWithoutAssignments = meta.story({
+ name: "(Test) Empty range keeps existing topics without prompting regeneration",
+ args: { facet: { ...facet, topics: [], rows: [] } },
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ await expect(
+ canvas.queryByRole("button", { name: "Generate topics" }),
+ ).not.toBeInTheDocument();
+ await expect(
+ canvas.getByRole("region", { name: "Topic traces" }),
+ ).toBeVisible();
+ },
+});
diff --git a/web/src/features/topics/CurrentTopicsView.tsx b/web/src/features/topics/CurrentTopicsView.tsx
index 62ad724a81..07fe9eeecf 100644
--- a/web/src/features/topics/CurrentTopicsView.tsx
+++ b/web/src/features/topics/CurrentTopicsView.tsx
@@ -27,9 +27,12 @@ export function CurrentTopicsView({
mapResult,
onOpenTrace,
onInspectTranscript,
+ canInspectTranscript,
peekView,
tracePanelRef,
traceFilters,
+ onGenerateTopics,
+ canGenerateTopics,
}: CurrentTopicsViewProps) {
const [selectedTraceId, setSelectedTraceId] = useState<string | null>(null);
const isNarrow = useMediaQuery({ query: "(max-width: 1023px)" });
@@ -83,13 +86,6 @@ export function CurrentTopicsView({
topics.map((topic) => topic.id),
),
);
- const counts = (
- <p className="text-muted-foreground text-xs">
- {facet.rows.length.toLocaleString()} traces · {facet.topics.length} topics
- {facet.awaitingCount > 0 &&
- ` · ${facet.awaitingCount.toLocaleString()} awaiting a map or updated assignment`}
- </p>
- );
const mapPanel = (
<section
aria-label="Topic map"
@@ -114,24 +110,31 @@ export function CurrentTopicsView({
}
fillContainer
/>
- ) : (
- <div className="flex flex-col gap-1 rounded-md border p-2">
- {counts}
- <p className="text-muted-foreground text-xs">
- {facet.usableCount.toLocaleString()} usable summaries collected for
- v{facet.facetVersion ?? 1}. Run Update topics to cluster stored
- summaries. You can configure the minimum there.
- </p>
- </div>
- )}
+ ) : null}
</section>
);
+ const emptyTopics = (
+ <div className="flex flex-1 flex-col items-center justify-center gap-3 p-6 text-center">
+ <h3 className="text-lg font-bold">Find patterns in your summaries</h3>
+ <p className="text-muted-foreground max-w-sm text-sm">
+ Generate topics to group similar summaries and discover recurring themes
+ for this facet. Choose a time range and the facets to include in Manual
+ processing.
+ </p>
+ <Button
+ text="Generate topics"
+ size="sm"
+ disabled={!canGenerateTopics}
+ onClick={onGenerateTopics}
+ />
+ </div>
+ );
const groupsPanel = (
<section
aria-label="Topic groups"
className="flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden rounded-md border"
>
- <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain p-2">
+ <div className="flex min-h-0 flex-1 flex-col overflow-y-auto overscroll-contain p-2">
<div className="grid gap-2 sm:grid-cols-2 lg:grid-cols-1 xl:grid-cols-2">
{facet.topics.map((topic) => (
<TopicGroupCard
@@ -145,12 +148,15 @@ export function CurrentTopicsView({
/>
))}
</div>
- {facet.topics.length === 0 && (
- <p className="text-muted-foreground text-xs">
- No topics yet. Inspect the collected summaries or update topics to
- find recurring groups.
- </p>
- )}
+ {facet.topics.length === 0 &&
+ (facet.map?.topics.length ? (
+ <p className="text-muted-foreground p-6 text-center text-sm">
+ No topic assignments in this time range. Choose a different time
+ range to explore existing topics.
+ </p>
+ ) : (
+ emptyTopics
+ ))}
</div>
</section>
);
@@ -158,7 +164,10 @@ export function CurrentTopicsView({
<section
aria-label="Topic traces"
ref={isNarrow ? undefined : tracePanelRef}
- className="flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden rounded-md border lg:col-start-2 lg:row-span-2 lg:row-start-1"
+ className={cn(
+ "flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden rounded-md border lg:col-start-2 lg:row-start-1",
+ facet.map && "lg:row-span-2",
+ )}
>
<TopicsTraceToolbar
projectId={projectId}
@@ -173,6 +182,7 @@ export function CurrentTopicsView({
projectId={projectId}
onOpenTrace={onOpenTrace}
onInspectTranscript={onInspectTranscript}
+ canInspectTranscript={canInspectTranscript}
peekView={peekView}
rows={visible}
totalCount={facet.rows.length}
@@ -188,10 +198,10 @@ export function CurrentTopicsView({
"grid min-h-0 min-w-0 flex-1 gap-2 overflow-hidden lg:grid-cols-2",
facet.map
? "grid-rows-[minmax(0,9fr)_minmax(0,11fr)] lg:grid-rows-[minmax(0,3fr)_minmax(0,2fr)]"
- : "grid-rows-[auto_minmax(0,1fr)]",
+ : "grid-rows-[minmax(0,1fr)]",
)}
>
- {mapPanel}
+ {facet.map && mapPanel}
{isNarrow ? (
<Tabs
value={mobilePanel}
@@ -231,6 +241,7 @@ function CurrentTraceTable({
projectId,
onOpenTrace,
onInspectTranscript,
+ canInspectTranscript,
peekView,
rows,
totalCount,
@@ -324,12 +335,14 @@ function CurrentTraceTable({
<p className="break-words whitespace-pre-wrap">
{row.original.summary || "No applicable summary."}
</p>
- <Button
- text="Debug transcript"
- variant="secondary"
- size="sm"
- onClick={inspectTranscript}
- />
+ {canInspectTranscript && (
+ <Button
+ text="Debug transcript"
+ variant="secondary"
+ size="sm"
+ onClick={inspectTranscript}
+ />
+ )}
</div>
);
},
@@ -372,6 +385,7 @@ type CurrentTraceTableProps = {
projectId: string;
onOpenTrace: (traceId: string) => void;
onInspectTranscript: (source: SummarySource) => void;
+ canInspectTranscript: boolean;
peekView: DataTablePeekViewProps;
rows: Facet["rows"];
totalCount: number;
@@ -383,6 +397,8 @@ type CurrentTraceTableProps = {
type CurrentTopicsViewProps = {
projectId: string;
facet: Facet;
+ onGenerateTopics: () => void;
+ canGenerateTopics: boolean;
mapResult: ComponentProps<typeof TopicEmbeddingMap>["query"];
tracePanelRef?: (element: HTMLElement | null) => void;
traceFilters: {
@@ -393,10 +409,11 @@ type CurrentTopicsViewProps = {
};
onOpenTrace: (traceId: string) => void;
onInspectTranscript: (source: SummarySource) => void;
+ canInspectTranscript: boolean;
peekView: DataTablePeekViewProps;
};
-type Facet = RouterOutputs["topics"]["currentResults"][number];
+type Facet = RouterOutputs["topics"]["currentResults"]["facets"][number];
type SummarySource = Pick<
Facet["rows"][number],
"traceId" | "facetVersion" | "unitStartTime"
diff --git a/web/src/features/topics/ManualTopicsFormContent.tsx b/web/src/features/topics/ManualTopicsFormContent.tsx
index 2ec9a18f1d..fe6d468d10 100644
--- a/web/src/features/topics/ManualTopicsFormContent.tsx
+++ b/web/src/features/topics/ManualTopicsFormContent.tsx
@@ -12,6 +12,7 @@ import { ManualTopicsDialog } from "./ManualTopicsDialog";
import { manualTopicsSelection } from "./manual-topics-selection";
export function ManualTopicsFormContent({
+ initialOperation = "process",
projectId,
canWrite,
generationTimeRange,
@@ -29,7 +30,7 @@ export function ManualTopicsFormContent({
}: ManualTopicsFormContentProps) {
const form = useForm<ManualTopicsDraft>({
defaultValues: {
- operation: "process",
+ operation: initialOperation,
selectionIntent: null,
reuse: true,
smallSample: false,
@@ -221,6 +222,7 @@ export function ManualTopicsFormContent({
}
type ManualTopicsFormContentProps = {
+ initialOperation?: TopicOperation;
projectId: string;
canWrite: boolean;
generationTimeRange: TimeRange;
diff --git a/web/src/features/topics/TopicAutomaticTraceScope.tsx b/web/src/features/topics/TopicAutomaticTraceScope.tsx
new file mode 100644
index 0000000000..e7347a2736
--- /dev/null
+++ b/web/src/features/topics/TopicAutomaticTraceScope.tsx
@@ -0,0 +1,462 @@
+import { useMemo, useState } from "react";
+import { format } from "date-fns";
+import { Badge } from "@/src/components/design-system/Badge/Badge";
+import { ObservationFilterBuilder } from "@/src/features/evals/v2/components/Evaluators/Testing/components/SampleObservationSelectorBase/components/ObservationFilterBuilder/ObservationFilterBuilder";
+import { FilterModeToggle } from "@/src/features/evals/v2/components/Evaluators/Testing/components/SampleObservationSelectorBase/components/FilterModeToggle";
+import { RULE_FIELD_REGISTRY } from "@/src/features/evals/v2/constants/ruleSearchRegistry";
+import {
+ EventsSearchBarRow,
+ toObservedOptions,
+ useEventsSearchBar,
+} from "@/src/features/search-bar";
+import { SectionHeader } from "@/src/features/evals/v2/components/Evaluators/Testing/components/SectionHeader/SectionHeader";
+import type { EvaluatorFilterExperience } from "@/src/features/evals/v2/types/evaluatorFilterExperience";
+import {
+ eventsEvalFilterColumns,
+ experimentEvalFilterColsWithOptions,
+ observationEvalFilterColsWithOptions,
+ type FilterState,
+ type TimeFilter,
+ type TracingSearchType,
+} from "@langfuse/shared";
+import { useEventsFilterOptions } from "@/src/features/events/hooks/useEventsFilterOptions";
+import { api, sendAsPostOption } from "@/src/utils/api";
+import { relativeTopicTimeRange } from "./time-range";
+
+const SAMPLE_TRACES_IN_SCOPE = [
+ {
+ start: "2026-10-08 15:58:44",
+ type: "GENERATION",
+ name: "billing-question",
+ input: '{"role":"user","content":"My subscription invoice..."}',
+ },
+ {
+ start: "2026-10-08 15:58:43",
+ type: "GENERATION",
+ name: "weather-question",
+ input: '{"role":"user","content":"I\'m visiting Lisbon this..."}',
+ },
+ {
+ start: "2026-10-08 15:54:02",
+ type: "SPAN",
+ name: "weather-question",
+ input: '{"role":"user","content":"What is the weather in..."}',
+ },
+];
+
+const topicsFilterRegistry = {
+ ...RULE_FIELD_REGISTRY,
+ aiFilterPrompt: true,
+ fields: RULE_FIELD_REGISTRY.fields.filter(
+ (field) => field.id !== "isRootObservation",
+ ),
+ columns: RULE_FIELD_REGISTRY.columns.filter(
+ (column) => column.id !== "isRootObservation",
+ ),
+};
+
+const queryOnlyColumnIds = topicsFilterRegistry.fields
+ .filter((field) => field.directFilter === false)
+ .map((field) => field.filterColumn ?? field.id);
+
+const BUILDER_OPTION_COLUMNS = [
+ "environment",
+ "name",
+ "traceTags",
+ "traceName",
+ "calledToolNames",
+] as const;
+
+function authoredTraceFilters(filters: FilterState): FilterState {
+ return filters.flatMap((filter) => {
+ if (filter.column === "isRootObservation") return [];
+ if (filter.column === "tags")
+ return [{ ...filter, column: "traceTags" as const }];
+ return [filter];
+ });
+}
+
+function matchCountLabel(count: number | null) {
+ if (count === null) return null;
+ const noun = count === 1 ? "match" : "matches";
+ return `(${count} ${noun})`;
+}
+
+function previewStatus(
+ pending: boolean,
+ error: string | undefined,
+ rowCount: number,
+) {
+ if (pending) return "Loading traces…";
+ if (error) return error;
+ if (rowCount === 0) return "No traces match this filter in the last 7 days.";
+ return null;
+}
+
+export function TopicAutomaticTraceScope({
+ projectId,
+ filters,
+ onFiltersChange,
+}: TopicAutomaticTraceScopeProps) {
+ if (!projectId)
+ return (
+ <SampleTraceScope filters={filters} onFiltersChange={onFiltersChange} />
+ );
+ return (
+ <ProjectTraceScope
+ projectId={projectId}
+ filters={filters}
+ onFiltersChange={onFiltersChange}
+ />
+ );
+}
+
+function SampleTraceScope({
+ filters,
+ onFiltersChange,
+}: {
+ filters: FilterState;
+ onFiltersChange: (filters: FilterState) => void;
+}) {
+ return (
+ <TraceScopeFrame
+ projectId={undefined}
+ filters={filters}
+ onFiltersChange={onFiltersChange}
+ countLabel="Sample"
+ rows={SAMPLE_TRACES_IN_SCOPE}
+ />
+ );
+}
+
+function ProjectTraceScope({
+ projectId,
+ filters,
+ onFiltersChange,
+}: {
+ projectId: string;
+ filters: FilterState;
+ onFiltersChange: (filters: FilterState) => void;
+}) {
+ const [range] = useState(() => relativeTopicTimeRange(7));
+ const [mode, setMode] = useState<EvaluatorFilterExperience>("query");
+ const [searchQuery, setSearchQuery] = useState<string | null>(null);
+ const [searchType, setSearchType] = useState<TracingSearchType[]>([]);
+ const startTimeFilter = useMemo<TimeFilter[]>(
+ () => [
+ {
+ column: "startTime",
+ type: "datetime",
+ operator: ">=",
+ value: range.from,
+ },
+ {
+ column: "startTime",
+ type: "datetime",
+ operator: "<",
+ value: range.to,
+ },
+ ],
+ [range],
+ );
+ const authored = useMemo(() => authoredTraceFilters(filters), [filters]);
+ const options = useEventsFilterOptions({
+ projectId,
+ startTimeFilter,
+ refiningFilter: authored,
+ isRootObservation: true,
+ includeApproxCount: true,
+ lazy: mode === "query",
+ columns: mode === "query" ? undefined : [...BUILDER_OPTION_COLUMNS],
+ enabled: true,
+ });
+ const observed = useMemo(
+ () =>
+ toObservedOptions(options.filterOptions, options.isFilterOptionsPending),
+ [options.filterOptions, options.isFilterOptionsPending],
+ );
+ const previewFilters = useMemo<FilterState>(
+ () => [
+ ...authored,
+ {
+ column: "isRootObservation",
+ type: "boolean",
+ operator: "=",
+ value: true,
+ },
+ ...startTimeFilter,
+ ],
+ [authored, startTimeFilter],
+ );
+ const preview = api.events.listCursor.useQuery({
+ projectId,
+ filter: previewFilters,
+ searchQuery,
+ searchType,
+ limit: 10,
+ });
+ const observations = preview.data?.observations ?? [];
+ const ioTargets = observations.flatMap((observation) =>
+ observation.traceId
+ ? [{ id: observation.id, traceId: observation.traceId }]
+ : [],
+ );
+ const startTimes = observations.map((observation) =>
+ observation.startTime.getTime(),
+ );
+ const io = api.events.batchIO.useQuery(
+ {
+ projectId,
+ observations: ioTargets,
+ minStartTime: new Date(
+ startTimes.length > 0 ? Math.min(...startTimes) : 0,
+ ),
+ maxStartTime: new Date(
+ startTimes.length > 0 ? Math.max(...startTimes) : 0,
+ ),
+ },
+ {
+ ...sendAsPostOption,
+ enabled: preview.isSuccess && ioTargets.length > 0,
+ },
+ );
+ const inputById = new Map((io.data ?? []).map((row) => [row.id, row.input]));
+ const builderColumns = useMemo(
+ () =>
+ experimentEvalFilterColsWithOptions(
+ options.filterOptions,
+ observationEvalFilterColsWithOptions(
+ {
+ ...options.filterOptions,
+ tags: options.filterOptions?.traceTags,
+ },
+ [...eventsEvalFilterColumns],
+ ),
+ ).flatMap((column) =>
+ column.id === "isRootObservation" ? [] : [column],
+ ),
+ [options.filterOptions],
+ );
+ const rows = observations.map((observation) => ({
+ id: observation.id,
+ start: format(observation.startTime, "yyyy-MM-dd HH:mm:ss"),
+ type: observation.type,
+ name: observation.name ?? "—",
+ input: inputById.get(observation.id) ?? (io.isPending ? "…" : ""),
+ }));
+ const status = previewStatus(
+ preview.isPending,
+ preview.error?.message,
+ rows.length,
+ );
+
+ return (
+ <TraceScopeFrame
+ projectId={projectId}
+ mode={mode}
+ filters={filters}
+ searchQuery={searchQuery}
+ observed={observed}
+ builderColumns={builderColumns}
+ erroredColumns={options.erroredColumns}
+ onRequestColumns={options.requestColumns}
+ countLabel={matchCountLabel(options.approxTotalCount)}
+ description="Root observations from the last 7 days. Topics summarizes the whole trace."
+ tooltip="The same filter Topics uses when it selects traces, limited to the last 7 days. Only root observations are shown."
+ rows={rows}
+ status={status}
+ searchType={searchType}
+ onModeChange={setMode}
+ onFiltersChange={onFiltersChange}
+ onSearchQueryChange={setSearchQuery}
+ onSearchTypeChange={setSearchType}
+ />
+ );
+}
+
+function TraceScopeFrame({
+ projectId,
+ mode: modeProp,
+ filters: filtersProp,
+ searchQuery: searchQueryProp,
+ searchType: searchTypeProp,
+ observed,
+ builderColumns,
+ erroredColumns,
+ onRequestColumns,
+ countLabel,
+ description,
+ tooltip,
+ rows,
+ status,
+ onModeChange,
+ onFiltersChange,
+ onSearchQueryChange,
+ onSearchTypeChange,
+}: {
+ projectId?: string;
+ mode?: EvaluatorFilterExperience;
+ filters?: FilterState;
+ searchQuery?: string | null;
+ searchType?: TracingSearchType[];
+ observed?: ReturnType<typeof toObservedOptions>;
+ builderColumns?: ReturnType<typeof experimentEvalFilterColsWithOptions>;
+ erroredColumns?: ReadonlySet<string>;
+ onRequestColumns?: (columns: readonly string[]) => void;
+ countLabel?: string | null;
+ description?: string;
+ tooltip?: string;
+ rows: Array<{
+ id?: string;
+ start: string;
+ type: string;
+ name: string;
+ input: string;
+ }>;
+ status?: string | null;
+ onModeChange?: (mode: EvaluatorFilterExperience) => void;
+ onFiltersChange?: (filters: FilterState) => void;
+ onSearchQueryChange?: (query: string | null) => void;
+ onSearchTypeChange?: (searchType: TracingSearchType[]) => void;
+}) {
+ const [localMode, setLocalMode] =
+ useState<EvaluatorFilterExperience>("query");
+ const [localFilters, setLocalFilters] = useState<FilterState>([]);
+ const [localSearchQuery, setLocalSearchQuery] = useState<string | null>(null);
+ const [localSearchType, setLocalSearchType] = useState<TracingSearchType[]>(
+ [],
+ );
+ const mode = modeProp ?? localMode;
+ const filters = filtersProp ?? localFilters;
+ const searchQuery = searchQueryProp ?? localSearchQuery;
+ const searchType = searchTypeProp ?? localSearchType;
+ const setMode = onModeChange ?? setLocalMode;
+ const setFilters = onFiltersChange ?? setLocalFilters;
+ const setSearchQuery = onSearchQueryChange ?? setLocalSearchQuery;
+ const setSearchType = onSearchTypeChange ?? setLocalSearchType;
+ const search = useEventsSearchBar({
+ projectId,
+ tableName: "topics-automatic-processing",
+ enabled: true,
+ filterState: filters,
+ searchQuery,
+ searchType,
+ observed,
+ setFilterState: setFilters,
+ setSearchQuery,
+ setSearchType,
+ registry: topicsFilterRegistry,
+ });
+
+ return (
+ <div className="flex flex-col gap-4">
+ <section className="flex flex-col gap-2">
+ <SectionHeader
+ title="Filter traces"
+ meta={<Badge text="Coming soon" color="blue" size="sm" />}
+ description="The sampling rate applies to all incoming traces. Custom trace filters are coming soon."
+ tooltip="Only traces matching this filter will be summarized. Topics always runs on whole traces."
+ trailing={
+ <div inert className="opacity-50">
+ <FilterModeToggle
+ mode={mode}
+ onChange={(next) => {
+ if (next === "builder" && searchQuery !== null)
+ search.applyFilters(filters);
+ setMode(next);
+ }}
+ />
+ </div>
+ }
+ />
+ <div inert aria-disabled className="opacity-50">
+ {mode === "query" ? (
+ <EventsSearchBarRow
+ projectId={projectId}
+ tableName="topics-automatic-processing"
+ store={search.store}
+ commit={search.commit}
+ observed={observed}
+ erroredColumns={erroredColumns}
+ registry={topicsFilterRegistry}
+ onApplyFilters={search.applyFilters}
+ onRequestColumns={onRequestColumns}
+ className="p-0"
+ />
+ ) : (
+ <ObservationFilterBuilder
+ columns={builderColumns ?? [...topicsFilterRegistry.columns]}
+ filterState={filters}
+ onChange={setFilters}
+ queryOnlyColumnIds={queryOnlyColumnIds}
+ />
+ )}
+ </div>
+ </section>
+ <section className="flex flex-col gap-2">
+ <SectionHeader
+ title="Matching traces"
+ meta={
+ countLabel ? (
+ <span className="text-muted-foreground text-sm">
+ {countLabel}
+ </span>
+ ) : null
+ }
+ description={
+ description ?? "A sample of traces this setup would include."
+ }
+ tooltip={
+ tooltip ??
+ "A fixed sample. The filter is applied when traces are processed, not in this table."
+ }
+ trailing={null}
+ />
+ <div className="max-h-72 overflow-auto rounded-md border">
+ <table className="w-full text-left text-sm">
+ <thead className="text-muted-foreground bg-background sticky top-0">
+ <tr className="border-b">
+ <th className="px-3 py-2 font-normal">Start time</th>
+ <th className="px-3 py-2 font-normal">Type</th>
+ <th className="px-3 py-2 font-normal">Name</th>
+ <th className="px-3 py-2 font-normal">Input</th>
+ </tr>
+ </thead>
+ <tbody>
+ {status ? (
+ <tr>
+ <td className="text-muted-foreground px-3 py-2" colSpan={4}>
+ {status}
+ </td>
+ </tr>
+ ) : (
+ rows.map((row) => (
+ <tr
+ key={row.id ?? `${row.start}-${row.name}`}
+ className="border-b last:border-b-0"
+ >
+ <td className="px-3 py-2 whitespace-nowrap">{row.start}</td>
+ <td className="px-3 py-2">{row.type}</td>
+ <td className="px-3 py-2">{row.name}</td>
+ <td
+ className="text-muted-foreground max-w-48 truncate px-3 py-2"
+ title={row.input}
+ >
+ {row.input}
+ </td>
+ </tr>
+ ))
+ )}
+ </tbody>
+ </table>
+ </div>
+ </section>
+ </div>
+ );
+}
+
+type TopicAutomaticTraceScopeProps = {
+ projectId?: string;
+ filters: FilterState;
+ onFiltersChange: (filters: FilterState) => void;
+};
diff --git a/web/src/features/topics/TopicEmbeddingMap.tsx b/web/src/features/topics/TopicEmbeddingMap.tsx
index 23b65a3701..88a9819850 100644
--- a/web/src/features/topics/TopicEmbeddingMap.tsx
+++ b/web/src/features/topics/TopicEmbeddingMap.tsx
@@ -65,6 +65,6 @@ type TopicEmbeddingMapProps = {
};
type Topic = Pick<
- RouterOutputs["topics"]["currentResults"][number]["topics"][number],
+ RouterOutputs["topics"]["currentResults"]["facets"][number]["topics"][number],
"id" | "name"
> & { description?: string };
diff --git a/web/src/features/topics/TopicModelSettings.tsx b/web/src/features/topics/TopicModelSettings.tsx
index a7e784062f..cd50d6035e 100644
--- a/web/src/features/topics/TopicModelSettings.tsx
+++ b/web/src/features/topics/TopicModelSettings.tsx
@@ -99,6 +99,7 @@ export function useTopicModelSettings({
automaticProcessing: {
...automaticProcessing,
dialog: {
+ projectId,
rule,
stored: settings.data,
traceIdleMs: readinessSettings.data?.traceIdleMs ?? null,
diff --git a/web/src/features/topics/TopicSetupNotice.stories.tsx b/web/src/features/topics/TopicSetupNotice.stories.tsx
index c2419e4e56..8006e73fab 100644
--- a/web/src/features/topics/TopicSetupNotice.stories.tsx
+++ b/web/src/features/topics/TopicSetupNotice.stories.tsx
@@ -14,3 +14,37 @@ export const Setup = meta.story({
onTurnBackOn: fn(),
},
});
+
+export const ReadyToProcess = meta.story({
+ args: {
+ canWrite: true,
+ canConfigure: true,
+ onConfigure: fn(),
+ onKeepOff: fn(),
+ onTurnBackOn: fn(),
+ notice: { unavailable: false, status: null },
+ showOnboarding: true,
+ configured: true,
+ canProcess: true,
+ onAutomaticProcessing: fn(),
+ onManualProcessing: fn(),
+ },
+});
+
+export const Processing = meta.story({
+ args: {
+ notice: { unavailable: false, status: null },
+ canWrite: true,
+ canConfigure: true,
+ onConfigure: fn(),
+ onKeepOff: fn(),
+ onTurnBackOn: fn(),
+ showOnboarding: true,
+ configured: true,
+ canProcess: true,
+ onAutomaticProcessing: fn(),
+ onManualProcessing: fn(),
+ automaticEnabled: true,
+ running: true,
+ },
+});
diff --git a/web/src/features/topics/TopicSetupNotice.tsx b/web/src/features/topics/TopicSetupNotice.tsx
index 9cfdb080fc..0b01d078c8 100644
--- a/web/src/features/topics/TopicSetupNotice.tsx
+++ b/web/src/features/topics/TopicSetupNotice.tsx
@@ -1,6 +1,7 @@
import { Sparkles } from "lucide-react";
import { Alert } from "@/src/components/design-system/Alert/Alert";
import { Button } from "@/src/components/design-system/Button/Button";
+import { StatusBadge } from "@/src/components/ui/StatusBadge/StatusBadge";
import { SplashScreen } from "@/src/components/ui/splash-screen";
import { type TopicSetupNoticeState } from "./TopicModelSettings";
@@ -11,9 +12,16 @@ type TopicSetupNoticeProps = {
onConfigure: () => void;
onKeepOff: () => void;
onTurnBackOn: () => void;
+ showOnboarding?: boolean;
+ configured?: boolean;
+ canProcess?: boolean;
+ automaticEnabled?: boolean;
+ running?: boolean;
+ onAutomaticProcessing?: () => void;
+ onManualProcessing?: () => void;
};
-/** Setup, paused, and availability notices above the Topics workspace. */
+/** Guides projects to their first summaries and surfaces paused processing. */
export function TopicSetupNotice({
notice,
canWrite,
@@ -21,24 +29,26 @@ export function TopicSetupNotice({
onConfigure,
onKeepOff,
onTurnBackOn,
+ showOnboarding = notice.status?.kind === "setup",
+ configured = false,
+ canProcess = false,
+ automaticEnabled = false,
+ running = false,
+ onAutomaticProcessing,
+ onManualProcessing,
}: TopicSetupNoticeProps) {
const { status } = notice;
+ const processingChoiceDescription = automaticEnabled
+ ? "Automatic processing is on for new traces. You can also summarize existing traces in manual batches."
+ : "Enable automatic processing for incoming traces, or summarize existing traces in manual batches of up to 1,000.";
+ const availableProcessingDescription = running
+ ? "Your traces are being processed. Summaries will appear here as they become available."
+ : processingChoiceDescription;
+ const processingDescription = notice.unavailable
+ ? "Topics processing is not enabled for this project. You can configure Topics, but an administrator needs to enable processing before you can analyze traces."
+ : availableProcessingDescription;
return (
<>
- {notice.unavailable ? (
- <Alert variant="info">
- <Alert.Title>
- Topics processing is not enabled for this project
- </Alert.Title>
- <Alert.Description>
- <p>
- You can configure Topics, but processing traces and automatic
- processing stay unavailable until Topics is enabled for this
- project.
- </p>
- </Alert.Description>
- </Alert>
- ) : null}
{status?.kind === "paused" ? (
<Alert variant="warning">
<Alert.Title>Automatic Topics processing is paused</Alert.Title>
@@ -63,24 +73,41 @@ export function TopicSetupNotice({
</Alert.Description>
</Alert>
) : null}
- {status?.kind === "setup" ? (
- <div className="mx-auto flex w-full max-w-xl flex-col items-center pt-12">
+ {notice.unavailable && !showOnboarding ? (
+ <p role="status" className="text-muted-foreground text-sm">
+ Topics processing is not enabled for this project. Existing summaries
+ and topics remain available.
+ </p>
+ ) : null}
+ {showOnboarding ? (
+ <div className="mx-auto flex w-full max-w-xl flex-col items-center overflow-y-auto pt-12">
<Sparkles
aria-hidden="true"
className="icon-xl text-muted-foreground"
/>
<SplashScreen
- title="Find patterns across your traces"
+ title={
+ configured
+ ? "Start analyzing your traces"
+ : "Find patterns across your traces"
+ }
description="Topics analyzes each trace along the questions you choose, called facets, and clusters similar answers, so you can see what users ask for, how runs end, and which issues come up along the way."
steps={[
{
title: "Configure Topics",
- description:
- "Pick the models Topics runs on and the facets to analyze, such as intent, outcome, and issues.",
+ badge: configured ? (
+ <StatusBadge type="completed" showText={false} isLive={false}>
+ Done
+ </StatusBadge>
+ ) : undefined,
+ description: configured
+ ? "Your project models and facets are ready. You can adjust them at any time."
+ : "Pick the models Topics runs on and the facets to analyze, such as intent, outcome, and issues.",
content: (
<Button
text="Configure Topics"
size="sm"
+ variant={configured ? "secondary" : "primary"}
disabled={!canWrite || !canConfigure}
onClick={onConfigure}
/>
@@ -88,21 +115,26 @@ export function TopicSetupNotice({
},
{
title: "Analyze traces",
- description:
- "After setup, enable automatic processing for incoming traces or summarize existing traces manually.",
+ description: processingDescription,
content: (
<div className="flex flex-wrap gap-2">
<Button
text="Automatic processing"
- variant="secondary"
+ variant={
+ configured && canProcess && !automaticEnabled
+ ? "primary"
+ : "secondary"
+ }
size="sm"
- disabled
+ disabled={!configured || !canProcess}
+ onClick={onAutomaticProcessing}
/>
<Button
text="Summarize traces & embed"
variant="secondary"
size="sm"
- disabled
+ disabled={!configured || !canProcess || running}
+ onClick={onManualProcessing}
/>
</div>
),
@@ -124,7 +156,7 @@ export function TopicSetupNotice({
/>
</div>
) : null}
- {status?.kind === "models" ? (
+ {status?.kind === "models" && !showOnboarding ? (
<Alert variant="info">
<Alert.Title>Choose the models Topics runs on</Alert.Title>
<Alert.Description>
diff --git a/web/src/features/topics/TopicsFilters.tsx b/web/src/features/topics/TopicsFilters.tsx
index 304d93b30a..268a5995fb 100644
--- a/web/src/features/topics/TopicsFilters.tsx
+++ b/web/src/features/topics/TopicsFilters.tsx
@@ -1,3 +1,6 @@
+import { Plus } from "lucide-react";
+import { Badge } from "@/src/components/design-system/Badge/Badge";
+import { Button } from "@/src/components/design-system/Button/Button";
import { type ReactNode } from "react";
import { Tabs } from "@/src/components/design-system/Tabs/Tabs";
import { resolveTopicFacetId } from "./topic-facet-selection";
@@ -23,6 +26,16 @@ export function TopicsFilters({
label={facet.name}
/>
))}
+ <div className="flex shrink-0 items-center gap-2 px-3">
+ <Button
+ text="Custom facet"
+ icon={Plus}
+ variant="ghost"
+ size="sm"
+ disabled
+ />
+ <Badge text="Coming soon" color="blue" size="sm" />
+ </div>
</Tabs.List>
</div>
<Tabs.Content value={selectedFacet} layout="fill">
diff --git a/web/src/features/topics/TopicsPage.clienttest.tsx b/web/src/features/topics/TopicsPage.clienttest.tsx
index 5f6eb63d37..b849b72f5b 100644
--- a/web/src/features/topics/TopicsPage.clienttest.tsx
+++ b/web/src/features/topics/TopicsPage.clienttest.tsx
@@ -22,6 +22,10 @@ const state = vi.hoisted(() => ({
executionId: undefined as string | undefined,
setQueryParams: vi.fn(),
currentTopics: vi.fn(),
+ showGenerateCTA: false,
+ hasStoredSummaries: true,
+ resultsDataAvailable: true,
+ openAutomaticProcessing: vi.fn(),
picker: vi.fn(),
push: vi.fn(),
openConfigure: vi.fn(),
@@ -127,7 +131,6 @@ vi.mock("./TopicTraceSelector", () => ({
reset: vi.fn(),
}),
}));
-vi.mock("./TopicSetupNotice", () => ({ TopicSetupNotice: () => null }));
vi.mock("./ConfigureTopicsDialogController", () => ({
ConfigureTopicsDialogController: ({
children,
@@ -140,7 +143,7 @@ vi.mock("./AutomaticProcessingDialogController", () => ({
children,
}: {
children: (control: { openDialog: () => void }) => ReactNode;
- }) => children({ openDialog: vi.fn() }),
+ }) => children({ openDialog: state.openAutomaticProcessing }),
}));
vi.mock("./CurrentTopics", () => ({
useCurrentTopics: (input: {
@@ -149,18 +152,30 @@ vi.mock("./CurrentTopics", () => ({
timeRange: { from: Date; to: Date };
}) => {
state.currentTopics(input);
- return { ...input, data: [] };
+ return {
+ ...input,
+ data: state.resultsDataAvailable
+ ? { hasStoredSummaries: state.hasStoredSummaries, facets: [] }
+ : undefined,
+ isLoading: false,
+ };
},
CurrentTopics: ({
result,
+ onGenerateTopics,
}: {
result: { running: boolean; refreshAfter: number };
+ onGenerateTopics: () => void;
}) => (
<div
data-testid="current-topics"
data-running={result.running}
data-refresh-after={result.refreshAfter}
- />
+ >
+ {state.showGenerateCTA && (
+ <button onClick={onGenerateTopics}>Generate topics</button>
+ )}
+ </div>
),
}));
vi.mock("@/src/utils/api", () => ({
@@ -302,6 +317,9 @@ beforeEach(() => {
disconnect() {}
},
);
+ state.showGenerateCTA = false;
+ state.resultsDataAvailable = true;
+ state.hasStoredSummaries = true;
state.status = "failed";
state.executionUpdatedAt = 110;
state.updatedAt = "2026-09-23T12:00:00Z";
@@ -1009,3 +1027,57 @@ it.each([
).not.toBeInTheDocument();
},
);
+
+it("guides a configured project through processing until its first stored summary exists", () => {
+ state.hasStoredSummaries = false;
+ const view = render(<TopicsPage />);
+ expect(
+ screen.getByRole("button", { name: "Summarize traces & embed" }),
+ ).toBeEnabled();
+ expect(screen.queryByTestId("current-topics")).toBeNull();
+ fireEvent.click(
+ screen.getAllByRole("button", { name: "Automatic processing" }).at(-1)!,
+ );
+ expect(state.openAutomaticProcessing).toHaveBeenCalledWith(false);
+ fireEvent.click(
+ screen.getByRole("button", { name: "Summarize traces & embed" }),
+ );
+ expect(
+ screen.getByRole("dialog", { name: "Manual processing" }),
+ ).toBeVisible();
+ fireEvent.click(screen.getByRole("button", { name: "Cancel" }));
+ state.hasStoredSummaries = true;
+ view.rerender(<TopicsPage />);
+ expect(screen.getByTestId("current-topics")).toBeVisible();
+ expect(
+ screen.queryByRole("button", { name: "Summarize traces & embed" }),
+ ).toBeNull();
+});
+
+it("opens generation directly from the empty topics panel", () => {
+ withSummaries();
+ state.showGenerateCTA = true;
+ render(<TopicsPage />);
+ fireEvent.click(screen.getByRole("button", { name: "Generate topics" }));
+ const dialog = within(
+ screen.getByRole("dialog", { name: "Manual processing" }),
+ );
+ expect(dialog.getByRole("tab", { name: "Generate topics" })).toHaveAttribute(
+ "aria-selected",
+ "true",
+ );
+ expect(dialog.getByRole("button", { name: "Generate topics" })).toBeEnabled();
+});
+
+it("keeps date controls reachable when a disabled results query has no data", () => {
+ state.resultsDataAvailable = false;
+ state.dateRange = rangeToString({
+ from: new Date("2026-10-10T00:00:00Z"),
+ to: new Date("2026-10-09T00:00:00Z"),
+ });
+ render(<TopicsPage />);
+ expect(
+ screen.getByRole("button", { name: "Select last 30 days" }),
+ ).toBeVisible();
+ expect(screen.queryByText("Start analyzing your traces")).toBeNull();
+});
diff --git a/web/src/features/topics/TopicsPage.tsx b/web/src/features/topics/TopicsPage.tsx
index a6dfa3efee..c659439ca8 100644
--- a/web/src/features/topics/TopicsPage.tsx
+++ b/web/src/features/topics/TopicsPage.tsx
@@ -290,10 +290,14 @@ function TopicsWorkspaceContent({
const results = useCurrentTopics({
projectId,
running,
+ pollForSummaries: modelSettings.automaticProcessing.state.status === "on",
refreshAfter: completedAt,
timeRange: currentTimeRange,
});
- const traceFilters = useTopicTraceFilters(projectId, results.data ?? []);
+ const traceFilters = useTopicTraceFilters(
+ projectId,
+ results.data?.facets ?? [],
+ );
const { selectedFacetId } = traceFilters;
const refreshResults = () => {
setRefreshedAt(Date.now());
@@ -357,22 +361,36 @@ function TopicsWorkspaceContent({
}
return (
- <DialogController
- renderDialog={({ closeDialog }) => (
+ <DialogController<TopicOperation>
+ renderDialog={({ closeDialog, state }) => (
<ManualTopicsFormContent
{...pipeline.dialogProps}
+ initialOperation={state}
closeDialog={closeDialog}
/>
)}
>
{({ openDialog }) => {
- const openManual = () => {
+ const openManual = (operation: TopicOperation) => {
if (!("from" in generationRange.selection))
changeGenerationRange(generationRange.selection);
utils.topics.summaryCounts.invalidate({ projectId });
pipeline.clearError();
- openDialog();
+ openDialog(operation);
};
+ function openManualProcessing() {
+ openManual("process");
+ }
+ function openTopicGeneration() {
+ openManual("update");
+ }
+ const hasStoredSummaries = Boolean(results.data?.hasStoredSummaries);
+ const showOnboarding =
+ validTimeRange &&
+ results.data !== undefined &&
+ !results.isLoading &&
+ !results.error &&
+ !hasStoredSummaries;
return (
<Page
headerProps={{
@@ -388,7 +406,7 @@ function TopicsWorkspaceContent({
configured={configured}
canWrite={canWrite}
manualAvailable={pipeline.available}
- openManual={openManual}
+ openManual={openManualProcessing}
onAutomaticProcessing={openAutomaticProcessingFromHeader}
onConfigure={openConfigure}
onHistory={openHistory}
@@ -407,7 +425,7 @@ function TopicsWorkspaceContent({
? {
label: "Manual processing",
disabled: false,
- onSelect: openManual,
+ onSelect: openManualProcessing,
}
: null
}
@@ -429,16 +447,18 @@ function TopicsWorkspaceContent({
},
}}
>
- <PageHeaderControlsPortal>
- <TimeRangePicker
- timeRange={effectiveTimeRange}
- onTimeRangeChange={setTimeRange}
- timeRangePresets={topicsTimeRangePresets}
- maxRangeMs={maxTimeRangeMs}
- className="my-0 max-w-full overflow-x-auto"
- triggerClassName="px-2"
- />
- </PageHeaderControlsPortal>
+ {!showOnboarding && (
+ <PageHeaderControlsPortal>
+ <TimeRangePicker
+ timeRange={effectiveTimeRange}
+ onTimeRangeChange={setTimeRange}
+ timeRangePresets={topicsTimeRangePresets}
+ maxRangeMs={maxTimeRangeMs}
+ className="my-0 max-w-full overflow-x-auto"
+ triggerClassName="px-2"
+ />
+ </PageHeaderControlsPortal>
+ )}
<div className="ph-no-capture flex min-h-0 flex-1 flex-col gap-2 overflow-hidden p-2">
{isTimeRangeCapped && (
<p
@@ -461,6 +481,13 @@ function TopicsWorkspaceContent({
onConfigure={openConfigure}
onKeepOff={automaticProcessing.clearPause}
onTurnBackOn={turnAutomaticProcessingBackOn}
+ showOnboarding={showOnboarding}
+ configured={configured}
+ canProcess={canWrite && !modelSettings.notice.unavailable}
+ automaticEnabled={automaticProcessing.state.status === "on"}
+ running={running}
+ onAutomaticProcessing={openAutomaticProcessingFromHeader}
+ onManualProcessing={openManualProcessing}
/>
<Sheet
open={historyOpen || executionId !== null}
@@ -532,7 +559,13 @@ function TopicsWorkspaceContent({
</div>
</SheetContent>
</Sheet>
- <div className="flex min-h-0 w-full min-w-0 flex-1 flex-col gap-2 overflow-hidden">
+ <div
+ className={
+ showOnboarding
+ ? "contents"
+ : "flex min-h-0 w-full min-w-0 flex-1 flex-col gap-2 overflow-hidden"
+ }
+ >
<TablePeekViewTraceDetail
{...peekNavigation}
itemType="TRACE"
@@ -540,9 +573,9 @@ function TopicsWorkspaceContent({
defaultWidthTarget={tracePanel}
widthStorageKey="topicsPeekViewWidthFraction"
/>
- {validTimeRange && (
+ {validTimeRange && !showOnboarding && (
<TopicsFilters
- facets={results.data ?? []}
+ facets={results.data?.facets ?? []}
selectedFacetId={selectedFacetId}
onSelectFacet={traceFilters.selectFacet}
>
@@ -553,6 +586,13 @@ function TopicsWorkspaceContent({
selectedFacetId={selectedFacetId}
traceFilters={traceFilters}
tracePanelRef={setTracePanel}
+ onGenerateTopics={openTopicGeneration}
+ canGenerateTopics={
+ canWrite &&
+ !modelSettings.notice.unavailable &&
+ !running &&
+ configured
+ }
/>
</TopicsFilters>
)}
diff --git a/web/src/features/topics/server/currentResults.ts b/web/src/features/topics/server/currentResults.ts
index 94e59ca48b..d462e88c16 100644
--- a/web/src/features/topics/server/currentResults.ts
+++ b/web/src/features/topics/server/currentResults.ts
@@ -7,6 +7,7 @@ import {
getLatestFacetSummaries,
getPublishedTopicRun,
getTopicRuns,
+ hasStoredTopicSummaries,
listTopicFacets,
readLatestTopicAssignments,
} from "@langfuse/shared/topics/server";
@@ -46,7 +47,10 @@ export async function currentTopicResults(
timeRange: TopicTimeRange,
) {
const facets = await listTopicFacets(projectId);
- return Promise.all(
+ const hasStoredSummaries =
+ facets.length > 0 && (await hasStoredTopicSummaries(projectId));
+ if (!hasStoredSummaries) return { hasStoredSummaries, facets: [] };
+ const currentFacets = await Promise.all(
facets.map(async (facet) => {
const version = facet.versions[0];
const [storedAssignments, storedSummaries, run] = await Promise.all([
@@ -164,4 +168,5 @@ export async function currentTopicResults(
};
}),
);
+ return { hasStoredSummaries, facets: currentFacets };
}
diff --git a/web/src/features/topics/server/topicsRouter.ts b/web/src/features/topics/server/topicsRouter.ts
index 072d0f9aff..c3e383b7c3 100644
--- a/web/src/features/topics/server/topicsRouter.ts
+++ b/web/src/features/topics/server/topicsRouter.ts
@@ -1,6 +1,10 @@
import { z } from "zod";
import { createHash } from "node:crypto";
-import { InvalidRequestError, LangfuseNotFoundError } from "@langfuse/shared";
+import {
+ ForbiddenError,
+ InvalidRequestError,
+ LangfuseNotFoundError,
+} from "@langfuse/shared";
import {
getTracingReadinessSettings,
type Transcript,
@@ -569,7 +573,11 @@ export const topicsRouter = createTRPCRouter({
unitStartTime: z.coerce.date(),
}),
)
- .query(async ({ input }) => {
+ .query(async ({ input, ctx }) => {
+ if (ctx.session.user.admin !== true)
+ throw new ForbiddenError(
+ "Transcript debugging is only available to Langfuse admins.",
+ );
const [summary] = await listTopicSummaries(
input.projectId,
{