📚 feat: Add Source Citations for File Search in Agents (#8652)

* feat: Source Citations for file_search in Agents

* Fix: Added citation limits and relevance score to app service. Removed duplicate tests

* ✨ feat: implement Role-level toggle to optionally disable file Source Citation in Agents

* 🐛 fix: update mock for librechat-data-provider to include PermissionTypes and SystemRoles

---------

Co-authored-by: “Praneeth <praneeth.goparaju@slalom.com>

packages/data-provider/src/config.ts

@@ -255,6 +255,9 @@ export const agentsEndpointSchema = baseEndpointSchema
       recursionLimit: z.number().optional(),
       disableBuilder: z.boolean().optional().default(false),
       maxRecursionLimit: z.number().optional(),
+      maxCitations: z.number().min(1).max(50).optional().default(30),
+      maxCitationsPerFile: z.number().min(1).max(10).optional().default(7),
+      minRelevanceScore: z.number().min(0.0).max(1.0).optional().default(0.45),
       allowedProviders: z.array(z.union([z.string(), eModelEndpointSchema])).optional(),
       capabilities: z
         .array(z.nativeEnum(AgentCapabilities))
@@ -265,6 +268,9 @@ export const agentsEndpointSchema = baseEndpointSchema
   .default({
     disableBuilder: false,
     capabilities: defaultAgentCapabilities,
+    maxCitations: 30,
+    maxCitationsPerFile: 7,
+    minRelevanceScore: 0.45,
   });
 
 export type TAgentsEndpoint = z.infer<typeof agentsEndpointSchema>;
@@ -518,6 +524,7 @@ export const intefaceSchema = z
     runCode: z.boolean().optional(),
     webSearch: z.boolean().optional(),
     fileSearch: z.boolean().optional(),
+    fileCitations: z.boolean().optional(),
   })
   .default({
     endpointsMenu: true,
@@ -534,6 +541,7 @@ export const intefaceSchema = z
     runCode: true,
     webSearch: true,
     fileSearch: true,
+    fileCitations: true,
   });
 
 export type TInterfaceConfig = z.infer<typeof intefaceSchema>;

packages/data-provider/src/permissions.ts

@@ -40,6 +40,10 @@ export enum PermissionTypes {
    * Type for using the "File Search" feature
    */
   FILE_SEARCH = 'FILE_SEARCH',
+  /**
+   * Type for using the "File Citations" feature in agents
+   */
+  FILE_CITATIONS = 'FILE_CITATIONS',
 }
 
 /**
@@ -112,6 +116,11 @@ export const fileSearchPermissionsSchema = z.object({
 });
 export type TFileSearchPermissions = z.infer<typeof fileSearchPermissionsSchema>;
 
+export const fileCitationsPermissionsSchema = z.object({
+  [Permissions.USE]: z.boolean().default(true),
+});
+export type TFileCitationsPermissions = z.infer<typeof fileCitationsPermissionsSchema>;
+
 // Define a single permissions schema that holds all permission types.
 export const permissionsSchema = z.object({
   [PermissionTypes.PROMPTS]: promptPermissionsSchema,
@@ -123,4 +132,5 @@ export const permissionsSchema = z.object({
   [PermissionTypes.RUN_CODE]: runCodePermissionsSchema,
   [PermissionTypes.WEB_SEARCH]: webSearchPermissionsSchema,
   [PermissionTypes.FILE_SEARCH]: fileSearchPermissionsSchema,
+  [PermissionTypes.FILE_CITATIONS]: fileCitationsPermissionsSchema,
 });

packages/data-provider/src/roles.ts

@@ -12,6 +12,7 @@ import {
   fileSearchPermissionsSchema,
   multiConvoPermissionsSchema,
   temporaryChatPermissionsSchema,
+  fileCitationsPermissionsSchema,
 } from './permissions';
 
 /**
@@ -78,6 +79,9 @@ const defaultRolesSchema = z.object({
       [PermissionTypes.FILE_SEARCH]: fileSearchPermissionsSchema.extend({
         [Permissions.USE]: z.boolean().default(true),
       }),
+      [PermissionTypes.FILE_CITATIONS]: fileCitationsPermissionsSchema.extend({
+        [Permissions.USE]: z.boolean().default(true),
+      }),
     }),
   }),
   [SystemRoles.USER]: roleSchema.extend({
@@ -125,6 +129,9 @@ export const roleDefaults = defaultRolesSchema.parse({
       [PermissionTypes.FILE_SEARCH]: {
         [Permissions.USE]: true,
       },
+      [PermissionTypes.FILE_CITATIONS]: {
+        [Permissions.USE]: true,
+      },
     },
   },
   [SystemRoles.USER]: {
@@ -139,6 +146,7 @@ export const roleDefaults = defaultRolesSchema.parse({
       [PermissionTypes.RUN_CODE]: {},
       [PermissionTypes.WEB_SEARCH]: {},
       [PermissionTypes.FILE_SEARCH]: {},
+      [PermissionTypes.FILE_CITATIONS]: {},
     },
   },
 });

packages/data-provider/src/schemas.ts

@@ -551,6 +551,7 @@ export type TAttachmentMetadata = {
   messageId: string;
   toolCallId: string;
   [Tools.web_search]?: SearchResultData;
+  [Tools.file_search]?: SearchResultData;
   [Tools.memory]?: MemoryArtifact;
 };
 

packages/data-provider/src/types/web.ts

@@ -34,7 +34,7 @@ export type ValidSource = ProcessedOrganic | ProcessedTopStory;
 
 export type ResultReference = {
   link: string;
-  type: 'link' | 'image' | 'video';
+  type: 'link' | 'image' | 'video' | 'file';
   title?: string;
   attribution?: string;
 };

packages/data-schemas/src/schema/role.ts

@@ -42,6 +42,9 @@ const rolePermissionsSchema = new Schema(
     [PermissionTypes.FILE_SEARCH]: {
       [Permissions.USE]: { type: Boolean, default: true },
     },
+    [PermissionTypes.FILE_CITATIONS]: {
+      [Permissions.USE]: { type: Boolean, default: true },
+    },
   },
   { _id: false },
 );
@@ -73,6 +76,7 @@ const roleSchema: Schema<IRole> = new Schema({
       [PermissionTypes.RUN_CODE]: { [Permissions.USE]: true },
       [PermissionTypes.WEB_SEARCH]: { [Permissions.USE]: true },
       [PermissionTypes.FILE_SEARCH]: { [Permissions.USE]: true },
+      [PermissionTypes.FILE_CITATIONS]: { [Permissions.USE]: true },
     }),
   },
 });