@juspay/neurolink 8.12.0 → 8.13.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [8.13.1](https://github.com/juspay/neurolink/compare/v8.13.0...v8.13.1) (2025-12-13)
+
+### Bug Fixes
+
+- **(provider):** Implement image count limits with validation and warnings ([ff3e27a](https://github.com/juspay/neurolink/commit/ff3e27a5ab3aafffc8312f645e0ebc566600cc63))
+
+## [8.13.0](https://github.com/juspay/neurolink/compare/v8.12.0...v8.13.0) (2025-12-13)
+
+### Features
+
+- **(tts):** Implement TTSProcessor.synthesize() method ([d6f3567](https://github.com/juspay/neurolink/commit/d6f3567dda26191f0ca9fd82a8cd7ccff5c9f819))
+
 ## [8.12.0](https://github.com/juspay/neurolink/compare/v8.11.0...v8.12.0) (2025-12-13)
 
 ### Features

package/dist/adapters/providerImageAdapter.d.ts

@@ -33,6 +33,11 @@ export declare class ProviderImageAdapter {
      * Format content for Vertex AI (model-specific routing)
      */
     private static formatForVertex;
+    /**
+     * Validate image count against provider limits
+     * Warns at 80% threshold, throws error if limit exceeded
+     */
+    private static validateImageCount;
     /**
      * Validate that provider and model support vision
      */

package/dist/adapters/providerImageAdapter.js

@@ -16,6 +16,28 @@ export class MultimodalLogger {
         }
     }
 }
+/**
+ * Image count limits per provider
+ * These limits prevent API rejections when too many images are sent
+ */
+const IMAGE_LIMITS = {
+    openai: 10,
+    azure: 10, // Same as OpenAI
+    "google-ai": 16,
+    google: 16,
+    anthropic: 20,
+    vertex: {
+        // Vertex has model-specific limits
+        claude: 20, // Claude models on Vertex
+        gemini: 16, // Gemini models on Vertex
+        default: 16,
+    },
+    ollama: 10, // Conservative limit for Ollama
+    litellm: 10, // Conservative limit, as it proxies to various providers
+    mistral: 10, // Conservative limit for Mistral
+    // Note: Bedrock limit defined for future use when vision support is added
+    bedrock: 20, // Same as Anthropic for Claude models on Bedrock
+};
 /**
  * Vision capability definitions for each provider
  */
@@ -368,7 +390,9 @@ export class ProviderImageAdapter {
                     break;
                 case "azure":
                 case "azure-openai":
-                    adaptedPayload = this.formatForOpenAI(text, images);
+                    // Azure uses same format as OpenAI but validate with azure provider name
+                    this.validateImageCount(images.length, "azure");
+                    adaptedPayload = this.formatForOpenAI(text, images, true);
                     break;
                 case "google-ai":
                 case "google":
@@ -381,7 +405,9 @@ export class ProviderImageAdapter {
                     adaptedPayload = this.formatForVertex(text, images, model);
                     break;
                 case "ollama":
-                    adaptedPayload = this.formatForOpenAI(text, images);
+                    // Ollama uses same format as OpenAI but validate with ollama provider name
+                    this.validateImageCount(images.length, "ollama");
+                    adaptedPayload = this.formatForOpenAI(text, images, true);
                     break;
                 case "huggingface":
                     adaptedPayload = this.formatForOpenAI(text, images);
@@ -415,7 +441,11 @@ export class ProviderImageAdapter {
     /**
      * Format content for OpenAI (GPT-4o format)
      */
-    static formatForOpenAI(text, images) {
+    static formatForOpenAI(text, images, skipValidation = false) {
+        // Validate image count before processing (unless called from another formatter)
+        if (!skipValidation) {
+            this.validateImageCount(images.length, "openai");
+        }
         const content = [{ type: "text", text }];
         images.forEach((image, index) => {
             try {
@@ -438,7 +468,11 @@ export class ProviderImageAdapter {
     /**
      * Format content for Google AI (Gemini format)
      */
-    static formatForGoogleAI(text, images) {
+    static formatForGoogleAI(text, images, skipValidation = false) {
+        // Validate image count before processing (unless called from another formatter)
+        if (!skipValidation) {
+            this.validateImageCount(images.length, "google-ai");
+        }
         const parts = [{ text }];
         images.forEach((image, index) => {
             try {
@@ -460,7 +494,11 @@ export class ProviderImageAdapter {
     /**
      * Format content for Anthropic (Claude format)
      */
-    static formatForAnthropic(text, images) {
+    static formatForAnthropic(text, images, skipValidation = false) {
+        // Validate image count before processing (unless called from another formatter)
+        if (!skipValidation) {
+            this.validateImageCount(images.length, "anthropic");
+        }
         const content = [{ type: "text", text }];
         images.forEach((image, index) => {
             try {
@@ -488,15 +526,65 @@ export class ProviderImageAdapter {
      * Format content for Vertex AI (model-specific routing)
      */
     static formatForVertex(text, images, model) {
-        // Route based on model type
+        // Validate image count with model-specific limits before processing
+        this.validateImageCount(images.length, "vertex", model);
+        // Route based on model type, skip validation in delegated methods
         if (model.includes("gemini")) {
-            return this.formatForGoogleAI(text, images);
+            return this.formatForGoogleAI(text, images, true);
         }
         else if (model.includes("claude")) {
-            return this.formatForAnthropic(text, images);
+            return this.formatForAnthropic(text, images, true);
+        }
+        else {
+            return this.formatForGoogleAI(text, images, true);
+        }
+    }
+    /**
+     * Validate image count against provider limits
+     * Warns at 80% threshold, throws error if limit exceeded
+     */
+    static validateImageCount(imageCount, provider, model) {
+        const normalizedProvider = provider.toLowerCase();
+        let limit;
+        // Determine the limit based on provider
+        if (normalizedProvider === "vertex" && model) {
+            // Vertex has model-specific limits
+            if (model.includes("claude")) {
+                limit = IMAGE_LIMITS.vertex.claude;
+            }
+            else if (model.includes("gemini")) {
+                limit = IMAGE_LIMITS.vertex.gemini;
+            }
+            else {
+                limit = IMAGE_LIMITS.vertex.default;
+            }
         }
         else {
-            return this.formatForGoogleAI(text, images);
+            // Use provider-specific limit
+            const providerLimit = normalizedProvider in IMAGE_LIMITS
+                ? IMAGE_LIMITS[normalizedProvider]
+                : undefined;
+            // If provider not found in limits map, use a conservative default
+            if (providerLimit === undefined) {
+                // Conservative default for unknown providers
+                limit = 10;
+                logger.warn(`Image count limit not defined for provider ${provider}. Using conservative default of 10 images.`);
+            }
+            else {
+                // providerLimit is always a number when defined (except vertex which is handled separately)
+                limit = providerLimit;
+            }
+        }
+        // Warn only once at 80% threshold to avoid noise in batch processing
+        const warningThreshold = Math.floor(limit * 0.8);
+        if (imageCount === warningThreshold) {
+            logger.warn(`Image count (${imageCount}) is approaching the limit for ${provider}. ` +
+                `Maximum allowed: ${limit}. Please reduce the number of images.`);
+        }
+        // Throw error if limit exceeded
+        if (imageCount > limit) {
+            throw new Error(`Image count (${imageCount}) exceeds the maximum limit for ${provider}. ` +
+                `Maximum allowed: ${limit}. Please reduce the number of images.`);
         }
     }
     /**

package/dist/lib/adapters/providerImageAdapter.d.ts

@@ -33,6 +33,11 @@ export declare class ProviderImageAdapter {
      * Format content for Vertex AI (model-specific routing)
      */
     private static formatForVertex;
+    /**
+     * Validate image count against provider limits
+     * Warns at 80% threshold, throws error if limit exceeded
+     */
+    private static validateImageCount;
     /**
      * Validate that provider and model support vision
      */

package/dist/lib/adapters/providerImageAdapter.js

@@ -16,6 +16,28 @@ export class MultimodalLogger {
         }
     }
 }
+/**
+ * Image count limits per provider
+ * These limits prevent API rejections when too many images are sent
+ */
+const IMAGE_LIMITS = {
+    openai: 10,
+    azure: 10, // Same as OpenAI
+    "google-ai": 16,
+    google: 16,
+    anthropic: 20,
+    vertex: {
+        // Vertex has model-specific limits
+        claude: 20, // Claude models on Vertex
+        gemini: 16, // Gemini models on Vertex
+        default: 16,
+    },
+    ollama: 10, // Conservative limit for Ollama
+    litellm: 10, // Conservative limit, as it proxies to various providers
+    mistral: 10, // Conservative limit for Mistral
+    // Note: Bedrock limit defined for future use when vision support is added
+    bedrock: 20, // Same as Anthropic for Claude models on Bedrock
+};
 /**
  * Vision capability definitions for each provider
  */
@@ -368,7 +390,9 @@ export class ProviderImageAdapter {
                     break;
                 case "azure":
                 case "azure-openai":
-                    adaptedPayload = this.formatForOpenAI(text, images);
+                    // Azure uses same format as OpenAI but validate with azure provider name
+                    this.validateImageCount(images.length, "azure");
+                    adaptedPayload = this.formatForOpenAI(text, images, true);
                     break;
                 case "google-ai":
                 case "google":
@@ -381,7 +405,9 @@ export class ProviderImageAdapter {
                     adaptedPayload = this.formatForVertex(text, images, model);
                     break;
                 case "ollama":
-                    adaptedPayload = this.formatForOpenAI(text, images);
+                    // Ollama uses same format as OpenAI but validate with ollama provider name
+                    this.validateImageCount(images.length, "ollama");
+                    adaptedPayload = this.formatForOpenAI(text, images, true);
                     break;
                 case "huggingface":
                     adaptedPayload = this.formatForOpenAI(text, images);
@@ -415,7 +441,11 @@ export class ProviderImageAdapter {
     /**
      * Format content for OpenAI (GPT-4o format)
      */
-    static formatForOpenAI(text, images) {
+    static formatForOpenAI(text, images, skipValidation = false) {
+        // Validate image count before processing (unless called from another formatter)
+        if (!skipValidation) {
+            this.validateImageCount(images.length, "openai");
+        }
         const content = [{ type: "text", text }];
         images.forEach((image, index) => {
             try {
@@ -438,7 +468,11 @@ export class ProviderImageAdapter {
     /**
      * Format content for Google AI (Gemini format)
      */
-    static formatForGoogleAI(text, images) {
+    static formatForGoogleAI(text, images, skipValidation = false) {
+        // Validate image count before processing (unless called from another formatter)
+        if (!skipValidation) {
+            this.validateImageCount(images.length, "google-ai");
+        }
         const parts = [{ text }];
         images.forEach((image, index) => {
             try {
@@ -460,7 +494,11 @@ export class ProviderImageAdapter {
     /**
      * Format content for Anthropic (Claude format)
      */
-    static formatForAnthropic(text, images) {
+    static formatForAnthropic(text, images, skipValidation = false) {
+        // Validate image count before processing (unless called from another formatter)
+        if (!skipValidation) {
+            this.validateImageCount(images.length, "anthropic");
+        }
         const content = [{ type: "text", text }];
         images.forEach((image, index) => {
             try {
@@ -488,15 +526,65 @@ export class ProviderImageAdapter {
      * Format content for Vertex AI (model-specific routing)
      */
     static formatForVertex(text, images, model) {
-        // Route based on model type
+        // Validate image count with model-specific limits before processing
+        this.validateImageCount(images.length, "vertex", model);
+        // Route based on model type, skip validation in delegated methods
         if (model.includes("gemini")) {
-            return this.formatForGoogleAI(text, images);
+            return this.formatForGoogleAI(text, images, true);
         }
         else if (model.includes("claude")) {
-            return this.formatForAnthropic(text, images);
+            return this.formatForAnthropic(text, images, true);
+        }
+        else {
+            return this.formatForGoogleAI(text, images, true);
+        }
+    }
+    /**
+     * Validate image count against provider limits
+     * Warns at 80% threshold, throws error if limit exceeded
+     */
+    static validateImageCount(imageCount, provider, model) {
+        const normalizedProvider = provider.toLowerCase();
+        let limit;
+        // Determine the limit based on provider
+        if (normalizedProvider === "vertex" && model) {
+            // Vertex has model-specific limits
+            if (model.includes("claude")) {
+                limit = IMAGE_LIMITS.vertex.claude;
+            }
+            else if (model.includes("gemini")) {
+                limit = IMAGE_LIMITS.vertex.gemini;
+            }
+            else {
+                limit = IMAGE_LIMITS.vertex.default;
+            }
         }
         else {
-            return this.formatForGoogleAI(text, images);
+            // Use provider-specific limit
+            const providerLimit = normalizedProvider in IMAGE_LIMITS
+                ? IMAGE_LIMITS[normalizedProvider]
+                : undefined;
+            // If provider not found in limits map, use a conservative default
+            if (providerLimit === undefined) {
+                // Conservative default for unknown providers
+                limit = 10;
+                logger.warn(`Image count limit not defined for provider ${provider}. Using conservative default of 10 images.`);
+            }
+            else {
+                // providerLimit is always a number when defined (except vertex which is handled separately)
+                limit = providerLimit;
+            }
+        }
+        // Warn only once at 80% threshold to avoid noise in batch processing
+        const warningThreshold = Math.floor(limit * 0.8);
+        if (imageCount === warningThreshold) {
+            logger.warn(`Image count (${imageCount}) is approaching the limit for ${provider}. ` +
+                `Maximum allowed: ${limit}. Please reduce the number of images.`);
+        }
+        // Throw error if limit exceeded
+        if (imageCount > limit) {
+            throw new Error(`Image count (${imageCount}) exceeds the maximum limit for ${provider}. ` +
+                `Maximum allowed: ${limit}. Please reduce the number of images.`);
         }
     }
     /**

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

@@ -85,35 +85,6 @@ export declare const VALID_TTS_QUALITIES: readonly TTSQuality[];
  * Type guard to check if an object is a TTSResult
  */
 export declare function isTTSResult(value: unknown): value is TTSResult;
-/**
- * TTS Handler type for provider-specific implementations
- *
- * Each provider (Google AI, OpenAI, etc.) implements this type
- * to provide TTS generation capabilities using their respective APIs.
- */
-export type TTSHandler = {
-    /**
-     * Generate audio from text using provider-specific TTS API
-     *
-     * @param text - Text to convert to speech
-     * @param options - TTS configuration options
-     * @returns Audio buffer with metadata
-     */
-    synthesize(text: string, options: TTSOptions): Promise<TTSResult>;
-    /**
-     * Get available voices for the provider
-     *
-     * @param languageCode - Optional language filter (e.g., "en-US")
-     * @returns List of available voices
-     */
-    getVoices(languageCode?: string): Promise<TTSVoice[]>;
-    /**
-     * Validate that the provider is properly configured
-     *
-     * @returns True if provider can generate TTS
-     */
-    isConfigured(): boolean;
-};
 /**
  * Type guard to check if TTSOptions are valid
  */

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

@@ -6,7 +6,69 @@
  *
  * @module utils/ttsProcessor
  */
-import type { TTSHandler } from "../types/ttsTypes.js";
+import type { TTSOptions, TTSResult, TTSVoice } from "../types/ttsTypes.js";
+import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
+import { NeuroLinkError } from "./errorHandling.js";
+/**
+ * TTS-specific error codes
+ */
+export declare const TTS_ERROR_CODES: {
+    readonly EMPTY_TEXT: "TTS_EMPTY_TEXT";
+    readonly TEXT_TOO_LONG: "TTS_TEXT_TOO_LONG";
+    readonly PROVIDER_NOT_SUPPORTED: "TTS_PROVIDER_NOT_SUPPORTED";
+    readonly PROVIDER_NOT_CONFIGURED: "TTS_PROVIDER_NOT_CONFIGURED";
+    readonly SYNTHESIS_FAILED: "TTS_SYNTHESIS_FAILED";
+};
+/**
+ * TTS Error class for text-to-speech specific errors
+ */
+export declare class TTSError extends NeuroLinkError {
+    constructor(options: {
+        code: string;
+        message: string;
+        category?: ErrorCategory;
+        severity?: ErrorSeverity;
+        retriable?: boolean;
+        context?: Record<string, unknown>;
+        originalError?: Error;
+    });
+}
+/**
+ * TTS Handler interface for provider-specific implementations
+ *
+ * Each provider (Google AI, OpenAI, etc.) implements this interface
+ * to provide TTS generation capabilities using their respective APIs.
+ */
+export interface TTSHandler {
+    /**
+     * Generate audio from text using provider-specific TTS API
+     *
+     * @param text - Text to convert to speech
+     * @param options - TTS configuration options
+     * @returns Audio buffer with metadata
+     */
+    synthesize(text: string, options: TTSOptions): Promise<TTSResult>;
+    /**
+     * Get available voices for the provider
+     *
+     * @param languageCode - Optional language filter (e.g., "en-US")
+     * @returns List of available voices
+     */
+    getVoices?(languageCode?: string): Promise<TTSVoice[]>;
+    /**
+     * Validate that the provider is properly configured
+     *
+     * @returns True if provider can generate TTS
+     */
+    isConfigured(): boolean;
+    /**
+     * Maximum text length supported by this provider (in characters)
+     * Different providers have different limits
+     *
+     * @default 3000 if not specified
+     */
+    maxTextLength?: number;
+}
 /**
  * TTS processor class for orchestrating text-to-speech operations
  *
@@ -32,6 +94,26 @@ export declare class TTSProcessor {
      * @private
      */
     private static readonly handlers;
+    /**
+     * Default maximum text length for TTS synthesis (characters)
+     *
+     * Providers can override this value by specifying the `maxTextLength` property
+     * in their respective `TTSHandler` implementation. If not specified, this default
+     * value will be used.
+     *
+     * @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
      *
@@ -74,4 +156,33 @@ export declare class TTSProcessor {
      * ```
      */
     static supports(providerName: string): boolean;
+    /**
+     * Synthesize speech from text using a registered TTS provider
+     *
+     * Orchestrates the text-to-speech generation process:
+     * 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
+     * 5. Enriches result with metadata
+     *
+     * @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
+     *
+     * @example
+     * ```typescript
+     * const result = await TTSProcessor.synthesize("Hello, world!", "google-ai", {
+     *   voice: "en-US-Neural2-C",
+     *   format: "mp3",
+     *   speed: 1.0
+     * });
+     *
+     * console.log(`Generated ${result.size} bytes of ${result.format} audio`);
+     * // Save to file or play the audio buffer
+     * ```
+     */
+    static synthesize(text: string, provider: string, options: TTSOptions): Promise<TTSResult>;
 }

package/dist/lib/utils/ttsProcessor.js

@@ -7,6 +7,35 @@
  * @module utils/ttsProcessor
  */
 import { logger } from "./logger.js";
+import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
+import { NeuroLinkError, withTimeout } from "./errorHandling.js";
+/**
+ * TTS-specific error codes
+ */
+export const TTS_ERROR_CODES = {
+    EMPTY_TEXT: "TTS_EMPTY_TEXT",
+    TEXT_TOO_LONG: "TTS_TEXT_TOO_LONG",
+    PROVIDER_NOT_SUPPORTED: "TTS_PROVIDER_NOT_SUPPORTED",
+    PROVIDER_NOT_CONFIGURED: "TTS_PROVIDER_NOT_CONFIGURED",
+    SYNTHESIS_FAILED: "TTS_SYNTHESIS_FAILED",
+};
+/**
+ * TTS Error class for text-to-speech specific errors
+ */
+export class TTSError extends NeuroLinkError {
+    constructor(options) {
+        super({
+            code: options.code,
+            message: options.message,
+            category: options.category ?? ErrorCategory.VALIDATION,
+            severity: options.severity ?? ErrorSeverity.MEDIUM,
+            retriable: options.retriable ?? false,
+            context: options.context,
+            originalError: options.originalError,
+        });
+        this.name = "TTSError";
+    }
+}
 /**
  * TTS processor class for orchestrating text-to-speech operations
  *
@@ -32,6 +61,26 @@ export class TTSProcessor {
      * @private
      */
     static handlers = new Map();
+    /**
+     * Default maximum text length for TTS synthesis (characters)
+     *
+     * Providers can override this value by specifying the `maxTextLength` property
+     * in their respective `TTSHandler` implementation. If not specified, this default
+     * value will be used.
+     *
+     * @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
      *
@@ -101,5 +150,138 @@ export class TTSProcessor {
         }
         return isSupported;
     }
+    /**
+     * Synthesize speech from text using a registered TTS provider
+     *
+     * Orchestrates the text-to-speech generation process:
+     * 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
+     * 5. Enriches result with metadata
+     *
+     * @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
+     *
+     * @example
+     * ```typescript
+     * const result = await TTSProcessor.synthesize("Hello, world!", "google-ai", {
+     *   voice: "en-US-Neural2-C",
+     *   format: "mp3",
+     *   speed: 1.0
+     * });
+     *
+     * console.log(`Generated ${result.size} bytes of ${result.format} audio`);
+     * // Save to file or play the audio buffer
+     * ```
+     */
+    static async synthesize(text, provider, options) {
+        // Trim the text once at the start
+        const trimmedText = text.trim();
+        // 1. Text validation: reject empty text
+        if (!trimmedText) {
+            logger.error("[TTSProcessor] Text is required for synthesis");
+            throw new TTSError({
+                code: TTS_ERROR_CODES.EMPTY_TEXT,
+                message: "Text is required for TTS synthesis",
+                severity: ErrorSeverity.LOW,
+                retriable: false,
+                context: { provider },
+            });
+        }
+        // 2. Handler lookup and error if provider not supported
+        const handler = this.getHandler(provider);
+        if (!handler) {
+            logger.error(`[TTSProcessor] Provider "${provider}" is not registered`);
+            throw new TTSError({
+                code: TTS_ERROR_CODES.PROVIDER_NOT_SUPPORTED,
+                message: `TTS provider "${provider}" is not supported. Use TTSProcessor.registerHandler() to register it.`,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+                context: {
+                    provider,
+                    availableProviders: Array.from(this.handlers.keys()),
+                },
+            });
+        }
+        // 3. Text validation: reject text exceeding provider-specific max length
+        const maxTextLength = handler.maxTextLength ?? this.DEFAULT_MAX_TEXT_LENGTH;
+        if (trimmedText.length > maxTextLength) {
+            logger.error(`[TTSProcessor] Text exceeds maximum length of ${maxTextLength} characters for provider "${provider}"`);
+            throw new TTSError({
+                code: TTS_ERROR_CODES.TEXT_TOO_LONG,
+                message: `Text length (${trimmedText.length}) exceeds maximum allowed length (${maxTextLength} characters) for provider "${provider}"`,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: false,
+                context: {
+                    provider,
+                    textLength: trimmedText.length,
+                    maxLength: maxTextLength,
+                },
+            });
+        }
+        // 4. Configuration check
+        if (!handler.isConfigured()) {
+            logger.warn(`[TTSProcessor] Provider "${provider}" is not properly configured`);
+            throw new TTSError({
+                code: TTS_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
+                message: `TTS provider "${provider}" is not configured. Please set the required API keys.`,
+                category: ErrorCategory.CONFIGURATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+                context: { provider },
+            });
+        }
+        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,
+                },
+            }));
+            // 6. Post-processing: add metadata
+            const enrichedResult = {
+                ...result,
+                voice: result.voice ?? options.voice,
+            };
+            logger.info(`[TTSProcessor] Successfully synthesized ${result.size} bytes of audio`);
+            // 7. Returns TTSResult with buffer, format, metadata
+            return enrichedResult;
+        }
+        catch (err) {
+            // 8. Comprehensive error handling
+            // Re-throw TTSError as-is
+            if (err instanceof TTSError) {
+                throw err;
+            }
+            // Wrap other errors in TTSError
+            const errorMessage = err instanceof Error ? err.message : String(err || "Unknown error");
+            logger.error(`[TTSProcessor] Synthesis failed for provider "${provider}": ${errorMessage}`);
+            throw new TTSError({
+                code: TTS_ERROR_CODES.SYNTHESIS_FAILED,
+                message: `TTS synthesis failed for provider "${provider}": ${errorMessage}`,
+                category: ErrorCategory.EXECUTION,
+                severity: ErrorSeverity.HIGH,
+                retriable: true,
+                context: {
+                    provider,
+                    textLength: trimmedText.length,
+                    options,
+                },
+                originalError: err instanceof Error ? err : undefined,
+            });
+        }
+    }
 }
 //# sourceMappingURL=ttsProcessor.js.map

package/dist/types/ttsTypes.d.ts

@@ -85,35 +85,6 @@ export declare const VALID_TTS_QUALITIES: readonly TTSQuality[];
  * Type guard to check if an object is a TTSResult
  */
 export declare function isTTSResult(value: unknown): value is TTSResult;
-/**
- * TTS Handler type for provider-specific implementations
- *
- * Each provider (Google AI, OpenAI, etc.) implements this type
- * to provide TTS generation capabilities using their respective APIs.
- */
-export type TTSHandler = {
-    /**
-     * Generate audio from text using provider-specific TTS API
-     *
-     * @param text - Text to convert to speech
-     * @param options - TTS configuration options
-     * @returns Audio buffer with metadata
-     */
-    synthesize(text: string, options: TTSOptions): Promise<TTSResult>;
-    /**
-     * Get available voices for the provider
-     *
-     * @param languageCode - Optional language filter (e.g., "en-US")
-     * @returns List of available voices
-     */
-    getVoices(languageCode?: string): Promise<TTSVoice[]>;
-    /**
-     * Validate that the provider is properly configured
-     *
-     * @returns True if provider can generate TTS
-     */
-    isConfigured(): boolean;
-};
 /**
  * Type guard to check if TTSOptions are valid
  */

package/dist/utils/ttsProcessor.d.ts

@@ -6,7 +6,69 @@
  *
  * @module utils/ttsProcessor
  */
-import type { TTSHandler } from "../types/ttsTypes.js";
+import type { TTSOptions, TTSResult, TTSVoice } from "../types/ttsTypes.js";
+import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
+import { NeuroLinkError } from "./errorHandling.js";
+/**
+ * TTS-specific error codes
+ */
+export declare const TTS_ERROR_CODES: {
+    readonly EMPTY_TEXT: "TTS_EMPTY_TEXT";
+    readonly TEXT_TOO_LONG: "TTS_TEXT_TOO_LONG";
+    readonly PROVIDER_NOT_SUPPORTED: "TTS_PROVIDER_NOT_SUPPORTED";
+    readonly PROVIDER_NOT_CONFIGURED: "TTS_PROVIDER_NOT_CONFIGURED";
+    readonly SYNTHESIS_FAILED: "TTS_SYNTHESIS_FAILED";
+};
+/**
+ * TTS Error class for text-to-speech specific errors
+ */
+export declare class TTSError extends NeuroLinkError {
+    constructor(options: {
+        code: string;
+        message: string;
+        category?: ErrorCategory;
+        severity?: ErrorSeverity;
+        retriable?: boolean;
+        context?: Record<string, unknown>;
+        originalError?: Error;
+    });
+}
+/**
+ * TTS Handler interface for provider-specific implementations
+ *
+ * Each provider (Google AI, OpenAI, etc.) implements this interface
+ * to provide TTS generation capabilities using their respective APIs.
+ */
+export interface TTSHandler {
+    /**
+     * Generate audio from text using provider-specific TTS API
+     *
+     * @param text - Text to convert to speech
+     * @param options - TTS configuration options
+     * @returns Audio buffer with metadata
+     */
+    synthesize(text: string, options: TTSOptions): Promise<TTSResult>;
+    /**
+     * Get available voices for the provider
+     *
+     * @param languageCode - Optional language filter (e.g., "en-US")
+     * @returns List of available voices
+     */
+    getVoices?(languageCode?: string): Promise<TTSVoice[]>;
+    /**
+     * Validate that the provider is properly configured
+     *
+     * @returns True if provider can generate TTS
+     */
+    isConfigured(): boolean;
+    /**
+     * Maximum text length supported by this provider (in characters)
+     * Different providers have different limits
+     *
+     * @default 3000 if not specified
+     */
+    maxTextLength?: number;
+}
 /**
  * TTS processor class for orchestrating text-to-speech operations
  *
@@ -32,6 +94,26 @@ export declare class TTSProcessor {
      * @private
      */
     private static readonly handlers;
+    /**
+     * Default maximum text length for TTS synthesis (characters)
+     *
+     * Providers can override this value by specifying the `maxTextLength` property
+     * in their respective `TTSHandler` implementation. If not specified, this default
+     * value will be used.
+     *
+     * @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
      *
@@ -74,4 +156,33 @@ export declare class TTSProcessor {
      * ```
      */
     static supports(providerName: string): boolean;
+    /**
+     * Synthesize speech from text using a registered TTS provider
+     *
+     * Orchestrates the text-to-speech generation process:
+     * 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
+     * 5. Enriches result with metadata
+     *
+     * @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
+     *
+     * @example
+     * ```typescript
+     * const result = await TTSProcessor.synthesize("Hello, world!", "google-ai", {
+     *   voice: "en-US-Neural2-C",
+     *   format: "mp3",
+     *   speed: 1.0
+     * });
+     *
+     * console.log(`Generated ${result.size} bytes of ${result.format} audio`);
+     * // Save to file or play the audio buffer
+     * ```
+     */
+    static synthesize(text: string, provider: string, options: TTSOptions): Promise<TTSResult>;
 }

package/dist/utils/ttsProcessor.js

@@ -7,6 +7,35 @@
  * @module utils/ttsProcessor
  */
 import { logger } from "./logger.js";
+import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
+import { NeuroLinkError, withTimeout } from "./errorHandling.js";
+/**
+ * TTS-specific error codes
+ */
+export const TTS_ERROR_CODES = {
+    EMPTY_TEXT: "TTS_EMPTY_TEXT",
+    TEXT_TOO_LONG: "TTS_TEXT_TOO_LONG",
+    PROVIDER_NOT_SUPPORTED: "TTS_PROVIDER_NOT_SUPPORTED",
+    PROVIDER_NOT_CONFIGURED: "TTS_PROVIDER_NOT_CONFIGURED",
+    SYNTHESIS_FAILED: "TTS_SYNTHESIS_FAILED",
+};
+/**
+ * TTS Error class for text-to-speech specific errors
+ */
+export class TTSError extends NeuroLinkError {
+    constructor(options) {
+        super({
+            code: options.code,
+            message: options.message,
+            category: options.category ?? ErrorCategory.VALIDATION,
+            severity: options.severity ?? ErrorSeverity.MEDIUM,
+            retriable: options.retriable ?? false,
+            context: options.context,
+            originalError: options.originalError,
+        });
+        this.name = "TTSError";
+    }
+}
 /**
  * TTS processor class for orchestrating text-to-speech operations
  *
@@ -32,6 +61,26 @@ export class TTSProcessor {
      * @private
      */
     static handlers = new Map();
+    /**
+     * Default maximum text length for TTS synthesis (characters)
+     *
+     * Providers can override this value by specifying the `maxTextLength` property
+     * in their respective `TTSHandler` implementation. If not specified, this default
+     * value will be used.
+     *
+     * @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
      *
@@ -101,4 +150,137 @@ export class TTSProcessor {
         }
         return isSupported;
     }
+    /**
+     * Synthesize speech from text using a registered TTS provider
+     *
+     * Orchestrates the text-to-speech generation process:
+     * 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
+     * 5. Enriches result with metadata
+     *
+     * @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
+     *
+     * @example
+     * ```typescript
+     * const result = await TTSProcessor.synthesize("Hello, world!", "google-ai", {
+     *   voice: "en-US-Neural2-C",
+     *   format: "mp3",
+     *   speed: 1.0
+     * });
+     *
+     * console.log(`Generated ${result.size} bytes of ${result.format} audio`);
+     * // Save to file or play the audio buffer
+     * ```
+     */
+    static async synthesize(text, provider, options) {
+        // Trim the text once at the start
+        const trimmedText = text.trim();
+        // 1. Text validation: reject empty text
+        if (!trimmedText) {
+            logger.error("[TTSProcessor] Text is required for synthesis");
+            throw new TTSError({
+                code: TTS_ERROR_CODES.EMPTY_TEXT,
+                message: "Text is required for TTS synthesis",
+                severity: ErrorSeverity.LOW,
+                retriable: false,
+                context: { provider },
+            });
+        }
+        // 2. Handler lookup and error if provider not supported
+        const handler = this.getHandler(provider);
+        if (!handler) {
+            logger.error(`[TTSProcessor] Provider "${provider}" is not registered`);
+            throw new TTSError({
+                code: TTS_ERROR_CODES.PROVIDER_NOT_SUPPORTED,
+                message: `TTS provider "${provider}" is not supported. Use TTSProcessor.registerHandler() to register it.`,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+                context: {
+                    provider,
+                    availableProviders: Array.from(this.handlers.keys()),
+                },
+            });
+        }
+        // 3. Text validation: reject text exceeding provider-specific max length
+        const maxTextLength = handler.maxTextLength ?? this.DEFAULT_MAX_TEXT_LENGTH;
+        if (trimmedText.length > maxTextLength) {
+            logger.error(`[TTSProcessor] Text exceeds maximum length of ${maxTextLength} characters for provider "${provider}"`);
+            throw new TTSError({
+                code: TTS_ERROR_CODES.TEXT_TOO_LONG,
+                message: `Text length (${trimmedText.length}) exceeds maximum allowed length (${maxTextLength} characters) for provider "${provider}"`,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: false,
+                context: {
+                    provider,
+                    textLength: trimmedText.length,
+                    maxLength: maxTextLength,
+                },
+            });
+        }
+        // 4. Configuration check
+        if (!handler.isConfigured()) {
+            logger.warn(`[TTSProcessor] Provider "${provider}" is not properly configured`);
+            throw new TTSError({
+                code: TTS_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
+                message: `TTS provider "${provider}" is not configured. Please set the required API keys.`,
+                category: ErrorCategory.CONFIGURATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+                context: { provider },
+            });
+        }
+        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,
+                },
+            }));
+            // 6. Post-processing: add metadata
+            const enrichedResult = {
+                ...result,
+                voice: result.voice ?? options.voice,
+            };
+            logger.info(`[TTSProcessor] Successfully synthesized ${result.size} bytes of audio`);
+            // 7. Returns TTSResult with buffer, format, metadata
+            return enrichedResult;
+        }
+        catch (err) {
+            // 8. Comprehensive error handling
+            // Re-throw TTSError as-is
+            if (err instanceof TTSError) {
+                throw err;
+            }
+            // Wrap other errors in TTSError
+            const errorMessage = err instanceof Error ? err.message : String(err || "Unknown error");
+            logger.error(`[TTSProcessor] Synthesis failed for provider "${provider}": ${errorMessage}`);
+            throw new TTSError({
+                code: TTS_ERROR_CODES.SYNTHESIS_FAILED,
+                message: `TTS synthesis failed for provider "${provider}": ${errorMessage}`,
+                category: ErrorCategory.EXECUTION,
+                severity: ErrorSeverity.HIGH,
+                retriable: true,
+                context: {
+                    provider,
+                    textLength: trimmedText.length,
+                    options,
+                },
+                originalError: err instanceof Error ? err : undefined,
+            });
+        }
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "8.12.0",
+  "version": "8.13.1",
   "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",