@juspay/neurolink 8.5.1 → 8.7.0

package/dist/lib/neurolink.js

@@ -1998,19 +1998,85 @@ Current user's request: ${currentInput}`;
                     }
                 }
                 const { stream: mcpStream, provider: providerName } = await this.createMCPStream(enhancedOptions);
-                // Create a wrapper around the stream that accumulates content
                 let accumulatedContent = "";
+                let chunkCount = 0;
+                const metadata = {
+                    fallbackAttempted: false,
+                    guardrailsBlocked: false,
+                    error: undefined,
+                };
                 const processedStream = (async function* (self) {
                     try {
                         for await (const chunk of mcpStream) {
+                            chunkCount++;
                             if (chunk &&
                                 "content" in chunk &&
                                 typeof chunk.content === "string") {
                                 accumulatedContent += chunk.content;
-                                // Emit chunk event for compatibility
                                 self.emitter.emit("response:chunk", chunk.content);
                             }
-                            yield chunk; // Preserve original streaming behavior
+                            yield chunk;
+                        }
+                        if (chunkCount === 0 && !metadata.fallbackAttempted) {
+                            metadata.fallbackAttempted = true;
+                            const errorMsg = "Stream completed with 0 chunks (possible guardrails block)";
+                            metadata.error = errorMsg;
+                            const fallbackRoute = ModelRouter.getFallbackRoute(originalPrompt || enhancedOptions.input.text || "", {
+                                provider: providerName,
+                                model: enhancedOptions.model || "gpt-4o",
+                                reasoning: "primary failed",
+                                confidence: 0.5,
+                            }, { fallbackStrategy: "auto" });
+                            logger.warn("Retrying with fallback provider", {
+                                originalProvider: providerName,
+                                fallbackProvider: fallbackRoute.provider,
+                                reason: errorMsg,
+                            });
+                            try {
+                                const fallbackProvider = await AIProviderFactory.createProvider(fallbackRoute.provider, fallbackRoute.model);
+                                // Ensure fallback provider can execute tools
+                                fallbackProvider.setupToolExecutor({
+                                    customTools: self.getCustomTools(),
+                                    executeTool: self.executeTool.bind(self),
+                                }, "NeuroLink.fallbackStream");
+                                // Get conversation messages for context (same as primary stream)
+                                const conversationMessages = await getConversationMessages(self.conversationMemory, {
+                                    prompt: enhancedOptions.input.text,
+                                    context: enhancedOptions.context,
+                                });
+                                const fallbackResult = await fallbackProvider.stream({
+                                    ...enhancedOptions,
+                                    model: fallbackRoute.model,
+                                    conversationMessages,
+                                });
+                                let fallbackChunkCount = 0;
+                                for await (const fallbackChunk of fallbackResult.stream) {
+                                    fallbackChunkCount++;
+                                    if (fallbackChunk &&
+                                        "content" in fallbackChunk &&
+                                        typeof fallbackChunk.content === "string") {
+                                        accumulatedContent += fallbackChunk.content;
+                                        self.emitter.emit("response:chunk", fallbackChunk.content);
+                                    }
+                                    yield fallbackChunk;
+                                }
+                                if (fallbackChunkCount === 0) {
+                                    throw new Error(`Fallback provider ${fallbackRoute.provider} also returned 0 chunks`);
+                                }
+                                // Fallback succeeded - likely guardrails blocked primary
+                                metadata.guardrailsBlocked = true;
+                            }
+                            catch (fallbackError) {
+                                const fallbackErrorMsg = fallbackError instanceof Error
+                                    ? fallbackError.message
+                                    : String(fallbackError);
+                                metadata.error = `${errorMsg}; Fallback failed: ${fallbackErrorMsg}`;
+                                logger.error("Fallback provider failed", {
+                                    fallbackProvider: fallbackRoute.provider,
+                                    error: fallbackErrorMsg,
+                                });
+                                throw fallbackError;
+                            }
                         }
                     }
                     finally {
@@ -2053,7 +2119,7 @@ Current user's request: ${currentInput}`;
                         }
                     }
                 })(this);
