Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

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

aeyeopsdeva827f35a6940
diff --git a/api/app/clients/tools/util/fileSearch.js b/api/app/clients/tools/util/fileSearch.js
index a153a1aec3..d9f701376f 100644
--- a/api/app/clients/tools/util/fileSearch.js
+++ b/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 } }];
},
{
diff --git a/api/app/clients/tools/util/handleTools.js b/api/app/clients/tools/util/handleTools.js
index cc5ba64662..558aba79a9 100644
--- a/api/app/clients/tools/util/handleTools.js
+++ b/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,
diff --git a/api/server/services/Files/Citations/index.js b/api/server/services/Files/Citations/index.js
index a1d9322467..e3030f064f 100644
--- a/api/server/services/Files/Citations/index.js
+++ b/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,
diff --git a/api/test/app/clients/tools/util/fileSearch.test.js b/api/test/app/clients/tools/util/fileSearch.test.js
index 0c1ff89515..f160ba5448 100644
--- a/api/test/app/clients/tools/util/fileSearch.test.js
+++ b/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: {
diff --git a/api/test/services/Files/processFileCitations.test.js b/api/test/services/Files/processFileCitations.test.js
index 8dd588afe9..daed1c7d23 100644
--- a/api/test/services/Files/processFileCitations.test.js
+++ b/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({
diff --git a/client/src/hooks/Messages/useSearchResultsByTurn.ts b/client/src/hooks/Messages/useSearchResultsByTurn.ts
index d7ec2c265b..b01b96027b 100644
--- a/client/src/hooks/Messages/useSearchResultsByTurn.ts
+++ b/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,
),
diff --git a/packages/api/src/files/citations.spec.ts b/packages/api/src/files/citations.spec.ts
new file mode 100644
index 0000000000..f09960f82c
--- /dev/null
+++ b/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([]);
+ });
+});
diff --git a/packages/api/src/files/citations.ts b/packages/api/src/files/citations.ts
new file mode 100644
index 0000000000..38155a5325
--- /dev/null
+++ b/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,
+ );
+}
diff --git a/packages/api/src/files/index.ts b/packages/api/src/files/index.ts
index 9ca5a4135e..97b7c716ce 100644
--- a/packages/api/src/files/index.ts
+++ b/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';