@juspay/neurolink 8.15.0 → 8.17.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [8.17.0](https://github.com/juspay/neurolink/compare/v8.16.0...v8.17.0) (2025-12-16)
+
+### Features
+
+- **(tts):** Add TTS type integration to GenerateOptions, GenerateResult, and StreamChunk ([e290330](https://github.com/juspay/neurolink/commit/e290330e8fe22a4cd0427185cbddbb8856fbd5ca))
+
+## [8.16.0](https://github.com/juspay/neurolink/compare/v8.15.0...v8.16.0) (2025-12-16)
+
+### Features
+
+- **(tts):** Implement GoogleTTSHandler.getVoices() API ([15d39f7](https://github.com/juspay/neurolink/commit/15d39f7e6bfe093971bc822e8f4251b7e8711bb9))
+
 ## [8.15.0](https://github.com/juspay/neurolink/compare/v8.14.0...v8.15.0) (2025-12-14)
 
 ### Features

package/dist/adapters/tts/googleTTSHandler.d.ts

@@ -2,6 +2,8 @@ import type { TTSHandler } from "../../utils/ttsProcessor.js";
 import type { TTSOptions, TTSResult, TTSVoice } from "../../types/ttsTypes.js";
 export declare class GoogleTTSHandler implements TTSHandler {
     private client;
+    private voicesCache;
+    private static readonly CACHE_TTL_MS;
     /**
      * Google Cloud TTS maximum input size.
      * ~5000 bytes INCLUDING SSML tags.
@@ -35,12 +37,11 @@ export declare class GoogleTTSHandler implements TTSHandler {
      *
      * Note: This method is optional in the TTSHandler interface, but Google Cloud TTS
      * fully implements it to provide comprehensive voice discovery capabilities.
-     * Will be Implemented in ISSUE - TTS-014
      *
      * @param languageCode - Optional language filter (e.g., "en-US")
      * @returns List of available voices
      */
-    getVoices(_languageCode?: string): Promise<TTSVoice[]>;
+    getVoices(languageCode?: string): Promise<TTSVoice[]>;
     /**
      * Generate audio from text using provider-specific TTS API
      *
@@ -67,4 +68,21 @@ export declare class GoogleTTSHandler implements TTSHandler {
      * @throws Error if format is unsupported
      */
     private mapFormat;
+    /**
+     * Detect the voice type from a Google Cloud TTS voice name
+     *
+     * Parses the voice name to identify the underlying voice technology/model type.
+     * Google Cloud TTS offers different voice types with varying quality and pricing.
+     *
+     * @param name - The full Google Cloud voice name (e.g., "en-US-Neural2-C")
+     * @returns The detected voice type
+     *
+     * @example
+     * detectVoiceType("en-US-Neural2-C") // returns "neural"
+     * detectVoiceType("en-US-Wavenet-A") // returns "wavenet"
+     * detectVoiceType("en-US-Standard-B") // returns "standard"
+     * detectVoiceType("en-US-Chirp-A") // returns "chirp"
+     * detectVoiceType("en-US-Journey-D") // returns "unknown" (unrecognized type)
+     */
+    private detectVoiceType;
 }

package/dist/adapters/tts/googleTTSHandler.js

@@ -9,8 +9,11 @@
 import { TextToSpeechClient } from "@google-cloud/text-to-speech";
 import { TTSError, TTS_ERROR_CODES } from "../../utils/ttsProcessor.js";
 import { ErrorCategory, ErrorSeverity } from "../../constants/enums.js";
+import { logger } from "../../utils/logger.js";
 export class GoogleTTSHandler {
     client = null;
+    voicesCache = null;
+    static CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
     /**
      * Google Cloud TTS maximum input size.
      * ~5000 bytes INCLUDING SSML tags.
@@ -51,13 +54,78 @@ export class GoogleTTSHandler {
      *
      * Note: This method is optional in the TTSHandler interface, but Google Cloud TTS
      * fully implements it to provide comprehensive voice discovery capabilities.
-     * Will be Implemented in ISSUE - TTS-014
      *
      * @param languageCode - Optional language filter (e.g., "en-US")
      * @returns List of available voices
      */
-    async getVoices(_languageCode) {
-        throw new Error("Not implemented yet");
+    async getVoices(languageCode) {
+        if (!this.client) {
+            throw new TTSError({
+                code: TTS_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
+                message: "Google Cloud TTS client not initialized. Set GOOGLE_APPLICATION_CREDENTIALS or pass credentials path.",
+                category: ErrorCategory.CONFIGURATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+            });
+        }
+        try {
+            // Return cached voices if available, valid, and no language filter is specified
+            if (this.voicesCache &&
+                Date.now() - this.voicesCache.timestamp <
+                    GoogleTTSHandler.CACHE_TTL_MS &&
+                !languageCode) {
+                return this.voicesCache.voices;
+            }
+            // Call Google Cloud listVoices API
+            const [response] = await this.client.listVoices(languageCode ? { languageCode } : {});
+            if (!response.voices || response.voices.length === 0) {
+                logger.warn("Google Cloud TTS returned no voices");
+                return [];
+            }
+            const voices = [];
+            for (const voice of response.voices ?? []) {
+                // Validate required fields
+                if (!voice.name ||
+                    !Array.isArray(voice.languageCodes) ||
+                    voice.languageCodes.length === 0) {
+                    logger.warn("Skipping voice with missing required fields", {
+                        name: voice.name,
+                        languageCodesCount: voice.languageCodes?.length,
+                    });
+                    continue;
+                }
+                const voiceName = voice.name;
+                const languageCodes = voice.languageCodes;
+                const primaryLanguageCode = languageCodes[0];
+                const voiceType = this.detectVoiceType(voiceName);
+                // Map Google's ssmlGender → internal Gender
+                const gender = voice.ssmlGender === "MALE"
+                    ? "male"
+                    : voice.ssmlGender === "FEMALE"
+                        ? "female"
+                        : "neutral";
+                voices.push({
+                    id: voiceName,
+                    name: voiceName,
+                    languageCode: primaryLanguageCode,
+                    languageCodes,
+                    gender,
+                    type: voiceType,
+                    naturalSampleRateHertz: voice.naturalSampleRateHertz ?? undefined,
+                });
+            }
+            // Cache the result with timestamp if no language filter
+            if (!languageCode) {
+                this.voicesCache = { voices, timestamp: Date.now() };
+            }
+            return voices;
+        }
+        catch (err) {
+            // Log error but return empty array for graceful degradation
+            const message = err instanceof Error ? err.message : "Unknown error";
+            logger.error(`Failed to fetch Google TTS voices: ${message}`);
+            return [];
+        }
     }
     /**
      * Generate audio from text using provider-specific TTS API
@@ -216,4 +284,36 @@ export class GoogleTTSHandler {
                 });
         }
     }
+    /**
+     * Detect the voice type from a Google Cloud TTS voice name
+     *
+     * Parses the voice name to identify the underlying voice technology/model type.
+     * Google Cloud TTS offers different voice types with varying quality and pricing.
+     *
+     * @param name - The full Google Cloud voice name (e.g., "en-US-Neural2-C")
+     * @returns The detected voice type
+     *
+     * @example
+     * detectVoiceType("en-US-Neural2-C") // returns "neural"
+     * detectVoiceType("en-US-Wavenet-A") // returns "wavenet"
+     * detectVoiceType("en-US-Standard-B") // returns "standard"
+     * detectVoiceType("en-US-Chirp-A") // returns "chirp"
+     * detectVoiceType("en-US-Journey-D") // returns "unknown" (unrecognized type)
+     */
+    detectVoiceType(name) {
+        const tokens = name.toLowerCase().split("-");
+        if (tokens.some((t) => t.startsWith("chirp"))) {
+            return "chirp";
+        }
+        if (tokens.includes("neural2")) {
+            return "neural";
+        }
+        if (tokens.includes("wavenet")) {
+            return "wavenet";
+        }
+        if (tokens.includes("standard")) {
+            return "standard";
+        }
+        return "unknown";
+    }
 }

package/dist/lib/adapters/tts/googleTTSHandler.d.ts

@@ -2,6 +2,8 @@ import type { TTSHandler } from "../../utils/ttsProcessor.js";
 import type { TTSOptions, TTSResult, TTSVoice } from "../../types/ttsTypes.js";
 export declare class GoogleTTSHandler implements TTSHandler {
     private client;
+    private voicesCache;
+    private static readonly CACHE_TTL_MS;
     /**
      * Google Cloud TTS maximum input size.
      * ~5000 bytes INCLUDING SSML tags.
@@ -35,12 +37,11 @@ export declare class GoogleTTSHandler implements TTSHandler {
      *
      * Note: This method is optional in the TTSHandler interface, but Google Cloud TTS
      * fully implements it to provide comprehensive voice discovery capabilities.
-     * Will be Implemented in ISSUE - TTS-014
      *
      * @param languageCode - Optional language filter (e.g., "en-US")
      * @returns List of available voices
      */
-    getVoices(_languageCode?: string): Promise<TTSVoice[]>;
+    getVoices(languageCode?: string): Promise<TTSVoice[]>;
     /**
      * Generate audio from text using provider-specific TTS API
      *
@@ -67,4 +68,21 @@ export declare class GoogleTTSHandler implements TTSHandler {
      * @throws Error if format is unsupported
      */
     private mapFormat;
+    /**
+     * Detect the voice type from a Google Cloud TTS voice name
+     *
+     * Parses the voice name to identify the underlying voice technology/model type.
+     * Google Cloud TTS offers different voice types with varying quality and pricing.
+     *
+     * @param name - The full Google Cloud voice name (e.g., "en-US-Neural2-C")
+     * @returns The detected voice type
+     *
+     * @example
+     * detectVoiceType("en-US-Neural2-C") // returns "neural"
+     * detectVoiceType("en-US-Wavenet-A") // returns "wavenet"
+     * detectVoiceType("en-US-Standard-B") // returns "standard"
+     * detectVoiceType("en-US-Chirp-A") // returns "chirp"
+     * detectVoiceType("en-US-Journey-D") // returns "unknown" (unrecognized type)
+     */
+    private detectVoiceType;
 }

package/dist/lib/adapters/tts/googleTTSHandler.js

@@ -9,8 +9,11 @@
 import { TextToSpeechClient } from "@google-cloud/text-to-speech";
 import { TTSError, TTS_ERROR_CODES } from "../../utils/ttsProcessor.js";
 import { ErrorCategory, ErrorSeverity } from "../../constants/enums.js";
+import { logger } from "../../utils/logger.js";
 export class GoogleTTSHandler {
     client = null;
+    voicesCache = null;
+    static CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
     /**
      * Google Cloud TTS maximum input size.
      * ~5000 bytes INCLUDING SSML tags.
@@ -51,13 +54,78 @@ export class GoogleTTSHandler {
      *
      * Note: This method is optional in the TTSHandler interface, but Google Cloud TTS
      * fully implements it to provide comprehensive voice discovery capabilities.
-     * Will be Implemented in ISSUE - TTS-014
      *
      * @param languageCode - Optional language filter (e.g., "en-US")
      * @returns List of available voices
      */
-    async getVoices(_languageCode) {
-        throw new Error("Not implemented yet");
+    async getVoices(languageCode) {
+        if (!this.client) {
+            throw new TTSError({
+                code: TTS_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
+                message: "Google Cloud TTS client not initialized. Set GOOGLE_APPLICATION_CREDENTIALS or pass credentials path.",
+                category: ErrorCategory.CONFIGURATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+            });
+        }
+        try {
+            // Return cached voices if available, valid, and no language filter is specified
+            if (this.voicesCache &&
+                Date.now() - this.voicesCache.timestamp <
+                    GoogleTTSHandler.CACHE_TTL_MS &&
+                !languageCode) {
+                return this.voicesCache.voices;
+            }
+            // Call Google Cloud listVoices API
+            const [response] = await this.client.listVoices(languageCode ? { languageCode } : {});
+            if (!response.voices || response.voices.length === 0) {
+                logger.warn("Google Cloud TTS returned no voices");
+                return [];
+            }
+            const voices = [];
+            for (const voice of response.voices ?? []) {
+                // Validate required fields
+                if (!voice.name ||
+                    !Array.isArray(voice.languageCodes) ||
+                    voice.languageCodes.length === 0) {
+                    logger.warn("Skipping voice with missing required fields", {
+                        name: voice.name,
+                        languageCodesCount: voice.languageCodes?.length,
+                    });
+                    continue;
+                }
+                const voiceName = voice.name;
+                const languageCodes = voice.languageCodes;
+                const primaryLanguageCode = languageCodes[0];
+                const voiceType = this.detectVoiceType(voiceName);
+                // Map Google's ssmlGender → internal Gender
+                const gender = voice.ssmlGender === "MALE"
+                    ? "male"
+                    : voice.ssmlGender === "FEMALE"
+                        ? "female"
+                        : "neutral";
+                voices.push({
+                    id: voiceName,
+                    name: voiceName,
+                    languageCode: primaryLanguageCode,
+                    languageCodes,
+                    gender,
+                    type: voiceType,
+                    naturalSampleRateHertz: voice.naturalSampleRateHertz ?? undefined,
+                });
+            }
+            // Cache the result with timestamp if no language filter
+            if (!languageCode) {
+                this.voicesCache = { voices, timestamp: Date.now() };
+            }
+            return voices;
+        }
+        catch (err) {
+            // Log error but return empty array for graceful degradation
+            const message = err instanceof Error ? err.message : "Unknown error";
+            logger.error(`Failed to fetch Google TTS voices: ${message}`);
+            return [];
+        }
     }
     /**
      * Generate audio from text using provider-specific TTS API
@@ -216,5 +284,37 @@ export class GoogleTTSHandler {
                 });
         }
     }
+    /**
+     * Detect the voice type from a Google Cloud TTS voice name
+     *
+     * Parses the voice name to identify the underlying voice technology/model type.
+     * Google Cloud TTS offers different voice types with varying quality and pricing.
+     *
+     * @param name - The full Google Cloud voice name (e.g., "en-US-Neural2-C")
+     * @returns The detected voice type
+     *
+     * @example
+     * detectVoiceType("en-US-Neural2-C") // returns "neural"
+     * detectVoiceType("en-US-Wavenet-A") // returns "wavenet"
+     * detectVoiceType("en-US-Standard-B") // returns "standard"
+     * detectVoiceType("en-US-Chirp-A") // returns "chirp"
+     * detectVoiceType("en-US-Journey-D") // returns "unknown" (unrecognized type)
+     */
+    detectVoiceType(name) {
+        const tokens = name.toLowerCase().split("-");
+        if (tokens.some((t) => t.startsWith("chirp"))) {
+            return "chirp";
+        }
+        if (tokens.includes("neural2")) {
+            return "neural";
+        }
+        if (tokens.includes("wavenet")) {
+            return "wavenet";
+        }
+        if (tokens.includes("standard")) {
+            return "standard";
+        }
+        return "unknown";
+    }
 }
 //# sourceMappingURL=googleTTSHandler.js.map

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

@@ -7,6 +7,7 @@ import type { ChatMessage, ConversationMemoryConfig } from "./conversation.js";
 import type { MiddlewareFactoryOptions } from "./middlewareTypes.js";
 import type { JsonValue } from "./common.js";
 import type { Content, ImageWithAltText } from "./content.js";
+import type { TTSOptions, TTSResult } from "./ttsTypes.js";
 /**
  * Generate function options type - Primary method for content generation
  * Supports multimodal content while maintaining backward compatibility
@@ -52,6 +53,39 @@ export type GenerateOptions = {
         format?: "jpeg" | "png";
         transcribeAudio?: boolean;
     };
+    /**
+     * Text-to-Speech (TTS) configuration
+     *
+     * Enable audio generation from the text response. The generated audio will be
+     * returned in the result's `audio` field as a TTSResult object.
+     *
+     * @example Basic TTS
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: "Tell me a story" },
+     *   provider: "google-ai",
+     *   tts: { enabled: true, voice: "en-US-Neural2-C" }
+     * });
+     * console.log(result.audio?.buffer); // Audio Buffer
+     * ```
+     *
+     * @example Advanced TTS with options
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: "Speak slowly and clearly" },
+     *   provider: "google-ai",
+     *   tts: {
+     *     enabled: true,
+     *     voice: "en-US-Neural2-D",
+     *     speed: 0.8,
+     *     pitch: 2.0,
+     *     format: "mp3",
+     *     quality: "standard"
+     *   }
+     * });
+     * ```
+     */
+    tts?: TTSOptions;
     provider?: AIProviderName | string;
     model?: string;
     region?: string;
@@ -144,6 +178,35 @@ export type GenerateResult = {
     outputs?: {
         text: string;
     };
+    /**
+     * Text-to-Speech audio result
+     *
+     * Contains the generated audio buffer and metadata when TTS is enabled.
+     * Generated by TTSProcessor.synthesize() using the specified provider.
+     *
+     * @example Accessing TTS audio
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: "Hello world" },
+     *   provider: "google-ai",
+     *   tts: { enabled: true, voice: "en-US-Neural2-C" }
+     * });
+     *
+     * if (result.audio) {
+     *   console.log(`Audio size: ${result.audio.size} bytes`);
+     *   console.log(`Format: ${result.audio.format}`);
+     *   if (result.audio.duration) {
+     *     console.log(`Duration: ${result.audio.duration}s`);
+     *   }
+     *   if (result.audio.voice) {
+     *     console.log(`Voice: ${result.audio.voice}`);
+     *   }
+     *   // Save or play the audio buffer
+     *   fs.writeFileSync('output.mp3', result.audio.buffer);
+     * }
+     * ```
+     */
+    audio?: TTSResult;
     provider?: string;
     model?: string;
     usage?: TokenUsage;

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

@@ -9,6 +9,7 @@ import type { EvaluationData } from "../index.js";
 import type { UnknownRecord, JsonValue } from "./common.js";
 import type { MiddlewareFactoryOptions } from "../types/middlewareTypes.js";
 import type { ChatMessage } from "./conversation.js";
+import type { TTSOptions, TTSChunk } from "./ttsTypes.js";
 /**
  * Progress tracking and metadata for streaming operations
  */
@@ -121,6 +122,60 @@ export type AudioChunk = {
     channels: number;
     encoding: PCMEncoding;
 };
+/**
+ * Stream chunk type using discriminated union for type safety
+ *
+ * Used in streaming responses to deliver either text or TTS audio chunks.
+ * The discriminated union ensures type safety - only one variant can exist at a time.
+ *
+ * @example Processing text chunks
+ * ```typescript
+ * for await (const chunk of result.stream) {
+ *   if (chunk.type === "text") {
+ *     console.log(chunk.content); // TypeScript knows 'content' exists
+ *   }
+ * }
+ * ```
+ *
+ * @example Processing audio chunks
+ * ```typescript
+ * const audioBuffer: Buffer[] = [];
+ * for await (const chunk of result.stream) {
+ *   if (chunk.type === "audio") {
+ *     audioBuffer.push(chunk.audioChunk.data); // TypeScript knows 'audioChunk' exists
+ *     if (chunk.audioChunk.isFinal) {
+ *       const fullAudio = Buffer.concat(audioBuffer);
+ *       fs.writeFileSync('output.mp3', fullAudio);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Processing both text and audio
+ * ```typescript
+ * for await (const chunk of result.stream) {
+ *   switch (chunk.type) {
+ *     case "text":
+ *       process.stdout.write(chunk.content);
+ *       break;
+ *     case "audio":
+ *       playAudioChunk(chunk.audioChunk.data);
+ *       break;
+ *   }
+ * }
+ * ```
+ */
+export type StreamChunk = {
+    /** Discriminator for text chunks */
+    type: "text";
+    /** Text content chunk */
+    content: string;
+} | {
+    /** Discriminator for audio chunks */
+    type: "audio";
+    /** TTS audio chunk data */
+    audioChunk: TTSChunk;
+};
 export type StreamOptions = {
     input: {
         text: string;
@@ -168,6 +223,46 @@ export type StreamOptions = {
         format?: "jpeg" | "png";
         transcribeAudio?: boolean;
     };
+    /**
+     * Text-to-Speech (TTS) configuration for streaming
+     *
+     * Enable audio generation from the streamed text response. Audio chunks will be
+     * delivered through the stream alongside text chunks as TTSChunk objects.
+     *
+     * @example Basic streaming TTS
+     * ```typescript
+     * const result = await neurolink.stream({
+     *   input: { text: "Tell me a story" },
+     *   provider: "google-ai",
+     *   tts: { enabled: true, voice: "en-US-Neural2-C" }
+     * });
+     *
+     * for await (const chunk of result.stream) {
+     *   if (chunk.type === "text") {
+     *     process.stdout.write(chunk.content);
+     *   } else if (chunk.type === "audio") {
+     *     // Handle audio chunk
+     *     playAudioChunk(chunk.audioChunk.data);
+     *   }
+     * }
+     * ```
+     *
+     * @example Advanced streaming TTS with audio buffer
+     * ```typescript
+     * const result = await neurolink.stream({
+     *   input: { text: "Speak slowly" },
+     *   provider: "google-ai",
+     *   tts: {
+     *     enabled: true,
+     *     voice: "en-US-Neural2-D",
+     *     speed: 0.8,
+     *     format: "mp3",
+     *     quality: "hd"
+     *   }
+     * });
+     * ```
+     */
+    tts?: TTSOptions;
     provider?: AIProviderName | string;
     model?: string;
     region?: string;

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

@@ -75,6 +75,10 @@ export type AudioSaveResult = {
     /** Error message if failed */
     error?: string;
 };
+/** Allowed TTS voice types */
+export type VoiceType = "standard" | "wavenet" | "neural" | "chirp" | "unknown";
+/** Allowed genders for TTS voices */
+export type Gender = "male" | "female" | "neutral";
 /**
  * TTS voice information
  */
@@ -83,12 +87,18 @@ export type TTSVoice = {
     id: string;
     /** Display name */
     name: string;
-    /** Language code (e.g., "en-US") */
+    /** Primary language code (e.g., "en-US") */
     languageCode: string;
+    /** All supported language codes */
+    languageCodes: string[];
     /** Gender */
-    gender: "male" | "female" | "neutral";
+    gender: Gender;
     /** Voice type */
-    type: "neural" | "wavenet" | "standard";
+    type?: VoiceType;
+    /** Voice description (optional) */
+    description?: string;
+    /** Natural sample rate in Hz (optional) */
+    naturalSampleRateHertz?: number;
 };
 /** Valid audio formats as an array for runtime validation */
 export declare const VALID_AUDIO_FORMATS: readonly AudioFormat[];
@@ -104,3 +114,27 @@ export declare function isTTSResult(value: unknown): value is TTSResult;
  * Type guard to check if TTSOptions are valid
  */
 export declare function isValidTTSOptions(options: unknown): options is TTSOptions;
+/**
+ * TTS audio chunk for streaming Text-to-Speech output
+ *
+ * Represents a chunk of audio data generated during streaming TTS.
+ * Used in StreamChunk type to deliver audio alongside text content.
+ */
+export type TTSChunk = {
+    /** Audio data chunk as Buffer */
+    data: Buffer;
+    /** Audio format of this chunk */
+    format: AudioFormat;
+    /** Chunk sequence number (0-indexed) */
+    index: number;
+    /** Whether this is the final audio chunk */
+    isFinal: boolean;
+    /** Cumulative audio size in bytes so far */
+    cumulativeSize?: number;
+    /** Estimated total duration in seconds (if available) */
+    estimatedDuration?: number;
+    /** Voice used for generation */
+    voice?: string;
+    /** Sample rate in Hz */
+    sampleRate?: number;
+};

package/dist/types/generateTypes.d.ts

@@ -7,6 +7,7 @@ import type { ChatMessage, ConversationMemoryConfig } from "./conversation.js";
 import type { MiddlewareFactoryOptions } from "./middlewareTypes.js";
 import type { JsonValue } from "./common.js";
 import type { Content, ImageWithAltText } from "./content.js";
+import type { TTSOptions, TTSResult } from "./ttsTypes.js";
 /**
  * Generate function options type - Primary method for content generation
  * Supports multimodal content while maintaining backward compatibility
@@ -52,6 +53,39 @@ export type GenerateOptions = {
         format?: "jpeg" | "png";
         transcribeAudio?: boolean;
     };
+    /**
+     * Text-to-Speech (TTS) configuration
+     *
+     * Enable audio generation from the text response. The generated audio will be
+     * returned in the result's `audio` field as a TTSResult object.
+     *
+     * @example Basic TTS
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: "Tell me a story" },
+     *   provider: "google-ai",
+     *   tts: { enabled: true, voice: "en-US-Neural2-C" }
+     * });
+     * console.log(result.audio?.buffer); // Audio Buffer
+     * ```
+     *
+     * @example Advanced TTS with options
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: "Speak slowly and clearly" },
+     *   provider: "google-ai",
+     *   tts: {
+     *     enabled: true,
+     *     voice: "en-US-Neural2-D",
+     *     speed: 0.8,
+     *     pitch: 2.0,
+     *     format: "mp3",
+     *     quality: "standard"
+     *   }
+     * });
+     * ```
+     */
+    tts?: TTSOptions;
     provider?: AIProviderName | string;
     model?: string;
     region?: string;
@@ -144,6 +178,35 @@ export type GenerateResult = {
     outputs?: {
         text: string;
     };
+    /**
+     * Text-to-Speech audio result
+     *
+     * Contains the generated audio buffer and metadata when TTS is enabled.
+     * Generated by TTSProcessor.synthesize() using the specified provider.
+     *
+     * @example Accessing TTS audio
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: "Hello world" },
+     *   provider: "google-ai",
+     *   tts: { enabled: true, voice: "en-US-Neural2-C" }
+     * });
+     *
+     * if (result.audio) {
+     *   console.log(`Audio size: ${result.audio.size} bytes`);
+     *   console.log(`Format: ${result.audio.format}`);
+     *   if (result.audio.duration) {
+     *     console.log(`Duration: ${result.audio.duration}s`);
+     *   }
+     *   if (result.audio.voice) {
+     *     console.log(`Voice: ${result.audio.voice}`);
+     *   }
+     *   // Save or play the audio buffer
+     *   fs.writeFileSync('output.mp3', result.audio.buffer);
+     * }
+     * ```
+     */
+    audio?: TTSResult;
     provider?: string;
     model?: string;
     usage?: TokenUsage;

package/dist/types/streamTypes.d.ts

@@ -9,6 +9,7 @@ import type { EvaluationData } from "../index.js";
 import type { UnknownRecord, JsonValue } from "./common.js";
 import type { MiddlewareFactoryOptions } from "../types/middlewareTypes.js";
 import type { ChatMessage } from "./conversation.js";
+import type { TTSOptions, TTSChunk } from "./ttsTypes.js";
 /**
  * Progress tracking and metadata for streaming operations
  */
@@ -121,6 +122,60 @@ export type AudioChunk = {
     channels: number;
     encoding: PCMEncoding;
 };
+/**
+ * Stream chunk type using discriminated union for type safety
+ *
+ * Used in streaming responses to deliver either text or TTS audio chunks.
+ * The discriminated union ensures type safety - only one variant can exist at a time.
+ *
+ * @example Processing text chunks
+ * ```typescript
+ * for await (const chunk of result.stream) {
+ *   if (chunk.type === "text") {
+ *     console.log(chunk.content); // TypeScript knows 'content' exists
+ *   }
+ * }
+ * ```
+ *
+ * @example Processing audio chunks
+ * ```typescript
+ * const audioBuffer: Buffer[] = [];
+ * for await (const chunk of result.stream) {
+ *   if (chunk.type === "audio") {
+ *     audioBuffer.push(chunk.audioChunk.data); // TypeScript knows 'audioChunk' exists
+ *     if (chunk.audioChunk.isFinal) {
+ *       const fullAudio = Buffer.concat(audioBuffer);
+ *       fs.writeFileSync('output.mp3', fullAudio);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Processing both text and audio
+ * ```typescript
+ * for await (const chunk of result.stream) {
+ *   switch (chunk.type) {
+ *     case "text":
+ *       process.stdout.write(chunk.content);
+ *       break;
+ *     case "audio":
+ *       playAudioChunk(chunk.audioChunk.data);
+ *       break;
+ *   }
+ * }
+ * ```
+ */
+export type StreamChunk = {
+    /** Discriminator for text chunks */
+    type: "text";
+    /** Text content chunk */
+    content: string;
+} | {
+    /** Discriminator for audio chunks */
+    type: "audio";
+    /** TTS audio chunk data */
+    audioChunk: TTSChunk;
+};
 export type StreamOptions = {
     input: {
         text: string;
@@ -168,6 +223,46 @@ export type StreamOptions = {
         format?: "jpeg" | "png";
         transcribeAudio?: boolean;
     };
+    /**
+     * Text-to-Speech (TTS) configuration for streaming
+     *
+     * Enable audio generation from the streamed text response. Audio chunks will be
+     * delivered through the stream alongside text chunks as TTSChunk objects.
+     *
+     * @example Basic streaming TTS
+     * ```typescript
+     * const result = await neurolink.stream({
+     *   input: { text: "Tell me a story" },
+     *   provider: "google-ai",
+     *   tts: { enabled: true, voice: "en-US-Neural2-C" }
+     * });
+     *
+     * for await (const chunk of result.stream) {
+     *   if (chunk.type === "text") {
+     *     process.stdout.write(chunk.content);
+     *   } else if (chunk.type === "audio") {
+     *     // Handle audio chunk
+     *     playAudioChunk(chunk.audioChunk.data);
+     *   }
+     * }
+     * ```
+     *
+     * @example Advanced streaming TTS with audio buffer
+     * ```typescript
+     * const result = await neurolink.stream({
+     *   input: { text: "Speak slowly" },
+     *   provider: "google-ai",
+     *   tts: {
+     *     enabled: true,
+     *     voice: "en-US-Neural2-D",
+     *     speed: 0.8,
+     *     format: "mp3",
+     *     quality: "hd"
+     *   }
+     * });
+     * ```
+     */
+    tts?: TTSOptions;
     provider?: AIProviderName | string;
     model?: string;
     region?: string;

package/dist/types/ttsTypes.d.ts

@@ -75,6 +75,10 @@ export type AudioSaveResult = {
     /** Error message if failed */
     error?: string;
 };
+/** Allowed TTS voice types */
+export type VoiceType = "standard" | "wavenet" | "neural" | "chirp" | "unknown";
+/** Allowed genders for TTS voices */
+export type Gender = "male" | "female" | "neutral";
 /**
  * TTS voice information
  */
@@ -83,12 +87,18 @@ export type TTSVoice = {
     id: string;
     /** Display name */
     name: string;
-    /** Language code (e.g., "en-US") */
+    /** Primary language code (e.g., "en-US") */
     languageCode: string;
+    /** All supported language codes */
+    languageCodes: string[];
     /** Gender */
-    gender: "male" | "female" | "neutral";
+    gender: Gender;
     /** Voice type */
-    type: "neural" | "wavenet" | "standard";
+    type?: VoiceType;
+    /** Voice description (optional) */
+    description?: string;
+    /** Natural sample rate in Hz (optional) */
+    naturalSampleRateHertz?: number;
 };
 /** Valid audio formats as an array for runtime validation */
 export declare const VALID_AUDIO_FORMATS: readonly AudioFormat[];
@@ -104,3 +114,27 @@ export declare function isTTSResult(value: unknown): value is TTSResult;
  * Type guard to check if TTSOptions are valid
  */
 export declare function isValidTTSOptions(options: unknown): options is TTSOptions;
+/**
+ * TTS audio chunk for streaming Text-to-Speech output
+ *
+ * Represents a chunk of audio data generated during streaming TTS.
+ * Used in StreamChunk type to deliver audio alongside text content.
+ */
+export type TTSChunk = {
+    /** Audio data chunk as Buffer */
+    data: Buffer;
+    /** Audio format of this chunk */
+    format: AudioFormat;
+    /** Chunk sequence number (0-indexed) */
+    index: number;
+    /** Whether this is the final audio chunk */
+    isFinal: boolean;
+    /** Cumulative audio size in bytes so far */
+    cumulativeSize?: number;
+    /** Estimated total duration in seconds (if available) */
+    estimatedDuration?: number;
+    /** Voice used for generation */
+    voice?: string;
+    /** Sample rate in Hz */
+    sampleRate?: number;
+};

package/package.json

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