@juspay/neurolink 9.1.1 → 9.3.0

package/dist/core/baseProvider.d.ts

@@ -1,12 +1,12 @@
-import type { ValidationSchema } from "../types/typeAliases.js";
-import type { Tool, LanguageModelV1, CoreMessage } from "ai";
-import type { AIProvider, TextGenerationOptions, TextGenerationResult, EnhancedGenerateResult, AnalyticsData } from "../types/index.js";
-import { AIProviderName } from "../constants/enums.js";
+import type { CoreMessage, LanguageModelV1, Tool } from "ai";
+import type { AIProviderName } from "../constants/enums.js";
 import type { EvaluationData } from "../index.js";
+import type { NeuroLink } from "../neurolink.js";
+import type { UnknownRecord } from "../types/common.js";
+import type { AIProvider, AnalyticsData, EnhancedGenerateResult, TextGenerationOptions, TextGenerationResult } from "../types/index.js";
 import type { MiddlewareFactoryOptions } from "../types/middlewareTypes.js";
 import type { StreamOptions, StreamResult } from "../types/streamTypes.js";
-import type { UnknownRecord } from "../types/common.js";
-import type { NeuroLink } from "../neurolink.js";
+import type { ValidationSchema } from "../types/typeAliases.js";
 import { TelemetryHandler } from "./modules/TelemetryHandler.js";
 /**
  * Abstract base class for all AI providers
@@ -50,6 +50,14 @@ export declare abstract class BaseProvider implements AIProvider {
      * Prepare generation context including tools and model
      */
     private prepareGenerationContext;
+    /**
+     * Get merged tools for streaming: combines base tools (MCP/built-in) with
+     * user-provided tools (e.g., RAG tools passed via options.tools).
+     *
+     * This is the canonical tool-merge pattern for executeStream() implementations.
+     * All providers should call this instead of getAllTools() directly.
+     */
+    protected getToolsForStream(options: StreamOptions | TextGenerationOptions): Promise<Record<string, Tool>>;
     /**
      * Build messages array for generation - delegated to MessageBuilder
      */
