chat-agent-toolkit 1.2.367 → 1.2.369

package/src/memory/storage/in-memory-storage.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Simple Memory Class
+ *
+ * Core memory management functionality with:
+ * - Message deduplication
+ * - Automatic summarization
+ * - Vector-based relevance search
+ * - Caching with TTL
+ * - Batch processing
+ * - Conflict resolution
+ */
+import type { IMemoryStorage } from "./storage-interface";
+import type { MemoryRecord, MemorySearchOptions, MemoryMetrics, MemoryOptions, MemoryContextOptions, MemoryType } from "../types";
+export declare class SimpleMemory {
+    private userId;
+    private storage;
+    private maxMemories;
+    private summaryThreshold;
+    private cacheExpiry;
+    private batchSize;
+    private relevanceThreshold;
+    private enableVectorSearch;
+    private enableAutoSummarization;
+    private recentMessages;
+    private memoryCache;
+    private isProcessing;
+    private processingQueue;
+    private summarizeTimeout?;
+    private metrics;
+    /**
+     * Initialize memory system for a user
+     */
+    constructor(userId: string, storage: IMemoryStorage, options?: MemoryOptions);
+    /**
+     * Add a message to current session with intelligent deduplication
+     */
+    addMessage(role: "user" | "assistant", content: string, metadata?: Record<string, any>): boolean;
+    /**
+     * Debounced summarization to prevent excessive processing
+     */
+    private debouncedSummarize;
+    /**
+     * Store important facts with validation and conflict resolution
+     */
+    storeFact(content: string, importance?: number, category?: MemoryType, metadata?: Record<string, any>): Promise<string>;
+    /**
+     * Find similar facts using content similarity
+     */
+    private findSimilarFacts;
+    /**
+     * Enhanced memory recall with caching and vector search
+     */
+    recallRelevantMemories(query?: string, limit?: number, options?: MemorySearchOptions): Promise<MemoryRecord[]>;
+    /**
+     * Apply vector search to memories
+     */
+    private applyVectorSearch;
+    /**
+     * Update relevance scores for memories
+     */
+    private updateRelevanceScores;
+    /**
+     * Improved summarization with error handling and batch processing
+     */
+    summarizeAndStore(): Promise<boolean>;
+    /**
+     * Extract facts from conversation using LLM
+     */
+    private extractFactsFromConversation;
+    /**
+     * Process facts in batches to avoid overwhelming the database
+     */
+    private processFactsInBatches;
+    /**
+     * Clear cache utility
+     */
+    clearCache(): void;
+    /**
+     * Get memory context with better formatting and relevance
+     */
+    getMemoryContext(query?: string, includeRecent?: boolean, options?: MemoryContextOptions): Promise<string>;
+    /**
+     * Get performance metrics
+     */
+    getMetrics(): MemoryMetrics;
+}

package/src/memory/storage/storage-interface.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Storage Interface
+ *
+ * Abstract interface for memory storage implementations.
+ * This allows swapping database backends without changing memory logic.
+ */
+import type { MemoryRecord, MemoryType, MemorySearchOptions, MemoryUpdate } from "../types";
+/**
+ * Storage interface that any database adapter must implement
+ */
+export interface IMemoryStorage {
+    /**
+     * Insert a new memory record
+     */
+    insertMemory(userId: string, memoryType: MemoryType, content: string, importance: number, metadata?: Record<string, any>): Promise<string>;
+    /**
+     * Find memories by user ID and optional filters
+     */
+    findMemories(userId: string, query?: string, limit?: number, options?: MemorySearchOptions): Promise<MemoryRecord[]>;
+    /**
+     * Find similar memories based on content
+     */
+    findSimilarMemories(userId: string, content: string, limit?: number): Promise<MemoryRecord[]>;
+    /**
+     * Update a memory record
+     */
+    updateMemory(id: string, updates: MemoryUpdate): Promise<void>;
+    /**
+     * Delete a memory record
+     */
+    deleteMemory(id: string): Promise<void>;
+    /**
+     * Get memory by ID
+     */
+    getMemoryById(id: string): Promise<MemoryRecord | null>;
+    /**
+     * Batch update memories
+     */
+    batchUpdateMemories(updates: Array<{
+        id: string;
+        updates: MemoryUpdate;
+    }>): Promise<void>;
+}

