@juspay/neurolink 7.45.0 → 7.47.0

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

@@ -0,0 +1,142 @@
+import type { LanguageModelV1CallOptions } from "ai";
+import type { TokenUsage } from "./analytics.js";
+import type { GenerateResult } from "./generateTypes.js";
+import type { ToolExecution } from "./tools.js";
+/**
+ * Represents the analysis of the user's query intent.
+ * This provides a basic understanding of what the user is trying to achieve.
+ */
+export interface QueryIntentAnalysis {
+    /** The type of query, e.g., asking a question or giving a command. */
+    type: "question" | "command" | "greeting" | "unknown";
+    /** The estimated complexity of the query. */
+    complexity: "low" | "medium" | "high";
+    /** Whether the query likely required the use of tools to be answered correctly. */
+    shouldHaveUsedTools: boolean;
+}
+/**
+ * Represents a single turn in an enhanced conversation history,
+ * including tool executions and evaluations for richer context.
+ */
+export interface EnhancedConversationTurn {
+    /** The role of the speaker, either 'user' or 'assistant'. */
+    role: "user" | "assistant";
+    /** The content of the message. */
+    content: string;
+    /** The timestamp of the message. */
+    timestamp: string;
+    /** Any tools that were executed as part of this turn. */
+    toolExecutions?: ToolExecution[];
+    /** The evaluation result for this turn, if applicable. */
+    evaluation?: EvaluationResult;
+}
+/**
+ * Contains all the rich context needed for a thorough, RAGAS-style evaluation.
+ * This object is constructed by the `ContextBuilder` and used by the `RAGASEvaluator`.
+ */
+export interface EnhancedEvaluationContext {
+    /** The original user query. */
+    userQuery: string;
+    /** An analysis of the user's query intent. */
+    queryAnalysis: QueryIntentAnalysis;
+    /** The AI's response that is being evaluated. */
+    aiResponse: string;
+    /** The AI provider that generated the response. */
+    provider: string;
+    /** The specific model that generated the response. */
+    model: string;
+    /** The parameters used for the generation call. */
+    generationParams: {
+        temperature?: number;
+        maxTokens?: number;
+        systemPrompt?: string;
+    };
+    /** A list of tools that were executed. */
+    toolExecutions: ToolExecution[];
+    /** The history of the conversation leading up to this turn. */
+    conversationHistory: EnhancedConversationTurn[];
+    /** The response time of the AI in milliseconds. */
+    responseTime: number;
+    /** The token usage for the generation. */
+    tokenUsage: TokenUsage;
+    /** The results of any previous evaluation attempts for this response. */
+    previousEvaluations?: EvaluationResult[];
+    /** The current attempt number for this evaluation (1-based). */
+    attemptNumber: number;
+}
+/**
+ * Represents the result of a single evaluation attempt, based on RAGAS principles.
+ */
+export interface EvaluationResult {
+    /** The final, overall score for the response, typically from 1 to 10. */
+    finalScore: number;
+    /** How well the response addresses the user's query. */
+    relevanceScore: number;
+    /** The factual accuracy of the information in the response. */
+    accuracyScore: number;
+    /** How completely the response answers the user's query. */
+    completenessScore: number;
+    /** Whether the final score meets the passing threshold. */
+    isPassing: boolean;
+    /** Constructive response from the judge LLM on how to improve the response. */
+    reasoning: string;
+    /** Specific suggestions for improving the response. */
+    suggestedImprovements: string;
+    /** The raw, unparsed response from the judge LLM. */
+    rawEvaluationResponse: string;
+    /** The model used to perform the evaluation. */
+    evaluationModel: string;
+    /** The time taken for the evaluation in milliseconds. */
+    evaluationTime: number;
+    /** The attempt number for this evaluation. */
+    attemptNumber: number;
+}
+/**
+ * Provides detailed information when a response fails quality assurance checks.
+ */
+export interface QualityErrorDetails {
+    /** The history of all evaluation attempts for this response. */
+    evaluationHistory: EvaluationResult[];
+    /** The final score of the last attempt. */
+    finalScore: number;
+    /** The total number of evaluation attempts made. */
+    attempts: number;
+    /** A summary message of the failure. */
+    message: string;
+}
+/**
+ * Configuration for the main `Evaluator` class.
+ */
+export interface EvaluationConfig {
+    /** The minimum score (1-10) for a response to be considered passing. */
+    threshold?: number;
+    /** The evaluation strategy to use. Currently only 'ragas' is supported. */
+    evaluationStrategy?: "ragas" | "custom";
+    /** The model to use for the LLM-as-judge evaluation. */
+    evaluationModel?: string;
+    /** The maximum number of evaluation attempts before failing. */
+    maxAttempts?: number;
+    /** The provider to use for the evaluation model. */
+    provider?: string;
+    /** A custom evaluator function to override the default behavior. */
+    customEvaluator?: (options: LanguageModelV1CallOptions, result: GenerateResult) => Promise<{
+        evaluationResult: EvaluationResult;
+        evalContext: EnhancedEvaluationContext;
+    }>;
+    /** The score below which a response is considered off-topic. */
+    offTopicThreshold?: number;
+    /** The score below which a failing response is considered a high severity alert. */
+    highSeverityThreshold?: number;
+    /** An optional function to generate custom evaluation prompts. */
+    promptGenerator?: GetPromptFunction;
+}
+/**
+ * A function that generates the main body of an evaluation prompt.
+ */
+export type GetPromptFunction = (context: {
+    userQuery: string;
+    history: string;
+    tools: string;
+    retryInfo: string;
+    aiResponse: string;
+}) => string;

