@librechat/agents 2.4.320 → 2.4.322

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "2.4.320",
+  "version": "2.4.322",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -122,7 +122,8 @@
     "tsc-alias": "^1.8.10",
     "tsconfig-paths": "^4.2.0",
     "tslib": "^2.6.3",
-    "typescript": "^5.5.3"
+    "typescript": "^5.5.3",
+    "winston": "^3.17.0"
   },
   "lint-staged": {
     "*.{js,ts}": [

package/src/scripts/search.ts

@@ -112,6 +112,9 @@ async function testStandardStreaming(): Promise<void> {
   // const userMessage = 'Are massage guns good?';
   // const userMessage = 'What is functional programming?';
   const userMessage = "Get me today's trending news.";
+  // const userMessage = "search recent italy earthquake volcano activity";
+  // const userMessage =
+  //   "use 'Trump' as the exact search query and tell me what you find.";
 
   conversationHistory.push(new HumanMessage(userMessage));
 

package/src/tools/search/firecrawl.ts

@@ -1,7 +1,7 @@
-/* eslint-disable no-console */
 import axios from 'axios';
 import { processContent } from './content';
 import type * as t from './types';
+import { createDefaultLogger } from './utils';
 
 /**
  * Firecrawl scraper implementation
@@ -12,6 +12,7 @@ export class FirecrawlScraper {
   private apiUrl: string;
   private defaultFormats: string[];
   private timeout: number;
+  private logger: t.Logger;
 
   constructor(config: t.FirecrawlScraperConfig = {}) {
     this.apiKey = config.apiKey ?? process.env.FIRECRAWL_API_KEY ?? '';
@@ -25,11 +26,15 @@ export class FirecrawlScraper {
     this.defaultFormats = config.formats ?? ['markdown', 'html'];
     this.timeout = config.timeout ?? 15000;
 
+    this.logger = config.logger || createDefaultLogger();
+
     if (!this.apiKey) {
-      console.warn('FIRECRAWL_API_KEY is not set. Scraping will not work.');
+      this.logger.warn('FIRECRAWL_API_KEY is not set. Scraping will not work.');
     }
 
-    console.log(`Firecrawl scraper initialized with API URL: ${this.apiUrl}`);
+    this.logger.debug(
+      `Firecrawl scraper initialized with API URL: ${this.apiUrl}`
+    );
   }
 
   /**
@@ -107,7 +112,7 @@ export class FirecrawlScraper {
         );
         return [markdown, rest];
       } catch (error) {
-        console.error('Error processing content:', error);
+        this.logger.error('Error processing content:', error);
         return [response.data.markdown, undefined];
       }
     } else if (response.data.markdown != null) {

package/src/tools/search/format.ts

@@ -1,107 +1,172 @@
 import type * as t from './types';
-import { getDomainName } from './utils';
+import { getDomainName, fileExtRegex } from './utils';
+
+function addHighlightSection(): string[] {
+  return ['\n## Highlights', ''];
+}
+
+// Helper function to format a source (organic or top story)
+function formatSource(
+  source: t.ValidSource,
+  index: number,
+  turn: number,
+  sourceType: 'search' | 'news',
+  references: t.ResultReference[]
+): string {
+  /** Array of all lines to include in the output */
+  const outputLines: string[] = [];
+
+  // Add the title
+  outputLines.push(
+    `# ${sourceType.charAt(0).toUpperCase() + sourceType.slice(1)} ${index}: ${source.title != null && source.title ? `"${source.title}"` : '(no title)'}`
+  );
+  outputLines.push(`\nAnchor: \\ue202turn${turn}${sourceType}${index}`);
+  outputLines.push(`URL: ${source.link}`);
+
+  // Add optional fields
+  if ('snippet' in source && source.snippet != null) {
+    outputLines.push(`Summary: ${source.snippet}`);
+  }
+
+  if (source.date != null) {
+    outputLines.push(`Date: ${source.date}`);
+  }
+
+  if (source.attribution != null) {
+    outputLines.push(`Source: ${source.attribution}`);
+  }
+
+  // Add highlight section or empty line
+  if ((source.highlights?.length ?? 0) > 0) {
+    outputLines.push(...addHighlightSection());
+  } else {
+    outputLines.push('');
+  }
+
+  // Process highlights if they exist
+  (source.highlights ?? [])
+    .filter((h) => h.text.trim().length > 0)
+    .forEach((h, hIndex) => {
+      outputLines.push(
+        `### Highlight ${hIndex + 1} [Relevance: ${h.score.toFixed(2)}]`
+      );
+      outputLines.push('');
+      outputLines.push('```text');
+      outputLines.push(h.text.trim());
+      outputLines.push('```');
+      outputLines.push('');
+
+      if (h.references != null && h.references.length) {
+        let hasHeader = false;
+        const refLines: string[] = [];
+
+        for (let j = 0; j < h.references.length; j++) {
+          const ref = h.references[j];
+          if (ref.reference.originalUrl.includes('mailto:')) {
+            continue;
+          }
+          references.push({
+            type: ref.type,
+            link: ref.reference.originalUrl,
+            attribution: getDomainName(ref.reference.originalUrl),
+            title: (
+              ((ref.reference.title ?? '') || ref.reference.text) ??
+              ''
+            ).split('\n')[0],
+          });
+
+          if (ref.type !== 'link') {
+            continue;
+          }
+
+          if (fileExtRegex.test(ref.reference.originalUrl)) {
+            continue;
+          }
+
+          if (!hasHeader) {
+            refLines.push('Core References:');
+            hasHeader = true;
+          }
+
+          refLines.push(
+            `- ${ref.type}#${ref.originalIndex + 1}: ${ref.reference.originalUrl}`
+          );
+          refLines.push(
+            `\t- Anchor: \\ue202turn${turn}ref${references.length - 1}`
+          );
+        }
+
+        if (hasHeader) {
+          outputLines.push(...refLines);
+          outputLines.push('');
+        }
+      }
+
+      if (hIndex < (source.highlights?.length ?? 0) - 1) {
+        outputLines.push('---');
+        outputLines.push('');
+      }
+    });
+
+  outputLines.push('');
+  return outputLines.join('\n');
+}
 
 export function formatResultsForLLM(
   turn: number,
   results: t.SearchResultData
 ): { output: string; references: t.ResultReference[] } {
-  let output = '';
+  /** Array to collect all output lines */
+  const outputLines: string[] = [];
 
   const addSection = (title: string): void => {
-    output += `\n=== ${title} ===\n`;
+    outputLines.push('');
+    outputLines.push(`=== ${title} ===`);
+    outputLines.push('');
   };
 
   const references: t.ResultReference[] = [];
+
   // Organic (web) results
   if (results.organic?.length != null && results.organic.length > 0) {
     addSection(`Web Results, Turn ${turn}`);
     for (let i = 0; i < results.organic.length; i++) {
       const r = results.organic[i];
-      output += [
-        `# Source ${i}: "${r.title ?? '(no title)'}"`,
-        `Anchor: \\ue202turn${turn}search${i}`,
-        `URL: ${r.link}`,
-        r.snippet != null ? `Summary: ${r.snippet}` : '',
-        r.date != null ? `Date: ${r.date}` : '',
-        r.attribution != null ? `Source: ${r.attribution}` : '',
-        '',
-        '\n## Highlights\n\n',
-        '',
-        '',
-      ]
-        .filter(Boolean)
-        .join('\n');
-
-      (r.highlights ?? [])
-        .filter((h) => h.text.trim().length > 0)
-        .forEach((h, hIndex) => {
-          output += `### Highlight ${hIndex + 1} [Relevance: ${h.score.toFixed(2)}]\n\n`;
-          output += '```text\n' + h.text.trim() + '\n```\n\n';
-
-          if (h.references != null && h.references.length) {
-            output += 'Core References:\n';
-            output += h.references
-              .map((ref) => {
-                references.push({
-                  link: ref.reference.originalUrl,
-                  attribution: getDomainName(ref.reference.originalUrl),
-                  title: (
-                    ((ref.reference.title ?? '') || ref.reference.text) ??
-                    ''
-                  ).split('\n')[0],
-                });
-                return `- ${ref.type}#${ref.originalIndex + 1}: ${ref.reference.originalUrl}\n\t- Anchor: \\ue202turn${turn}ref${references.length - 1}`;
-              })
-              .join('\n');
-            output += '\n\n';
-          }
-
-          if (hIndex < (r.highlights?.length ?? 0) - 1) {
-            output += '---\n\n';
-          }
-        });
-
+      outputLines.push(formatSource(r, i, turn, 'search', references));
       delete results.organic[i].highlights;
-      output += '\n';
     }
   }
 
-  // Ignoring these sections for now
-  // // Top stories (news)
-  // const topStores = results.topStories ?? [];
-  // if (topStores.length) {
-  //   addSection('News Results');
-  //   topStores.forEach((r, i) => {
-  //     output += [
-  //       `Anchor: \ue202turn0news${i}`,
-  //       `Title: ${r.title ?? '(no title)'}`,
-  //       `URL: ${r.link}`,
-  //       r.snippet != null ? `Snippet: ${r.snippet}` : '',
-  //       r.date != null ? `Date: ${r.date}` : '',
-  //       r.attribution != null ? `Source: ${r.attribution}` : '',
-  //       ''
-  //     ].filter(Boolean).join('\n');
-  //   });
-  // }
+  // Top stories (news)
+  const topStories = results.topStories ?? [];
+  if (topStories.length) {
+    addSection('News Results');
+    for (let i = 0; i < topStories.length; i++) {
+      const r = topStories[i];
+      outputLines.push(formatSource(r, i, turn, 'news', references));
+      if (results.topStories?.[i]?.highlights) {
+        delete results.topStories[i].highlights;
+      }
+    }
+  }
 
   // // Images
   // const images = results.images ?? [];
   // if (images.length) {
   //   addSection('Image Results');
-  //   images.forEach((img, i) => {
-  //     output += [
-  //       `Anchor: \ue202turn0image${i}`,
-  //       `Title: ${img.title ?? '(no title)'}`,
-  //       `Image URL: ${img.imageUrl}`,
-  //       ''
-  //     ].join('\n');
-  //   });
+  //   const imageLines = images.map((img, i) => [
+  //     `Anchor: \ue202turn0image${i}`,
+  //     `Title: ${img.title ?? '(no title)'}`,
+  //     `Image URL: ${img.imageUrl}`,
+  //     ''
+  //   ].join('\n'));
+  //   outputLines.push(imageLines.join('\n'));
   // }
 
   // Knowledge Graph
   if (results.knowledgeGraph != null) {
     addSection('Knowledge Graph');
-    output += [
+    const kgLines = [
       `**Title:** ${results.knowledgeGraph.title ?? '(no title)'}`,
       results.knowledgeGraph.type != null
         ? `**Type:** ${results.knowledgeGraph.type}`
@@ -129,15 +194,15 @@ export function formatResultsForLLM(
         )}\n\`\`\``
         : '',
       '',
-    ]
-      .filter(Boolean)
-      .join('\n\n');
+    ].filter(Boolean);
+
+    outputLines.push(kgLines.join('\n\n'));
   }
 
   // Answer Box
   if (results.answerBox != null) {
     addSection('Answer Box');
-    output += [
+    const abLines = [
       results.answerBox.title != null
         ? `**Title:** ${results.answerBox.title}`
         : '',
@@ -153,30 +218,35 @@ export function formatResultsForLLM(
         ? `**Link:** ${results.answerBox.link}`
         : '',
       '',
-    ]
-      .filter(Boolean)
-      .join('\n\n');
+    ].filter(Boolean);
+
+    outputLines.push(abLines.join('\n\n'));
   }
 
   // People also ask
   const peopleAlsoAsk = results.peopleAlsoAsk ?? [];
   if (peopleAlsoAsk.length) {
     addSection('People Also Ask');
+
+    const paaLines: string[] = [];
     peopleAlsoAsk.forEach((p, i) => {
-      output += [
+      const questionLines = [
         `### Question ${i + 1}:`,
         `"${p.question}"`,
-        `${p.snippet != null && p.snippet ? `Snippet: ${p.snippet}}` : ''}`,
+        `${p.snippet != null && p.snippet ? `Snippet: ${p.snippet}` : ''}`,
         `${p.title != null && p.title ? `Title: ${p.title}` : ''}`,
         `${p.link != null && p.link ? `Link: ${p.link}` : ''}`,
         '',
-      ]
-        .filter(Boolean)
-        .join('\n\n');
+      ].filter(Boolean);
+
+      paaLines.push(questionLines.join('\n\n'));
     });
+
+    outputLines.push(paaLines.join(''));
   }
+
   return {
-    output: output.trim(),
+    output: outputLines.join('\n').trim(),
     references,
   };
 }

package/src/tools/search/rerankers.ts

@@ -1,12 +1,14 @@
-/* eslint-disable no-console */
 import axios from 'axios';
 import type * as t from './types';
+import { createDefaultLogger } from './utils';
 
 export abstract class BaseReranker {
   protected apiKey: string | undefined;
+  protected logger: t.Logger;
 
-  constructor() {
+  constructor(logger?: t.Logger) {
     // Each specific reranker will set its API key
+    this.logger = logger || createDefaultLogger();
   }
 
   abstract rerank(
@@ -25,16 +27,22 @@ export abstract class BaseReranker {
   }
 
   protected logDocumentSamples(documents: string[]): void {
-    console.log('Sample documents being sent to API:');
+    this.logger.debug('Sample documents being sent to API:');
     for (let i = 0; i < Math.min(3, documents.length); i++) {
-      console.log(`Document ${i}: ${documents[i].substring(0, 100)}...`);
+      this.logger.debug(`Document ${i}: ${documents[i].substring(0, 100)}...`);
     }
   }
 }
 
 export class JinaReranker extends BaseReranker {
-  constructor({ apiKey = process.env.JINA_API_KEY }: { apiKey?: string }) {
-    super();
+  constructor({
+    apiKey = process.env.JINA_API_KEY,
+    logger,
+  }: {
+    apiKey?: string;
+    logger?: t.Logger;
+  }) {
+    super(logger);
     this.apiKey = apiKey;
   }
 
@@ -43,11 +51,11 @@ export class JinaReranker extends BaseReranker {
     documents: string[],
     topK: number = 5
   ): Promise<t.Highlight[]> {
-    console.log(`Reranking ${documents.length} documents with Jina`);
+    this.logger.debug(`Reranking ${documents.length} documents with Jina`);
 
     try {
       if (this.apiKey == null || this.apiKey === '') {
-        console.warn('JINA_API_KEY is not set. Using default ranking.');
+        this.logger.warn('JINA_API_KEY is not set. Using default ranking.');
         return this.getDefaultRanking(documents, topK);
       }
 
@@ -73,14 +81,14 @@ export class JinaReranker extends BaseReranker {
       );
 
       // Log the response data structure
-      console.log('Jina API response structure:');
-      console.log('Model:', response.data?.model);
-      console.log('Usage:', response.data?.usage);
-      console.log('Results count:', response.data?.results.length);
+      this.logger.debug('Jina API response structure:');
+      this.logger.debug('Model:', response.data?.model);
+      this.logger.debug('Usage:', response.data?.usage);
+      this.logger.debug('Results count:', response.data?.results.length);
 
       // Log a sample of the results
       if ((response.data?.results.length ?? 0) > 0) {
-        console.log(
+        this.logger.debug(
           'Sample result:',
           JSON.stringify(response.data?.results[0], null, 2)
         );
@@ -108,13 +116,13 @@ export class JinaReranker extends BaseReranker {
           return { text, score };
         });
       } else {
-        console.warn(
+        this.logger.warn(
           'Unexpected response format from Jina API. Using default ranking.'
         );
         return this.getDefaultRanking(documents, topK);
       }
     } catch (error) {
-      console.error('Error using Jina reranker:', error);
+      this.logger.error('Error using Jina reranker:', error);
       // Fallback to default ranking on error
       return this.getDefaultRanking(documents, topK);
     }
@@ -122,8 +130,14 @@ export class JinaReranker extends BaseReranker {
 }
 
 export class CohereReranker extends BaseReranker {
-  constructor({ apiKey = process.env.COHERE_API_KEY }: { apiKey?: string }) {
-    super();
+  constructor({
+    apiKey = process.env.COHERE_API_KEY,
+    logger,
+  }: {
+    apiKey?: string;
+    logger?: t.Logger;
+  }) {
+    super(logger);
     this.apiKey = apiKey;
   }
 
@@ -132,11 +146,11 @@ export class CohereReranker extends BaseReranker {
     documents: string[],
     topK: number = 5
   ): Promise<t.Highlight[]> {
-    console.log(`Reranking ${documents.length} documents with Cohere`);
+    this.logger.debug(`Reranking ${documents.length} documents with Cohere`);
 
     try {
       if (this.apiKey == null || this.apiKey === '') {
-        console.warn('COHERE_API_KEY is not set. Using default ranking.');
+        this.logger.warn('COHERE_API_KEY is not set. Using default ranking.');
         return this.getDefaultRanking(documents, topK);
       }
 
@@ -161,14 +175,14 @@ export class CohereReranker extends BaseReranker {
       );
 
       // Log the response data structure
-      console.log('Cohere API response structure:');
-      console.log('ID:', response.data?.id);
-      console.log('Meta:', response.data?.meta);
-      console.log('Results count:', response.data?.results.length);
+      this.logger.debug('Cohere API response structure:');
+      this.logger.debug('ID:', response.data?.id);
+      this.logger.debug('Meta:', response.data?.meta);
+      this.logger.debug('Results count:', response.data?.results.length);
 
       // Log a sample of the results
       if ((response.data?.results.length ?? 0) > 0) {
-        console.log(
+        this.logger.debug(
           'Sample result:',
           JSON.stringify(response.data?.results[0], null, 2)
         );
@@ -182,13 +196,13 @@ export class CohereReranker extends BaseReranker {
           return { text, score };
         });
       } else {
-        console.warn(
+        this.logger.warn(
           'Unexpected response format from Cohere API. Using default ranking.'
         );
         return this.getDefaultRanking(documents, topK);
       }
     } catch (error) {
-      console.error('Error using Cohere reranker:', error);
+      this.logger.error('Error using Cohere reranker:', error);
       // Fallback to default ranking on error
       return this.getDefaultRanking(documents, topK);
     }
@@ -196,8 +210,8 @@ export class CohereReranker extends BaseReranker {
 }
 
 export class InfinityReranker extends BaseReranker {
-  constructor() {
-    super();
+  constructor(logger?: t.Logger) {
+    super(logger);
     // No API key needed for the placeholder implementation
   }
 
@@ -206,7 +220,7 @@ export class InfinityReranker extends BaseReranker {
     documents: string[],
     topK: number = 5
   ): Promise<t.Highlight[]> {
-    console.log(
+    this.logger.debug(
       `Reranking ${documents.length} documents with Infinity (placeholder)`
     );
     // This would be replaced with actual Infinity reranker implementation
@@ -221,24 +235,31 @@ export const createReranker = (config: {
   rerankerType: t.RerankerType;
   jinaApiKey?: string;
   cohereApiKey?: string;
+  logger?: t.Logger;
 }): BaseReranker | undefined => {
-  const { rerankerType, jinaApiKey, cohereApiKey } = config;
+  const { rerankerType, jinaApiKey, cohereApiKey, logger } = config;
+
+  // Create a default logger if none is provided
+  const defaultLogger = logger || createDefaultLogger();
 
   switch (rerankerType.toLowerCase()) {
   case 'jina':
-    return new JinaReranker({ apiKey: jinaApiKey });
+    return new JinaReranker({ apiKey: jinaApiKey, logger: defaultLogger });
   case 'cohere':
-    return new CohereReranker({ apiKey: cohereApiKey });
+    return new CohereReranker({
+      apiKey: cohereApiKey,
+      logger: defaultLogger,
+    });
   case 'infinity':
-    return new InfinityReranker();
+    return new InfinityReranker(defaultLogger);
   case 'none':
-    console.log('Skipping reranking as reranker is set to "none"');
+    defaultLogger.debug('Skipping reranking as reranker is set to "none"');
     return undefined;
   default:
-    console.warn(
+    defaultLogger.warn(
       `Unknown reranker type: ${rerankerType}. Defaulting to InfinityReranker.`
     );
-    return new JinaReranker({ apiKey: jinaApiKey });
+    return new JinaReranker({ apiKey: jinaApiKey, logger: defaultLogger });
   }
 };
 

package/src/tools/search/schema.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+
+export enum DATE_RANGE {
+  PAST_HOUR = 'h',
+  PAST_24_HOURS = 'd',
+  PAST_WEEK = 'w',
+  PAST_MONTH = 'm',
+  PAST_YEAR = 'y',
+}
+
+export const DEFAULT_QUERY_DESCRIPTION = `
+GUIDELINES:
+- Start broad, then narrow: Begin with key concepts, then refine with specifics
+- Think like sources: Use terminology experts would use in the field
+- Consider perspective: Frame queries from different viewpoints for better results
+- Quality over quantity: A precise 3-4 word query often beats lengthy sentences
+
+TECHNIQUES (combine for power searches):
+- EXACT PHRASES: Use quotes ("climate change report")
+- EXCLUDE TERMS: Use minus to remove unwanted results (-wikipedia)
+- SITE-SPECIFIC: Restrict to websites (site:edu research)
+- FILETYPE: Find specific documents (filetype:pdf study)
+- OR OPERATOR: Find alternatives (electric OR hybrid cars)
+- DATE RANGE: Recent information (data after:2020)
+- WILDCARDS: Use * for unknown terms (how to * bread)
+- SPECIFIC QUESTIONS: Use who/what/when/where/why/how
+- DOMAIN TERMS: Include technical terminology for specialized topics
+- CONCISE TERMS: Prioritize keywords over sentences
+`.trim();
+
+export const DEFAULT_COUNTRY_DESCRIPTION =
+  `Country code to localize search results.
+Use standard 2-letter country codes: "us", "uk", "ca", "de", "fr", "jp", "br", etc.
+Provide this when the search should return results specific to a particular country.
+Examples:
+- "us" for United States (default)
+- "de" for Germany
+- "in" for India
+`.trim();
+
+export const querySchema = z.string().describe(DEFAULT_QUERY_DESCRIPTION);
+export const dateSchema = z
+  .nativeEnum(DATE_RANGE)
+  .optional()
+  .describe('Date range for search results.');
+export const countrySchema = z
+  .string()
+  .optional()
+  .describe(DEFAULT_COUNTRY_DESCRIPTION);
+export const imagesSchema = z
+  .boolean()
+  .optional()
+  .describe('Whether to also run an image search.');
+
+export const videosSchema = z
+  .boolean()
+  .optional()
+  .describe('Whether to also run a video search.');
+
+export const newsSchema = z
+  .boolean()
+  .optional()
+  .describe('Whether to also run a news search.');