@retrivora-ai/rag-engine 0.1.7 → 0.1.9

package/src/core/PluginManager.ts

@@ -0,0 +1,277 @@
+/**
+ * PluginManager — Universal plugin registration and lifecycle management
+ *
+ * Provides a flexible architecture for registering custom vector DBs, LLMs,
+ * and other providers without modifying core code.
+ *
+ * Features:
+ * - Dynamic plugin registration
+ * - Dependency resolution
+ * - Plugin validation
+ * - Lifecycle management
+ */
+
+export interface PluginMetadata {
+  /** Unique identifier (e.g., 'myprovider.vectordb.custom') */
+  id: string;
+  /** Human-readable name */
+  name: string;
+  /** Plugin version */
+  version: string;
+  /** Detailed description */
+  description?: string;
+  /** Author information */
+  author?: string;
+  /** Supported capabilities */
+  capabilities: PluginCapability[];
+  /** Required dependencies (other plugin IDs) */
+  dependencies?: string[];
+}
+
+export type PluginCapability = 'chat' | 'embed' | 'vector-db' | 'reranker' | 'parser';
+
+export interface IPluginProvider {
+  /**
+   * Get plugin metadata
+   */
+  getMetadata(): PluginMetadata;
+
+  /**
+   * Validate configuration for this plugin
+   */
+  validateConfig?(config: Record<string, unknown>): {
+    valid: boolean;
+    errors?: string[];
+  };
+
+  /**
+   * Initialize plugin with configuration
+   */
+  initialize(config: Record<string, unknown>): Promise<void>;
+
+  /**
+   * Check if plugin is ready
+   */
+  isReady(): Promise<boolean>;
+
+  /**
+   * Gracefully shutdown plugin
+   */
+  shutdown(): Promise<void>;
+
+  /**
+   * Get plugin-specific health status
+   */
+  getHealthStatus?(): Promise<{
+    healthy: boolean;
+    details?: Record<string, unknown>;
+  }>;
+}
+
+export interface PluginDescriptor {
+  metadata: PluginMetadata;
+  factory: (config: Record<string, unknown>) => Promise<IPluginProvider>;
+  validateConfig?: (config: Record<string, unknown>) => {
+    valid: boolean;
+    errors?: string[];
+  };
+}
+
+export class PluginManager {
+  private static readonly registeredPlugins: Map<string, PluginDescriptor> = new Map();
+  private static readonly instances: Map<string, IPluginProvider> = new Map();
+
+  /**
+   * Register a new plugin provider
+   */
+  static registerPlugin(descriptor: PluginDescriptor): void {
+    const { metadata } = descriptor;
+
+    if (this.registeredPlugins.has(metadata.id)) {
+      throw new Error(
+        `[PluginManager] Plugin with ID "${metadata.id}" is already registered. ` +
+        `Use unregisterPlugin() first if you need to replace it.`
+      );
+    }
+
+    // Validate metadata
+    if (!metadata.id || !metadata.name || !metadata.version) {
+      throw new Error(
+        '[PluginManager] Plugin metadata must include id, name, and version'
+      );
+    }
+
+    if (metadata.capabilities.length === 0) {
+      throw new Error('[PluginManager] Plugin must declare at least one capability');
+    }
+
+    this.registeredPlugins.set(metadata.id, descriptor);
+    console.log(
+      `[PluginManager] Registered plugin: ${metadata.name} v${metadata.version} (${metadata.id})`
+    );
+  }
+
+  /**
+   * Unregister a plugin and cleanup its instance
+   */
+  static async unregisterPlugin(pluginId: string): Promise<void> {
+    if (this.instances.has(pluginId)) {
+      const instance = this.instances.get(pluginId)!;
+      await instance.shutdown();
+      this.instances.delete(pluginId);
+    }
+
+    this.registeredPlugins.delete(pluginId);
+  }
+
+  /**
+   * Get plugin metadata
+   */
+  static getPluginMetadata(pluginId: string): PluginMetadata | null {
+    return this.registeredPlugins.get(pluginId)?.metadata ?? null;
+  }
+
+  /**
+   * List all registered plugins with optional filtering by capability
+   */
+  static listPlugins(capability?: PluginCapability): PluginMetadata[] {
+    const plugins = Array.from(this.registeredPlugins.values()).map(d => d.metadata);
+
+    if (capability) {
+      return plugins.filter(p => p.capabilities.includes(capability));
+    }
+
+    return plugins;
+  }
+
+  /**
+   * Create and cache a plugin instance with dependency resolution
+   */
+  static async createInstance(
+    pluginId: string,
+    config: Record<string, unknown>
+  ): Promise<IPluginProvider> {
+    // Return cached instance if already created
+    if (this.instances.has(pluginId)) {
+      return this.instances.get(pluginId)!;
+    }
+
+    const descriptor = this.registeredPlugins.get(pluginId);
+    if (!descriptor) {
+      throw new Error(
+        `[PluginManager] Plugin "${pluginId}" not registered. ` +
+        `Registered plugins: ${Array.from(this.registeredPlugins.keys()).join(', ')}`
+      );
+    }
+
+    const { metadata, factory } = descriptor;
+
+    // Validate configuration
+    if (descriptor.validateConfig) {
+      const validation = descriptor.validateConfig(config);
+      if (!validation.valid) {
+        throw new Error(
+          `[PluginManager] Invalid configuration for plugin "${pluginId}": ` +
+          `${validation.errors?.join('; ') || 'Unknown error'}`
+        );
+      }
+    }
+
+    // Resolve dependencies
+    if (metadata.dependencies && metadata.dependencies.length > 0) {
+      for (const depId of metadata.dependencies) {
+        if (!this.instances.has(depId)) {
+          throw new Error(
+            `[PluginManager] Plugin "${pluginId}" requires "${depId}" to be initialized first`
+          );
+        }
+      }
+    }
+
+    // Initialize plugin
+    console.log(`[PluginManager] Initializing plugin: ${pluginId}`);
+    const instance = await factory(config);
+
+    // Verify plugin is ready
+    const isReady = await instance.isReady();
+    if (!isReady) {
+      throw new Error(
+        `[PluginManager] Plugin "${pluginId}" failed to initialize properly`
+      );
+    }
+
+    // Cache instance
+    this.instances.set(pluginId, instance);
+
+    return instance;
+  }
+
+  /**
+   * Get cached instance of a plugin
+   */
+  static getInstance(pluginId: string): IPluginProvider | null {
+    return this.instances.get(pluginId) ?? null;
+  }
+
+  /**
+   * Check if a plugin is ready (either registered or instantiated)
+   */
+  static isPluginAvailable(pluginId: string): boolean {
+    return this.registeredPlugins.has(pluginId) || this.instances.has(pluginId);
+  }
+
+  /**
+   * Shutdown all plugin instances
+   */
+  static async shutdownAll(): Promise<void> {
+    const errors: Error[] = [];
+
+    for (const [pluginId, instance] of this.instances.entries()) {
+      try {
+        await instance.shutdown();
+        console.log(`[PluginManager] Shutdown plugin: ${pluginId}`);
+      } catch (error) {
+        errors.push(
+          new Error(`Failed to shutdown plugin ${pluginId}: ${error instanceof Error ? error.message : String(error)}`)
+        );
+      }
+    }
+
+    this.instances.clear();
+
+    if (errors.length > 0) {
+      throw new AggregateError(errors, '[PluginManager] Errors during shutdown');
+    }
+  }
+
+  /**
+   * Get health status of all instantiated plugins
+   */
+  static async getHealthStatus(): Promise<
+    Map<string, { healthy: boolean; details?: Record<string, unknown> }>
+  > {
+    const status = new Map();
+
+    for (const [pluginId, instance] of this.instances.entries()) {
+      try {
+        const health = await instance.getHealthStatus?.();
+        status.set(pluginId, health ?? { healthy: true });
+      } catch (error) {
+        status.set(pluginId, {
+          healthy: false,
+          details: { error: error instanceof Error ? error.message : String(error) },
+        });
+      }
+    }
+
+    return status;
+  }
+
+  /**
+   * Clear all registered and instantiated plugins (for testing)
+   */
+  static reset(): void {
+    this.registeredPlugins.clear();
+    this.instances.clear();
+  }
+}