@librechat/agents 2.4.30 → 2.4.311

package/dist/types/tools/search/firecrawl.d.ts

@@ -0,0 +1,117 @@
+export interface FirecrawlScrapeOptions {
+    formats?: string[];
+    includeTags?: string[];
+    excludeTags?: string[];
+    headers?: Record<string, string>;
+    waitFor?: number;
+    timeout?: number;
+}
+interface ScrapeMetadata {
+    sourceURL?: string;
+    url?: string;
+    scrapeId?: string;
+    statusCode?: number;
+    title?: string;
+    description?: string;
+    language?: string;
+    favicon?: string;
+    viewport?: string;
+    robots?: string;
+    'theme-color'?: string;
+    '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:author'?: string;
+    'article:published_time'?: string;
+    'article:modified_time'?: string;
+    'article:section'?: string;
+    'article:tag'?: string;
+    'article:publisher'?: string;
+    publishedTime?: string;
+    modifiedTime?: string;
+    '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;
+    'fb:app_id'?: string;
+    'al:ios:url'?: string;
+    'al:ios:app_name'?: string;
+    'al:ios:app_store_id'?: string;
+    [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 declare function getAttribution(link: string, metadata?: ScrapeMetadata): string | undefined;
+/**
+ * Firecrawl scraper implementation
+ * Uses the Firecrawl API to scrape web pages
+ */
+export declare class FirecrawlScraper {
+    private apiKey;
+    private apiUrl;
+    private defaultFormats;
+    private timeout;
+    constructor(config?: FirecrawlScraperConfig);
+    /**
+     * Scrape a single URL
+     * @param url URL to scrape
+     * @param options Scrape options
+     * @returns Scrape response
+     */
+    scrapeUrl(url: string, options?: FirecrawlScrapeOptions): Promise<[string, FirecrawlScrapeResponse]>;
+    /**
+     * Extract content from scrape response
+     * @param response Scrape response
+     * @returns Extracted content or empty string if not available
+     */
+    extractContent(response: FirecrawlScrapeResponse): string;
+    /**
+     * Extract metadata from scrape response
+     * @param response Scrape response
+     * @returns Metadata object
+     */
+    extractMetadata(response: FirecrawlScrapeResponse): ScrapeMetadata;
+}
+/**
+ * Create a Firecrawl scraper instance
+ * @param config Scraper configuration
+ * @returns Firecrawl scraper instance
+ */
+export declare const createFirecrawlScraper: (config?: FirecrawlScraperConfig) => FirecrawlScraper;
+export {};

package/dist/types/tools/search/format.d.ts

@@ -0,0 +1,2 @@
+import type * as t from './types';
+export declare function formatResultsForLLM(results: t.SearchResultData): string;

package/dist/types/tools/search/highlights.d.ts

@@ -0,0 +1,13 @@
+import type * as t from './types';
+/**
+ * Expand highlights in search results using smart boundary detection.
+ *
+ * This implementation finds natural text boundaries like paragraphs, sentences,
+ * and phrases to provide context while maintaining readability.
+ *
+ * @param searchResults - Search results object
+ * @param mainExpandBy - Primary expansion size on each side (default: 300)
+ * @param separatorExpandBy - Additional range to look for separators (default: 150)
+ * @returns Copy of search results with expanded highlights
+ */
+export declare function expandHighlights(searchResults: t.SearchResultData, mainExpandBy?: number, separatorExpandBy?: number): t.SearchResultData;

package/dist/types/tools/search/index.d.ts

@@ -0,0 +1,2 @@
+export * from './tool';
+export type * from './types';

package/dist/types/tools/search/rerankers.d.ts

@@ -0,0 +1,32 @@
+import type * as t from './types';
+export declare abstract class BaseReranker {
+    protected apiKey: string | undefined;
+    constructor();
+    abstract rerank(query: string, documents: string[], topK?: number): Promise<t.Highlight[]>;
+    protected getDefaultRanking(documents: string[], topK: number): t.Highlight[];
+    protected logDocumentSamples(documents: string[]): void;
+}
+export declare class JinaReranker extends BaseReranker {
+    constructor({ apiKey }: {
+        apiKey?: string;
+    });
+    rerank(query: string, documents: string[], topK?: number): Promise<t.Highlight[]>;
+}
+export declare class CohereReranker extends BaseReranker {
+    constructor({ apiKey }: {
+        apiKey?: string;
+    });
+    rerank(query: string, documents: string[], topK?: number): Promise<t.Highlight[]>;
+}
+export declare class InfinityReranker extends BaseReranker {
+    constructor();
+    rerank(query: string, documents: string[], topK?: number): Promise<t.Highlight[]>;
+}
+/**
+ * Creates the appropriate reranker based on type and configuration
+ */
+export declare const createReranker: (config: {
+    rerankerType: t.RerankerType;
+    jinaApiKey?: string;
+    cohereApiKey?: string;
+}) => BaseReranker | undefined;

package/dist/types/tools/search/search.d.ts

@@ -0,0 +1,9 @@
+import type * as t from './types';
+import { FirecrawlScraper } from './firecrawl';
+export declare const createSearchAPI: (config: t.SearchConfig) => {
+    getSources: (query: string, numResults?: number, storedLocation?: string) => Promise<t.SearchResult>;
+};
+export declare const createSourceProcessor: (config?: t.ProcessSourcesConfig, scraperInstance?: FirecrawlScraper) => {
+    processSources: (result: t.SearchResult, numElements: number, query: string, proMode?: boolean) => Promise<t.SearchResultData>;
+    topResults: number;
+};

package/dist/types/tools/search/tool.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from './types';
+declare const SearchToolSchema: z.ZodObject<{
+    query: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+}, {
+    query: string;
+}>;
+export declare const createSearchTool: (config?: t.SearchToolConfig) => DynamicStructuredTool<typeof SearchToolSchema>;
+export {};

package/dist/types/tools/search/types.d.ts

@@ -0,0 +1,150 @@
+import type { RunnableConfig } from '@langchain/core/runnables';
+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;
+}
+export interface ValidSource {
+    link: string;
+    position?: number;
+    title?: string;
+    snippet?: string;
+    date?: string;
+    content?: string;
+    attribution?: string;
+    highlights?: Highlight[];
+}
+export interface SearchResultData {
+    organic?: ValidSource[];
+    topStories?: ValidSource[];
+    images?: ImageResult[];
+    knowledgeGraph?: KnowledgeGraphResult;
+    answerBox?: AnswerBoxResult;
+    peopleAlsoAsk?: PeopleAlsoAskResult[];
+    relatedSearches?: string[];
+    suggestions?: string[];
+    error?: string;
+}
+export interface SearchResult {
+    data?: SearchResultData;
+    error?: string;
+    success: boolean;
+}
+export interface Source {
+    link: string;
+    html?: string;
+    title?: string;
+    snippet?: string;
+    date?: string;
+}
+export interface SearchConfig {
+    searchProvider?: SearchProvider;
+    serperApiKey?: string;
+    searxngInstanceUrl?: string;
+    searxngApiKey?: string;
+}
+export interface ScrapeResult {
+    url: string;
+    error?: boolean;
+    content: string;
+    attribution?: string;
+    highlights?: Highlight[];
+}
+export interface ProcessSourcesConfig {
+    topResults?: number;
+    strategies?: string[];
+    filterContent?: boolean;
+    reranker?: BaseReranker;
+}
+export interface FirecrawlConfig {
+    firecrawlApiKey?: string;
+    firecrawlApiUrl?: string;
+    firecrawlFormats?: string[];
+}
+export interface ScraperContentResult {
+    content: string;
+}
+export interface ScraperExtractionResult {
+    no_extraction: ScraperContentResult;
+}
+export interface SearXNGResult {
+    title?: string;
+    url?: string;
+    content?: string;
+    publishedDate?: string;
+    img_src?: string;
+}
+export interface JinaRerankerResult {
+    index: number;
+    relevance_score: number;
+    document?: string | {
+        text: string;
+    };
+}
+export interface JinaRerankerResponse {
+    model: string;
+    usage: {
+        total_tokens: number;
+    };
+    results: JinaRerankerResult[];
+}
+export interface CohereRerankerResult {
+    index: number;
+    relevance_score: number;
+}
+export interface CohereRerankerResponse {
+    results: CohereRerankerResult[];
+    id: string;
+    meta: {
+        api_version: {
+            version: string;
+            is_experimental: boolean;
+        };
+        billed_units: {
+            search_units: number;
+        };
+    };
+}
+export interface SearchToolConfig extends SearchConfig, ProcessSourcesConfig, FirecrawlConfig {
+    jinaApiKey?: string;
+    cohereApiKey?: string;
+    rerankerType?: RerankerType;
+    onSearchResults?: (results: SearchResult, runnableConfig?: RunnableConfig) => void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "2.4.30",
+  "version": "2.4.311",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -52,6 +52,7 @@
     "thinking": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/thinking.ts --name 'Jo' --location 'New York, NY'",
     "memory": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/memory.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
     "tool-test": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/tools.ts --provider 'alibaba' --name 'Jo' --location 'New York, NY'",
+    "search": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/search.ts --provider 'anthropic' --name 'Jo' --location 'New York, NY'",
     "abort": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/abort.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
     "start:cli2": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/cli2.ts --provider 'anthropic' --name 'Jo' --location 'New York, NY'",
     "script2": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/proto/example_test.ts",

package/src/common/enum.ts

@@ -158,6 +158,7 @@ export enum Callback {
 export enum Constants {
   OFFICIAL_CODE_BASEURL = 'https://api.librechat.ai/v1',
   EXECUTE_CODE = 'execute_code',
+  WEB_SEARCH = 'web_search',
   CONTENT_AND_ARTIFACT = 'content_and_artifact',
 }
 

package/src/index.ts

@@ -10,6 +10,7 @@ export * from './graphs';
 
 /* Tools */
 export * from './tools/CodeExecutor';
+export * from './tools/search';
 
 /* Misc. */
 export * from './common';

package/src/scripts/search.ts

@@ -0,0 +1,141 @@
+/* eslint-disable no-console */
+// src/scripts/cli.ts
+import { config } from 'dotenv';
+config();
+import { HumanMessage, BaseMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { createSearchTool } from '@/tools/search';
+
+import { getArgs } from '@/scripts/args';
+import { Run } from '@/run';
+import { GraphEvents, Callback } from '@/common';
+import { getLLMConfig } from '@/utils/llmConfig';
+
+const conversationHistory: BaseMessage[] = [];
+async function testStandardStreaming(): Promise<void> {
+  const { userName, location, provider, currentDate } = await getArgs();
+  const { contentParts, aggregateContent } = createContentAggregator();
+  const customHandlers = {
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_COMPLETED,
+        data: t.StreamEventData
+      ): void => {
+        console.log('====== ON_RUN_STEP_COMPLETED ======');
+        // console.dir(data, { depth: null });
+        aggregateContent({
+          event,
+          data: data as unknown as { result: t.ToolEndEvent },
+        });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP,
+        data: t.StreamEventData
+      ): void => {
+        console.log('====== ON_RUN_STEP ======');
+        console.dir(data, { depth: null });
+        aggregateContent({ event, data: data as t.RunStep });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_DELTA,
+        data: t.StreamEventData
+      ): void => {
+        console.log('====== ON_RUN_STEP_DELTA ======');
+        console.dir(data, { depth: null });
+        aggregateContent({ event, data: data as t.RunStepDeltaEvent });
+      },
+    },
+    [GraphEvents.ON_MESSAGE_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_MESSAGE_DELTA,
+        data: t.StreamEventData
+      ): void => {
+        console.log('====== ON_MESSAGE_DELTA ======');
+        console.dir(data, { depth: null });
+        aggregateContent({ event, data: data as t.MessageDeltaEvent });
+      },
+    },
+    [GraphEvents.TOOL_START]: {
+      handle: (
+        _event: string,
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('====== TOOL_START ======');
+        // console.dir(data, { depth: null });
+      },
+    },
+  };
+
+  const llmConfig = getLLMConfig(provider);
+
+  const run = await Run.create<t.IState>({
+    runId: 'test-run-id',
+    graphConfig: {
+      type: 'standard',
+      llmConfig,
+      tools: [createSearchTool()],
+      instructions:
+        'You are a friendly AI assistant. Always address the user by their name.',
+      additional_instructions: `The user's name is ${userName} and they are located in ${location}.`,
+    },
+    returnContent: true,
+    customHandlers,
+  });
+
+  const config = {
+    configurable: {
+      provider,
+      thread_id: 'conversation-num-1',
+    },
+    streamMode: 'values',
+    version: 'v2' as const,
+  };
+
+  console.log('Test 1: Weather query (content parts test)');
+
+  // const userMessage = `
+  // Make a search for the weather in ${location} today, which is ${currentDate}.
+  // Before making the search, please let me know what you're about to do, then immediately start searching without hesitation.
+  // Make sure to always refer to me by name, which is ${userName}.
+  // After giving me a thorough summary, tell me a joke about the weather forecast we went over.
+  // `;
+  const userMessage = 'Are massage guns good?';
+
+  conversationHistory.push(new HumanMessage(userMessage));
+
+  const inputs = {
+    messages: conversationHistory,
+  };
+  const finalContentParts = await run.processStream(inputs, config);
+  const finalMessages = run.getRunMessages();
+  if (finalMessages) {
+    conversationHistory.push(...finalMessages);
+    console.dir(conversationHistory, { depth: null });
+  }
+  // console.dir(finalContentParts, { depth: null });
+  console.log('\n\n====================\n\n');
+  // console.dir(contentParts, { depth: null });
+}
+
+process.on('unhandledRejection', (reason, promise) => {
+  console.error('Unhandled Rejection at:', promise, 'reason:', reason);
+  console.log('Conversation history:');
+  process.exit(1);
+});
+
+testStandardStreaming().catch((err) => {
+  console.error(err);
+  console.log('Conversation history:');
+  console.dir(conversationHistory, { depth: null });
+  process.exit(1);
+});