package/dist/lib/types/evaluationTypes.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,5 +1,7 @@
 import type { LanguageModelV1Middleware } from "ai";
 import type { JsonValue } from "../types/common.js";
+import type { EvaluationData } from "./evaluation.js";
+import type { GetPromptFunction } from "./evaluationTypes.js";
 /**
  * Metadata interface for NeuroLink middleware
  * Provides additional information about middleware without affecting execution
@@ -33,7 +35,7 @@ export interface MiddlewareConfig {
     /** Whether the middleware is enabled */
     enabled?: boolean;
     /** Middleware-specific configuration */
-    config?: Record<string, JsonValue>;
+    config?: Record<string, unknown>;
     /** Conditions under which to apply this middleware */
     conditions?: MiddlewareConditions;
 }
@@ -108,7 +110,7 @@ export interface MiddlewareChainStats {
 /**
  * Built-in middleware types
  */
-export type BuiltInMiddlewareType = "analytics" | "guardrails" | "logging" | "caching" | "rateLimit" | "retry" | "timeout";
+export type BuiltInMiddlewareType = "analytics" | "guardrails" | "logging" | "caching" | "rateLimit" | "retry" | "timeout" | "autoEvaluation";
 /**
  * Middleware preset configurations
  */
@@ -144,3 +146,27 @@ export interface MiddlewareFactoryOptions {
         collectStats?: boolean;
     };
 }
+/**
+ * Configuration for the Auto-Evaluation Middleware.
+ */
+export interface AutoEvaluationConfig {
+    /** The minimum score (1-10) for a response to be considered passing. */
+    threshold?: number;
+    /** The maximum number of retry attempts before failing. */
+    maxRetries?: number;
+    /** The model to use for the LLM-as-judge evaluation. */
+    evaluationModel?: string;
+    /**
+     * If true, the middleware will wait for the evaluation to complete before returning.
+     * If the evaluation fails, it will throw an error. Defaults to true.
+     */
+    blocking?: boolean;
+    /** A callback function to be invoked with the evaluation result. */
+    onEvaluationComplete?: (evaluation: EvaluationData) => void | Promise<void>;
+    /** The score below which a response is considered off-topic. */
+    offTopicThreshold?: number;
+    /** The score below which a failing response is considered a high severity alert. */
+    highSeverityThreshold?: number;
+    promptGenerator?: GetPromptFunction;
+    provider?: string;
+}

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

