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

package/src/tools/search/tool.ts

@@ -12,6 +12,7 @@ import {
 } from './schema';
 import { createSearchAPI, createSourceProcessor } from './search';
 import { createSerperScraper } from './serper-scraper';
+import { createTavilyScraper } from './tavily-scraper';
 import { createFirecrawlScraper } from './firecrawl';
 import { expandHighlights } from './highlights';
 import { formatResultsForLLM } from './format';
@@ -309,12 +310,16 @@ async function executeParallelSearches({
 function createSearchProcessor({
   searchAPI,
   safeSearch,
+  supportsVideos,
   sourceProcessor,
   scraper,
   onGetHighlights,
   logger,
 }: {
   safeSearch: t.SearchToolConfig['safeSearch'];
+  /* Tavily search API does not return videos. Other providers (Serper)
+   * do — this flag short-circuits the videos request when unsupported. */
+  supportsVideos: boolean;
   searchAPI: ReturnType<typeof createSearchAPI>;
   sourceProcessor: ReturnType<typeof createSourceProcessor>;
   scraper: t.BaseScraper;
@@ -366,7 +371,7 @@ function createSearchProcessor({
           country,
           safeSearch,
           images,
-          videos,
+          videos: supportsVideos && videos,
           news,
           logger,
         });
@@ -549,6 +554,10 @@ export const createSearchTool = (
     serperApiKey,
     searxngInstanceUrl,
     searxngApiKey,
+    tavilyApiKey,
+    tavilySearchUrl,
+    tavilyExtractUrl,
+    tavilySearchOptions,
     domainBlocklist,
     countryBlocklist,
     rerankerType = 'cohere',
@@ -562,6 +571,7 @@ export const createSearchTool = (
     firecrawlVersion,
     firecrawlOptions,
     serperScraperOptions,
+    tavilyScraperOptions,
     scraperTimeout,
     jinaApiKey,
     jinaApiUrl,
@@ -571,6 +581,15 @@ export const createSearchTool = (
   } = config;
 
   const logger = config.logger || createDefaultLogger();
+  /* Tavily search API exposes a `safe_search` boolean derived from the
+   * tool's existing safeSearch level (0 = off, ≥1 = on). Bridge the two. */
+  const effectiveTavilySearchOptions =
+    searchProvider === 'tavily' && config.safeSearch != null
+      ? {
+        ...tavilySearchOptions,
+        safeSearch: config.safeSearch !== 0,
+      }
+      : tavilySearchOptions;
 
   const schemaProperties: Record<string, unknown> = {
     query: querySchema,
@@ -580,7 +599,7 @@ export const createSearchTool = (
     news: newsSchema,
   };
 
-  if (searchProvider === 'serper') {
+  if (searchProvider === 'serper' || searchProvider === 'tavily') {
     schemaProperties.country = countrySchema;
   }
 
@@ -595,6 +614,9 @@ export const createSearchTool = (
     serperApiKey,
     searxngInstanceUrl,
     searxngApiKey,
+    tavilyApiKey,
+    tavilySearchUrl,
+    tavilySearchOptions: effectiveTavilySearchOptions,
     domainBlocklist,
     countryBlocklist,
   });
@@ -609,6 +631,17 @@ export const createSearchTool = (
       timeout: scraperTimeout ?? serperScraperOptions?.timeout,
       logger,
     });
+  } else if (scraperProvider === 'tavily') {
+    scraperInstance = createTavilyScraper({
+      ...tavilyScraperOptions,
+      apiKey:
+        tavilyScraperOptions?.apiKey ??
+        tavilyApiKey ??
+        process.env.TAVILY_API_KEY,
+      apiUrl: tavilyScraperOptions?.apiUrl ?? tavilyExtractUrl,
+      timeout: scraperTimeout ?? tavilyScraperOptions?.timeout,
+      logger,
+    });
   } else {
     scraperInstance = createFirecrawlScraper({
       ...firecrawlOptions,
@@ -647,6 +680,7 @@ export const createSearchTool = (
   const search = createSearchProcessor({
     searchAPI,
     safeSearch,
+    supportsVideos: searchProvider !== 'tavily',
     sourceProcessor,
     scraper: scraperInstance,
     onGetHighlights,

package/src/tools/search/types.ts

@@ -3,8 +3,8 @@ import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseReranker } from './rerankers';
 import { DATE_RANGE } from './schema';
 
-export type SearchProvider = 'serper' | 'searxng';
-export type ScraperProvider = 'firecrawl' | 'serper';
+export type SearchProvider = 'serper' | 'searxng' | 'tavily';
+export type ScraperProvider = 'firecrawl' | 'serper' | 'tavily';
 export type RerankerType = 'infinity' | 'jina' | 'cohere' | 'none';
 
 export interface Highlight {
@@ -62,11 +62,59 @@ export interface Source {
   date?: string;
 }
 
+export type TavilyTimeRange = 'day' | 'week' | 'month' | 'year';
+export type TavilyTimeRangeInput =
+  | TavilyTimeRange
+  | 'h'
+  | 'd'
+  | 'w'
+  | 'm'
+  | 'y';
+
+export interface TavilySearchOptions {
+  searchDepth?: 'basic' | 'advanced' | 'fast' | 'ultra-fast';
+  maxResults?: number;
+  includeImages?: boolean;
+  includeAnswer?: boolean | 'basic' | 'advanced';
+  includeRawContent?: boolean | 'markdown' | 'text';
+  includeDomains?: string[];
+  excludeDomains?: string[];
+  topic?: 'general' | 'news' | 'finance';
+  timeRange?: TavilyTimeRangeInput;
+  includeImageDescriptions?: boolean;
+  includeFavicon?: boolean;
+  chunksPerSource?: number;
+  safeSearch?: boolean;
+  timeout?: number;
+}
+
+export interface TavilySearchPayload {
+  query: string;
+  search_depth: NonNullable<TavilySearchOptions['searchDepth']>;
+  topic: NonNullable<TavilySearchOptions['topic']>;
+  max_results: number;
+  safe_search?: boolean;
+  time_range?: TavilyTimeRange;
+  country?: string;
+  include_images?: boolean;
+  include_answer?: NonNullable<TavilySearchOptions['includeAnswer']>;
+  include_raw_content?: NonNullable<TavilySearchOptions['includeRawContent']>;
+  include_domains?: string[];
+  exclude_domains?: string[];
+  include_image_descriptions?: boolean;
+  include_favicon?: boolean;
+  chunks_per_source?: number;
+}
+
 export interface SearchConfig {
   searchProvider?: SearchProvider;
   serperApiKey?: string;
   searxngInstanceUrl?: string;
   searxngApiKey?: string;
+  tavilyApiKey?: string;
+  tavilySearchUrl?: string;
+  tavilyExtractUrl?: string;
+  tavilySearchOptions?: TavilySearchOptions;
   /** Domains to exclude from search results (e.g., 'reddit.com', 'twitter.com').
    *  Appended as -site: operators to the search query. */
   domainBlocklist?: string[];
@@ -112,6 +160,17 @@ export interface SerperScraperConfig {
   includeMarkdown?: boolean;
 }
 
+export interface TavilyScraperConfig {
+  apiKey?: string;
+  apiUrl?: string;
+  timeout?: number;
+  logger?: Logger;
+  extractDepth?: 'basic' | 'advanced';
+  includeImages?: boolean;
+  includeFavicon?: boolean;
+  format?: 'markdown' | 'text';
+}
+
 export interface ScraperContentResult {
   content: string;
 }
@@ -160,6 +219,7 @@ export interface SearchToolConfig
   extends SearchConfig,
     ProcessSourcesConfig,
     FirecrawlConfig {
+  tavilyScraperOptions?: TavilyScraperConfig;
   logger?: Logger;
   safeSearch?: SafeSearchLevel;
   jinaApiKey?: string;
@@ -187,20 +247,27 @@ export type UsedReferences = {
   reference: MediaReference;
 }[];
 
+export type AnyScraperResponse =
+  | FirecrawlScrapeResponse
+  | SerperScrapeResponse
+  | TavilyScrapeResponse;
+
 /** Base Scraper Interface */
 export interface BaseScraper {
   scrapeUrl(
     url: string,
     options?: unknown
-  ): Promise<[string, FirecrawlScrapeResponse | SerperScrapeResponse]>;
+  ): Promise<[string, AnyScraperResponse]>;
+  scrapeUrls?(
+    urls: string[],
+    options?: unknown
+  ): Promise<Array<[string, AnyScraperResponse]>>;
   extractContent(
-    response: FirecrawlScrapeResponse | SerperScrapeResponse
+    response: AnyScraperResponse
   ): [string, undefined | References];
   extractMetadata(
-    response: FirecrawlScrapeResponse | SerperScrapeResponse
-  ):
-    | ScrapeMetadata
-    | Record<string, string | number | boolean | null | undefined>;
+    response: AnyScraperResponse
+  ): ScrapeMetadata | GenericScrapeMetadata;
 }
 
 /** Firecrawl */
@@ -214,6 +281,25 @@ export type SerperScrapeOptions = Omit<
   'apiKey' | 'apiUrl' | 'logger'
 >;
 
+export type TavilyScrapeOptions = Omit<
+  TavilyScraperConfig,
+  'apiKey' | 'apiUrl' | 'logger'
+>;
+
+export interface TavilyExtractPayload {
+  urls: string[];
+  extract_depth: NonNullable<TavilyScraperConfig['extractDepth']>;
+  include_images: boolean;
+  include_favicon?: boolean;
+  format?: NonNullable<TavilyScraperConfig['format']>;
+  timeout?: number;
+}
+
+export type GenericScrapeMetadata = Record<
+  string,
+  string | number | boolean | null | undefined
+>;
+
 export interface ScrapeMetadata {
   // Core source information
   sourceURL?: string;
@@ -300,6 +386,45 @@ export interface SerperScrapeResponse {
   error?: string;
 }
 
+export interface TavilyScrapeResponse {
+  success: boolean;
+  data?: {
+    rawContent?: string;
+    images?: string[];
+    favicon?: string;
+  };
+  error?: string;
+}
+
+export interface TavilySearchResult {
+  title?: string;
+  url?: string;
+  content?: string;
+  score?: number;
+  published_date?: string;
+}
+
+export type TavilyImageResult =
+  | string
+  | {
+      url?: string;
+      description?: string;
+    };
+
+export interface TavilySearchResponse {
+  answer?: string;
+  images?: TavilyImageResult[];
+  results?: TavilySearchResult[];
+}
+
+export interface TavilyExtractResult {
+  url: string;
+  raw_content?: string;
+  images?: string[];
+  favicon?: string;
+  error?: string;
+}
+
 export interface FirecrawlScraperConfig {
   apiKey?: string;
   apiUrl?: string;

package/src/tools/search/utils.ts

@@ -29,11 +29,18 @@ export const fileExtRegex =
 
 export const getDomainName = (
   link: string,
-  metadata?: t.ScrapeMetadata,
+  metadata?: t.ScrapeMetadata | t.GenericScrapeMetadata,
   logger?: t.Logger
 ): string | undefined => {
   try {
-    const url = metadata?.sourceURL ?? metadata?.url ?? (link || '');
+    const sourceUrl = metadata?.sourceURL;
+    const metadataUrl = metadata?.url;
+    const url =
+      typeof sourceUrl === 'string'
+        ? sourceUrl
+        : typeof metadataUrl === 'string'
+          ? metadataUrl
+          : link || '';
     const domain = new URL(url).hostname.replace(/^www\./, '');
     if (domain) {
       return domain;
@@ -52,7 +59,7 @@ export const getDomainName = (
 
 export function getAttribution(
   link: string,
-  metadata?: t.ScrapeMetadata,
+  metadata?: t.ScrapeMetadata | t.GenericScrapeMetadata,
   logger?: t.Logger
 ): string | undefined {
   if (!metadata) return getDomainName(link, metadata, logger);
@@ -60,16 +67,17 @@ export function getAttribution(
   const twitterSite = metadata['twitter:site'];
   const twitterSiteFormatted =
     typeof twitterSite === 'string' ? twitterSite.replace(/^@/, '') : undefined;
+  const title = metadata.title;
 
   const possibleAttributions = [
     metadata.ogSiteName,
     metadata['og:site_name'],
-    metadata.title?.split('|').pop()?.trim(),
+    typeof title === 'string' ? title.split('|').pop()?.trim() : undefined,
     twitterSiteFormatted,
   ];
 
   const attribution = possibleAttributions.find(
-    (attr) => attr != null && typeof attr === 'string' && attr.trim() !== ''
+    (attr): attr is string => typeof attr === 'string' && attr.trim() !== ''
   );
   if (attribution != null) {
     return attribution;

package/src/tools/skillCatalog.ts

@@ -0,0 +1,126 @@
+// src/tools/skillCatalog.ts
+import type { SkillCatalogEntry } from '@/types';
+
+const HEADER = '## Available Skills';
+const DEFAULT_CONTEXT_WINDOW_TOKENS = 200_000;
+const DEFAULT_BUDGET_PERCENT = 0.01;
+const DEFAULT_MAX_ENTRY_CHARS = 250;
+const DEFAULT_MIN_DESC_LENGTH = 20;
+const DEFAULT_CHARS_PER_TOKEN = 4;
+
+export type SkillCatalogOptions = {
+  /** Total context window in tokens. Default: 200_000 */
+  contextWindowTokens?: number;
+  /** Fraction of context budget for catalog. Default: 0.01 (1%) */
+  budgetPercent?: number;
+  /** Max chars per entry description. Default: 250 */
+  maxEntryChars?: number;
+  /** Descriptions below this length trigger names-only fallback. Default: 20 */
+  minDescLength?: number;
+  /** Approximate chars per token for budget calculation. Default: 4 */
+  charsPerToken?: number;
+};
+
+/**
+ * Formats a skill catalog for injection into agent context.
+ * Uses a truncation ladder: full descriptions, proportional truncation, names-only.
+ * Returns empty string for empty input.
+ */
+export function formatSkillCatalog(
+  skills: SkillCatalogEntry[],
+  opts?: SkillCatalogOptions
+): string {
+  if (skills.length === 0) return '';
+
+  const contextWindowTokens =
+    opts?.contextWindowTokens ?? DEFAULT_CONTEXT_WINDOW_TOKENS;
+  const budgetPercent = opts?.budgetPercent ?? DEFAULT_BUDGET_PERCENT;
+  const maxEntryChars = Math.max(
+    1,
+    opts?.maxEntryChars ?? DEFAULT_MAX_ENTRY_CHARS
+  );
+  const minDescLength = opts?.minDescLength ?? DEFAULT_MIN_DESC_LENGTH;
+  const charsPerToken = opts?.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
+
+  const budgetChars = Math.floor(
+    contextWindowTokens * budgetPercent * charsPerToken
+  );
+
+  const capped = skills.map((s) => ({
+    name: s.name,
+    description:
+      s.description.length > maxEntryChars
+        ? s.description.slice(0, maxEntryChars - 1) + '\u2026'
+        : s.description,
+  }));
+
+  const fullOutput = formatEntries(capped);
+  if (fullOutput.length <= budgetChars) return fullOutput;
+
+  const headerLen = HEADER.length + 2;
+  const newlineChars = capped.length > 1 ? capped.length - 1 : 0;
+  const availableChars = budgetChars - headerLen - newlineChars;
+  const perEntryOverhead = 4;
+  const nameCharsTotal = capped.reduce(
+    (sum, s) => sum + s.name.length + perEntryOverhead,
+    0
+  );
+  const availableForDescs = availableChars - nameCharsTotal;
+
+  if (availableForDescs <= 0) {
+    return fitNamesOnly(capped, budgetChars);
+  }
+
+  const maxDescPerEntry = Math.floor(availableForDescs / capped.length);
+
+  if (maxDescPerEntry < minDescLength) {
+    return fitNamesOnly(capped, budgetChars);
+  }
+
+  const truncated = capped.map((s) => ({
+    name: s.name,
+    description:
+      s.description.length > maxDescPerEntry
+        ? s.description.slice(0, maxDescPerEntry - 1) + '\u2026'
+        : s.description,
+  }));
+
+  const result = formatEntries(truncated);
+  if (result.length <= budgetChars) return result;
+  return fitNamesOnly(capped, budgetChars);
+}
+
+function formatEntries(
+  entries: { name: string; description: string }[]
+): string {
+  const lines = entries.map((e) =>
+    e.description ? `- ${e.name}: ${e.description}` : `- ${e.name}`
+  );
+  return `${HEADER}\n\n${lines.join('\n')}`;
+}
+
+/** Names-only fallback that drops trailing entries if the list still exceeds budget. */
+function fitNamesOnly(
+  entries: { name: string }[],
+  budgetChars: number
+): string {
+  // Format: "HEADER\n\n- name1\n- name2\n..."
+  // Running sum avoids O(n²) repeated string construction.
+  const prefix = HEADER.length + 2; // "HEADER\n\n"
+  const entryOverhead = 2; // "- "
+  let total = prefix;
+  let fitCount = 0;
+
+  for (let i = 0; i < entries.length; i++) {
+    const added = (i > 0 ? 1 : 0) + entryOverhead + entries[i].name.length;
+    if (total + added > budgetChars) break;
+    total += added;
+    fitCount = i + 1;
+  }
+
+  if (fitCount === 0) return '';
+  const namesOnly = entries
+    .slice(0, fitCount)
+    .map((s) => ({ name: s.name, description: '' }));
+  return formatEntries(namesOnly);
+}