package/src/memory/types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Memory System Types and Constants
+ *
+ * Defines interfaces and configuration for the memory management system
+ */
+/**
+ * Memory types for categorization
+ */
+export declare const MEMORY_TYPES: {
+    readonly FACT: "fact";
+    readonly CONVERSATION: "conversation";
+    readonly PREFERENCE: "preference";
+    readonly PERSONAL: "personal";
+    readonly WORK: "work";
+    readonly MANUAL: "manual";
+};
+export type MemoryType = (typeof MEMORY_TYPES)[keyof typeof MEMORY_TYPES];
+/**
+ * Configuration constants for memory management
+ */
+export declare const MEMORY_CONFIG: {
+    readonly DEFAULT_MAX_MEMORIES: 100;
+    readonly DEFAULT_SUMMARY_THRESHOLD: 10;
+    readonly DEFAULT_CACHE_EXPIRY: number;
+    readonly DEFAULT_BATCH_SIZE: 5;
+    readonly DEFAULT_RELEVANCE_THRESHOLD: 0.3;
+    readonly DEFAULT_IMPORTANCE_RANGE: {
+        readonly min: 0;
+        readonly max: 10;
+    };
+    readonly DEFAULT_RATE_LIMIT: {
+        readonly requests: 10;
+        readonly windowMs: 60000;
+    };
+    readonly DEFAULT_TIMEOUT: 30000;
+    readonly VECTOR_SEARCH_ENABLED: true;
+    readonly AUTO_SUMMARIZATION_ENABLED: true;
+};
+/**
+ * Memory record structure
+ */
+export interface MemoryRecord {
+    id: string;
+    user_id: string;
+    memory_type: MemoryType;
+    content: string;
+    importance: number;
+    access_count: number;
+    metadata?: Record<string, any>;
+    created_at: Date;
+    updated_at: Date;
+    relevance_score?: number;
+}
+/**
+ * Message structure for conversation tracking
+ */
+export interface Message {
+    role: "user" | "assistant";
+    content: string;
+    timestamp: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Memory search options
+ */
+export interface MemorySearchOptions {
+    minImportance?: number;
+    memoryType?: MemoryType;
+    includeMetadata?: boolean;
+}
+/**
+ * Memory update payload
+ */
+export interface MemoryUpdate {
+    importance?: number;
+    access_count?: number | {
+        increment: number;
+    };
+    updated_at?: Date;
+    metadata?: Record<string, any>;
+}
+/**
+ * Memory context options
+ */
+export interface MemoryContextOptions {
+    maxMemories?: number;
+    minImportance?: number;
+}
+/**
+ * Performance metrics
+ */
+export interface MemoryMetrics {
+    cacheHits: number;
+    cacheMisses: number;
+    vectorSearches: number;
+    summarizations: number;
+    errors: number;
+    cacheSize: number;
+    recentMessagesCount: number;
+    isProcessing: boolean;
+}
+/**
+ * Memory initialization options
+ */
+export interface MemoryOptions {
+    maxMemories?: number;
+    summaryThreshold?: number;
+    cacheExpiry?: number;
+    batchSize?: number;
+    relevanceThreshold?: number;
+    enableVectorSearch?: boolean;
+    enableAutoSummarization?: boolean;
+}
+/**
+ * Extracted fact structure
+ */
+export interface ExtractedFact {
+    content: string;
+    importance?: number;
+    category?: MemoryType;
+    metadata?: Record<string, any>;
+}

package/src/models/registry.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @fileoverview Re-export ModelRegistry from config directory
+ */
+export { default } from "../config/model-registry";

package/src/models/types.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @fileoverview Re-export model types from config directory
+ */
+export type { Model, ConfigModelProvider, MinimalProvider } from "../config/config-types";

package/src/prompts/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @module agent-toolkit/prompts
+ * @description Prompt templates for AI agent tasks including web search and writing assistance.
+ */
+export * from "./search-prompts";

package/src/prompts/meta-search-types.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @module agent-toolkit/prompts/meta-search-types
+ * @description Shared types for search prompt few-shot examples.
+ */
+/** A `[role, content]` tuple used for few-shot prompt examples. */
+export type FewShotExample = [role: "user" | "assistant", content: string];

package/src/prompts/search-prompts.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @module agent-toolkit/prompts/search-prompts
+ * @description Prompt templates for web search and writing assistant agents.
+ */
+import type { FewShotExample } from './meta-search-types';
+export declare const webSearchRetrieverPrompt = "\nYou are an AI question rephraser. You will be given a conversation and a follow-up question,  you will have to rephrase the follow up question so it is a standalone question and can be used by another LLM to search the web for information to answer it.\nIf it is a simple writing task or a greeting (unless the greeting contains a question after it) like Hi, Hello, How are you, etc. than a question then you need to return `not_needed` as the response (This is because the LLM won't need to search the web for finding information on this topic).\nIf the user asks some question from some URL or wants you to summarize a PDF or a webpage (via URL) you need to return the links inside the `links` XML block and the question inside the `question` XML block. If the user wants to you to summarize the webpage or the PDF you need to return `summarize` inside the `question` XML block in place of a question and the link to summarize in the `links` XML block.\nYou must always return the rephrased question inside the `question` XML block, if there are no links in the follow-up question then don't insert a `links` XML block in your response.\n\n**Note**: All user messages are individual entities and should be treated as such do not mix conversations.\n";
+export declare const webSearchRetrieverFewShots: FewShotExample[];
+/**
+ * Default template for generating follow-up question suggestions after an
+ * answer. Interpolated with `{maxQuestions}` and `{chat_history}`.
+ *
+ * Exported (rather than inlined in the suggestion agent) so the settings UI can
+ * show the live default in an editable textarea and users can override it.
+ */
+export declare const followUpSuggestionsPrompt = "\nYou are an AI suggestion generator for an AI powered search engine. You will be given a conversation below. You need to generate {maxQuestions} suggestions based on the conversation. The suggestion should be relevant to the conversation that can be used by the user to ask the chat model for more information.\nYou need to make sure the suggestions are relevant to the conversation and are helpful to the user. Keep a note that the user might use these suggestions to ask a chat model for more information.\nMake sure the suggestions are medium in length and are informative and relevant to the conversation.\n\nProvide these suggestions separated by newlines between the XML tags <suggestions> and </suggestions>. For example:\n\n<suggestions>\nTell me more about SpaceX and their recent projects\nWhat is the latest news on SpaceX?\nWho is the CEO of SpaceX?\n</suggestions>\n\nConversation:\n{chat_history}\n";
+export declare const webSearchResponsePrompt = "\n    You are QwkSearch, an AI model skilled in web search and crafting detailed, engaging, and well-structured answers. You excel at summarizing web pages and extracting relevant information to create professional, blog-style responses.\n\n    Your task is to provide answers that are:\n    - **Informative and relevant**: Thoroughly address the user's query using the given context.\n    - **Well-structured**: Include clear headings and subheadings, and use a professional tone to present information concisely and logically.\n    - **Engaging and detailed**: Write responses that read like a high-quality blog post, including extra details and relevant insights.\n    - **Cited and credible**: Use inline citations with [number] notation to refer to the context source(s) for each fact or detail included.\n    - **Explanatory and Comprehensive**: Strive to explain the topic in depth, offering detailed analysis, insights, and clarifications wherever applicable.\n\n    ### Formatting Instructions\n    - **Structure**: Use a well-organized format with proper headings (e.g., \"## Example heading 1\" or \"## Example heading 2\"). Present information in paragraphs or concise bullet points where appropriate.\n    - **Tone and Style**: Maintain a neutral, journalistic tone with engaging narrative flow. Write as though you're crafting an in-depth article for a professional audience.\n    - **Markdown Usage**: Format your response with Markdown for clarity. Use headings, subheadings, bold text, and italicized words as needed to enhance readability.\n    - **Length and Depth**: Provide comprehensive coverage of the topic. Avoid superficial responses and strive for depth without unnecessary repetition. Expand on technical or complex topics to make them easier to understand for a general audience.\n    - **No main heading/title**: Start your response directly with the introduction unless asked to provide a specific title.\n    - **Conclusion or Summary**: Include a concluding paragraph that synthesizes the provided information or suggests potential next steps, where appropriate.\n\n    ### Citation Requirements\n    - Cite every single fact, statement, or sentence using [number] notation corresponding to the source from the provided `context`.\n    - Integrate citations naturally at the end of sentences or clauses as appropriate. For example, \"The Eiffel Tower is one of the most visited landmarks in the world[1].\"\n    - Ensure that **every sentence in your response includes at least one citation**, even when information is inferred or connected to general knowledge available in the provided context.\n    - Use multiple sources for a single detail if applicable, such as, \"Paris is a cultural hub, attracting millions of visitors annually[1][2].\"\n    - Always prioritize credibility and accuracy by linking all statements back to their respective context sources.\n    - Avoid citing unsupported assumptions or personal interpretations; if no source supports a statement, clearly indicate the limitation.\n\n    ### Special Instructions\n    - If the query involves technical, historical, or complex topics, provide detailed background and explanatory sections to ensure clarity.\n    - If the user provides vague input or if relevant information is missing, explain what additional details might help refine the search.\n    - If no relevant information is found, say: \"Hmm, sorry I could not find any relevant information on this topic. Would you like me to search again or ask something else?\" Be transparent about limitations and suggest alternatives or ways to reframe the query.\n\n    ### User instructions\n    These instructions are shared to you by the user and not by the system. You will have to follow them but give them less priority than the above instructions. If the user has provided specific instructions or preferences, incorporate them into your response while adhering to the overall guidelines.\n    {systemInstructions}\n\n    ### Example Output\n    - Begin with a brief introduction summarizing the event or query topic.\n    - Follow with detailed sections under clear headings, covering all aspects of the query if possible.\n    - Provide explanations or historical context as needed to enhance understanding.\n    - End with a conclusion or overall perspective if relevant.\n\n    <context>\n    {context}\n    </context>\n\n    Current date & time in ISO format (UTC timezone) is: {date}.\n";
+export declare const writingAssistantPrompt = "\nYou are QwkSearch, an AI model who is expert at searching the web and answering user's queries. You are currently set on focus mode 'Writing Assistant', this means you will be helping the user write a response to a given query.\nYou should still use retrieved web context and cite it while helping the user write a strong response.\nYou will be shared a context that can contain information from files user has uploaded to get answers from. You will have to generate answers upon that.\n\nYou have to cite the answer using [number] notation. You must cite the sentences with their relevant context number. You must cite each and every part of the answer so the user can know where the information is coming from.\nPlace these citations at the end of that particular sentence. You can cite the same sentence multiple times if it is relevant to the user's query like [number1][number2].\nHowever you do not need to cite it using the same number. You can use different numbers to cite the same sentence multiple times. The number refers to the number of the search result (passed in the context) used to generate that part of the answer.\n\n### User instructions\nThese instructions are shared to you by the user and not by the system. You will have to follow them but give them less priority than the above instructions. If the user has provided specific instructions or preferences, incorporate them into your response while adhering to the overall guidelines.\n{systemInstructions}\n\n<context>\n{context}\n</context>\n";
+declare const _default: {
+    webSearchResponsePrompt: string;
+    webSearchRetrieverPrompt: string;
+    webSearchRetrieverFewShots: FewShotExample[];
+    writingAssistantPrompt: string;
+    followUpSuggestionsPrompt: string;
+};
+export default _default;

package/src/tools/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Agent Tools Module
+ *
+ * Exports tool definitions for QwkSearch API integration including web search,
+ * content extraction, and AI response generation. Tools are automatically
+ * attached to agents when declared in prompt templates.
+ *
+ * @module tools
+ * @author ai-research-agent contributors
+ */
+export { AGENT_TOOLS } from "./qwksearch-api-tools";
+export { QwkSearchMCPSession, getQwkSearchTools } from "./qwksearch-mcp-tools";
+export * from "./search";

package/src/tools/qwksearch-api-tools.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview Specialized tools for AI agents to interact with the QwkSearch API.
+ * Provides web search, content extraction, and AI response generation.
+ */
+import { z } from "zod";
+/**
+ * List of tools available for agent usage, including their schemas and implementation.
+ */
+export declare const AGENT_TOOLS: ({
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        query: z.ZodString;
+        category: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+            files: "files";
+            general: "general";
+            images: "images";
+            it: "it";
+            news: "news";
+            science: "science";
+            videos: "videos";
+        }>>>;
+        recency: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+            day: "day";
+            month: "month";
+            none: "none";
+            week: "week";
+            year: "year";
+        }>>>;
+        page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        language: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        public: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        baseURL: z.ZodOptional<z.ZodString>;
+        apiKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    func: ({ query, category, recency, page, language, public: isPublic, timeout, baseURL, apiKey }: {
+        apiKey: any;
+        baseURL: any;
+        category?: string;
+        language?: string;
+        page?: number;
+        public?: boolean;
+        query: any;
+        recency?: string;
+        timeout?: number;
+    }) => Promise<string>;
+} | {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        url: z.ZodString;
+        images: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        links: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        formatting: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        absoluteURLs: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        baseURL: z.ZodOptional<z.ZodString>;
+        apiKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    func: ({ url, images, links, formatting, absoluteURLs, timeout, baseURL, apiKey }: {
+        absoluteURLs?: boolean;
+        apiKey: any;
+        baseURL: any;
+        formatting?: boolean;
+        images?: boolean;
+        links?: boolean;
+        timeout?: number;
+        url: any;
+    }) => Promise<string>;
+} | {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        url: z.ZodString;
+        blockImages: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        wait: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        waitUntil: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+            domcontentloaded: "domcontentloaded";
+            load: "load";
+            networkidle0: "networkidle0";
+            networkidle2: "networkidle2";
+        }>>>;
+        bypassCaptcha: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        sessionId: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        format: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+            html: "html";
+            json: "json";
+        }>>>;
+        scraperUrl: z.ZodOptional<z.ZodString>;
+        scraperApiKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    func: ({ url, blockImages, wait, timeout, waitUntil, bypassCaptcha, sessionId, format, scraperUrl, scraperApiKey }: {
+        blockImages?: boolean;
+        bypassCaptcha?: boolean;
+        format?: string;
+        scraperApiKey: any;
+        scraperUrl: any;
+        sessionId?: string;
+        timeout?: number;
+        url: any;
+        wait?: number;
+        waitUntil?: string;
+    }) => Promise<string>;
+})[];

