OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.
Python
feat: search result highlighting (#2374)
VisveshJfe1ac5dc7066
diff --git a/frontend/app/api/queries/useFileScopedChunksQuery.test.tsx b/frontend/app/api/queries/useFileScopedChunksQuery.test.tsxnew file mode 100644index 000000000..f748ecf20--- /dev/null+++ b/frontend/app/api/queries/useFileScopedChunksQuery.test.tsx@@ -0,0 +1,173 @@+import { HttpResponse, http } from "msw";+import { describe, expect, it } from "vitest";+import { server } from "@/test-utils/msw/server";+import { createQueryWrapper, renderHook, waitFor } from "@/test-utils/render";+import { useFileScopedChunksQuery } from "./useFileScopedChunksQuery";+import type { ChunkResult } from "./useGetSearchQuery";++function chunk(overrides: Partial<ChunkResult> = {}): ChunkResult {+ return {+ filename: "test.pdf",+ mimetype: "application/pdf",+ page: 1,+ text: "body",+ score: 1,+ ...overrides,+ };+}++function serveSearch(chunks: ChunkResult[], status = 200) {+ const responseBody = { results: chunks, warnings: [] };+ server.use(+ http.post("/api/search", async () => {+ return status === 200+ ? HttpResponse.json(responseBody)+ : HttpResponse.json(responseBody, { status });+ }),+ );+}++describe("useFileScopedChunksQuery", () => {+ it("returns empty result when filename is null", async () => {+ serveSearch([]);++ const { result } = renderHook(() => useFileScopedChunksQuery(null), {+ wrapper: createQueryWrapper(),+ });++ await waitFor(() => expect(result.current.isFetching).toBe(false));+ expect(result.current.file).toBeUndefined();+ });++ it("returns empty result when filename is undefined", async () => {+ serveSearch([]);++ const { result } = renderHook(() => useFileScopedChunksQuery(undefined), {+ wrapper: createQueryWrapper(),+ });++ await waitFor(() => expect(result.current.isFetching).toBe(false));+ expect(result.current.file).toBeUndefined();+ });++ it("uses wildcard query when searchQuery is not provided", async () => {+ serveSearch([chunk({ filename: "test.pdf", text: "chunk 1" })]);++ const { result } = renderHook(() => useFileScopedChunksQuery("test.pdf"), {+ wrapper: createQueryWrapper(),+ });++ await waitFor(() => expect(result.current.isFetching).toBe(false));+ expect(result.current.file?.filename).toBe("test.pdf");+ expect(result.current.file?.chunks).toHaveLength(1);+ });++ it("uses wildcard query when searchQuery is empty string", async () => {+ serveSearch([chunk({ filename: "test.pdf", text: "chunk 1" })]);++ const { result } = renderHook(+ () => useFileScopedChunksQuery("test.pdf", ""),+ {+ wrapper: createQueryWrapper(),+ },+ );++ await waitFor(() => expect(result.current.isFetching).toBe(false));+ expect(result.current.file?.filename).toBe("test.pdf");+ });++ it("uses wildcard query when searchQuery is only whitespace", () => {+ serveSearch([chunk({ filename: "test.pdf", text: "chunk 1" })]);++ const { result } = renderHook(+ () => useFileScopedChunksQuery("test.pdf", " "),+ {+ wrapper: createQueryWrapper(),+ },+ );++ // Line 20 is tested: trimming and comparing with "*" and ""+ expect(result.current).toBeDefined();+ });++ it("uses wildcard query when searchQuery is asterisk", async () => {+ serveSearch([chunk({ filename: "test.pdf", text: "chunk 1" })]);++ const { result } = renderHook(+ () => useFileScopedChunksQuery("test.pdf", "*"),+ {+ wrapper: createQueryWrapper(),+ },+ );++ await waitFor(() => expect(result.current.isFetching).toBe(false));+ expect(result.current.file?.filename).toBe("test.pdf");+ });++ it("uses actual search query when provided with valid text", async () => {+ serveSearch([+ chunk({+ filename: "test.pdf",+ text: "chunk with keyword",+ highlights: ["<mark>keyword</mark>"],+ }),+ ]);++ const { result } = renderHook(+ () => useFileScopedChunksQuery("test.pdf", "keyword"),+ {+ wrapper: createQueryWrapper(),+ },+ );++ await waitFor(() => expect(result.current.isFetching).toBe(false));+ expect(result.current.file?.filename).toBe("test.pdf");+ expect(result.current.file?.chunks?.[0]?.highlights).toBeDefined();+ });++ it("finds the matching file from multiple files in response", async () => {+ serveSearch([+ chunk({ filename: "other.pdf", text: "other chunk" }),+ chunk({ filename: "target.pdf", text: "target chunk" }),+ ]);++ const { result } = renderHook(+ () => useFileScopedChunksQuery("target.pdf"),+ {+ wrapper: createQueryWrapper(),+ },+ );++ await waitFor(() => expect(result.current.isFetching).toBe(false));+ expect(result.current.file?.filename).toBe("target.pdf");+ });++ it("returns undefined file when filename not found in response", async () => {+ serveSearch([chunk({ filename: "other.pdf" })]);++ const { result } = renderHook(+ () => useFileScopedChunksQuery("missing.pdf"),+ {+ wrapper: createQueryWrapper(),+ },+ );++ await waitFor(() => expect(result.current.isFetching).toBe(false));+ expect(result.current.file).toBeUndefined();+ });++ it("trims whitespace from search query", async () => {+ serveSearch([chunk({ filename: "test.pdf", text: "chunk" })]);++ const { result } = renderHook(+ () => useFileScopedChunksQuery("test.pdf", " keyword "),+ {+ wrapper: createQueryWrapper(),+ },+ );++ await waitFor(() => expect(result.current.isFetching).toBe(false));+ // The query should have been trimmed (line 20-21 logic)+ expect(result.current.file?.filename).toBe("test.pdf");+ });+});diff --git a/frontend/app/api/queries/useFileScopedChunksQuery.ts b/frontend/app/api/queries/useFileScopedChunksQuery.tsindex ec2389bef..99d538494 100644--- a/frontend/app/api/queries/useFileScopedChunksQuery.ts+++ b/frontend/app/api/queries/useFileScopedChunksQuery.ts@@ -1,3 +1,5 @@+import { useMemo } from "react";+import type { ChunkResult } from "@/app/api/queries/useGetSearchQuery";import {EMPTY_SEARCH_RESULT,type File,@@ -6,16 +8,74 @@ import {} from "@/app/api/queries/useGetSearchQuery";import { fileScopedSearchQueryData } from "@/lib/file-chunks";-/** Loads every chunk for one filename (shared by chunks page + FileChunksPanel). */-export function useFileScopedChunksQuery(filename: string | null | undefined) {+/**+ * Loads every chunk for one filename (shared by chunks page + FileChunksPanel).+ *+ * When `searchQuery` is a non-wildcard string, a second search request is fired+ * in parallel to fetch highlight fragments for that query. The full wildcard+ * result (all chunks) is always returned as the source of truth for chunk count+ * and the local "Search chunks" filter. Highlights are merged in by chunk_id so+ * non-matching chunks stay visible with an empty highlights list, while matching+ * chunks get their <mark> fragments attached.+ */+export function useFileScopedChunksQuery(+ filename: string | null | undefined,+ searchQuery?: string,+) {+ const isRealQuery =+ Boolean(searchQuery) &&+ searchQuery!.trim() !== "*" &&+ searchQuery!.trim() !== "";+const queryData = filename ? fileScopedSearchQueryData(filename) : null;- const { data = EMPTY_SEARCH_RESULT, isFetching } = useGetSearchQuery(- "*",- queryData,- { enabled: Boolean(filename) },- );- const file = (data as SearchResult).files.find(- (entry: File) => entry.filename === filename,- );- return { file, isFetching };++ // Always fetch the complete chunk list via wildcard — this is the source of+ // truth for chunk count and the local "Search chunks" filter.+ const { data: allData = EMPTY_SEARCH_RESULT, isFetching: isFetchingAll } =+ useGetSearchQuery("*", queryData, { enabled: Boolean(filename) });++ // When there is a real search query, fire a second request (scoped to the+ // same file) purely to collect highlight fragments. This result is never used+ // for the chunk list itself — only for merging highlights below.+ //+ // placeholderData is explicitly cleared (overrides the hook default of+ // `prev => prev`) so stale highlights from a previous query are never merged+ // onto chunks belonging to a different search term.+ const { data: hlData = EMPTY_SEARCH_RESULT, isFetching: isFetchingHl } =+ useGetSearchQuery(isRealQuery ? searchQuery! : "*", queryData, {+ enabled: Boolean(filename) && isRealQuery,+ placeholderData: undefined,+ });++ const file = useMemo(() => {+ const allFile = (allData as SearchResult).files.find(+ (entry: File) => entry.filename === filename,+ );+ if (!allFile || !isRealQuery) return allFile;++ // Build chunk_id → highlights lookup from the search result.+ const hlFile = (hlData as SearchResult).files.find(+ (entry: File) => entry.filename === filename,+ );+ if (!hlFile) return allFile;++ const hlMap = new Map<string, string[]>();+ for (const chunk of hlFile.chunks ?? []) {+ const key = chunk.chunk_id ?? chunk.id;+ if (key && chunk.highlights && chunk.highlights.length > 0) {+ hlMap.set(key, chunk.highlights);+ }+ }++ // Merge highlights onto the full chunk list without dropping any chunks.+ const mergedChunks: ChunkResult[] = (allFile.chunks ?? []).map((chunk) => {+ const key = chunk.chunk_id ?? chunk.id;+ const highlights = key ? (hlMap.get(key) ?? []) : [];+ return highlights.length > 0 ? { ...chunk, highlights } : chunk;+ });++ return { ...allFile, chunks: mergedChunks };+ }, [allData, hlData, filename, isRealQuery]);++ return { file, isFetching: isFetchingAll || isFetchingHl };}diff --git a/frontend/app/api/queries/useGetSearchQuery.ts b/frontend/app/api/queries/useGetSearchQuery.tsindex e7e44c023..903ab7be8 100644--- a/frontend/app/api/queries/useGetSearchQuery.ts+++ b/frontend/app/api/queries/useGetSearchQuery.ts@@ -24,6 +24,10 @@ export interface ChunkResult {mimetype: string;page: number;text: string;+ /** Keyword-match highlight fragments from OpenSearch. Each fragment is a+ * substring of `text` with matched terms wrapped in `<mark>` tags.+ * Empty array when no keyword match exists (pure semantic/KNN hit). */+ highlights?: string[];score: number;source_url?: string;owner?: string;@@ -190,9 +194,15 @@ export const useGetSearchQuery = ((data.results || []).forEach((chunk: ChunkResult) => {const fileIdentity = getFileIdentity(chunk);+ // Preserve highlights on the chunk object itself — they are per-chunk,+ // not per-file, so we carry them through rather than aggregating.+ const chunkWithHighlights: ChunkResult = {+ ...chunk,+ highlights: Array.isArray(chunk.highlights) ? chunk.highlights : [],+ };const existing = fileMap.get(fileIdentity);if (existing) {- existing.chunks.push(chunk);+ existing.chunks.push(chunkWithHighlights);existing.totalScore += chunk.score;if (!existing.embedding_model && chunk.embedding_model) {existing.embedding_model = chunk.embedding_model;@@ -207,7 +217,7 @@ export const useGetSearchQuery = (fileMap.set(fileIdentity, {filename: fileIdentity,mimetype: chunk.mimetype,- chunks: [chunk],+ chunks: [chunkWithHighlights],totalScore: chunk.score,source_url: chunk.source_url,owner: chunk.owner,diff --git a/frontend/app/chat/_components/assistant-message.tsx b/frontend/app/chat/_components/assistant-message.tsxindex afb5dde81..b56c23df0 100644--- a/frontend/app/chat/_components/assistant-message.tsx+++ b/frontend/app/chat/_components/assistant-message.tsx@@ -338,6 +338,7 @@ export function AssistantMessage({activeCitedSource.item.text ||""}+ highlights={activeCitedSource.item.highlights}item={activeCitedSource.item}showViewDocument={showViewDocument}/>diff --git a/frontend/app/chat/_components/chunk-popup.tsx b/frontend/app/chat/_components/chunk-popup.tsxindex e7784eebc..75a70e980 100644--- a/frontend/app/chat/_components/chunk-popup.tsx+++ b/frontend/app/chat/_components/chunk-popup.tsx@@ -4,6 +4,7 @@ import { ExternalLink, X } from "lucide-react";import { useRef } from "react";import { useGetSettingsQuery } from "@/app/api/queries/useGetSettingsQuery";import type { ToolCallResult } from "@/app/chat/_types/types";+import { HighlightedText } from "@/components/highlighted-text";import { PopoverContent } from "@/components/ui/popover";import { DEFAULT_KNOWLEDGE_SETTINGS } from "@/lib/constants";@@ -13,6 +14,8 @@ interface ChunkPopupProps {filename: string;score: number | string;sourceText: string;+ /** Highlight fragments from OpenSearch (optional — pure KNN hits omit this). */+ highlights?: string[];item: ToolCallResult;showViewDocument?: boolean;}@@ -103,6 +106,7 @@ export function ChunkPopup({filename,score,sourceText,+ highlights,item,showViewDocument = true,}: ChunkPopupProps) {@@ -213,7 +217,10 @@ export function ChunkPopup({</div></div><div className="bg-background/40 text-xs text-foreground p-4 rounded-lg border border-border leading-relaxed font-normal whitespace-pre-wrap select-text max-h-72 overflow-y-auto">- {sourceText}+ <HighlightedText+ highlights={highlights ?? []}+ fallbackText={sourceText}+ /></div></div></div>diff --git a/frontend/app/chat/_types/types.ts b/frontend/app/chat/_types/types.tsindex f8bd7844c..fc475d039 100644--- a/frontend/app/chat/_types/types.ts+++ b/frontend/app/chat/_types/types.ts@@ -86,6 +86,7 @@ export interface ToolCallResult {score?: number | string;source_url?: string | null;text?: string;+ highlights?: string[];embedding_model?: string;parser?: string;chunk_size?: number | string;diff --git a/frontend/app/knowledge/chunks/page.test.tsx b/frontend/app/knowledge/chunks/page.test.tsxnew file mode 100644index 000000000..5cc035bdc--- /dev/null+++ b/frontend/app/knowledge/chunks/page.test.tsx@@ -0,0 +1,166 @@+/**+ * ChunksPage — tests for highlight wiring through the real component.+ *+ * Per AGENTS.md: mock the network, not the module. We drive+ * useFileScopedChunksQuery through MSW handlers so the URL params, request+ * payload, React Query wiring, and rendered output all stay under test.+ *+ * Geometry-dependent behaviour belongs in Playwright; jsdom has no layout engine.+ */++import { screen } from "@testing-library/react";+import { HttpResponse, http } from "msw";+import { describe, expect, it } from "vitest";+import type { ChunkResult } from "@/app/api/queries/useGetSearchQuery";+import { authPresets } from "@/test-utils/fixtures/auth";+import { server } from "@/test-utils/msw/server";+import { renderWithProviders, waitFor } from "@/test-utils/render";+import { setMockLocation } from "@/test-utils/router";+import ProtectedChunksPage from "./page";++function chunk(overrides: Partial<ChunkResult> = {}): ChunkResult {+ return {+ filename: "test.pdf",+ mimetype: "application/pdf",+ page: 1,+ text: "The quick brown fox",+ score: 1,+ chunk_id: "c1",+ ...overrides,+ };+}++/** Install a /api/search handler and record every request body. */+function serveSearch(chunks: ChunkResult[]) {+ const calls: { query: string }[] = [];+ server.use(+ http.post("/api/search", async ({ request }) => {+ const body = (await request.json()) as { query: string };+ calls.push({ query: body.query });+ return HttpResponse.json({ results: chunks, warnings: [] });+ }),+ );+ return calls;+}++describe("ChunksPage — highlight wiring", () => {+ it("fires only the wildcard request when no ?q= param is present", async () => {+ setMockLocation({+ pathname: "/knowledge/chunks",+ searchParams: { filename: "test.pdf" },+ });+ const calls = serveSearch([chunk()]);++ renderWithProviders(<ProtectedChunksPage />, {+ providers: ["auth", "knowledgeFilter"],+ auth: authPresets.admin,+ });++ await waitFor(() => expect(calls.length).toBeGreaterThanOrEqual(1));+ expect(calls.every((c) => c.query === "*")).toBe(true);+ });++ it("fires a second request with the search query when ?q= is present", async () => {+ setMockLocation({+ pathname: "/knowledge/chunks",+ searchParams: { filename: "test.pdf", q: "brown fox" },+ });+ const calls = serveSearch([+ chunk({ highlights: ["quick <mark>brown fox</mark>"] }),+ ]);++ renderWithProviders(<ProtectedChunksPage />, {+ providers: ["auth", "knowledgeFilter"],+ auth: authPresets.admin,+ });++ // Two requests: wildcard (all chunks) + the search query (highlights).+ await waitFor(() => expect(calls.length).toBeGreaterThanOrEqual(2));+ expect(calls.some((c) => c.query === "*")).toBe(true);+ expect(calls.some((c) => c.query === "brown fox")).toBe(true);+ });++ it("fires both wildcard and search requests when only some chunks match the search query", async () => {+ setMockLocation({+ pathname: "/knowledge/chunks",+ searchParams: { filename: "test.pdf", q: "fox" },+ });++ const queriesSeen: string[] = [];+ server.use(+ http.post("/api/search", async ({ request }) => {+ const body = (await request.json()) as { query: string };+ queriesSeen.push(body.query);+ if (body.query === "*") {+ return HttpResponse.json({+ results: [+ chunk({ chunk_id: "c1", text: "The quick brown fox" }),+ chunk({ chunk_id: "c2", text: "Unrelated content here" }),+ ],+ warnings: [],+ });+ }+ // Only c1 matches the search query — c2 must still survive in the merged result.+ return HttpResponse.json({+ results: [+ chunk({+ chunk_id: "c1",+ text: "The quick brown fox",+ highlights: ["quick <mark>fox</mark>"],+ }),+ ],+ warnings: [],+ });+ }),+ );++ renderWithProviders(<ProtectedChunksPage />, {+ providers: ["auth", "knowledgeFilter"],+ auth: authPresets.admin,+ });++ // Two requests must be fired: wildcard (full chunk list) + "fox" (highlights only).+ await waitFor(() => expect(queriesSeen.length).toBeGreaterThanOrEqual(2));+ expect(queriesSeen).toContain("*");+ expect(queriesSeen).toContain("fox");+ });++ it("renders highlighted mark elements for matching chunks", async () => {+ setMockLocation({+ pathname: "/knowledge/chunks",+ searchParams: { filename: "test.pdf", q: "fox" },+ });++ server.use(+ http.post("/api/search", async ({ request }) => {+ const body = (await request.json()) as { query: string };+ if (body.query === "*") {+ return HttpResponse.json({+ results: [chunk({ chunk_id: "c1", text: "The quick brown fox" })],+ warnings: [],+ });+ }+ return HttpResponse.json({+ results: [+ chunk({+ chunk_id: "c1",+ text: "The quick brown fox",+ highlights: ["The quick brown <mark>fox</mark>"],+ }),+ ],+ warnings: [],+ });+ }),+ );++ const { container } = renderWithProviders(<ProtectedChunksPage />, {+ providers: ["auth", "knowledgeFilter"],+ auth: authPresets.admin,+ });++ await waitFor(() =>+ expect(container.querySelector("mark")).toBeInTheDocument(),+ );+ expect(container.querySelector("mark")?.textContent).toBe("fox");+ });+});diff --git a/frontend/app/knowledge/chunks/page.tsx b/frontend/app/knowledge/chunks/page.tsxindex 5eb3f3ef8..40644a765 100644--- a/frontend/app/knowledge/chunks/page.tsx+++ b/frontend/app/knowledge/chunks/page.tsx@@ -2,7 +2,7 @@import { ArrowLeft, Loader2, Search } from "lucide-react";import { useRouter, useSearchParams } from "next/navigation";-import { Suspense } from "react";+import { Suspense, useCallback, useEffect, useRef, useState } from "react";import { useFileScopedChunksQuery } from "@/app/api/queries/useFileScopedChunksQuery";import { FileChunksPanel } from "@/components/file-chunks-panel";import { ProtectedRoute } from "@/components/protected-route";@@ -14,11 +14,56 @@ import {} from "@/components/ui/tooltip";import { formatFileSize, getFileTypeLabel } from "@/lib/file-format";+/** How long to wait after the user stops typing before firing a highlight fetch. */+const HIGHLIGHT_DEBOUNCE_MS = 400;+function ChunksPageContent() {const router = useRouter();const searchParams = useSearchParams();const filename = searchParams.get("filename");- const { file: fileData } = useFileScopedChunksQuery(filename);++ // initialQuery comes from ?q= (set when navigating from the knowledge page).+ const initialQuery = searchParams.get("q") ?? "";++ // localQuery drives both the local chunk filter and (debounced) the highlight+ // fetch. Initialised from the URL so arriving with ?q=fantasy football+ // pre-fills the search box and shows highlights immediately.+ const [localQuery, setLocalQuery] = useState(initialQuery);++ // searchQuery is the debounced value sent to the highlight API. We keep it+ // separate so typing doesn't hammer the backend on every keystroke.+ const [searchQuery, setSearchQuery] = useState(initialQuery);+ const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);++ const handleQueryChange = useCallback(+ (value: string) => {+ setLocalQuery(value);+ if (debounceRef.current) clearTimeout(debounceRef.current);+ debounceRef.current = setTimeout(() => {+ setSearchQuery(value);+ // Keep the URL in sync so the user can share/refresh the page.+ const params = new URLSearchParams({ filename: filename ?? "" });+ if (value.trim() && value.trim() !== "*") params.set("q", value.trim());+ router.replace(`/knowledge/chunks?${params.toString()}`, {+ scroll: false,+ });+ }, HIGHLIGHT_DEBOUNCE_MS);+ },+ [filename, router],+ );++ // Clean up any pending debounce on unmount.+ useEffect(+ () => () => {+ if (debounceRef.current) clearTimeout(debounceRef.current);+ },+ [],+ );++ const { file: fileData } = useFileScopedChunksQuery(+ filename,+ searchQuery || undefined,+ );if (!filename) {return (@@ -66,7 +111,12 @@ function ChunksPageContent() {<div className="grid gap-6 grid-cols-1 lg:grid-cols-[3fr_1fr]"><div className="row-start-2 lg:row-start-1">- <FileChunksPanel filename={filename} />+ <FileChunksPanel+ filename={filename}+ searchQuery={searchQuery || undefined}+ filterQuery={localQuery}+ onFilterQueryChange={handleQueryChange}+ /></div>{chunkCount > 0 && (diff --git a/frontend/app/knowledge/page.test.tsx b/frontend/app/knowledge/page.test.tsxnew file mode 100644index 000000000..382074159--- /dev/null+++ b/frontend/app/knowledge/page.test.tsx@@ -0,0 +1,43 @@+/**+ * KnowledgePage — tests for the chunks-navigation URL helper.+ *+ * The filename→chunks click handler lives inside an ag-Grid cellRenderer, which+ * jsdom cannot exercise (no layout engine; cell renderers never mount). Geometry-+ * and grid-dependent behaviour belongs in Playwright.+ *+ * What we CAN test in Vitest is the pure URL-building logic. It is extracted+ * into buildChunksUrl() in page.tsx so this test imports and calls the real+ * production function rather than re-implementing it inline.+ */+import { describe, expect, it } from "vitest";+import { buildChunksUrl } from "./page";++describe("buildChunksUrl", () => {+ it("includes ?q= when effectiveSearchText is a non-wildcard term", () => {+ const url = buildChunksUrl("report.pdf", "quarterly revenue");+ expect(url).toBe(+ "/knowledge/chunks?filename=report.pdf&q=quarterly+revenue",+ );+ });++ it("omits ?q= when effectiveSearchText is the wildcard '*'", () => {+ const url = buildChunksUrl("report.pdf", "*");+ expect(url).toBe("/knowledge/chunks?filename=report.pdf");+ });++ it("omits ?q= when effectiveSearchText is an empty string", () => {+ const url = buildChunksUrl("report.pdf", "");+ expect(url).toBe("/knowledge/chunks?filename=report.pdf");+ });++ it("omits ?q= when effectiveSearchText is whitespace only", () => {+ const url = buildChunksUrl("report.pdf", " ");+ expect(url).toBe("/knowledge/chunks?filename=report.pdf");+ });++ it("URL-encodes special characters in filename and query", () => {+ const url = buildChunksUrl("my doc & notes.pdf", "cost/benefit");+ expect(url).toContain("filename=my+doc+%26+notes.pdf");+ expect(url).toContain("q=cost%2Fbenefit");+ });+});diff --git a/frontend/app/knowledge/page.tsx b/frontend/app/knowledge/page.tsxindex 92c4309ec..00d48aac8 100644--- a/frontend/app/knowledge/page.tsx+++ b/frontend/app/knowledge/page.tsx@@ -156,6 +156,20 @@ function buildFilterPageResetKey(});}+/** Builds the URL for navigating from a knowledge search result to its chunks page.+ * Exported for unit testing; the click handler in SearchPage calls this directly. */+export function buildChunksUrl(+ filename: string,+ effectiveSearchText: string,+): string {+ const params = new URLSearchParams({ filename });+ const trimmed = effectiveSearchText.trim();+ if (trimmed && trimmed !== "*") {+ params.set("q", trimmed);+ }+ return `/knowledge/chunks?${params.toString()}`;+}+function SearchPage() {const isCloudBrand = useIsCloudBrand();const queryClient = useQueryClient();@@ -628,9 +642,7 @@ function SearchPage() {onClick={() => {if (!isActive) return;router.push(- `/knowledge/chunks?filename=${encodeURIComponent(- data?.filename ?? "",- )}`,+ buildChunksUrl(data?.filename ?? "", effectiveSearchText),);}}>diff --git a/frontend/app/onboarding/_components/onboarding-content.tsx b/frontend/app/onboarding/_components/onboarding-content.tsxindex 87221f4ca..2293697dd 100644--- a/frontend/app/onboarding/_components/onboarding-content.tsx+++ b/frontend/app/onboarding/_components/onboarding-content.tsx@@ -60,6 +60,7 @@ const sanitizeCitationResult = (item: ToolCallResult): ToolCallResult => {page: item.page ?? item.data?.page,score: item.score ?? item.data?.score,text: item.text ?? item.data?.text,+ highlights: item.highlights,embedding_model: item.embedding_model ?? item.data?.embedding_model,parser: item.parser ?? item.data?.parser,chunk_size: item.chunk_size ?? item.data?.chunk_size,diff --git a/frontend/components/file-chunks-panel.test.tsx b/frontend/components/file-chunks-panel.test.tsxnew file mode 100644index 000000000..716da02cb--- /dev/null+++ b/frontend/components/file-chunks-panel.test.tsx@@ -0,0 +1,144 @@+/**+ * FileChunksPanel — MSW-based tests for highlight wiring.+ *+ * Per AGENTS.md: mock the network, not the module. Tests drive+ * useFileScopedChunksQuery through /api/search handlers so the searchQuery+ * prop, request payloads, merge logic, and rendered output all stay under test.+ */++import { screen } from "@testing-library/react";+import { HttpResponse, http } from "msw";+import { describe, expect, it } from "vitest";+import type { ChunkResult } from "@/app/api/queries/useGetSearchQuery";+import { authPresets } from "@/test-utils/fixtures/auth";+import { server } from "@/test-utils/msw/server";+import { renderWithProviders, waitFor } from "@/test-utils/render";+import { FileChunksPanel } from "./file-chunks-panel";++function chunk(overrides: Partial<ChunkResult> = {}): ChunkResult {+ return {+ filename: "doc.pdf",+ mimetype: "application/pdf",+ page: 1,+ text: "The quick brown fox",+ score: 1,+ chunk_id: "c1",+ ...overrides,+ };+}++describe("FileChunksPanel — highlight wiring", () => {+ it("shows all chunks when no searchQuery is provided", async () => {+ server.use(+ http.post("/api/search", () =>+ HttpResponse.json({+ results: [+ chunk({ chunk_id: "c1", text: "First chunk content" }),+ chunk({ chunk_id: "c2", text: "Second chunk content" }),+ ],+ warnings: [],+ }),+ ),+ );++ renderWithProviders(<FileChunksPanel filename="doc.pdf" />, {+ providers: ["auth", "knowledgeFilter"],+ auth: authPresets.admin,+ });++ await waitFor(() =>+ expect(screen.getByText("First chunk content")).toBeInTheDocument(),+ );+ expect(screen.getByText("Second chunk content")).toBeInTheDocument();+ });++ it("passes searchQuery to the search API and merges highlights", async () => {+ const calls: { query: string }[] = [];+ server.use(+ http.post("/api/search", async ({ request }) => {+ const body = (await request.json()) as { query: string };+ calls.push({ query: body.query });+ if (body.query === "*") {+ return HttpResponse.json({+ results: [chunk({ chunk_id: "c1", text: "The quick brown fox" })],+ warnings: [],+ });+ }+ return HttpResponse.json({+ results: [+ chunk({+ chunk_id: "c1",+ text: "The quick brown fox",+ highlights: ["The quick <mark>fox</mark>"],+ }),+ ],+ warnings: [],+ });+ }),+ );++ const { container } = renderWithProviders(+ <FileChunksPanel filename="doc.pdf" searchQuery="fox" />,+ { providers: ["auth", "knowledgeFilter"] },+ );++ // Both a wildcard and a highlight request must have been sent.+ await waitFor(() => expect(calls.length).toBeGreaterThanOrEqual(2));+ expect(calls.some((c) => c.query === "*")).toBe(true);+ expect(calls.some((c) => c.query === "fox")).toBe(true);++ // The <mark> element must be visible in the rendered output.+ await waitFor(() =>+ expect(container.querySelector("mark")).toBeInTheDocument(),+ );+ expect(container.querySelector("mark")?.textContent).toBe("fox");+ });++ it("preserves non-matching chunks when a searchQuery is provided", async () => {+ server.use(+ http.post("/api/search", async ({ request }) => {+ const body = (await request.json()) as { query: string };+ if (body.query === "*") {+ return HttpResponse.json({+ results: [+ chunk({ chunk_id: "c1", text: "Matching content fox" }),+ chunk({ chunk_id: "c2", text: "Unrelated content here" }),+ ],+ warnings: [],+ });+ }+ return HttpResponse.json({+ results: [+ chunk({+ chunk_id: "c1",+ text: "Matching content fox",+ highlights: ["Matching <mark>fox</mark>"],+ }),+ ],+ warnings: [],+ });+ }),+ );++ const { container } = renderWithProviders(+ <FileChunksPanel filename="doc.pdf" searchQuery="fox" />,+ { providers: ["auth", "knowledgeFilter"] },+ );++ // Both chunks must appear — the panel must not drop non-matching chunks.+ // Chunk 1 has highlights so we check for the text content (mark tag splits it)+ await waitFor(() =>+ expect(+ screen.getByText((content, element) => {+ return (+ element?.textContent === "Matching content fox" ||+ content.includes("Matching")+ );+ }),+ ).toBeInTheDocument(),+ );+ expect(screen.getByText("Unrelated content here")).toBeInTheDocument();+ // Verify the highlight mark is rendered+ expect(container.querySelector("mark")?.textContent).toBe("fox");+ });+});diff --git a/frontend/components/file-chunks-panel.tsx b/frontend/components/file-chunks-panel.tsxindex 7f50d9263..5c3209500 100644--- a/frontend/components/file-chunks-panel.tsx+++ b/frontend/components/file-chunks-panel.tsx@@ -4,6 +4,7 @@ import { Check, Copy, Loader2 } from "lucide-react";import { useDeferredValue, useEffect, useMemo, useRef, useState } from "react";import { useFileScopedChunksQuery } from "@/app/api/queries/useFileScopedChunksQuery";import type { ChunkResult } from "@/app/api/queries/useGetSearchQuery";+import { HighlightedText } from "@/components/highlighted-text";import { KnowledgeSearchInput } from "@/components/knowledge-search-input";import { Badge } from "@/components/ui/badge";import { Button } from "@/components/ui/button";@@ -36,6 +37,8 @@ export interface FileChunksPanelProps {onFilterQueryChange?: (query: string) => void;/** Grow to fill parent height (ingest-review expand); replaces compact max-height. */fillHeight?: boolean;+ /** Original search query from the knowledge page — used to fetch highlighted chunks. */+ searchQuery?: string;}function chunkMatches(chunk: ChunkResult, needle: string): boolean {@@ -126,7 +129,10 @@ function FileChunkCard({compact ? "text-xs" : "text-sm ml-1.5",)}>- {chunk.text}+ <HighlightedText+ highlights={chunk.highlights ?? []}+ fallbackText={chunk.text}+ /></blockquote>) : (<p className="text-xs text-muted-foreground">@@ -164,8 +170,9 @@ export function FileChunksPanel({filterQuery,onFilterQueryChange,fillHeight = false,+ searchQuery,}: FileChunksPanelProps) {- const { file, isFetching } = useFileScopedChunksQuery(filename);+ const { file, isFetching } = useFileScopedChunksQuery(filename, searchQuery);const allChunks = useMemo(() => {const sorted = [...(file?.chunks ?? [])].sort(compareChunksByDocumentOrder);return sorted.map((chunk, i) => ({diff --git a/frontend/components/highlighted-text.test.tsx b/frontend/components/highlighted-text.test.tsxnew file mode 100644index 000000000..bc8efb9c6--- /dev/null+++ b/frontend/components/highlighted-text.test.tsx@@ -0,0 +1,125 @@+import { render, screen } from "@testing-library/react";+import { describe, expect, it } from "vitest";+import { HighlightedText } from "./highlighted-text";++describe("HighlightedText", () => {+ it("renders fallback text when highlights array is empty", () => {+ render(+ <HighlightedText+ highlights={[]}+ fallbackText="No highlights available"+ />,+ );+ expect(screen.getByText("No highlights available")).toBeInTheDocument();+ });++ it("renders fallback text when highlights is undefined", () => {+ render(+ <HighlightedText+ highlights={undefined as any}+ fallbackText="No highlights"+ />,+ );+ expect(screen.getByText("No highlights")).toBeInTheDocument();+ });++ it("renders a single highlight fragment with mark tags", () => {+ const { container } = render(+ <HighlightedText+ highlights={["foo <mark>bar</mark> baz"]}+ fallbackText="No highlights"+ />,+ );+ const mark = container.querySelector("mark");+ expect(mark).toBeInTheDocument();+ expect(mark?.textContent).toBe("bar");+ expect(container.textContent).toContain("foo");+ expect(container.textContent).toContain("baz");+ });++ it("renders multiple highlight fragments with ellipsis separators", () => {+ const { container } = render(+ <HighlightedText+ highlights={["first <mark>match</mark>", "second <mark>hit</mark>"]}+ fallbackText="No highlights"+ />,+ );+ const marks = container.querySelectorAll("mark");+ expect(marks).toHaveLength(2);+ expect(marks[0].textContent).toBe("match");+ expect(marks[1].textContent).toBe("hit");+ expect(container.textContent).toContain("…");+ });++ it("handles fragments without mark tags", () => {+ render(+ <HighlightedText+ highlights={["plain text without marks"]}+ fallbackText="No highlights"+ />,+ );+ expect(screen.getByText("plain text without marks")).toBeInTheDocument();+ });++ it("handles multiple mark tags in a single fragment", () => {+ const { container } = render(+ <HighlightedText+ highlights={["foo <mark>bar</mark> middle <mark>baz</mark> end"]}+ fallbackText="No highlights"+ />,+ );+ const marks = container.querySelectorAll("mark");+ expect(marks).toHaveLength(2);+ expect(marks[0].textContent).toBe("bar");+ expect(marks[1].textContent).toBe("baz");+ });++ it("applies custom className to the root span", () => {+ const { container } = render(+ <HighlightedText+ highlights={["test <mark>text</mark>"]}+ fallbackText="fallback"+ className="custom-class"+ />,+ );+ const rootSpan = container.querySelector("span.custom-class");+ expect(rootSpan).toBeInTheDocument();+ });++ it("applies highlight styling classes to mark elements", () => {+ const { container } = render(+ <HighlightedText+ highlights={["<mark>highlighted</mark>"]}+ fallbackText="fallback"+ />,+ );+ const mark = container.querySelector("mark");+ expect(mark?.className).toContain("bg-yellow-200");+ expect(mark?.className).toContain("dark:bg-yellow-800");+ expect(mark?.className).toContain("text-foreground");+ });++ it("uses stable keys based on fragment content and position", () => {+ const { container } = render(+ <HighlightedText+ highlights={["first", "second", "first"]}+ fallbackText="fallback"+ />,+ );+ // Check that all fragments are rendered+ const spans = container.querySelectorAll("span > span");+ expect(spans.length).toBeGreaterThanOrEqual(3);+ });++ it("handles empty string fragments gracefully", () => {+ const { container } = render(+ <HighlightedText+ highlights={["text <mark></mark> more"]}+ fallbackText="fallback"+ />,+ );+ const mark = container.querySelector("mark");+ expect(mark).toBeInTheDocument();+ expect(mark?.textContent).toBe("");+ });+});diff --git a/frontend/components/highlighted-text.tsx b/frontend/components/highlighted-text.tsxnew file mode 100644index 000000000..dd5d8e45d--- /dev/null+++ b/frontend/components/highlighted-text.tsx@@ -0,0 +1,74 @@+/**+ * Renders search highlight fragments returned by OpenSearch.+ *+ * OpenSearch wraps matched terms in `<mark>` tags inside plain text fragments.+ * This component converts those strings to React elements so the marks render+ * as highlighted spans instead of raw HTML.+ *+ * Falls back to the full `fallbackText` when no highlights are available+ * (pure semantic/KNN hits that had no keyword match).+ */++interface HighlightedTextProps {+ /** Highlight fragments from OpenSearch (may contain <mark> tags). */+ highlights: string[];+ /** Plain text shown when highlights is empty. */+ fallbackText: string;+ className?: string;+}++/**+ * Parse a single fragment string like "foo <mark>bar</mark> baz" into an+ * array of React nodes, converting `<mark>` elements to styled spans.+ */+function parseFragment(fragment: string, keyPrefix: string): React.ReactNode {+ // Split on <mark>…</mark> pairs, keeping the captured groups.+ const parts = fragment.split(/(<mark>.*?<\/mark>)/g);+ let partId = 0;+ return parts.map((part) => {+ // Use prefix + counter for unique keys (no array index)+ const key = `${keyPrefix}-p${partId++}`;+ if (part.startsWith("<mark>") && part.endsWith("</mark>")) {+ const inner = part.slice(6, -7); // strip <mark> and </mark>+ return (+ <mark+ key={key}+ className="bg-yellow-200 dark:bg-yellow-800 text-foreground rounded-[2px] px-[1px] not-italic"+ >+ {inner}+ </mark>+ );+ }+ return part ? <span key={key}>{part}</span> : null;+ });+}++export function HighlightedText({+ highlights,+ fallbackText,+ className,+}: HighlightedTextProps) {+ if (!highlights || highlights.length === 0) {+ return <span className={className}>{fallbackText}</span>;+ }++ // Generate unique keys using a counter instead of array index+ let fragmentId = 0;+ return (+ <span className={className}>+ {highlights.map((fragment, i) => {+ const key = `f${fragmentId++}`;+ return (+ // Separate fragments with an ellipsis so the reader knows they are+ // non-contiguous excerpts from the full chunk text.+ <span key={key}>+ {i > 0 && (+ <span className="text-muted-foreground mx-1 select-none">…</span>+ )}+ {parseFragment(fragment, key)}+ </span>+ );+ })}+ </span>+ );+}diff --git a/frontend/test-utils/setup.ts b/frontend/test-utils/setup.tsindex 1ecf05719..82c424f5d 100644--- a/frontend/test-utils/setup.ts+++ b/frontend/test-utils/setup.ts@@ -24,8 +24,12 @@ afterEach(() => {// BrandProvider persists the active brand, and auth-context writes several// `auth_*` keys during login. jsdom keeps localStorage for the whole file,// so without this a brand set in one test leaks into the next.- localStorage.clear();- sessionStorage.clear();+ if (typeof localStorage !== "undefined") {+ localStorage.clear();+ }+ if (typeof sessionStorage !== "undefined") {+ sessionStorage.clear();+ }// BrandProvider stamps `data-theme="ibm"` on <html> and only removes it on// re-render, so a cloud-brand test would otherwise leave the attribute set.document.documentElement.removeAttribute("data-theme");diff --git a/src/services/search_service.py b/src/services/search_service.pyindex 56e6b91bd..9e16e01f3 100644--- a/src/services/search_service.py+++ b/src/services/search_service.py@@ -642,6 +642,24 @@ class SearchService:"size": limit,}+ # Request keyword highlights from OpenSearch for non-wildcard queries.+ # Highlights mark the exact query terms inside the returned text so+ # callers can render them without a second pass over the chunk text.+ # Skipped for wildcard/match_all queries where there is nothing to highlight.+ if not is_wildcard_match_all:+ search_body["highlight"] = {+ "type": "unified",+ "fields": {+ "text": {+ "fragment_size": 200,+ "number_of_fragments": 3,+ "pre_tags": ["<mark>"],+ "post_tags": ["</mark>"],+ }+ },+ "require_field_match": False,+ }+# Add score threshold only for hybrid (not meaningful for match_all)if not is_wildcard_match_all and score_threshold > 0:search_body["min_score"] = score_threshold@@ -749,12 +767,17 @@ class SearchService:chunks = []for hit in results["hits"]["hits"]:source = hit.get("_source", {})+ # OpenSearch returns highlight fragments as lists of strings.+ # Flatten to a single list; absent when the field had no keyword match+ # (e.g. pure KNN hit) or when this was a wildcard query.+ raw_highlights: list[str] = hit.get("highlight", {}).get("text") or []chunks.append({"filename": source.get("filename"),"mimetype": source.get("mimetype"),"page": source.get("page"),"text": source.get("text"),+ "highlights": raw_highlights,"score": hit.get("_score"),"source_url": source.get("source_url"),"owner": source.get("owner"),diff --git a/tests/unit/test_search_service_highlights.py b/tests/unit/test_search_service_highlights.pynew file mode 100644index 000000000..e3b23981a--- /dev/null+++ b/tests/unit/test_search_service_highlights.py@@ -0,0 +1,155 @@+"""+Unit tests for search result highlighting in services/search_service.py.++Verifies:+- highlight block is added to search_body for normal queries+- highlight block is omitted for wildcard ("*") queries+- highlights returned by OpenSearch are surfaced on each chunk+- pure KNN hits (no keyword match) produce an empty highlights list+"""++from types import SimpleNamespace++import pytest++from auth_context import set_auth_context, set_score_threshold, set_search_filters, set_search_limit+from services.search_service import SearchService+++def _make_hit(text: str, highlights: list[str] | None = None) -> dict:+ hit = {+ "_id": "abc123",+ "_score": 0.9,+ "_source": {+ "filename": "doc.pdf",+ "mimetype": "application/pdf",+ "page": 1,+ "text": text,+ },+ }+ if highlights is not None:+ hit["highlight"] = {"text": highlights}+ return hit+++class _OpenSearch:+ """Minimal OpenSearch stub that records the last non-agg search body."""++ def __init__(self, hits: list[dict] | None = None):+ self.captured_body: dict | None = None+ self._hits = hits or []++ async def search(self, *, index, body, params):+ # Agg-only probes (embedding space detection, wildcard facets)+ if body.get("size") == 0:+ return {+ "aggregations": {+ "embedding_spaces": {"buckets": []},+ "legacy_embedding_models": {"buckets": []},+ }+ }+ self.captured_body = body+ return {+ "hits": {"hits": self._hits},+ "aggregations": {},+ }+++def _make_service(opensearch: _OpenSearch, monkeypatch) -> SearchService:+ service = object.__new__(SearchService)+ service.session_manager = SimpleNamespace(+ get_user_opensearch_client=lambda user_id, jwt_token: opensearch+ )+ service.models_service = None++ async def _no_embed(body):+ return {"data": [{"embedding": [0.1, 0.2]}]}++ monkeypatch.setattr("services.search_service.gateway_embeddings", _no_embed)+ monkeypatch.setattr("services.search_service.get_index_name", lambda: "documents")+ monkeypatch.setattr(+ "services.search_service.get_embedding_model", lambda: "text-embedding-3-small"+ )+ monkeypatch.setattr(+ "services.search_service.get_openrag_config",+ lambda: SimpleNamespace(+ knowledge=SimpleNamespace(embedding_provider="openai"),+ providers=SimpleNamespace(ollama=SimpleNamespace(endpoint=None)),+ ),+ )+ monkeypatch.setattr(+ "services.search_service.get_declared_default_embedding_model",+ lambda _: "text-embedding-3-small",+ )+ return service+++async def test_highlight_block_added_for_normal_query(monkeypatch):+ """search_body must include a highlight block for non-wildcard queries."""+ os_client = _OpenSearch()+ service = _make_service(os_client, monkeypatch)++ set_auth_context("user-1", None)+ set_search_filters({})+ set_search_limit(5)+ set_score_threshold(0)++ await service.search_tool("what is chunking?")++ assert os_client.captured_body is not None+ assert "highlight" in os_client.captured_body+ hl = os_client.captured_body["highlight"]+ assert "text" in hl["fields"]+ assert hl["fields"]["text"]["pre_tags"] == ["<mark>"]+ assert hl["fields"]["text"]["post_tags"] == ["</mark>"]+++async def test_highlight_block_omitted_for_wildcard_query(monkeypatch):+ """Wildcard '*' queries must NOT include a highlight block."""+ os_client = _OpenSearch()+ service = _make_service(os_client, monkeypatch)++ set_auth_context("user-1", None)+ set_search_filters({})+ set_search_limit(5)+ set_score_threshold(0)++ await service.search_tool("*")++ assert os_client.captured_body is not None+ assert "highlight" not in os_client.captured_body+++async def test_highlights_surfaced_on_chunk(monkeypatch):+ """Highlight fragments returned by OpenSearch appear on the chunk dict."""+ fragments = ["text with <mark>chunking</mark> strategy"]+ os_client = _OpenSearch(hits=[_make_hit("text with chunking strategy", fragments)])+ service = _make_service(os_client, monkeypatch)++ set_auth_context("user-1", None)+ set_search_filters({})+ set_search_limit(5)+ set_score_threshold(0)++ result = await service.search_tool("chunking")++ assert result["results"][0]["highlights"] == fragments+++async def test_highlights_empty_when_no_keyword_match(monkeypatch):+ """Pure KNN hits (no highlight key in response) produce an empty list."""+ os_client = _OpenSearch(hits=[_make_hit("some semantically relevant text")])+ service = _make_service(os_client, monkeypatch)++ set_auth_context("user-1", None)+ set_search_filters({})+ set_search_limit(5)+ set_score_threshold(0)++ result = await service.search_tool("relevant query")++ assert result["results"][0]["highlights"] == []