@juspay/neurolink 8.18.0 → 8.19.1

package/dist/lib/core/baseProvider.js

@@ -13,6 +13,7 @@ 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";
 /**
  * Abstract base class for all AI providers
  * Tools are integrated as first-class citizens - always available by default
@@ -298,6 +299,21 @@ export class BaseProvider {
     /**
      * Text generation method - implements AIProvider interface
      * Tools are always available unless explicitly disabled
+     *
+     * Supports Text-to-Speech (TTS) audio generation in two modes:
+     * 1. Direct synthesis (default): TTS synthesizes the input text without AI generation
+     * 2. AI response synthesis: TTS synthesizes the AI-generated response after generation
+     *
+     * When TTS is enabled with useAiResponse=false (default), the method returns early with
+     * only the audio result, skipping AI generation entirely for optimal performance.
+     *
+     * When TTS is enabled with useAiResponse=true, the method performs full AI generation
+     * and then synthesizes the AI response to audio.
+     *
+     * @param optionsOrPrompt - Generation options or prompt string
+     * @param _analysisSchema - Optional analysis schema (not used)
+     * @returns Enhanced result with optional audio field containing TTSResult
+     *
      * IMPLEMENTATION NOTE: Uses streamText() under the hood and accumulates results
      * for consistency and better performance
      */
