Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(business-knowledge): add playground search mode and citations (#122101)

Marco Gancitano18223195065e
diff --git a/docs/published/docs/business-knowledge/start.mdx b/docs/published/docs/business-knowledge/start.mdx
index 2737ea950efb..e5ecf80ce055 100644
--- a/docs/published/docs/business-knowledge/start.mdx
+++ b/docs/published/docs/business-knowledge/start.mdx
@@ -50,9 +50,18 @@ Leave it out to search the whole project.
## Playground
-The **Playground** tab asks a question against your sources and shows the answer.
+The **Playground** tab has two modes.
Use it to check that a source is found before you rely on it in Support or PostHog AI.
+- **Chat** asks a question against your sources and shows the answer.
+ Open **Looked through business knowledge** under a question to see each search and document read the answer made.
+ Open a search or a read to see its chunks.
+ A chunk from a source the answer cited is tagged **Cited**.
+- **Search** shows the chunks that match a query, without writing an answer.
+
+The chunks under a chat answer load again when you open them.
+If your sources changed since the answer, they can differ from what the answer used.
+
## Content checks
PostHog checks each document before using it in an answer.
diff --git a/frontend/snapshots.yml b/frontend/snapshots.yml
index c1d94b88470c..dd85c3ec3c4e 100644
--- a/frontend/snapshots.yml
+++ b/frontend/snapshots.yml
@@ -9962,18 +9962,26 @@ snapshots:
hash: v1.k794b7964.c4b1a6986db44af6a8e496ec80f9d177d131a2db6e5fa09cc87a79ec6c53a6f4.09YBKQpa28bk-h-ntRltPIPEGy_XRWA3Ner82vwyHRc
scenes-app-batchexports--runs-with-data--light:
hash: v1.k794b7964.4c1646577dc53efffd814b1a2e723f9da6b10d3641e979f48c5d0447859e2348.fkHuUw1l_9c3rJKSi467jx-6Nv81nNp-PjeRmsgU7l0
+ scenes-app-business-knowledge-playground--chat-citations--dark:
+ hash: v1.k794b7964.46287a4667d6a7977a23193db30e3042377ebc7e988cd5eccd8a1ac411d45966.OZvEKplY375_EkYnxSBg_hWz-HmkWE-3n83RW4gcPe0
+ scenes-app-business-knowledge-playground--chat-citations--light:
+ hash: v1.k794b7964.51499b6453006544ad1dea90bb84c7d1006aa68c3579f7d43a24eefced66cd34.SDbrud1AhjhV6lNIqj2G2jKfOaIWrYvLla6q5qE7-pg
scenes-app-business-knowledge-playground--narrow-scene--dark:
- hash: v1.k794b7964.b321de09fb261e9702b5108e3e5e728dce9725a4f6505a6d7320fe69ec9d1e03.y3-moQ1dJq2sK8P6JK6Y9RnV_J2KA6mk74yuonrxgaQ
+ hash: v1.k794b7964.f79ec74f665be20d3b328907b340731950a6511614029a321c80050d1709c962.io6TjbEN37uQwwctqkEEDM65Qw7qODR91KqQQDGBz_A
scenes-app-business-knowledge-playground--narrow-scene--light:
- hash: v1.k794b7964.4bf82cff8092f8ba03f06805e2dfd5ff50ce1cc69a1a7d4d133c5e8f3739c4a5.kHMLcQF3qu0iQIs6_KjfRnjXiy2nxlpmiCV906-VMV8
+ hash: v1.k794b7964.f3a473dd47ff467d5c44f2a1e3d85c33b9339974a0b304d8c1394cc346fea0a3.oNrw5CTqGZQ5KUU1B04MTM5KWJZMa4AiIMWO9YOy3s8
scenes-app-business-knowledge-playground--new-chat--dark:
- hash: v1.k794b7964.764a1ff0a787ddd6bd73d691a34c5d22cebaf9be9877d0c36de12104ab87156b.DUQXhk7rrwF65Bm_eblKzmLzOVRG3hFv5QVSeGOBplg
+ hash: v1.k794b7964.5204ba012e17ab3cb7d32cce00fadc82ca73d186071ce944c7bea604b9a0e018.xYIFSiA8hbd2dgrd2obg6v-zKOgMwwfsZ0cXDjePRG8
scenes-app-business-knowledge-playground--new-chat--light:
- hash: v1.k794b7964.2b766f32efc2f6e78a8689dd32769561427c44dd781a1b22e04a991795e21943.vplL_jaXejpIF00jWKMtGn9WHDcvrx-XUEsZPreuPmE
+ hash: v1.k794b7964.62cf0349d8e1f4b1ceff4bab4c0065a605bfd6c7c1850f9a9250e9f362901fcc.owuQiZCglMK7214KVp8j2lGQqymA4i3lPcpyxr8uObI
scenes-app-business-knowledge-playground--saved-chat--dark:
- hash: v1.k794b7964.9679c5b5506576d63a6fa87eb3a782cf9c4923c28c4921ba5b5bbb4e6a7ca085.qbsU5idHy6QnOQb0HzlGOqkAiVOnyN13qhdsBtlJY_0
+ hash: v1.k794b7964.0071e299896e5467fc857e07d2000a5e47f73f38a91d6cc0333e18f461d5e87d.FbrwmsH2s0A7Ntc2XjQrI6MxsLs5zAgNWBifTKxHwco
scenes-app-business-knowledge-playground--saved-chat--light:
- hash: v1.k794b7964.f2388b5b836e5f04fe2f7c94b51a2e7c8356bd4806cf135c1ee115951b43d2ec.syOurGASFyjDfm1O0BrEprdwtoTrpOLtWcEeMz_cYAo
+ hash: v1.k794b7964.bb58e075b37a593d5d4979d2427a5183a9c624ca67dbd977b861c5333068216b.FCVDwV8RrYTtl5_ccv2ZRNStH9BjDJDST3P_EqYHGPM
+ scenes-app-business-knowledge-playground--search-results--dark:
+ hash: v1.k794b7964.4a5178e5723a01554f25bbd2f8bcfbda830e1fe4d715638f8a8cd670a368bf7f.IsZTKk5J2yMk8-AoHT9SKgA_A8CuUqV_sGzr_HcIcf8
+ scenes-app-business-knowledge-playground--search-results--light:
+ hash: v1.k794b7964.11e67e933f080984cda5268a25348799fe68f31b315c2735ae9b624e342e8867.b6mjNKB0pZA-Oknq0lfzCo9APZc1_fjMamfiTnoHzRU
scenes-app-businessknowledge-knowledgesourcedetails--file--dark:
hash: v1.k794b7964.aa678ca573339c3280899906358dfc7a66cd6a80092cd0e85caf9eb2e9ada21d.KntYpsaUMk50Qp1knzQP00-1cOUiZGmFF7GnkPAlrwc
scenes-app-businessknowledge-knowledgesourcedetails--file--light:
diff --git a/products/business_knowledge/frontend/api.ts b/products/business_knowledge/frontend/api.ts
index 861038121a47..e3cc428cb8ef 100644
--- a/products/business_knowledge/frontend/api.ts
+++ b/products/business_knowledge/frontend/api.ts
@@ -2,6 +2,8 @@ import { getCurrentTeamId } from 'lib/utils/getAppContext'
import { apiMutator } from '../../../frontend/src/lib/api-orval-mutator'
import {
+ businessKnowledgeDocumentsSearchList,
+ businessKnowledgeDocumentsWindowList,
businessKnowledgeLibrariesCreate,
businessKnowledgeLibrariesDestroy,
businessKnowledgeLibrariesList,
@@ -21,11 +23,15 @@ import {
businessKnowledgeSourcesTextRetrieve,
} from './generated/api'
import type {
+ BusinessKnowledgeDocumentsSearchListParams,
+ BusinessKnowledgeDocumentsWindowListParams,
BusinessKnowledgeSourcesListAddedBy,
BusinessKnowledgeSourcesListParams,
BusinessKnowledgeSourcesListSourceType,
CrawlModeEnumApi,
+ KnowledgeDocumentWindowApi,
KnowledgeLibraryApi,
+ KnowledgeSearchResultApi,
KnowledgeSourceApi,
PlaygroundChatApi,
PlaygroundChatListApi,
@@ -164,6 +170,19 @@ export async function deletePlaygroundChat(chatId: string): Promise<void> {
await businessKnowledgePlaygroundChatsDestroy(String(getCurrentTeamId()), chatId)
}
+export async function searchKnowledge(
+ params: BusinessKnowledgeDocumentsSearchListParams
+): Promise<KnowledgeSearchResultApi[]> {
+ return await businessKnowledgeDocumentsSearchList(String(getCurrentTeamId()), params)
+}
+
+export async function getDocumentWindow(
+ documentId: string,
+ params: BusinessKnowledgeDocumentsWindowListParams
+): Promise<KnowledgeDocumentWindowApi[]> {
+ return await businessKnowledgeDocumentsWindowList(String(getCurrentTeamId()), documentId, params)
+}
+
export async function refreshSource(id: string): Promise<KnowledgeSourceApi> {
return await businessKnowledgeSourcesRefreshCreate(String(getCurrentTeamId()), id)
}
diff --git a/products/business_knowledge/frontend/scenes/playground/BusinessKnowledgePlaygroundScene.stories.tsx b/products/business_knowledge/frontend/scenes/playground/BusinessKnowledgePlaygroundScene.stories.tsx
index ae9ef0b7ecb0..6b8b24569c96 100644
--- a/products/business_knowledge/frontend/scenes/playground/BusinessKnowledgePlaygroundScene.stories.tsx
+++ b/products/business_knowledge/frontend/scenes/playground/BusinessKnowledgePlaygroundScene.stories.tsx
@@ -1,4 +1,5 @@
import { Meta, StoryObj } from '@storybook/react'
+import { waitFor, within } from '@testing-library/react'
import { FEATURE_FLAGS } from 'lib/constants'
import { App } from 'scenes/App'
@@ -6,7 +7,9 @@ import { urls } from 'scenes/urls'
import { mswDecorator } from '~/mocks/browser'
-import type { PlaygroundChatApi, PlaygroundChatListApi } from '../../generated/api.schemas'
+import { userEvent } from 'storybook/test'
+
+import type { KnowledgeSearchResultApi, PlaygroundChatApi, PlaygroundChatListApi } from '../../generated/api.schemas'
const listedChat: PlaygroundChatListApi = {
id: 'chat-1',
@@ -73,6 +76,40 @@ const chat: PlaygroundChatApi = {
],
}
+const searchResults: KnowledgeSearchResultApi[] = [
+ {
+ chunk_id: 'chunk-1',
+ document_id: 'doc-1',
+ ordinal: 3,
+ source_id: 'source-1',
+ source_name: 'Refund policy',
+ source_type: 'url',
+ document_title: 'Refunds and cancellations',
+ heading_path: 'Billing > Refunds',
+ content: [
+ 'Refunds are available within 30 days of purchase for annual and monthly plans.',
+ 'After 30 days, a support manager has to approve an exception. Open a ticket with the order number and the reason for the request.',
+ 'Approved exceptions are refunded to the original payment method within 5 to 10 business days.',
+ 'Usage-based charges for the current billing period are not refundable.',
+ ].join('\n\n'),
+ is_generated: false,
+ url: 'https://example.com/help/refunds',
+ },
+ {
+ chunk_id: 'chunk-2',
+ document_id: 'doc-2',
+ ordinal: 0,
+ source_id: 'source-2',
+ source_name: 'Support policies',
+ source_type: 'text',
+ document_title: 'Support policies',
+ heading_path: '',
+ content: 'Priority support is included on the Enterprise plan.',
+ is_generated: false,
+ url: '',
+ },
+]
+
// The fixtures show answers that are still running, so their spinners never hide.
const LIST_SELECTOR = '[data-attr="business-knowledge-playground-open-chat"]'
const SAVED_CHAT_SELECTORS = [LIST_SELECTOR, 'text=Refund policy']
@@ -93,6 +130,7 @@ const meta: Meta = {
get: {
'/api/projects/:team_id/business_knowledge/playground/chats/': [listedChat, olderChat],
'/api/projects/:team_id/business_knowledge/playground/chats/:chatId/': chat,
+ '/api/projects/:team_id/business_knowledge/documents/search/': searchResults,
},
}),
],
@@ -110,6 +148,37 @@ export const NewChat: Story = {
},
}
+export const SearchResults: Story = {
+ parameters: {
+ pageUrl: urls.businessKnowledgePlayground(),
+ testOptions: { waitForLoadersToDisappear: false, waitForSelector: 'text=Refunds and cancellations' },
+ },
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement)
+ await waitFor(() => {
+ const modeSearch = canvasElement.querySelector<HTMLElement>(
+ '[data-attr="business-knowledge-playground-mode-search"]'
+ )
+ if (!modeSearch) {
+ throw new Error('The mode switcher must render')
+ }
+ modeSearch.click()
+ })
+ await userEvent.type(await canvas.findByPlaceholderText('Search business knowledge'), 'refund{Enter}')
+ },
+}
+
+export const ChatCitations: Story = {
+ parameters: {
+ testOptions: { waitForLoadersToDisappear: false, waitForSelector: 'text=Refunds and cancellations' },
+ },
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement)
+ await userEvent.click(await canvas.findByText('Looked through business knowledge'))
+ await userEvent.click(await canvas.findByText('Searched business knowledge'))
+ },
+}
+
export const NarrowScene: Story = {
parameters: {
testOptions: {
diff --git a/products/business_knowledge/frontend/scenes/playground/BusinessKnowledgePlaygroundScene.test.tsx b/products/business_knowledge/frontend/scenes/playground/BusinessKnowledgePlaygroundScene.test.tsx
index 2aca6af52ace..513e23e5e0f0 100644
--- a/products/business_knowledge/frontend/scenes/playground/BusinessKnowledgePlaygroundScene.test.tsx
+++ b/products/business_knowledge/frontend/scenes/playground/BusinessKnowledgePlaygroundScene.test.tsx
@@ -1,6 +1,6 @@
import '@testing-library/jest-dom'
-import { cleanup, render, screen } from '@testing-library/react'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
import { useActions, useValues } from 'kea'
import { type ReactNode } from 'react'
@@ -113,6 +113,9 @@ describe('BusinessKnowledgePlaygroundScene', () => {
expect(document.querySelector('[data-message-type="ai"] [data-testid="react-markdown"]')).toHaveTextContent(
'**Yes**, within 30 days.'
)
+ expect(screen.getByText('1 search')).toBeInTheDocument()
+ expect(screen.queryByText('Searched business knowledge')).not.toBeInTheDocument()
+ fireEvent.click(screen.getByText('Looked through business knowledge'))
expect(screen.getByText('Searched business knowledge')).toBeInTheDocument()
expect(screen.getByText('refund window')).toBeInTheDocument()
expect(screen.queryByText(/call business-knowledge-documents-search/)).not.toBeInTheDocument()
diff --git a/products/business_knowledge/frontend/scenes/playground/BusinessKnowledgePlaygroundScene.tsx b/products/business_knowledge/frontend/scenes/playground/BusinessKnowledgePlaygroundScene.tsx
index 2c0cbc1d5a01..c6a0d74a13bd 100644
--- a/products/business_knowledge/frontend/scenes/playground/BusinessKnowledgePlaygroundScene.tsx
+++ b/products/business_knowledge/frontend/scenes/playground/BusinessKnowledgePlaygroundScene.tsx
@@ -1,3 +1,8 @@
+import { useActions, useValues } from 'kea'
+
+import { IconMessage, IconSearch } from '@posthog/icons'
+import { LemonSegmentedButton } from '@posthog/lemon-ui'
+
import { NotFound } from 'lib/components/NotFound'
import { useFeatureFlag } from 'lib/hooks/useFeatureFlag'
import { SceneExport } from 'scenes/sceneTypes'
@@ -9,6 +14,7 @@ import { ProductKey } from '~/queries/schema/schema-general'
import { BusinessKnowledgeTabs } from '../../components/BusinessKnowledgeTabs/BusinessKnowledgeTabs'
import { businessKnowledgePlaygroundLogic } from './businessKnowledgePlaygroundLogic'
import { PlaygroundChatList } from './PlaygroundChatList'
+import { PlaygroundSearch } from './PlaygroundSearch'
import { PlaygroundThread } from './PlaygroundThread'
export const scene: SceneExport = {
@@ -19,6 +25,8 @@ export const scene: SceneExport = {
export function BusinessKnowledgePlaygroundScene(): JSX.Element {
const isEnabled = useFeatureFlag('PRODUCT_BUSINESS_KNOWLEDGE')
+ const { mode } = useValues(businessKnowledgePlaygroundLogic)
+ const { setMode } = useActions(businessKnowledgePlaygroundLogic)
if (!isEnabled) {
return <NotFound object="Business knowledge" caption="This feature is not enabled for your project." />
@@ -32,11 +40,38 @@ export function BusinessKnowledgePlaygroundScene(): JSX.Element {
resourceType={{ type: 'business_knowledge' }}
/>
<BusinessKnowledgeTabs activeTab="playground" />
- {/* 521px: a 520px scene stacks the list above the thread. */}
- <div className="@container flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden @min-[32.5625rem]:flex-row">
- <PlaygroundChatList />
- <PlaygroundThread />
+ <div>
+ <LemonSegmentedButton
+ size="small"
+ value={mode}
+ onChange={setMode}
+ options={[
+ {
+ value: 'chat',
+ label: 'Chat',
+ icon: <IconMessage />,
+ // pinned: autocapture / Playwright key. Do not rename.
+ 'data-attr': 'business-knowledge-playground-mode-chat',
+ },
+ {
+ value: 'search',
+ label: 'Search',
+ icon: <IconSearch />,
+ // pinned: autocapture / Playwright key. Do not rename.
+ 'data-attr': 'business-knowledge-playground-mode-search',
+ },
+ ]}
+ />
</div>
+ {mode === 'search' ? (
+ <PlaygroundSearch />
+ ) : (
+ // 521px: a 520px scene stacks the list above the thread.
+ <div className="@container flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden @min-[32.5625rem]:flex-row">
+ <PlaygroundChatList />
+ <PlaygroundThread />
+ </div>
+ )}
</SceneContent>
)
}
diff --git a/products/business_knowledge/frontend/scenes/playground/PlaygroundChunk.tsx b/products/business_knowledge/frontend/scenes/playground/PlaygroundChunk.tsx
new file mode 100644
index 000000000000..b209e691bf2f
--- /dev/null
+++ b/products/business_knowledge/frontend/scenes/playground/PlaygroundChunk.tsx
@@ -0,0 +1,70 @@
+import { useState } from 'react'
+
+import { IconCopy } from '@posthog/icons'
+import { LemonButton, LemonCard } from '@posthog/lemon-ui'
+
+import { Link } from 'lib/lemon-ui/Link'
+import { copyToClipboard } from 'lib/utils/copyToClipboard'
+import { cn } from 'lib/utils/css-classes'
+
+import type { KnowledgeSearchResultApi } from '../../generated/api.schemas'
+
+// About four lines at this width. Counting avoids measuring the rendered text.
+const COLLAPSE_AFTER_CHARS = 400
+const COLLAPSE_AFTER_LINES = 4
+
+export interface PlaygroundChunkProps {
+ chunk: KnowledgeSearchResultApi
+ rank: number
+}
+
+export function PlaygroundChunk({ chunk, rank }: PlaygroundChunkProps): JSX.Element {
+ const [expanded, setExpanded] = useState(false)
+ const collapsible =
+ chunk.content.length > COLLAPSE_AFTER_CHARS || chunk.content.split('\n').length > COLLAPSE_AFTER_LINES
+ const title = chunk.document_title || chunk.source_name
+
+ return (
+ <LemonCard hoverEffect={false} className="flex flex-col gap-2 p-3">
+ <div className="flex items-start gap-2">
+ <span className="font-semibold text-secondary">{`#${rank}`}</span>
+ <div className="flex min-w-0 flex-1 flex-col">
+ {chunk.url ? (
+ <Link to={chunk.url} target="_blank" className="truncate font-semibold">
+ {title}
+ </Link>
+ ) : (
+ <span className="truncate font-semibold">{title}</span>
+ )}
+ {title !== chunk.source_name ? (
+ <span className="truncate text-xs text-secondary">{chunk.source_name}</span>
+ ) : null}
+ {chunk.heading_path ? (
+ <span className="text-xs break-words text-secondary">{chunk.heading_path}</span>
+ ) : null}
+ </div>
+ <LemonButton
+ size="xsmall"
+ icon={<IconCopy />}
+ tooltip="Copy chunk"
+ onClick={() => void copyToClipboard(chunk.content, 'chunk')}
+ />
+ </div>
+ <div
+ className={cn('text-sm break-words', collapsible && !expanded ? 'line-clamp-4' : 'whitespace-pre-wrap')}
+ >
+ {chunk.content}
+ </div>
+ {collapsible ? (
+ <LemonButton
+ size="xsmall"
+ type="tertiary"
+ className="self-start"
+ onClick={() => setExpanded(!expanded)}
+ >
+ {expanded ? 'Show less' : 'Show full chunk'}
+ </LemonButton>
+ ) : null}
+ </LemonCard>
+ )
+}
diff --git a/products/business_knowledge/frontend/scenes/playground/PlaygroundCitationRow.tsx b/products/business_knowledge/frontend/scenes/playground/PlaygroundCitationRow.tsx
new file mode 100644
index 000000000000..680d7dd5f96d
--- /dev/null
+++ b/products/business_knowledge/frontend/scenes/playground/PlaygroundCitationRow.tsx
@@ -0,0 +1,55 @@
+import { IconChevronRight, IconCopy } from '@posthog/icons'
+import { LemonButton, LemonTag } from '@posthog/lemon-ui'
+
+import { copyToClipboard } from 'lib/utils/copyToClipboard'
+
+import type { PlaygroundCitationChunk } from './playgroundCitationsLogic'
+
+export interface PlaygroundCitationRowProps {
+ chunk: PlaygroundCitationChunk
+ /** Search position. Omitted for chunks read in document order. */
+ rank?: number
+ cited: boolean
+}
+
+export function PlaygroundCitationRow({ chunk, rank, cited }: PlaygroundCitationRowProps): JSX.Element {
+ const title = chunk.document_title || chunk.source_name
+ const location = [title !== chunk.source_name ? chunk.source_name : '', chunk.heading_path]
+ .filter(Boolean)
+ .join(' · ')
+
+ return (
+ <details className="group min-w-0">
+ <summary className="flex min-w-0 cursor-pointer list-none items-center gap-1.5 py-0.5 [&::-webkit-details-marker]:hidden">
+ <IconChevronRight className="shrink-0 text-secondary transition-transform group-open:rotate-90 motion-reduce:transition-none" />
+ {rank !== undefined ? <span className="shrink-0 text-secondary tabular-nums">{`#${rank}`}</span> : null}
+ <span className="max-w-fit min-w-0 shrink truncate font-semibold">{title}</span>
+ {cited ? (
+ <LemonTag size="small" type="success" className="shrink-0">
+ Cited
+ </LemonTag>
+ ) : null}
+ <span className="min-w-0 flex-1 truncate text-secondary group-open:invisible">{chunk.content}</span>
+ </summary>
+ <div className="ml-5 flex flex-col gap-1 pb-2">
+ {location ? <span className="text-xs text-secondary">{location}</span> : null}
+ <div className="break-words whitespace-pre-wrap">{chunk.content}</div>
+ <div className="flex flex-wrap gap-1">
+ <LemonButton
+ size="xsmall"
+ type="secondary"
+ icon={<IconCopy />}
+ onClick={() => void copyToClipboard(chunk.content, 'chunk')}
+ >
+ Copy
+ </LemonButton>
+ {chunk.url ? (
+ <LemonButton size="xsmall" type="secondary" to={chunk.url} targetBlank>
+ Open page
+ </LemonButton>
+ ) : null}
+ </div>
+ </div>
+ </details>
+ )
+}
diff --git a/products/business_knowledge/frontend/scenes/playground/PlaygroundCitations.tsx b/products/business_knowledge/frontend/scenes/playground/PlaygroundCitations.tsx
new file mode 100644
index 000000000000..6d3ad82b7786
--- /dev/null
+++ b/products/business_knowledge/frontend/scenes/playground/PlaygroundCitations.tsx
@@ -0,0 +1,40 @@
+import { useValues } from 'kea'
+
+import { LemonBanner, LemonSkeleton } from '@posthog/lemon-ui'
+
+import { PlaygroundCitationRow } from './PlaygroundCitationRow'
+import { playgroundCitationsLogic } from './playgroundCitationsLogic'
+import { type PlaygroundCitationRequest, isCitedChunk } from './playgroundDisplay'
+
+export interface PlaygroundCitationsProps {
+ citationKey: string
+ request: PlaygroundCitationRequest
+ /** Source refs from the answer, used to tag the chunks it cited. */
+ citedRefs: string[]
+}
+
+export function PlaygroundCitations({ citationKey, request, citedRefs }: PlaygroundCitationsProps): JSX.Element {
+ const { chunks, chunksError } = useValues(playgroundCitationsLogic({ citationKey, request }))
+
+ if (chunksError) {
+ return <LemonBanner type="error">{chunksError}</LemonBanner>
+ }
+ if (chunks === null) {
+ return <LemonSkeleton repeat={3} className="h-5" />
+ }
+ if (chunks.length === 0) {
+ return <div className="text-secondary">No chunks match this search now.</div>
+ }
+ return (
+ <div className="flex min-w-0 flex-col">
+ {chunks.map((chunk, index) => (
+ <PlaygroundCitationRow
+ key={chunk.chunk_id}
+ chunk={chunk}
+ rank={request.kind === 'search' ? index + 1 : undefined}
+ cited={isCitedChunk(chunk, citedRefs)}
+ />
+ ))}
+ </div>
+ )
+}
diff --git a/products/business_knowledge/frontend/scenes/playground/PlaygroundSearch.tsx b/products/business_knowledge/frontend/scenes/playground/PlaygroundSearch.tsx
new file mode 100644
index 000000000000..042e759dc607
--- /dev/null
+++ b/products/business_knowledge/frontend/scenes/playground/PlaygroundSearch.tsx
@@ -0,0 +1,62 @@
+import { useActions, useValues } from 'kea'
+
+import { IconSearch } from '@posthog/icons'
+import { LemonBanner, LemonButton, LemonInput, LemonSkeleton } from '@posthog/lemon-ui'
+
+import { businessKnowledgePlaygroundLogic } from './businessKnowledgePlaygroundLogic'
+import { PlaygroundChunk } from './PlaygroundChunk'
+
+export function PlaygroundSearch(): JSX.Element {
+ const { searchQuery, searching, searchResults, searchError } = useValues(businessKnowledgePlaygroundLogic)
+ const { setSearchQuery, search } = useActions(businessKnowledgePlaygroundLogic)
+
+ return (
+ <div className="min-h-0 min-w-0 flex-1 overflow-y-auto">
+ <div className="mx-auto flex w-full max-w-180 flex-col gap-3 p-4">
+ <div className="flex gap-2">
+ <LemonInput
+ type="search"
+ autoFocus
+ fullWidth
+ className="min-w-0 flex-1"
+ placeholder="Search business knowledge"
+ aria-label="Search business knowledge"
+ value={searchQuery}
+ onChange={setSearchQuery}
+ onPressEnter={() => search()}
+ // pinned: autocapture / Playwright key. Do not rename.
+ data-attr="business-knowledge-playground-search-query"
+ />
+ <LemonButton
+ type="primary"
+ icon={<IconSearch />}
+ loading={searching}
+ disabledReason={searchQuery.trim() ? undefined : 'Enter something to search for'}
+ onClick={() => search()}
+ // pinned: autocapture / Playwright key. Do not rename.
+ data-attr="business-knowledge-playground-search"
+ >
+ Search
+ </LemonButton>
+ </div>
+ {searching ? (
+ <LemonSkeleton repeat={3} className="h-24" />
+ ) : searchError ? (
+ <LemonBanner type="error">{searchError}</LemonBanner>
+ ) : searchResults === null ? (
+ <div className="py-8 text-center text-secondary">
+ Search returns the matching chunks from your business knowledge, without writing an answer.
+ </div>
+ ) : searchResults.length === 0 ? (
+ <div className="py-8 text-center text-secondary">
+ No chunks match this search. Try other words, or check that your sources finished processing.
+ </div>
+ ) : (
+ searchResults.map((result, index) => (
+ <PlaygroundChunk key={result.chunk_id} rank={index + 1} chunk={result} />
+ ))
+ )}
+ </div>
+ </div>
+ )
+}
diff --git a/products/business_knowledge/frontend/scenes/playground/PlaygroundTrace.tsx b/products/business_knowledge/frontend/scenes/playground/PlaygroundTrace.tsx
new file mode 100644
index 000000000000..8ce4fbaae0f8
--- /dev/null
+++ b/products/business_knowledge/frontend/scenes/playground/PlaygroundTrace.tsx
@@ -0,0 +1,63 @@
+import { IconDocument, IconGithub, IconSearch } from '@posthog/icons'
+
+import { Thread } from 'products/posthog_ai/frontend/api/primitives'
+
+import { type SandboxSearchApi, SandboxToolNameEnumApi } from '../../generated/api.schemas'
+import { PlaygroundCitations } from './PlaygroundCitations'
+import { citationRequest, describeSearch, summarizeSearches } from './playgroundDisplay'
+
+export interface PlaygroundTraceProps {
+ id: string
+ running: boolean
+ searches: SandboxSearchApi[]
+ /** Source refs from the answer, used to tag the chunks it cited. */
+ citedRefs: string[]
+}
+
+function searchIcon(tool: string): JSX.Element {
+ if (tool === SandboxToolNameEnumApi.BusinessKnowledgeRepositoriesSearch) {
+ return <IconGithub />
+ }
+ return tool === SandboxToolNameEnumApi.BusinessKnowledgeDocumentsSearch ? <IconSearch /> : <IconDocument />
+}
+
+export function PlaygroundTrace({ id, running, searches, citedRefs }: PlaygroundTraceProps): JSX.Element {
+ const steps = searches.map((search, index) => {
+ const label = describeSearch(search)
+ const request = citationRequest(search)
+ return (
+ <Thread.Activity
+ key={`${search.tool}-${index}`}
+ id={`${id}-search-${index}`}
+ title={label.title}
+ subtitle={label.subtitle}
+ status="completed"
+ icon={searchIcon(search.tool)}
+ animate={false}
+ showCompletionIcon={false}
+ details={
+ request ? (
+ <PlaygroundCitations
+ citationKey={`${id}-search-${index}`}
+ request={request}
+ citedRefs={citedRefs}
+ />
+ ) : undefined
+ }
+ />
+ )
+ })
+
+ // Open while the answer runs, folded once it finishes.
+ return (
+ <Thread.Activity
+ id={`${id}-trace`}
+ title={running ? 'Looking through business knowledge' : 'Looked through business knowledge'}
+ subtitle={summarizeSearches(searches)}
+ status={running ? 'in_progress' : 'completed'}
+ animate={running}
+ showCompletionIcon={false}
+ details={steps.length > 0 ? <div className="flex min-w-0 flex-col gap-1">{steps}</div> : undefined}
+ />
+ )
+}
diff --git a/products/business_knowledge/frontend/scenes/playground/PlaygroundTurn.tsx b/products/business_knowledge/frontend/scenes/playground/PlaygroundTurn.tsx
index 1c7fae33841c..55146eecb938 100644
--- a/products/business_knowledge/frontend/scenes/playground/PlaygroundTurn.tsx
+++ b/products/business_knowledge/frontend/scenes/playground/PlaygroundTurn.tsx
@@ -1,13 +1,11 @@
import { memo } from 'react'
-import { IconDocument, IconGithub, IconSearch } from '@posthog/icons'
-
import { LemonMarkdown } from 'lib/lemon-ui/LemonMarkdown'
import { Thread } from 'products/posthog_ai/frontend/api/primitives'
-import { type PlaygroundTurnApi, SandboxToolNameEnumApi } from '../../generated/api.schemas'
-import { describeSearch } from './playgroundDisplay'
+import type { PlaygroundTurnApi } from '../../generated/api.schemas'
+import { PlaygroundTrace } from './PlaygroundTrace'
export interface PlaygroundTurnProps {
id: string
@@ -20,43 +18,16 @@ export const PlaygroundTurn = memo(function PlaygroundTurn({ id, question, turn
const run = turn?.run ?? null
const isRunning = turn === null || run?.status === 'running'
const error = turn?.error ?? run?.error ?? null
+ const searches = run?.searches ?? []
+ const citedRefs = run?.sources.map((source) => source.ref) ?? []
return (
<>
<Thread.Message type="human">
<Thread.Markdown content={question} id={`${id}-question`} />
</Thread.Message>
- {run?.searches.map((search, index) => {
- const label = describeSearch(search)
- return (
- <Thread.Activity
- key={`${search.tool}-${index}`}
- id={`${id}-search-${index}`}
- title={label.title}
- subtitle={label.subtitle}
- status="completed"
- icon={
- search.tool === SandboxToolNameEnumApi.BusinessKnowledgeRepositoriesSearch ? (
- <IconGithub />
- ) : search.tool === SandboxToolNameEnumApi.BusinessKnowledgeDocumentsSearch ? (
- <IconSearch />
- ) : (
- <IconDocument />
- )
- }
- animate={false}
- showCompletionIcon={false}
- />
- )
- })}
- {isRunning ? (
- <Thread.Reasoning
- content="Looking through business knowledge"
- completed={false}
- id={`${id}-running`}
- showCompletionIcon={false}
- animate
- />
+ {isRunning || searches.length > 0 ? (
+ <PlaygroundTrace id={id} running={isRunning} searches={searches} citedRefs={citedRefs} />
) : null}
{run?.status === 'completed' && run.reply ? (
<Thread.Message type="ai" wrapperClassName="max-w-4/5">
diff --git a/products/business_knowledge/frontend/scenes/playground/businessKnowledgePlaygroundLogic.test.ts b/products/business_knowledge/frontend/scenes/playground/businessKnowledgePlaygroundLogic.test.ts
index 323ff9a00d97..06eea6583ae3 100644
--- a/products/business_knowledge/frontend/scenes/playground/businessKnowledgePlaygroundLogic.test.ts
+++ b/products/business_knowledge/frontend/scenes/playground/businessKnowledgePlaygroundLogic.test.ts
@@ -6,8 +6,19 @@ import { urls } from 'scenes/urls'
import { initKeaTests } from '~/test/init'
-import { askPlaygroundChat, createPlaygroundChat, getPlaygroundChat, listPlaygroundChats } from '../../api'
-import type { PlaygroundChatApi, PlaygroundChatListApi, SandboxRunApi } from '../../generated/api.schemas'
+import {
+ askPlaygroundChat,
+ createPlaygroundChat,
+ getPlaygroundChat,
+ listPlaygroundChats,
+ searchKnowledge,
+} from '../../api'
+import type {
+ KnowledgeSearchResultApi,
+ PlaygroundChatApi,
+ PlaygroundChatListApi,
+ SandboxRunApi,
+} from '../../generated/api.schemas'
import { businessKnowledgePlaygroundLogic } from './businessKnowledgePlaygroundLogic'
jest.mock('../../api', () => ({
@@ -16,12 +27,14 @@ jest.mock('../../api', () => ({
getPlaygroundChat: jest.fn(),
askPlaygroundChat: jest.fn(),
deletePlaygroundChat: jest.fn(),
+ searchKnowledge: jest.fn(),
}))
const mockedList = listPlaygroundChats as jest.MockedFunction<typeof listPlaygroundChats>
const mockedCreate = createPlaygroundChat as jest.MockedFunction<typeof createPlaygroundChat>
const mockedGet = getPlaygroundChat as jest.MockedFunction<typeof getPlaygroundChat>
const mockedAsk = askPlaygroundChat as jest.MockedFunction<typeof askPlaygroundChat>
+const mockedSearch = searchKnowledge as jest.MockedFunction<typeof searchKnowledge>
function run(status: SandboxRunApi['status'], extra: Partial<SandboxRunApi> = {}): SandboxRunApi {
return {
@@ -237,6 +250,38 @@ describe('businessKnowledgePlaygroundLogic', () => {
expect(logic.values.asking).toBe(false)
})
+ it('shows a search error, then replaces it with the next results', async () => {
+ const hit: KnowledgeSearchResultApi = {
+ chunk_id: 'chunk-1',
+ document_id: 'doc-1',
+ ordinal: 0,
+ source_id: 'source-1',
+ source_name: 'Refund policy',
+ source_type: 'text',
+ document_title: 'Refund policy',
+ heading_path: '',
+ content: 'Refunds after 30 days need manager approval.',
+ is_generated: false,
+ url: '',
+ }
+ mockedSearch.mockRejectedValueOnce(new ApiError('invalid', 400, undefined, { detail: 'Query is too long.' }))
+ logic.actions.setSearchQuery(' refund ')
+ await expectLogic(logic, () => {
+ logic.actions.search()
+ }).toDispatchActions(['setSearchError'])
+ expect(logic.values.searching).toBe(false)
+ expect(logic.values.searchError).toBe('Query is too long.')
+
+ mockedSearch.mockResolvedValueOnce([hit])
+ await expectLogic(logic, () => {
+ logic.actions.search()
+ }).toDispatchActions(['setSearchResults'])
+ expect(mockedSearch).toHaveBeenLastCalledWith({ query: 'refund' })
+ expect(logic.values.searching).toBe(false)
+ expect(logic.values.searchError).toBeNull()
+ expect(logic.values.searchResults).toEqual([hit])
+ })
+
it('ignores a poll response that arrives after a newer one', async () => {
let resolveOlder: (value: PlaygroundChatApi) => void = () => {}
mockedGet
diff --git a/products/business_knowledge/frontend/scenes/playground/businessKnowledgePlaygroundLogic.ts b/products/business_knowledge/frontend/scenes/playground/businessKnowledgePlaygroundLogic.ts
index 6a7710e9dc03..09bdefaade24 100644
--- a/products/business_knowledge/frontend/scenes/playground/businessKnowledgePlaygroundLogic.ts
+++ b/products/business_knowledge/frontend/scenes/playground/businessKnowledgePlaygroundLogic.ts
@@ -12,22 +12,23 @@ import {
deletePlaygroundChat,
getPlaygroundChat,
listPlaygroundChats,
+ searchKnowledge,
} from '../../api'
-import type { PlaygroundChatApi, PlaygroundChatListApi, SandboxRunApi } from '../../generated/api.schemas'
-import { type PlaygroundChatGroup, groupPlaygroundChats } from './playgroundDisplay'
+import type {
+ KnowledgeSearchResultApi,
+ PlaygroundChatApi,
+ PlaygroundChatListApi,
+ SandboxRunApi,
+} from '../../generated/api.schemas'
+import { type PlaygroundChatGroup, errorDetail, groupPlaygroundChats } from './playgroundDisplay'
+
+export type PlaygroundMode = 'chat' | 'search'
const POLL_MS = 2000
const LIST_POLL_MS = 5000
// Matches MAX_OPEN_RUNS_PER_OWNER in backend/sandbox.py. The server still enforces the limit.
const MAX_OPEN_ANSWERS = 3
-function errorDetail(error: unknown, fallback: string): string {
- if (error instanceof ApiError && error.detail) {
- return error.detail
- }
- return fallback
-}
-
function isTerminal(run: SandboxRunApi | null): boolean {
return run?.status === 'completed' || run?.status === 'failed' || run?.status === 'cancelled'
}
@@ -52,8 +53,13 @@ export interface businessKnowledgePlaygroundLogicValues {
chats: PlaygroundChatListApi[]
chatsLoading: boolean
deletingChatId: string | null
+ mode: PlaygroundMode
pendingQuestion: string | null
question: string
+ searchError: string | null
+ searchQuery: string
+ searchResults: KnowledgeSearchResultApi[] | null
+ searching: boolean
}
// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
@@ -94,6 +100,9 @@ export interface businessKnowledgePlaygroundLogicActions {
pollFailed: (error: string) => {
error: string
}
+ search: () => {
+ value: true
+ }
setAskError: (askError: string | null) => {
askError: string | null
}
@@ -115,12 +124,27 @@ export interface businessKnowledgePlaygroundLogicActions {
setDeletingChatId: (deletingChatId: string | null) => {
deletingChatId: string | null
}
+ setMode: (mode: PlaygroundMode) => {
+ mode: PlaygroundMode
+ }
setPendingQuestion: (pendingQuestion: string | null) => {
pendingQuestion: string | null
}
setQuestion: (question: string) => {
question: string
}
+ setSearchError: (searchError: string | null) => {
+ searchError: string | null
+ }
+ setSearchQuery: (searchQuery: string) => {
+ searchQuery: string
+ }
+ setSearchResults: (searchResults: KnowledgeSearchResultApi[]) => {
+ searchResults: KnowledgeSearchResultApi[]
+ }
+ setSearching: (searching: boolean) => {
+ searching: boolean
+ }
startPolling: () => {
value: true
}
@@ -167,6 +191,12 @@ export const businessKnowledgePlaygroundLogic = kea<businessKnowledgePlaygroundL
startPolling: true,
poll: true,
pollFailed: (error: string) => ({ error }),
+ setMode: (mode: PlaygroundMode) => ({ mode }),
+ setSearchQuery: (searchQuery: string) => ({ searchQuery }),
+ search: true,
+ setSearching: (searching: boolean) => ({ searching }),
+ setSearchResults: (searchResults: KnowledgeSearchResultApi[]) => ({ searchResults }),
+ setSearchError: (searchError: string | null) => ({ searchError }),
}),
loaders(() => ({
chats: [
@@ -248,6 +278,36 @@ export const businessKnowledgePlaygroundLogic = kea<businessKnowledgePlaygroundL
setDeletingChatId: (_, { deletingChatId }) => deletingChatId,
},
],
+ mode: [
+ 'chat' as PlaygroundMode,
+ {
+ setMode: (_, { mode }) => mode,
+ },
+ ],
+ searchQuery: [
+ '',
+ {
+ setSearchQuery: (_, { searchQuery }) => searchQuery,
+ },
+ ],
+ searching: [
+ false,
+ {
+ setSearching: (_, { searching }) => searching,
+ },
+ ],
+ searchResults: [
+ null as KnowledgeSearchResultApi[] | null,
+ {
+ setSearchResults: (_, { searchResults }) => searchResults,
+ },
+ ],
+ searchError: [
+ null as string | null,
+ {
+ setSearchError: (_, { searchError }) => searchError,
+ },
+ ],
}),
selectors({
chatHasOpenTurn: [(s) => [s.chat], (chat: PlaygroundChatApi | null): boolean => hasOpenTurn(chat)],
@@ -445,6 +505,31 @@ export const businessKnowledgePlaygroundLogic = kea<businessKnowledgePlaygroundL
cache.disposables.dispose('playgroundPoll')
actions.setAsking(false)
},
+ search: async () => {
+ const query = values.searchQuery.trim()
+ if (!query || values.searching) {
+ return
+ }
+ actions.setSearching(true)
+ actions.setSearchError(null)
+ try {
+ const results = await searchKnowledge({ query })
+ if (cache.disposables.isDisposed) {
+ return
+ }
+ posthog.capture('business knowledge playground searched', { result_count: results.length })
+ actions.setSearchResults(results)
+ } catch (error) {
+ if (cache.disposables.isDisposed) {
+ return
+ }
+ actions.setSearchError(errorDetail(error, "Couldn't search business knowledge. Try again."))
+ } finally {
+ if (!cache.disposables.isDisposed) {
+ actions.setSearching(false)
+ }
+ }
+ },
}
}),
urlToAction(({ actions, values }) => ({
diff --git a/products/business_knowledge/frontend/scenes/playground/playgroundCitationsLogic.ts b/products/business_knowledge/frontend/scenes/playground/playgroundCitationsLogic.ts
new file mode 100644
index 000000000000..3ab6e68f7d14
--- /dev/null
+++ b/products/business_knowledge/frontend/scenes/playground/playgroundCitationsLogic.ts
@@ -0,0 +1,93 @@
+import { MakeLogicType, actions, afterMount, kea, key, listeners, path, props, reducers } from 'kea'
+import posthog from 'posthog-js'
+
+import { getDocumentWindow, searchKnowledge } from '../../api'
+import type { KnowledgeDocumentWindowApi, KnowledgeSearchResultApi } from '../../generated/api.schemas'
+import { type PlaygroundCitationRequest, errorDetail } from './playgroundDisplay'
+
+export type PlaygroundCitationChunk = KnowledgeSearchResultApi | KnowledgeDocumentWindowApi
+
+export interface PlaygroundCitationsLogicProps {
+ citationKey: string
+ request: PlaygroundCitationRequest
+}
+
+// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
+export interface playgroundCitationsLogicValues {
+ chunks: PlaygroundCitationChunk[] | null
+ chunksError: string | null
+}
+
+// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
+export interface playgroundCitationsLogicActions {
+ loadChunks: () => {
+ value: true
+ }
+ setChunks: (chunks: PlaygroundCitationChunk[]) => {
+ chunks: PlaygroundCitationChunk[]
+ }
+ setChunksError: (chunksError: string) => {
+ chunksError: string
+ }
+}
+
+// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
+export interface playgroundCitationsLogicMeta {
+ key: string
+}
+
+export type playgroundCitationsLogicType = MakeLogicType<
+ playgroundCitationsLogicValues,
+ playgroundCitationsLogicActions,
+ PlaygroundCitationsLogicProps,
+ playgroundCitationsLogicMeta
+>
+
+export const playgroundCitationsLogic = kea<playgroundCitationsLogicType>([
+ props({} as PlaygroundCitationsLogicProps),
+ key((props) => props.citationKey),
+ path((key) => ['products', 'business_knowledge', 'frontend', 'scenes', 'playgroundCitationsLogic', key]),
+ actions({
+ loadChunks: true,
+ setChunks: (chunks: PlaygroundCitationChunk[]) => ({ chunks }),
+ setChunksError: (chunksError: string) => ({ chunksError }),
+ }),
+ reducers({
+ chunks: [
+ null as PlaygroundCitationChunk[] | null,
+ {
+ setChunks: (_, { chunks }) => chunks,
+ },
+ ],
+ chunksError: [
+ null as string | null,
+ {
+ loadChunks: () => null,
+ setChunksError: (_, { chunksError }) => chunksError,
+ },
+ ],
+ }),
+ listeners(({ actions, props, cache }) => ({
+ loadChunks: async () => {
+ const { request } = props
+ try {
+ const chunks =
+ request.kind === 'search'
+ ? await searchKnowledge(request.params)
+ : await getDocumentWindow(request.documentId, request.params)
+ if (!cache.disposables.isDisposed) {
+ actions.setChunks(chunks)
+ }
+ } catch (error) {
+ if (!cache.disposables.isDisposed) {
+ actions.setChunksError(errorDetail(error, "Couldn't load these chunks. Try again."))
+ }
+ }
+ },
+ })),
+ // Replays the logged call on expand. The run does not store tool output, so changed sources give different chunks.
+ afterMount(({ actions, props }) => {
+ posthog.capture('business knowledge playground citations opened', { kind: props.request.kind })
+ actions.loadChunks()
+ }),
+])
diff --git a/products/business_knowledge/frontend/scenes/playground/playgroundDisplay.test.ts b/products/business_knowledge/frontend/scenes/playground/playgroundDisplay.test.ts
index 9c57ccf48c62..c952be4c7f16 100644
--- a/products/business_knowledge/frontend/scenes/playground/playgroundDisplay.test.ts
+++ b/products/business_knowledge/frontend/scenes/playground/playgroundDisplay.test.ts
@@ -1,5 +1,5 @@
import { SandboxToolNameEnumApi } from '../../generated/api.schemas'
-import { describeSearch } from './playgroundDisplay'
+import { citationRequest, describeSearch, isCitedChunk } from './playgroundDisplay'
describe('describeSearch', () => {
it('labels repository search and file reads separately from knowledge search', () => {
@@ -23,3 +23,56 @@ describe('describeSearch', () => {
).toBe('Read document context')
})
})
+
+describe('citationRequest', () => {
+ it.each([
+ {
+ name: 'a single-exec search keeps every retrieval argument',
+ search: {
+ tool: SandboxToolNameEnumApi.BusinessKnowledgeDocumentsSearch,
+ input: 'call business-knowledge-documents-search {"query": "refund", "limit": 5, "rerank": true, "library_id": "lib-1"}',
+ },
+ expected: { kind: 'search', params: { query: 'refund', limit: 5, rerank: true, library_id: 'lib-1' } },
+ },
+ {
+ name: 'a window read targets its document and ordinal',
+ search: {
+ tool: SandboxToolNameEnumApi.BusinessKnowledgeDocumentWindowRetrieve,
+ input: JSON.stringify({ id: 'doc-1', around_ordinal: 3, radius: 2 }),
+ },
+ expected: { kind: 'window', documentId: 'doc-1', params: { around_ordinal: 3, radius: 2 } },
+ },
+ {
+ name: 'a repository search has no chunks to show',
+ search: {
+ tool: SandboxToolNameEnumApi.BusinessKnowledgeRepositoriesSearch,
+ input: JSON.stringify({ query: 'billing' }),
+ },
+ expected: null,
+ },
+ {
+ name: 'an unparseable input has no request',
+ search: { tool: SandboxToolNameEnumApi.BusinessKnowledgeDocumentsSearch, input: 'not json' },
+ expected: null,
+ },
+ ])('$name', ({ search, expected }) => {
+ expect(citationRequest(search)).toEqual(expected)
+ })
+})
+
+describe('isCitedChunk', () => {
+ const chunk = { source_name: 'Help center', document_title: 'Refunds and cancellations' }
+
+ it.each([
+ { name: 'a ref naming the source', refs: ['Help center'], expected: true },
+ {
+ name: 'a ref that adds a section to the title',
+ refs: ['Refunds and cancellations, after 30 days'],
+ expected: true,
+ },
+ { name: 'a ref for another source', refs: ['Support plans'], expected: false },
+ { name: 'a blank ref', refs: [' '], expected: false },
+ ])('$name', ({ refs, expected }) => {
+ expect(isCitedChunk(chunk, refs)).toBe(expected)
+ })
+})
diff --git a/products/business_knowledge/frontend/scenes/playground/playgroundDisplay.ts b/products/business_knowledge/frontend/scenes/playground/playgroundDisplay.ts
index a686f2633a56..4131f58f233d 100644
--- a/products/business_knowledge/frontend/scenes/playground/playgroundDisplay.ts
+++ b/products/business_knowledge/frontend/scenes/playground/playgroundDisplay.ts
@@ -1,7 +1,15 @@
+import { ApiError } from 'lib/api'
import { dayjs } from 'lib/dayjs'
import { humanFriendlyDuration } from 'lib/utils/durations'
-import { type PlaygroundChatListApi, type SandboxSearchApi, SandboxToolNameEnumApi } from '../../generated/api.schemas'
+import {
+ type BusinessKnowledgeDocumentsSearchListParams,
+ type BusinessKnowledgeDocumentsWindowListParams,
+ type KnowledgeSearchResultApi,
+ type PlaygroundChatListApi,
+ type SandboxSearchApi,
+ SandboxToolNameEnumApi,
+} from '../../generated/api.schemas'
const DATE_GROUP_ORDER = ['Today', 'Yesterday', 'Last 7 days', 'Last 30 days', 'Older'] as const
@@ -17,6 +25,17 @@ export interface PlaygroundSearchLabel {
subtitle: string | null
}
+export type PlaygroundCitationRequest =
+ | { kind: 'search'; params: BusinessKnowledgeDocumentsSearchListParams }
+ | { kind: 'window'; documentId: string; params: BusinessKnowledgeDocumentsWindowListParams }
+
+export function errorDetail(error: unknown, fallback: string): string {
+ if (error instanceof ApiError && error.detail) {
+ return error.detail
+ }
+ return fallback
+}
+
function dateGroupLabel(iso: string, now: dayjs.Dayjs): PlaygroundChatGroupLabel {
const date = dayjs(iso)
const today = now.startOf('day')
@@ -93,3 +112,61 @@ export function describeSearch(search: SandboxSearchApi): PlaygroundSearchLabel
}
return { title: 'Read document context', subtitle: args ? null : search.input }
}
+
+/** Folded trace subtitle, such as "2 searches, 1 read". Null before the first call. */
+export function summarizeSearches(searches: SandboxSearchApi[]): string | null {
+ const reads = searches.filter(
+ (search) =>
+ search.tool === SandboxToolNameEnumApi.BusinessKnowledgeDocumentWindowRetrieve ||
+ search.tool === SandboxToolNameEnumApi.BusinessKnowledgeRepositoriesFileRetrieve
+ ).length
+ const lookups = searches.length - reads
+ const parts = [
+ lookups > 0 ? `${lookups} ${lookups === 1 ? 'search' : 'searches'}` : null,
+ reads > 0 ? `${reads} ${reads === 1 ? 'read' : 'reads'}` : null,
+ ].filter((part): part is string => part !== null)
+ return parts.length > 0 ? parts.join(', ') : null
+}
+
+/** Source refs are free text the agent writes, so this matches loosely on source and document names. */
+export function isCitedChunk(
+ chunk: Pick<KnowledgeSearchResultApi, 'source_name' | 'document_title'>,
+ refs: string[]
+): boolean {
+ const names = [chunk.source_name, chunk.document_title].map((name) => name.trim().toLowerCase()).filter(Boolean)
+ return refs.some((ref) => {
+ const needle = ref.trim().toLowerCase()
+ return needle !== '' && names.some((name) => needle.includes(name) || name.includes(needle))
+ })
+}
+
+/** The request that fetches the chunks a document search or window read returned. Null for other tools. */
+export function citationRequest(search: SandboxSearchApi): PlaygroundCitationRequest | null {
+ const args = searchArguments(search)
+ if (search.tool === SandboxToolNameEnumApi.BusinessKnowledgeDocumentsSearch && typeof args?.query === 'string') {
+ return {
+ kind: 'search',
+ params: {
+ query: args.query,
+ ...(typeof args.limit === 'number' ? { limit: args.limit } : {}),
+ ...(typeof args.rerank === 'boolean' ? { rerank: args.rerank } : {}),
+ ...(typeof args.library_id === 'string' ? { library_id: args.library_id } : {}),
+ },
+ }
+ }
+ if (
+ search.tool === SandboxToolNameEnumApi.BusinessKnowledgeDocumentWindowRetrieve &&
+ typeof args?.id === 'string' &&
+ typeof args.around_ordinal === 'number'
+ ) {
+ return {
+ kind: 'window',
+ documentId: args.id,
+ params: {
+ around_ordinal: args.around_ordinal,
+ ...(typeof args.radius === 'number' ? { radius: args.radius } : {}),
+ },
+ }
+ }
+ return null
+}