Skip to content

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.tsx
new file mode 100644
index 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.ts
index 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.ts
index 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.tsx
index 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.tsx
index 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.ts
index 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.tsx
new file mode 100644
index 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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
index 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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
index 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.py
index 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.py
new file mode 100644
index 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"] == []