@@ -81,4 +81,48 @@ export declare const imageUtils: {
      * Convert file size to human readable format
      */
     formatFileSize: (bytes: number) => string;
+    /**
+     * Convert Buffer to base64 string
+     */
+    bufferToBase64: (buffer: Buffer) => string;
+    /**
+     * Convert base64 string to Buffer
+     */
+    base64ToBuffer: (base64: string) => Buffer;
+    /**
+     * Convert file path to base64 data URI
+     */
+    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;
+    }) => Promise<string>;
+    /**
+     * Extract base64 data from data URI
+     */
+    extractBase64FromDataUri: (dataUri: string) => string;
+    /**
+     * Extract MIME type from data URI
+     */
+    extractMimeTypeFromDataUri: (dataUri: string) => string;
+    /**
+     * Create data URI from base64 and MIME type
+     */
+    createDataUri: (base64: string, mimeType?: string) => string;
+    /**
+     * Validate base64 string format
+     */
+    isValidBase64: (str: string) => boolean;
+    /**
+     * Get base64 string size in bytes
+     */
+    getBase64Size: (base64: string) => number;
+    /**
+     * Compress base64 image by reducing quality (basic implementation)
+     * Note: This is a placeholder - for production use, consider using sharp or similar
+     */
+    compressBase64: (base64: string, _quality?: number) => string;
 };

package/dist/lib/utils/imageProcessor.js

@@ -151,6 +151,8 @@ export class ImageProcessor {
                     bmp: "image/bmp",
                     tiff: "image/tiff",
                     tif: "image/tiff",
+                    svg: "image/svg+xml",
+                    avif: "image/avif",
                 };
                 return imageTypes[extension || ""] || "image/jpeg";
             }
@@ -183,6 +185,21 @@ export class ImageProcessor {
                         return "image/webp";
                     }
                 }
+                // SVG: check for "<svg" or "<?xml" at start (text-based)
+                if (input.length >= 4) {
+                    const start = input.subarray(0, 4).toString();
+                    if (start === "<svg" || start === "<?xm") {
+                        return "image/svg+xml";
+                    }
+                }
+                // AVIF: check for "ftypavif" signature at bytes 4-11
+                if (input.length >= 12) {
+                    const ftyp = input.subarray(4, 8).toString();
+                    const brand = input.subarray(8, 12).toString();
+                    if (ftyp === "ftyp" && brand === "avif") {
+                        return "image/avif";
+                    }
+                }
             }
             return "image/jpeg"; // Default fallback
         }
@@ -217,6 +234,8 @@ export class ImageProcessor {
             "image/webp",
             "image/bmp",
             "image/tiff",
+            "image/svg+xml",
+            "image/avif",
         ];
         return supportedFormats.includes(mediaType.toLowerCase());
     }
