@librechat/agents 2.4.317 → 2.4.318

package/src/tools/search/types.ts

@@ -4,72 +4,41 @@ import type { BaseReranker } from './rerankers';
 export type SearchProvider = 'serper' | 'searxng';
 export type RerankerType = 'infinity' | 'jina' | 'cohere' | 'none';
 
-export interface OrganicResult {
-  position?: number;
-  title?: string;
-  link: string;
-  snippet?: string;
-  date?: string;
-}
-
-export interface TopStoryResult {
-  title?: string;
-  link: string;
-  source?: string;
-  date?: string;
-  imageUrl?: string;
-}
-
-export interface ImageResult {
-  title?: string;
-  imageUrl?: string;
-}
-
-export interface KnowledgeGraphResult {
-  title?: string;
-  type?: string;
-  description?: string;
-  attributes?: Record<string, string>;
-  imageUrl?: string;
-}
-
-export interface AnswerBoxResult {
-  title?: string;
-  answer?: string;
-  snippet?: string;
-  date?: string;
-}
-
-export interface PeopleAlsoAskResult {
-  question?: string;
-  answer?: string;
-}
-
 export interface Highlight {
   score: number;
   text: string;
+  references?: UsedReferences;
 }
 
-export interface ValidSource {
-  link: string;
-  position?: number;
-  title?: string;
-  snippet?: string;
-  date?: string;
+export type ProcessedSource = {
   content?: string;
   attribution?: string;
+  references?: References;
   highlights?: Highlight[];
-}
+};
+
+export type ProcessedOrganic = OrganicResult & ProcessedSource;
+export type ProcessedTopStory = TopStoryResult & ProcessedSource;
+export type ValidSource = ProcessedOrganic | ProcessedTopStory;
 
+export type ResultReference = {
+  link: string;
+  title?: string;
+  attribution?: string;
+};
 export interface SearchResultData {
-  organic?: ValidSource[];
-  topStories?: ValidSource[];
+  organic?: ProcessedOrganic[];
+  topStories?: ProcessedTopStory[];
   images?: ImageResult[];
+  videos?: VideoResult[];
+  places?: PlaceResult[];
+  news?: NewsResult[];
+  shopping?: ShoppingResult[];
   knowledgeGraph?: KnowledgeGraphResult;
   answerBox?: AnswerBoxResult;
   peopleAlsoAsk?: PeopleAlsoAskResult[];
-  relatedSearches?: string[];
-  suggestions?: string[];
+  relatedSearches?: Array<{ query: string }>;
+  references?: ResultReference[];
   error?: string;
 }
 
@@ -94,11 +63,17 @@ export interface SearchConfig {
   searxngApiKey?: string;
 }
 
+export type References = {
+  links: MediaReference[];
+  images: MediaReference[];
+  videos: MediaReference[];
+};
 export interface ScrapeResult {
   url: string;
   error?: boolean;
   content: string;
   attribution?: string;
+  references?: References;
   highlights?: Highlight[];
 }
 
@@ -177,3 +152,406 @@ export interface SearchToolConfig
     runnableConfig?: RunnableConfig
   ) => void;
 }
