@illuma-ai/agents 1.4.0-alpha.6 → 1.5.0

package/src/tools/search/search.ts

@@ -2,6 +2,7 @@ import axios from 'axios';
 import { RecursiveCharacterTextSplitter } from '@langchain/textsplitters';
 import type * as t from './types';
 import { getAttribution, createDefaultLogger } from './utils';
+import { createTavilyAPI } from './tavily-search';
 import { BaseReranker } from './rerankers';
 
 const chunker = {
@@ -438,6 +439,9 @@ export const createSearchAPI = (
     serperApiKey,
     searxngInstanceUrl,
     searxngApiKey,
+    tavilyApiKey,
+    tavilySearchUrl,
+    tavilySearchOptions,
     domainBlocklist,
     countryBlocklist,
   } = config;
@@ -446,9 +450,11 @@ export const createSearchAPI = (
     return createSerperAPI(serperApiKey, domainBlocklist, countryBlocklist);
   } else if (searchProvider.toLowerCase() === 'searxng') {
     return createSearXNGAPI(searxngInstanceUrl, searxngApiKey);
+  } else if (searchProvider.toLowerCase() === 'tavily') {
+    return createTavilyAPI(tavilyApiKey, tavilySearchUrl, tavilySearchOptions);
   } else {
     throw new Error(
-      `Invalid search provider: ${searchProvider}. Must be 'serper' or 'searxng'`
+      `Invalid search provider: ${searchProvider}. Must be 'serper', 'searxng', or 'tavily'`
     );
   }
 };
