@juspay/neurolink 9.30.0 → 9.31.1

package/dist/client/memory/hippocampusInitializer.js

@@ -0,0 +1,19 @@
+import { Hippocampus, } from "@juspay/hippocampus";
+import { logger } from "../utils/logger.js";
+export function initializeHippocampus(config) {
+    try {
+        const instance = new Hippocampus(config);
+        logger.info("[memoryInitializer] Memory initialized successfully", {
+            storageType: config.storage?.type || "sqlite",
+            maxWords: config.maxWords || 50,
+            hasCustomPrompt: !!config.prompt,
+        });
+        return instance;
+    }
+    catch (error) {
+        logger.warn("[memoryInitializer] Failed to initialize memory; disabling", {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+}

package/dist/client/memory/memoryRetrievalTools.js

@@ -0,0 +1,166 @@
+/**
+ * Memory retrieval tools for LLM access to conversation history.
+ * Enables the AI to retrieve full tool outputs, review previous messages,
+ * and search conversation memory.
+ *
+ * Follows the createFileTools() factory pattern from files/fileTools.ts.
+ * @module
+ */
+import { tool } from "ai";
+import { z } from "zod";
+import { logger } from "../utils/logger.js";
+import { SpanSerializer, SpanType, SpanStatus, } from "../observability/index.js";
+import { getMetricsAggregator } from "../observability/index.js";
+/** Maximum characters returned per retrieval request */
+const DEFAULT_RETRIEVAL_LIMIT = 50_000;
+/** Hard maximum for user/LLM-supplied limit to prevent massive tool outputs */
+const MAX_RETRIEVAL_LIMIT = 200_000;
+/** Maximum number of search matches returned */
+const MAX_SEARCH_MATCHES = 50;
+/**
+ * Factory function that creates memory retrieval tools bound to a memory manager.
+ * @param memoryManager - The Redis conversation memory manager instance
+ * @returns Record of tool name to Vercel AI SDK tool definition
+ */
+export function createMemoryRetrievalTools(memoryManager) {
+    return {
+        retrieve_context: tool({
+            description: "Retrieve messages from conversation memory. Use this to access full tool " +
+                "outputs when a result was truncated, review previous assistant responses, " +
+                "or search through conversation history. Supports filtering by role, " +
+                "pagination for large content, and regex search within messages.",
+            inputSchema: z.object({
+                sessionId: z.string().describe("Session ID for the conversation"),
+                messageId: z
+                    .string()
+                    .optional()
+                    .describe("Specific message ID to retrieve"),
+                role: z
+                    .enum(["user", "assistant", "system", "tool_call", "tool_result"])
+                    .optional()
+                    .describe("Filter messages by role"),
+                lastN: z
+                    .number()
+                    .int()
+                    .positive()
+                    .optional()
+                    .describe("Retrieve the last N messages matching the filter"),
+                offset: z
+                    .number()
+                    .int()
+                    .nonnegative()
+                    .optional()
+                    .describe("Character offset for paginated reading of large content (default: 0)"),
+                limit: z
+                    .number()
+                    .int()
+                    .positive()
+                    .optional()
+                    .describe("Max characters to return per message (default: 50000)"),
+                search: z
+                    .string()
+                    .optional()
+                    .describe("Regex pattern to search within message content. " +
+                    "Returns matching lines with line numbers."),
+            }),
+            execute: async (args) => {
+                const span = SpanSerializer.createSpan(SpanType.MEMORY, "memory.retrieve", {
+                    "memory.operation": "retrieve",
+                    "memory.store": "redis",
+                    "memory.query": args.search || args.messageId || `lastN:${args.lastN ?? "all"}`,
+                });
+                const startTime = Date.now();
+                try {
+                    const conversation = await memoryManager.getSessionRaw(args.sessionId);
+                    if (!conversation) {
+                        span.durationMs = Date.now() - startTime;
+                        const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
+                        getMetricsAggregator().recordSpan(endedSpan);
+                        return { error: "Session not found", sessionId: args.sessionId };
+                    }
+                    let messages = conversation.messages;
+                    // Filter by specific messageId
+                    if (args.messageId) {
+                        const msg = messages.find((m) => m.id === args.messageId);
+                        if (!msg) {
+                            span.durationMs = Date.now() - startTime;
+                            const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
+                            getMetricsAggregator().recordSpan(endedSpan);
+                            return { error: "Message not found", messageId: args.messageId };
+                        }
+                        messages = [msg];
+                    }
+                    // Filter by role
+                    if (args.role) {
+                        messages = messages.filter((m) => m.role === args.role);
+                    }
+                    // Take last N
+                    if (args.lastN) {
+                        messages = messages.slice(-args.lastN);
+                    }
+                    const charLimit = Math.min(args.limit ?? DEFAULT_RETRIEVAL_LIMIT, MAX_RETRIEVAL_LIMIT);
+                    const results = messages.map((msg) => {
+                        const content = msg.content ?? "";
+                        // Search mode: return matching lines with line numbers
+                        if (args.search) {
+                            try {
+                                const pattern = args.search;
+                                // Validate regex length to mitigate ReDoS from LLM-provided input
+                                if (pattern.length > 200) {
+                                    return {
+                                        id: msg.id,
+                                        error: "Search pattern too long (max 200 chars)",
+                                    };
+                                }
+                                const regex = new RegExp(pattern, "i"); // no 'g' flag — avoids stateful .test() bug
+                                const lines = content.split("\n");
+                                const matches = lines
+                                    .map((line, i) => ({ line: i + 1, text: line }))
+                                    .filter((l) => regex.test(l.text))
+                                    .slice(0, MAX_SEARCH_MATCHES);
+                                return {
+                                    id: msg.id,
+                                    role: msg.role,
+                                    tool: msg.tool,
+                                    matchCount: matches.length,
+                                    matches,
+                                    totalSize: content.length,
+                                };
+                            }
+                            catch {
+                                return { id: msg.id, error: "Invalid regex pattern" };
+                            }
+                        }
+                        // Paginated read mode
+                        const start = args.offset ?? 0;
+                        const end = start + charLimit;
+                        const slice = content.slice(start, end);
+                        return {
+                            id: msg.id,
+                            role: msg.role,
+                            tool: msg.tool,
+                            content: slice,
+                            totalSize: content.length,
+                            hasMore: end < content.length,
+                        };
+                    });
+                    span.durationMs = Date.now() - startTime;
+                    const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
+                    getMetricsAggregator().recordSpan(endedSpan);
+                    return { messages: results, totalMessages: results.length };
+                }
+                catch (error) {
+                    span.durationMs = Date.now() - startTime;
+                    const endedSpan = SpanSerializer.endSpan(span, SpanStatus.ERROR);
+                    endedSpan.statusMessage =
+                        error instanceof Error ? error.message : String(error);
+                    getMetricsAggregator().recordSpan(endedSpan);
+                    logger.error("[MemoryRetrievalTools] Error retrieving context", {
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    return { error: "Failed to retrieve context" };
+                }
+            },
+        }),
+    };
+}

package/dist/client/middleware/builtin/analytics.js

@@ -0,0 +1,132 @@
+import { logger } from "../../utils/logger.js";
+/**
+ * Create analytics middleware for tracking AI model usage
+ * Collects metrics on token usage, response times, and model performance
+ */
+export function createAnalyticsMiddleware() {
+    const requestMetrics = new Map();
+    const metadata = {
+        id: "analytics",
+        name: "Analytics Tracking",
+        description: "Tracks token usage, response times, and model performance metrics",
+        priority: 100, // High priority to ensure analytics are captured
+        defaultEnabled: true,
+    };
+    const middleware = {
+        specificationVersion: "v3",
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        wrapGenerate: async ({ doGenerate, params }) => {
+            const requestId = `analytics-${Date.now()}`;
+            const startTime = Date.now();
+            logger.debug(`[AnalyticsMiddleware] Starting request tracking`, {
+                requestId,
+                hasPrompt: !!params.prompt,
+            });
+            try {
+                // Execute the generation
+                const result = await doGenerate();
+                // Calculate metrics
+                const responseTime = Date.now() - startTime;
+                const analytics = {
+                    requestId,
+                    responseTime,
+                    timestamp: new Date().toISOString(),
+                    usage: {
+                        input: result.usage?.promptTokens ?? 0,
+                        output: result.usage?.completionTokens ?? 0,
+                        total: (result.usage?.promptTokens ?? 0) +
+                            (result.usage?.completionTokens ?? 0),
+                    },
+                };
+                // Store metrics for potential retrieval
+                requestMetrics.set(requestId, analytics);
+                logger.debug(`[AnalyticsMiddleware] Request completed`, analytics);
+                // Add analytics to the result
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const updatedResult = { ...result };
+                if (!updatedResult.experimental_providerMetadata) {
+                    updatedResult.experimental_providerMetadata = {};
+                }
+                if (!updatedResult.experimental_providerMetadata.neurolink) {
+                    updatedResult.experimental_providerMetadata.neurolink = {};
+                }
+                updatedResult.experimental_providerMetadata.neurolink.analytics =
+                    analytics;
+                return updatedResult;
+            }
+            catch (error) {
+                const responseTime = Date.now() - startTime;
+                logger.error(`[AnalyticsMiddleware] Request failed`, {
+                    requestId,
+                    responseTime,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                throw error;
+            }
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        wrapStream: async ({ doStream, params }) => {
+            const requestId = `analytics-stream-${Date.now()}`;
+            const startTime = Date.now();
+            logger.debug(`[AnalyticsMiddleware] Starting stream tracking`, {
+                requestId,
+                hasPrompt: !!params.prompt,
+            });
+            try {
+                const result = await doStream();
+                const streamAnalytics = {
+                    requestId,
+                    startTime,
+                    timestamp: new Date().toISOString(),
+                    streamingMode: true,
+                };
+                requestMetrics.set(requestId, streamAnalytics);
+                // Ensure the result includes all required properties
+                const updatedResult = {
+                    ...result,
+                    stream: result.stream || new ReadableStream(),
+                    rawCall: result.rawCall || { rawPrompt: null, rawSettings: {} },
+                    rawResponse: {
+                        ...(result.rawResponse || {}),
+                        neurolink: {
+                            ...(result.rawResponse?.neurolink ?? {}),
+                            analytics: streamAnalytics,
+                        },
+                    },
+                };
+                return updatedResult;
+            }
+            catch (error) {
+                const responseTime = Date.now() - startTime;
+                logger.error(`[AnalyticsMiddleware] Stream failed`, {
+                    requestId,
+                    responseTime,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                throw error;
+            }
+        },
+    };
+    // Return the NeuroLinkMiddleware with metadata
+    return {
+        ...middleware,
+        metadata,
+    };
+}
+/**
+ * Get collected metrics from analytics middleware
+ * Note: This is a utility function for accessing metrics
+ */
+export function getAnalyticsMetrics() {
+    // This would need to be implemented with a global registry
+    // For now, return empty map
+    return new Map();
+}
+/**
+ * Clear collected metrics from analytics middleware
+ * Note: This is a utility function for clearing metrics
+ */
+export function clearAnalyticsMetrics() {
+    // This would need to be implemented with a global registry
+    // For now, do nothing
+}

package/dist/client/middleware/builtin/autoEvaluation.js

@@ -0,0 +1,203 @@
+/**
+ * @file Implements the Auto-Evaluation Middleware for ensuring response quality.
+ */
+import { Evaluator } from "../../evaluation/index.js";
+import { logger } from "../../utils/logger.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 function createAutoEvaluationMiddleware(config = {}) {
+    const metadata = {
+        id: "autoEvaluation",
+        name: "Auto Evaluation",
+        description: "Automatically evaluates response quality and retries if needed.",
+        priority: 90,
+        defaultEnabled: false, // Should be explicitly enabled
+    };
+    logger.debug("Auto-Evaluation Middleware Config:", config);
+    const middleware = {
+        specificationVersion: "v3",
+        wrapGenerate: async ({ doGenerate, params }) => {
+            const options = params;
+            const rawResult = await doGenerate();
+            const rawReasoning = rawResult.reasoning;
+            const textParts = rawResult.content
+                .filter((c) => c.type === "text")
+                .map((c) => c.text);
+            const toolCallParts = rawResult.content.filter((c) => c.type === "tool-call");
+            const inputTokens = rawResult.usage.inputTokens.total ?? 0;
+            const outputTokens = rawResult.usage.outputTokens.total ?? 0;
+            const result = {
+                content: textParts.join(""),
+                finishReason: rawResult.finishReason.unified,
+                reasoning: typeof rawReasoning === "string"
+                    ? rawReasoning
+                    : Array.isArray(rawReasoning)
+                        ? rawReasoning
+                            .map((r) => typeof r === "string"
+                            ? r
+                            : (r?.text ?? JSON.stringify(r)))
+                            .join("\n")
+                        : undefined,
+                usage: {
+                    input: inputTokens,
+                    output: outputTokens,
+                    total: inputTokens + outputTokens,
+                },
+                toolCalls: toolCallParts.length > 0
+                    ? toolCallParts.map((tc) => {
+                        let parsedArgs;
+                        try {
+                            parsedArgs = JSON.parse(tc.input);
+                        }
+                        catch (e) {
+                            logger.warn(`Failed to parse tool call args for tool ${tc.toolName}:`, e);
+                            parsedArgs = { raw: tc.input };
+                        }
+                        return {
+                            toolCallId: tc.toolCallId,
+                            toolName: tc.toolName,
+                            args: parsedArgs,
+                        };
+                    })
+                    : undefined,
+            };
+            const isBlocking = config.blocking !== false;
+            if (isBlocking) {
+                const evaluationResult = await performEvaluation(config, options, result);
+                return {
+                    ...rawResult,
+                    evaluationResult,
+                };
+            }
+            else {
+                performEvaluation(config, options, result).catch((err) => {
+                    logger.error("Non-blocking auto-evaluation error:", err);
+                });
+                return rawResult;
+            }
+        },
+        wrapStream: async ({ doStream, params }) => {
+            const options = params;
+            const rawResult = await doStream();
+            const [streamForUser, streamForEvaluation] = rawResult.stream.tee();
+            // Non-blocking evaluation for streams
+            consumeAndEvaluateStream(config, options, streamForEvaluation).catch((err) => {
+                logger.error("Non-blocking stream auto-evaluation error:", err);
+            });
+            return {
+                ...rawResult,
+                stream: streamForUser,
+            };
+        },
+    };
+    return {
+        ...middleware,
+        metadata,
+    };
+}
+/**
+ * A common function to perform the evaluation logic.
+ * @param config The middleware configuration.
+ * @param options The text generation options.
+ * @param result The generation result.
+ */
+async function performEvaluation(config, options, result) {
+    const isBlocking = config.blocking !== false;
+    const threshold = config.threshold ??
+        (Number(process.env.NEUROLINK_EVALUATION_THRESHOLD) || 7);
+    try {
+        const evaluator = new Evaluator({
+            threshold,
+            provider: config.provider,
+            promptGenerator: config.promptGenerator,
+            evaluationModel: config.evaluationModel,
+        });
+        const evaluationResult = await evaluator.evaluate(options, result, threshold, config);
+        if (config.onEvaluationComplete) {
+            await config.onEvaluationComplete(evaluationResult);
+        }
+    }
+    catch (error) {
+        logger.error("Error during auto-evaluation:", error);
+        if (isBlocking) {
+            throw error;
+        }
+    }
+}
+/**
+ * Consumes a stream to build the full response and then evaluates it.
+ * @param config The middleware configuration.
+ * @param options The generation options.
+ * @param stream The stream to consume.
+ */
+async function consumeAndEvaluateStream(config, options, stream) {
+    let fullText = "";
+    let usage;
+    const toolCalls = [];
+    const reader = stream.getReader();
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            switch (value.type) {
+                case "text-delta":
+                    fullText += value.delta;
+                    break;
+                case "tool-call":
+                    {
+                        let parsedArgs;
+                        try {
+                            parsedArgs = JSON.parse(value.input);
+                        }
+                        catch (e) {
+                            logger.warn(`Failed to parse tool call args for tool ${value.toolName}:`, e);
+                            // In case of parsing failure, we can't assign a string.
+                            // Let's use an object with the raw string to maintain type safety.
+                            parsedArgs = { raw: value.input };
+                        }
+                        toolCalls.push({
+                            toolCallId: value.toolCallId,
+                            toolName: value.toolName,
+                            args: parsedArgs,
+                        });
+                    }
+                    break;
+                case "finish":
+                    {
+                        const finishInputTokens = value.usage.inputTokens.total ?? 0;
+                        const finishOutputTokens = value.usage.outputTokens.total ?? 0;
+                        usage = {
+                            input: finishInputTokens,
+                            output: finishOutputTokens,
+                            total: finishInputTokens + finishOutputTokens,
+                        };
+                    }
+                    break;
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const result = {
+        content: fullText,
+        usage,
+        toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+    };
+    // For streams, evaluation is always non-blocking from the user's perspective.
+    if (config.blocking) {
+        logger.warn("Auto-evaluation 'blocking' mode is not supported for streaming responses. Evaluation will proceed non-blockingly.");
+    }
+    // Create a new config object to force non-blocking behavior for the evaluation function
+    const nonBlockingConfig = { ...config, blocking: false };
+    await performEvaluation(nonBlockingConfig, options, result);
+}
+export default createAutoEvaluationMiddleware;

package/dist/client/middleware/builtin/guardrails.js

@@ -0,0 +1,109 @@
+import { generateText } from "ai";
+import { createBlockedResponse, createBlockedStream, applyContentFiltering, handlePrecallGuardrails, } from "../utils/guardrailsUtils.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * Create Guardrails AI middleware for content filtering and policy enforcement
+ * @param config Configuration for the guardrails middleware
+ * @returns NeuroLink middleware instance
+ */
+export function createGuardrailsMiddleware(config = {}) {
+    const metadata = {
+        id: "guardrails",
+        name: "Guardrails AI",
+        description: "Provides comprehensive content filtering and policy enforcement using custom rules, AI models, and precall evaluation to filter inappropriate content before it reaches the LLM.",
+        priority: 90,
+        defaultEnabled: true,
+    };
+    // WeakMap to store blocking state from transformParams to wrap methods
+    const blockingState = new WeakMap();
+    const middleware = {
+        specificationVersion: "v3",
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        transformParams: async ({ params }) => {
+            if (config.precallEvaluation?.enabled) {
+                const { shouldBlock, transformedParams } = await handlePrecallGuardrails(params, config.precallEvaluation);
+                // Store the blocking state for use in wrap methods
+                blockingState.set(transformedParams, shouldBlock);
+                return transformedParams;
+            }
+            return params;
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        wrapGenerate: async ({ doGenerate, params }) => {
+            logger.debug(`[GuardrailsMiddleware] Applying to generate call.`);
+            // Check if this request should be blocked (set by transformParams)
+            if (config.precallEvaluation?.enabled && blockingState.get(params)) {
+                return createBlockedResponse();
+            }
+            let result = await doGenerate();
+            const filterResult = applyContentFiltering(result.text || "", config.badWords, "generate");
+            if (filterResult.hasChanges) {
+                result = { ...result, text: filterResult.filteredText };
+            }
+            if (config.modelFilter?.enabled && config.modelFilter.filterModel) {
+                logger.debug(`[GuardrailsMiddleware] Invoking model-based filter.`);
+                try {
+                    const filterPrompt = `Is the following text safe? Respond with only "safe" or "unsafe".\n\nText: "${result.text}"`;
+                    const { text: filterResponse } = await generateText({
+                        model: config.modelFilter.filterModel,
+                        prompt: filterPrompt,
+                    });
+                    if (filterResponse.toLowerCase().trim() === "unsafe") {
+                        logger.warn(`[GuardrailsMiddleware] Model-based filter flagged content as unsafe.`);
+                        result = { ...result, text: "<REDACTED BY AI GUARDRAIL>" };
+                    }
+                }
+                catch (error) {
+                    logger.error(`[GuardrailsMiddleware] Model-based filter failed.`, {
+                        error,
+                    });
+                }
+            }
+            return result;
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        wrapStream: async ({ doStream, params }) => {
+            logger.debug(`[GuardrailsMiddleware] Applying to stream call.`);
+            // Check if this request should be blocked (set by transformParams)
+            if (config.precallEvaluation?.enabled && blockingState.get(params)) {
+                return {
+                    stream: createBlockedStream(),
+                    rawCall: { rawPrompt: null, rawSettings: {} },
+                    warnings: [],
+                };
+            }
+            const { stream, ...rest } = await doStream();
+            let hasYieldedChunks = false;
+            const transformStream = new TransformStream({
+                transform(chunk, controller) {
+                    hasYieldedChunks = true;
+                    let filteredChunk = chunk;
+                    if (typeof filteredChunk === "object" &&
+                        "textDelta" in filteredChunk) {
+                        const filterResult = applyContentFiltering(filteredChunk.textDelta, config.badWords, "stream");
+                        if (filterResult.hasChanges) {
+                            filteredChunk = {
+                                ...filteredChunk,
+                                textDelta: filterResult.filteredText,
+                            };
+                        }
+                    }
+                    controller.enqueue(filteredChunk);
+                },
+                flush() {
+                    if (!hasYieldedChunks) {
+                        logger.warn(`[GuardrailsMiddleware] Stream ended without yielding any chunks`);
+                    }
+                },
+            });
+            return {
+                stream: stream.pipeThrough(transformStream),
+                ...rest,
+            };
+        },
+    };
+    return {
+        ...middleware,
+        metadata,
+    };
+}