+export interface MediaReference {
+  originalUrl: string;
+  title?: string;
+  text?: string;
+}
+
+export type UsedReferences = {
+  type: 'link' | 'image' | 'video';
+  originalIndex: number;
+  reference: MediaReference;
+}[];
+
+/** Firecrawl */
+
+export interface FirecrawlScrapeOptions {
+  formats?: string[];
+  includeTags?: string[];
+  excludeTags?: string[];
+  headers?: Record<string, string>;
+  waitFor?: number;
+  timeout?: number;
+}
+
+export interface ScrapeMetadata {
+  // Core source information
+  sourceURL?: string;
+  url?: string;
+  scrapeId?: string;
+  statusCode?: number;
+  // Basic metadata
+  title?: string;
+  description?: string;
+  language?: string;
+  favicon?: string;
+  viewport?: string;
+  robots?: string;
+  'theme-color'?: string;
+  // Open Graph metadata
+  'og:url'?: string;
+  'og:title'?: string;
+  'og:description'?: string;
+  'og:type'?: string;
+  'og:image'?: string;
+  'og:image:width'?: string;
+  'og:image:height'?: string;
+  'og:site_name'?: string;
+  ogUrl?: string;
+  ogTitle?: string;
+  ogDescription?: string;
+  ogImage?: string;
+  ogSiteName?: string;
+  // Article metadata
+  'article:author'?: string;
+  'article:published_time'?: string;
+  'article:modified_time'?: string;
+  'article:section'?: string;
+  'article:tag'?: string;
+  'article:publisher'?: string;
+  publishedTime?: string;
+  modifiedTime?: string;
+  // Twitter metadata
+  'twitter:site'?: string;
+  'twitter:creator'?: string;
+  'twitter:card'?: string;
+  'twitter:image'?: string;
+  'twitter:dnt'?: string;
+  'twitter:app:name:iphone'?: string;
+  'twitter:app:id:iphone'?: string;
+  'twitter:app:url:iphone'?: string;
+  'twitter:app:name:ipad'?: string;
+  'twitter:app:id:ipad'?: string;
+  'twitter:app:url:ipad'?: string;
+  'twitter:app:name:googleplay'?: string;
+  'twitter:app:id:googleplay'?: string;
+  'twitter:app:url:googleplay'?: string;
+  // Facebook metadata
+  'fb:app_id'?: string;
+  // App links
+  'al:ios:url'?: string;
+  'al:ios:app_name'?: string;
+  'al:ios:app_store_id'?: string;
+  // Allow for additional properties that might be present
+  [key: string]: string | number | boolean | null | undefined;
+}
+
+export interface FirecrawlScrapeResponse {
+  success: boolean;
+  data?: {
+    markdown?: string;
+    html?: string;
+    rawHtml?: string;
+    screenshot?: string;
+    links?: string[];
+    metadata?: ScrapeMetadata;
+  };
+  error?: string;
+}
+
+export interface FirecrawlScraperConfig {
+  apiKey?: string;
+  apiUrl?: string;
+  formats?: string[];
+  timeout?: number;
+}
+
+export type GetSourcesParams = {
+  query: string;
+  country?: string;
+  numResults?: number;
+};
+
+/** Serper API */
+export interface VideoResult {
+  title?: string;
+  link?: string;
+  snippet?: string;
+  imageUrl?: string;
+  duration?: string;
+  source?: string;
+  channel?: string;
+  date?: string;
+  position?: number;
+}
+
+export interface PlaceResult {
+  position?: number;
+  name?: string;
+  address?: string;
+  latitude?: number;
+  longitude?: number;
+  rating?: number;
+  ratingCount?: number;
+  category?: string;
+  identifier?: string;
+}
+
+export interface NewsResult {
+  title?: string;
+  link?: string;
+  snippet?: string;
+  date?: string;
+  source?: string;
+  imageUrl?: string;
+  position?: number;
+}
+
+export interface ShoppingResult {
+  title?: string;
+  source?: string;
+  link?: string;
+  price?: string;
+  delivery?: string;
+  imageUrl?: string;
+  rating?: number;
+  ratingCount?: number;
+  offers?: string;
+  productId?: string;
+  position?: number;
+}
+
+export interface ScholarResult {
+  title?: string;
+  link?: string;
+  publicationInfo?: string;
+  snippet?: string;
+  year?: number;
+  citedBy?: number;
+}
+
+export interface ImageResult {
+  title?: string;
+  imageUrl?: string;
+  imageWidth?: number;
+  imageHeight?: number;
+  thumbnailUrl?: string;
+  thumbnailWidth?: number;
+  thumbnailHeight?: number;
+  source?: string;
+  domain?: string;
+  link?: string;
+  googleUrl?: string;
+  position?: number;
+}
+
+export interface SerperSearchPayload extends SerperSearchInput {
+  /**
+   * Search type/vertical
+   * Options: "search" (web), "images", "news", "places", "videos"
+   */
+  type?: 'search' | 'images' | 'news' | 'places' | 'videos';
+
+  /**
+   * Starting index for search results pagination (used instead of page)
+   */
+  start?: number;
+
+  /**
+   * Filtering for safe search
+   * Options: "off", "moderate", "active"
+   */
+  safe?: 'off' | 'moderate' | 'active';
+}
+
+export type SerperSearchParameters = Pick<SerperSearchPayload, 'q' | 'type'> & {
+  engine: 'google';
+};
+
+export interface OrganicResult {
+  position?: number;
+  title?: string;
+  link: string;
+  snippet?: string;
+  date?: string;
+  sitelinks?: Array<{
+    title: string;
+    link: string;
+  }>;
+}
+
+export interface TopStoryResult {
+  title?: string;
+  link: string;
+  source?: string;
+  date?: string;
+  imageUrl?: string;
+}
+export interface KnowledgeGraphResult {
+  title?: string;
+  type?: string;
+  imageUrl?: string;
+  description?: string;
+  descriptionSource?: string;
+  descriptionLink?: string;
+  attributes?: Record<string, string>;
+  website?: string;
+}
+
+export interface AnswerBoxResult {
+  title?: string;
+  snippet?: string;
+  snippetHighlighted?: string[];
+  link?: string;
+  date?: string;
+}
+
+export interface PeopleAlsoAskResult {
+  question?: string;
+  snippet?: string;
+  title?: string;
+  link?: string;
+}
+
+export type RelatedSearches = Array<{ query: string }>;
+
+export interface SerperSearchInput {
+  /**
+   * The search query string
+   */
+  q: string;
+
+  /**
+   * Country code for localized results
+   * Examples: "us", "uk", "ca", "de", etc.
+   */
+  gl?: string;
+
+  /**
+   * Interface language
+   * Examples: "en", "fr", "de", etc.
+   */
+  hl?: string;
+
+  /**
+   * Number of results to return (up to 100)
+   */
+  num?: number;
+  /**
+   * Specific location for contextual results
+   * Example: "New York, NY"
+   */
+  location?: string;
+
+  /**
+   * Search autocorrection setting
+   */
+  autocorrect?: boolean;
+  page?: number;
+}
+
+export type SerperResultData = {
+  searchParameters: SerperSearchPayload;
+  organic?: OrganicResult[];
+  topStories?: TopStoryResult[];
+  images?: ImageResult[];
+  videos?: VideoResult[];
+  places?: PlaceResult[];
+  news?: NewsResult[];
+  shopping?: ShoppingResult[];
+  peopleAlsoAsk?: PeopleAlsoAskResult[];
+  relatedSearches?: RelatedSearches;
+  knowledgeGraph?: KnowledgeGraphResult;
+  answerBox?: AnswerBoxResult;
+  credits?: number;
+};
+
+/** SearXNG */
+
+export interface SearxNGSearchPayload {
+  /**
+   * The search query string
+   * Supports syntax specific to different search engines
+   * Example: "site:github.com SearXNG"
+   */
+  q: string;
+
+  /**
+   * Comma-separated list of search categories
+   * Example: "general,images,news"
+   */
+  categories?: string;
+
+  /**
+   * Comma-separated list of search engines to use
+   * Example: "google,bing,duckduckgo"
+   */
+  engines?: string;
+
+  /**
+   * Code of the language for search results
+   * Example: "en", "fr", "de", "es"
+   */
+  language?: string;
+
+  /**
+   * Search page number
+   * Default: 1
+   */
+  pageno?: number;
+
+  /**
+   * Time range filter for search results
+   * Options: "day", "month", "year"
+   */
+  time_range?: 'day' | 'month' | 'year';
+
+  /**
+   * Output format of results
+   * Options: "json", "csv", "rss"
+   */
+  format?: 'json' | 'csv' | 'rss';
+
+  /**
+   * Open search results on new tab
+   * Options: `0` (off), `1` (on)
+   */
+  results_on_new_tab?: 0 | 1;
+
+  /**
+   * Proxy image results through SearxNG
+   * Options: true, false
+   */
+  image_proxy?: boolean;
+
+  /**
+   * Service for autocomplete suggestions
+   * Options: "google", "dbpedia", "duckduckgo", "mwmbl",
+   *          "startpage", "wikipedia", "stract", "swisscows", "qwant"
+   */
+  autocomplete?: string;
+
+  /**
+   * Safe search filtering level
+   * Options: "0" (off), "1" (moderate), "2" (strict)
+   */
+  safesearch?: 0 | 1 | 2;
+
+  /**
+   * Theme to use for results page
+   * Default: "simple" (other themes may be available per instance)
+   */
+  theme?: string;
+
+  /**
+   * List of enabled plugins
+   * Default: "Hash_plugin,Self_Information,Tracker_URL_remover,Ahmia_blacklist"
+   */
+  enabled_plugins?: string;
+
+  /**
+   * List of disabled plugins
+   */
+  disabled_plugins?: string;
+
+  /**
+   * List of enabled engines
+   */
+  enabled_engines?: string;
+
+  /**
+   * List of disabled engines
+   */
+  disabled_engines?: string;
+}

