🛤️ fix: Align File Search Citation Paths (#15650)

* fix: keep file search anchors aligned with citation passages

* refactor: centralize file citation selection

* test: wire citation helpers into API mocks

---------

Co-authored-by: aeyeopsdev <275853971+aeyeopsdev@users.noreply.github.com>
Co-authored-by: Danny Avila <danny@librechat.ai>

Author: aeyeopsdev

api/app/clients/tools/util/fileSearch.js

@@ -1,8 +1,12 @@
 const axios = require('axios');
 const { logger } = require('@librechat/data-schemas');
 const { tool } = require('@librechat/agents/langchain/tools');
-const { generateShortLivedToken, logAxiosError } = require('@librechat/api');
-const { Tools, EToolResources } = require('librechat-data-provider');
+const {
+  logAxiosError,
+  selectFileCitationSources,
+  generateShortLivedToken,
+} = require('@librechat/api');
+const { Tools, EModelEndpoint, EToolResources } = require('librechat-data-provider');
 const { filterFilesByAgentAccess } = require('~/server/services/Files/permissions');
 const { getFiles } = require('~/models');
 
@@ -82,13 +86,20 @@ const primeFiles = async (options) => {
 /**
  *
  * @param {Object} options
+ * @param {AppConfig} [options.appConfig]
  * @param {string} options.userId
  * @param {Array<{ file_id: string; filename: string; fromAgent?: boolean }>} options.files
  * @param {string} [options.entity_id]
  * @param {boolean} [options.fileCitations=false] - Whether to include citation instructions
  * @returns
  */
-const createFileSearchTool = async ({ userId, files, entity_id, fileCitations = false }) => {
+const createFileSearchTool = async ({
+  userId,
+  files,
+  entity_id,
+  fileCitations = false,
+  appConfig,
+}) => {
   return tool(
     async ({ query }) => {
       if (files.length === 0) {
@@ -132,6 +143,7 @@ const createFileSearchTool = async ({ userId, files, entity_id, fileCitations =
               'Content-Type': 'application/json',
             },
           })
+          .then((result) => ({ data: result.data, file_id: file.file_id }))
           .catch((error) => {
             logAxiosError({
               message: 'Error encountered in `file_search` while querying file',
@@ -149,12 +161,12 @@ const createFileSearchTool = async ({ userId, files, entity_id, fileCitations =
       }
 
       const formattedResults = validResults
-        .flatMap((result, fileIndex) =>
+        .flatMap((result) =>
           result.data.map(([docInfo, distance]) => ({
             filename: docInfo.metadata.source.split('/').pop(),
             content: docInfo.page_content,
             distance,
-            file_id: files[fileIndex]?.file_id,
+            file_id: result.file_id,
             page: docInfo.metadata.page || null,
           })),
         )
@@ -168,15 +180,6 @@ const createFileSearchTool = async ({ userId, files, entity_id, fileCitations =
         ];
       }
 
-      const formattedString = formattedResults
-        .map(
-          (result, index) =>
-            `File: ${result.filename}${
-              fileCitations ? `\nAnchor: \\ue202turn0file${index} (${result.filename})` : ''
-            }\nRelevance: ${(1.0 - result.distance).toFixed(4)}\nContent: ${result.content}\n`,
-        )
-        .join('\n---\n');
-
       const sources = formattedResults.map((result) => ({
         type: 'file',
         fileId: result.file_id,
@@ -187,6 +190,21 @@ const createFileSearchTool = async ({ userId, files, entity_id, fileCitations =
         pageRelevance: result.page ? { [result.page]: 1.0 - result.distance } : {},
       }));
 
+      const citationConfig = appConfig?.endpoints?.[EModelEndpoint.agents];
+      const citationSources = fileCitations
+        ? selectFileCitationSources(sources, citationConfig)
+        : [];
+      const formattedString = formattedResults
+        .map((result, index) => {
+          const citationIndex = citationSources.indexOf(sources[index]);
+          return `File: ${result.filename}${
+            citationIndex >= 0
+              ? `\nAnchor: \\ue202turn0file${citationIndex} (${result.filename})`
+              : ''
+          }\nRelevance: ${(1.0 - result.distance).toFixed(4)}\nContent: ${result.content}\n`;
+        })
+        .join('\n---\n');
+
       return [formattedString, { [Tools.file_search]: { sources, fileCitations } }];
     },
     {

api/app/clients/tools/util/handleTools.js

@@ -417,6 +417,7 @@ const loadTools = async ({
         }
 
         return createFileSearchTool({
+          appConfig: options.req.config,
           userId: user,
           files,
           entity_id: agent?.id,

api/server/services/Files/Citations/index.js

@@ -1,6 +1,7 @@
 const { nanoid } = require('nanoid');
 const { checkAccess } = require('@librechat/api');
 const { logger } = require('@librechat/data-schemas');
+const { applyCitationLimits, selectFileCitationSources } = require('@librechat/api');
 const {
   Tools,
   Permissions,
@@ -54,22 +55,15 @@ async function processFileCitations({ user, appConfig, toolArtifact, toolCallId,
       }
     }
 
-    const maxCitations = appConfig.endpoints?.[EModelEndpoint.agents]?.maxCitations ?? 30;
-    const maxCitationsPerFile =
-      appConfig.endpoints?.[EModelEndpoint.agents]?.maxCitationsPerFile ?? 5;
-    const minRelevanceScore =
-      appConfig.endpoints?.[EModelEndpoint.agents]?.minRelevanceScore ?? 0.45;
-
-    const sources = toolArtifact[Tools.file_search].sources || [];
-    const filteredSources = sources.filter((source) => source.relevance >= minRelevanceScore);
-    if (filteredSources.length === 0) {
-      logger.debug(
-        `[processFileCitations] No sources above relevance threshold of ${minRelevanceScore}`,
-      );
+    const selectedSources = selectFileCitationSources(toolArtifact[Tools.file_search].sources, {
+      maxCitations: appConfig.endpoints?.[EModelEndpoint.agents]?.maxCitations,
+      maxCitationsPerFile: appConfig.endpoints?.[EModelEndpoint.agents]?.maxCitationsPerFile,
+      minRelevanceScore: appConfig.endpoints?.[EModelEndpoint.agents]?.minRelevanceScore,
+    });
+    if (selectedSources.length === 0) {
       return null;
     }
 
-    const selectedSources = applyCitationLimits(filteredSources, maxCitations, maxCitationsPerFile);
     const enhancedSources = await enhanceSourcesWithMetadata(selectedSources, appConfig);
 
     if (enhancedSources.length > 0) {
@@ -92,32 +86,6 @@ async function processFileCitations({ user, appConfig, toolArtifact, toolCallId,
   }
 }
 
-/**
- * Apply citation limits to sources
- * @param {Array} sources - All sources
- * @param {number} maxCitations - Maximum total citations
- * @param {number} maxCitationsPerFile - Maximum citations per file
- * @returns {Array} Selected sources
- */
-function applyCitationLimits(sources, maxCitations, maxCitationsPerFile) {
-  const byFile = {};
-  sources.forEach((source) => {
-    if (!byFile[source.fileId]) {
-      byFile[source.fileId] = [];
-    }
-    byFile[source.fileId].push(source);
-  });
-
-  const representatives = [];
-  for (const fileId in byFile) {
-    const fileSources = byFile[fileId].sort((a, b) => b.relevance - a.relevance);
-    const selectedFromFile = fileSources.slice(0, maxCitationsPerFile);
-    representatives.push(...selectedFromFile);
-  }
-
-  return representatives.sort((a, b) => b.relevance - a.relevance).slice(0, maxCitations);
-}
-
 /**
  * Enhance sources with file metadata from database
  * @param {Array} sources - Selected sources
@@ -156,6 +124,7 @@ async function enhanceSourcesWithMetadata(sources, appConfig) {
 }
 
 module.exports = {
+  selectFileCitationSources,
   applyCitationLimits,
   processFileCitations,
   enhanceSourcesWithMetadata,

api/test/app/clients/tools/util/fileSearch.test.js

@@ -2,10 +2,14 @@ const axios = require('axios');
 const { ResourceType } = require('librechat-data-provider');
 
 jest.mock('axios');
-jest.mock('@librechat/api', () => ({
-  generateShortLivedToken: jest.fn(),
-  logAxiosError: jest.fn(),
-}));
+jest.mock('@librechat/api', () => {
+  const { selectFileCitationSources } = jest.requireActual('@librechat/api');
+  return {
+    generateShortLivedToken: jest.fn(),
+    logAxiosError: jest.fn(),
+    selectFileCitationSources,
+  };
+});
 
 jest.mock('@librechat/data-schemas', () => ({
   logger: {

api/test/services/Files/processFileCitations.test.js

@@ -11,9 +11,14 @@ jest.mock('~/models', () => ({
   getRoleByName: jest.fn(),
 }));
 
-jest.mock('@librechat/api', () => ({
-  checkAccess: jest.fn().mockResolvedValue(true),
-}));
+jest.mock('@librechat/api', () => {
+  const { applyCitationLimits, selectFileCitationSources } = jest.requireActual('@librechat/api');
+  return {
+    applyCitationLimits,
+    checkAccess: jest.fn().mockResolvedValue(true),
+    selectFileCitationSources,
+  };
+});
 
 jest.mock('~/cache/getLogStores', () => () => ({
   get: jest.fn().mockResolvedValue({

client/src/hooks/Messages/useSearchResultsByTurn.ts

@@ -11,15 +11,6 @@ interface FileSource {
   metadata?: any;
 }
 
-interface DeduplicatedSource {
-  fileId: string;
-  fileName: string;
-  pages: number[];
-  relevance: number;
-  pageRelevance: Record<string, number>;
-  metadata?: any;
-}
-
 /**
  * The `file_search` attachment is typed as {@link SearchResultData} in the
  * shared schema, but at runtime the agent file-search tool emits a
@@ -55,49 +46,13 @@ export function useSearchResultsByTurn(attachments?: TAttachment[]) {
       if (attachment.type === Tools.file_search && attachment[Tools.file_search]) {
         const sources = getFileSearchSources(attachment[Tools.file_search]);
 
-        // Deduplicate sources by fileId and merge pages
-        const deduplicatedSources = new Map<string, DeduplicatedSource>();
-
-        sources.forEach((source: FileSource) => {
-          const fileId = source.fileId;
-          if (deduplicatedSources.has(fileId)) {
-            // Merge pages for the same file
-            const existing = deduplicatedSources.get(fileId);
-            if (existing) {
-              const existingPages = existing.pages || [];
-              const newPages = source.pages || [];
-              const allPages = [...existingPages, ...newPages];
-              // Remove duplicates and sort
-              const uniquePages = [...new Set(allPages)].sort((a, b) => a - b);
-
-              // Merge page relevance mappings
-              const existingPageRelevance = existing.pageRelevance || {};
-              const newPageRelevance = source.pageRelevance || {};
-              const mergedPageRelevance = { ...existingPageRelevance, ...newPageRelevance };
-
-              existing.pages = uniquePages;
-              existing.relevance = Math.max(existing.relevance || 0, source.relevance || 0);
-              existing.pageRelevance = mergedPageRelevance;
-            }
-          } else {
-            deduplicatedSources.set(fileId, {
-              fileId: source.fileId,
-              fileName: source.fileName,
-              pages: source.pages || [],
-              relevance: source.relevance || 0.5,
-              pageRelevance: source.pageRelevance || {},
-              metadata: source.metadata,
-            });
-          }
-        });
-
         // Convert agent file sources to SearchResultData format
         const agentSearchData: SearchResultData = {
           turn: agentFileSearchTurn,
           organic: [], // Agent file search doesn't have organic web results
           topStories: [], // No top stories for file search
           images: [], // No images for file search
-          references: Array.from(deduplicatedSources.values()).map(
+          references: sources.map(
             (source) =>
               ({
                 title: source.fileName || localize('com_file_unknown'),
@@ -111,8 +66,8 @@ export function useSearchResultsByTurn(attachments?: TAttachment[]) {
                 // Store additional agent-specific data as properties on the reference
                 fileId: source.fileId,
                 fileName: source.fileName,
-                pages: source.pages,
-                pageRelevance: source.pageRelevance,
+                pages: source.pages || [],
+                pageRelevance: source.pageRelevance || {},
                 metadata: source.metadata,
               }) as any,
           ),

packages/api/src/files/citations.spec.ts

@@ -0,0 +1,28 @@
+import { applyCitationLimits, selectFileCitationSources } from './citations';
+
+describe('file citation selection', () => {
+  const sources = [
+    { fileId: 'a', relevance: 0.9, page: 1 },
+    { fileId: 'a', relevance: 0.8, page: 2 },
+    { fileId: 'b', relevance: 0.7, page: 1 },
+    { fileId: 'c', relevance: 0.2, page: 1 },
+  ];
+
+  it('applies per-file and total limits by relevance', () => {
+    expect(applyCitationLimits(sources, 2, 1)).toEqual([sources[0], sources[2]]);
+  });
+
+  it('shares relevance and count selection without losing source identity', () => {
+    expect(
+      selectFileCitationSources(sources, {
+        minRelevanceScore: 0.5,
+        maxCitations: 3,
+        maxCitationsPerFile: 1,
+      }),
+    ).toEqual([sources[0], sources[2]]);
+  });
+
+  it('handles artifacts without sources', () => {
+    expect(selectFileCitationSources(undefined)).toEqual([]);
+  });
+});

packages/api/src/files/citations.ts

@@ -0,0 +1,44 @@
+export interface FileCitationSource {
+  fileId: string;
+  relevance: number;
+}
+
+export interface FileCitationSelectionConfig {
+  maxCitations?: number;
+  maxCitationsPerFile?: number;
+  minRelevanceScore?: number;
+}
+
+export function applyCitationLimits<TSource extends FileCitationSource>(
+  sources: readonly TSource[],
+  maxCitations: number,
+  maxCitationsPerFile: number,
+): TSource[] {
+  const byFile = new Map<string, TSource[]>();
+  for (const source of sources) {
+    const fileSources = byFile.get(source.fileId) ?? [];
+    fileSources.push(source);
+    byFile.set(source.fileId, fileSources);
+  }
+
+  const representatives: TSource[] = [];
+  for (const fileSources of byFile.values()) {
+    representatives.push(
+      ...fileSources.sort((a, b) => b.relevance - a.relevance).slice(0, maxCitationsPerFile),
+    );
+  }
+
+  return representatives.sort((a, b) => b.relevance - a.relevance).slice(0, maxCitations);
+}
+
+/** Selects the passages shared by model anchors and browser citation attachments. */
+export function selectFileCitationSources<TSource extends FileCitationSource>(
+  sources: readonly TSource[] | null | undefined,
+  config?: FileCitationSelectionConfig,
+): TSource[] {
+  return applyCitationLimits(
+    (sources ?? []).filter((source) => source.relevance >= (config?.minRelevanceScore ?? 0.45)),
+    config?.maxCitations ?? 30,
+    config?.maxCitationsPerFile ?? 5,
+  );
+}

packages/api/src/files/index.ts

@@ -1,6 +1,7 @@
 export * from './agents';
 export * from './audio';
 export * from './code';
+export * from './citations';
 export * from './context';
 export * from './deletion';
 export * from './extract';