@snap-agent/core 0.1.0 → 0.1.3

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-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.mjs';
-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.mjs';
-import { LanguageModel, UserModelMessage, AssistantModelMessage } from 'ai';
+import { P as ProviderConfig, a as ProviderType, b as Plugin, S as StoredPluginConfig, A as AgentData, c as StorageAdapter, d as AgentConfig, e as AgentFile, R as RAGDocument, I as IngestOptions, f as IngestResult, B as BulkOperation, g as BulkResult, U as URLSource, h as URLIngestResult, T as ThreadData, i as ThreadConfig, M as MessageRole, j as MessageAttachment, k as MessageData, C as ClientConfig, l as ChatRequest, m as ChatResponse, n as StreamCallbacks, o as RAGPlugin, p as ToolPlugin, q as MiddlewarePlugin, r as AnalyticsPlugin, s as RAGContext } from './index-m2vDW79n.mjs';
+export { L as AgentNotFoundError, K as AgentSDKError, u as BasePlugin, D as DataTransform, H as ErrorTrackingData, w as IngestionSchedule, Q as InvalidConfigError, W as MemoryStorage, V as MongoDBStorage, Y as MongoDBStorageConfig, y as PerformanceTimings, J as PluginRegistryInterface, O as ProviderNotFoundError, t as RAGConfig, z as RAGMetrics, F as RequestTrackingData, G as ResponseTrackingData, N as ThreadNotFoundError, E as TokenMetrics, x as Tool, v as URLSourceAuth, X as UpstashStorage, Z as UpstashStorageConfig } from './index-m2vDW79n.mjs';
+import { LanguageModel, UserModelMessage, AssistantModelMessage, Schema } from 'ai';
 
 /**
  * Provider factory for creating language model instances
@@ -50,6 +50,118 @@ declare const Models: {
     };
 };
 
+/**
+ * Plugin Registry for serializing/deserializing plugins
+ *
+ * Plugins are runtime objects that can't be stored in a database.
+ * This registry enables:
+ * 1. Storing serializable plugin configurations in MongoDB
+ * 2. Reinstantiating plugins from stored config when loading agents
+ */
+
+/**
+ * Factory function that creates a plugin instance from config
+ */
+type PluginFactory<T extends Plugin = Plugin> = (config: Record<string, any>) => T | Promise<T>;
+/**
+ * Resolves environment variable references in config values
+ * Format: "${ENV_VAR_NAME}" or "${ENV_VAR_NAME:default_value}"
+ *
+ * @example
+ * resolveEnvVars({ apiKey: "${OPENAI_API_KEY}" })
+ * // Returns: { apiKey: "sk-..." } (actual env value)
+ *
+ * @example
+ * resolveEnvVars({ timeout: "${TIMEOUT:5000}" })
+ * // Returns: { timeout: "5000" } (default if env not set)
+ */
+declare function resolveEnvVars(config: Record<string, any>): Record<string, any>;
+/**
+ * Global plugin registry for managing plugin factories
+ *
+ * @example
+ * // Register a plugin factory
+ * pluginRegistry.register('@snap-agent/rag-ecommerce', (config) =>
+ *   new EcommerceRAGPlugin(config)
+ * );
+ *
+ * // Later, instantiate from stored config
+ * const plugin = await pluginRegistry.instantiate({
+ *   type: 'rag',
+ *   name: '@snap-agent/rag-ecommerce',
+ *   config: { mongoUri: '${MONGO_URI}', voyageApiKey: '${VOYAGE_API_KEY}' }
+ * });
+ */
+declare class PluginRegistry {
+    private registrations;
+    /**
+     * Register a plugin factory
+     *
+     * @param name - Unique plugin identifier (e.g., "@snap-agent/rag-ecommerce")
+     * @param factory - Function that creates plugin instance from config
+     * @param defaultConfig - Optional default configuration values
+     */
+    register(name: string, factory: PluginFactory, defaultConfig?: Record<string, any>): void;
+    /**
+     * Unregister a plugin factory
+     */
+    unregister(name: string): boolean;
+    /**
+     * Check if a plugin is registered
+     */
+    isRegistered(name: string): boolean;
+    /**
+     * Get all registered plugin names
+     */
+    getRegisteredPlugins(): string[];
+    /**
+     * Instantiate a plugin from stored configuration
+     *
+     * @param storedConfig - Serialized plugin configuration from database
+     * @returns Plugin instance
+     * @throws Error if plugin is not registered
+     */
+    instantiate(storedConfig: StoredPluginConfig): Promise<Plugin>;
+    /**
+     * Instantiate multiple plugins from stored configurations
+     *
+     * @param storedConfigs - Array of serialized plugin configurations
+     * @returns Array of plugin instances (skips disabled plugins)
+     */
+    instantiateAll(storedConfigs: StoredPluginConfig[]): Promise<Plugin[]>;
+    /**
+     * Extract serializable configuration from a plugin instance
+     * Requires the plugin to implement getConfig() method
+     *
+     * @param plugin - Plugin instance
+     * @returns Stored plugin configuration
+     */
+    extractConfig(plugin: Plugin & {
+        getConfig?: () => Record<string, any>;
+    }): StoredPluginConfig;
+    /**
+     * Extract configurations from multiple plugins
+     */
+    extractAllConfigs(plugins: Array<Plugin & {
+        getConfig?: () => Record<string, any>;
+    }>): StoredPluginConfig[];
+}
+/**
+ * Default global plugin registry instance
+ * Use this for simple setups, or create your own PluginRegistry for isolation
+ */
+declare const pluginRegistry: PluginRegistry;
+/**
+ * Create an env var reference for use in stored plugin configs
+ *
+ * @example
+ * const config = {
+ *   apiKey: envRef('OPENAI_API_KEY'),
+ *   timeout: envRef('TIMEOUT', '5000'),
+ * };
+ */
+declare function envRef(envVarName: string, defaultValue?: string): string;
+
 type AIMessage$1 = UserModelMessage | AssistantModelMessage;
 /**
  * Agent class representing an AI agent with persistent state
@@ -62,12 +174,32 @@ declare class Agent {
     constructor(data: AgentData, storage: StorageAdapter, providerFactory: ProviderFactory);
     /**
      * Create a new agent
+     *
+     * If plugins are provided, their configurations will be extracted (if they implement getConfig())
+     * and stored in the database for later reinstantiation.
      */
     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>;
