@juspay/neurolink 7.6.1 → 7.7.1

package/dist/utils/optionsConversion.js

@@ -0,0 +1,126 @@
+/**
+ * Type conversion utilities between GenerateOptions and StreamOptions
+ *
+ * 🔧 FIX: Addresses Issue #2 - Type System Mismatch
+ * Factory patterns need to work with both generate() and stream() methods
+ */
+/**
+ * Convert GenerateOptions to StreamOptions
+ * Preserves all factory configuration and enhancement data
+ */
+export function convertGenerateToStreamOptions(generateOptions) {
+    const streamOptions = {
+        // Core input mapping
+        input: generateOptions.input,
+        // Provider and model settings
+        provider: generateOptions.provider,
+        model: generateOptions.model,
+        temperature: generateOptions.temperature,
+        maxTokens: generateOptions.maxTokens,
+        systemPrompt: generateOptions.systemPrompt,
+        // Tool configuration
+        tools: generateOptions.tools,
+        disableTools: generateOptions.disableTools,
+        // maxSteps only exists in StreamOptions, not GenerateOptions
+        // Analytics and evaluation
+        enableEvaluation: generateOptions.enableEvaluation,
+        enableAnalytics: generateOptions.enableAnalytics,
+        context: generateOptions.context,
+        // Domain-aware evaluation
+        evaluationDomain: generateOptions.evaluationDomain,
+        toolUsageContext: generateOptions.toolUsageContext,
+        conversationHistory: generateOptions.conversationHistory,
+        // 🔧 FIX: Factory configuration (critical for issue #2)
+        factoryConfig: generateOptions.factoryConfig,
+        // 🔧 FIX: Streaming configuration
+        streaming: generateOptions.streaming,
+    };
+    return streamOptions;
+}
+/**
+ * Convert StreamOptions to GenerateOptions
+ * Useful for fallback scenarios and unified processing
+ */
+export function convertStreamToGenerateOptions(streamOptions) {
+    const generateOptions = {
+        // Core input mapping
+        input: streamOptions.input,
+        // Provider and model settings
+        provider: streamOptions.provider,
+        model: streamOptions.model,
+        temperature: streamOptions.temperature,
+        maxTokens: streamOptions.maxTokens,
+        systemPrompt: streamOptions.systemPrompt,
+        // Tool configuration
+        tools: streamOptions.tools,
+        disableTools: streamOptions.disableTools,
+        // Note: maxSteps exists in StreamOptions but not in GenerateOptions
+        // Analytics and evaluation
+        enableEvaluation: streamOptions.enableEvaluation,
+        enableAnalytics: streamOptions.enableAnalytics,
+        context: streamOptions.context,
+        // Domain-aware evaluation
+        evaluationDomain: streamOptions.evaluationDomain,
+        toolUsageContext: streamOptions.toolUsageContext,
+        conversationHistory: streamOptions.conversationHistory,
+        // 🔧 FIX: Factory configuration (critical for issue #2)
+        factoryConfig: streamOptions.factoryConfig,
+        // 🔧 FIX: Streaming configuration
+        streaming: streamOptions.streaming,
+    };
+    return generateOptions;
+}
+/**
+ * Check if options object has factory configuration
+ * Useful for determining if enhanced processing is needed
+ */
+export function hasFactoryConfig(options) {
+    return !!options?.factoryConfig;
+}
+/**
+ * Extract factory configuration from either options type
+ * Returns null if no factory config is present
+ */
+export function extractFactoryConfig(options) {
+    const config = options?.factoryConfig;
+    return config ? config : null;
+}
+/**
+ * Check if options object has streaming configuration
+ * Useful for determining if streaming enhancements are needed
+ */
+export function hasStreamingConfig(options) {
+    return !!options?.streaming;
+}
+/**
+ * Extract streaming configuration from either options type
+ * Returns null if no streaming config is present
+ */
+export function extractStreamingConfig(options) {
+    const config = options?.streaming;
+    return config ? config : null;
+}
+/**
+ * Create factory-enhanced StreamOptions from domain configuration
+ * This is the key function that addresses Issue #2
+ */
+export function createFactoryAwareStreamOptions(baseOptions, factoryConfig) {
+    return {
+        input: baseOptions.input || { text: "" },
+        ...baseOptions,
+        factoryConfig,
+        enableEvaluation: true, // Enable evaluation when using factory patterns
+    };
+}
+/**
+ * Create factory-enhanced GenerateOptions from domain configuration
+ * Parallel function for generate() method
+ */
+export function createFactoryAwareGenerateOptions(baseOptions, factoryConfig) {
+    return {
+        input: baseOptions.input || { text: "" },
+        ...baseOptions,
+        factoryConfig,
+        enableEvaluation: true, // Enable evaluation when using factory patterns
+    };
+}