@@ -494,9 +500,13 @@ export const createSourceProcessor = (
           const promise: Promise<t.ScrapeResult> = scraper
             .scrapeUrl(currentLink, {})
             .then(([url, response]) => {
+              /* metadata exists on Firecrawl/Serper responses but not on
+               * Tavily's. Read it via the scraper's extractMetadata abstraction
+               * to stay polymorphic across all scraper providers. */
+              const rawMeta = scraper.extractMetadata(response);
               const attribution = getAttribution(
                 url,
-                response.data?.metadata,
+                Object.keys(rawMeta).length > 0 ? rawMeta : undefined,
                 logger_
               );
               if (response.success && response.data) {

package/src/tools/search/serper-scraper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serper-scraper.js","sourceRoot":"","sources":["serper-scraper.ts"],"names":[],"mappings":"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"}

package/src/tools/search/tavily-scraper.ts

@@ -0,0 +1,235 @@
+import axios from 'axios';
+import type * as t from './types';
+import { createDefaultLogger } from './utils';
+
+const DEFAULT_BASIC_TIMEOUT = 15000;
+const DEFAULT_ADVANCED_TIMEOUT = 30000;
+const MAX_BATCH_SIZE = 20;
+
+const getDefaultTimeout = (extractDepth: 'basic' | 'advanced'): number =>
+  extractDepth === 'advanced'
+    ? DEFAULT_ADVANCED_TIMEOUT
+    : DEFAULT_BASIC_TIMEOUT;
+
+const normalizeUrlKey = (url: string): string => {
+  try {
+    const parsedUrl = new URL(url);
+    parsedUrl.hash = '';
+    if (parsedUrl.pathname.length > 1) {
+      parsedUrl.pathname = parsedUrl.pathname.replace(/\/+$/, '');
+    }
+    return parsedUrl.toString();
+  } catch {
+    return url;
+  }
+};
+
+const setUrlResult = (
+  map: Map<string, t.TavilyExtractResult>,
+  result: t.TavilyExtractResult
+): void => {
+  map.set(result.url, result);
+  const normalizedUrl = normalizeUrlKey(result.url);
+  if (!map.has(normalizedUrl)) {
+    map.set(normalizedUrl, result);
+  }
+};
+
+export class TavilyScraper implements t.BaseScraper {
+  private apiKey: string;
+  private apiUrl: string;
+  private timeout: number;
+  private payloadTimeout: number | undefined;
+  private logger: t.Logger;
+  private extractDepth: 'basic' | 'advanced';
+  private includeImages: boolean;
+  private includeFavicon: boolean;
+  private format: 'markdown' | 'text' | undefined;
+
+  constructor(config: t.TavilyScraperConfig = {}) {
+    this.apiKey = config.apiKey ?? process.env.TAVILY_API_KEY ?? '';
+    this.apiUrl =
+      config.apiUrl ??
+      process.env.TAVILY_EXTRACT_URL ??
+      'https://api.tavily.com/extract';
+    this.payloadTimeout = config.timeout;
+    this.extractDepth = config.extractDepth ?? 'basic';
+    this.timeout = config.timeout ?? getDefaultTimeout(this.extractDepth);
+    this.includeImages = config.includeImages ?? false;
+    this.includeFavicon = config.includeFavicon ?? false;
+    this.format = config.format;
+    this.logger = config.logger || createDefaultLogger();
+
+    if (!this.apiKey) {
+      this.logger.warn('TAVILY_API_KEY is not set. Scraping will not work.');
+    }
+  }
+
+  async scrapeUrl(
+    url: string,
+    options: t.TavilyScrapeOptions = {}
+  ): Promise<[string, t.TavilyScrapeResponse]> {
+    const results = await this.scrapeUrls([url], options);
+    return results[0];
+  }
+
+  async scrapeUrls(
+    urls: string[],
+    options: t.TavilyScrapeOptions = {}
+  ): Promise<Array<[string, t.TavilyScrapeResponse]>> {
+    if (!this.apiKey) {
+      return urls.map((url) => [
+        url,
+        { success: false, error: 'TAVILY_API_KEY is not set' },
+      ]);
+    }
+
+    const batches: string[][] = [];
+    for (let i = 0; i < urls.length; i += MAX_BATCH_SIZE) {
+      batches.push(urls.slice(i, i + MAX_BATCH_SIZE));
+    }
+
+    const allResults: Array<[string, t.TavilyScrapeResponse]> = [];
+
+    for (const batch of batches) {
+      const batchResults = await this.extractBatch(batch, options);
+      allResults.push(...batchResults);
+    }
+
+    return allResults;
+  }
+
+  private async extractBatch(
+    urls: string[],
+    options: t.TavilyScrapeOptions = {}
+  ): Promise<Array<[string, t.TavilyScrapeResponse]>> {
+    try {
+      const includeFavicon = options.includeFavicon ?? this.includeFavicon;
+      const format = options.format ?? this.format;
+      const extractDepth = options.extractDepth ?? this.extractDepth;
+      const payload: t.TavilyExtractPayload = {
+        urls,
+        extract_depth: extractDepth,
+        include_images: options.includeImages ?? this.includeImages,
+      };
+
+      if (includeFavicon) {
+        payload.include_favicon = true;
+      }
+      if (format != null) {
+        payload.format = format;
+      }
+
+      const effectiveTimeout =
+        options.timeout ??
+        this.payloadTimeout ??
+        (options.extractDepth != null
+          ? getDefaultTimeout(extractDepth)
+          : this.timeout);
+      const payloadTimeout = options.timeout ?? this.payloadTimeout;
+      if (payloadTimeout != null) {
+        payload.timeout = Math.min(Math.max(payloadTimeout / 1000, 1), 60);
+      }
+
+      const response = await axios.post<{
+        results?: t.TavilyExtractResult[];
+        failed_results?: t.TavilyExtractResult[];
+      }>(this.apiUrl, payload, {
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        timeout: effectiveTimeout,
+      });
+
+      const data = response.data;
+      const successMap = new Map<string, t.TavilyExtractResult>();
+      const failedMap = new Map<string, t.TavilyExtractResult>();
+
+      for (const result of data.results ?? []) {
+        setUrlResult(successMap, result);
+      }
+      for (const result of data.failed_results ?? []) {
+        setUrlResult(failedMap, result);
+      }
+
+      return urls.map((url): [string, t.TavilyScrapeResponse] => {
+        const success =
+          successMap.get(url) ?? successMap.get(normalizeUrlKey(url));
+        if (success && success.error == null) {
+          return [
+            url,
+            {
+              success: true,
+              data: {
+                rawContent: success.raw_content ?? '',
+                images: success.images ?? [],
+                favicon: success.favicon,
+              },
+            },
+          ];
+        }
+
+        const failed =
+          failedMap.get(url) ?? failedMap.get(normalizeUrlKey(url));
+        const error =
+          success?.error ??
+          failed?.error ??
+          'URL not found in Tavily Extract response';
+        return [url, { success: false, error }];
+      });
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      return urls.map((url) => [
+        url,
+        {
+          success: false,
+          error: `Tavily Extract API request failed: ${errorMessage}`,
+        },
+      ]);
+    }
+  }
+
+  extractContent(
+    response: t.TavilyScrapeResponse
+  ): [string, undefined | t.References] {
+    if (!response.success || !response.data) {
+      return ['', undefined];
+    }
+
+    const content = response.data.rawContent ?? '';
+    const images = response.data.images ?? [];
+
+    const references: t.References | undefined =
+      images.length > 0
+        ? {
+            links: [],
+            images: images.map((imageUrl) => ({ originalUrl: imageUrl })),
+            videos: [],
+          }
+        : undefined;
+
+    return [content, references];
+  }
+
+  extractMetadata(response: t.TavilyScrapeResponse): t.GenericScrapeMetadata {
+    if (!response.success || !response.data) {
+      return {};
+    }
+
+    const metadata: t.GenericScrapeMetadata = {
+      images_count: response.data.images?.length ?? 0,
+    };
+    if (response.data.favicon != null) {
+      metadata.favicon = response.data.favicon;
+    }
+    return metadata;
+  }
+}
+
+export const createTavilyScraper = (
+  config: t.TavilyScraperConfig = {}
+): TavilyScraper => {
+  return new TavilyScraper(config);
+};

package/src/tools/search/tavily-search.ts

@@ -0,0 +1,424 @@
+import axios from 'axios';
+import type * as t from './types';
+
+const DEFAULT_TAVILY_TIMEOUT = 15000;
+
+const TAVILY_COUNTRY_ALIASES: Record<string, string> = {
+  ba: 'bosnia and herzegovina',
+  cg: 'congo',
+  cz: 'czech republic',
+  gb: 'united kingdom',
+  mm: 'myanmar',
+  tr: 'turkey',
+  tt: 'trinidad and tobago',
+  uk: 'united kingdom',
+};
+
+const TAVILY_SUPPORTED_COUNTRIES = new Set([
+  'afghanistan',
+  'albania',
+  'algeria',
+  'andorra',
+  'angola',
+  'argentina',
+  'armenia',
+  'australia',
+  'austria',
+  'azerbaijan',
+  'bahamas',
+  'bahrain',
+  'bangladesh',
+  'barbados',
+  'belarus',
+  'belgium',
+  'belize',
+  'benin',
+  'bhutan',
+  'bolivia',
+  'bosnia and herzegovina',
+  'botswana',
+  'brazil',
+  'brunei',
+  'bulgaria',
+  'burkina faso',
+  'burundi',
+  'cambodia',
+  'cameroon',
+  'canada',
+  'cape verde',
+  'central african republic',
+  'chad',
+  'chile',
+  'china',
+  'colombia',
+  'comoros',
+  'congo',
+  'costa rica',
+  'croatia',
+  'cuba',
+  'cyprus',
+  'czech republic',
+  'denmark',
+  'djibouti',
+  'dominican republic',
+  'ecuador',
+  'egypt',
+  'el salvador',
+  'equatorial guinea',
+  'eritrea',
+  'estonia',
+  'ethiopia',
+  'fiji',
+  'finland',
+  'france',
+  'gabon',
+  'gambia',
+  'georgia',
+  'germany',
+  'ghana',
+  'greece',
+  'guatemala',
+  'guinea',
+  'haiti',
+  'honduras',
+  'hungary',
+  'iceland',
+  'india',
+  'indonesia',
+  'iran',
+  'iraq',
+  'ireland',
+  'israel',
+  'italy',
+  'jamaica',
+  'japan',
+  'jordan',
+  'kazakhstan',
+  'kenya',
+  'kuwait',
+  'kyrgyzstan',
+  'latvia',
+  'lebanon',
+  'lesotho',
+  'liberia',
+  'libya',
+  'liechtenstein',
+  'lithuania',
+  'luxembourg',
+  'madagascar',
+  'malawi',
+  'malaysia',
+  'maldives',
+  'mali',
+  'malta',
+  'mauritania',
+  'mauritius',
+  'mexico',
+  'moldova',
+  'monaco',
+  'mongolia',
+  'montenegro',
+  'morocco',
+  'mozambique',
+  'myanmar',
+  'namibia',
+  'nepal',
+  'netherlands',
+  'new zealand',
+  'nicaragua',
+  'niger',
+  'nigeria',
+  'north korea',
+  'north macedonia',
+  'norway',
+  'oman',
+  'pakistan',
+  'panama',
+  'papua new guinea',
+  'paraguay',
+  'peru',
+  'philippines',
+  'poland',
+  'portugal',
+  'qatar',
+  'romania',
+  'russia',
+  'rwanda',
+  'saudi arabia',
+  'senegal',
+  'serbia',
+  'singapore',
+  'slovakia',
+  'slovenia',
+  'somalia',
+  'south africa',
+  'south korea',
+  'south sudan',
+  'spain',
+  'sri lanka',
+  'sudan',
+  'sweden',
+  'switzerland',
+  'syria',
+  'taiwan',
+  'tajikistan',
+  'tanzania',
+  'thailand',
+  'togo',
+  'trinidad and tobago',
+  'tunisia',
+  'turkey',
+  'turkmenistan',
+  'uganda',
+  'ukraine',
+  'united arab emirates',
+  'united kingdom',
+  'united states',
+  'uruguay',
+  'uzbekistan',
+  'venezuela',
+  'vietnam',
+  'yemen',
+  'zambia',
+  'zimbabwe',
+]);
+
+const TAVILY_REGION_NAMES = new Intl.DisplayNames(['en'], {
+  type: 'region',
+});
+
+const normalizeTavilyCountryName = (country: string): string =>
+  country
+    .toLowerCase()
+    .replace(/\s*\([^)]*\)/g, '')
+    .replace(/\s*&\s*/g, ' and ')
+    .normalize('NFD')
+    .replace(/\p{Diacritic}/gu, '');
+
+const normalizeTavilyCountry = (country?: string): string | undefined => {
+  const normalizedCountry = country?.trim().toLowerCase();
+  if (normalizedCountry == null || normalizedCountry === '') {
+    return undefined;
+  }
+
+  const countryAlias = TAVILY_COUNTRY_ALIASES[normalizedCountry];
+  if (countryAlias != null) {
+    return TAVILY_SUPPORTED_COUNTRIES.has(countryAlias)
+      ? countryAlias
+      : undefined;
+  }
+
+  if (/^[a-z]{2}$/.test(normalizedCountry)) {
+    const regionName = TAVILY_REGION_NAMES.of(normalizedCountry.toUpperCase());
+    if (regionName == null) {
+      return undefined;
+    }
+    const countryName = normalizeTavilyCountryName(regionName);
+    return TAVILY_SUPPORTED_COUNTRIES.has(countryName)
+      ? countryName
+      : undefined;
+  }
+
+  const countryName = normalizeTavilyCountryName(normalizedCountry);
+  return TAVILY_SUPPORTED_COUNTRIES.has(countryName) ? countryName : undefined;
+};
+
+const normalizeTavilyTimeRange = (
+  timeRange?: t.TavilyTimeRangeInput
+): t.TavilyTimeRange | undefined => {
+  switch (timeRange) {
+    case 'h':
+    case 'd':
+      return 'day';
+    case 'w':
+      return 'week';
+    case 'm':
+      return 'month';
+    case 'y':
+      return 'year';
+    case 'day':
+    case 'week':
+    case 'month':
+    case 'year':
+      return timeRange;
+    default:
+      return undefined;
+  }
+};
+
+const getHostname = (link: string): string => {
+  try {
+    return new URL(link).hostname;
+  } catch {
+    return link;
+  }
+};
+
+export const createTavilyAPI = (
+  apiKey?: string,
+  apiUrl?: string,
+  options?: t.TavilySearchOptions
+): {
+  getSources: (params: t.GetSourcesParams) => Promise<t.SearchResult>;
+} => {
+  const config = {
+    apiKey: apiKey ?? process.env.TAVILY_API_KEY,
+    apiUrl:
+      apiUrl ??
+      process.env.TAVILY_SEARCH_URL ??
+      'https://api.tavily.com/search',
+    timeout: options?.timeout ?? DEFAULT_TAVILY_TIMEOUT,
+  };
+
+  if (config.apiKey == null || config.apiKey === '') {
+    throw new Error('TAVILY_API_KEY is required for Tavily API');
+  }
+
+  const getSources = async ({
+    query,
+    date,
+    country,
+    numResults = 8,
+    type,
+    news,
+  }: t.GetSourcesParams): Promise<t.SearchResult> => {
+    if (!query.trim()) {
+      return { success: false, error: 'Query cannot be empty' };
+    }
+
+    try {
+      const timeRange =
+        normalizeTavilyTimeRange(options?.timeRange) ??
+        (date != null ? (normalizeTavilyTimeRange(date) ?? 'day') : undefined);
+      const topic =
+        news === true || type === 'news'
+          ? 'news'
+          : (options?.topic ?? 'general');
+      const maxResults = options?.maxResults ?? numResults;
+      const searchDepth = options?.searchDepth ?? 'basic';
+
+      const payload: t.TavilySearchPayload = {
+        query,
+        search_depth: searchDepth,
+        topic,
+        max_results: Math.min(Math.max(1, maxResults), 20),
+      };
+
+      if (
+        options?.safeSearch != null &&
+        searchDepth !== 'fast' &&
+        searchDepth !== 'ultra-fast'
+      ) {
+        payload.safe_search = options.safeSearch;
+      }
+      if (timeRange != null) {
+        payload.time_range = timeRange;
+      }
+      const tavilyCountry =
+        topic === 'general' ? normalizeTavilyCountry(country) : undefined;
+      if (tavilyCountry != null) {
+        payload.country = tavilyCountry;
+      }
+      if (type === 'images' || options?.includeImages) {
+        payload.include_images = true;
+      }
+      if (options?.includeAnswer != null) {
+        payload.include_answer = options.includeAnswer;
+      }
+      if (options?.includeRawContent != null) {
+        payload.include_raw_content = options.includeRawContent;
+      }
+      if (
+        options?.includeDomains != null &&
+        options.includeDomains.length > 0
+      ) {
+        payload.include_domains = options.includeDomains;
+      }
+      if (
+        options?.excludeDomains != null &&
+        options.excludeDomains.length > 0
+      ) {
+        payload.exclude_domains = options.excludeDomains;
+      }
+      if (options?.includeImageDescriptions != null) {
+        payload.include_image_descriptions = options.includeImageDescriptions;
+      }
+      if (options?.includeFavicon != null) {
+        payload.include_favicon = options.includeFavicon;
+      }
+      if (options?.chunksPerSource != null && searchDepth === 'advanced') {
+        payload.chunks_per_source = options.chunksPerSource;
+      }
+
+      const response = await axios.post<t.TavilySearchResponse>(
+        config.apiUrl,
+        payload,
+        {
+          headers: {
+            Authorization: `Bearer ${config.apiKey}`,
+            'Content-Type': 'application/json',
+          },
+          timeout: config.timeout,
+        }
+      );
+
+      const data = response.data;
+
+      const organicResults: t.OrganicResult[] = (data.results ?? []).map(
+        (result: t.TavilySearchResult) => ({
+          title: result.title ?? '',
+          link: result.url ?? '',
+          snippet: result.content ?? '',
+          date: result.published_date,
+        })
+      );
+
+      const imageResults: t.ImageResult[] = Array.isArray(data.images)
+        ? data.images.slice(0, 6).reduce<t.ImageResult[]>((acc, image) => {
+            const imageUrl = typeof image === 'string' ? image : image.url;
+            if (imageUrl == null || imageUrl === '') {
+              return acc;
+            }
+            acc.push({
+              imageUrl,
+              title: typeof image === 'string' ? undefined : image.description,
+              position: acc.length + 1,
+            });
+            return acc;
+          }, [])
+        : [];
+
+      const newsResults: t.NewsResult[] =
+        topic === 'news'
+          ? organicResults.map((r) => ({
+              title: r.title,
+              link: r.link,
+              snippet: r.snippet,
+              date: r.date,
+              source: getHostname(r.link),
+            }))
+          : [];
+
+      const results: t.SearchResultData = {
+        organic: organicResults,
+        images: imageResults,
+        topStories: [],
+        videos: [],
+        news: newsResults,
+        answerBox: data.answer != null ? { snippet: data.answer } : undefined,
+        relatedSearches: [],
+      };
+
+      return { success: true, data: results };
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      return {
+        success: false,
+        error: `Tavily API request failed: ${errorMessage}`,
+      };
+    }
+  };
+
+  return { getSources };
+};