@juspay/neurolink 8.18.0 → 8.19.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [8.19.1](https://github.com/juspay/neurolink/compare/v8.19.0...v8.19.1) (2025-12-20)
+
+### Bug Fixes
+
+- **(files):** comprehensive extension-less file detection with fallback parsing (FD-018) ([7e9dbc7](https://github.com/juspay/neurolink/commit/7e9dbc78df48f6df051c7845824977f360f8feee))
+
+## [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/adapters/providerImageAdapter.d.ts

@@ -60,4 +60,16 @@ export declare class ProviderImageAdapter {
      * Get all vision-capable providers
      */
     static getVisionProviders(): string[];
+    /**
+     * Count total "images" in a message (actual images + PDF pages)
+     * PDF pages count toward image limits for providers
+     */
+    static countImagesInMessage(images: Array<Buffer | string>, pdfPages?: number | null): number;
+    /**
+     * Extract page count from PDF metadata array
+     * Returns total pages across all PDFs
+     */
+    static countImagesInPages(pdfMetadataArray: Array<{
+        pageCount?: number | null;
+    }> | undefined): number;
 }

package/dist/adapters/providerImageAdapter.js

@@ -416,13 +416,19 @@ export class ProviderImageAdapter {
                     adaptedPayload = this.formatForOpenAI(text, images);
                     break;
                 case "litellm":
-                    adaptedPayload = this.formatForOpenAI(text, images);
+                    // LiteLLM uses same format as OpenAI but validate with litellm provider name
+                    this.validateImageCount(images.length, "litellm");
+                    adaptedPayload = this.formatForOpenAI(text, images, true);
                     break;
                 case "mistral":
-                    adaptedPayload = this.formatForOpenAI(text, images);
+                    // Mistral uses same format as OpenAI but validate with mistral provider name
+                    this.validateImageCount(images.length, "mistral");
+                    adaptedPayload = this.formatForOpenAI(text, images, true);
                     break;
                 case "bedrock":
-                    adaptedPayload = this.formatForAnthropic(text, images);
+                    // Bedrock uses same format as Anthropic but validate with bedrock provider name
+                    this.validateImageCount(images.length, "bedrock");
+                    adaptedPayload = this.formatForAnthropic(text, images, true);
                     break;
                 default:
                     throw new Error(`Vision not supported for provider: ${provider}`);
@@ -666,4 +672,25 @@ export class ProviderImageAdapter {
     static getVisionProviders() {
         return Object.keys(VISION_CAPABILITIES);
     }
+    /**
+     * Count total "images" in a message (actual images + PDF pages)
+     * PDF pages count toward image limits for providers
+     */
+    static countImagesInMessage(images, pdfPages) {
+        const imageCount = images?.length || 0;
+        const pageCount = pdfPages ?? 0;
+        return imageCount + pageCount;
+    }
+    /**
+     * Extract page count from PDF metadata array
+     * Returns total pages across all PDFs
+     */
+    static countImagesInPages(pdfMetadataArray) {
+        if (!pdfMetadataArray || pdfMetadataArray.length === 0) {
+            return 0;
+        }
+        return pdfMetadataArray.reduce((total, pdf) => {
+            return total + (pdf.pageCount ?? 0);
+        }, 0);
+    }
 }

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

@@ -24,8 +24,9 @@ export declare const CONVERSATION_INSTRUCTIONS = "\n\nIMPORTANT: You are continu
  * Structured output instructions for JSON/structured output mode
  * Used to ensure AI providers output only valid JSON without conversational filler
  * This addresses the issue where models add text like "Excellent!" before JSON output
+ * and the case where tools are used but final output must still be pure JSON
  */
-export declare const STRUCTURED_OUTPUT_INSTRUCTIONS = "\n\nSTRUCTURED OUTPUT REQUIREMENT:\nYou MUST respond with ONLY a valid JSON object that matches the provided schema.\n- Do NOT include any text before the JSON (no greetings, acknowledgments, or preamble like \"Excellent!\", \"Sure!\", \"Here is the result:\", etc.)\n- Do NOT include any text after the JSON (no explanations, summaries, or follow-up comments)\n- Do NOT wrap the JSON in markdown code blocks\n- Output ONLY the raw JSON object, starting with { and ending with }\n- Ensure the JSON is valid and parseable";
+export declare const STRUCTURED_OUTPUT_INSTRUCTIONS = "\nOutput ONLY valid JSON. No markdown, text, or decorations\u2014ever.\n\nFORBIDDEN: markdown code blocks, text before/after JSON, explanations, preambles, summaries, conversational text about tools.\n\nREQUIRED: response starts with { and ends with }, valid JSON only, no additional characters.\n\nIF YOU CALLED TOOLS: Incorporate data directly into the JSON structure. Do NOT explain what you did.\n\nWRONG: ```json\n{\"field\": \"value\"}\n```\nWRONG: Based on the data, here's the result: {\"field\": \"value\"}\nCORRECT: {\"field\": \"value\"}\n\nYour entire response = raw JSON object. Nothing else.";
 /**
  * Get default configuration values for conversation memory
  * Reads environment variables when called (not at module load time)

package/dist/config/conversationMemory.js

@@ -30,16 +30,24 @@ Always reference and build upon this conversation history when relevant. If the
  * Structured output instructions for JSON/structured output mode
  * Used to ensure AI providers output only valid JSON without conversational filler
  * This addresses the issue where models add text like "Excellent!" before JSON output
+ * and the case where tools are used but final output must still be pure JSON
  */
 export const STRUCTURED_OUTPUT_INSTRUCTIONS = `
+Output ONLY valid JSON. No markdown, text, or decorations—ever.
 
-STRUCTURED OUTPUT REQUIREMENT:
-You MUST respond with ONLY a valid JSON object that matches the provided schema.
-- Do NOT include any text before the JSON (no greetings, acknowledgments, or preamble like "Excellent!", "Sure!", "Here is the result:", etc.)
-- Do NOT include any text after the JSON (no explanations, summaries, or follow-up comments)
-- Do NOT wrap the JSON in markdown code blocks
-- Output ONLY the raw JSON object, starting with { and ending with }
-- Ensure the JSON is valid and parseable`;
+FORBIDDEN: markdown code blocks, text before/after JSON, explanations, preambles, summaries, conversational text about tools.
+
+REQUIRED: response starts with { and ends with }, valid JSON only, no additional characters.
+
+IF YOU CALLED TOOLS: Incorporate data directly into the JSON structure. Do NOT explain what you did.
+
+WRONG: \`\`\`json
+{"field": "value"}
+\`\`\`
+WRONG: Based on the data, here's the result: {"field": "value"}
+CORRECT: {"field": "value"}
+
+Your entire response = raw JSON object. Nothing else.`;
 /**
  * Get default configuration values for conversation memory
  * Reads environment variables when called (not at module load time)

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,30 @@ export class BaseProvider {
         this.validateOptions(options);
         const startTime = Date.now();
         try {
+            // ===== TTS MODE 1: Direct Input Synthesis (useAiResponse=false) =====
+            // Synthesize input text directly without AI generation
+            // This is optimal for simple read-aloud scenarios
+            if (options.tts?.enabled && !options.tts?.useAiResponse) {
+                const textToSynthesize = options.prompt ?? options.input?.text ?? "";
+                // Build base result structure - common to both paths
+                const baseResult = {
+                    content: textToSynthesize,
+                    provider: options.provider ?? this.providerName,
+                    model: this.modelName,
+                    usage: { input: 0, output: 0, total: 0 },
+                };
+                try {
+                    const ttsResult = await TTSProcessor.synthesize(textToSynthesize, options.provider ?? this.providerName, options.tts);
+                    baseResult.audio = ttsResult;
+                }
+                catch (ttsError) {
+                    logger.error(`TTS synthesis failed in Mode 1 (direct input synthesis):`, ttsError);
+                    // baseResult remains without audio - graceful degradation
+                }
+                // Call enhanceResult for consistency - enables analytics/evaluation for TTS-only requests
+                return await this.enhanceResult(baseResult, options, startTime);
+            }
+            // ===== Normal AI Generation Flow =====
             const { tools, model } = await this.prepareGenerationContext(options);
             const messages = await this.buildMessages(options);
             const generateResult = await this.executeGeneration(model, messages, tools, options);
@@ -314,7 +354,44 @@ export class BaseProvider {
             const responseTime = Date.now() - startTime;
             await this.recordPerformanceMetrics(generateResult.usage, responseTime);
             const { toolsUsed, toolExecutions } = this.extractToolInformation(generateResult);
-            const enhancedResult = this.formatEnhancedResult(generateResult, tools, toolsUsed, toolExecutions, options);
+            let enhancedResult = this.formatEnhancedResult(generateResult, tools, toolsUsed, toolExecutions, options);
+            // ===== TTS MODE 2: AI Response Synthesis (useAiResponse=true) =====
+            // Synthesize AI-generated response after generation completes
+            if (options.tts?.enabled && options.tts?.useAiResponse) {
+                const aiResponse = enhancedResult.content;
+                const provider = options.provider ?? this.providerName;
+                // Validate AI response and provider before synthesis
+                if (aiResponse && provider) {
+                    try {
+                        const ttsResult = await TTSProcessor.synthesize(aiResponse, provider, options.tts);
+                        // Add audio to enhanced result (TTSProcessor already includes latency in metadata)
+                        enhancedResult = {
+                            ...enhancedResult,
+                            audio: ttsResult,
+                        };
+                    }
+                    catch (ttsError) {
+                        // Log TTS error but continue with text-only result
+                        logger.error(`TTS synthesis failed in Mode 2 (AI response synthesis):`, ttsError);
+                        // enhancedResult remains unchanged (no audio field added)
+                    }
+                }
+                else {
+                    logger.warn(`TTS synthesis skipped despite being enabled`, {
+                        provider: this.providerName,
+                        hasAiResponse: !!aiResponse,
+                        aiResponseLength: aiResponse?.length ?? 0,
+                        hasProvider: !!provider,
+                        ttsConfig: {
+                            enabled: options.tts?.enabled,
+                            useAiResponse: options.tts?.useAiResponse,
+                        },
+                        reason: !aiResponse
+                            ? "AI response is empty or undefined"
+                            : "Provider is missing",
+                    });
+                }
+            }
             return await this.enhanceResult(enhancedResult, options, startTime);
         }
         catch (error) {
@@ -361,6 +438,7 @@ export class BaseProvider {
             enhancedWithTools: !!(result.toolsUsed && result.toolsUsed.length > 0),
             analytics: result.analytics,
             evaluation: result.evaluation,
+            audio: result.audio,
         };
     }
     /**

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

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

package/dist/core/modules/GenerationHandler.js

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

package/dist/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/adapters/providerImageAdapter.d.ts

@@ -60,4 +60,16 @@ export declare class ProviderImageAdapter {
      * Get all vision-capable providers
      */
     static getVisionProviders(): string[];
+    /**
+     * Count total "images" in a message (actual images + PDF pages)
+     * PDF pages count toward image limits for providers
+     */
+    static countImagesInMessage(images: Array<Buffer | string>, pdfPages?: number | null): number;
+    /**
+     * Extract page count from PDF metadata array
+     * Returns total pages across all PDFs
+     */
+    static countImagesInPages(pdfMetadataArray: Array<{
+        pageCount?: number | null;
+    }> | undefined): number;
 }

package/dist/lib/adapters/providerImageAdapter.js

@@ -416,13 +416,19 @@ export class ProviderImageAdapter {
                     adaptedPayload = this.formatForOpenAI(text, images);
                     break;
                 case "litellm":
-                    adaptedPayload = this.formatForOpenAI(text, images);
+                    // LiteLLM uses same format as OpenAI but validate with litellm provider name
+                    this.validateImageCount(images.length, "litellm");
+                    adaptedPayload = this.formatForOpenAI(text, images, true);
                     break;
                 case "mistral":
-                    adaptedPayload = this.formatForOpenAI(text, images);
+                    // Mistral uses same format as OpenAI but validate with mistral provider name
+                    this.validateImageCount(images.length, "mistral");
+                    adaptedPayload = this.formatForOpenAI(text, images, true);
                     break;
                 case "bedrock":
-                    adaptedPayload = this.formatForAnthropic(text, images);
+                    // Bedrock uses same format as Anthropic but validate with bedrock provider name
+                    this.validateImageCount(images.length, "bedrock");
+                    adaptedPayload = this.formatForAnthropic(text, images, true);
                     break;
                 default:
                     throw new Error(`Vision not supported for provider: ${provider}`);
@@ -666,5 +672,26 @@ export class ProviderImageAdapter {
     static getVisionProviders() {
         return Object.keys(VISION_CAPABILITIES);
     }
+    /**
+     * Count total "images" in a message (actual images + PDF pages)
+     * PDF pages count toward image limits for providers
+     */
+    static countImagesInMessage(images, pdfPages) {
+        const imageCount = images?.length || 0;
+        const pageCount = pdfPages ?? 0;
+        return imageCount + pageCount;
+    }
+    /**
+     * Extract page count from PDF metadata array
+     * Returns total pages across all PDFs
+     */
+    static countImagesInPages(pdfMetadataArray) {
+        if (!pdfMetadataArray || pdfMetadataArray.length === 0) {
+            return 0;
+        }
+        return pdfMetadataArray.reduce((total, pdf) => {
+            return total + (pdf.pageCount ?? 0);
+        }, 0);
+    }
 }
 //# sourceMappingURL=providerImageAdapter.js.map

package/dist/lib/config/conversationMemory.d.ts

@@ -24,8 +24,9 @@ export declare const CONVERSATION_INSTRUCTIONS = "\n\nIMPORTANT: You are continu
  * Structured output instructions for JSON/structured output mode
  * Used to ensure AI providers output only valid JSON without conversational filler
  * This addresses the issue where models add text like "Excellent!" before JSON output
+ * and the case where tools are used but final output must still be pure JSON
  */
-export declare const STRUCTURED_OUTPUT_INSTRUCTIONS = "\n\nSTRUCTURED OUTPUT REQUIREMENT:\nYou MUST respond with ONLY a valid JSON object that matches the provided schema.\n- Do NOT include any text before the JSON (no greetings, acknowledgments, or preamble like \"Excellent!\", \"Sure!\", \"Here is the result:\", etc.)\n- Do NOT include any text after the JSON (no explanations, summaries, or follow-up comments)\n- Do NOT wrap the JSON in markdown code blocks\n- Output ONLY the raw JSON object, starting with { and ending with }\n- Ensure the JSON is valid and parseable";
+export declare const STRUCTURED_OUTPUT_INSTRUCTIONS = "\nOutput ONLY valid JSON. No markdown, text, or decorations\u2014ever.\n\nFORBIDDEN: markdown code blocks, text before/after JSON, explanations, preambles, summaries, conversational text about tools.\n\nREQUIRED: response starts with { and ends with }, valid JSON only, no additional characters.\n\nIF YOU CALLED TOOLS: Incorporate data directly into the JSON structure. Do NOT explain what you did.\n\nWRONG: ```json\n{\"field\": \"value\"}\n```\nWRONG: Based on the data, here's the result: {\"field\": \"value\"}\nCORRECT: {\"field\": \"value\"}\n\nYour entire response = raw JSON object. Nothing else.";
 /**
  * Get default configuration values for conversation memory
  * Reads environment variables when called (not at module load time)

package/dist/lib/config/conversationMemory.js

@@ -30,16 +30,24 @@ Always reference and build upon this conversation history when relevant. If the
  * Structured output instructions for JSON/structured output mode
  * Used to ensure AI providers output only valid JSON without conversational filler
  * This addresses the issue where models add text like "Excellent!" before JSON output
+ * and the case where tools are used but final output must still be pure JSON
  */
 export const STRUCTURED_OUTPUT_INSTRUCTIONS = `
+Output ONLY valid JSON. No markdown, text, or decorations—ever.
 
-STRUCTURED OUTPUT REQUIREMENT:
-You MUST respond with ONLY a valid JSON object that matches the provided schema.
-- Do NOT include any text before the JSON (no greetings, acknowledgments, or preamble like "Excellent!", "Sure!", "Here is the result:", etc.)
-- Do NOT include any text after the JSON (no explanations, summaries, or follow-up comments)
-- Do NOT wrap the JSON in markdown code blocks
-- Output ONLY the raw JSON object, starting with { and ending with }
-- Ensure the JSON is valid and parseable`;
+FORBIDDEN: markdown code blocks, text before/after JSON, explanations, preambles, summaries, conversational text about tools.
+
+REQUIRED: response starts with { and ends with }, valid JSON only, no additional characters.
+
+IF YOU CALLED TOOLS: Incorporate data directly into the JSON structure. Do NOT explain what you did.
+
+WRONG: \`\`\`json
+{"field": "value"}
+\`\`\`
+WRONG: Based on the data, here's the result: {"field": "value"}
+CORRECT: {"field": "value"}
+
+Your entire response = raw JSON object. Nothing else.`;
 /**
  * Get default configuration values for conversation memory
  * Reads environment variables when called (not at module load time)

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
      */