package/dist/utils/optionsUtils.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Options Enhancement Utilities
+ * Provides intelligent enhancement of GenerateOptions with factory patterns
+ * Supports domain configuration, streaming optimization, and MCP integration
+ */
+import type { GenerateOptions, UnifiedGenerationOptions } from "../types/generateTypes.js";
+import type { StreamOptions } from "../types/streamTypes.js";
+import type { ExecutionContext } from "../mcp/contracts/mcpContract.js";
+/**
+ * Enhancement types for different optimization strategies
+ */
+export type EnhancementType = "streaming-optimization" | "mcp-integration" | "legacy-migration" | "context-conversion" | "domain-configuration" | "batch-parallel-enhancement" | "batch-hybrid-enhancement" | "batch-dependency-enhancement";
+/**
+ * Enhancement options for modifying GenerateOptions
+ */
+export interface EnhancementOptions {
+    enhancementType: EnhancementType;
+    streamingOptions?: {
+        enabled?: boolean;
+        chunkSize?: number;
+        bufferSize?: number;
+        enableProgress?: boolean;
+        preferStreaming?: boolean;
+    };
+    mcpOptions?: {
+        enableToolRegistry?: boolean;
+        contextAware?: boolean;
+        executionContext?: ExecutionContext;
+    };
+    legacyMigration?: {
+        legacyContext?: Record<string, unknown>;
+        domainType?: string;
+        preserveFields?: boolean;
+    };
+    domainConfiguration?: {
+        domainType: string;
+        keyTerms?: string[];
+        failurePatterns?: string[];
+        successPatterns?: string[];
+        evaluationCriteria?: Record<string, unknown>;
+    };
+    performance?: {
+        enableAnalytics?: boolean;
+        enableEvaluation?: boolean;
+        timeout?: number;
+    };
+}
+/**
+ * Enhancement result with metadata
+ */
+export interface EnhancementResult {
+    options: UnifiedGenerationOptions;
+    metadata: {
+        enhancementApplied: boolean;
+        enhancementType: EnhancementType;
+        processingTime: number;
+        configurationUsed: Record<string, unknown>;
+        warnings: string[];
+        recommendations: string[];
+    };
+}
+/**
+ * Options Enhancement Utility Class
+ * Main utility for enhancing GenerateOptions with factory patterns
+ */
+export declare class OptionsEnhancer {
+    /**
+     * Thread-safe enhancement counter using SharedArrayBuffer and Atomics
+     *
+     * NOTE ON THREAD-SAFETY:
+     * JavaScript's main execution is single-threaded. Thread-safety using SharedArrayBuffer and Atomics
+     * is only relevant in environments that support multi-threading, such as web workers (in browsers)
+     * or worker threads (in Node.js).
+     *
+     * RATIONALE FOR THREAD-SAFETY:
+     * OptionsEnhancer is used across multiple worker threads in high-performance scenarios:
+     * - Parallel batch processing (batchEnhanceParallel function)
+     * - Streaming operations with concurrent enhancements
+     * - Factory pattern implementations that may run in web workers
+     * - Analytics tracking requires accurate counts across all threads
+     *
+     * SharedArrayBuffer + Atomics ensures accurate statistics without race conditions
+     * when enhancement operations occur simultaneously across multiple contexts.
+     *
+     * NOTE: SharedArrayBuffer requires cross-origin isolation headers in browsers:
+     *   - Cross-Origin-Opener-Policy: same-origin
+     *   - Cross-Origin-Embedder-Policy: require-corp
+     * Without these, SharedArrayBuffer will be unavailable and thread-safety will be disabled.
+     * In Node.js, SharedArrayBuffer is available in worker threads.
+     */
+    private static enhancementCountBuffer;
+    private static enhancementCountArray;
+    private static fallbackEnhancementCount;
+    private static get enhancementCount();
+    private static incrementEnhancementCount;
+    /**
+     * Enhance GenerateOptions with factory patterns
+     * Primary method for applying enhancements
+     */
+    static enhance(options: GenerateOptions, enhancementOptions: EnhancementOptions): EnhancementResult;
+    /**
+     * Enhance options for streaming optimization
+     * Specialized method for streaming enhancements
+     */
+    static enhanceForStreaming(options: GenerateOptions, streamingConfig?: {
+        chunkSize?: number;
+        bufferSize?: number;
+        enableProgress?: boolean;
+    }): EnhancementResult;
+    /**
+     * Convert legacy business context to factory options
+     * Migration utility for existing business-specific code
+     */
+    static migrateFromLegacy(options: GenerateOptions, legacyContext: Record<string, unknown>, domainType: string): EnhancementResult;
+    /**
+     * Create unified options from separate generation and streaming options
+     * Utility for combining different option types
+     */
+    static createUnified(generateOptions: GenerateOptions, streamOptions?: Partial<StreamOptions>): UnifiedGenerationOptions;
+    /**
+     * Enhance GenerateOptions with domain configuration
+     * Convenience method for domain-specific enhancements
+     */
+    static enhanceWithDomain(options: GenerateOptions, domainConfig: {
+        domainType: string;
+        keyTerms?: string[];
+        failurePatterns?: string[];
+        successPatterns?: string[];
+        evaluationCriteria?: Record<string, unknown>;
+    }): EnhancementResult;
+    /**
+     * Validate enhancement compatibility
+     * Check if enhancement options are compatible with base options
+     */
+    static validateEnhancement(options: GenerateOptions, enhancementOptions: EnhancementOptions): {
+        valid: boolean;
+        warnings: string[];
+        recommendations: string[];
+    };
+    private static applyEnhancement;
+    private static applyStreamingOptimization;
+    private static applyMcpIntegration;
+    private static applyLegacyMigration;
+    private static applyContextConversion;
+    private static applyDomainConfiguration;
+    private static createErrorResult;
+    /**
+     * Get enhancement statistics
+     * Utility for monitoring enhancement usage
+     */
+    static getStatistics(): {
+        enhancementCount: number;
+        lastReset: number;
+    };
+    /**
+     * Reset enhancement statistics
+     * Utility for clearing counters
+     */
+    static resetStatistics(): void;
+}
+/**
+ * Convenience functions for common enhancement patterns
+ */
+/**
+ * Quick streaming enhancement
+ * Simplified interface for streaming optimization
+ */
+export declare function enhanceForStreaming(options: GenerateOptions, chunkSize?: number): EnhancementResult;
+/**
+ * Quick legacy migration
+ * Simplified interface for legacy context migration
+ */
+export declare function migrateLegacyContext(options: GenerateOptions, legacyContext: Record<string, unknown>, domainType: string): EnhancementResult;
+/**
+ * Batch enhancement utility with intelligent parallel processing
+ * Automatically detects independent enhancements for parallel processing
+ */
+export declare function batchEnhance(options: GenerateOptions, enhancements: EnhancementOptions[]): EnhancementResult;
+/**
+ * Plugin-based conflict detection system
+ * Extensible and configurable enhancement conflict resolution
+ */
+export interface ConflictDetectionPlugin {
+    /** Plugin name for identification */
+    name: string;
+    /** Plugin version for compatibility checks */
+    version: string;
+    /** Check if two enhancement types conflict */
+    detectConflict(enhancementA: EnhancementType, enhancementB: EnhancementType, optionsA?: EnhancementOptions, optionsB?: EnhancementOptions): boolean;
+    /** Get conflict severity (low, medium, high) */
+    getConflictSeverity?(enhancementA: EnhancementType, enhancementB: EnhancementType): "low" | "medium" | "high";
+    /** Suggest resolution strategies */
+    suggestResolution?(enhancementA: EnhancementType, enhancementB: EnhancementType): string[];
+}
+/**
+ * Plugin registry for managing conflict detection plugins
+ */
+declare class ConflictDetectionRegistry {
+    private plugins;
+    private activePlugins;
+    constructor();
+    /**
+     * Register a new conflict detection plugin
+     */
+    registerPlugin(plugin: ConflictDetectionPlugin): void;
+    /**
+     * Set active plugins (in order of priority)
+     */
+    setActivePlugins(pluginNames: string[]): void;
+    /**
+     * Detect conflicts using active plugins
+     */
+    detectConflicts(enhancementA: EnhancementType, enhancementB: EnhancementType, optionsA?: EnhancementOptions, optionsB?: EnhancementOptions): {
+        hasConflict: boolean;
+        severity: "low" | "medium" | "high";
+        detectedBy: string[];
+        suggestions: string[];
+    };
+    /**
+     * Get information about registered plugins
+     */
+    getPluginInfo(): Array<{
+        name: string;
+        version: string;
+        active: boolean;
+    }>;
+}
+/**
+ * Get the global conflict detection registry for plugin management
+ * Allows external systems to register custom conflict detection plugins
+ */
+export declare function getConflictDetectionRegistry(): ConflictDetectionRegistry;
+/**
+ * Parallel batch enhancement utility
+ * Apply multiple independent enhancements in parallel for better performance
+ * Note: Only use for independent enhancements that don't depend on each other
+ */
+export declare function batchEnhanceParallel(baseOptions: GenerateOptions[], enhancements: EnhancementOptions[]): Promise<EnhancementResult[]>;
+/**
+ * Batch enhancement with dependency handling
+ * Apply enhancements with proper dependency resolution
+ */
+export declare function batchEnhanceWithDependencies(options: GenerateOptions, enhancements: (EnhancementOptions & {
+    dependsOn?: number[];
+})[]): EnhancementResult;
+export {};