@snap-agent/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,472 @@
+import { P as ProviderConfig, a as ProviderType, A as AgentData, S as StorageAdapter, b as AgentConfig, c as AgentFile, d as Plugin, R as RAGDocument, I as IngestOptions, e as IngestResult, B as BulkOperation, f as BulkResult, U as URLSource, g as URLIngestResult, T as ThreadData, h as ThreadConfig, M as MessageRole, i as MessageAttachment, j as MessageData, C as ClientConfig, k as ChatRequest, l as ChatResponse, m as StreamCallbacks, n as RAGPlugin, o as ToolPlugin, p as MiddlewarePlugin, q as AnalyticsPlugin, r as RAGContext } from './index-CDsqnM8L.js';
+export { F as AgentNotFoundError, D as AgentSDKError, t as BasePlugin, E as ErrorTrackingData, J as InvalidConfigError, L as MemoryStorage, K as MongoDBStorage, O as MongoDBStorageConfig, v as PerformanceTimings, H as ProviderNotFoundError, s as RAGConfig, w as RAGMetrics, y as RequestTrackingData, z as ResponseTrackingData, G as ThreadNotFoundError, x as TokenMetrics, u as Tool, N as UpstashStorage, Q as UpstashStorageConfig } from './index-CDsqnM8L.js';
+import { LanguageModel, UserModelMessage, AssistantModelMessage } from 'ai';
+
+/**
+ * Provider factory for creating language model instances
+ * Supports OpenAI, Anthropic, and Google providers via Vercel AI SDK
+ */
+declare class ProviderFactory {
+    private config;
+    private modelCache;
+    constructor(config: ProviderConfig);
+    /**
+     * Get a language model for the specified provider and model
+     * Uses dynamic imports for edge runtime compatibility
+     */
+    getModel(provider: ProviderType, modelName: string): Promise<LanguageModel>;
+    /**
+     * Check if a provider is configured
+     */
+    isProviderConfigured(provider: ProviderType): boolean;
+    /**
+     * Get list of configured providers
+     */
+    getConfiguredProviders(): ProviderType[];
+    /**
+     * Clear the model cache
+     */
+    clearCache(): void;
+}
+/**
+ * Common model names for quick reference
+ */
+declare const Models: {
+    readonly OpenAI: {
+        readonly GPT4O: "gpt-4o";
+        readonly GPT4O_MINI: "gpt-4o-mini";
+        readonly GPT4_TURBO: "gpt-4-turbo";
+        readonly GPT35_TURBO: "gpt-3.5-turbo";
+    };
+    readonly Anthropic: {
+        readonly CLAUDE_35_SONNET: "claude-3-5-sonnet-20241022";
+        readonly CLAUDE_35_HAIKU: "claude-3-5-haiku-20241022";
+        readonly CLAUDE_3_OPUS: "claude-3-opus-20240229";
+    };
+    readonly Google: {
+        readonly GEMINI_2_FLASH: "gemini-2.0-flash-exp";
+        readonly GEMINI_15_PRO: "gemini-1.5-pro";
+        readonly GEMINI_15_FLASH: "gemini-1.5-flash";
+    };
+};
+
+type AIMessage$1 = UserModelMessage | AssistantModelMessage;
+/**
+ * Agent class representing an AI agent with persistent state
+ */
+declare class Agent {
+    private data;
+    private storage;
+    private providerFactory;
+    private pluginManager;
+    constructor(data: AgentData, storage: StorageAdapter, providerFactory: ProviderFactory);
+    /**
+     * Create a new agent
+     */
+    static create(config: AgentConfig, storage: StorageAdapter, providerFactory: ProviderFactory): Promise<Agent>;
+    /**
+     * Load an existing agent by ID
+     */
+    static load(agentId: string, storage: StorageAdapter, providerFactory: ProviderFactory): Promise<Agent | null>;
+    /**
+     * Update agent properties
+     */
+    update(updates: Partial<AgentConfig>): Promise<void>;
+    /**
+     * Delete this agent
+     */
+    delete(): Promise<void>;
+    /**
+     * Add files to the agent
+     */
+    addFiles(files: AgentFile[]): Promise<void>;
+    /**
+     * Generate a text response with optional plugin support
+     */
+    generateResponse(messages: AIMessage$1[], options?: {
+        useRAG?: boolean;
+        ragFilters?: Record<string, any>;
+        threadId?: string;
+    }): Promise<{
+        text: string;
+        metadata?: Record<string, any>;
+    }>;
+    /**
+     * Stream a text response with optional plugin support
+     */
+    streamResponse(messages: AIMessage$1[], onChunk: (chunk: string) => void, onComplete?: (fullText: string, metadata?: Record<string, any>) => void, onError?: (error: Error) => void, options?: {
+        useRAG?: boolean;
+        ragFilters?: Record<string, any>;
+        threadId?: string;
+    }): Promise<void>;
+    /**
+     * Get agent ID
+     */
+    get id(): string;
+    /**
+     * Get agent name
+     */
+    get name(): string;
+    /**
+     * Get agent instructions
+     */
+    get instructions(): string;
+    /**
+     * Get agent provider
+     */
+    get provider(): string;
+    /**
+     * Get agent model
+     */
+    get model(): string;
+    /**
+     * Get all plugins attached to this agent
+     */
+    get plugins(): Plugin[];
+    /**
+     * Add a plugin to this agent
+     */
+    addPlugin(plugin: Plugin): void;
+    /**
+     * Remove a plugin by name
+     */
+    removePlugin(pluginName: string): void;
+    /**
+     * Get all agent data
+     */
+    toJSON(): AgentData;
+    /**
+     * Ingest documents into RAG plugins
+     * Documents will be ingested into all RAG plugins that support ingestion
+     */
+    ingestDocuments(documents: RAGDocument[], options?: IngestOptions): Promise<IngestResult[]>;
+    /**
+     * Update a document in RAG plugins
+     */
+    updateDocument(id: string, document: Partial<RAGDocument>, options?: IngestOptions): Promise<void>;
+    /**
+     * Delete documents from RAG plugins
+     */
+    deleteDocuments(ids: string | string[], options?: IngestOptions): Promise<number>;
+    /**
+     * Perform bulk operations on RAG plugins
+     */
+    bulkDocumentOperations(operations: BulkOperation[], options?: IngestOptions): Promise<BulkResult[]>;
+    /**
+     * Ingest documents from a URL source (CSV, JSON, XML, API)
+     * Supports authentication, scheduling, and data transformation
+     */
+    ingestFromUrl(source: URLSource, options?: IngestOptions): Promise<URLIngestResult[]>;
+    /**
+     * Handle webhook payload for real-time document updates
+     * Useful for product inventory updates, price changes, etc.
+     */
+    handleWebhook(payload: any, source: string, options?: IngestOptions): Promise<IngestResult[]>;
+}
+
+type AIMessage = UserModelMessage | AssistantModelMessage;
+/**
+ * Thread class representing a conversation thread
+ */
+declare class Thread {
+    private data;
+    private storage;
+    constructor(data: ThreadData, storage: StorageAdapter);
+    /**
+     * Create a new thread
+     */
+    static create(config: ThreadConfig, storage: StorageAdapter): Promise<Thread>;
+    /**
+     * Load an existing thread by ID
+     */
+    static load(threadId: string, storage: StorageAdapter): Promise<Thread | null>;
+    /**
+     * Update thread properties
+     */
+    update(updates: Partial<ThreadConfig>): Promise<void>;
+    /**
+     * Delete this thread
+     */
+    delete(): Promise<void>;
+    /**
+     * Add a message to the thread
+     */
+    addMessage(role: MessageRole, content: string, attachments?: MessageAttachment[]): Promise<string>;
+    /**
+     * Get messages from this thread
+     */
+    getMessages(limit?: number): Promise<MessageData[]>;
+    /**
+     * Get conversation context for AI (formatted for Vercel AI SDK)
+     */
+    getConversationContext(maxMessages?: number): Promise<AIMessage[]>;
+    /**
+     * Update thread name
+     */
+    updateName(name: string): Promise<void>;
+    /**
+     * Update pending status
+     */
+    updatePendingStatus(isPending: boolean): Promise<void>;
+    /**
+     * Get thread ID
+     */
+    get id(): string;
+    /**
+     * Get thread name
+     */
+    get name(): string | undefined;
+    /**
+     * Get agent ID
+     */
+    get agentId(): string;
+    /**
+     * Get messages (cached from last load)
+     */
+    get messages(): MessageData[];
+    /**
+     * Check if thread is pending
+     */
+    get isPending(): boolean;
+    /**
+     * Get all thread data
+     */
+    toJSON(): ThreadData;
+}
+
+/**
+ * Main SDK Client for managing AI agents and conversations
+ */
+declare class AgentClient {
+    private storage;
+    private providerFactory;
+    private providers;
+    constructor(config: ClientConfig);
+    private validateConfig;
+    /**
+     * Create a new agent
+     */
+    createAgent(config: Omit<AgentConfig, 'provider'> & {
+        provider?: AgentConfig['provider'];
+    }): Promise<Agent>;
+    /**
+     * Get an agent by ID
+     */
+    getAgent(agentId: string): Promise<Agent>;
+    /**
+     * List agents for a user
+     */
+    listAgents(userId: string, organizationId?: string): Promise<AgentData[]>;
+    /**
+     * Delete an agent
+     */
+    deleteAgent(agentId: string): Promise<void>;
+    /**
+     * Create a new thread
+     */
+    createThread(config: ThreadConfig): Promise<Thread>;
+    /**
+     * Get a thread by ID
+     */
+    getThread(threadId: string | undefined): Promise<Thread>;
+    /**
+     * List threads by user or agent
+     */
+    listThreads(filters: {
+        userId?: string;
+        agentId?: string;
+        organizationId?: string;
+    }): Promise<ThreadData[]>;
+    /**
+     * Delete a thread
+     */
+    deleteThread(threadId: string): Promise<void>;
+    /**
+     * Send a message and get a response (non-streaming)
+     */
+    chat(request: ChatRequest): Promise<ChatResponse>;
+    /**
+     * Send a message and stream the response
+     */
+    chatStream(request: ChatRequest, callbacks: StreamCallbacks): Promise<void>;
+    /**
+     * Generate a name for a thread based on its first message
+     */
+    generateThreadName(firstMessage: string): Promise<string>;
+    /**
+     * Get list of configured providers
+     */
+    getConfiguredProviders(): ProviderType[];
+    /**
+     * Check if a provider is configured
+     */
+    isProviderConfigured(provider: string): boolean;
+}
+
+/**
+ * Plugin Manager
+ * Manages and orchestrates plugin execution for agents
+ */
+declare class PluginManager {
+    private plugins;
+    constructor(plugins?: Plugin[]);
+    getRAGPlugins(): RAGPlugin[];
+    getToolPlugins(): ToolPlugin[];
+    getMiddlewarePlugins(): MiddlewarePlugin[];
+    getAnalyticsPlugins(): AnalyticsPlugin[];
+    getAllPlugins(): Plugin[];
+    /**
+     * Execute all RAG plugins and merge their contexts
+     * Returns an array of context strings, one per plugin
+     */
+    executeRAG(message: string, options: {
+        agentId: string;
+        threadId?: string;
+        filters?: Record<string, any>;
+        metadata?: Record<string, any>;
+    }): Promise<{
+        contexts: string[];
+        allMetadata: Record<string, any>[];
+    }>;
+    /**
+     * Execute all middleware plugins before request
+     */
+    executeBeforeRequest(messages: any[], context: {
+        agentId: string;
+        threadId?: string;
+    }): Promise<{
+        messages: any[];
+        metadata?: any;
+    }>;
+    /**
+     * Execute all middleware plugins after response
+     */
+    executeAfterResponse(response: string, context: {
+        agentId: string;
+        threadId?: string;
+        metadata?: any;
+    }): Promise<{
+        response: string;
+        metadata?: any;
+    }>;
+    /**
+     * Track request in all analytics plugins
+     */
+    trackRequest(data: {
+        agentId: string;
+        threadId?: string;
+        message: string;
+        timestamp: Date;
+    }): Promise<void>;
+    /**
+     * Track response in all analytics plugins
+     */
+    trackResponse(data: {
+        agentId: string;
+        threadId?: string;
+        response: string;
+        latency: number;
+        tokensUsed?: number;
+        timestamp: Date;
+    }): Promise<void>;
+    /**
+     * Check if any plugins of a specific type exist
+     */
+    hasPluginsOfType(type: Plugin['type']): boolean;
+    /**
+     * Get plugin by name
+     */
+    getPluginByName(name: string): Plugin | undefined;
+}
+
+/**
+ * Configuration for the default RAG plugin
+ */
+interface DefaultRAGConfig {
+    /**
+     * API key for the embedding provider
+     */
+    embeddingProviderApiKey: string;
+    /**
+     * Embedding provider to use
+     * @default 'openai'
+     */
+    embeddingProvider?: 'openai';
+    /**
+     * OpenAI embedding model
+     * @default 'text-embedding-3-small'
+     */
+    embeddingModel?: string;
+    /**
+     * Number of results to return from search
+     * @default 5
+     */
+    limit?: number;
+}
+/**
+ * Default RAG Plugin
+ *
+ * A minimal, zero-config RAG plugin that provides basic document storage,
+ * embedding generation, and semantic search capabilities.
+ *
+ * Features:
+ * - In-memory vector storage (for simplicity)
+ * - OpenAI embeddings
+ * - Cosine similarity search
+ * - Simple ingestion and retrieval
+ *
+ * For production use cases with advanced features (attribute extraction,
+ * rescoring, reranking, etc.), use specialized plugins like @snap-agent/rag-ecommerce
+ */
+declare class DefaultRAGPlugin implements RAGPlugin {
+    name: string;
+    type: "rag";
+    private config;
+    private documents;
+    constructor(config: DefaultRAGConfig);
+    /**
+     * Retrieve context for a message using semantic search
+     */
+    retrieveContext(message: string, options: {
+        agentId: string;
+        threadId?: string;
+        filters?: Record<string, any>;
+        metadata?: Record<string, any>;
+    }): Promise<RAGContext>;
+    /**
+     * Ingest documents into the RAG system
+     */
+    ingest(documents: RAGDocument[], options?: IngestOptions): Promise<IngestResult>;
+    /**
+     * Update a single document
+     */
+    update(id: string, document: Partial<RAGDocument>, options?: IngestOptions): Promise<void>;
+    /**
+     * Delete document(s) by ID
+     */
+    delete(ids: string | string[], options?: IngestOptions): Promise<number>;
+    /**
+     * Generate embedding using OpenAI
+     */
+    private generateEmbedding;
+    /**
+     * Calculate cosine similarity between two vectors
+     */
+    private cosineSimilarity;
+    /**
+     * Get statistics about stored documents
+     */
+    getStats(): Record<string, any>;
+    /**
+     * Clear all documents for an agent
+     */
+    clearAgent(agentId: string): void;
+    /**
+     * Clear all documents
+     */
+    clearAll(): void;
+}
+
+declare function createClient(config: ClientConfig): AgentClient;
+
+export { Agent, AgentClient, AgentConfig, AgentData, AgentFile, AnalyticsPlugin, BulkOperation, BulkResult, ChatRequest, ChatResponse, ClientConfig, type DefaultRAGConfig, DefaultRAGPlugin, IngestOptions, IngestResult, MessageAttachment, MessageData, MessageRole, MiddlewarePlugin, Models, Plugin, PluginManager, ProviderConfig, ProviderFactory, ProviderType, RAGContext, RAGDocument, RAGPlugin, StorageAdapter, StreamCallbacks, Thread, ThreadConfig, ThreadData, ToolPlugin, createClient };