@@ -119,6 +127,35 @@ export declare abstract class BaseProvider implements AIProvider {
      * Ensures existing scripts using createAIProvider().generateText() continue to work
      */
     generateText(options: TextGenerationOptions): Promise<TextGenerationResult>;
+    /**
+     * Generate embeddings for text
+     *
+     * This is a default implementation that throws an error.
+     * Providers that support embeddings (OpenAI, Google Vertex, Amazon Bedrock)
+     * should override this method with their specific implementation.
+     *
+     * @param text - The text to embed
+     * @param _modelName - Optional embedding model name (provider-specific)
+     * @returns Promise resolving to the embedding vector (array of numbers)
+     * @throws Error if the provider does not support embeddings
+     *
+     * @example
+     * ```typescript
+     * const provider = await ProviderFactory.createProvider('openai', 'text-embedding-3-small');
+     * const embedding = await provider.embed('Hello world');
+     * console.log(embedding); // [0.123, -0.456, ...]
+     * ```
+     */
+    embed(text: string, _modelName?: string): Promise<number[]>;
+    /**
+     * Get the default embedding model for this provider
+     *
+     * Override in subclasses to provide provider-specific defaults.
+     * Returns undefined for providers that don't support embeddings.
+     *
+     * @returns The default embedding model name, or undefined if not supported
+     */
+    protected getDefaultEmbeddingModel(): string | undefined;
     /**
      * Provider-specific streaming implementation (only used when tools are disabled)
      */
@@ -256,30 +293,6 @@ export declare abstract class BaseProvider implements AIProvider {
      * ```
      */
     private handleVideoGeneration;
-    /**
-     * Handle PPT generation mode
-     *
-     * Generates a complete PowerPoint presentation using AI content planning
-     * and slide generation. This method orchestrates:
-     * 1. Input validation
-     * 2. Content planning via AI
-     * 3. Individual slide generation (with optional images)
-     * 4. PPTX assembly and file output
-     *
-     * @param options - Text generation options with PPT config
-     * @param startTime - Generation start timestamp for metrics
-     * @returns Enhanced result with PPT data
-     *
-     * @example
-     * ```typescript
-     * const result = await provider.generate({
-     *   input: { text: "Introducing Our New Product" },
-     *   output: { mode: "ppt", ppt: { pages: 10, theme: "modern" } }
-     * });
-     * // result.ppt contains the generated presentation info
-     * ```
-     */
-    private handlePPTGeneration;
     /**
      * Create analytics - delegated to TelemetryHandler
      */

package/dist/core/baseProvider.js

@@ -1,20 +1,18 @@
-import { generateText } from "ai";
-import { AIProviderName } from "../constants/enums.js";
+import { directAgentTools } from "../agent/directTools.js";
+import { IMAGE_GENERATION_MODELS } from "../core/constants.js";
 import { MiddlewareFactory } from "../middleware/factory.js";
 import { logger } from "../utils/logger.js";
-import { IMAGE_GENERATION_MODELS } from "../core/constants.js";
-import { directAgentTools } from "../agent/directTools.js";
 import { createTimeoutController, TimeoutError } from "../utils/timeout.js";
 import { shouldDisableBuiltinTools } from "../utils/toolUtils.js";
-import { getKeysAsString, getKeyCount } from "../utils/transformationUtils.js";
+import { getKeyCount, getKeysAsString } from "../utils/transformationUtils.js";
+import { TTSProcessor } from "../utils/ttsProcessor.js";
+import { GenerationHandler } from "./modules/GenerationHandler.js";
 // Import modules for composition
 import { MessageBuilder } from "./modules/MessageBuilder.js";
 import { StreamHandler } from "./modules/StreamHandler.js";
-import { GenerationHandler } from "./modules/GenerationHandler.js";
 import { TelemetryHandler } from "./modules/TelemetryHandler.js";
-import { Utilities } from "./modules/Utilities.js";
 import { ToolsManager } from "./modules/ToolsManager.js";
-import { TTSProcessor } from "../utils/ttsProcessor.js";
+import { Utilities } from "./modules/Utilities.js";
 /**
  * Abstract base class for all AI providers
  * Tools are integrated as first-class citizens - always available by default
@@ -75,7 +73,7 @@ export class BaseProvider {
      * When tools are involved, falls back to generate() with synthetic streaming
      */
     async stream(optionsOrPrompt, analysisSchema) {
-        const options = this.normalizeStreamOptions(optionsOrPrompt);
+        let options = this.normalizeStreamOptions(optionsOrPrompt);
         logger.info(`Starting stream`, {
             provider: this.providerName,
             hasTools: !options.disableTools && this.supportsTools(),
@@ -98,6 +96,22 @@ export class BaseProvider {
             // Skip real streaming, go directly to fake streaming
             return await this.executeFakeStreaming(options, analysisSchema);
         }
+        // Central tool merge: Pre-merge base tools (MCP/built-in) with user-provided
+        // tools (e.g. RAG tools) into options.tools. This way, every provider's
+        // executeStream() can simply use options.tools (or getAllTools() + options.tools)
+        // and get the complete tool set without needing per-provider merge logic.
+        if (!options.disableTools && this.supportsTools()) {
+            const baseTools = await this.getAllTools();
+            const externalTools = (options.tools || {});
+            const mergedTools = { ...baseTools, ...externalTools };
+            options = { ...options, tools: mergedTools };
+            logger.debug(`Central tool merge for stream`, {
+                provider: this.providerName,
+                baseToolCount: Object.keys(baseTools).length,
+                externalToolCount: Object.keys(externalTools).length,
+                totalToolCount: Object.keys(mergedTools).length,
+            });
+        }
         // CRITICAL FIX: Always prefer real streaming over fake streaming
         // Try real streaming first, use fake streaming only as fallback
         try {
@@ -148,6 +162,7 @@ export class BaseProvider {
                 systemPrompt: options.systemPrompt,
                 temperature: options.temperature,
                 maxTokens: options.maxTokens,
+                tools: options.tools, // 🔧 FIX: Pass user-provided tools (including RAG tools) to generation pipeline
                 disableTools: false,
                 maxSteps: options.maxSteps || 5,
                 provider: options.provider,
@@ -265,6 +280,29 @@ export class BaseProvider {
         const model = await this.getAISDKModelWithMiddleware(options);
         return { tools, model };
     }
+    /**
+     * Get merged tools for streaming: combines base tools (MCP/built-in) with
+     * user-provided tools (e.g., RAG tools passed via options.tools).
+     *
+     * This is the canonical tool-merge pattern for executeStream() implementations.
+     * All providers should call this instead of getAllTools() directly.
+     */
+    async getToolsForStream(options) {
+        const shouldUseTools = !options.disableTools && this.supportsTools();
+        if (!shouldUseTools) {
+            return {};
+        }
+        const baseTools = await this.getAllTools();
+        const externalTools = (options.tools || {});
+        const merged = { ...baseTools, ...externalTools };
+        logger.debug(`Tools prepared for streaming`, {
+            provider: this.providerName,
+            baseToolCount: Object.keys(baseTools).length,
+            externalToolCount: Object.keys(externalTools).length,
+            totalToolCount: Object.keys(merged).length,
+        });
+        return merged;
+    }
     /**
      * Build messages array for generation - delegated to MessageBuilder
      */
@@ -346,15 +384,9 @@ export class BaseProvider {
         try {
             // ===== VIDEO GENERATION MODE =====
             // Generate video from image + prompt using Veo 3.1
-            if (options.output?.mode === "video" || options.output?.video) {
+            if (options.output?.mode === "video") {
                 return await this.handleVideoGeneration(options, startTime);
             }
-            // ===== PPT GENERATION MODE =====
-            // Generate PowerPoint presentation from topic using AI content planning
-            // Triggered by mode="ppt" OR presence of ppt config block
-            if (options.output?.mode === "ppt" || options.output?.ppt) {
-                return await this.handlePPTGeneration(options, startTime);
-            }
             // ===== IMAGE GENERATION MODE =====
             // Route to executeImageGeneration for image generation models
             const isImageModel = IMAGE_GENERATION_MODELS.some((m) => this.modelName.includes(m));
@@ -485,6 +517,46 @@ export class BaseProvider {
             audio: result.audio,
         };
     }
+    /**
+     * Generate embeddings for text
+     *
+     * This is a default implementation that throws an error.
+     * Providers that support embeddings (OpenAI, Google Vertex, Amazon Bedrock)
+     * should override this method with their specific implementation.
+     *
+     * @param text - The text to embed
+     * @param _modelName - Optional embedding model name (provider-specific)
+     * @returns Promise resolving to the embedding vector (array of numbers)
+     * @throws Error if the provider does not support embeddings
+     *
+     * @example
+     * ```typescript
+     * const provider = await ProviderFactory.createProvider('openai', 'text-embedding-3-small');
+     * const embedding = await provider.embed('Hello world');
+     * console.log(embedding); // [0.123, -0.456, ...]
+     * ```
+     */
+    async embed(text, _modelName) {
+        logger.warn(`embed() called on ${this.providerName} which does not have a native implementation`, {
+            textLength: text.length,
+        });
+        throw new Error(`Embedding generation is not supported by the ${this.providerName} provider. ` +
+            `Supported providers: openai, vertex/google, bedrock. ` +
+            `Use an embedding model like text-embedding-3-small (OpenAI), text-embedding-004 (Vertex), ` +
+            `or amazon.titan-embed-text-v2:0 (Bedrock).`);
+    }
+    /**
+     * Get the default embedding model for this provider
+     *
+     * Override in subclasses to provide provider-specific defaults.
+     * Returns undefined for providers that don't support embeddings.
+     *
+     * @returns The default embedding model name, or undefined if not supported
+     */
+    getDefaultEmbeddingModel() {
+        // Default implementation returns undefined - providers override this
+        return undefined;
+    }
     /**
      * Get AI SDK model with middleware applied
      * This method wraps the base model with any configured middleware
@@ -688,21 +760,14 @@ export class BaseProvider {
     }
     async enhanceResult(result, options, startTime) {
         const responseTime = Date.now() - startTime;
+        // CRITICAL FIX: Store imageOutput separately to ensure it's preserved
         const imageOutput = result.imageOutput;
-        const ppt = result.ppt;
-        const video = result.video;
         let enhancedResult = { ...result };
         if (options.enableAnalytics) {
             try {
                 const analytics = await this.createAnalytics(result, responseTime, options);
-                // Preserve ALL fields when adding analytics
-                enhancedResult = {
-                    ...enhancedResult,
-                    analytics,
-                    imageOutput,
-                    ppt,
-                    video,
-                };
+                // Preserve ALL fields including imageOutput when adding analytics
+                enhancedResult = { ...enhancedResult, analytics, imageOutput };
             }
             catch (error) {
                 logger.warn(`Analytics creation failed for ${this.providerName}:`, error);
@@ -711,28 +776,17 @@ export class BaseProvider {
         if (options.enableEvaluation) {
             try {
                 const evaluation = await this.createEvaluation(result, options);
-                // Preserve ALL fields when adding evaluation
-                enhancedResult = {
-                    ...enhancedResult,
-                    evaluation,
-                    imageOutput,
-                    ppt,
-                    video,
-                };
+                // Preserve ALL fields including imageOutput when adding evaluation
+                enhancedResult = { ...enhancedResult, evaluation, imageOutput };
             }
             catch (error) {
                 logger.warn(`Evaluation creation failed for ${this.providerName}:`, error);
             }
         }
+        // CRITICAL FIX: Always restore imageOutput if it existed in the original result
         if (imageOutput) {
             enhancedResult.imageOutput = imageOutput;
         }
-        if (ppt) {
-            enhancedResult.ppt = ppt;
-        }
-        if (video) {
-            enhancedResult.video = video;
-        }
         return enhancedResult;
     }
     /**
@@ -875,7 +929,10 @@ export class BaseProvider {
         // Validate image format and size (for Buffer inputs)
         const imageValidation = validateImageForVideo(imageBuffer);
         if (imageValidation) {
-            throw ErrorFactory.invalidParameters("video-generation", new Error(imageValidation.message), { field: "input.images[0]", validation: imageValidation });
+            throw ErrorFactory.invalidParameters("video-generation", new Error(imageValidation.message), {
+                field: "input.images[0]",
+                validation: imageValidation,
+            });
         }
         // Get prompt text
         const prompt = options.prompt || options.input?.text || "";
@@ -904,103 +961,6 @@ export class BaseProvider {
         };
         return await this.enhanceResult(baseResult, options, startTime);
     }
-    /**
-     * Handle PPT generation mode
-     *
-     * Generates a complete PowerPoint presentation using AI content planning
-     * and slide generation. This method orchestrates:
-     * 1. Input validation
-     * 2. Content planning via AI
-     * 3. Individual slide generation (with optional images)
-     * 4. PPTX assembly and file output
-     *
-     * @param options - Text generation options with PPT config
-     * @param startTime - Generation start timestamp for metrics
-     * @returns Enhanced result with PPT data
-     *
-     * @example
-     * ```typescript
-     * const result = await provider.generate({
-     *   input: { text: "Introducing Our New Product" },
-     *   output: { mode: "ppt", ppt: { pages: 10, theme: "modern" } }
-     * });
-     * // result.ppt contains the generated presentation info
-     * ```
-     */
-    async handlePPTGeneration(options, startTime) {
-        // Dynamic imports to avoid loading PPT dependencies unless needed
-        const { generatePresentation } = await import("../features/ppt/presentationOrchestrator.js");
-        const { PPT_GENERATION_TIMEOUT_MS } = await import("../features/ppt/constants.js");
-        const { validatePPTGenerationInput } = await import("../utils/parameterValidation.js");
-        const { ErrorFactory, withTimeout } = await import("../utils/errorHandling.js");
-        const { extractPPTContext, getEffectivePPTProvider } = await import("../features/ppt/utils.js");
-        // Get effective PPT provider (handles validation and auto-selection)
-        const effective = await getEffectivePPTProvider(this, this.providerName, this.modelName, this.neurolink);
-        // Build input from prompt or input.text (preserve images for logo)
-        const inputText = options.input?.text || options.prompt || "";
-        const generateOptions = {
-            input: {
-                text: inputText,
-                images: options.input?.images, // Pass through images for logo
-            },
-            output: options.output,
-            provider: effective.providerName,
-            model: options.model,
-        };
-        // Validate PPT generation input
-        const validation = validatePPTGenerationInput(generateOptions);
-        if (!validation.isValid) {
-            const errorMessages = validation.errors.map((e) => e.message).join("; ");
-            throw ErrorFactory.invalidParameters("ppt-generation", new Error(errorMessages), { errors: validation.errors });
-        }
-        // Log warnings
-        for (const warning of validation.warnings) {
-            logger.warn(`PPT generation warning: ${warning}`);
-        }
-        // Extract context with all PPT options (including images for logo)
-        const context = extractPPTContext({
-            input: {
-                text: inputText,
-                images: options.input?.images, // Pass through images for logo
-            },
-            output: generateOptions.output,
-            provider: effective.providerName,
-            model: effective.modelName,
-        });
-        logger.info("Starting PPT generation", {
-            provider: effective.providerName,
-            model: effective.modelName,
-            topic: context.topic.substring(0, 100),
-            pages: context.pages,
-            theme: context.theme,
-            generateAIImages: context.generateAIImages,
-        });
-        // Generate presentation using orchestrator (with timeout)
-        const pptResult = await withTimeout(generatePresentation({
-            context,
-            provider: effective.provider,
-            providerName: effective.providerName,
-            modelName: effective.modelName,
-            neurolink: this.neurolink,
-            imageProvider: effective.providerName,
-            imageModel: effective.modelName,
-        }), PPT_GENERATION_TIMEOUT_MS, ErrorFactory.toolTimeout("pptGeneration", PPT_GENERATION_TIMEOUT_MS));
-        logger.info("PPT generation complete", {
-            filePath: pptResult.filePath,
-            totalSlides: pptResult.totalSlides,
-            processingTime: Date.now() - startTime,
-        });
-        // Ensure we always have model name - fallback to this provider's modelName or default
-        const finalModelName = effective.modelName || this.modelName || this.getDefaultModel();
-        // Build result
-        return await this.enhanceResult({
-            content: context.topic,
-            provider: effective.providerName,
-            model: finalModelName,
-            usage: { input: 0, output: 0, total: 0 },
-            ppt: pptResult,
-        }, options, startTime);
-    }
     /**
      * Create analytics - delegated to TelemetryHandler
      */

package/dist/core/conversationMemoryFactory.d.ts

@@ -3,13 +3,13 @@
  * Creates appropriate conversation memory manager based on configuration
  */
 import type { ConversationMemoryConfig, RedisStorageConfig } from "../types/conversation.js";
-import type { StorageType, TypedEventEmitter, NeuroLinkEvents } from "../types/common.js";
+import type { StorageType } from "../types/common.js";
 import { ConversationMemoryManager } from "./conversationMemoryManager.js";
 import { RedisConversationMemoryManager } from "./redisConversationMemoryManager.js";
 /**
  * Creates a conversation memory manager based on configuration
  */
-export declare function createConversationMemoryManager(config: ConversationMemoryConfig, storageType?: StorageType, redisConfig?: RedisStorageConfig, eventEmitter?: TypedEventEmitter<NeuroLinkEvents>): ConversationMemoryManager | RedisConversationMemoryManager;
+export declare function createConversationMemoryManager(config: ConversationMemoryConfig, storageType?: StorageType, redisConfig?: RedisStorageConfig): ConversationMemoryManager | RedisConversationMemoryManager;
 /**
  * Get storage type from environment variable or configuration
  */

package/dist/core/conversationMemoryFactory.js

@@ -8,7 +8,7 @@ import { logger } from "../utils/logger.js";
 /**
  * Creates a conversation memory manager based on configuration
  */
-export function createConversationMemoryManager(config, storageType = "memory", redisConfig, eventEmitter) {
+export function createConversationMemoryManager(config, storageType = "memory", redisConfig) {
     logger.debug("[conversationMemoryFactory] Creating conversation memory manager", {
         storageType,
         config: {
@@ -38,7 +38,7 @@ export function createConversationMemoryManager(config, storageType = "memory",
             ttl: redisConfig?.ttl || 86400,
             hasConnectionOptions: !!redisConfig?.connectionOptions,
         });
-        const redisManager = new RedisConversationMemoryManager(config, redisConfig, eventEmitter);
+        const redisManager = new RedisConversationMemoryManager(config, redisConfig);
         logger.debug("[conversationMemoryFactory] Redis conversation manager created successfully", {
             managerType: redisManager.constructor.name,
             config: {

package/dist/core/conversationMemoryInitializer.d.ts

@@ -5,11 +5,10 @@
 import type { ConversationMemoryConfig } from "../types/conversation.js";
 import type { ConversationMemoryManager } from "./conversationMemoryManager.js";
 import type { RedisConversationMemoryManager } from "./redisConversationMemoryManager.js";
-import type { TypedEventEmitter, NeuroLinkEvents } from "../types/common.js";
 /**
  * Initialize conversation memory for NeuroLink
  * This function decides whether to use in-memory or Redis storage
  */
 export declare function initializeConversationMemory(config?: {
     conversationMemory?: Partial<ConversationMemoryConfig>;
-}, eventEmitter?: TypedEventEmitter<NeuroLinkEvents>): Promise<ConversationMemoryManager | RedisConversationMemoryManager | null>;
+}): Promise<ConversationMemoryManager | RedisConversationMemoryManager | null>;

package/dist/core/conversationMemoryInitializer.js

@@ -9,7 +9,7 @@ import { logger } from "../utils/logger.js";
  * Initialize conversation memory for NeuroLink
  * This function decides whether to use in-memory or Redis storage
  */
-export async function initializeConversationMemory(config, eventEmitter) {
+export async function initializeConversationMemory(config) {
     logger.debug("[conversationMemoryInitializer] Initialize conversation memory called", {
         hasConfig: !!config,
         hasMemoryConfig: !!config?.conversationMemory,
@@ -55,7 +55,7 @@ export async function initializeConversationMemory(config, eventEmitter) {
             });
             // Create Redis-based conversation memory manager
             logger.debug("[conversationMemoryInitializer] Creating Redis conversation memory manager");
-            const redisMemoryManager = createConversationMemoryManager(memoryConfig, "redis", redisConfig, eventEmitter);
+            const redisMemoryManager = createConversationMemoryManager(memoryConfig, "redis", redisConfig);
             logger.debug("[conversationMemoryInitializer] Checking Redis manager creation result", {
                 managerType: redisMemoryManager?.constructor?.name || "unknown",
                 isRedisType: redisMemoryManager?.constructor?.name ===

package/dist/core/infrastructure/baseError.d.ts

@@ -0,0 +1,21 @@
+export type ErrorCode = string;
+export declare class NeuroLinkFeatureError extends Error {
+    readonly code: ErrorCode;
+    readonly feature: string;
+    readonly retryable: boolean;
+    readonly details?: Record<string, unknown>;
+    readonly cause?: Error;
+    constructor(message: string, code: ErrorCode, feature: string, options?: {
+        retryable?: boolean;
+        details?: Record<string, unknown>;
+        cause?: Error;
+    });
+}
+export declare function createErrorFactory<TCodes extends Record<string, string>>(feature: string, codes: TCodes): {
+    codes: TCodes;
+    create: (code: keyof TCodes, message: string, options?: {
+        retryable?: boolean;
+        details?: Record<string, unknown>;
+        cause?: Error;
+    }) => NeuroLinkFeatureError;
+};

package/dist/core/infrastructure/baseError.js

@@ -0,0 +1,22 @@
+export class NeuroLinkFeatureError extends Error {
+    code;
+    feature;
+    retryable;
+    details;
+    cause;
+    constructor(message, code, feature, options) {
+        super(message);
+        this.name = `${feature}Error`;
+        this.code = code;
+        this.feature = feature;
+        this.retryable = options?.retryable ?? false;
+        this.details = options?.details;
+        this.cause = options?.cause;
+    }
+}
+export function createErrorFactory(feature, codes) {
+    return {
+        codes,
+        create: (code, message, options) => new NeuroLinkFeatureError(message, codes[code], feature, options),
+    };
+}

package/dist/core/infrastructure/baseFactory.d.ts

@@ -0,0 +1,21 @@
+export type FactoryFunction<TInstance, TConfig> = (config?: TConfig) => Promise<TInstance>;
+export type FactoryRegistration<TInstance, TConfig> = {
+    factory: FactoryFunction<TInstance, TConfig>;
+    aliases: string[];
+    metadata?: Record<string, unknown>;
+};
+export declare abstract class BaseFactory<TInstance, TConfig = unknown> {
+    protected items: Map<string, FactoryRegistration<TInstance, TConfig>>;
+    protected aliasMap: Map<string, string>;
+    protected initialized: boolean;
+    protected initPromise: Promise<void> | null;
+    protected abstract registerAll(): Promise<void>;
+    ensureInitialized(): Promise<void>;
+    register(name: string, factory: FactoryFunction<TInstance, TConfig>, aliases?: string[], metadata?: Record<string, unknown>): void;
+    create(nameOrAlias: string, config?: TConfig): Promise<TInstance>;
+    resolveName(nameOrAlias: string): string;
+    has(nameOrAlias: string): boolean;
+    getAvailable(): string[];
+    getAliases(): Map<string, string>;
+    clear(): void;
+}

package/dist/core/infrastructure/baseFactory.js

@@ -0,0 +1,54 @@
+import { logger } from "../../utils/logger.js";
+export class BaseFactory {
+    items = new Map();
+    aliasMap = new Map();
+    initialized = false;
+    initPromise = null;
+    async ensureInitialized() {
+        if (this.initialized) {
+            return;
+        }
+        if (this.initPromise) {
+            return this.initPromise;
+        }
+        this.initPromise = this.registerAll();
+        await this.initPromise;
+        this.initialized = true;
+    }
+    register(name, factory, aliases = [], metadata) {
+        this.items.set(name, { factory, aliases, metadata });
+        for (const alias of aliases) {
+            this.aliasMap.set(alias.toLowerCase(), name);
+        }
+        logger.debug(`Registered ${name} with aliases: ${aliases.join(", ")}`);
+    }
+    async create(nameOrAlias, config) {
+        await this.ensureInitialized();
+        const name = this.resolveName(nameOrAlias);
+        const registration = this.items.get(name);
+        if (!registration) {
+            throw new Error(`Unknown item: ${nameOrAlias}`);
+        }
+        return registration.factory(config);
+    }
+    resolveName(nameOrAlias) {
+        const lower = nameOrAlias.toLowerCase();
+        return this.aliasMap.get(lower) || nameOrAlias;
+    }
+    has(nameOrAlias) {
+        const name = this.resolveName(nameOrAlias);
+        return this.items.has(name);
+    }
+    getAvailable() {
+        return Array.from(this.items.keys());
+    }
+    getAliases() {
+        return new Map(this.aliasMap);
+    }
+    clear() {
+        this.items.clear();
+        this.aliasMap.clear();
+        this.initialized = false;
+        this.initPromise = null;
+    }
+}

package/dist/core/infrastructure/baseRegistry.d.ts

@@ -0,0 +1,21 @@
+export type RegistryEntry<TItem, TMetadata = unknown> = {
+    factory: () => Promise<TItem>;
+    metadata: TMetadata;
+    instance?: TItem;
+};
+export declare abstract class BaseRegistry<TItem, TMetadata = unknown> {
+    protected items: Map<string, RegistryEntry<TItem, TMetadata>>;
+    protected initialized: boolean;
+    protected initPromise: Promise<void> | null;
+    protected abstract registerAll(): Promise<void>;
+    ensureInitialized(): Promise<void>;
+    register(id: string, factory: () => Promise<TItem>, metadata: TMetadata): void;
+    get(id: string): Promise<TItem | undefined>;
+    has(id: string): boolean;
+    list(): Array<{
+        id: string;
+        metadata: TMetadata;
+    }>;
+    clear(): void;
+    isInitialized(): boolean;
+}