@juspay/neurolink 8.18.0 → 8.19.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [8.19.0](https://github.com/juspay/neurolink/compare/v8.18.0...v8.19.0) (2025-12-18)
+
+### Features
+
+- **(tts):** Integrate TTS into BaseProvider.generate() ([ffae0b5](https://github.com/juspay/neurolink/commit/ffae0b5be9c4a2ef249876bdeee265004adf28a3))
+
 ## [8.18.0](https://github.com/juspay/neurolink/compare/v8.17.0...v8.18.0) (2025-12-16)
 
 ### Features

package/dist/cli/loop/optionsSchema.d.ts

@@ -5,4 +5,4 @@ import type { OptionSchema } from "../../lib/types/cli.js";
  * This object provides metadata for validation and help text in the CLI loop.
  * It is derived from the main TextGenerationOptions interface to ensure consistency.
  */
-export declare const textGenerationOptionsSchema: Record<keyof Omit<TextGenerationOptions, "prompt" | "input" | "schema" | "tools" | "context" | "conversationHistory" | "conversationMessages" | "conversationMemoryConfig" | "originalPrompt" | "middleware" | "expectedOutcome" | "evaluationCriteria" | "region" | "csvOptions">, OptionSchema>;
+export declare const textGenerationOptionsSchema: Record<keyof Omit<TextGenerationOptions, "prompt" | "input" | "schema" | "tools" | "context" | "conversationHistory" | "conversationMessages" | "conversationMemoryConfig" | "originalPrompt" | "middleware" | "expectedOutcome" | "evaluationCriteria" | "region" | "csvOptions" | "tts">, OptionSchema>;

package/dist/core/baseProvider.d.ts

@@ -85,6 +85,21 @@ export declare abstract class BaseProvider implements AIProvider {
     /**
      * 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
      */

package/dist/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,27 @@ 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 ?? "";
+                const ttsResult = await TTSProcessor.synthesize(textToSynthesize, options.provider ?? this.providerName, options.tts);
+                const baseResult = {
+                    content: textToSynthesize,
+                    audio: ttsResult,
+                    provider: options.provider ?? this.providerName,
+                    model: this.modelName,
+                    usage: {
+                        input: 0,
+                        output: 0,
+                        total: 0,
+                    },
+                };
+                // 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 +351,37 @@ 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) {
+                    const ttsResult = await TTSProcessor.synthesize(aiResponse, provider, options.tts);
+                    // Add audio to enhanced result (TTSProcessor already includes latency in metadata)
+                    enhancedResult = {
+                        ...enhancedResult,
+                        audio: ttsResult,
+                    };
+                }
+                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 +428,7 @@ export class BaseProvider {
             enhancedWithTools: !!(result.toolsUsed && result.toolsUsed.length > 0),
             analytics: result.analytics,
             evaluation: result.evaluation,
+            audio: result.audio,
         };
     }
     /**

package/dist/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/core/baseProvider.d.ts

@@ -85,6 +85,21 @@ export declare abstract class BaseProvider implements AIProvider {
     /**
      * 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
      */

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,27 @@ 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 ?? "";
+                const ttsResult = await TTSProcessor.synthesize(textToSynthesize, options.provider ?? this.providerName, options.tts);
+                const baseResult = {
+                    content: textToSynthesize,
+                    audio: ttsResult,
+                    provider: options.provider ?? this.providerName,
+                    model: this.modelName,
+                    usage: {
+                        input: 0,
+                        output: 0,
+                        total: 0,
+                    },
+                };
+                // 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 +351,37 @@ 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) {
+                    const ttsResult = await TTSProcessor.synthesize(aiResponse, provider, options.tts);
+                    // Add audio to enhanced result (TTSProcessor already includes latency in metadata)
+                    enhancedResult = {
+                        ...enhancedResult,
+                        audio: ttsResult,
+                    };
+                }
+                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 +428,7 @@ export class BaseProvider {
             enhancedWithTools: !!(result.toolsUsed && result.toolsUsed.length > 0),
             analytics: result.analytics,
             evaluation: result.evaluation,
+            audio: result.audio,
         };
     }
     /**

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/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/ttsProcessor.d.ts

@@ -39,14 +39,46 @@ export declare class TTSError extends NeuroLinkError {
  *
  * Each provider (Google AI, OpenAI, etc.) implements this interface
  * to provide TTS generation capabilities using their respective APIs.
+ *
+ * **Timeout Handling:**
+ * Implementations MUST handle their own timeouts for the `synthesize()` method.
+ * Recommended timeout: 30 seconds. Implementations should use `withTimeout()` utility
+ * or provider-specific timeout mechanisms (e.g., Google Cloud client timeout).
+ *
+ * **Error Handling:**
+ * Implementations should throw TTSError for all failures, including timeouts.
+ * Use appropriate error codes from TTS_ERROR_CODES.
+ *
+ * @example
+ * ```typescript
+ * class MyTTSHandler implements TTSHandler {
+ *   async synthesize(text: string, options: TTSOptions): Promise<TTSResult> {
+ *     // REQUIRED: Implement timeout handling
+ *     return await withTimeout(
+ *       this.actualSynthesis(text, options),
+ *       30000, // 30 second timeout
+ *       'TTS synthesis timed out'
+ *     );
+ *   }
+ *
+ *   isConfigured(): boolean {
+ *     return !!process.env.MY_TTS_API_KEY;
+ *   }
+ * }
+ * ```
  */
 export interface TTSHandler {
     /**
      * Generate audio from text using provider-specific TTS API
      *
-     * @param text - Text to convert to speech
-     * @param options - TTS configuration options
+     * **IMPORTANT: Timeout Responsibility**
+     * Implementations MUST enforce their own timeouts (recommended: 30 seconds).
+     * Use the `withTimeout()` utility or provider-specific timeout mechanisms.
+     *
+     * @param text - Text to convert to speech (pre-validated, non-empty, within length limits)
+     * @param options - TTS configuration options (voice, format, speed, etc.)
      * @returns Audio buffer with metadata
+     * @throws {TTSError} On synthesis failure, timeout, or configuration issues
      */
     synthesize(text: string, options: TTSOptions): Promise<TTSResult>;
     /**
@@ -105,16 +137,6 @@ export declare class TTSProcessor {
      * @private
      */
     private static readonly DEFAULT_MAX_TEXT_LENGTH;
-    /**
-     * Default timeout for TTS synthesis operations (milliseconds)
-     *
-     * This timeout prevents indefinite hangs in provider API calls and serves as
-     * a safety net for all TTS operations. Individual handlers may implement
-     * shorter provider-specific timeouts.
-     *
-     * @private
-     */
-    private static readonly DEFAULT_SYNTHESIS_TIMEOUT_MS;
     /**
      * Register a TTS handler for a specific provider
      *
@@ -164,14 +186,19 @@ export declare class TTSProcessor {
      * 1. Validates input text (not empty, within length limits)
      * 2. Looks up the provider handler
      * 3. Verifies provider configuration
-     * 4. Delegates synthesis to the provider
+     * 4. Delegates synthesis to the provider (timeout handled by provider)
      * 5. Enriches result with metadata
      *
+     * **Timeout Handling:**
+     * Timeouts are enforced by individual provider implementations (see TTSHandler interface).
+     * Providers typically use 30-second timeouts via `withTimeout()` utility or
+     * provider-specific timeout mechanisms (e.g., Google Cloud client timeout).
+     *
      * @param text - Text to convert to speech
      * @param provider - Provider identifier
      * @param options - TTS configuration options
      * @returns Audio result with buffer and metadata
-     * @throws TTSError if validation fails, provider not supported/configured, or synthesis times out
+     * @throws TTSError if validation fails or provider not supported/configured
      *
      * @example
      * ```typescript

package/dist/lib/utils/ttsProcessor.js

@@ -8,7 +8,7 @@
  */
 import { logger } from "./logger.js";
 import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
-import { NeuroLinkError, withTimeout } from "./errorHandling.js";
+import { NeuroLinkError } from "./errorHandling.js";
 /**
  * TTS-specific error codes
  */
@@ -72,16 +72,6 @@ export class TTSProcessor {
      * @private
      */
     static DEFAULT_MAX_TEXT_LENGTH = 3000;
-    /**
-     * Default timeout for TTS synthesis operations (milliseconds)
-     *
-     * This timeout prevents indefinite hangs in provider API calls and serves as
-     * a safety net for all TTS operations. Individual handlers may implement
-     * shorter provider-specific timeouts.
-     *
-     * @private
-     */
-    static DEFAULT_SYNTHESIS_TIMEOUT_MS = 60000;
     /**
      * Register a TTS handler for a specific provider
      *
@@ -158,14 +148,19 @@ export class TTSProcessor {
      * 1. Validates input text (not empty, within length limits)
      * 2. Looks up the provider handler
      * 3. Verifies provider configuration
-     * 4. Delegates synthesis to the provider
+     * 4. Delegates synthesis to the provider (timeout handled by provider)
      * 5. Enriches result with metadata
      *
+     * **Timeout Handling:**
+     * Timeouts are enforced by individual provider implementations (see TTSHandler interface).
+     * Providers typically use 30-second timeouts via `withTimeout()` utility or
+     * provider-specific timeout mechanisms (e.g., Google Cloud client timeout).
+     *
      * @param text - Text to convert to speech
      * @param provider - Provider identifier
      * @param options - TTS configuration options
      * @returns Audio result with buffer and metadata
-     * @throws TTSError if validation fails, provider not supported/configured, or synthesis times out
+     * @throws TTSError if validation fails or provider not supported/configured
      *
      * @example
      * ```typescript
@@ -238,19 +233,8 @@ export class TTSProcessor {
         }
         try {
             logger.debug(`[TTSProcessor] Starting synthesis with provider: ${provider}`);
-            // 5. Call handler.synthesize() with timeout protection (60 second safety net)
-            const result = await withTimeout(handler.synthesize(trimmedText, options), this.DEFAULT_SYNTHESIS_TIMEOUT_MS, new TTSError({
-                code: TTS_ERROR_CODES.SYNTHESIS_FAILED,
-                message: `TTS synthesis timeout for provider "${provider}" after ${this.DEFAULT_SYNTHESIS_TIMEOUT_MS}ms`,
-                category: ErrorCategory.EXECUTION,
-                severity: ErrorSeverity.HIGH,
-                retriable: true,
-                context: {
-                    provider,
-                    timeoutMs: this.DEFAULT_SYNTHESIS_TIMEOUT_MS,
-                    textLength: trimmedText.length,
-                },
-            }));
+            // 5. Call handler.synthesize() - providers handle their own timeouts
+            const result = await handler.synthesize(trimmedText, options);
             // 6. Post-processing: add metadata
             const enrichedResult = {
                 ...result,

package/dist/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/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/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/utils/ttsProcessor.d.ts

@@ -39,14 +39,46 @@ export declare class TTSError extends NeuroLinkError {
  *
  * Each provider (Google AI, OpenAI, etc.) implements this interface
  * to provide TTS generation capabilities using their respective APIs.
+ *
+ * **Timeout Handling:**
+ * Implementations MUST handle their own timeouts for the `synthesize()` method.
+ * Recommended timeout: 30 seconds. Implementations should use `withTimeout()` utility
+ * or provider-specific timeout mechanisms (e.g., Google Cloud client timeout).
+ *
+ * **Error Handling:**
+ * Implementations should throw TTSError for all failures, including timeouts.
+ * Use appropriate error codes from TTS_ERROR_CODES.
+ *
+ * @example
+ * ```typescript
+ * class MyTTSHandler implements TTSHandler {
+ *   async synthesize(text: string, options: TTSOptions): Promise<TTSResult> {
+ *     // REQUIRED: Implement timeout handling
+ *     return await withTimeout(
+ *       this.actualSynthesis(text, options),
+ *       30000, // 30 second timeout
+ *       'TTS synthesis timed out'
+ *     );
+ *   }
+ *
+ *   isConfigured(): boolean {
+ *     return !!process.env.MY_TTS_API_KEY;
+ *   }
+ * }
+ * ```
  */
 export interface TTSHandler {
     /**
      * Generate audio from text using provider-specific TTS API
      *
-     * @param text - Text to convert to speech
-     * @param options - TTS configuration options
+     * **IMPORTANT: Timeout Responsibility**
+     * Implementations MUST enforce their own timeouts (recommended: 30 seconds).
+     * Use the `withTimeout()` utility or provider-specific timeout mechanisms.
+     *
+     * @param text - Text to convert to speech (pre-validated, non-empty, within length limits)
+     * @param options - TTS configuration options (voice, format, speed, etc.)
      * @returns Audio buffer with metadata
+     * @throws {TTSError} On synthesis failure, timeout, or configuration issues
      */
     synthesize(text: string, options: TTSOptions): Promise<TTSResult>;
     /**
@@ -105,16 +137,6 @@ export declare class TTSProcessor {
      * @private
      */
     private static readonly DEFAULT_MAX_TEXT_LENGTH;
-    /**
-     * Default timeout for TTS synthesis operations (milliseconds)
-     *
-     * This timeout prevents indefinite hangs in provider API calls and serves as
-     * a safety net for all TTS operations. Individual handlers may implement
-     * shorter provider-specific timeouts.
-     *
-     * @private
-     */
-    private static readonly DEFAULT_SYNTHESIS_TIMEOUT_MS;
     /**
      * Register a TTS handler for a specific provider
      *
@@ -164,14 +186,19 @@ export declare class TTSProcessor {
      * 1. Validates input text (not empty, within length limits)
      * 2. Looks up the provider handler
      * 3. Verifies provider configuration
-     * 4. Delegates synthesis to the provider
+     * 4. Delegates synthesis to the provider (timeout handled by provider)
      * 5. Enriches result with metadata
      *
+     * **Timeout Handling:**
+     * Timeouts are enforced by individual provider implementations (see TTSHandler interface).
+     * Providers typically use 30-second timeouts via `withTimeout()` utility or
+     * provider-specific timeout mechanisms (e.g., Google Cloud client timeout).
+     *
      * @param text - Text to convert to speech
      * @param provider - Provider identifier
      * @param options - TTS configuration options
      * @returns Audio result with buffer and metadata
-     * @throws TTSError if validation fails, provider not supported/configured, or synthesis times out
+     * @throws TTSError if validation fails or provider not supported/configured
      *
      * @example
      * ```typescript

package/dist/utils/ttsProcessor.js

@@ -8,7 +8,7 @@
  */
 import { logger } from "./logger.js";
 import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
-import { NeuroLinkError, withTimeout } from "./errorHandling.js";
+import { NeuroLinkError } from "./errorHandling.js";
 /**
  * TTS-specific error codes
  */
@@ -72,16 +72,6 @@ export class TTSProcessor {
      * @private
      */
     static DEFAULT_MAX_TEXT_LENGTH = 3000;
-    /**
-     * Default timeout for TTS synthesis operations (milliseconds)
-     *
-     * This timeout prevents indefinite hangs in provider API calls and serves as
-     * a safety net for all TTS operations. Individual handlers may implement
-     * shorter provider-specific timeouts.
-     *
-     * @private
-     */
-    static DEFAULT_SYNTHESIS_TIMEOUT_MS = 60000;
     /**
      * Register a TTS handler for a specific provider
      *
@@ -158,14 +148,19 @@ export class TTSProcessor {
      * 1. Validates input text (not empty, within length limits)
      * 2. Looks up the provider handler
      * 3. Verifies provider configuration
-     * 4. Delegates synthesis to the provider
+     * 4. Delegates synthesis to the provider (timeout handled by provider)
      * 5. Enriches result with metadata
      *
+     * **Timeout Handling:**
+     * Timeouts are enforced by individual provider implementations (see TTSHandler interface).
+     * Providers typically use 30-second timeouts via `withTimeout()` utility or
+     * provider-specific timeout mechanisms (e.g., Google Cloud client timeout).
+     *
      * @param text - Text to convert to speech
      * @param provider - Provider identifier
      * @param options - TTS configuration options
      * @returns Audio result with buffer and metadata
-     * @throws TTSError if validation fails, provider not supported/configured, or synthesis times out
+     * @throws TTSError if validation fails or provider not supported/configured
      *
      * @example
      * ```typescript
@@ -238,19 +233,8 @@ export class TTSProcessor {
         }
         try {
             logger.debug(`[TTSProcessor] Starting synthesis with provider: ${provider}`);
-            // 5. Call handler.synthesize() with timeout protection (60 second safety net)
-            const result = await withTimeout(handler.synthesize(trimmedText, options), this.DEFAULT_SYNTHESIS_TIMEOUT_MS, new TTSError({
-                code: TTS_ERROR_CODES.SYNTHESIS_FAILED,
-                message: `TTS synthesis timeout for provider "${provider}" after ${this.DEFAULT_SYNTHESIS_TIMEOUT_MS}ms`,
-                category: ErrorCategory.EXECUTION,
-                severity: ErrorSeverity.HIGH,
-                retriable: true,
-                context: {
-                    provider,
-                    timeoutMs: this.DEFAULT_SYNTHESIS_TIMEOUT_MS,
-                    textLength: trimmedText.length,
-                },
-            }));
+            // 5. Call handler.synthesize() - providers handle their own timeouts
+            const result = await handler.synthesize(trimmedText, options);
             // 6. Post-processing: add metadata
             const enrichedResult = {
                 ...result,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "8.18.0",
+  "version": "8.19.0",
   "description": "Universal AI Development Platform with working MCP integration, multi-provider support, and professional CLI. Built-in tools operational, 58+ external MCP servers discoverable. Connect to filesystem, GitHub, database operations, and more. Build, test, and deploy AI applications with 9 major providers: OpenAI, Anthropic, Google AI, AWS Bedrock, Azure, Hugging Face, Ollama, and Mistral AI.",
   "author": {
     "name": "Juspay Technologies",