package/src/tools/search/utils.ts

@@ -0,0 +1,43 @@
+/* eslint-disable no-console */
+import type * as t from './types';
+
+export const getDomainName = (
+  link: string,
+  metadata?: t.ScrapeMetadata
+): string | undefined => {
+  try {
+    const url = metadata?.sourceURL ?? metadata?.url ?? (link || '');
+    const domain = new URL(url).hostname.replace(/^www\./, '');
+    if (domain) {
+      return domain;
+    }
+  } catch (e) {
+    // URL parsing failed
+    console.error('Error parsing URL:', e);
+  }
+
+  return;
+};
+
+export function getAttribution(
+  link: string,
+  metadata?: t.ScrapeMetadata
+): string | undefined {
+  if (!metadata) return getDomainName(link, metadata);
+
+  const possibleAttributions = [
+    metadata.ogSiteName,
+    metadata['og:site_name'],
+    metadata.title?.split('|').pop()?.trim(),
+    metadata['twitter:site']?.replace(/^@/, ''),
+  ];
+
+  const attribution = possibleAttributions.find(
+    (attr) => attr != null && typeof attr === 'string' && attr.trim() !== ''
+  );
+  if (attribution != null) {
+    return attribution;
+  }
+
+  return getDomainName(link, metadata);
+}