@@ -306,6 +322,30 @@ export class BaseProvider {
         this.validateOptions(options);
         const startTime = Date.now();
         try {
+            // ===== TTS MODE 1: Direct Input Synthesis (useAiResponse=false) =====
+            // Synthesize input text directly without AI generation
+            // This is optimal for simple read-aloud scenarios
+            if (options.tts?.enabled && !options.tts?.useAiResponse) {
+                const textToSynthesize = options.prompt ?? options.input?.text ?? "";
+                // Build base result structure - common to both paths
+                const baseResult = {
+                    content: textToSynthesize,
+                    provider: options.provider ?? this.providerName,
+                    model: this.modelName,
+                    usage: { input: 0, output: 0, total: 0 },
+                };
+                try {
+                    const ttsResult = await TTSProcessor.synthesize(textToSynthesize, options.provider ?? this.providerName, options.tts);
+                    baseResult.audio = ttsResult;
+                }
+                catch (ttsError) {
+                    logger.error(`TTS synthesis failed in Mode 1 (direct input synthesis):`, ttsError);
+                    // baseResult remains without audio - graceful degradation
+                }
+                // Call enhanceResult for consistency - enables analytics/evaluation for TTS-only requests
+                return await this.enhanceResult(baseResult, options, startTime);
+            }
+            // ===== Normal AI Generation Flow =====
             const { tools, model } = await this.prepareGenerationContext(options);
             const messages = await this.buildMessages(options);
             const generateResult = await this.executeGeneration(model, messages, tools, options);
@@ -314,7 +354,44 @@ export class BaseProvider {
             const responseTime = Date.now() - startTime;
             await this.recordPerformanceMetrics(generateResult.usage, responseTime);
             const { toolsUsed, toolExecutions } = this.extractToolInformation(generateResult);
-            const enhancedResult = this.formatEnhancedResult(generateResult, tools, toolsUsed, toolExecutions, options);
+            let enhancedResult = this.formatEnhancedResult(generateResult, tools, toolsUsed, toolExecutions, options);
+            // ===== TTS MODE 2: AI Response Synthesis (useAiResponse=true) =====
+            // Synthesize AI-generated response after generation completes
+            if (options.tts?.enabled && options.tts?.useAiResponse) {
+                const aiResponse = enhancedResult.content;
+                const provider = options.provider ?? this.providerName;
+                // Validate AI response and provider before synthesis
+                if (aiResponse && provider) {
+                    try {
+                        const ttsResult = await TTSProcessor.synthesize(aiResponse, provider, options.tts);
+                        // Add audio to enhanced result (TTSProcessor already includes latency in metadata)
+                        enhancedResult = {
+                            ...enhancedResult,
+                            audio: ttsResult,
+                        };
+                    }
+                    catch (ttsError) {
+                        // Log TTS error but continue with text-only result
+                        logger.error(`TTS synthesis failed in Mode 2 (AI response synthesis):`, ttsError);
+                        // enhancedResult remains unchanged (no audio field added)
+                    }
+                }
+                else {
+                    logger.warn(`TTS synthesis skipped despite being enabled`, {
+                        provider: this.providerName,
+                        hasAiResponse: !!aiResponse,
+                        aiResponseLength: aiResponse?.length ?? 0,
+                        hasProvider: !!provider,
+                        ttsConfig: {
+                            enabled: options.tts?.enabled,
+                            useAiResponse: options.tts?.useAiResponse,
+                        },
+                        reason: !aiResponse
+                            ? "AI response is empty or undefined"
+                            : "Provider is missing",
+                    });
+                }
+            }
             return await this.enhanceResult(enhancedResult, options, startTime);
         }
         catch (error) {
@@ -361,6 +438,7 @@ export class BaseProvider {
             enhancedWithTools: !!(result.toolsUsed && result.toolsUsed.length > 0),
             analytics: result.analytics,
             evaluation: result.evaluation,
+            audio: result.audio,
         };
     }
     /**

package/dist/lib/core/modules/GenerationHandler.d.ts

@@ -29,6 +29,11 @@ export declare class GenerationHandler {
         functionId?: string;
         metadata?: Record<string, string | number | boolean>;
     } | undefined, handleToolStorageFn: (toolCalls: unknown[], toolResults: unknown[], options: TextGenerationOptions, timestamp: Date) => Promise<void>);
+    /**
+     * Helper method to call generateText with optional structured output
+     * @private
+     */
+    private callGenerateText;
     /**
      * Execute the generation with AI SDK
      */

package/dist/lib/core/modules/GenerationHandler.js

@@ -12,7 +12,7 @@
  *
  * @module core/modules/GenerationHandler
  */
-import { generateText, Output } from "ai";
+import { generateText, Output, NoObjectGeneratedError } from "ai";
 import { logger } from "../../utils/logger.js";
 import { DEFAULT_MAX_STEPS } from "../constants.js";
 /**
@@ -32,11 +32,12 @@ export class GenerationHandler {
         this.handleToolStorageFn = handleToolStorageFn;
     }
     /**
-     * Execute the generation with AI SDK
+     * Helper method to call generateText with optional structured output
+     * @private
      */
-    async executeGeneration(model, messages, tools, options) {
-        const shouldUseTools = !options.disableTools && this.supportsToolsFn();
-        const useStructuredOutput = !!options.schema &&
+    async callGenerateText(model, messages, tools, options, shouldUseTools, includeStructuredOutput) {
+        const useStructuredOutput = includeStructuredOutput &&
+            !!options.schema &&
             (options.output?.format === "json" ||
                 options.output?.format === "structured");
         return await generateText({
@@ -64,6 +65,34 @@ export class GenerationHandler {
             },
         });
     }
+    /**
+     * Execute the generation with AI SDK
+     */
+    async executeGeneration(model, messages, tools, options) {
+        const shouldUseTools = !options.disableTools && this.supportsToolsFn();
+        const useStructuredOutput = !!options.schema &&
+            (options.output?.format === "json" ||
+                options.output?.format === "structured");
+        try {
+            return await this.callGenerateText(model, messages, tools, options, shouldUseTools, true);
+        }
+        catch (error) {
+            // If NoObjectGeneratedError is thrown when using schema + tools together,
+            // fall back to generating without experimental_output and extract JSON manually
+            if (error instanceof NoObjectGeneratedError && useStructuredOutput) {
+                logger.debug("[GenerationHandler] NoObjectGeneratedError caught - falling back to manual JSON extraction", {
+                    provider: this.providerName,
+                    model: this.modelName,
+                    error: error.message,
+                });
+                // Retry without experimental_output - the formatEnhancedResult method
+                // will extract JSON from the text response
+                return await this.callGenerateText(model, messages, tools, options, shouldUseTools, false);
+            }
+            // Re-throw other errors
+            throw error;
+        }
+    }
     /**
      * Log generation completion information
      */
@@ -164,11 +193,29 @@ export class GenerationHandler {
                 options.output?.format === "structured");
         let content;
         if (useStructuredOutput) {
-            if (generateResult.experimental_output !== undefined) {
-                content = JSON.stringify(generateResult.experimental_output);
+            try {
+                const experimentalOutput = generateResult.experimental_output;
+                if (experimentalOutput !== undefined) {
+                    content = JSON.stringify(experimentalOutput);
+                }
+                else {
+                    // Fall back to text parsing
+                    const rawText = generateResult.text || "";
+                    const strippedText = rawText
+                        .replace(/^```(?:json)?\s*\n?/i, "")
+                        .replace(/\n?```\s*$/i, "")
+                        .trim();
+                    content = strippedText;
+                }
             }
-            else {
-                logger.debug("[GenerationHandler] experimental_output not available, falling back to text parsing");
+            catch (outputError) {
+                // experimental_output is a getter that can throw NoObjectGeneratedError
+                // Fall back to text parsing when structured output fails
+                logger.debug("[GenerationHandler] experimental_output threw, falling back to text parsing", {
+                    error: outputError instanceof Error
+                        ? outputError.message
+                        : String(outputError),
+                });
                 const rawText = generateResult.text || "";
                 const strippedText = rawText
                     .replace(/^```(?:json)?\s*\n?/i, "")

package/dist/lib/factories/providerRegistry.js

@@ -89,6 +89,24 @@ export class ProviderRegistry {
             }, process.env.SAGEMAKER_MODEL || "sagemaker-model", ["sagemaker", "aws-sagemaker"]);
             logger.debug("All providers registered successfully");
             this.registered = true;
+            // ===== TTS HANDLER REGISTRATION =====
+            try {
+                // Create handler instance and register explicitly
+                const { GoogleTTSHandler } = await import("../adapters/tts/googleTTSHandler.js");
+                const { TTSProcessor } = await import("../utils/ttsProcessor.js");
+                const googleHandler = new GoogleTTSHandler();
+                TTSProcessor.registerHandler("google-ai", googleHandler);
+                TTSProcessor.registerHandler("vertex", googleHandler);
+                logger.debug("TTS handlers registered successfully", {
+                    providers: ["google-ai", "vertex"],
+                });
+            }
+            catch (ttsError) {
+                logger.warn("Failed to register TTS handlers - TTS functionality will be unavailable", {
+                    error: ttsError instanceof Error ? ttsError.message : String(ttsError),
+                });
+                // Don't throw - TTS is optional functionality
+            }
         }
         catch (error) {
             logger.error("Failed to register providers:", error);

package/dist/lib/mcp/servers/agent/directToolsServer.js

@@ -23,6 +23,11 @@ export const directToolsServer = createMCPServer({
  */
 if (!shouldDisableBuiltinTools()) {
     Object.entries(directAgentTools).forEach(([toolName, toolDef]) => {
+        // Skip undefined tools
+        if (!toolDef) {
+            logger.warn(`Skipping undefined tool during direct tools server registration: ${toolName}`);
+            return;
+        }
         // The toolDef is a Vercel AI SDK Tool object
         // Extract properties from the Tool object
         const toolSpec = toolDef._spec || toolDef;

package/dist/lib/mcp/toolRegistry.js

@@ -47,6 +47,11 @@ export class MCPToolRegistry extends MCPRegistry {
     registerDirectTools() {
         registryLogger.debug("Auto-registering direct tools...");
         for (const [toolName, toolDef] of Object.entries(directAgentTools)) {
+            // Skip undefined tools
+            if (!toolDef) {
+                registryLogger.warn(`Skipping undefined tool during registration: ${toolName}`);
+                continue;
+            }
             const toolId = `direct.${toolName}`;
             const toolInfo = {
                 name: toolName,

package/dist/lib/neurolink.js

@@ -1287,6 +1287,7 @@ Current user's request: ${currentInput}`;
                 toolUsageContext: options.toolUsageContext,
                 input: options.input, // This includes text, images, and content arrays
                 region: options.region,
+                tts: options.tts,
             };
             // Apply factory enhancement using centralized utilities
             const textOptions = enhanceTextGenerationOptions(baseOptions, factoryResult);
@@ -1360,6 +1361,7 @@ Current user's request: ${currentInput}`;
                             factoryResult.domainType,
                     }
                     : undefined,
+                audio: textResult.audio,
             };
             if (this.conversationMemoryConfig?.conversationMemory?.mem0Enabled &&
                 options.context?.userId &&
@@ -1497,7 +1499,8 @@ Current user's request: ${currentInput}`;
      * Attempt MCP generation with retry logic
      */
     async attemptMCPGeneration(options, generateInternalId, generateInternalStartTime, generateInternalHrTimeStart, functionTag) {
-        if (!options.disableTools) {
+        if (!options.disableTools &&
+            !(options.tts?.enabled && !options.tts?.useAiResponse)) {
             return await this.performMCPGenerationRetries(options, generateInternalId, generateInternalStartTime, generateInternalHrTimeStart, functionTag);
         }
         return null;
@@ -1658,6 +1661,7 @@ Current user's request: ${currentInput}`;
                 toolExecutions: transformedToolExecutions,
                 enhancedWithTools: Boolean(hasToolExecutions), // Mark as enhanced if tools were actually used
                 availableTools: transformToolsForMCP(transformToolsToExpectedFormat(availableTools)),
+                audio: result.audio,
                 // Include analytics and evaluation from BaseProvider
                 analytics: result.analytics,
                 evaluation: result.evaluation,
@@ -1750,6 +1754,7 @@ Current user's request: ${currentInput}`;
                     enhancedWithTools: false,
                     analytics: result.analytics,
                     evaluation: result.evaluation,
+                    audio: result.audio,
                 };
             }
             catch (error) {

package/dist/lib/types/generateTypes.d.ts

@@ -300,6 +300,36 @@ export type TextGenerationOptions = {
     timeout?: number | string;
     disableTools?: boolean;
     maxSteps?: number;
+    /**
+     * Text-to-Speech (TTS) configuration
+     *
+     * Enable audio generation from text. Behavior depends on useAiResponse flag:
+     * - When useAiResponse is false/undefined (default): TTS synthesizes the input text directly
+     * - When useAiResponse is true: TTS synthesizes the AI-generated response
+     *
+     * @example Using input text (default)
+     * ```typescript
+     * const neurolink = new NeuroLink();
+     * const result = await neurolink.generate({
+     *   input: { text: "Hello world" },
+     *   provider: "google-ai",
+     *   tts: { enabled: true, voice: "en-US-Neural2-C" }
+     * });
+     * // TTS synthesizes "Hello world" directly, no AI generation
+     * ```
+     *
+     * @example Using AI response
+     * ```typescript
+     * const neurolink = new NeuroLink();
+     * const result = await neurolink.generate({
+     *   input: { text: "Tell me a joke" },
+     *   provider: "google-ai",
+     *   tts: { enabled: true, useAiResponse: true, voice: "en-US-Neural2-C" }
+     * });
+     * // AI generates the joke, then TTS synthesizes the AI's response
+     * ```
+     */
+    tts?: TTSOptions;
     enableEvaluation?: boolean;
     enableAnalytics?: boolean;
     context?: Record<string, JsonValue>;
@@ -346,6 +376,7 @@ export type TextGenerationResult = {
     }>;
     analytics?: AnalyticsData;
     evaluation?: EvaluationData;
+    audio?: TTSResult;
 };
 /**
  * Enhanced result type with optional analytics/evaluation

package/dist/lib/types/ttsTypes.d.ts

@@ -19,6 +19,35 @@ export type TTSQuality = "standard" | "hd";
 export type TTSOptions = {
     /** Enable TTS output */
     enabled?: boolean;
+    /**
+     * Use the AI-generated response for TTS instead of the input text
+     *
+     * When false or undefined (default): TTS will synthesize the input text/prompt directly without calling AI generation
+     * When true: TTS will synthesize the AI-generated response after generation completes
+     *
+     * @default false
+     *
+     * @example Using input text directly (default)
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: "Hello world" },
+     *   provider: "google-ai",
+     *   tts: { enabled: true }  // or useAiResponse: false
+     * });
+     * // TTS synthesizes "Hello world" directly, no AI generation
+     * ```
+     *
+     * @example Using AI response
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: "Tell me a joke" },
+     *   provider: "google-ai",
+     *   tts: { enabled: true, useAiResponse: true }
+     * });
+     * // AI generates the joke, then TTS synthesizes the AI's response
+     * ```
+     */
+    useAiResponse?: boolean;
     /** Voice identifier (e.g., "en-US-Neural2-C") */
     voice?: string;
     /** Audio format (default: mp3) */

package/dist/lib/utils/fileDetector.d.ts

@@ -31,6 +31,31 @@ export declare class FileDetector {
      * @returns Processed file result with type and content
      */
     static detectAndProcess(input: FileInput, options?: FileDetectorOptions): Promise<FileProcessingResult>;
+    /**
+     * Try fallback parsing for a specific file type
+     * Used when file detection returns "unknown" but we want to try parsing anyway
+     */
+    private static tryFallbackParsing;
+    /**
+     * Check if content is valid text (UTF-8, mostly printable)
+     */
+    private static isValidText;
+    /**
+     * Guess the MIME type for text content based on content patterns
+     */
+    private static guessTextMimeType;
+    /**
+     * Strict YAML detection for guessTextMimeType
+     * Similar to ContentHeuristicStrategy but requires at least 2 indicators
+     * to avoid false positives from simple key: value patterns
+     */
+    private static looksLikeYAMLStrict;
+    /**
+     * Strict XML detection for guessTextMimeType
+     * Ensures content has proper XML declaration or valid tag structure with closing tags
+     * Prevents false positives from arbitrary content starting with <
+     */
+    private static looksLikeXMLStrict;
     /**
      * Detect file type using multi-strategy approach
      * Stops at first strategy with confidence >= threshold (default: 80%)