-                const streamResult = await this.processStreamResult(mcpStream, enhancedOptions, factoryResult);
+                const streamResult = await this.processStreamResult(processedStream, enhancedOptions, factoryResult);
                 const responseTime = Date.now() - startTime;
                 this.emitStreamEndEvents(streamResult);
                 return this.createStreamResponse(streamResult, processedStream, {
@@ -2062,7 +2128,9 @@ Current user's request: ${currentInput}`;
                     startTime,
                     responseTime,
                     streamId,
-                    fallback: false,
+                    fallback: metadata.fallbackAttempted,
+                    guardrailsBlocked: metadata.guardrailsBlocked,
+                    error: metadata.error,
                 });
             }
             catch (error) {
@@ -2181,6 +2249,8 @@ Current user's request: ${currentInput}`;
                 startTime: config.startTime,
                 responseTime: config.responseTime,
                 fallback: config.fallback || false,
+                guardrailsBlocked: config.guardrailsBlocked,
+                error: config.error,
             },
         };
     }

package/dist/lib/telemetry/telemetryService.d.ts

@@ -31,7 +31,7 @@ export declare class TelemetryService {
     private initializeTelemetry;
     private initializeMetrics;
     initialize(): Promise<void>;
-    traceAIRequest<T>(provider: string, operation: () => Promise<T>): Promise<T>;
+    traceAIRequest<T>(provider: string, operation: () => Promise<T>, operationType?: string): Promise<T>;
     recordAIRequest(provider: string, model: string, tokens: number, duration: number): void;
     recordAIError(provider: string, error: Error): void;
     recordMCPToolCall(toolName: string, duration: number, success: boolean): void;

package/dist/lib/telemetry/telemetryService.js

@@ -108,14 +108,14 @@ export class TelemetryService {
         }
     }
     // AI Operation Tracing (NO-OP when disabled)
