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: Skip Blank RAG Queries Before Embedding (#16231)

lia-by-librechat[bot]44703da3c62e
diff --git a/api/app/clients/prompts/createContextHandlers.js b/api/app/clients/prompts/createContextHandlers.js
index 37b6ba925f..1f75978e26 100644
--- a/api/app/clients/prompts/createContextHandlers.js
+++ b/api/app/clients/prompts/createContextHandlers.js
@@ -1,159 +1,22 @@
const axios = require('axios');
-const { isEnabled, generateShortLivedToken, logAxiosError } = require('@librechat/api');
-
-const footer = `Use the context as your learned knowledge to better answer the user.
-
-In your response, remember to follow these guidelines:
-- If you don't know the answer, simply say that you don't know.
-- If you are unsure how to answer, ask for clarification.
-- Avoid mentioning that you obtained the information from the context.
-`;
+const {
+ isEnabled,
+ generateShortLivedToken,
+ logAxiosError,
+ createRagContextHandlers,
+} = require('@librechat/api');
function createContextHandlers(req, userMessageContent) {
- if (!process.env.RAG_API_URL) {
- return;
- }
-
- const queryPromises = [];
- const processedFiles = [];
- const processedIds = new Set();
- const jwtToken = generateShortLivedToken(req.user.id);
- const useFullContext = isEnabled(process.env.RAG_USE_FULL_CONTEXT);
-
- const query = async (file) => {
- if (useFullContext) {
- return axios.get(`${process.env.RAG_API_URL}/documents/${file.file_id}/context`, {
- headers: {
- Authorization: `Bearer ${jwtToken}`,
- },
- });
- }
-
- return axios.post(
- `${process.env.RAG_API_URL}/query`,
- {
- file_id: file.file_id,
- query: userMessageContent,
- k: 4,
- },
- {
- headers: {
- Authorization: `Bearer ${jwtToken}`,
- 'Content-Type': 'application/json',
- },
- },
- );
- };
-
- const processFile = async (file) => {
- if (file.embedded && !processedIds.has(file.file_id)) {
- try {
- const promise = query(file);
- queryPromises.push(promise);
- processedFiles.push(file);
- processedIds.add(file.file_id);
- } catch (error) {
- logAxiosError({ message: `Error processing file ${file.filename}`, error });
- }
- }
- };
-
- const createContext = async () => {
- try {
- if (!queryPromises.length || !processedFiles.length) {
- return '';
- }
-
- const oneFile = processedFiles.length === 1;
- const header = `The user has attached ${oneFile ? 'a' : processedFiles.length} file${
- !oneFile ? 's' : ''
- } to the conversation:`;
-
- const files = `${
- oneFile
- ? ''
- : `
- <files>`
- }${processedFiles
- .map(
- (file) => `
- <file>
- <filename>${file.filename}</filename>
- <type>${file.type}</type>
- </file>`,
- )
- .join('')}${
- oneFile
- ? ''
- : `
- </files>`
- }`;
-
- const resolvedQueries = await Promise.all(queryPromises);
-
- const context =
- resolvedQueries.length === 0
- ? '\n\tThe semantic search did not return any results.'
- : resolvedQueries
- .map((queryResult, index) => {
- const file = processedFiles[index];
- let contextItems = queryResult.data;
-
- const generateContext = (currentContext) =>
- `
- <file>
- <filename>${file.filename}</filename>
- <context>${currentContext}
- </context>
- </file>`;
-
- if (useFullContext) {
- return generateContext(`\n${contextItems}`);
- }
-
- contextItems = queryResult.data
- .map((item) => {
- const pageContent = item[0].page_content;
- return `
- <contextItem>
- <![CDATA[${pageContent?.trim()}]]>
- </contextItem>`;
- })
- .join('');
-
- return generateContext(contextItems);
- })
- .join('');
-
- if (useFullContext) {
- const prompt = `${header}
- ${context}
- ${footer}`;
-
- return prompt;
- }
-
- const prompt = `${header}
- ${files}
-
- A semantic search was executed with the user's message as the query, retrieving the following context inside <context></context> XML tags.
-
- <context>${context}
- </context>
-
- ${footer}`;
-
- return prompt;
- } catch (error) {
- logAxiosError({ message: 'Error creating context', error });
- throw error;
- }
- };
-
- return {
- processFile,
- createContext,
- };
+ return createRagContextHandlers({
+ req,
+ userMessageContent,
+ ragApiUrl: process.env.RAG_API_URL,
+ fullContextSetting: process.env.RAG_USE_FULL_CONTEXT,
+ httpClient: axios,
+ isEnabled,
+ generateShortLivedToken,
+ logAxiosError,
+ });
}
module.exports = createContextHandlers;
diff --git a/api/app/clients/prompts/createContextHandlers.spec.js b/api/app/clients/prompts/createContextHandlers.spec.js
new file mode 100644
index 0000000000..4181b28f0c
--- /dev/null
+++ b/api/app/clients/prompts/createContextHandlers.spec.js
@@ -0,0 +1,47 @@
+const axios = require('axios');
+
+jest.mock('axios');
+jest.mock('@librechat/api', () => ({
+ createRagContextHandlers: jest.requireActual('@librechat/api').createRagContextHandlers,
+ isEnabled: jest.fn((value) => value === 'true'),
+ generateShortLivedToken: jest.fn(() => 'signed-token'),
+ logAxiosError: jest.fn(),
+}));
+
+const createContextHandlers = require('./createContextHandlers');
+
+const req = { user: { id: 'user-1' } };
+const file = { embedded: true, file_id: 'file-1', filename: 'notes.pdf', type: 'application/pdf' };
+
+beforeEach(() => {
+ jest.clearAllMocks();
+ process.env.RAG_API_URL = 'http://rag';
+ delete process.env.RAG_USE_FULL_CONTEXT;
+ axios.post.mockResolvedValue({ data: [] });
+ axios.get.mockResolvedValue({ data: 'whole document' });
+});
+
+afterAll(() => {
+ delete process.env.RAG_API_URL;
+ delete process.env.RAG_USE_FULL_CONTEXT;
+});
+
+it('does not send an empty file-only message to the embeddings endpoint', async () => {
+ const handlers = createContextHandlers(req, '');
+ await handlers.processFile(file);
+
+ expect(await handlers.createContext()).toBe('');
+ expect(axios.post).not.toHaveBeenCalled();
+});
+
+it('still fetches context on file-only messages in full-document mode', async () => {
+ process.env.RAG_USE_FULL_CONTEXT = 'true';
+ const handlers = createContextHandlers(req, '');
+ await handlers.processFile(file);
+
+ expect(await handlers.createContext()).toContain('whole document');
+ expect(axios.post).not.toHaveBeenCalled();
+ expect(axios.get).toHaveBeenCalledWith('http://rag/documents/file-1/context', {
+ headers: { Authorization: 'Bearer signed-token' },
+ });
+});
diff --git a/api/app/clients/tools/util/fileSearch.js b/api/app/clients/tools/util/fileSearch.js
index f18eef6bc3..e58874f311 100644
--- a/api/app/clients/tools/util/fileSearch.js
+++ b/api/app/clients/tools/util/fileSearch.js
@@ -5,8 +5,9 @@ const {
logAxiosError,
selectFileCitationSources,
generateShortLivedToken,
+ executeFileSearchQuery,
} = require('@librechat/api');
-const { Tools, EModelEndpoint, EToolResources } = require('librechat-data-provider');
+const { Tools, EToolResources } = require('librechat-data-provider');
const { filterFilesByAgentAccess } = require('~/server/services/Files/permissions');
const { getFiles } = require('~/models');
@@ -101,115 +102,21 @@ const createFileSearchTool = async ({
appConfig,
}) => {
return tool(
- async ({ query }) => {
- if (files.length === 0) {
- return ['No files to search. Instruct the user to add files for the search.', undefined];
- }
- const jwtToken = generateShortLivedToken(userId);
- if (!jwtToken) {
- return ['There was an error authenticating the file search request.', undefined];
- }
-
- /**
- * @param {import('librechat-data-provider').TFile & { fromAgent?: boolean }} file
- * @returns {{ file_id: string, query: string, k: number, entity_id?: string }}
- */
- const createQueryBody = (file) => {
- const body = {
- file_id: file.file_id,
- query,
- k: 5,
- };
- // User-attached files are embedded under the user id (no entity);
- // only agent knowledge-base files carry the agent's entity_id.
- // Sending entity_id for user attachments makes the RAG API's entity
- // filter return no results for them. When files are provided by
- // primeFiles, fromAgent is always set; for callers that pass files
- // directly without the flag, the safe default is unscoped (no
- // entity_id).
- if (!entity_id || file.fromAgent !== true) {
- return body;
- }
- body.entity_id = entity_id;
- logger.debug(`[${Tools.file_search}] RAG API /query body`, body);
- return body;
- };
-
- const queryPromises = files.map((file) =>
- axios
- .post(`${process.env.RAG_API_URL}/query`, createQueryBody(file), {
- headers: {
- Authorization: `Bearer ${jwtToken}`,
- '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',
- error,
- });
- return null;
- }),
- );
-
- const results = await Promise.all(queryPromises);
- const validResults = results.filter((result) => result !== null);
-
- if (validResults.length === 0) {
- return ['No results found or errors occurred while searching the files.', undefined];
- }
-
- const formattedResults = validResults
- .flatMap((result) =>
- result.data.map(([docInfo, distance]) => ({
- filename: docInfo.metadata.source.split('/').pop(),
- content: docInfo.page_content,
- distance,
- file_id: result.file_id,
- page:
- Number.isInteger(docInfo.metadata.page) && docInfo.metadata.page >= 0
- ? docInfo.metadata.page + 1
- : null,
- })),
- )
- .sort((a, b) => a.distance - b.distance)
- .slice(0, 10);
-
- if (formattedResults.length === 0) {
- return [
- 'No content found in the files. The files may not have been processed correctly or you may need to refine your query.',
- undefined,
- ];
- }
-
- const sources = formattedResults.map((result) => ({
- type: 'file',
- fileId: result.file_id,
- content: result.content,
- fileName: result.filename,
- relevance: 1.0 - result.distance,
- pages: result.page ? [result.page] : [],
- 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 } }];
- },
+ ({ query }) =>
+ executeFileSearchQuery({
+ query,
+ userId,
+ files,
+ entity_id,
+ fileCitations,
+ appConfig,
+ ragApiUrl: process.env.RAG_API_URL,
+ httpClient: axios,
+ generateShortLivedToken,
+ logAxiosError,
+ selectFileCitationSources,
+ logger,
+ }),
{
name: Tools.file_search,
responseFormat: 'content_and_artifact',
diff --git a/api/test/app/clients/tools/util/fileSearch.test.js b/api/test/app/clients/tools/util/fileSearch.test.js
index 27788b2124..fd932f590e 100644
--- a/api/test/app/clients/tools/util/fileSearch.test.js
+++ b/api/test/app/clients/tools/util/fileSearch.test.js
@@ -3,11 +3,13 @@ const { ResourceType } = require('librechat-data-provider');
jest.mock('axios');
jest.mock('@librechat/api', () => {
- const { selectFileCitationSources } = jest.requireActual('@librechat/api');
+ const { selectFileCitationSources, executeFileSearchQuery } =
+ jest.requireActual('@librechat/api');
return {
generateShortLivedToken: jest.fn(),
logAxiosError: jest.fn(),
selectFileCitationSources,
+ executeFileSearchQuery,
};
});
@@ -75,6 +77,25 @@ describe('fileSearch.js - tuple return validation', () => {
expect(result[1]).toBeUndefined();
});
+ it.each(['', ' ', '\n\t', undefined])(
+ 'does not query any files when the search query is blank (%j)',
+ async (query) => {
+ const fileSearchTool = await createFileSearchTool({
+ userId: 'user1',
+ files: [
+ { file_id: 'file-1', filename: 'one.pdf' },
+ { file_id: 'file-2', filename: 'two.pdf' },
+ ],
+ });
+
+ const result = await fileSearchTool.func({ query });
+
+ expect(result).toEqual(['A non-empty query is required to search the files.', undefined]);
+ expect(axios.post).not.toHaveBeenCalled();
+ expect(generateShortLivedToken).not.toHaveBeenCalled();
+ },
+ );
+
it('should return tuple when JWT token generation fails', async () => {
generateShortLivedToken.mockReturnValue(null);
@@ -138,6 +159,28 @@ describe('fileSearch.js - tuple return validation', () => {
expect(source.pageRelevance).toEqual(pages.length ? { [pages[0]]: expect.any(Number) } : {});
});
+ it('forwards valid query text unchanged', async () => {
+ generateShortLivedToken.mockReturnValue('mock-jwt-token');
+ axios.post.mockResolvedValue({ data: [] });
+ const fileSearchTool = await createFileSearchTool({
+ userId: 'user1',
+ files: [{ file_id: 'file-1', filename: 'one.pdf' }],
+ });
+
+ await fileSearchTool.func({ query: ' find me ' });
+
+ expect(axios.post).toHaveBeenCalledWith(
+ 'http://localhost:8000/query',
+ { file_id: 'file-1', query: ' find me ', k: 5 },
+ {
+ headers: {
+ Authorization: 'Bearer mock-jwt-token',
+ 'Content-Type': 'application/json',
+ },
+ },
+ );
+ });
+
it('should return tuple with formatted results and sources artifact', async () => {
generateShortLivedToken.mockReturnValue('mock-jwt-token');
@@ -235,6 +278,27 @@ describe('fileSearch.js - tuple return validation', () => {
expect(artifact.file_search.fileCitations).toBe(true);
});
+ it('keeps a successful file result when another file search fails', async () => {
+ generateShortLivedToken.mockReturnValue('mock-jwt-token');
+ axios.post.mockRejectedValueOnce(new Error('file unavailable')).mockResolvedValueOnce({
+ data: [[{ page_content: 'Found passage', metadata: { source: '/good.pdf' } }, 0.2]],
+ });
+ const fileSearchTool = await createFileSearchTool({
+ userId: 'user1',
+ files: [
+ { file_id: 'missing', filename: 'missing.pdf' },
+ { file_id: 'good', filename: 'good.pdf' },
+ ],
+ });
+
+ const [content, artifact] = await fileSearchTool.func({ query: 'lookup' });
+
+ expect(axios.post).toHaveBeenCalledTimes(2);
+ expect(content).toContain('Found passage');
+ expect(artifact.file_search.sources).toHaveLength(1);
+ expect(artifact.file_search.sources[0].fileId).toBe('good');
+ });
+
it('should handle multiple files correctly', async () => {
generateShortLivedToken.mockReturnValue('mock-jwt-token');
diff --git a/packages/api/src/files/index.ts b/packages/api/src/files/index.ts
index 5bda69aea7..0d5a83dde5 100644
--- a/packages/api/src/files/index.ts
+++ b/packages/api/src/files/index.ts
@@ -18,6 +18,8 @@ export * from './upload/routing';
export * from './upload/diagnostics';
export * from './upload/fallback';
export * from './rag';
+export * from './rag/context';
+export * from './rag/search';
export * from './regexEngine';
export * from './retention';
export * from './sse';
diff --git a/packages/api/src/files/rag/context.spec.ts b/packages/api/src/files/rag/context.spec.ts
new file mode 100644
index 0000000000..535cc3ca9e
--- /dev/null
+++ b/packages/api/src/files/rag/context.spec.ts
@@ -0,0 +1,87 @@
+import { createRagContextHandlers } from './context';
+
+const req = { user: { id: 'user-1' } };
+const files = ['a.pdf', 'b.pdf', 'c.pdf'].map((filename, index) => ({
+ file_id: `file-${index}`,
+ filename,
+ type: 'application/pdf',
+ embedded: true,
+}));
+
+function setup(userMessageContent?: string, fullContextSetting?: string, ragApiUrl = 'http://rag') {
+ const httpClient = {
+ get: jest.fn().mockResolvedValue({ data: 'whole document' }),
+ post: jest.fn().mockResolvedValue({ data: [[{ page_content: 'Relevant excerpt' }, 0.1]] }),
+ };
+ const generateShortLivedToken = jest.fn(() => 'signed-token');
+ const isEnabled = jest.fn((setting?: string | boolean | null) => setting === 'true');
+ const logAxiosError = jest.fn(() => 'logged');
+ const handlers = createRagContextHandlers({
+ req,
+ userMessageContent,
+ ragApiUrl,
+ fullContextSetting,
+ httpClient,
+ generateShortLivedToken,
+ isEnabled,
+ logAxiosError,
+ });
+ return { handlers, httpClient, generateShortLivedToken, isEnabled, logAxiosError };
+}
+
+describe('legacy RAG context', () => {
+ it.each(['', ' ', '\t\n ', undefined])(
+ 'skips searches for a blank message (%j), even across several files',
+ async (text) => {
+ const { handlers, httpClient } = setup(text);
+ for (const file of files) {
+ await handlers?.processFile(file);
+ }
+ expect(await handlers?.createContext()).toBe('');
+ expect(httpClient.post).not.toHaveBeenCalled();
+ expect(httpClient.get).not.toHaveBeenCalled();
+ },
+ );
+
+ it('retains the original query and formats valid search results', async () => {
+ const { handlers, httpClient } = setup(' what is the deadline? ');
+ await handlers?.processFile(files[0]);
+ await handlers?.processFile(files[0]);
+ expect(await handlers?.createContext()).toContain('Relevant excerpt');
+ expect(httpClient.post).toHaveBeenCalledTimes(1);
+ expect(httpClient.post).toHaveBeenCalledWith(
+ 'http://rag/query',
+ { file_id: 'file-0', query: ' what is the deadline? ', k: 4 },
+ { headers: { Authorization: 'Bearer signed-token', 'Content-Type': 'application/json' } },
+ );
+ });
+
+ it('continues to fetch the full document for a blank message in full-context mode', async () => {
+ const { handlers, httpClient } = setup('', 'true');
+ await handlers?.processFile(files[0]);
+ expect(await handlers?.createContext()).toContain('whole document');
+ expect(httpClient.post).not.toHaveBeenCalled();
+ expect(httpClient.get).toHaveBeenCalledWith('http://rag/documents/file-0/context', {
+ headers: { Authorization: 'Bearer signed-token' },
+ });
+ });
+
+ it('does nothing when RAG is disabled, without looking at the request', () => {
+ const { handlers, generateShortLivedToken, isEnabled } = setup('', 'true', '');
+ expect(handlers).toBeUndefined();
+ expect(generateShortLivedToken).not.toHaveBeenCalled();
+ expect(isEnabled).not.toHaveBeenCalled();
+ });
+
+ it('preserves failed-request behavior for a nonblank query', async () => {
+ const { handlers, httpClient, logAxiosError } = setup('question');
+ const failure = new Error('backend unavailable');
+ httpClient.post.mockRejectedValueOnce(failure);
+ await handlers?.processFile(files[0]);
+ await expect(handlers?.createContext()).rejects.toBe(failure);
+ expect(logAxiosError).toHaveBeenCalledWith({
+ message: 'Error creating context',
+ error: failure,
+ });
+ });
+});
diff --git a/packages/api/src/files/rag/context.ts b/packages/api/src/files/rag/context.ts
new file mode 100644
index 0000000000..4f481d72de
--- /dev/null
+++ b/packages/api/src/files/rag/context.ts
@@ -0,0 +1,204 @@
+import type { AxiosResponse } from 'axios';
+import type axios from 'axios';
+import type { logAxiosError } from '~/utils/axios';
+import type { isEnabled } from '~/utils/common';
+
+interface ContextFile {
+ embedded?: boolean;
+ file_id: string;
+ filename: string;
+ type?: string;
+}
+
+interface SearchHit {
+ page_content?: string;
+}
+
+type SearchResults = [SearchHit, number][];
+type ContextResponse = AxiosResponse<string | SearchResults>;
+
+interface RagContextOptions {
+ req: { user: { id: string } };
+ userMessageContent?: string;
+ ragApiUrl?: string;
+ fullContextSetting?: string;
+ httpClient: Pick<typeof axios, 'get' | 'post'>;
+ generateShortLivedToken: (userId: string) => string;
+ isEnabled: typeof isEnabled;
+ logAxiosError: typeof logAxiosError;
+}
+
+const footer = `Use the context as your learned knowledge to better answer the user.
+
+In your response, remember to follow these guidelines:
+- If you don't know the answer, simply say that you don't know.
+- If you are unsure how to answer, ask for clarification.
+- Avoid mentioning that you obtained the information from the context.
+`;
+
+/** Builds legacy RAG context for non-agents endpoints (including Bedrock). */
+export function createRagContextHandlers({
+ req,
+ userMessageContent,
+ ragApiUrl,
+ fullContextSetting,
+ httpClient,
+ generateShortLivedToken,
+ isEnabled,
+ logAxiosError,
+}: RagContextOptions):
+ | {
+ processFile: (file: ContextFile) => Promise<void>;
+ createContext: () => Promise<string>;
+ }
+ | undefined {
+ if (!ragApiUrl) {
+ return undefined;
+ }
+
+ const queryPromises: Array<Promise<ContextResponse>> = [];
+ const processedFiles: ContextFile[] = [];
+ const processedIds = new Set<string>();
+ const jwtToken = generateShortLivedToken(req.user.id);
+ const useFullContext = isEnabled(fullContextSetting);
+ const canSemanticSearch =
+ typeof userMessageContent === 'string' && userMessageContent.trim().length > 0;
+
+ const query = async (file: ContextFile): Promise<ContextResponse> => {
+ if (useFullContext) {
+ return httpClient.get<string>(`${ragApiUrl}/documents/${file.file_id}/context`, {
+ headers: {
+ Authorization: `Bearer ${jwtToken}`,
+ },
+ });
+ }
+
+ return httpClient.post<SearchResults>(
+ `${ragApiUrl}/query`,
+ {
+ file_id: file.file_id,
+ query: userMessageContent,
+ k: 4,
+ },
+ {
+ headers: {
+ Authorization: `Bearer ${jwtToken}`,
+ 'Content-Type': 'application/json',
+ },
+ },
+ );
+ };
+
+ const processFile = async (file: ContextFile): Promise<void> => {
+ if (!useFullContext && !canSemanticSearch) {
+ return;
+ }
+ if (file.embedded && !processedIds.has(file.file_id)) {
+ try {
+ const promise = query(file);
+ queryPromises.push(promise);
+ processedFiles.push(file);
+ processedIds.add(file.file_id);
+ } catch (error) {
+ logAxiosError({ message: `Error processing file ${file.filename}`, error });
+ }
+ }
+ };
+
+ const createContext = async (): Promise<string> => {
+ try {
+ if (!queryPromises.length || !processedFiles.length) {
+ return '';
+ }
+
+ const oneFile = processedFiles.length === 1;
+ const header = `The user has attached ${oneFile ? 'a' : processedFiles.length} file${
+ !oneFile ? 's' : ''
+ } to the conversation:`;
+
+ const files = `${
+ oneFile
+ ? ''
+ : `
+ <files>`
+ }${processedFiles
+ .map(
+ (file) => `
+ <file>
+ <filename>${file.filename}</filename>
+ <type>${file.type}</type>
+ </file>`,
+ )
+ .join('')}${
+ oneFile
+ ? ''
+ : `
+ </files>`
+ }`;
+
+ const resolvedQueries = await Promise.all(queryPromises);
+
+ const context =
+ resolvedQueries.length === 0
+ ? '\n\tThe semantic search did not return any results.'
+ : resolvedQueries
+ .map((queryResult, index) => {
+ const file = processedFiles[index];
+ const contextItems = queryResult.data;
+
+ const generateContext = (currentContext: string): string => `
+ <file>
+ <filename>${file.filename}</filename>
+ <context>${currentContext}
+ </context>
+ </file>`;
+
+ if (useFullContext) {
+ return generateContext(`\n${contextItems}`);
+ }
+
+ if (!Array.isArray(contextItems)) {
+ throw new TypeError('Unexpected RAG query response');
+ }
+
+ return generateContext(
+ contextItems
+ .map((item) => {
+ const pageContent = item[0].page_content;
+ return `
+ <contextItem>
+ <![CDATA[${pageContent?.trim()}]]>
+ </contextItem>`;
+ })
+ .join(''),
+ );
+ })
+ .join('');
+
+ if (useFullContext) {
+ const prompt = `${header}
+ ${context}
+ ${footer}`;
+
+ return prompt;
+ }
+
+ const prompt = `${header}
+ ${files}
+
+ A semantic search was executed with the user's message as the query, retrieving the following context inside <context></context> XML tags.
+
+ <context>${context}
+ </context>
+
+ ${footer}`;
+
+ return prompt;
+ } catch (error) {
+ logAxiosError({ message: 'Error creating context', error });
+ throw error;
+ }
+ };
+
+ return { processFile, createContext };
+}
diff --git a/packages/api/src/files/rag/search.ts b/packages/api/src/files/rag/search.ts
new file mode 100644
index 0000000000..6b6b3ccc3b
--- /dev/null
+++ b/packages/api/src/files/rag/search.ts
@@ -0,0 +1,158 @@
+import { EModelEndpoint, Tools } from 'librechat-data-provider';
+import type { logger } from '@librechat/data-schemas';
+import type axios from 'axios';
+import type { FileCitationSelectionConfig, selectFileCitationSources } from '../citations';
+import type { logAxiosError } from '~/utils/axios';
+
+type SearchFile = { file_id: string; fromAgent?: boolean };
+type FileSearchResult = [
+ string,
+ { file_search: { sources: FileSearchSource[]; fileCitations: boolean } } | undefined,
+];
+
+type FileSearchSource = {
+ type: string;
+ fileId: string;
+ content: string;
+ fileName?: string;
+ relevance: number;
+ pages: number[];
+ pageRelevance: { [page: number]: number };
+};
+
+interface SearchHit {
+ page_content: string;
+ metadata: { source: string; page?: number | string | null };
+}
+
+type SearchResults = [SearchHit, number][];
+
+interface SearchOptions {
+ query?: string;
+ userId: string;
+ files: readonly SearchFile[];
+ entity_id?: string;
+ fileCitations: boolean;
+ appConfig?: { endpoints?: Partial<Record<EModelEndpoint, FileCitationSelectionConfig>> };
+ ragApiUrl?: string;
+ httpClient: Pick<typeof axios, 'post'>;
+ generateShortLivedToken: (userId: string) => string;
+ logAxiosError: typeof logAxiosError;
+ selectFileCitationSources: typeof selectFileCitationSources;
+ logger: Pick<typeof logger, 'debug'>;
+}
+
+/** Executes a file-search tool call without sending malformed queries to RAG API. */
+export async function executeFileSearchQuery({
+ query,
+ userId,
+ files,
+ entity_id,
+ fileCitations,
+ appConfig,
+ ragApiUrl,
+ httpClient,
+ generateShortLivedToken,
+ logAxiosError,
+ selectFileCitationSources,
+ logger,
+}: SearchOptions): Promise<FileSearchResult> {
+ if (files.length === 0) {
+ return ['No files to search. Instruct the user to add files for the search.', undefined];
+ }
+ if (typeof query !== 'string' || query.trim().length === 0) {
+ return ['A non-empty query is required to search the files.', undefined];
+ }
+ const jwtToken = generateShortLivedToken(userId);
+ if (!jwtToken) {
+ return ['There was an error authenticating the file search request.', undefined];
+ }
+
+ const createQueryBody = (file: SearchFile) => {
+ const body: { file_id: string; query: string; k: number; entity_id?: string } = {
+ file_id: file.file_id,
+ query,
+ k: 5,
+ };
+ // Only agent knowledge-base files carry entity_id. User attachments must stay user-scoped.
+ if (!entity_id || file.fromAgent !== true) {
+ return body;
+ }
+ body.entity_id = entity_id;
+ logger.debug(`[${Tools.file_search}] RAG API /query body`, body);
+ return body;
+ };
+
+ const queryPromises = files.map((file) =>
+ httpClient
+ .post<SearchResults>(`${ragApiUrl}/query`, createQueryBody(file), {
+ headers: {
+ Authorization: `Bearer ${jwtToken}`,
+ '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',
+ error,
+ });
+ return null;
+ }),
+ );
+
+ const results = await Promise.all(queryPromises);
+ const validResults = results.filter((result) => result !== null);
+
+ if (validResults.length === 0) {
+ return ['No results found or errors occurred while searching the files.', undefined];
+ }
+
+ const formattedResults = validResults
+ .flatMap((result) =>
+ result.data.map(([docInfo, distance]) => ({
+ filename: docInfo.metadata.source.split('/').pop(),
+ content: docInfo.page_content,
+ distance,
+ file_id: result.file_id,
+ page:
+ typeof docInfo.metadata.page === 'number' &&
+ Number.isInteger(docInfo.metadata.page) &&
+ docInfo.metadata.page >= 0
+ ? docInfo.metadata.page + 1
+ : null,
+ })),
+ )
+ .sort((a, b) => a.distance - b.distance)
+ .slice(0, 10);
+
+ if (formattedResults.length === 0) {
+ return [
+ 'No content found in the files. The files may not have been processed correctly or you may need to refine your query.',
+ undefined,
+ ];
+ }
+
+ const sources = formattedResults.map((result) => ({
+ type: 'file',
+ fileId: result.file_id,
+ content: result.content,
+ fileName: result.filename,
+ relevance: 1.0 - result.distance,
+ pages: result.page ? [result.page] : [],
+ 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 } }];
+}