@juspay/neurolink 9.32.0 → 9.33.0

package/dist/client/memory/hippocampusInitializer.js

@@ -1,19 +0,0 @@
-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

@@ -1,166 +0,0 @@
-/**
- * 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

@@ -1,132 +0,0 @@
-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

@@ -1,203 +0,0 @@
-/**
- * @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

@@ -1,109 +0,0 @@
-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,
-    };
-}