@@ -332,14 +351,7 @@ export const imageUtils = {
     /**
      * Check if a string is base64 encoded
      */
-    isBase64: (str) => {
-        try {
-            return btoa(atob(str)) === str;
-        }
-        catch {
-            return false;
-        }
-    },
+    isBase64: (str) => imageUtils.isValidBase64(str),
     /**
      * Extract file extension from filename or URL
      */
@@ -359,4 +371,143 @@ export const imageUtils = {
         const i = Math.floor(Math.log(bytes) / Math.log(k));
         return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
     },
+    /**
+     * Convert Buffer to base64 string
+     */
+    bufferToBase64: (buffer) => {
+        return buffer.toString("base64");
+    },
+    /**
+     * Convert base64 string to Buffer
+     */
+    base64ToBuffer: (base64) => {
+        // Remove data URI prefix if present
+        const cleanBase64 = base64.includes(",") ? base64.split(",")[1] : base64;
+        return Buffer.from(cleanBase64, "base64");
+    },
+    /**
+     * Convert file path to base64 data URI
+     */
+    fileToBase64DataUri: async (filePath, maxBytes = 10 * 1024 * 1024) => {
+        try {
+            const fs = await import("fs/promises");
+            // File existence and type validation
+            const stat = await fs.stat(filePath);
+            if (!stat.isFile()) {
+                throw new Error("Not a file");
+            }
+            // Size check before reading - prevent memory exhaustion
+            if (stat.size > maxBytes) {
+                throw new Error(`File too large: ${stat.size} bytes (max: ${maxBytes} bytes)`);
+            }
+            const buffer = await fs.readFile(filePath);
+            // Enhanced MIME detection: try buffer content first, fallback to filename
+            const mimeType = ImageProcessor.detectImageType(buffer) ||
+                ImageProcessor.detectImageType(filePath);
+            const base64 = buffer.toString("base64");
+            return `data:${mimeType};base64,${base64}`;
+        }
+        catch (error) {
+            throw new Error(`Failed to convert file to base64: ${error instanceof Error ? error.message : "Unknown error"}`);
+        }
+    },
+    /**
+     * Convert URL to base64 data URI by downloading the image
+     */
+    urlToBase64DataUri: async (url, { timeoutMs = 15000, maxBytes = 10 * 1024 * 1024 } = {}) => {
+        try {
+            // Basic protocol whitelist
+            if (!/^https?:\/\//i.test(url)) {
+                throw new Error("Unsupported protocol");
+            }
+            const controller = new AbortController();
+            const t = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const response = await fetch(url, { signal: controller.signal });
+                if (!response.ok) {
+                    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+                }
+                const contentType = response.headers.get("content-type") || "";
+                if (!/^image\//i.test(contentType)) {
+                    throw new Error(`Unsupported content-type: ${contentType || "unknown"}`);
+                }
+                const len = Number(response.headers.get("content-length") || 0);
+                if (len && len > maxBytes) {
+                    throw new Error(`Content too large: ${len} bytes`);
+                }
+                const buffer = await response.arrayBuffer();
+                if (buffer.byteLength > maxBytes) {
+                    throw new Error(`Downloaded content too large: ${buffer.byteLength} bytes`);
+                }
+                const base64 = Buffer.from(buffer).toString("base64");
+                return `data:${contentType || "image/jpeg"};base64,${base64}`;
+            }
+            finally {
+                clearTimeout(t);
+            }
+        }
+        catch (error) {
+            throw new Error(`Failed to download and convert URL to base64: ${error instanceof Error ? error.message : "Unknown error"}`);
+        }
+    },
+    /**
+     * Extract base64 data from data URI
+     */
+    extractBase64FromDataUri: (dataUri) => {
+        if (!dataUri.includes(",")) {
+            return dataUri; // Already just base64
+        }
+        return dataUri.split(",")[1];
+    },
+    /**
+     * Extract MIME type from data URI
+     */
+    extractMimeTypeFromDataUri: (dataUri) => {
+        const match = dataUri.match(/^data:([^;]+);base64,/);
+        return match ? match[1] : "image/jpeg";
+    },
+    /**
+     * Create data URI from base64 and MIME type
+     */
+    createDataUri: (base64, mimeType = "image/jpeg") => {
+        // Remove data URI prefix if already present
+        const cleanBase64 = base64.includes(",") ? base64.split(",")[1] : base64;
+        return `data:${mimeType};base64,${cleanBase64}`;
+    },
+    /**
+     * Validate base64 string format
+     */
+    isValidBase64: (str) => {
+        try {
+            // Remove data URI prefix if present
+            const cleanBase64 = str.includes(",") ? str.split(",")[1] : str;
+            // Check if it's valid base64
+            const decoded = Buffer.from(cleanBase64, "base64");
+            const reencoded = decoded.toString("base64");
+            // Remove padding for comparison (base64 can have different padding)
+            const normalizeBase64 = (b64) => b64.replace(/=+$/, "");
+            return normalizeBase64(cleanBase64) === normalizeBase64(reencoded);
+        }
+        catch {
+            return false;
+        }
+    },
+    /**
+     * Get base64 string size in bytes
+     */
+    getBase64Size: (base64) => {
+        // Remove data URI prefix if present
+        const cleanBase64 = base64.includes(",") ? base64.split(",")[1] : base64;
+        return Buffer.byteLength(cleanBase64, "base64");
+    },
+    /**
+     * Compress base64 image by reducing quality (basic implementation)
+     * Note: This is a placeholder - for production use, consider using sharp or similar
+     */
+    compressBase64: (base64, _quality = 0.8) => {
+        // This is a basic implementation that just returns the original
+        // In a real implementation, you'd use an image processing library
+        logger.warn("Base64 compression not implemented - returning original");
+        return base64;
+    },
 };

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

