groq-rag 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,771 @@
+import Groq from 'groq-sdk';
+import * as groq_sdk_core_mjs from 'groq-sdk/core.mjs';
+import * as groq_sdk_lib_streaming_mjs from 'groq-sdk/lib/streaming.mjs';
+import { ChatCompletionCreateParamsNonStreaming, ChatCompletion, ChatCompletionCreateParamsStreaming } from 'groq-sdk/resources/chat/completions';
+
+interface GroqRAGConfig {
+    apiKey?: string;
+    baseURL?: string;
+    timeout?: number;
+    maxRetries?: number;
+    embedding?: EmbeddingConfig;
+    vectorStore?: VectorStoreConfig;
+    web?: WebConfig;
+}
+interface EmbeddingConfig {
+    provider: 'groq' | 'openai' | 'local' | 'custom';
+    model?: string;
+    apiKey?: string;
+    baseURL?: string;
+    dimensions?: number;
+}
+interface VectorStoreConfig {
+    provider: 'memory' | 'chroma' | 'pinecone' | 'qdrant' | 'custom';
+    connectionString?: string;
+    apiKey?: string;
+    namespace?: string;
+    indexName?: string;
+}
+interface WebConfig {
+    userAgent?: string;
+    timeout?: number;
+    maxContentLength?: number;
+    followRedirects?: boolean;
+    proxy?: string;
+}
+interface Document {
+    id: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+    embedding?: number[];
+}
+interface DocumentChunk {
+    id: string;
+    documentId: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+    embedding?: number[];
+    startIndex?: number;
+    endIndex?: number;
+}
+interface EmbeddingResult {
+    embedding: number[];
+    tokenCount?: number;
+}
+interface SearchResult {
+    document: DocumentChunk;
+    score: number;
+    relevance?: 'high' | 'medium' | 'low';
+}
+interface RAGOptions {
+    /** Number of documents to retrieve */
+    topK?: number;
+    /** Minimum similarity score (0-1) */
+    minScore?: number;
+    /** Include document metadata in context */
+    includeMetadata?: boolean;
+    /** Custom context template */
+    contextTemplate?: string;
+    /** Maximum context length in tokens */
+    maxContextTokens?: number;
+}
+interface RAGChatOptions extends RAGOptions {
+    messages: Groq.Chat.ChatCompletionMessageParam[];
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    stream?: boolean;
+    systemPrompt?: string;
+}
+interface RAGResponse {
+    content: string;
+    sources: SearchResult[];
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+interface FetchOptions {
+    headers?: Record<string, string>;
+    timeout?: number;
+    maxLength?: number;
+    extractText?: boolean;
+    includeLinks?: boolean;
+    includeImages?: boolean;
+}
+interface FetchResult {
+    url: string;
+    title?: string;
+    content: string;
+    markdown?: string;
+    links?: Array<{
+        text: string;
+        href: string;
+    }>;
+    images?: Array<{
+        alt: string;
+        src: string;
+    }>;
+    metadata?: {
+        description?: string;
+        author?: string;
+        publishedDate?: string;
+    };
+    fetchedAt: Date;
+}
+interface SearchOptions {
+    maxResults?: number;
+    language?: string;
+    region?: string;
+    safeSearch?: boolean;
+}
+interface WebSearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+    position: number;
+}
+interface BrowseOptions extends FetchOptions {
+    /** Wait for JavaScript to execute */
+    waitForJs?: boolean;
+    /** Wait for specific selector */
+    waitForSelector?: string;
+    /** Execute custom JavaScript */
+    executeScript?: string;
+    /** Screenshot options */
+    screenshot?: boolean;
+    /** Scroll to load more content */
+    scrollToBottom?: boolean;
+}
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    execute: (params: Record<string, unknown>) => Promise<unknown>;
+}
+interface ToolResult {
+    name: string;
+    result: unknown;
+    error?: string;
+    executionTime?: number;
+}
+interface AgentConfig {
+    name?: string;
+    model?: string;
+    systemPrompt?: string;
+    tools?: ToolDefinition[];
+    maxIterations?: number;
+    verbose?: boolean;
+    memory?: AgentMemory;
+}
+interface AgentMemory {
+    messages: Groq.Chat.ChatCompletionMessageParam[];
+    context?: string;
+    variables?: Record<string, unknown>;
+}
+interface AgentStep {
+    thought?: string;
+    action?: string;
+    actionInput?: Record<string, unknown>;
+    observation?: string;
+    isFinal?: boolean;
+}
+interface AgentResult {
+    output: string;
+    steps: AgentStep[];
+    toolCalls: ToolResult[];
+    totalTokens?: number;
+}
+interface ChunkingOptions {
+    strategy: 'fixed' | 'sentence' | 'paragraph' | 'semantic' | 'recursive';
+    chunkSize?: number;
+    chunkOverlap?: number;
+    separators?: string[];
+}
+interface VectorStore {
+    add(documents: DocumentChunk[]): Promise<void>;
+    search(query: number[], options?: {
+        topK?: number;
+        filter?: Record<string, unknown>;
+    }): Promise<SearchResult[]>;
+    delete(ids: string[]): Promise<void>;
+    clear(): Promise<void>;
+    count(): Promise<number>;
+}
+interface EmbeddingProvider {
+    embed(text: string): Promise<EmbeddingResult>;
+    embedBatch(texts: string[]): Promise<EmbeddingResult[]>;
+    dimensions: number;
+}
+
+/**
+ * RAG Retriever - handles document ingestion and retrieval
+ */
+declare class Retriever {
+    private vectorStore;
+    private embeddings;
+    private chunker;
+    constructor(vectorStore: VectorStore, embeddings: EmbeddingProvider, chunkingOptions?: Partial<ChunkingOptions>);
+    /**
+     * Add a document to the retriever
+     */
+    addDocument(content: string, metadata?: Record<string, unknown>): Promise<string>;
+    /**
+     * Add multiple documents
+     */
+    addDocuments(documents: Array<{
+        content: string;
+        metadata?: Record<string, unknown>;
+    }>): Promise<string[]>;
+    /**
+     * Add raw text directly (without chunking)
+     */
+    addChunk(content: string, metadata?: Record<string, unknown>): Promise<string>;
+    /**
+     * Retrieve relevant documents for a query
+     */
+    retrieve(query: string, options?: RAGOptions): Promise<SearchResult[]>;
+    /**
+     * Retrieve and format context for LLM
+     */
+    getContext(query: string, options?: RAGOptions): Promise<string>;
+    /**
+     * Delete documents by ID
+     */
+    deleteDocuments(ids: string[]): Promise<void>;
+    /**
+     * Clear all documents
+     */
+    clear(): Promise<void>;
+    /**
+     * Get document count
+     */
+    count(): Promise<number>;
+}
+/**
+ * Create a default retriever with in-memory storage
+ */
+declare function createRetriever(vectorStore: VectorStore, embeddings: EmbeddingProvider, options?: Partial<ChunkingOptions>): Retriever;
+
+/**
+ * Web content fetcher - fetches and parses web pages
+ */
+declare class WebFetcher {
+    private config;
+    private turndown;
+    constructor(config?: WebConfig);
+    /**
+     * Fetch a URL and extract content
+     */
+    fetch(url: string, options?: FetchOptions): Promise<FetchResult>;
+    /**
+     * Fetch multiple URLs in parallel
+     */
+    fetchMany(urls: string[], options?: FetchOptions): Promise<Array<FetchResult | Error>>;
+    /**
+     * Fetch and extract just the text content
+     */
+    fetchText(url: string): Promise<string>;
+    /**
+     * Fetch and convert to markdown
+     */
+    fetchMarkdown(url: string): Promise<string>;
+}
+/**
+ * Create a web fetcher with default config
+ */
+declare function createFetcher(config?: WebConfig): WebFetcher;
+
+/**
+ * Web search provider interface
+ */
+interface SearchProvider {
+    search(query: string, options?: SearchOptions): Promise<WebSearchResult[]>;
+}
+/**
+ * DuckDuckGo search (no API key required)
+ */
+declare class DuckDuckGoSearch implements SearchProvider {
+    private baseUrl;
+    search(query: string, options?: SearchOptions): Promise<WebSearchResult[]>;
+    private parseResults;
+    private decodeUrl;
+    private decodeHtml;
+}
+/**
+ * Brave Search API
+ */
+declare class BraveSearch implements SearchProvider {
+    private apiKey;
+    private baseUrl;
+    constructor(apiKey: string);
+    search(query: string, options?: SearchOptions): Promise<WebSearchResult[]>;
+}
+/**
+ * Serper.dev Google Search API
+ */
+declare class SerperSearch implements SearchProvider {
+    private apiKey;
+    private baseUrl;
+    constructor(apiKey: string);
+    search(query: string, options?: SearchOptions): Promise<WebSearchResult[]>;
+}
+/**
+ * Create a search provider based on available API keys
+ */
+declare function createSearchProvider(config?: {
+    provider?: 'duckduckgo' | 'brave' | 'serper';
+    apiKey?: string;
+}): SearchProvider;
+
+/**
+ * ReAct-style agent that can use tools
+ */
+declare class Agent {
+    private client;
+    private config;
+    private executor;
+    private messages;
+    constructor(client: Groq, config?: AgentConfig);
+    private getDefaultSystemPrompt;
+    /**
+     * Add a tool to the agent
+     */
+    addTool(tool: ToolDefinition): void;
+    /**
+     * Run the agent with a user message
+     */
+    run(input: string): Promise<AgentResult>;
+    /**
+     * Run with streaming output
+     */
+    runStream(input: string): AsyncGenerator<{
+        type: 'thought' | 'tool_call' | 'tool_result' | 'content' | 'done';
+        data: unknown;
+    }>;
+    /**
+     * Clear conversation history
+     */
+    clearHistory(): void;
+    /**
+     * Get conversation history
+     */
+    getHistory(): Groq.Chat.ChatCompletionMessageParam[];
+}
+/**
+ * Create an agent with default configuration
+ */
+declare function createAgent(client: Groq, config?: AgentConfig): Agent;
+
+/**
+ * Extended Groq client with RAG, web, and agent capabilities
+ */
+declare class GroqRAG {
+    private groq;
+    private config;
+    private retriever?;
+    private fetcher;
+    private searchProvider;
+    chat: ChatWithRAG;
+    web: WebModule;
+    rag: RAGModule;
+    constructor(config?: GroqRAGConfig);
+    /**
+     * Get the underlying Groq client
+     */
+    get client(): Groq;
+    /**
+     * Initialize RAG with vector store and embeddings
+     */
+    initRAG(options?: {
+        embedding?: EmbeddingConfig;
+        vectorStore?: VectorStoreConfig;
+        chunking?: Partial<ChunkingOptions>;
+    }): Promise<Retriever>;
+    /**
+     * Get the retriever (initializes with defaults if not already initialized)
+     */
+    getRetriever(): Promise<Retriever>;
+    /**
+     * Get the web fetcher
+     */
+    getFetcher(): WebFetcher;
+    /**
+     * Get the search provider
+     */
+    getSearchProvider(): SearchProvider;
+    /**
+     * Create an agent with tools
+     */
+    createAgent(config?: AgentConfig): Agent;
+    /**
+     * Create an agent with built-in tools (web search, fetch, RAG)
+     */
+    createAgentWithBuiltins(config?: AgentConfig): Promise<Agent>;
+    /**
+     * Standard chat completions (passthrough to Groq)
+     */
+    complete(params: ChatCompletionCreateParamsNonStreaming): Promise<ChatCompletion>;
+    /**
+     * Streaming chat completions (passthrough to Groq)
+     */
+    stream(params: ChatCompletionCreateParamsStreaming): groq_sdk_core_mjs.APIPromise<groq_sdk_lib_streaming_mjs.Stream<Groq.Chat.Completions.ChatCompletionChunk>>;
+}
+/**
+ * Chat module with RAG support
+ */
+declare class ChatWithRAG {
+    private parent;
+    constructor(parent: GroqRAG);
+    /**
+     * Chat with RAG-augmented context
+     */
+    withRAG(options: RAGChatOptions): Promise<RAGResponse>;
+    /**
+     * Chat with web search augmentation
+     */
+    withWebSearch(options: {
+        messages: Groq.Chat.ChatCompletionMessageParam[];
+        model?: string;
+        searchQuery?: string;
+        maxResults?: number;
+    }): Promise<{
+        content: string;
+        sources: WebSearchResult[];
+    }>;
+    /**
+     * Chat with URL content
+     */
+    withUrl(options: {
+        messages: Groq.Chat.ChatCompletionMessageParam[];
+        url: string;
+        model?: string;
+    }): Promise<{
+        content: string;
+        source: FetchResult;
+    }>;
+}
+/**
+ * Web module for fetching and searching
+ */
+declare class WebModule {
+    private parent;
+    constructor(parent: GroqRAG);
+    /**
+     * Fetch a URL
+     */
+    fetch(url: string, options?: FetchOptions): Promise<FetchResult>;
+    /**
+     * Fetch multiple URLs
+     */
+    fetchMany(urls: string[], options?: FetchOptions): Promise<Array<FetchResult | Error>>;
+    /**
+     * Search the web
+     */
+    search(query: string, options?: SearchOptions): Promise<WebSearchResult[]>;
+    /**
+     * Fetch URL and convert to markdown
+     */
+    fetchMarkdown(url: string): Promise<string>;
+}
+/**
+ * RAG module for document management
+ */
+declare class RAGModule {
+    private parent;
+    constructor(parent: GroqRAG);
+    /**
+     * Add a document to the knowledge base
+     */
+    addDocument(content: string, metadata?: Record<string, unknown>): Promise<string>;
+    /**
+     * Add multiple documents
+     */
+    addDocuments(documents: Array<{
+        content: string;
+        metadata?: Record<string, unknown>;
+    }>): Promise<string[]>;
+    /**
+     * Add a URL's content to the knowledge base
+     */
+    addUrl(url: string, metadata?: Record<string, unknown>): Promise<string>;
+    /**
+     * Query the knowledge base
+     */
+    query(query: string, options?: {
+        topK?: number;
+        minScore?: number;
+    }): Promise<SearchResult[]>;
+    /**
+     * Get formatted context for a query
+     */
+    getContext(query: string, options?: {
+        topK?: number;
+        includeMetadata?: boolean;
+    }): Promise<string>;
+    /**
+     * Clear the knowledge base
+     */
+    clear(): Promise<void>;
+    /**
+     * Get document count
+     */
+    count(): Promise<number>;
+}
+
+/**
+ * In-memory vector store implementation
+ */
+declare class MemoryVectorStore implements VectorStore {
+    private documents;
+    add(documents: DocumentChunk[]): Promise<void>;
+    search(queryEmbedding: number[], options?: {
+        topK?: number;
+        filter?: Record<string, unknown>;
+    }): Promise<SearchResult[]>;
+    delete(ids: string[]): Promise<void>;
+    clear(): Promise<void>;
+    count(): Promise<number>;
+    /**
+     * Get all documents (useful for debugging)
+     */
+    getAll(): DocumentChunk[];
+}
+/**
+ * Chroma vector store adapter
+ */
+declare class ChromaVectorStore implements VectorStore {
+    private baseURL;
+    private collectionName;
+    private collectionId?;
+    constructor(config: VectorStoreConfig);
+    private ensureCollection;
+    add(documents: DocumentChunk[]): Promise<void>;
+    search(queryEmbedding: number[], options?: {
+        topK?: number;
+        filter?: Record<string, unknown>;
+    }): Promise<SearchResult[]>;
+    delete(ids: string[]): Promise<void>;
+    clear(): Promise<void>;
+    count(): Promise<number>;
+}
+/**
+ * Create a vector store based on config
+ */
+declare function createVectorStore(config: VectorStoreConfig): VectorStore;
+
+/**
+ * Groq-based embedding provider (uses compatible models)
+ */
+declare class GroqEmbeddings implements EmbeddingProvider {
+    private client;
+    private model;
+    dimensions: number;
+    constructor(config: EmbeddingConfig & {
+        groqClient?: Groq;
+    });
+    embed(text: string): Promise<EmbeddingResult>;
+    embedBatch(texts: string[]): Promise<EmbeddingResult[]>;
+    /**
+     * Generate a pseudo-embedding (for demo purposes)
+     * In production, replace with actual embedding API
+     */
+    private generatePseudoEmbedding;
+}
+/**
+ * OpenAI-compatible embedding provider
+ */
+declare class OpenAIEmbeddings implements EmbeddingProvider {
+    private apiKey;
+    private baseURL;
+    private model;
+    dimensions: number;
+    constructor(config: EmbeddingConfig);
+    embed(text: string): Promise<EmbeddingResult>;
+    embedBatch(texts: string[]): Promise<EmbeddingResult[]>;
+}
+/**
+ * Create an embedding provider based on config
+ */
+declare function createEmbeddingProvider(config: EmbeddingConfig, groqClient?: Groq): EmbeddingProvider;
+
+/**
+ * Tool executor - manages and executes tools
+ */
+declare class ToolExecutor {
+    private tools;
+    constructor(tools?: ToolDefinition[]);
+    /**
+     * Register a tool
+     */
+    register(tool: ToolDefinition): void;
+    /**
+     * Unregister a tool
+     */
+    unregister(name: string): boolean;
+    /**
+     * Get all registered tools
+     */
+    getTools(): ToolDefinition[];
+    /**
+     * Get tools in Groq API format
+     */
+    getToolsForAPI(): Groq.Chat.ChatCompletionTool[];
+    /**
+     * Check if a tool exists
+     */
+    has(name: string): boolean;
+    /**
+     * Execute a tool by name
+     */
+    execute(name: string, params: Record<string, unknown>): Promise<ToolResult>;
+    /**
+     * Execute multiple tool calls in parallel
+     */
+    executeMany(calls: Array<{
+        name: string;
+        params: Record<string, unknown>;
+    }>): Promise<ToolResult[]>;
+    /**
+     * Process tool calls from Groq API response
+     */
+    processToolCalls(toolCalls: Groq.Chat.ChatCompletionMessageToolCall[]): Promise<Array<{
+        toolCallId: string;
+        result: ToolResult;
+    }>>;
+    /**
+     * Format tool results as messages for Groq API
+     */
+    formatToolResultsAsMessages(results: Array<{
+        toolCallId: string;
+        result: ToolResult;
+    }>): Groq.Chat.ChatCompletionToolMessageParam[];
+}
+/**
+ * Create a tool executor with optional initial tools
+ */
+declare function createToolExecutor(tools?: ToolDefinition[]): ToolExecutor;
+
+/**
+ * Create web search tool
+ */
+declare function createWebSearchTool(searchProvider?: DuckDuckGoSearch): ToolDefinition;
+/**
+ * Create URL fetch tool
+ */
+declare function createFetchUrlTool(fetcher?: WebFetcher): ToolDefinition;
+/**
+ * Create RAG query tool
+ */
+declare function createRAGQueryTool(retriever: Retriever): ToolDefinition;
+/**
+ * Create calculator tool
+ */
+declare function createCalculatorTool(): ToolDefinition;
+/**
+ * Create current datetime tool
+ */
+declare function createDateTimeTool(): ToolDefinition;
+/**
+ * Get all built-in tools (except RAG which needs a retriever)
+ */
+declare function getBuiltinTools(): ToolDefinition[];
+
+/**
+ * Text chunking utilities for RAG
+ */
+declare class TextChunker {
+    private options;
+    constructor(options?: Partial<ChunkingOptions>);
+    /**
+     * Chunk text into smaller pieces
+     */
+    chunk(text: string, documentId: string): DocumentChunk[];
+    /**
+     * Fixed-size chunking with overlap
+     */
+    private fixedChunk;
+    /**
+     * Sentence-based chunking
+     */
+    private sentenceChunk;
+    /**
+     * Paragraph-based chunking
+     */
+    private paragraphChunk;
+    /**
+     * Recursive character text splitter (LangChain-style)
+     */
+    private recursiveChunk;
+    private recursiveSplit;
+    /**
+     * Semantic chunking (placeholder - would use embeddings in production)
+     */
+    private semanticChunk;
+}
+/**
+ * Utility function for quick chunking
+ */
+declare function chunkText(text: string, documentId: string, options?: Partial<ChunkingOptions>): DocumentChunk[];
+
+/**
+ * Generate a unique ID
+ */
+declare function generateId(): string;
+/**
+ * Cosine similarity between two vectors
+ */
+declare function cosineSimilarity(a: number[], b: number[]): number;
+/**
+ * Estimate token count (rough approximation)
+ */
+declare function estimateTokens(text: string): number;
+/**
+ * Truncate text to approximate token limit
+ */
+declare function truncateToTokens(text: string, maxTokens: number): string;
+/**
+ * Clean and normalize text
+ */
+declare function cleanText(text: string): string;
+/**
+ * Extract URLs from text
+ */
+declare function extractUrls(text: string): string[];
+/**
+ * Sleep utility
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Retry with exponential backoff
+ */
+declare function retry<T>(fn: () => Promise<T>, options?: {
+    maxRetries?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+}): Promise<T>;
+/**
+ * Create a context string from search results
+ */
+declare function formatContext(results: Array<{
+    content: string;
+    metadata?: Record<string, unknown>;
+}>, options?: {
+    includeMetadata?: boolean;
+    separator?: string;
+}): string;
+/**
+ * Parse JSON safely
+ */
+declare function safeJsonParse<T>(text: string, defaultValue: T): T;
+/**
+ * Batch array into chunks
+ */
+declare function batch<T>(array: T[], size: number): T[][];
+
+export { Agent, type AgentConfig, type AgentMemory, type AgentResult, type AgentStep, BraveSearch, type BrowseOptions, ChromaVectorStore, type ChunkingOptions, type Document, type DocumentChunk, DuckDuckGoSearch, type EmbeddingConfig, type EmbeddingProvider, type EmbeddingResult, type FetchOptions, type FetchResult, GroqEmbeddings, GroqRAG, type GroqRAGConfig, MemoryVectorStore, OpenAIEmbeddings, type RAGChatOptions, type RAGOptions, type RAGResponse, Retriever, type SearchOptions, type SearchProvider, type SearchResult, SerperSearch, TextChunker, type ToolDefinition, ToolExecutor, type ToolResult, type VectorStore, type VectorStoreConfig, type WebConfig, WebFetcher, type WebSearchResult, batch, chunkText, cleanText, cosineSimilarity, createAgent, createCalculatorTool, createDateTimeTool, createEmbeddingProvider, createFetchUrlTool, createFetcher, createRAGQueryTool, createRetriever, createSearchProvider, createToolExecutor, createVectorStore, createWebSearchTool, GroqRAG as default, estimateTokens, extractUrls, formatContext, generateId, getBuiltinTools, retry, safeJsonParse, sleep, truncateToTokens };