+     *
+     * Plugins can be attached in three ways (in order of priority):
+     * 1. Direct plugins array - runtime plugin instances passed directly
+     * 2. Plugin registry - reinstantiate from stored configs using registered factories
+     * 3. No plugins - agent loads without plugin functionality
+     *
+     * @param agentId - The agent ID to load
+     * @param storage - Storage adapter
+     * @param providerFactory - Provider factory
+     * @param options - Either:
+     *   - Plugin[] array (legacy, for backwards compatibility)
+     *   - Options object with plugins and/or registry
+     */
+    static load(agentId: string, storage: StorageAdapter, providerFactory: ProviderFactory, options?: Plugin[] | {
+        /** Direct plugin instances to attach */
+        plugins?: Plugin[];
+        /** Registry to reinstantiate plugins from stored configs */
+        registry?: PluginRegistry;
+    }): Promise<Agent | null>;
     /**
      * Update agent properties
      */
@@ -83,12 +215,19 @@ declare class Agent {
     /**
      * Generate a text response with optional plugin support
      */
-    generateResponse(messages: AIMessage$1[], options?: {
+    generateResponse<T = unknown>(messages: AIMessage$1[], options?: {
         useRAG?: boolean;
         ragFilters?: Record<string, any>;
         threadId?: string;
+        output?: {
+            mode: 'json';
+        } | {
+            mode: 'object';
+            schema: Schema<T>;
+        };
     }): Promise<{
         text: string;
+        parsed?: T;
         metadata?: Record<string, any>;
     }>;
     /**
@@ -241,6 +380,7 @@ declare class AgentClient {
     private storage;
     private providerFactory;
     private providers;
+    private pluginRegistry?;
     constructor(config: ClientConfig);
     private validateConfig;
     /**
@@ -251,8 +391,21 @@ declare class AgentClient {
     }): Promise<Agent>;
     /**
      * Get an agent by ID
-     */
-    getAgent(agentId: string): Promise<Agent>;
+     *
+     * Plugin loading priority:
+     * 1. Direct plugins array passed to this method
+     * 2. Plugin registry (if configured) - reinstantiates from stored configs
+     * 3. No plugins
+     *
+     * @param agentId - The agent ID to load
+     * @param options - Either Plugin[] for backwards compatibility, or options object
+     */
+    getAgent(agentId: string, options?: Plugin[] | {
+        /** Direct plugin instances to attach (highest priority) */
+        plugins?: Plugin[];
+        /** Override the client's registry for this call */
+        registry?: PluginRegistry;
+    }): Promise<Agent>;
     /**
      * List agents for a user
      */
@@ -469,4 +622,4 @@ declare class DefaultRAGPlugin implements RAGPlugin {
 
 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 };
+export { Agent, AgentClient, AgentConfig, AgentData, AgentFile, AnalyticsPlugin, BulkOperation, BulkResult, ChatRequest, ChatResponse, ClientConfig, type DefaultRAGConfig, DefaultRAGPlugin, IngestOptions, IngestResult, MessageAttachment, MessageData, MessageRole, MiddlewarePlugin, Models, Plugin, type PluginFactory, PluginManager, PluginRegistry, ProviderConfig, ProviderFactory, ProviderType, RAGContext, RAGDocument, RAGPlugin, StorageAdapter, StoredPluginConfig, StreamCallbacks, Thread, ThreadConfig, ThreadData, ToolPlugin, URLIngestResult, URLSource, createClient, envRef, pluginRegistry, resolveEnvVars };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-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';
+import { P as ProviderConfig, a as ProviderType, b as Plugin, S as StoredPluginConfig, A as AgentData, c as StorageAdapter, d as AgentConfig, e as AgentFile, R as RAGDocument, I as IngestOptions, f as IngestResult, B as BulkOperation, g as BulkResult, U as URLSource, h as URLIngestResult, T as ThreadData, i as ThreadConfig, M as MessageRole, j as MessageAttachment, k as MessageData, C as ClientConfig, l as ChatRequest, m as ChatResponse, n as StreamCallbacks, o as RAGPlugin, p as ToolPlugin, q as MiddlewarePlugin, r as AnalyticsPlugin, s as RAGContext } from './index-m2vDW79n.js';
+export { L as AgentNotFoundError, K as AgentSDKError, u as BasePlugin, D as DataTransform, H as ErrorTrackingData, w as IngestionSchedule, Q as InvalidConfigError, W as MemoryStorage, V as MongoDBStorage, Y as MongoDBStorageConfig, y as PerformanceTimings, J as PluginRegistryInterface, O as ProviderNotFoundError, t as RAGConfig, z as RAGMetrics, F as RequestTrackingData, G as ResponseTrackingData, N as ThreadNotFoundError, E as TokenMetrics, x as Tool, v as URLSourceAuth, X as UpstashStorage, Z as UpstashStorageConfig } from './index-m2vDW79n.js';
+import { LanguageModel, UserModelMessage, AssistantModelMessage, Schema } from 'ai';
 
 /**
  * Provider factory for creating language model instances
@@ -50,6 +50,118 @@ declare const Models: {
     };
 };
 
+/**
+ * Plugin Registry for serializing/deserializing plugins
+ *
+ * Plugins are runtime objects that can't be stored in a database.
+ * This registry enables:
+ * 1. Storing serializable plugin configurations in MongoDB
+ * 2. Reinstantiating plugins from stored config when loading agents
+ */
+
+/**
+ * Factory function that creates a plugin instance from config
+ */
+type PluginFactory<T extends Plugin = Plugin> = (config: Record<string, any>) => T | Promise<T>;
+/**
+ * Resolves environment variable references in config values
+ * Format: "${ENV_VAR_NAME}" or "${ENV_VAR_NAME:default_value}"
+ *
+ * @example
+ * resolveEnvVars({ apiKey: "${OPENAI_API_KEY}" })
+ * // Returns: { apiKey: "sk-..." } (actual env value)
+ *
+ * @example
+ * resolveEnvVars({ timeout: "${TIMEOUT:5000}" })
+ * // Returns: { timeout: "5000" } (default if env not set)
+ */
+declare function resolveEnvVars(config: Record<string, any>): Record<string, any>;
+/**
+ * Global plugin registry for managing plugin factories
+ *
+ * @example
+ * // Register a plugin factory
+ * pluginRegistry.register('@snap-agent/rag-ecommerce', (config) =>
+ *   new EcommerceRAGPlugin(config)
+ * );
+ *
+ * // Later, instantiate from stored config
+ * const plugin = await pluginRegistry.instantiate({
+ *   type: 'rag',
+ *   name: '@snap-agent/rag-ecommerce',
+ *   config: { mongoUri: '${MONGO_URI}', voyageApiKey: '${VOYAGE_API_KEY}' }
+ * });
+ */
+declare class PluginRegistry {
+    private registrations;
+    /**
+     * Register a plugin factory
+     *
+     * @param name - Unique plugin identifier (e.g., "@snap-agent/rag-ecommerce")
+     * @param factory - Function that creates plugin instance from config
+     * @param defaultConfig - Optional default configuration values
+     */
+    register(name: string, factory: PluginFactory, defaultConfig?: Record<string, any>): void;
+    /**
+     * Unregister a plugin factory
+     */
+    unregister(name: string): boolean;
+    /**
+     * Check if a plugin is registered
+     */
+    isRegistered(name: string): boolean;
+    /**
+     * Get all registered plugin names
+     */
+    getRegisteredPlugins(): string[];
+    /**
+     * Instantiate a plugin from stored configuration
+     *
+     * @param storedConfig - Serialized plugin configuration from database
+     * @returns Plugin instance
+     * @throws Error if plugin is not registered
+     */
+    instantiate(storedConfig: StoredPluginConfig): Promise<Plugin>;
+    /**
+     * Instantiate multiple plugins from stored configurations
+     *
+     * @param storedConfigs - Array of serialized plugin configurations
+     * @returns Array of plugin instances (skips disabled plugins)
+     */
+    instantiateAll(storedConfigs: StoredPluginConfig[]): Promise<Plugin[]>;
+    /**
+     * Extract serializable configuration from a plugin instance
+     * Requires the plugin to implement getConfig() method
+     *
+     * @param plugin - Plugin instance
+     * @returns Stored plugin configuration
+     */
+    extractConfig(plugin: Plugin & {
+        getConfig?: () => Record<string, any>;
+    }): StoredPluginConfig;
+    /**
+     * Extract configurations from multiple plugins
+     */
+    extractAllConfigs(plugins: Array<Plugin & {
+        getConfig?: () => Record<string, any>;
+    }>): StoredPluginConfig[];
+}
+/**
+ * Default global plugin registry instance
+ * Use this for simple setups, or create your own PluginRegistry for isolation
+ */
+declare const pluginRegistry: PluginRegistry;
+/**
+ * Create an env var reference for use in stored plugin configs
+ *
+ * @example
+ * const config = {
+ *   apiKey: envRef('OPENAI_API_KEY'),
+ *   timeout: envRef('TIMEOUT', '5000'),
+ * };
+ */
+declare function envRef(envVarName: string, defaultValue?: string): string;
+
 type AIMessage$1 = UserModelMessage | AssistantModelMessage;
 /**
  * Agent class representing an AI agent with persistent state
@@ -62,12 +174,32 @@ declare class Agent {
     constructor(data: AgentData, storage: StorageAdapter, providerFactory: ProviderFactory);
     /**
      * Create a new agent
+     *
+     * If plugins are provided, their configurations will be extracted (if they implement getConfig())
+     * and stored in the database for later reinstantiation.
      */
     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>;
+     *
+     * Plugins can be attached in three ways (in order of priority):
+     * 1. Direct plugins array - runtime plugin instances passed directly
+     * 2. Plugin registry - reinstantiate from stored configs using registered factories
+     * 3. No plugins - agent loads without plugin functionality
+     *
+     * @param agentId - The agent ID to load
+     * @param storage - Storage adapter
+     * @param providerFactory - Provider factory
+     * @param options - Either:
+     *   - Plugin[] array (legacy, for backwards compatibility)
+     *   - Options object with plugins and/or registry
+     */
+    static load(agentId: string, storage: StorageAdapter, providerFactory: ProviderFactory, options?: Plugin[] | {
+        /** Direct plugin instances to attach */
+        plugins?: Plugin[];
+        /** Registry to reinstantiate plugins from stored configs */
+        registry?: PluginRegistry;
+    }): Promise<Agent | null>;
     /**
      * Update agent properties
      */
@@ -83,12 +215,19 @@ declare class Agent {
     /**
      * Generate a text response with optional plugin support
      */
-    generateResponse(messages: AIMessage$1[], options?: {
+    generateResponse<T = unknown>(messages: AIMessage$1[], options?: {
         useRAG?: boolean;
         ragFilters?: Record<string, any>;
         threadId?: string;
+        output?: {
+            mode: 'json';
+        } | {
+            mode: 'object';
+            schema: Schema<T>;
+        };
     }): Promise<{
         text: string;
+        parsed?: T;
         metadata?: Record<string, any>;
     }>;
     /**
@@ -241,6 +380,7 @@ declare class AgentClient {
     private storage;
     private providerFactory;
     private providers;
+    private pluginRegistry?;
     constructor(config: ClientConfig);
     private validateConfig;
     /**
@@ -251,8 +391,21 @@ declare class AgentClient {
     }): Promise<Agent>;
     /**
      * Get an agent by ID
-     */
-    getAgent(agentId: string): Promise<Agent>;
+     *
+     * Plugin loading priority:
+     * 1. Direct plugins array passed to this method
+     * 2. Plugin registry (if configured) - reinstantiates from stored configs
+     * 3. No plugins
+     *
+     * @param agentId - The agent ID to load
+     * @param options - Either Plugin[] for backwards compatibility, or options object
+     */
+    getAgent(agentId: string, options?: Plugin[] | {
+        /** Direct plugin instances to attach (highest priority) */
+        plugins?: Plugin[];
+        /** Override the client's registry for this call */
+        registry?: PluginRegistry;
+    }): Promise<Agent>;
     /**
      * List agents for a user
      */
@@ -469,4 +622,4 @@ declare class DefaultRAGPlugin implements RAGPlugin {
 
 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 };
+export { Agent, AgentClient, AgentConfig, AgentData, AgentFile, AnalyticsPlugin, BulkOperation, BulkResult, ChatRequest, ChatResponse, ClientConfig, type DefaultRAGConfig, DefaultRAGPlugin, IngestOptions, IngestResult, MessageAttachment, MessageData, MessageRole, MiddlewarePlugin, Models, Plugin, type PluginFactory, PluginManager, PluginRegistry, ProviderConfig, ProviderFactory, ProviderType, RAGContext, RAGDocument, RAGPlugin, StorageAdapter, StoredPluginConfig, StreamCallbacks, Thread, ThreadConfig, ThreadData, ToolPlugin, URLIngestResult, URLSource, createClient, envRef, pluginRegistry, resolveEnvVars };