@@ -7,13 +7,12 @@ import type { MultimodalChatMessage } from "../types/conversation.js";
 import type { TextGenerationOptions } from "../types/index.js";
 import type { StreamOptions } from "../types/streamTypes.js";
 import type { GenerateOptions } from "../types/generateTypes.js";
+import type { CoreMessage } from "ai";
 /**
- * Core message type compatible with AI SDK
+ * Type-safe conversion from MultimodalChatMessage[] to CoreMessage[]
+ * Filters out invalid content and ensures strict CoreMessage contract compliance
  */
-type CoreMessage = {
-    role: "user" | "assistant" | "system";
-    content: string;
-};
+export declare function convertToCoreMessages(messages: MultimodalChatMessage[]): CoreMessage[];
 /**
  * Build a properly formatted message array for AI providers
  * Combines system prompt, conversation history, and current user prompt
@@ -25,4 +24,3 @@ export declare function buildMessagesArray(options: TextGenerationOptions | Stre
  * Detects when images are present and routes through provider adapter
  */
 export declare function buildMultimodalMessagesArray(options: GenerateOptions, provider: string, model: string): Promise<MultimodalChatMessage[]>;
-export {};

package/dist/lib/utils/messageBuilder.js

@@ -8,6 +8,147 @@ import { ProviderImageAdapter, MultimodalLogger, } from "../adapters/providerIma
 import { logger } from "./logger.js";
 import { request } from "undici";
 import { readFileSync, existsSync } from "fs";
