@librechat/agents 2.4.321 → 3.0.0-rc1

package/src/tools/search/tool.ts

@@ -1,88 +1,246 @@
-/* eslint-disable no-console */
 import { z } from 'zod';
 import { tool, DynamicStructuredTool } from '@langchain/core/tools';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type * as t from './types';
+import {
+  DATE_RANGE,
+  querySchema,
+  dateSchema,
+  countrySchema,
+  imagesSchema,
+  videosSchema,
+  newsSchema,
+} from './schema';
 import { createSearchAPI, createSourceProcessor } from './search';
 import { createFirecrawlScraper } from './firecrawl';
 import { expandHighlights } from './highlights';
 import { formatResultsForLLM } from './format';
+import { createDefaultLogger } from './utils';
 import { createReranker } from './rerankers';
 import { Constants } from '@/common';
 
-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();
-
-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();
+/**
+ * Executes parallel searches and merges the results
+ */
+async function executeParallelSearches({
+  searchAPI,
+  query,
+  date,
+  country,
+  safeSearch,
+  images,
+  videos,
+  news,
+  logger,
+}: {
+  searchAPI: ReturnType<typeof createSearchAPI>;
+  query: string;
+  date?: DATE_RANGE;
+  country?: string;
+  safeSearch: t.SearchToolConfig['safeSearch'];
+  images: boolean;
+  videos: boolean;
+  news: boolean;
+  logger: t.Logger;
+}): Promise<t.SearchResult> {
+  // Prepare all search tasks to run in parallel
+  const searchTasks: Promise<t.SearchResult>[] = [
+    // Main search
+    searchAPI.getSources({
+      query,
+      date,
+      country,
+      safeSearch,
+    }),
+  ];
+
+  if (images) {
+    searchTasks.push(
+      searchAPI
+        .getSources({
+          query,
+          date,
+          country,
+          safeSearch,
+          type: 'images',
+        })
+        .catch((error) => {
+          logger.error('Error fetching images:', error);
+          return {
+            success: false,
+            error: `Images search failed: ${error instanceof Error ? error.message : String(error)}`,
+          };
+        })
+    );
+  }
+  if (videos) {
+    searchTasks.push(
+      searchAPI
+        .getSources({
+          query,
+          date,
+          country,
+          safeSearch,
+          type: 'videos',
+        })
+        .catch((error) => {
+          logger.error('Error fetching videos:', error);
+          return {
+            success: false,
+            error: `Videos search failed: ${error instanceof Error ? error.message : String(error)}`,
+          };
+        })
+    );
+  }
+  if (news) {
+    searchTasks.push(
+      searchAPI
+        .getSources({
+          query,
+          date,
+          country,
+          safeSearch,
+          type: 'news',
+        })
+        .catch((error) => {
+          logger.error('Error fetching news:', error);
+          return {
+            success: false,
+            error: `News search failed: ${error instanceof Error ? error.message : String(error)}`,
+          };
+        })
+    );
+  }
+
+  // Run all searches in parallel
+  const results = await Promise.all(searchTasks);
+
+  // Get the main search result (first result)
+  const mainResult = results[0];
+  if (!mainResult.success) {
+    throw new Error(mainResult.error ?? 'Search failed');
+  }
+
+  // Merge additional results with the main results
+  const mergedResults = { ...mainResult.data };
+
+  // Convert existing news to topStories if present
+  if (mergedResults.news !== undefined && mergedResults.news.length > 0) {
+    const existingNewsAsTopStories = mergedResults.news
+      .filter((newsItem) => newsItem.link !== undefined && newsItem.link !== '')
+      .map((newsItem) => ({
+        title: newsItem.title ?? '',
+        link: newsItem.link ?? '',
+        source: newsItem.source ?? '',
+        date: newsItem.date ?? '',
+        imageUrl: newsItem.imageUrl ?? '',
+        processed: false,
+      }));
+    mergedResults.topStories = [
+      ...(mergedResults.topStories ?? []),
+      ...existingNewsAsTopStories,
+    ];
+    delete mergedResults.news;
+  }
+
+  results.slice(1).forEach((result) => {
+    if (result.success && result.data !== undefined) {
+      if (result.data.images !== undefined && result.data.images.length > 0) {
+        mergedResults.images = [
+          ...(mergedResults.images ?? []),
+          ...result.data.images,
+        ];
+      }
+      if (result.data.videos !== undefined && result.data.videos.length > 0) {
+        mergedResults.videos = [
+          ...(mergedResults.videos ?? []),
+          ...result.data.videos,
+        ];
+      }
+      if (result.data.news !== undefined && result.data.news.length > 0) {
+        const newsAsTopStories = result.data.news.map((newsItem) => ({
+          ...newsItem,
+          link: newsItem.link ?? '',
+        }));
+        mergedResults.topStories = [
+          ...(mergedResults.topStories ?? []),
+          ...newsAsTopStories,
+        ];
+      }
+    }
+  });
+
+  return { success: true, data: mergedResults };
+}
 
 function createSearchProcessor({
   searchAPI,
+  safeSearch,
   sourceProcessor,
   onGetHighlights,
+  logger,
 }: {
+  safeSearch: t.SearchToolConfig['safeSearch'];
   searchAPI: ReturnType<typeof createSearchAPI>;
   sourceProcessor: ReturnType<typeof createSourceProcessor>;
   onGetHighlights: t.SearchToolConfig['onGetHighlights'];
+  logger: t.Logger;
 }) {
   return async function ({
     query,
+    date,
     country,
     proMode = true,
     maxSources = 5,
     onSearchResults,
+    images = false,
+    videos = false,
+    news = false,
   }: {
     query: string;
     country?: string;
-    maxSources?: number;
+    date?: DATE_RANGE;
     proMode?: boolean;
+    maxSources?: number;
     onSearchResults: t.SearchToolConfig['onSearchResults'];
+    images?: boolean;
+    videos?: boolean;
+    news?: boolean;
   }): Promise<t.SearchResultData> {
     try {
-      const result = await searchAPI.getSources({ query, country });
-      onSearchResults?.(result);
+      // Execute parallel searches and merge results
+      const searchResult = await executeParallelSearches({
+        searchAPI,
+        query,
+        date,
+        country,
+        safeSearch,
+        images,
+        videos,
+        news,
+        logger,
+      });
 
-      if (!result.success) {
-        throw new Error(result.error ?? 'Search failed');
-      }
+      onSearchResults?.(searchResult);
 
       const processedSources = await sourceProcessor.processSources({
         query,
-        result,
+        news,
+        result: searchResult,
         proMode,
         onGetHighlights,
         numElements: maxSources,
       });
+
       return expandHighlights(processedSources);
     } catch (error) {
-      console.error('Error in search:', error);
+      logger.error('Error in search:', error);
       return {
         organic: [],
         topStories: [],
         images: [],
+        videos: [],
+        news: [],
         relatedSearches: [],
         error: error instanceof Error ? error.message : String(error),
       };
@@ -116,11 +274,15 @@ function createTool({
 }): DynamicStructuredTool<typeof schema> {
   return tool<typeof schema>(
     async (params, runnableConfig) => {
-      const { query, country: _c } = params;
+      const { query, date, country: _c, images, videos, news } = params;
       const country = typeof _c === 'string' && _c ? _c : undefined;
       const searchResult = await search({
         query,
+        date,
         country,
+        images,
+        videos,
+        news,
         onSearchResults: createOnSearchResults({
           runnableConfig,
           onSearchResults: _onSearchResults,
@@ -181,28 +343,36 @@ export const createSearchTool = (
     topResults = 5,
     strategies = ['no_extraction'],
     filterContent = true,
+    safeSearch = 1,
     firecrawlApiKey,
     firecrawlApiUrl,
-    firecrawlFormats = ['markdown', 'html'],
+    firecrawlOptions,
+    scraperTimeout,
     jinaApiKey,
     cohereApiKey,
     onSearchResults: _onSearchResults,
     onGetHighlights,
   } = config;
 
-  const querySchema = z.string().describe(DEFAULT_QUERY_DESCRIPTION);
+  const logger = config.logger || createDefaultLogger();
+
   const schemaObject: {
     query: z.ZodString;
+    date: z.ZodOptional<z.ZodNativeEnum<typeof DATE_RANGE>>;
     country?: z.ZodOptional<z.ZodString>;
+    images: z.ZodOptional<z.ZodBoolean>;
+    videos: z.ZodOptional<z.ZodBoolean>;
+    news: z.ZodOptional<z.ZodBoolean>;
   } = {
     query: querySchema,
+    date: dateSchema,
+    images: imagesSchema,
+    videos: videosSchema,
+    news: newsSchema,
   };
 
   if (searchProvider === 'serper') {
-    schemaObject.country = z
-      .string()
-      .optional()
-      .describe(DEFAULT_COUNTRY_DESCRIPTION);
+    schemaObject.country = countrySchema;
   }
 
   const toolSchema = z.object(schemaObject);
@@ -215,19 +385,22 @@ export const createSearchTool = (
   });
 
   const firecrawlScraper = createFirecrawlScraper({
+    ...firecrawlOptions,
     apiKey: firecrawlApiKey ?? process.env.FIRECRAWL_API_KEY,
     apiUrl: firecrawlApiUrl,
-    formats: firecrawlFormats,
+    timeout: scraperTimeout ?? firecrawlOptions?.timeout,
+    formats: firecrawlOptions?.formats ?? ['markdown', 'rawHtml'],
   });
 
   const selectedReranker = createReranker({
     rerankerType,
     jinaApiKey,
     cohereApiKey,
+    logger,
   });
 
   if (!selectedReranker) {
-    console.warn('No reranker selected. Using default ranking.');
+    logger.warn('No reranker selected. Using default ranking.');
   }
 
   const sourceProcessor = createSourceProcessor(
@@ -236,14 +409,17 @@ export const createSearchTool = (
       topResults,
       strategies,
       filterContent,
+      logger,
     },
     firecrawlScraper
   );
 
   const search = createSearchProcessor({
     searchAPI,
+    safeSearch,
     sourceProcessor,
     onGetHighlights,
+    logger,
   });
 
   return createTool({

package/src/tools/search/types.ts

@@ -1,6 +1,8 @@
 import { z } from 'zod';
+import type { Logger as WinstonLogger } from 'winston';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseReranker } from './rerankers';
+import { DATE_RANGE } from './schema';
 
 export type SearchProvider = 'serper' | 'searxng';
 export type RerankerType = 'infinity' | 'jina' | 'cohere' | 'none';
@@ -86,12 +88,13 @@ export interface ProcessSourcesConfig {
   strategies?: string[];
   filterContent?: boolean;
   reranker?: BaseReranker;
+  logger?: Logger;
 }
 
 export interface FirecrawlConfig {
   firecrawlApiKey?: string;
   firecrawlApiUrl?: string;
-  firecrawlFormats?: string[];
+  firecrawlOptions?: FirecrawlScraperConfig;
 }
 
 export interface ScraperContentResult {
@@ -135,13 +138,19 @@ export interface CohereRerankerResponse {
   };
 }
 
+export type SafeSearchLevel = 0 | 1 | 2;
+
+export type Logger = WinstonLogger;
 export interface SearchToolConfig
   extends SearchConfig,
     ProcessSourcesConfig,
     FirecrawlConfig {
+  logger?: Logger;
+  safeSearch?: SafeSearchLevel;
   jinaApiKey?: string;
   cohereApiKey?: string;
   rerankerType?: RerankerType;
+  scraperTimeout?: number;
   onSearchResults?: (
     results: SearchResult,
     runnableConfig?: RunnableConfig
@@ -161,15 +170,10 @@ export type UsedReferences = {
 }[];
 
 /** Firecrawl */
-
-export interface FirecrawlScrapeOptions {
-  formats?: string[];
-  includeTags?: string[];
-  excludeTags?: string[];
-  headers?: Record<string, string>;
-  waitFor?: number;
-  timeout?: number;
-}
+export type FirecrawlScrapeOptions = Omit<
+  FirecrawlScraperConfig,
+  'apiKey' | 'apiUrl' | 'logger'
+>;
 
 export interface ScrapeMetadata {
   // Core source information
@@ -251,12 +255,34 @@ export interface FirecrawlScraperConfig {
   apiUrl?: string;
   formats?: string[];
   timeout?: number;
+  logger?: Logger;
+  includeTags?: string[];
+  excludeTags?: string[];
+  waitFor?: number;
+  maxAge?: number;
+  mobile?: boolean;
+  skipTlsVerification?: boolean;
+  blockAds?: boolean;
+  removeBase64Images?: boolean;
+  parsePDF?: boolean;
+  storeInCache?: boolean;
+  zeroDataRetention?: boolean;
+  headers?: Record<string, string>;
+  location?: { country?: string; languages?: string[] };
+  onlyMainContent?: boolean;
+  changeTrackingOptions?: object;
 }
 
 export type GetSourcesParams = {
   query: string;
+  date?: DATE_RANGE;
   country?: string;
   numResults?: number;
+  safeSearch?: SearchToolConfig['safeSearch'];
+  images?: boolean;
+  videos?: boolean;
+  news?: boolean;
+  type?: 'search' | 'images' | 'videos' | 'news';
 };
 
 /** Serper API */
@@ -435,6 +461,13 @@ export interface SerperSearchInput {
    */
   autocorrect?: boolean;
   page?: number;
+  /**
+   * Date range for search results
+   * Options: "h" (past hour), "d" (past 24 hours), "w" (past week),
+   * "m" (past month), "y" (past year)
+   * `qdr:${DATE_RANGE}`
+   */
+  tbs?: string;
 }
 
 export type SerperResultData = {
@@ -558,12 +591,22 @@ export interface SearXNGResult {
   content?: string;
   publishedDate?: string;
   img_src?: string;
+  score?: number;
+  engine?: string;
+  category?: string;
+  thumbnail?: string;
+  priority?: string;
+  engines?: string[];
+  positions?: number[];
+  template?: string;
+  parsed_url?: string[];
 }
 
 export type ProcessSourcesFields = {
   result: SearchResult;
   numElements: number;
   query: string;
+  news: boolean;
   proMode: boolean;
   onGetHighlights: SearchToolConfig['onGetHighlights'];
 };
@@ -571,16 +614,28 @@ export type ProcessSourcesFields = {
 export type SearchToolSchema = z.ZodObject<
   {
     query: z.ZodString;
+    date: z.ZodOptional<z.ZodNativeEnum<typeof DATE_RANGE>>;
     country?: z.ZodOptional<z.ZodString>;
+    images: z.ZodOptional<z.ZodBoolean>;
+    videos: z.ZodOptional<z.ZodBoolean>;
+    news: z.ZodOptional<z.ZodBoolean>;
   },
   'strip',
   z.ZodTypeAny,
   {
     query: string;
+    date?: DATE_RANGE;
     country?: unknown;
+    images?: boolean;
+    videos?: boolean;
+    news?: boolean;
   },
   {
     query: string;
+    date?: DATE_RANGE;
     country?: unknown;
+    images?: boolean;
+    videos?: boolean;
+    news?: boolean;
   }
 >;

package/src/tools/search/utils.ts

@@ -1,9 +1,36 @@
 /* eslint-disable no-console */
+
 import type * as t from './types';
 
+/**
+ * Singleton instance of the default logger
+ */
+let defaultLoggerInstance: t.Logger | null = null;
+
+/**
+ * Creates a default logger that maps to console methods
+ * Uses a singleton pattern to avoid creating multiple instances
+ * @returns A default logger that implements the Logger interface
+ */
+export const createDefaultLogger = (): t.Logger => {
+  if (!defaultLoggerInstance) {
+    defaultLoggerInstance = {
+      error: console.error,
+      warn: console.warn,
+      info: console.info,
+      debug: console.debug,
+    } as t.Logger;
+  }
+  return defaultLoggerInstance;
+};
+
+export const fileExtRegex =
+  /\.(pdf|jpe?g|png|gif|svg|webp|bmp|ico|tiff?|avif|heic|doc[xm]?|xls[xm]?|ppt[xm]?|zip|rar|mp[34]|mov|avi|wav)(?:\?.*)?$/i;
+
 export const getDomainName = (
   link: string,
-  metadata?: t.ScrapeMetadata
+  metadata?: t.ScrapeMetadata,
+  logger?: t.Logger
 ): string | undefined => {
   try {
     const url = metadata?.sourceURL ?? metadata?.url ?? (link || '');
@@ -13,7 +40,11 @@ export const getDomainName = (
     }
   } catch (e) {
     // URL parsing failed
-    console.error('Error parsing URL:', e);
+    if (logger) {
+      logger.error('Error parsing URL:', e);
+    } else {
+      console.error('Error parsing URL:', e);
+    }
   }
 
   return;
@@ -21,9 +52,10 @@ export const getDomainName = (
 
 export function getAttribution(
   link: string,
-  metadata?: t.ScrapeMetadata
+  metadata?: t.ScrapeMetadata,
+  logger?: t.Logger
 ): string | undefined {
-  if (!metadata) return getDomainName(link, metadata);
+  if (!metadata) return getDomainName(link, metadata, logger);
 
   const twitterSite = metadata['twitter:site'];
   const twitterSiteFormatted =
@@ -43,5 +75,5 @@ export function getAttribution(
     return attribution;
   }
 
-  return getDomainName(link, metadata);
+  return getDomainName(link, metadata, logger);
 }