-    async traceAIRequest(provider, operation) {
+    async traceAIRequest(provider, operation, operationType = "generate_text") {
         if (!this.enabled || !this.tracer) {
-            return await operation(); // Direct execution when disabled
+            return await operation();
         }
-        const span = this.tracer.startSpan(`ai.${provider}.generate_text`, {
+        const span = this.tracer.startSpan(`ai.${provider}.${operationType}`, {
             attributes: {
                 "ai.provider": provider,
-                "ai.operation": "generate_text",
+                "ai.operation": operationType,
             },
         });
         try {

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

@@ -337,6 +337,8 @@ export type GenerateResult = CommandResult & {
         name: string;
         description: string;
     }>;
+    /** TTS audio result when TTS is enabled */
+    audio?: import("./index.js").TTSResult;
 };
 /**
  * Stream result chunk

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

@@ -129,3 +129,8 @@ export type TypedEventEmitter<TEvents extends Record<string, unknown>> = {
     listenerCount<K extends keyof TEvents>(event: K): number;
     listeners<K extends keyof TEvents>(event: K): Array<(...args: unknown[]) => void>;
 };
+export type Context = {
+    traceName?: string;
+    userId?: string;
+    sessionId?: string;
+};

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

@@ -14,5 +14,5 @@
  * import type { MultimodalInput } from './types/multimodal.js';
  * ```
  */
-export type { TextContent, ImageContent, CSVContent, PDFContent, AudioContent, VideoContent, Content, MultimodalInput, MultimodalMessage, VisionCapability, ProviderImageFormat, ProcessedImage, ProviderMultimodalPayload, } from "./multimodal.js";
+export type { TextContent, ImageContent, CSVContent, PDFContent, AudioContent, VideoContent, Content, ImageWithAltText, MultimodalInput, MultimodalMessage, VisionCapability, ProviderImageFormat, ProcessedImage, ProviderMultimodalPayload, } from "./multimodal.js";
 export { isTextContent, isImageContent, isCSVContent, isPDFContent, isAudioContent, isVideoContent, isMultimodalInput, } from "./multimodal.js";

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

@@ -81,18 +81,7 @@ export type PDFProcessorOptions = {
     bedrockApiMode?: "converse" | "invokeModel";
 };
 /**
- * File detector options
- */
-export type FileDetectorOptions = {
-    maxSize?: number;
-    timeout?: number;
-    allowedTypes?: FileType[];
-    csvOptions?: CSVProcessorOptions;
-    confidenceThreshold?: number;
-    provider?: string;
-};
-/**
- * Audio processor options for transcription configuration
+ * Audio processor options
  */
 export type AudioProcessorOptions = {
     /** AI provider to use for transcription (e.g., 'openai', 'google', 'azure') */
@@ -108,6 +97,18 @@ export type AudioProcessorOptions = {
     /** Maximum file size in megabytes */
     maxSizeMB?: number;
 };
+/**
+ * File detector options
+ */
+export type FileDetectorOptions = {
+    maxSize?: number;
+    timeout?: number;
+    allowedTypes?: FileType[];
+    audioOptions?: AudioProcessorOptions;
+    csvOptions?: CSVProcessorOptions;
+    confidenceThreshold?: number;
+    provider?: string;
+};
 /**
  * Google AI Studio Files API types
  */

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

@@ -6,7 +6,7 @@ import type { EvaluationData } from "./evaluation.js";
 import type { ChatMessage, ConversationMemoryConfig } from "./conversation.js";
 import type { MiddlewareFactoryOptions } from "./middlewareTypes.js";
 import type { JsonValue } from "./common.js";
-import type { Content } from "./content.js";
+import type { Content, ImageWithAltText } from "./content.js";
 /**
  * Generate function options type - Primary method for content generation
  * Supports multimodal content while maintaining backward compatibility
@@ -14,7 +14,24 @@ import type { Content } from "./content.js";
 export type GenerateOptions = {
     input: {
         text: string;
-        images?: Array<Buffer | string>;
+        /**
+         * Images to include in the request.
+         * Supports simple image data (Buffer, string) or objects with alt text for accessibility.
+         *
+         * @example Simple usage
+         * ```typescript
+         * images: [imageBuffer, "https://example.com/image.jpg"]
+         * ```
+         *
+         * @example With alt text for accessibility
+         * ```typescript
+         * images: [
+         *   { data: imageBuffer, altText: "Product screenshot showing main dashboard" },
+         *   { data: "https://example.com/chart.png", altText: "Sales chart for Q3 2024" }
+         * ]
+         * ```
+         */
+        images?: Array<Buffer | string | ImageWithAltText>;
         csvFiles?: Array<Buffer | string>;
         pdfFiles?: Array<Buffer | string>;
         files?: Array<Buffer | string>;

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

@@ -32,3 +32,4 @@ export * from "./utilities.js";
 export * from "./middlewareTypes.js";
 export * from "./fileTypes.js";
 export * from "./content.js";
+export * from "./ttsTypes.js";

package/dist/lib/types/index.js

@@ -35,4 +35,6 @@ export * from "./middlewareTypes.js";
 export * from "./fileTypes.js";
 // Content types for multimodal support
 export * from "./content.js";
+// TTS (Text-to-Speech) types
+export * from "./ttsTypes.js";
 //# sourceMappingURL=index.js.map

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

@@ -52,6 +52,8 @@ export type TextContent = {
 export type ImageContent = {
     type: "image";
     data: Buffer | string;
+    /** Alternative text for accessibility (screen readers, SEO) */
+    altText?: string;
     mediaType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp" | "image/bmp" | "image/tiff";
     metadata?: {
         description?: string;
@@ -164,13 +166,48 @@ export type VideoContent = {
  * Covers text, images, documents, and multimedia
  */
 export type Content = TextContent | ImageContent | CSVContent | PDFContent | AudioContent | VideoContent;
+/**
+ * Image data with optional alt text for accessibility
+ * Use this when you need to provide alt text for screen readers and SEO
+ *
+ * @example
+ * ```typescript
+ * const imageWithAlt: ImageWithAltText = {
+ *   data: imageBuffer,
+ *   altText: "A dashboard showing quarterly sales trends"
+ * };
+ * ```
+ */
+export type ImageWithAltText = {
+    /** Image data as Buffer, base64 string, URL, or data URI */
+    data: Buffer | string;
+    /** Alternative text for accessibility (screen readers, SEO) */
+    altText?: string;
+};
 /**
  * Multimodal input type for options that may contain images or content arrays
  * This is the primary interface for users to provide multimodal content
  */
 export type MultimodalInput = {
     text: string;
-    images?: Array<Buffer | string>;
+    /**
+     * Images to include in the request.
+     * Can be simple image data (Buffer, string) or objects with alt text for accessibility.
+     *
+     * @example Simple usage
+     * ```typescript
+     * images: [imageBuffer, "https://example.com/image.jpg"]
+     * ```
+     *
+     * @example With alt text for accessibility
+     * ```typescript
+     * images: [
+     *   { data: imageBuffer, altText: "Product screenshot showing main dashboard" },
+     *   { data: "https://example.com/chart.png", altText: "Sales chart for Q3 2024" }
+     * ]
+     * ```
+     */
+    images?: Array<Buffer | string | ImageWithAltText>;
     content?: Content[];
     csvFiles?: Array<Buffer | string>;
     pdfFiles?: Array<Buffer | string>;

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

@@ -1,7 +1,7 @@
 import type { Tool } from "ai";
 import type { ValidationSchema, StandardRecord } from "./typeAliases.js";
 import type { AIModelProviderConfig } from "./providers.js";
-import type { Content } from "./content.js";
+import type { Content, ImageWithAltText } from "./content.js";
 import type { AnalyticsData, ToolExecutionEvent, ToolExecutionSummary } from "../types/index.js";
 import { AIProviderName } from "../constants/enums.js";
 import type { TokenUsage } from "./analytics.js";
@@ -125,7 +125,24 @@ export type StreamOptions = {
     input: {
         text: string;
         audio?: AudioInputSpec;
-        images?: Array<Buffer | string>;
+        /**
+         * Images to include in the request.
+         * Supports simple image data (Buffer, string) or objects with alt text for accessibility.
+         *
+         * @example Simple usage
+         * ```typescript
+         * images: [imageBuffer, "https://example.com/image.jpg"]
+         * ```
+         *
+         * @example With alt text for accessibility
+         * ```typescript
+         * images: [
+         *   { data: imageBuffer, altText: "Product screenshot showing main dashboard" },
+         *   { data: "https://example.com/chart.png", altText: "Sales chart for Q3 2024" }
+         * ]
+         * ```
+         */
+        images?: Array<Buffer | string | ImageWithAltText>;
         csvFiles?: Array<Buffer | string>;
         pdfFiles?: Array<Buffer | string>;
         files?: Array<Buffer | string>;
@@ -211,6 +228,8 @@ export type StreamResult = {
         totalToolExecutions?: number;
         toolExecutionTime?: number;
         hasToolErrors?: boolean;
+        guardrailsBlocked?: boolean;
+        error?: string;
     };
     analytics?: AnalyticsData | Promise<AnalyticsData>;
     evaluation?: EvaluationData | Promise<EvaluationData>;

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

@@ -0,0 +1,91 @@
+/**
+ * Text-to-Speech (TTS) Type Definitions for NeuroLink
+ *
+ * This module defines types for TTS audio generation and output.
+ *
+ * @module types/ttsTypes
+ */
+/**
+ * Supported audio formats for TTS output
+ */
+export type AudioFormat = "mp3" | "wav" | "ogg" | "opus";
+/**
+ * TTS quality settings
+ */
+export type TTSQuality = "standard" | "hd";
+/**
+ * TTS configuration options
+ */
+export type TTSOptions = {
+    /** Enable TTS output */
+    enabled?: boolean;
+    /** Voice identifier (e.g., "en-US-Neural2-C") */
+    voice?: string;
+    /** Audio format (default: mp3) */
+    format?: AudioFormat;
+    /** Speaking rate 0.25-4.0 (default: 1.0) */
+    speed?: number;
+    /** Audio quality (default: standard) */
+    quality?: TTSQuality;
+    /** Output file path (optional) */
+    output?: string;
+    /** Auto-play audio after generation (default: false) */
+    play?: boolean;
+};
+/**
+ * TTS audio result returned from generation
+ */
+export type TTSResult = {
+    /** Audio data as Buffer */
+    buffer: Buffer;
+    /** Audio format */
+    format: AudioFormat;
+    /** Audio file size in bytes */
+    size: number;
+    /** Duration in seconds (if available) */
+    duration?: number;
+    /** Voice used for generation */
+    voice?: string;
+    /** Sample rate in Hz */
+    sampleRate?: number;
+};
+/**
+ * Result of saving audio to file
+ */
+export type AudioSaveResult = {
+    /** Whether the save was successful */
+    success: boolean;
+    /** Full path to the saved file */
+    path: string;
+    /** File size in bytes */
+    size: number;
+    /** Error message if failed */
+    error?: string;
+};
+/**
+ * TTS voice information
+ */
+export type TTSVoice = {
+    /** Voice identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Language code (e.g., "en-US") */
+    languageCode: string;
+    /** Gender */
+    gender: "male" | "female" | "neutral";
+    /** Voice type */
+    type: "neural" | "wavenet" | "standard";
+};
+/** Valid audio formats as an array for runtime validation */
+export declare const VALID_AUDIO_FORMATS: readonly AudioFormat[];
+/** Valid TTS quality levels as an array for runtime validation */
+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;
+/**
+ * Type guard to check if TTSOptions are valid
+ */
+export declare function isValidTTSOptions(options: unknown): options is TTSOptions;

package/dist/lib/types/ttsTypes.js

@@ -0,0 +1,58 @@
+/**
+ * Text-to-Speech (TTS) Type Definitions for NeuroLink
+ *
+ * This module defines types for TTS audio generation and output.
+ *
+ * @module types/ttsTypes
+ */
+/** Valid audio formats as an array for runtime validation */
+export const VALID_AUDIO_FORMATS = [
+    "mp3",
+    "wav",
+    "ogg",
+    "opus",
+];
+/** Valid TTS quality levels as an array for runtime validation */
+export const VALID_TTS_QUALITIES = ["standard", "hd"];
+/**
+ * Type guard to check if an object is a TTSResult
+ */
+export function isTTSResult(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const obj = value;
+    return (Buffer.isBuffer(obj.buffer) &&
+        typeof obj.format === "string" &&
+        VALID_AUDIO_FORMATS.includes(obj.format) &&
+        typeof obj.size === "number" &&
+        obj.size >= 0);
+}
+/**
+ * Type guard to check if TTSOptions are valid
+ */
+export function isValidTTSOptions(options) {
+    if (!options || typeof options !== "object") {
+        return false;
+    }
+    const opts = options;
+    if (opts.speed !== undefined) {
+        if (typeof opts.speed !== "number" ||
+            opts.speed < 0.25 ||
+            opts.speed > 4.0) {
+            return false;
+        }
+    }
+    if (opts.format !== undefined) {
+        if (!VALID_AUDIO_FORMATS.includes(opts.format)) {
+            return false;
+        }
+    }
+    if (opts.quality !== undefined) {
+        if (!VALID_TTS_QUALITIES.includes(opts.quality)) {
+            return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=ttsTypes.js.map

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

@@ -17,6 +17,18 @@ export declare class ImageProcessor {
      * @returns Processed image as data URI
      */
     static process(content: Buffer, _options?: unknown): Promise<FileProcessingResult>;
+    /**
+     * Validate processed output meets required format
+     * Checks:
+     * - Base64 content is non-empty
+     * - Data URI format is valid (data:{mimeType};base64,{content})
+     * - MIME type is in the allowed list
+     * @param dataUri - The complete data URI string
+     * @param base64 - The base64-encoded content
+     * @param mediaType - The MIME type of the image
+     * @throws Error if any validation fails
+     */
+    private static validateProcessOutput;
     /**
      * Process image for OpenAI (requires data URI format)
      */
@@ -104,11 +116,32 @@ export declare const imageUtils: {
      */
     fileToBase64DataUri: (filePath: string, maxBytes?: number) => Promise<string>;
     /**
-     * Convert URL to base64 data URI by downloading the image
-     */
-    urlToBase64DataUri: (url: string, { timeoutMs, maxBytes }?: {
-        timeoutMs?: number | undefined;
-        maxBytes?: number | undefined;
+     * Convert URL to base64 data URI by downloading the image.
+     * Implements retry logic with exponential backoff for network errors.
+     *
+     * Retries are performed for:
+     * - Network errors (ECONNRESET, ENOTFOUND, ECONNREFUSED, ETIMEDOUT, ERR_NETWORK, AbortError)
+     * - Server errors (5xx status codes)
+     * - Rate limiting (429 Too Many Requests)
+     * - Request timeouts (408 Request Timeout)
+     *
+     * Retries are NOT performed for:
+     * - Client errors (4xx status codes except 408, 429)
+     * - Invalid content type
+     * - Content size limit exceeded
+     * - Unsupported protocol
+     *
+     * @param url - The URL of the image to download
+     * @param options - Configuration options
+     * @param options.timeoutMs - Timeout for each download attempt (default: 15000ms)
+     * @param options.maxBytes - Maximum allowed file size (default: 10MB)
+     * @param options.maxAttempts - Maximum number of total attempts including initial attempt (default: 3)
+     * @returns Promise<string> - Base64 data URI of the downloaded image
+     */
+    urlToBase64DataUri: (url: string, { timeoutMs, maxBytes, maxAttempts, }?: {
+        timeoutMs?: number;
+        maxBytes?: number;
+        maxAttempts?: number;
     }) => Promise<string>;
     /**
      * Extract base64 data from data URI