+/**
+ * Type guard for validating message roles
+ */
+function isValidRole(role) {
+    return (typeof role === "string" &&
+        (role === "user" || role === "assistant" || role === "system"));
+}
+/**
+ * Type guard for validating content items
+ */
+function isValidContentItem(item) {
+    if (!item || typeof item !== "object") {
+        return false;
+    }
+    const contentItem = item;
+    if (contentItem.type === "text") {
+        return typeof contentItem.text === "string";
+    }
+    if (contentItem.type === "image") {
+        return (typeof contentItem.image === "string" &&
+            (contentItem.mimeType === undefined ||
+                typeof contentItem.mimeType === "string"));
+    }
+    return false;
+}
+/**
+ * Safely convert content item to AI SDK content format
+ */
+function convertContentItem(item) {
+    if (!isValidContentItem(item)) {
+        return null;
+    }
+    const contentItem = item;
+    if (contentItem.type === "text" && typeof contentItem.text === "string") {
+        return { type: "text", text: contentItem.text };
+    }
+    if (contentItem.type === "image" && typeof contentItem.image === "string") {
+        return {
+            type: "image",
+            image: contentItem.image,
+            ...(contentItem.mimeType && { mimeType: contentItem.mimeType }),
+        };
+    }
+    return null;
+}
+/**
+ * Type-safe conversion from MultimodalChatMessage[] to CoreMessage[]
+ * Filters out invalid content and ensures strict CoreMessage contract compliance
+ */
+export function convertToCoreMessages(messages) {
+    return messages
+        .map((msg) => {
+        // Validate role
+        if (!isValidRole(msg.role)) {
+            logger.warn("Invalid message role found, skipping", { role: msg.role });
+            return null;
+        }
+        // Handle string content
+        if (typeof msg.content === "string") {
+            // Create properly typed discriminated union messages
+            if (msg.role === "system") {
+                return {
+                    role: "system",
+                    content: msg.content,
+                };
+            }
+            else if (msg.role === "user") {
+                return {
+                    role: "user",
+                    content: msg.content,
+                };
+            }
+            else if (msg.role === "assistant") {
+                return {
+                    role: "assistant",
+                    content: msg.content,
+                };
+            }
+        }
+        // Handle array content (multimodal) - only user messages support full multimodal content
+        if (Array.isArray(msg.content)) {
+            const validContent = msg.content
+                .map(convertContentItem)
+                .filter((item) => item !== null);
+            // If no valid content items, skip the message
+            if (validContent.length === 0) {
+                logger.warn("No valid content items found in multimodal message, skipping");
+                return null;
+            }
+            if (msg.role === "user") {
+                // User messages support both text and image content
+                return {
+                    role: "user",
+                    content: validContent,
+                };
+            }
+            else if (msg.role === "assistant") {
+                // Assistant messages only support text content, filter out images
+                const textOnlyContent = validContent.filter((item) => item.type === "text");
+                if (textOnlyContent.length === 0) {
+                    // If no text content, convert to empty string
+                    return {
+                        role: "assistant",
+                        content: "",
+                    };
+                }
+                else if (textOnlyContent.length === 1) {
+                    // Single text item, use string content
+                    return {
+                        role: "assistant",
+                        content: textOnlyContent[0].text,
+                    };
+                }
+                else {
+                    // Multiple text items, concatenate them
+                    const combinedText = textOnlyContent
+                        .map((item) => item.text)
+                        .join(" ");
+                    return {
+                        role: "assistant",
+                        content: combinedText,
+                    };
+                }
+            }
+            else {
+                // System messages cannot have multimodal content, convert to text
+                const textContent = validContent.find((item) => item.type === "text")?.text || "";
+                return {
+                    role: "system",
+                    content: textContent,
+                };
+            }
+        }
+        // Invalid content type
+        logger.warn("Invalid message content type found, skipping", {
+            contentType: typeof msg.content,
+        });
+        return null;
+    })
+        .filter((msg) => msg !== null);
+}
 /**
  * Convert ChatMessage to CoreMessage for AI SDK compatibility
  */
@@ -84,7 +225,10 @@ export async function buildMultimodalMessagesArray(options, provider, model) {
     // If no images, use standard message building and convert to MultimodalChatMessage[]
     if (!hasImages) {
         const standardMessages = buildMessagesArray(options);
-        return standardMessages.map((msg) => ({ ...msg, content: msg.content }));
+        return standardMessages.map((msg) => ({
+            role: msg.role,
+            content: typeof msg.content === "string" ? msg.content : msg.content,
+        }));
     }
     // Validate provider supports vision
     if (!ProviderImageAdapter.supportsVision(provider, model)) {

package/dist/middleware/builtin/autoEvaluation.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @file Implements the Auto-Evaluation Middleware for ensuring response quality.
+ */
+import type { NeuroLinkMiddleware, AutoEvaluationConfig } from "../../types/middlewareTypes.js";
+/**
+ * Creates the Auto-Evaluation middleware, which intercepts generation requests
+ * to evaluate the quality of the response. If the response quality is below a
+ * configured threshold, it can trigger retries with feedback.
+ *
+ * @param config - Configuration for the auto-evaluation middleware.
+ * @returns A `NeuroLinkMiddleware` object.
+ */
+export declare function createAutoEvaluationMiddleware(config?: AutoEvaluationConfig): NeuroLinkMiddleware;
+export default createAutoEvaluationMiddleware;