🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
feat(public-api): add unstable read-only Topics endpoints (#19104)
Lysander Kiesel14986f6bc53b
diff --git a/fern/apis/server/definition/unstable/topics.yml b/fern/apis/server/definition/unstable/topics.ymlnew file mode 100644index 0000000000..c493843d30--- /dev/null+++ b/fern/apis/server/definition/unstable/topics.yml@@ -0,0 +1,231 @@+# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json+imports:+ errors: ./errors.yml+ pagination: ../utils/pagination.yml++service:+ auth: true+ base-path: /api/public/unstable+ endpoints:+ listFacets:+ docs: |+ Unstable: Topics is in closed beta. The shape may change without notice.++ List the project's Topics facets. Only active facets (attached to the+ project's Topics rule, or all facets if the project has no rule) are+ returned unless `filter` contains an `active` condition.++ `filter` is a JSON array of filter conditions combined with AND.+ String matching is case-insensitive. Columns: `id` (stringOptions),+ `name` (string, stringOptions), `description` (string), `isBuiltIn`+ (boolean), `active` (boolean).+ method: GET+ path: /topic-facets+ request:+ name: ListTopicFacetsRequest+ query-parameters:+ filter:+ type: optional<string>+ docs: JSON array of filter conditions, for example `[{"type":"string","column":"name","operator":"contains","value":"issue"}]`.+ page:+ type: optional<integer>+ docs: 1-based page number. Defaults to `1`.+ limit:+ type: optional<integer>+ docs: Maximum number of items per page. Defaults to `50`, at most `100`.+ response: TopicFacetList+ errors:+ - errors.BadRequestError+ - errors.UnauthorizedError+ - errors.AccessDeniedError+ - errors.NotFoundError+ - errors.MethodNotAllowedError+ - errors.TooManyRequestsError+ - errors.InternalServerError+ getFacet:+ docs: |+ Unstable: Topics is in closed beta. The shape may change without notice.++ Get one Topics facet by id, including inactive facets.+ method: GET+ path: /topic-facets/{facetId}+ path-parameters:+ facetId: string+ response: TopicFacet+ errors:+ - errors.BadRequestError+ - errors.UnauthorizedError+ - errors.AccessDeniedError+ - errors.NotFoundError+ - errors.MethodNotAllowedError+ - errors.TooManyRequestsError+ - errors.InternalServerError+ list:+ docs: |+ Unstable: Topics is in closed beta. The shape may change without notice.++ List the topics of each active facet's current published map, with+ the number of traces currently assigned to each topic in the window.+ Retired topics are not listed. `facets` holds per-facet trace counts+ by topic status.++ The window applies to the trace start time. It defaults to the last+ 7 days and can span at most 93 days.++ `filter` is a JSON array of filter conditions combined with AND.+ String matching is case-insensitive. Columns: `facetId`+ (stringOptions), `facetName` (string, stringOptions), `id`+ (stringOptions), `name` (string, stringOptions). Facet conditions also+ restrict `facets`.+ method: GET+ path: /topics+ request:+ name: ListTopicsRequest+ query-parameters:+ fromTimestamp:+ type: optional<datetime>+ docs: Start of the window (trace start time, inclusive). Defaults to 7 days before `toTimestamp`.+ toTimestamp:+ type: optional<datetime>+ docs: End of the window (trace start time, exclusive). Defaults to now.+ filter:+ type: optional<string>+ docs: JSON array of filter conditions, for example `[{"type":"stringOptions","column":"facetName","operator":"any of","value":["Issues"]}]`.+ orderBy:+ type: optional<TopicsOrderBy>+ docs: Defaults to `traceCount.desc`.+ page:+ type: optional<integer>+ docs: 1-based page number. Defaults to `1`.+ limit:+ type: optional<integer>+ docs: Maximum number of items per page. Defaults to `50`, at most `100`.+ response: TopicList+ errors:+ - errors.BadRequestError+ - errors.UnauthorizedError+ - errors.AccessDeniedError+ - errors.NotFoundError+ - errors.MethodNotAllowedError+ - errors.TooManyRequestsError+ - errors.InternalServerError+ get:+ docs: |+ Unstable: Topics is in closed beta. The shape may change without notice.++ Get one topic by its stable id. Topics on the current map are always+ found. A retired topic is found while traces in the window are still+ assigned to it, with `inCurrentMap: false`.+ method: GET+ path: /topics/{topicId}+ path-parameters:+ topicId: string+ request:+ name: GetTopicRequest+ query-parameters:+ fromTimestamp:+ type: optional<datetime>+ docs: Start of the window used for `traceCount`. Defaults to 7 days before `toTimestamp`.+ toTimestamp:+ type: optional<datetime>+ docs: End of the window used for `traceCount`. Defaults to now.+ response: TopicWithStatus+ errors:+ - errors.BadRequestError+ - errors.UnauthorizedError+ - errors.AccessDeniedError+ - errors.NotFoundError+ - errors.MethodNotAllowedError+ - errors.TooManyRequestsError+ - errors.InternalServerError++types:+ TopicsOrderBy:+ enum:+ - value: traceCount.desc+ name: TraceCountDesc+ - value: traceCount.asc+ name: TraceCountAsc+ - value: name.asc+ name: NameAsc+ - value: name.desc+ name: NameDesc+ TopicFacetPublishedRun:+ properties:+ id: string+ completedAt: optional<datetime>+ topicCount: integer+ TopicFacet:+ properties:+ id: string+ name: string+ description: string+ isBuiltIn: boolean+ active:+ type: boolean+ docs: Whether the facet is attached to the project's Topics rule. True for all facets if the project has no rule.+ version:+ type: integer+ docs: Latest facet version.+ prompt:+ type: string+ docs: Prompt of the latest facet version.+ publishedRun:+ type: optional<TopicFacetPublishedRun>+ docs: The run that produced the facet's current map. Null before the first map.+ TopicFacetList:+ properties:+ data: list<TopicFacet>+ meta: pagination.MetaResponse+ TopicFacetRef:+ properties:+ id: string+ name: string+ version: integer+ TopicWindow:+ properties:+ from: datetime+ to: datetime+ Topic:+ properties:+ id:+ type: string+ docs: Stable topic id, kept across map updates.+ versionId:+ type: string+ docs: Id of this topic version.+ name: string+ description: string+ facet: TopicFacetRef+ runId:+ type: string+ docs: The run that produced this topic version.+ traceCount:+ type: integer+ docs: Traces in the window whose current result for the facet is this topic.+ TopicWithStatus:+ extends: Topic+ properties:+ inCurrentMap:+ type: boolean+ docs: False for retired topics that still have assigned traces in the window.+ window: TopicWindow+ TopicStatusCounts:+ docs: Traces in the window by their current result for one facet.+ properties:+ assigned: integer+ outlier: integer+ awaitingMap: integer+ notApplicable: integer+ insufficientInput: integer+ TopicFacetCounts:+ properties:+ facet: TopicFacetRef+ publishedRunId: optional<string>+ counts: TopicStatusCounts+ TopicList:+ properties:+ window: TopicWindow+ data: list<Topic>+ facets: list<TopicFacetCounts>+ meta: pagination.MetaResponsediff --git a/packages/shared/src/topics/index.ts b/packages/shared/src/topics/index.tsindex d5f4b87ab9..fd03cae3bf 100644--- a/packages/shared/src/topics/index.ts+++ b/packages/shared/src/topics/index.ts@@ -13,6 +13,8 @@ export const topicIdSchema = z.max(128).regex(/^[a-zA-Z0-9_-]+$/);export const topicTraceIdSchema = z.string().min(1).max(1000);+/** The longest time range any Topics read or update accepts. */+export const TOPICS_MAX_TIME_RANGE_MS = 93 * 86_400_000;export const topicTimeRangeSchema = z.object({ from: z.coerce.date(), to: z.coerce.date() }).refine(({ from, to }) => from < to, {@@ -97,10 +99,13 @@ export const topicTraceSelectionCriteriaSchema = topicRuleConfigSchemamessage: "Choose an end time after the start time.",path: ["to"],})- .refine(({ from, to }) => to.getTime() - from.getTime() <= 93 * 86400000, {- message: "Select at most 93 days of traces.",- path: ["from"],- });+ .refine(+ ({ from, to }) => to.getTime() - from.getTime() <= TOPICS_MAX_TIME_RANGE_MS,+ {+ message: "Select at most 93 days of traces.",+ path: ["from"],+ },+ );export const topicTraceSelectionSnapshotSchema =topicTraceSelectionCriteriaSchema.safeExtend({excludedTraceIds: z.array(topicTraceIdSchema).default([]),diff --git a/web/public/generated/api/openapi.yml b/web/public/generated/api/openapi.ymlindex c6684d1f15..95ee7ef6fb 100644--- a/web/public/generated/api/openapi.yml+++ b/web/public/generated/api/openapi.yml@@ -7494,6 +7494,347 @@ paths:schema:$ref: '#/components/schemas/unstablePublicApiError'security: *ref_0+ /api/public/unstable/topic-facets:+ get:+ description: |-+ Unstable: Topics is in closed beta. The shape may change without notice.++ List the project's Topics facets. Only active facets (attached to the+ project's Topics rule, or all facets if the project has no rule) are+ returned unless `filter` contains an `active` condition.++ `filter` is a JSON array of filter conditions combined with AND.+ String matching is case-insensitive. Columns: `id` (stringOptions),+ `name` (string, stringOptions), `description` (string), `isBuiltIn`+ (boolean), `active` (boolean).+ operationId: unstable_topics_listFacets+ tags:+ - UnstableTopics+ parameters:+ - name: filter+ in: query+ description: >-+ JSON array of filter conditions, for example+ `[{"type":"string","column":"name","operator":"contains","value":"issue"}]`.+ required: false+ schema:+ type: string+ nullable: true+ - name: page+ in: query+ description: 1-based page number. Defaults to `1`.+ required: false+ schema:+ type: integer+ nullable: true+ - name: limit+ in: query+ description: Maximum number of items per page. Defaults to `50`, at most `100`.+ required: false+ schema:+ type: integer+ nullable: true+ responses:+ '200':+ description: ''+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/unstableTopicFacetList'+ '400':+ description: ''+ content:+ application/json:+ schema: {}+ '401':+ description: ''+ content:+ application/json:+ schema: {}+ '403':+ description: ''+ content:+ application/json:+ schema: {}+ '404':+ description: ''+ content:+ application/json:+ schema: {}+ '405':+ description: ''+ content:+ application/json:+ schema: {}+ '429':+ description: ''+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/unstablePublicApiError'+ '500':+ description: ''+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/unstablePublicApiError'+ security: *ref_0+ /api/public/unstable/topic-facets/{facetId}:+ get:+ description: |-+ Unstable: Topics is in closed beta. The shape may change without notice.++ Get one Topics facet by id, including inactive facets.+ operationId: unstable_topics_getFacet+ tags:+ - UnstableTopics+ parameters:+ - name: facetId+ in: path+ required: true+ schema:+ type: string+ responses:+ '200':+ description: ''+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/unstableTopicFacet'+ '400':+ description: ''+ content:+ application/json:+ schema: {}+ '401':+ description: ''+ content:+ application/json:+ schema: {}+ '403':+ description: ''+ content:+ application/json:+ schema: {}+ '404':+ description: ''+ content:+ application/json:+ schema: {}+ '405':+ description: ''+ content:+ application/json:+ schema: {}+ '429':+ description: ''+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/unstablePublicApiError'+ '500':+ description: ''+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/unstablePublicApiError'+ security: *ref_0+ /api/public/unstable/topics:+ get:+ description: |-+ Unstable: Topics is in closed beta. The shape may change without notice.++ List the topics of each active facet's current published map, with+ the number of traces currently assigned to each topic in the window.+ Retired topics are not listed. `facets` holds per-facet trace counts+ by topic status.++ The window applies to the trace start time. It defaults to the last+ 7 days and can span at most 93 days.++ `filter` is a JSON array of filter conditions combined with AND.+ String matching is case-insensitive. Columns: `facetId`+ (stringOptions), `facetName` (string, stringOptions), `id`+ (stringOptions), `name` (string, stringOptions). Facet conditions also+ restrict `facets`.+ operationId: unstable_topics_list+ tags:+ - UnstableTopics+ parameters:+ - name: fromTimestamp+ in: query+ description: >-+ Start of the window (trace start time, inclusive). Defaults to 7+ days before `toTimestamp`.+ required: false+ schema:+ type: string+ format: date-time+ nullable: true+ - name: toTimestamp+ in: query+ description: End of the window (trace start time, exclusive). Defaults to now.+ required: false+ schema:+ type: string+ format: date-time+ nullable: true+ - name: filter+ in: query+ description: >-+ JSON array of filter conditions, for example+ `[{"type":"stringOptions","column":"facetName","operator":"any+ of","value":["Issues"]}]`.+ required: false+ schema:+ type: string+ nullable: true+ - name: orderBy+ in: query+ description: Defaults to `traceCount.desc`.+ required: false+ schema:+ $ref: '#/components/schemas/unstableTopicsOrderBy'+ nullable: true+ - name: page+ in: query+ description: 1-based page number. Defaults to `1`.+ required: false+ schema:+ type: integer+ nullable: true+ - name: limit+ in: query+ description: Maximum number of items per page. Defaults to `50`, at most `100`.+ required: false+ schema:+ type: integer+ nullable: true+ responses:+ '200':+ description: ''+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/unstableTopicList'+ '400':+ description: ''+ content:+ application/json:+ schema: {}+ '401':+ description: ''+ content:+ application/json:+ schema: {}+ '403':+ description: ''+ content:+ application/json:+ schema: {}+ '404':+ description: ''+ content:+ application/json:+ schema: {}+ '405':+ description: ''+ content:+ application/json:+ schema: {}+ '429':+ description: ''+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/unstablePublicApiError'+ '500':+ description: ''+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/unstablePublicApiError'+ security: *ref_0+ /api/public/unstable/topics/{topicId}:+ get:+ description: |-+ Unstable: Topics is in closed beta. The shape may change without notice.++ Get one topic by its stable id. Topics on the current map are always+ found. A retired topic is found while traces in the window are still+ assigned to it, with `inCurrentMap: false`.+ operationId: unstable_topics_get+ tags:+ - UnstableTopics+ parameters:+ - name: topicId+ in: path+ required: true+ schema:+ type: string+ - name: fromTimestamp+ in: query+ description: >-+ Start of the window used for `traceCount`. Defaults to 7 days before+ `toTimestamp`.+ required: false+ schema:+ type: string+ format: date-time+ nullable: true+ - name: toTimestamp+ in: query+ description: End of the window used for `traceCount`. Defaults to now.+ required: false+ schema:+ type: string+ format: date-time+ nullable: true+ responses:+ '200':+ description: ''+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/unstableTopicWithStatus'+ '400':+ description: ''+ content:+ application/json:+ schema: {}+ '401':+ description: ''+ content:+ application/json:+ schema: {}+ '403':+ description: ''+ content:+ application/json:+ schema: {}+ '404':+ description: ''+ content:+ application/json:+ schema: {}+ '405':+ description: ''+ content:+ application/json:+ schema: {}+ '429':+ description: ''+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/unstablePublicApiError'+ '500':+ description: ''+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/unstablePublicApiError'+ security: *ref_0components:schemas:AnnotationQueueStatus:@@ -14777,6 +15118,210 @@ components:required:- message- code+ unstableTopicsOrderBy:+ title: unstableTopicsOrderBy+ type: string+ enum:+ - traceCount.desc+ - traceCount.asc+ - name.asc+ - name.desc+ unstableTopicFacetPublishedRun:+ title: unstableTopicFacetPublishedRun+ type: object+ properties:+ id:+ type: string+ completedAt:+ type: string+ format: date-time+ nullable: true+ topicCount:+ type: integer+ required:+ - id+ - topicCount+ unstableTopicFacet:+ title: unstableTopicFacet+ type: object+ properties:+ id:+ type: string+ name:+ type: string+ description:+ type: string+ isBuiltIn:+ type: boolean+ active:+ type: boolean+ description: >-+ Whether the facet is attached to the project's Topics rule. True for+ all facets if the project has no rule.+ version:+ type: integer+ description: Latest facet version.+ prompt:+ type: string+ description: Prompt of the latest facet version.+ publishedRun:+ $ref: '#/components/schemas/unstableTopicFacetPublishedRun'+ nullable: true+ description: >-+ The run that produced the facet's current map. Null before the first+ map.+ required:+ - id+ - name+ - description+ - isBuiltIn+ - active+ - version+ - prompt+ unstableTopicFacetList:+ title: unstableTopicFacetList+ type: object+ properties:+ data:+ type: array+ items:+ $ref: '#/components/schemas/unstableTopicFacet'+ meta:+ $ref: '#/components/schemas/utilsMetaResponse'+ required:+ - data+ - meta+ unstableTopicFacetRef:+ title: unstableTopicFacetRef+ type: object+ properties:+ id:+ type: string+ name:+ type: string+ version:+ type: integer+ required:+ - id+ - name+ - version+ unstableTopicWindow:+ title: unstableTopicWindow+ type: object+ properties:+ from:+ type: string+ format: date-time+ to:+ type: string+ format: date-time+ required:+ - from+ - to+ unstableTopic:+ title: unstableTopic+ type: object+ properties:+ id:+ type: string+ description: Stable topic id, kept across map updates.+ versionId:+ type: string+ description: Id of this topic version.+ name:+ type: string+ description:+ type: string+ facet:+ $ref: '#/components/schemas/unstableTopicFacetRef'+ runId:+ type: string+ description: The run that produced this topic version.+ traceCount:+ type: integer+ description: >-+ Traces in the window whose current result for the facet is this+ topic.+ required:+ - id+ - versionId+ - name+ - description+ - facet+ - runId+ - traceCount+ unstableTopicWithStatus:+ title: unstableTopicWithStatus+ type: object+ properties:+ inCurrentMap:+ type: boolean+ description: >-+ False for retired topics that still have assigned traces in the+ window.+ window:+ $ref: '#/components/schemas/unstableTopicWindow'+ required:+ - inCurrentMap+ - window+ allOf:+ - $ref: '#/components/schemas/unstableTopic'+ unstableTopicStatusCounts:+ title: unstableTopicStatusCounts+ type: object+ description: Traces in the window by their current result for one facet.+ properties:+ assigned:+ type: integer+ outlier:+ type: integer+ awaitingMap:+ type: integer+ notApplicable:+ type: integer+ insufficientInput:+ type: integer+ required:+ - assigned+ - outlier+ - awaitingMap+ - notApplicable+ - insufficientInput+ unstableTopicFacetCounts:+ title: unstableTopicFacetCounts+ type: object+ properties:+ facet:+ $ref: '#/components/schemas/unstableTopicFacetRef'+ publishedRunId:+ type: string+ nullable: true+ counts:+ $ref: '#/components/schemas/unstableTopicStatusCounts'+ required:+ - facet+ - counts+ unstableTopicList:+ title: unstableTopicList+ type: object+ properties:+ window:+ $ref: '#/components/schemas/unstableTopicWindow'+ data:+ type: array+ items:+ $ref: '#/components/schemas/unstableTopic'+ facets:+ type: array+ items:+ $ref: '#/components/schemas/unstableTopicFacetCounts'+ meta:+ $ref: '#/components/schemas/utilsMetaResponse'+ required:+ - window+ - data+ - facets+ - metautilsMetaResponse:title: utilsMetaResponsetype: objectdiff --git a/web/src/__tests__/server/__snapshots__/public-api-auth-parity.servertest.ts.snap b/web/src/__tests__/server/__snapshots__/public-api-auth-parity.servertest.ts.snapindex c12eb89211..fdfffe174d 100644--- a/web/src/__tests__/server/__snapshots__/public-api-auth-parity.servertest.ts.snap+++ b/web/src/__tests__/server/__snapshots__/public-api-auth-parity.servertest.ts.snap@@ -562,6 +562,34 @@ exports[`public-api auth parity > legacy matches the captured baseline except do"GET unstable/skills/index | org/bearer": 401,"GET unstable/skills/index | project/basic": 200,"GET unstable/skills/index | project/bearer": 403,+ "GET unstable/topic-facets/[facetId] | admin/admin": 401,+ "GET unstable/topic-facets/[facetId] | agent/basic": 401,+ "GET unstable/topic-facets/[facetId] | agent/bearer": 401,+ "GET unstable/topic-facets/[facetId] | org/basic": 403,+ "GET unstable/topic-facets/[facetId] | org/bearer": 401,+ "GET unstable/topic-facets/[facetId] | project/basic": 404,+ "GET unstable/topic-facets/[facetId] | project/bearer": 403,+ "GET unstable/topic-facets/index | admin/admin": 401,+ "GET unstable/topic-facets/index | agent/basic": 401,+ "GET unstable/topic-facets/index | agent/bearer": 401,+ "GET unstable/topic-facets/index | org/basic": 403,+ "GET unstable/topic-facets/index | org/bearer": 401,+ "GET unstable/topic-facets/index | project/basic": 404,+ "GET unstable/topic-facets/index | project/bearer": 403,+ "GET unstable/topics/[topicId] | admin/admin": 401,+ "GET unstable/topics/[topicId] | agent/basic": 401,+ "GET unstable/topics/[topicId] | agent/bearer": 401,+ "GET unstable/topics/[topicId] | org/basic": 403,+ "GET unstable/topics/[topicId] | org/bearer": 401,+ "GET unstable/topics/[topicId] | project/basic": 404,+ "GET unstable/topics/[topicId] | project/bearer": 403,+ "GET unstable/topics/index | admin/admin": 401,+ "GET unstable/topics/index | agent/basic": 401,+ "GET unstable/topics/index | agent/bearer": 401,+ "GET unstable/topics/index | org/basic": 403,+ "GET unstable/topics/index | org/bearer": 401,+ "GET unstable/topics/index | project/basic": 404,+ "GET unstable/topics/index | project/bearer": 403,"GET v2/datasets/[datasetName]/index | admin/admin": 401,"GET v2/datasets/[datasetName]/index | agent/basic": 401,"GET v2/datasets/[datasetName]/index | agent/bearer": 401,diff --git a/web/src/__tests__/server/public-api-auth-parity.servertest.ts b/web/src/__tests__/server/public-api-auth-parity.servertest.tsindex a93f768d88..257d27c269 100644--- a/web/src/__tests__/server/public-api-auth-parity.servertest.ts+++ b/web/src/__tests__/server/public-api-auth-parity.servertest.ts@@ -139,6 +139,10 @@ const projectRoutes: Route[] = [methods: ["PATCH", "DELETE"],},{ route: "unstable/skills/files/content", methods: ["GET"] },+ { route: "unstable/topics/index", methods: ["GET"] },+ { route: "unstable/topics/[topicId]", methods: ["GET"] },+ { route: "unstable/topic-facets/index", methods: ["GET"] },+ { route: "unstable/topic-facets/[facetId]", methods: ["GET"] },];// Org and misc routes call shadowAuth directly from the handler body.diff --git a/web/src/__tests__/server/unit/topics.servertest.ts b/web/src/__tests__/server/unit/topics.servertest.tsindex 8ec369bcf2..1ad0b23f34 100644--- a/web/src/__tests__/server/unit/topics.servertest.ts+++ b/web/src/__tests__/server/unit/topics.servertest.ts@@ -1272,12 +1272,16 @@ describe("Topics current results", () => {expect.arrayContaining([{id: "retained",+ versionId: "retained",+ runId: "old-map-retained",name: "Specific refund issues",description: "Current description",count: 1,},{id: "retired",+ versionId: "retired-new",+ runId: "old-map-retired-new",name: "Old retired-new",description: "Historical retired-new",count: 2,diff --git a/web/src/__tests__/server/unit/unstable-topics-public-api.servertest.ts b/web/src/__tests__/server/unit/unstable-topics-public-api.servertest.tsnew file mode 100644index 0000000000..59af821f99--- /dev/null+++ b/web/src/__tests__/server/unit/unstable-topics-public-api.servertest.ts@@ -0,0 +1,377 @@+import { beforeEach, describe, expect, it, vi } from "vitest";+import { LangfuseNotFoundError } from "@langfuse/shared";++const mocks = vi.hoisted(() => ({+ isTopicsProjectEnabled: vi.fn(),+ listTopicFacets: vi.fn(),+ listTopicRules: vi.fn(),+ getPublishedTopicRun: vi.fn(),+ hasStoredTopicSummaries: vi.fn(),+ readLatestTopicAssignments: vi.fn(),+ getLatestFacetSummaries: vi.fn(),+ getTopicRuns: vi.fn(),+}));+vi.mock("@langfuse/shared/topics/server", () => mocks);++import {+ getPublicTopic,+ getPublicTopicFacet,+ listPublicTopicFacets,+ listPublicTopics,+} from "@/src/features/topics/server/publicApi";+import { StructuredPublicApiError } from "@/src/features/public-api/types/structuredPublicApiError";++const projectId = "project-a";+const unitStartTime = "2026-10-19T10:00:00.000Z";+const window = {+ fromTimestamp: new Date("2026-10-13T00:00:00Z"),+ toTimestamp: new Date("2026-10-20T00:00:00Z"),+};++const facet = (id: string, name: string, isBuiltIn = true) => ({+ id,+ projectId,+ name,+ description: `${name} facet`,+ isBuiltIn,+ versions: [+ {+ projectId,+ facetId: id,+ version: 2,+ prompt: `${name} prompt`,+ createdAt: "2026-10-01T00:00:00.000Z",+ },+ ],+});++const definition = (topicId: string, name: string, runId: string) => ({+ topicVersionId: `${topicId}-${runId}`,+ projectId,+ topicId,+ createdByRunId: runId,+ createdAt: "2026-10-18T00:00:00.000Z",+ tags: [],+ name,+ description: `${name} description`,+ centroid: [],+ radius: 0,+ representativeSummaries: [],+});++const issuesRun = {+ id: "run-2",+ projectId,+ facetId: "issues",+ facetVersion: 2,+ status: "completed",+ createdAt: "2026-10-18T00:00:00.000Z",+ startedAt: null,+ finishedAt: "2026-10-18T03:00:00.000Z",+ config: {},+ error: null,+ topics: [+ definition("timeouts", "Tool call timeouts", "run-2"),+ // Reused unchanged from the previous run.+ definition("refunds", "Refund loops", "run-1"),+ ],+};+const oldRun = {+ ...issuesRun,+ id: "run-1",+ topics: [definition("retired", "Retired topic", "run-1")],+};++const summary = (traceId: string, state: string) => ({+ projectId,+ facetId: "issues",+ facetVersion: 2,+ traceId,+ sessionId: null,+ unitStartTime,+ processedAt: "2026-10-19T11:00:00.000Z",+ state,+ summary: `${traceId} summary`,+});++const assignment = (+ traceId: string,+ topic: { topicId: string; runId: string } | null,+) => ({+ projectId,+ facetId: "issues",+ facetVersion: 2,+ traceId,+ sessionId: null,+ unitStartTime,+ summaryProcessedAt: "2026-10-19T11:00:00.000Z",+ runId: topic?.runId ?? "run-2",+ topicId: topic?.topicId ?? null,+ topicVersionId: topic ? `${topic.topicId}-${topic.runId}` : null,+ assignedAt: "2026-10-19T12:00:00.000Z",+});++describe("unstable Topics public API", () => {+ beforeEach(() => {+ vi.clearAllMocks();+ mocks.isTopicsProjectEnabled.mockReturnValue(true);+ mocks.listTopicFacets.mockResolvedValue([+ facet("issues", "Issues"),+ facet("custom", "Custom Facet", false),+ ]);+ mocks.listTopicRules.mockResolvedValue([{ facetIds: ["issues"] }]);+ mocks.getPublishedTopicRun.mockImplementation(async (_, facetId) =>+ facetId === "issues" ? issuesRun : null,+ );+ mocks.hasStoredTopicSummaries.mockResolvedValue(true);+ mocks.getLatestFacetSummaries.mockResolvedValue([+ summary("t1", "complete"),+ summary("t2", "complete"),+ summary("t3", "complete"),+ summary("t4", "complete"),+ summary("t5", "complete"),+ summary("t6", "not_applicable"),+ summary("t7", "insufficient_input"),+ ]);+ mocks.readLatestTopicAssignments.mockResolvedValue([+ assignment("t1", { topicId: "timeouts", runId: "run-2" }),+ assignment("t2", { topicId: "timeouts", runId: "run-2" }),+ assignment("t3", { topicId: "retired", runId: "run-1" }),+ assignment("t4", null),+ ]);+ mocks.getTopicRuns.mockResolvedValue([oldRun]);+ });++ it("returns not found for projects without Topics before reading anything", async () => {+ mocks.isTopicsProjectEnabled.mockReturnValue(false);+ const calls = [+ listPublicTopicFacets({ projectId, page: 1, limit: 50 }),+ getPublicTopicFacet({ projectId, facetId: "issues" }),+ listPublicTopics({+ projectId,+ orderBy: "traceCount.desc",+ page: 1,+ limit: 50,+ }),+ getPublicTopic({ projectId, topicId: "timeouts" }),+ ];+ for (const call of calls)+ await expect(call).rejects.toThrow(+ new LangfuseNotFoundError("Topics is not available for this project."),+ );+ expect(mocks.listTopicFacets).not.toHaveBeenCalled();+ expect(mocks.getLatestFacetSummaries).not.toHaveBeenCalled();+ });++ it("lists active facets by default and filters case-insensitively", async () => {+ const active = await listPublicTopicFacets({+ projectId,+ page: 1,+ limit: 50,+ });+ expect(active.data).toEqual([+ {+ id: "issues",+ name: "Issues",+ description: "Issues facet",+ isBuiltIn: true,+ active: true,+ version: 2,+ prompt: "Issues prompt",+ publishedRun: {+ id: "run-2",+ completedAt: new Date("2026-10-18T03:00:00.000Z"),+ topicCount: 2,+ },+ },+ ]);+ expect(active.meta).toEqual({+ page: 1,+ limit: 50,+ totalItems: 1,+ totalPages: 1,+ });++ const inactive = await listPublicTopicFacets({+ projectId,+ page: 1,+ limit: 50,+ filter: [+ { type: "boolean", column: "active", operator: "=", value: false },+ {+ type: "string",+ column: "name",+ operator: "contains",+ value: "FACET",+ },+ ],+ });+ expect(inactive.data.map(({ id, active }) => ({ id, active }))).toEqual([+ { id: "custom", active: false },+ ]);++ await expect(+ getPublicTopicFacet({ projectId, facetId: "custom" }),+ ).resolves.toMatchObject({ id: "custom", publishedRun: null });+ await expect(+ getPublicTopicFacet({ projectId, facetId: "missing" }),+ ).rejects.toThrow(LangfuseNotFoundError);+ });++ it("treats every facet as active when the project has no Topics rule", async () => {+ mocks.listTopicRules.mockResolvedValue([]);+ const facets = await listPublicTopicFacets({+ projectId,+ page: 1,+ limit: 50,+ });+ expect(facets.data.map(({ id, active }) => [id, active])).toEqual([+ ["issues", true],+ ["custom", true],+ ]);+ const topics = await listPublicTopics({+ projectId,+ ...window,+ orderBy: "traceCount.desc",+ page: 1,+ limit: 50,+ });+ expect(topics.facets.map(({ facet }) => facet.id)).toEqual([+ "issues",+ "custom",+ ]);+ expect(topics.data.map(({ id }) => id)).toEqual(["timeouts", "refunds"]);+ });++ it("rejects unknown filter columns with the allowed columns", async () => {+ const error = await listPublicTopicFacets({+ projectId,+ page: 1,+ limit: 50,+ filter: [+ { type: "string", column: "constructor", operator: "=", value: "x" },+ ],+ }).catch((caught: unknown) => caught);+ expect(error).toBeInstanceOf(StructuredPublicApiError);+ expect(error).toMatchObject({+ httpCode: 400,+ code: "invalid_query",+ details: {+ column: "constructor",+ allowedValues: ["id", "name", "description", "isBuiltIn", "active"],+ },+ });+ });++ it("lists current-map topics with trace counts and per-status facet counts", async () => {+ const result = await listPublicTopics({+ projectId,+ ...window,+ orderBy: "traceCount.desc",+ page: 1,+ limit: 50,+ });+ expect(mocks.getLatestFacetSummaries).toHaveBeenCalledTimes(1);+ expect(mocks.getLatestFacetSummaries).toHaveBeenCalledWith(+ projectId,+ "issues",+ undefined,+ { from: window.fromTimestamp, to: window.toTimestamp },+ undefined,+ );+ expect(result.window).toEqual({+ from: window.fromTimestamp,+ to: window.toTimestamp,+ });+ expect(result.data).toEqual([+ {+ id: "timeouts",+ versionId: "timeouts-run-2",+ name: "Tool call timeouts",+ description: "Tool call timeouts description",+ facet: { id: "issues", name: "Issues", version: 2 },+ runId: "run-2",+ traceCount: 2,+ },+ expect.objectContaining({ id: "refunds", runId: "run-1", traceCount: 0 }),+ ]);+ expect(result.facets).toEqual([+ {+ facet: { id: "issues", name: "Issues", version: 2 },+ publishedRunId: "run-2",+ counts: {+ assigned: 3,+ outlier: 1,+ awaitingMap: 1,+ notApplicable: 1,+ insufficientInput: 1,+ },+ },+ ]);++ const filtered = await listPublicTopics({+ projectId,+ ...window,+ orderBy: "name.asc",+ page: 1,+ limit: 50,+ filter: [+ {+ type: "stringOptions",+ column: "facetName",+ operator: "none of",+ value: ["issues"],+ },+ ],+ });+ expect(filtered.data).toEqual([]);+ expect(filtered.facets).toEqual([]);+ expect(mocks.getLatestFacetSummaries).toHaveBeenCalledTimes(1);+ });++ it("rejects windows longer than 93 days", async () => {+ await expect(+ listPublicTopics({+ projectId,+ fromTimestamp: new Date("2026-01-01T00:00:00Z"),+ toTimestamp: new Date("2026-10-01T00:00:00Z"),+ orderBy: "traceCount.desc",+ page: 1,+ limit: 50,+ }),+ ).rejects.toMatchObject({ httpCode: 400, code: "invalid_query" });+ await expect(+ listPublicTopics({+ projectId,+ fromTimestamp: new Date(Date.now() - 100 * 86_400_000),+ orderBy: "traceCount.desc",+ page: 1,+ limit: 50,+ }),+ ).rejects.toMatchObject({ httpCode: 400, code: "invalid_query" });+ expect(mocks.getLatestFacetSummaries).not.toHaveBeenCalled();+ });++ it("gets current and retired topics by stable id", async () => {+ await expect(+ getPublicTopic({ projectId, topicId: "timeouts", ...window }),+ ).resolves.toMatchObject({+ id: "timeouts",+ inCurrentMap: true,+ traceCount: 2,+ });+ await expect(+ getPublicTopic({ projectId, topicId: "retired", ...window }),+ ).resolves.toMatchObject({+ id: "retired",+ versionId: "retired-run-1",+ runId: "run-1",+ name: "Retired topic",+ inCurrentMap: false,+ traceCount: 1,+ });+ await expect(+ getPublicTopic({ projectId, topicId: "unknown", ...window }),+ ).rejects.toThrow(LangfuseNotFoundError);+ });+});diff --git a/web/src/__tests__/server/withMiddlewares.servertest.ts b/web/src/__tests__/server/withMiddlewares.servertest.tsindex 1983ae0dae..7c2435491e 100644--- a/web/src/__tests__/server/withMiddlewares.servertest.ts+++ b/web/src/__tests__/server/withMiddlewares.servertest.ts@@ -109,6 +109,22 @@ describe("clickHouseRouteForRequest", () => {);});+ it("reports static routes as themselves even where a template overlaps them", () => {+ const apiDir = `${__dirname}/../../pages/api`;+ const staticPaths = readdirSync(apiDir, { recursive: true })+ .map(String)+ .filter((file) => file.endsWith(".ts") && !file.includes("["))+ .map(+ (file) => "/api/" + file.replace(/\.ts$/, "").replace(/\/index$/, ""),+ );++ const misreported = staticPaths.filter(+ (path) =>+ clickHouseRouteForRequest(request("GET", path)) !== `GET ${path}`,+ );+ expect(misreported).toEqual([]);+ });+it("falls back to UNKNOWN method for missing methods", () => {expect(clickHouseRouteForRequest(request(undefined, "/api/public/health")),diff --git a/web/src/features/public-api/server/clickHouseRequestTags.ts b/web/src/features/public-api/server/clickHouseRequestTags.tsindex 28162627e4..6c0d517e42 100644--- a/web/src/features/public-api/server/clickHouseRequestTags.ts+++ b/web/src/features/public-api/server/clickHouseRequestTags.ts@@ -41,6 +41,8 @@ export const DYNAMIC_API_ROUTE_TEMPLATES = ["/api/public/skills/[skillName]/versions/[skillVersion]","/api/public/unstable/skills/[skillName]","/api/public/unstable/skills/[skillName]/versions/[skillVersion]",+ "/api/public/unstable/topic-facets/[facetId]",+ "/api/public/unstable/topics/[topicId]","/api/public/v2/datasets/[datasetName]","/api/public/v2/evaluation-rules/[evaluationRuleId]","/api/public/v2/evaluators/[evaluatorId]",diff --git a/web/src/features/public-api/types/unstable-topics.ts b/web/src/features/public-api/types/unstable-topics.tsnew file mode 100644index 0000000000..73dfa02086--- /dev/null+++ b/web/src/features/public-api/types/unstable-topics.ts@@ -0,0 +1,118 @@+import { z } from "zod";+import { optionalJsonParam, singleFilterList } from "@langfuse/shared";++const pagination = z.object({+ page: z.coerce.number().int().positive().default(1),+ limit: z.coerce.number().int().positive().max(100).default(50),+});++const timeWindow = z.object({+ fromTimestamp: z.coerce.date().optional(),+ toTimestamp: z.coerce.date().optional(),+});++const paginationMeta = z.object({+ page: z.number(),+ limit: z.number(),+ totalItems: z.number(),+ totalPages: z.number(),+});++const FacetRefSchema = z+ .object({ id: z.string(), name: z.string(), version: z.number().int() })+ .strict();++const WindowSchema = z+ .object({ from: z.coerce.date(), to: z.coerce.date() })+ .strict();++const TopicFacetSchema = z+ .object({+ id: z.string(),+ name: z.string(),+ description: z.string(),+ isBuiltIn: z.boolean(),+ active: z.boolean(),+ version: z.number().int(),+ prompt: z.string(),+ publishedRun: z+ .object({+ id: z.string(),+ completedAt: z.coerce.date().nullable(),+ topicCount: z.number().int(),+ })+ .strict()+ .nullable(),+ })+ .strict();++const TopicSchema = z+ .object({+ id: z.string(),+ versionId: z.string(),+ name: z.string(),+ description: z.string(),+ facet: FacetRefSchema,+ runId: z.string(),+ traceCount: z.number().int(),+ })+ .strict();++const TopicStatusCountsSchema = z+ .object({+ assigned: z.number().int(),+ outlier: z.number().int(),+ awaitingMap: z.number().int(),+ notApplicable: z.number().int(),+ insufficientInput: z.number().int(),+ })+ .strict();++export const GetUnstableTopicFacetsQuery = pagination.extend({+ filter: optionalJsonParam(singleFilterList, "filter"),+});+export const GetUnstableTopicFacetsResponse = z+ .object({ data: z.array(TopicFacetSchema), meta: paginationMeta })+ .strict();++export const TopicFacetIdQuery = z.object({ facetId: z.string() });+/** @alias */+export const GetUnstableTopicFacetResponse = TopicFacetSchema;++const TOPICS_ORDER_BY = [+ "traceCount.desc",+ "traceCount.asc",+ "name.asc",+ "name.desc",+] as const;++export const GetUnstableTopicsQuery = pagination+ .extend(timeWindow.shape)+ .extend({+ filter: optionalJsonParam(singleFilterList, "filter"),+ orderBy: z.enum(TOPICS_ORDER_BY).default("traceCount.desc"),+ });+export const GetUnstableTopicsResponse = z+ .object({+ window: WindowSchema,+ data: z.array(TopicSchema),+ facets: z.array(+ z+ .object({+ facet: FacetRefSchema,+ publishedRunId: z.string().nullable(),+ counts: TopicStatusCountsSchema,+ })+ .strict(),+ ),+ meta: paginationMeta,+ })+ .strict();++export const GetUnstableTopicQuery = timeWindow.extend({+ topicId: z.string(),+});+export const GetUnstableTopicResponse = TopicSchema.extend({+ inCurrentMap: z.boolean(),+ window: WindowSchema,+}).strict();diff --git a/web/src/features/topics/CurrentTopicsView.stories.tsx b/web/src/features/topics/CurrentTopicsView.stories.tsxindex 446e60180f..0173f4228a 100644--- a/web/src/features/topics/CurrentTopicsView.stories.tsx+++ b/web/src/features/topics/CurrentTopicsView.stories.tsx@@ -12,6 +12,8 @@ import {const topic = {id: "billing",+ versionId: "billing-v1",+ runId: "run",name: "Billing questions",description: "Invoice support",count: 60,diff --git a/web/src/features/topics/TopicGridView.stories.tsx b/web/src/features/topics/TopicGridView.stories.tsxindex d5a197b775..193d65c049 100644--- a/web/src/features/topics/TopicGridView.stories.tsx+++ b/web/src/features/topics/TopicGridView.stories.tsx@@ -21,7 +21,7 @@ const topics = [count: 0,},{ id: "howto", name: "How-to and onboarding", description: "", count: 0 },-];+].map((topic) => ({ ...topic, versionId: `${topic.id}-v1`, runId: "run" }));const clusters: { topic: number | null; x: number; y: number; n: number }[] = [{ topic: 0, x: -6, y: -4, n: 70 },{ topic: 1, x: 5, y: -5, n: 55 },diff --git a/web/src/features/topics/TopicTreemapView.stories.tsx b/web/src/features/topics/TopicTreemapView.stories.tsxindex 190a25bb6b..ae37182dd8 100644--- a/web/src/features/topics/TopicTreemapView.stories.tsx+++ b/web/src/features/topics/TopicTreemapView.stories.tsx@@ -23,6 +23,8 @@ const names = [];const topics = names.map((name, index) => ({id: `topic-${index}`,+ versionId: `topic-${index}-v1`,+ runId: "run",name,description: "",count: counts[index],@@ -95,7 +97,13 @@ const issueTopics = [{ name: "Run stopped before delivering final report", count: 18 },{ name: "Run halted before delivering requested report", count: 18 },{ name: "Partial answers without follow-up", count: 16 },-].map((topic, index) => ({ ...topic, id: `issue-${index}`, description: "" }));+].map((topic, index) => ({+ ...topic,+ id: `issue-${index}`,+ versionId: `issue-${index}-v1`,+ runId: "run",+ description: "",+}));export const LongNamesOnShortTiles = meta.story({name: "Long names on short tiles",diff --git a/web/src/features/topics/TopicTreemapView.tsx b/web/src/features/topics/TopicTreemapView.tsxindex 182b252e6a..89a1007daf 100644--- a/web/src/features/topics/TopicTreemapView.tsx+++ b/web/src/features/topics/TopicTreemapView.tsx@@ -63,6 +63,8 @@ export function TopicTreemapView({...facet.topics,{id: UNASSIGNED_ID,+ versionId: "",+ runId: "",name: "Unassigned",description: "",count: unassignedCount,diff --git a/web/src/features/topics/server/currentResults.ts b/web/src/features/topics/server/currentResults.tsindex 1df0247459..4d576c1530 100644--- a/web/src/features/topics/server/currentResults.ts+++ b/web/src/features/topics/server/currentResults.ts@@ -48,9 +48,11 @@ function resolveTopicResult(export async function currentTopicResults(projectId: string,timeRange: TopicTimeRange,- traceIds?: string[],+ { facetIds, traceIds }: { facetIds?: string[]; traceIds?: string[] } = {},) {- const facets = await listTopicFacets(projectId);+ const facets = (await listTopicFacets(projectId)).filter(+ (facet) => !facetIds || facetIds.includes(facet.id),+ );const hasStoredSummaries =facets.length > 0 && (await hasStoredTopicSummaries(projectId));if (!hasStoredSummaries) return { hasStoredSummaries, facets: [] };@@ -164,6 +166,12 @@ export async function currentTopicResults(topicByVersion.get(topic.assignment.topicVersionId ?? "");return {id,+ versionId:+ definition?.topicVersionId ??+ topic.assignment.topicVersionId ??+ "",+ runId:+ definition?.createdByRunId ?? topic.assignment.runId ?? "",name: definition?.name ?? "Unavailable topic",description: definition?.description ?? "",count: topic.count,@@ -175,6 +183,8 @@ export async function currentTopicResults(runId: run.id,topics: run.topics.map((topic) => ({id: topic.topicId,+ versionId: topic.topicVersionId,+ runId: topic.createdByRunId,name: topic.name,description: topic.description,})),@@ -199,9 +209,9 @@ export async function traceFacetResults(to: new Date(timestamp.getTime() + slackMs),});if (!unitTimeRange) return [];- const { facets } = await currentTopicResults(projectId, unitTimeRange, [- traceId,- ]);+ const { facets } = await currentTopicResults(projectId, unitTimeRange, {+ traceIds: [traceId],+ });return facets.map((facet) => {const row = facet.rows.find((item) => item.traceId === traceId);return {diff --git a/web/src/features/topics/server/publicApi.ts b/web/src/features/topics/server/publicApi.tsnew file mode 100644index 0000000000..57d38c8c45--- /dev/null+++ b/web/src/features/topics/server/publicApi.ts@@ -0,0 +1,351 @@+import { LangfuseNotFoundError, type FilterState } from "@langfuse/shared";+import { InMemoryFilterService } from "@langfuse/shared/src/server";+import {+ TOPICS_MAX_TIME_RANGE_MS,+ type TopicFacet,+ type TopicRun,+ type TopicTimeRange,+} from "@langfuse/shared/topics";+import {+ getPublishedTopicRun,+ isTopicsProjectEnabled,+ listTopicFacets,+ listTopicRules,+} from "@langfuse/shared/topics/server";+import { createStructuredPublicApiError } from "@/src/features/public-api/types/structuredPublicApiError";+import { currentTopicResults } from "./currentResults";++const DEFAULT_WINDOW_MS = 7 * 86_400_000;++type FilterType = FilterState[number]["type"];+type FilterColumns<T> = Record<+ string,+ { types: readonly FilterType[]; value: (row: T) => unknown }+>;++/**+ * Public read access uses the project gate only: API keys carry no user, so+ * the UI's per-user feature preview cannot apply.+ */+function assertTopicsApiAvailable(projectId: string) {+ if (!isTopicsProjectEnabled(projectId))+ throw new LangfuseNotFoundError(+ "Topics is not available for this project.",+ );+}++function invalidFilter(message: string, column: string, allowed: string[]) {+ return createStructuredPublicApiError({+ httpCode: 400,+ code: "invalid_query",+ message,+ details: { column, allowedValues: allowed },+ });+}++function lower(value: unknown): unknown {+ if (typeof value === "string") return value.toLowerCase();+ if (Array.isArray(value)) return value.map(lower);+ return value;+}++/** String matching on Topics routes is case-insensitive. */+function applyFilter<T>(+ rows: T[],+ filter: FilterState | undefined,+ columns: FilterColumns<T>,+): T[] {+ if (!filter || filter.length === 0) return rows;+ const names = Object.keys(columns);+ for (const condition of filter) {+ const column = Object.hasOwn(columns, condition.column)+ ? columns[condition.column]+ : undefined;+ if (!column)+ throw invalidFilter(+ `Unknown filter column "${condition.column}".`,+ condition.column,+ names,+ );+ if (!column.types.includes(condition.type))+ throw invalidFilter(+ `Filter column "${condition.column}" does not support type "${condition.type}".`,+ condition.column,+ [...column.types],+ );+ }+ const conditions = filter.map(+ (condition) =>+ ({+ ...condition,+ value: lower(condition.value),+ }) as FilterState[number],+ );+ return rows.filter((row) =>+ InMemoryFilterService.evaluateFilter(row, conditions, (data, name) =>+ lower(columns[name].value(data)),+ ),+ );+}++function paginate<T>(rows: T[], page: number, limit: number) {+ return {+ data: rows.slice((page - 1) * limit, page * limit),+ meta: {+ page,+ limit,+ totalItems: rows.length,+ totalPages: Math.ceil(rows.length / limit),+ },+ };+}++function resolveWindow(from?: Date, to?: Date): TopicTimeRange {+ const end = to ?? new Date();+ const start = from ?? new Date(end.getTime() - DEFAULT_WINDOW_MS);+ if (+ start >= end ||+ end.getTime() - start.getTime() > TOPICS_MAX_TIME_RANGE_MS+ )+ throw createStructuredPublicApiError({+ httpCode: 400,+ code: "invalid_query",+ message:+ "fromTimestamp must be before toTimestamp, and the window can span at most 93 days.",+ });+ return { from: start, to: end };+}++// Matches currentTopicResults: the latest rule's facets, or all facets without a rule (manual runs).+async function isFacetActive(projectId: string) {+ const [rule] = await listTopicRules(projectId);+ return (facetId: string) => !rule || rule.facetIds.includes(facetId);+}++function publicFacet(facet: TopicFacet, active: boolean, run: TopicRun | null) {+ const version = facet.versions[0];+ return {+ id: facet.id,+ name: facet.name,+ description: facet.description,+ isBuiltIn: facet.isBuiltIn,+ active,+ version: version?.version ?? 0,+ prompt: version?.prompt ?? "",+ publishedRun: run+ ? {+ id: run.id,+ completedAt: run.finishedAt ? new Date(run.finishedAt) : null,+ topicCount: run.topics.length,+ }+ : null,+ };+}++type PublicFacet = ReturnType<typeof publicFacet>;++const facetColumns: FilterColumns<PublicFacet> = {+ id: { types: ["stringOptions"], value: (row) => row.id },+ name: { types: ["string", "stringOptions"], value: (row) => row.name },+ description: { types: ["string"], value: (row) => row.description },+ isBuiltIn: { types: ["boolean"], value: (row) => row.isBuiltIn },+ active: { types: ["boolean"], value: (row) => row.active },+};++const hasActiveCondition = (filter: FilterState | undefined) =>+ filter?.some((condition) => condition.column === "active") ?? false;++async function loadPublicFacets(projectId: string) {+ const [facets, isActive] = await Promise.all([+ listTopicFacets(projectId),+ isFacetActive(projectId),+ ]);+ return Promise.all(+ facets.map(async (facet) =>+ publicFacet(+ facet,+ isActive(facet.id),+ await getPublishedTopicRun(projectId, facet.id),+ ),+ ),+ );+}++/** Lists facets; only active facets unless the filter names `active`. */+export async function listPublicTopicFacets(params: {+ projectId: string;+ filter?: FilterState;+ page: number;+ limit: number;+}) {+ assertTopicsApiAvailable(params.projectId);+ const facets = applyFilter(+ await loadPublicFacets(params.projectId),+ hasActiveCondition(params.filter)+ ? params.filter+ : [+ ...(params.filter ?? []),+ { type: "boolean", column: "active", operator: "=", value: true },+ ],+ facetColumns,+ );+ return paginate(facets, params.page, params.limit);+}++export async function getPublicTopicFacet(params: {+ projectId: string;+ facetId: string;+}) {+ assertTopicsApiAvailable(params.projectId);+ const facet = (await loadPublicFacets(params.projectId)).find(+ ({ id }) => id === params.facetId,+ );+ if (!facet) throw new LangfuseNotFoundError("Facet not found.");+ return facet;+}++const facetSummaryColumns: FilterColumns<{+ facet: { id: string; name: string };+}> = {+ facetId: { types: ["stringOptions"], value: (row) => row.facet.id },+ facetName: {+ types: ["string", "stringOptions"],+ value: (row) => row.facet.name,+ },+};++async function loadPublicTopics(+ projectId: string,+ window: TopicTimeRange,+ facetFilter?: FilterState,+) {+ const [facets, isActive] = await Promise.all([+ listTopicFacets(projectId),+ isFacetActive(projectId),+ ]);+ const facetIds = applyFilter(+ facets+ .filter(({ id }) => isActive(id))+ .map(({ id, name }) => ({ facet: { id, name } })),+ facetFilter,+ facetSummaryColumns,+ ).map(({ facet }) => facet.id);+ const results = await currentTopicResults(projectId, window, { facetIds });+ return results.facets.map((facet) => {+ const ref = {+ id: facet.facetId,+ name: facet.name,+ version: facet.facetVersion ?? 0,+ };+ const traceCounts = new Map(facet.topics.map((topic) => [topic.id, topic]));+ const current = (facet.map?.topics ?? []).map((topic) => ({+ id: topic.id,+ versionId: topic.versionId,+ name: topic.name,+ description: topic.description,+ facet: ref,+ runId: topic.runId,+ traceCount: traceCounts.get(topic.id)?.count ?? 0,+ }));+ const currentIds = new Set(current.map(({ id }) => id));+ const retired = facet.topics+ .filter((topic) => !currentIds.has(topic.id))+ .map((topic) => ({+ id: topic.id,+ versionId: topic.versionId,+ name: topic.name,+ description: topic.description,+ facet: ref,+ runId: topic.runId,+ traceCount: topic.count,+ }));+ const count = (outcome: string) =>+ facet.rows.filter((row) => row.outcome === outcome).length;+ return {+ summary: {+ facet: ref,+ publishedRunId: facet.map?.runId ?? null,+ counts: {+ assigned: count("assigned"),+ outlier: count("outlier"),+ awaitingMap: count("awaiting_map"),+ notApplicable: count("not_applicable"),+ insufficientInput: count("insufficient_input"),+ },+ },+ current,+ retired,+ };+ });+}++type PublicTopic = Awaited<+ ReturnType<typeof loadPublicTopics>+>[number]["current"][number];++const topicColumns: FilterColumns<PublicTopic> = {+ ...facetSummaryColumns,+ id: { types: ["stringOptions"], value: (row) => row.id },+ name: { types: ["string", "stringOptions"], value: (row) => row.name },+};++const topicOrder = {+ "traceCount.desc": (a: PublicTopic, b: PublicTopic) =>+ b.traceCount - a.traceCount || a.name.localeCompare(b.name),+ "traceCount.asc": (a: PublicTopic, b: PublicTopic) =>+ a.traceCount - b.traceCount || a.name.localeCompare(b.name),+ "name.asc": (a: PublicTopic, b: PublicTopic) => a.name.localeCompare(b.name),+ "name.desc": (a: PublicTopic, b: PublicTopic) => b.name.localeCompare(a.name),+};++/** Lists the topics of each active facet's current map; retired topics are not listed. */+export async function listPublicTopics(params: {+ projectId: string;+ fromTimestamp?: Date;+ toTimestamp?: Date;+ filter?: FilterState;+ orderBy: keyof typeof topicOrder;+ page: number;+ limit: number;+}) {+ assertTopicsApiAvailable(params.projectId);+ const window = resolveWindow(params.fromTimestamp, params.toTimestamp);+ const facets = await loadPublicTopics(+ params.projectId,+ window,+ params.filter?.filter(({ column }) =>+ Object.hasOwn(facetSummaryColumns, column),+ ),+ );+ const topics = applyFilter(+ facets.flatMap(({ current }) => current),+ params.filter,+ topicColumns,+ ).sort(topicOrder[params.orderBy]);+ return {+ window,+ facets: facets.map(({ summary }) => summary),+ ...paginate(topics, params.page, params.limit),+ };+}++/**+ * Resolves a topic of an active facet's current map, or a retired topic that+ * still has current traces in the window.+ */+export async function getPublicTopic(params: {+ projectId: string;+ topicId: string;+ fromTimestamp?: Date;+ toTimestamp?: Date;+}) {+ assertTopicsApiAvailable(params.projectId);+ const window = resolveWindow(params.fromTimestamp, params.toTimestamp);+ for (const facet of await loadPublicTopics(params.projectId, window)) {+ const current = facet.current.find(({ id }) => id === params.topicId);+ if (current) return { ...current, inCurrentMap: true, window };+ const retired = facet.retired.find(({ id }) => id === params.topicId);+ if (retired) return { ...retired, inCurrentMap: false, window };+ }+ throw new LangfuseNotFoundError("Topic not found.");+}diff --git a/web/src/features/topics/server/topicsRouter.ts b/web/src/features/topics/server/topicsRouter.tsindex a0ace71aee..e36e73afe9 100644--- a/web/src/features/topics/server/topicsRouter.ts+++ b/web/src/features/topics/server/topicsRouter.ts@@ -15,6 +15,7 @@ import {topicRuleConfigSchema,topicTimeRangeSchema,topicsAutomaticProcessingSchema,+ TOPICS_MAX_TIME_RANGE_MS,topicsModelSettingsSchema,topicsSetupSchema,type TopicTimeRange,@@ -75,7 +76,7 @@ const SETUP_TRACE_SPAN_MARGIN_MS = 5 * 60_000;const executionInput = projectInput.extend({ executionId: topicIdSchema });const resultInput = projectInput.extend({timeRange: topicTimeRangeSchema.refine(- ({ from, to }) => to.getTime() - from.getTime() <= 93 * 86_400_000,+ ({ from, to }) => to.getTime() - from.getTime() <= TOPICS_MAX_TIME_RANGE_MS,"Select a time range of at most 93 days.",),});diff --git a/web/src/features/topics/server/traceSelection.ts b/web/src/features/topics/server/traceSelection.tsindex d8b1f746a0..496a13e788 100644--- a/web/src/features/topics/server/traceSelection.ts+++ b/web/src/features/topics/server/traceSelection.ts@@ -6,6 +6,7 @@ import {topicIdSchema,topicTraceSelectionCriteriaSchema,topicTraceSelectionSnapshotSchema,+ TOPICS_MAX_TIME_RANGE_MS,} from "@langfuse/shared/topics";import type { PrismaClient } from "@langfuse/shared/src/db";import { selectTopicTraceRows } from "@langfuse/shared/topics/server";@@ -43,7 +44,7 @@ export const topicTriggerInputSchema = z(input) =>input.operation !== "update" ||input.timeRange.to.getTime() - input.timeRange.from.getTime() <=- 93 * 86_400_000,+ TOPICS_MAX_TIME_RANGE_MS,"Select a time range of at most 93 days.",);diff --git a/web/src/pages/api/public/unstable/topic-facets/[facetId].ts b/web/src/pages/api/public/unstable/topic-facets/[facetId].tsnew file mode 100644index 0000000000..4f240832e2--- /dev/null+++ b/web/src/pages/api/public/unstable/topic-facets/[facetId].ts@@ -0,0 +1,20 @@+import {+ createUnstablePublicApiRoute,+ withUnstablePublicApiMiddlewares,+} from "@/src/features/public-api/server/unstable-public-api-route";+import {+ GetUnstableTopicFacetResponse,+ TopicFacetIdQuery,+} from "@/src/features/public-api/types/unstable-topics";+import { getPublicTopicFacet } from "@/src/features/topics/server/publicApi";++export default withUnstablePublicApiMiddlewares({+ GET: createUnstablePublicApiRoute({+ name: "Get Unstable Topic Facet",+ action: "topics:read",+ querySchema: TopicFacetIdQuery,+ responseSchema: GetUnstableTopicFacetResponse,+ fn: ({ query, auth }) =>+ getPublicTopicFacet({ projectId: auth.scope.projectId, ...query }),+ }),+});diff --git a/web/src/pages/api/public/unstable/topic-facets/index.ts b/web/src/pages/api/public/unstable/topic-facets/index.tsnew file mode 100644index 0000000000..eeeeaabd27--- /dev/null+++ b/web/src/pages/api/public/unstable/topic-facets/index.ts@@ -0,0 +1,20 @@+import {+ createUnstablePublicApiRoute,+ withUnstablePublicApiMiddlewares,+} from "@/src/features/public-api/server/unstable-public-api-route";+import {+ GetUnstableTopicFacetsQuery,+ GetUnstableTopicFacetsResponse,+} from "@/src/features/public-api/types/unstable-topics";+import { listPublicTopicFacets } from "@/src/features/topics/server/publicApi";++export default withUnstablePublicApiMiddlewares({+ GET: createUnstablePublicApiRoute({+ name: "List Unstable Topic Facets",+ action: "topics:read",+ querySchema: GetUnstableTopicFacetsQuery,+ responseSchema: GetUnstableTopicFacetsResponse,+ fn: ({ query, auth }) =>+ listPublicTopicFacets({ projectId: auth.scope.projectId, ...query }),+ }),+});diff --git a/web/src/pages/api/public/unstable/topics/[topicId].ts b/web/src/pages/api/public/unstable/topics/[topicId].tsnew file mode 100644index 0000000000..edb96cdebb--- /dev/null+++ b/web/src/pages/api/public/unstable/topics/[topicId].ts@@ -0,0 +1,20 @@+import {+ createUnstablePublicApiRoute,+ withUnstablePublicApiMiddlewares,+} from "@/src/features/public-api/server/unstable-public-api-route";+import {+ GetUnstableTopicQuery,+ GetUnstableTopicResponse,+} from "@/src/features/public-api/types/unstable-topics";+import { getPublicTopic } from "@/src/features/topics/server/publicApi";++export default withUnstablePublicApiMiddlewares({+ GET: createUnstablePublicApiRoute({+ name: "Get Unstable Topic",+ action: "topics:read",+ querySchema: GetUnstableTopicQuery,+ responseSchema: GetUnstableTopicResponse,+ fn: ({ query, auth }) =>+ getPublicTopic({ projectId: auth.scope.projectId, ...query }),+ }),+});diff --git a/web/src/pages/api/public/unstable/topics/index.ts b/web/src/pages/api/public/unstable/topics/index.tsnew file mode 100644index 0000000000..3a2d0ca5cc--- /dev/null+++ b/web/src/pages/api/public/unstable/topics/index.ts@@ -0,0 +1,20 @@+import {+ createUnstablePublicApiRoute,+ withUnstablePublicApiMiddlewares,+} from "@/src/features/public-api/server/unstable-public-api-route";+import {+ GetUnstableTopicsQuery,+ GetUnstableTopicsResponse,+} from "@/src/features/public-api/types/unstable-topics";+import { listPublicTopics } from "@/src/features/topics/server/publicApi";++export default withUnstablePublicApiMiddlewares({+ GET: createUnstablePublicApiRoute({+ name: "List Unstable Topics",+ action: "topics:read",+ querySchema: GetUnstableTopicsQuery,+ responseSchema: GetUnstableTopicsResponse,+ fn: ({ query, auth }) =>+ listPublicTopics({ projectId: auth.scope.projectId, ...query }),+ }),+});