package/src/tools/qwksearch-mcp-tools.d.ts

@@ -0,0 +1,26 @@
+import type { ToolSet } from "ai";
+export interface QwkSearchMCPConfig {
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+/**
+ * Long-lived MCP session for QwkSearch tools.
+ * Spawns a local MCP server process and keeps it alive across tool calls.
+ */
+export declare class QwkSearchMCPSession {
+    private client;
+    private config;
+    constructor(config?: QwkSearchMCPConfig);
+    getTools(): Promise<ToolSet>;
+    close(): Promise<void>;
+}
+/**
+ * One-shot helper to get QwkSearch MCP tools.
+ * Creates a session, fetches tools, and returns them.
+ * Caller should close the returned session when done.
+ */
+export declare function getQwkSearchTools(config?: QwkSearchMCPConfig): Promise<{
+    tools: ToolSet;
+    session: QwkSearchMCPSession;
+}>;

package/src/tools/search/doc-utils.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @module research/search/doc-utils
+ * @description Document utilities: fallback docs, reranking, and formatting.
+ */
+import type { Document } from "./document";
+export interface R2CredentialsInput {
+    accountId: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    bucket: string;
+}
+export declare function buildFallbackDocs(query: string): Document[];
+export declare function normalizeSourcesOutput(output: unknown, query: string): Document[];
+/** The payload resolved for an uploaded fileId. */
+export interface LoadedUpload {
+    title: string;
+    content: string;
+    /** MIME type for image uploads (e.g. `"image/png"`). */
+    mediaType?: string;
+    /** `data:`/`http(s)` URL of an image upload, passed to the LLM as image content. */
+    image?: string;
+}
+/** An image attachment resolved from an uploaded fileId. */
+export interface UploadImageAttachment {
+    mediaType: string;
+    /** `data:`/`http(s)` URL of the image, ready for an AI SDK image content part. */
+    image: string;
+}
+/**
+ * Resolves an uploaded fileId to its extracted payload. Hosts register a loader
+ * (e.g. reading the native R2 binding) so the search pipeline does not depend
+ * on filesystem or credential-based access. Image uploads additionally carry
+ * `mediaType` and `image` so they can be passed to the LLM directly.
+ */
+export type UploadFileLoader = (fileId: string) => Promise<LoadedUpload | null>;
+/**
+ * Registers the loader used by {@link rerankDocs} to resolve uploaded
+ * fileIds to extracted content. The registered loader takes precedence over
+ * the S3-credentials fallback.
+ */
+export declare function registerUploadFileLoader(loader: UploadFileLoader): void;
+/**
+ * Resolves image attachments for the given uploaded fileIds so they can be
+ * passed to the LLM as image content parts. Non-image uploads (documents) and
+ * images stored without inline data are skipped.
+ */
+export declare function loadUploadImages(fileIds: string[], r2Credentials?: R2CredentialsInput): Promise<UploadImageAttachment[]>;
+export declare function rerankDocs(query: string, docs: Document[], fileIds: string[], optimizationMode: "speed" | "balanced" | "quality", r2Credentials?: R2CredentialsInput): Promise<Document[]>;
+export declare function processDocs(docs: Document[]): string;

package/src/tools/search/document.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @module research/search/document
+ * @description Minimal document shape shared across the search pipeline.
+ * A document is a chunk of page content plus citation metadata (title, url, source, etc.).
+ */
+export interface Document<Metadata extends Record<string, any> = Record<string, any>> {
+    pageContent: string;
+    metadata: Metadata;
+}
+/**
+ * Splits text into overlapping chunks on whitespace boundaries.
+ * Default chunkSize 1000, chunkOverlap 200.
+ */
+export declare function splitTextIntoChunks(text: string, chunkSize?: number, chunkOverlap?: number): string[];

package/src/tools/search/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @module agent-toolkit/tools/search
+ * @description Meta search agent tools for AI-powered web search and research
+ */
+export { default as MetaSearchAgent } from "./metaSearchAgent";
+export type { MetaSearchAgentType, Config, ChatTurnMessage, SearchingEvent, FewShotExample } from "./meta-search-types";
+export { searchHandlers, createSearchHandlers } from "./search-handlers";
+export { default as generateSuggestions } from "./suggestionGeneratorAgent";
+export { groupAndSummarizeDocs } from "./link-summarizer";
+export type { Document } from "./document";
+export { splitTextIntoChunks } from "./document";
+export { buildFallbackDocs, rerankDocs, processDocs, normalizeSourcesOutput, registerUploadFileLoader, loadUploadImages } from "./doc-utils";
+export type { UploadFileLoader, LoadedUpload, UploadImageAttachment } from "./doc-utils";

package/src/tools/search/link-summarizer.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @module research/search/link-summarizer
+ * @description Groups link documents by URL then summarizes each group with an LLM.
+ */
+import { type LanguageModel } from "ai";
+import type { Document } from "./document";
+/**
+ * Groups fetched link documents by URL (max 10 chunks per URL), then
+ * summarizes each group with the LLM in parallel.
+ */
+export declare function groupAndSummarizeDocs(llm: LanguageModel, linkDocs: Document[], question: string): Promise<Document[]>;

package/src/tools/search/meta-search-types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @module research/search/meta-search-types
+ * @description Shared types for the MetaSearchAgent.
+ */
+import type { LanguageModel } from "ai";
+import type EventEmitter from "events";
+/** A single conversation turn, matching the Vercel AI SDK message shape. */
+export interface ChatTurnMessage {
+    role: "user" | "assistant" | "system";
+    content: string;
+}
+/** A `[role, content]` tuple used for few-shot prompt examples. */
+export type FewShotExample = [role: "user" | "assistant", content: string];
+export interface MetaSearchAgentType {
+    searchAndAnswer: (message: string, history: ChatTurnMessage[], llm: LanguageModel, optimizationMode: "speed" | "balanced" | "quality", fileIds: string[], systemInstructions: string, category?: string, sourceExtractionEnabled?: boolean, thinkingTimeLimit?: number, 
+    /** User-authored replacement for the focus mode's query-expansion prompt. */
+    queryExpansionPrompt?: string) => Promise<EventEmitter>;
+}
+/** Emitted on the EventEmitter data channel to report live search progress. */
+export interface SearchingEvent {
+    query: string;
+    /** Display label shown in the UI (e.g. "Academic · max 10"). */
+    category?: string;
+    status: "running" | "done";
+}
+export interface Config {
+    searchWeb: boolean;
+    rerank: boolean;
+    rerankThreshold: number;
+    queryGeneratorPrompt: string;
+    queryGeneratorFewShots: FewShotExample[];
+    responsePrompt: string;
+    activeEngines: string[];
+    /** Optional: Function to fetch documents from URLs */
+    getDocumentsFromLinks?: (options: {
+        links: string[];
+    }) => Promise<any[]>;
+    /** Optional: Function to search via SearXNG */
+    searchSearxng?: (query: string, options: any) => Promise<{
+        results: any[];
+        suggestions: string[];
+    }>;
+    /** Optional: Function to search via Tavily */
+    searchTavily?: (query: string, options: any) => Promise<{
+        results: any[];
+        suggestions: string[];
+    }>;
+    /** Optional: Function to check if Tavily is configured */
+    isTavilyConfigured?: () => boolean;
+    /** Optional: Function to scrape a URL */
+    scrapeURL?: (url: string, options: any) => Promise<string>;
+}
+export type BasicChainInput = {
+    chat_history: ChatTurnMessage[];
+    query: string;
+};

package/src/tools/search/metaSearchAgent.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Orchestrator for complex research queries.
+ * Manages query expansion, web search execution, and result synthesis using
+ * LLMs through the Vercel AI SDK (generateText/streamText).
+ */
+import { type LanguageModel } from "ai";
+import EventEmitter from "events";
+import type { Config, ChatTurnMessage, MetaSearchAgentType } from "./meta-search-types";
+export type { MetaSearchAgentType, Config } from "./meta-search-types";
+declare class MetaSearchAgent implements MetaSearchAgentType {
+    private config;
+    constructor(config: Config);
+    /**
+     * Rephrases the user's query into a standalone search question (and any
+     * URLs to summarize), runs the web search, and returns the documents to
+     * use as answer context.
+     */
+    private retrieveSearchDocs;
+    /**
+     * Runs the full search-and-answer pipeline, emitting "sources",
+     * "response", "searching", "end", and "error" events on the emitter.
+     */
+    private runPipeline;
+    searchAndAnswer(message: string, history: ChatTurnMessage[], llm: LanguageModel, optimizationMode: "speed" | "balanced" | "quality", fileIds: string[], systemInstructions: string, category?: string, sourceExtractionEnabled?: boolean, thinkingTimeLimit?: number, queryExpansionPrompt?: string): Promise<EventEmitter<any>>;
+}
+export default MetaSearchAgent;