@juspay/neurolink 9.63.1 → 9.65.0

package/dist/core/baseProvider.js

@@ -5,7 +5,10 @@ import { IMAGE_GENERATION_MODELS } from "../core/constants.js";
 import { MiddlewareFactory } from "../middleware/factory.js";
 import { ATTR, tracers } from "../telemetry/index.js";
 import { isAbortError } from "../utils/errorHandling.js";
+import { hasLifecycleErrorFired, markLifecycleErrorFired, } from "../utils/lifecycleCallbacks.js";
+import { resolveLifecycleTimeoutMs } from "../utils/lifecycleTimeout.js";
 import { logger } from "../utils/logger.js";
+import { withTimeoutFn } from "../utils/async/withTimeout.js";
 import { composeAbortSignals, createTimeoutController, TimeoutError, } from "../utils/timeout.js";
 import { shouldDisableBuiltinTools } from "../utils/toolUtils.js";
 import { getKeyCount, getKeysAsString } from "../utils/transformationUtils.js";
@@ -133,7 +136,14 @@ export class BaseProvider {
                     provider: this.providerName,
                     model: this.modelName,
                 });
-                return await this.executeFakeStreaming(options, analysisSchema);
+                // Note: executeFakeStreaming() owns its own catch that fires the
+                // consumer-supplied onError before re-throwing through
+                // handleProviderError(), so we do not need to wrap again here —
+                // doing so would route the error through handleProviderError()
+                // twice (and risk a double-fire onError without the shared
+                // lifecycle-fired WeakSet mark).
+                const fakeResult = await this.executeFakeStreaming(options, analysisSchema);
+                return this.wrapStreamWithLifecycleCallbacks(fakeResult, options);
             }
         }
         // CRITICAL: Image generation models don't support real streaming
@@ -151,8 +161,11 @@ export class BaseProvider {
                 model: this.modelName,
                 reason: "Image generation requires fake streaming to yield image output",
             });
-            // Skip real streaming, go directly to fake streaming
-            return await this.executeFakeStreaming(options, analysisSchema);
+            // Skip real streaming, go directly to fake streaming.
+            // executeFakeStreaming() owns its own catch + lifecycle fire, so
+            // wrapping again here would double-route through handleProviderError().
+            const fakeResult = await this.executeFakeStreaming(options, analysisSchema);
+            return this.wrapStreamWithLifecycleCallbacks(fakeResult, options);
         }
         // Central tool merge: Pre-merge base tools (MCP/built-in) with user-provided
         // tools (e.g. RAG tools) into options.tools. This way, every provider's
@@ -177,8 +190,14 @@ export class BaseProvider {
                 provider: this.providerName,
                 timestamp: Date.now(),
             });
-            // If real streaming succeeds, return it (with tools support via Vercel AI SDK)
-            return realStreamResult;
+            // Wire lifecycle callbacks (onChunk/onFinish/onError) on the user-
+            // facing StreamResult.stream. The AI-SDK lifecycle middleware only
+            // sees AI-SDK-internal chunks via streamText/wrapLanguageModel, so
+            // providers with custom HTTP streaming (Ollama, llama.cpp's /api,
+            // anything that doesn't go through streamText) bypass it. Wrapping
+            // here makes the callbacks fire for every provider, regardless of
+            // streaming implementation.
+            return this.wrapStreamWithLifecycleCallbacks(realStreamResult, options);
         }
         catch (realStreamError) {
             // Don't retry on terminal/abort errors — only fall back for
@@ -195,23 +214,178 @@ export class BaseProvider {
                 errMsg.includes("quota") ||
                 errMsg.includes("rate limit") ||
                 errMsg.includes("authentication")) {
+                await this.fireLifecycleErrorCallback(options, realStreamError);
                 throw this.handleProviderError(realStreamError);
             }
             logger.warn(`Real streaming failed for ${this.providerName}, falling back to fake streaming:`, {
                 error: errMsg,
                 timestamp: Date.now(),
             });
-            // Fallback to fake streaming only if real streaming fails AND tools are enabled
+            // Fallback to fake streaming only if real streaming fails AND tools
+            // are enabled. executeFakeStreaming() owns its own catch + lifecycle
+            // fire, so a fake-streaming failure here surfaces through that path
+            // without needing an outer wrap (which would double-route through
+            // handleProviderError()).
             if (!options.disableTools && this.supportsTools()) {
-                return await this.executeFakeStreaming(options, analysisSchema);
+                const fakeResult = await this.executeFakeStreaming(options, analysisSchema);
+                return this.wrapStreamWithLifecycleCallbacks(fakeResult, options);
             }
             else {
+                // If real streaming failed and no tools are enabled, fire onError
+                // before re-throwing so consumer-supplied callbacks see the failure.
+                await this.fireLifecycleErrorCallback(options, realStreamError);
                 // If real streaming failed and no tools are enabled, re-throw the original error
                 logger.error(`Real streaming failed for ${this.providerName}:`, realStreamError);
                 throw this.handleProviderError(realStreamError);
             }
         }
     }
+    /**
+     * Wrap a StreamResult with consumer-facing lifecycle callbacks.
+     *
+     * `options.onChunk`, `options.onFinish`, `options.onError` are translated
+     * by NeuroLink.applyStreamLifecycleMiddleware() into
+     * `options.middleware.middlewareConfig.lifecycle.config`. The AI SDK's
+     * lifecycle middleware only sees these via the wrapped LanguageModel —
+     * which is bypassed by providers that stream via raw HTTP fetch (Ollama
+     * over /api/chat, custom OpenAI-compatible servers, etc). Wrapping the
+     * user-facing stream here ensures the callbacks fire regardless of the
+     * underlying transport.
+     */
+    wrapStreamWithLifecycleCallbacks(result, options) {
+        const lifecycle = options
+            ?.middleware?.middlewareConfig?.lifecycle?.config;
+        if (!lifecycle?.onChunk && !lifecycle?.onFinish && !lifecycle?.onError) {
+            return result;
+        }
+        const { onChunk, onFinish, onError } = lifecycle;
+        const startTime = Date.now();
+        const originalStream = result.stream;
+        // Lifecycle callbacks are awaited with a bounded deadline so callers
+        // observe ordering guarantees (onChunk/onFinish/onError have all
+        // settled by the time `for await` returns / throws). The previous
+        // fire-and-forget pattern left async work running past stream close,
+        // creating races during cleanup. The deadline is configurable via
+        // `lifecycle.timeoutMs` (per-call) or `NEUROLINK_LIFECYCLE_TIMEOUT_MS`
+        // (env / CLI surface) — see `resolveLifecycleTimeoutMs`.
+        const timeoutMs = resolveLifecycleTimeoutMs(lifecycle);
+        const safeFire = async (fn, label) => {
+            try {
+                await withTimeoutFn(async () => {
+                    const ret = fn();
+                    if (ret && typeof ret.then === "function") {
+                        await ret;
+                    }
+                }, timeoutMs, `[lifecycle] ${label} callback exceeded ${timeoutMs}ms`);
+            }
+            catch (e) {
+                logger.warn(`[lifecycle] ${label} callback error:`, e);
+            }
+        };
+        const wrappedStream = (async function* () {
+            let accumulated = "";
+            let seq = 0;
+            try {
+                for await (const chunk of originalStream) {
+                    const textPart = chunk &&
+                        typeof chunk === "object" &&
+                        "content" in chunk &&
+                        typeof chunk.content === "string"
+                        ? chunk.content
+                        : "";
+                    // Only fire onChunk for actual text deltas. Non-text chunks
+                    // (image, tts_audio) would otherwise produce empty text-delta
+                    // events that consumers must filter out themselves.
+                    if (onChunk && textPart) {
+                        const currentSeq = seq++;
+                        await safeFire(() => onChunk({
+                            type: "text-delta",
+                            textDelta: textPart,
+                            sequenceNumber: currentSeq,
+                        }), "onChunk");
+                    }
+                    if (textPart) {
+                        accumulated += textPart;
+                    }
+                    yield chunk;
+                }
+                if (onFinish) {
+                    await safeFire(() => onFinish({
+                        text: accumulated,
+                        duration: Date.now() - startTime,
+                    }), "onFinish");
+                }
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                if (onError && !hasLifecycleErrorFired(err)) {
+                    // Mark before firing so a higher layer that also routes through
+                    // fireLifecycleErrorCallback (or its own lifecycle wrapper) with
+                    // the same error instance won't double-fire onError. Mirrors the
+                    // pattern in fireLifecycleErrorCallback below.
+                    markLifecycleErrorFired(err);
+                    await safeFire(() => onError({
+                        error: err,
+                        duration: Date.now() - startTime,
+                        recoverable: false,
+                    }), "onError");
+                }
+                throw err;
+            }
+        })();
+        return { ...result, stream: wrappedStream };
+    }
+    /**
+     * Fire the consumer-supplied onError callback before throwing. Used in
+     * error branches inside stream() that re-throw without emitting any
+     * stream chunks (which would otherwise hide the failure from a caller
+     * that supplied `onError`).
+     */
+    async fireLifecycleErrorCallback(options, error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        // The AI-SDK lifecycle middleware stamps errors it has already
+        // surfaced (Symbol.for("neurolink.onErrorFired"); see
+        // utils/lifecycleCallbacks.ts). Skip here so consumers don't receive
+        // duplicate onError events for the same failure.
+        if (hasLifecycleErrorFired(err)) {
+            return;
+        }
+        const lifecycle = options
+            ?.middleware?.middlewareConfig?.lifecycle?.config;
+        const onError = lifecycle?.onError;
+        if (!onError) {
+            return;
+        }
+        // Set the marker before invoking so a sync re-entry (or a concurrent
+        // dispatch path) can't double-fire onError for the same error object.
+        markLifecycleErrorFired(err);
+        // Fire the consumer's onError with a bounded deadline AND await its
+        // completion — callers can now `await fireLifecycleErrorCallback(...)`
+        // to guarantee the consumer's async onError settles before the
+        // surrounding stream() / executeFakeStreaming() rethrows. Deadline is
+        // configurable via `lifecycle.timeoutMs` or the
+        // `NEUROLINK_LIFECYCLE_TIMEOUT_MS` env var.
+        const timeoutMs = resolveLifecycleTimeoutMs(lifecycle);
+        try {
+            await withTimeoutFn(async () => {
+                // Capturing `onError` into a const above means TypeScript sees the
+                // narrowing past the early-return, so no non-null assertion needed
+                // here — and the callback identity is stable across the timeout
+                // boundary even if the caller mutates `lifecycle.onError` mid-call.
+                const ret = onError({
+                    error: err,
+                    duration: 0,
+                    recoverable: false,
+                });
+                if (ret && typeof ret.then === "function") {
+                    await ret;
+                }
+            }, timeoutMs, `[lifecycle] onError callback exceeded ${timeoutMs}ms`);
+        }
+        catch (e) {
+            logger.warn("[lifecycle] onError callback error:", e);
+        }
+    }
     /**
      * Execute fake streaming - extracted method for reusability
      */
@@ -347,6 +521,14 @@ export class BaseProvider {
         }
         catch (error) {
             logger.error(`Fake streaming fallback failed for ${this.providerName}:`, error);
+            // Fire the consumer-supplied onError BEFORE re-throwing through
+            // handleProviderError() so callers using onChunk/onFinish/onError
+            // get notified even when fake-streaming setup (message build, image
+            // adapter, etc.) fails synchronously. Awaited so the consumer's
+            // async onError fully settles before we rethrow. The shared
+            // lifecycle-fired WeakSet mark prevents double-fire if a wrapper
+            // layer also handles this.
+            await this.fireLifecycleErrorCallback(options, error);
             throw this.handleProviderError(error);
         }
     }
@@ -694,7 +876,15 @@ export class BaseProvider {
         }, options, startTime);
     }
     async executeStandardGenerateFlow(options, startTime, model, messages, tools) {
-        const timeoutController = createTimeoutController(options.timeout, this.providerName, "generate");
+        // Apply a defensive default timeout (3 min) when the caller didn't pass
+        // one. Without this guard, AI SDK's generateText() will wait forever on
+        // an upstream that accepts the connection but never produces a response
+        // (observed against the litellm gateway when a request triggers the
+        // team-access denial path — connection stays open, no response is sent,
+        // and the matrix test hangs the entire suite). Callers can still pass
+        // a larger value (e.g. video generation passes 10 min).
+        const effectiveTimeout = options.timeout ?? 180_000;
+        const timeoutController = createTimeoutController(effectiveTimeout, this.providerName, "generate");
         const composedSignal = composeAbortSignals(options.abortSignal, timeoutController?.controller.signal);
         const composedOptions = composedSignal
             ? { ...options, abortSignal: composedSignal }
@@ -802,6 +992,11 @@ export class BaseProvider {
             analytics: result.analytics,
             evaluation: result.evaluation,
             audio: result.audio,
+            // Forward reasoning fields populated by GenerationHandler from AI-SDK
+            // reasoning parts (DeepSeek `reasoning_content`, Anthropic thinking,
+            // Gemini thought parts, OpenAI o1).
+            reasoning: result.reasoning,
+            reasoningTokens: result.reasoningTokens,
         };
     }
     /**
@@ -828,8 +1023,9 @@ export class BaseProvider {
             textLength: text.length,
         });
         throw new Error(`Embedding generation is not supported by the ${this.providerName} provider. ` +
-            `Supported providers: openai, vertex/google, bedrock. ` +
+            `Supported providers: openai, vertex/google, bedrock, cohere, voyage, jina. ` +
             `Use an embedding model like text-embedding-3-small (OpenAI), text-embedding-004 (Vertex), ` +
+            `embed-english-v3.0 (Cohere), voyage-3 (Voyage), jina-embeddings-v3 (Jina), ` +
             `or amazon.titan-embed-text-v2:0 (Bedrock).`);
     }
     /**
@@ -849,9 +1045,10 @@ export class BaseProvider {
             count: texts.length,
         });
         throw new Error(`Batch embedding generation is not supported by the ${this.providerName} provider. ` +
-            `Supported providers: openai, googleAiStudio, vertex/google, bedrock. ` +
+            `Supported providers: openai, googleAiStudio, vertex/google, bedrock, cohere, voyage, jina. ` +
             `Use an embedding model like text-embedding-3-small (OpenAI), gemini-embedding-001 (Google AI), ` +
-            `text-embedding-004 (Vertex), or amazon.titan-embed-text-v2:0 (Bedrock).`);
+            `text-embedding-004 (Vertex), embed-english-v3.0 (Cohere), voyage-3 (Voyage), ` +
+            `jina-embeddings-v3 (Jina), or amazon.titan-embed-text-v2:0 (Bedrock).`);
     }
     /**
      * Get the default embedding model for this provider
@@ -1005,6 +1202,15 @@ export class BaseProvider {
                 : new DOMException("The operation was aborted", "AbortError");
         }
         const formatted = this.formatProviderError(error);
+        // Preserve the lifecycle-fired mark across formatting:
+        // fireLifecycleErrorCallback() marks the ORIGINAL error in the shared
+        // WeakSet, but formatProviderError() typically returns a new Error
+        // instance. Re-mark the formatted error so a higher layer (e.g.
+        // NeuroLink.stream()'s top-level catch + applyStreamLifecycleMiddleware)
+        // doesn't fire onError a second time for the same failure.
+        if (hasLifecycleErrorFired(error)) {
+            markLifecycleErrorFired(formatted);
+        }
         // P3 fix: Classify error and set error.type on the active OTel span
         try {
             const activeSpan = trace.getSpan(context.active());

package/dist/core/constants.d.ts

@@ -3,6 +3,17 @@
  * Single source of truth for all default values
  */
 export declare const IMAGE_GENERATION_MODELS: string[];
+/**
+ * Boundary-aware test for whether `modelName` represents an image-generation
+ * model.
+ *
+ * Matches when the model name **equals** an entry in
+ * {@link IMAGE_GENERATION_MODELS} or contains the entry as a prefix followed
+ * by a separator (`-`, `_`, `:`, `/`, `.`) or end-of-string. This avoids
+ * accidental matches such as a custom fine-tune named `"my-V_1"` matching
+ * `"V_1"` via plain substring inclusion.
+ */
+export declare function isImageGenerationModel(modelName: string | undefined): boolean;
 export declare const PDF_IMAGE_GENERATION_MODELS: string[];
 export declare const GLOBAL_LOCATION_MODELS: string[];
 export declare const DEFAULT_MAX_TOKENS: undefined;

package/dist/core/constants.js

@@ -3,12 +3,80 @@
  * Single source of truth for all default values
  */
 // Image Generation Model Identifiers
-// Used to detect if a model is an image generation model (not text generation)
+// Used to detect if a model is an image generation model (not text generation).
+// `isImageGenerationModel(name)` (below) does boundary-aware matching:
+// the modelName must equal an entry OR contain an entry followed by a
+// non-alphanumeric character (`-`, `_`, `:`, `/`, `.`, end-of-string).
+// This prevents short identifiers like `"V_1"` or `"gpt-image-1"` from
+// accidentally matching unrelated model names that happen to embed them.
 export const IMAGE_GENERATION_MODELS = [
+    // Gemini image models (Vertex AI, Google AI Studio)
     "gemini-3-pro-image-preview",
     "gemini-2.5-flash-image",
     "gemini-3.1-flash-image-preview",
+    // Stability AI (direct provider — image-only)
+    "stable-image-ultra",
+    "stable-image-core",
+    "sd3.5-large",
+    "sd3.5-large-turbo",
+    "sd3.5-medium",
+    // Ideogram (direct provider — image-only). API uses model-version
+    // identifiers like "V_1", "V_1_TURBO", "V_2", "V_2_TURBO", "V_2A",
+    // "V_2A_TURBO", "V_3". Keep prefixes that won't collide with generic
+    // text-model names.
+    "V_1",
+    "V_1_TURBO",
+    "V_2",
+    "V_2_TURBO",
+    "V_2A",
+    "V_2A_TURBO",
+    "V_3",
+    // Recraft (direct provider — image-only)
+    "recraftv3",
+    "recraftv2",
+    // OpenAI image models (DALL-E + GPT-Image). Substring match keeps
+    // version variants like "dall-e-3" / "dall-e-2" routed correctly.
+    "gpt-image-1",
+    "dall-e-3",
+    "dall-e-2",
+    // Replicate-hosted image models (matched on model slug prefix).
+    // Replicate model slugs are passed through as-is via the LLM
+    // provider; image-gen models trigger the image-gen path.
+    "black-forest-labs/flux",
+    "stability-ai/sdxl",
+    "stability-ai/stable-diffusion",
 ];
+/**
+ * Boundary-aware test for whether `modelName` represents an image-generation
+ * model.
+ *
+ * Matches when the model name **equals** an entry in
+ * {@link IMAGE_GENERATION_MODELS} or contains the entry as a prefix followed
+ * by a separator (`-`, `_`, `:`, `/`, `.`) or end-of-string. This avoids
+ * accidental matches such as a custom fine-tune named `"my-V_1"` matching
+ * `"V_1"` via plain substring inclusion.
+ */
+export function isImageGenerationModel(modelName) {
+    if (!modelName) {
+        return false;
+    }
+    for (const entry of IMAGE_GENERATION_MODELS) {
+        if (modelName === entry) {
+            return true;
+        }
+        const idx = modelName.indexOf(entry);
+        if (idx === -1) {
+            continue;
+        }
+        const before = idx === 0 ? "" : modelName[idx - 1];
+        const after = modelName[idx + entry.length] ?? "";
+        const isBoundary = (ch) => ch === "" || /[-_:./@]/.test(ch);
+        if (isBoundary(before) && isBoundary(after)) {
+            return true;
+        }
+    }
+    return false;
+}
 // PDF Image Generation Models
 // Models that support generating images from PDFs
 export const PDF_IMAGE_GENERATION_MODELS = [

package/dist/core/modules/MessageBuilder.js

@@ -106,6 +106,16 @@ export class MessageBuilder {
                     fileRegistry: options.fileRegistry,
                 };
                 messages = await buildMultimodalMessagesArray(multimodalOptions, this.providerName, this.modelName);
+                // Propagate any systemPrompt augmentation (e.g. inline-file
+                // handling guidance from processUnifiedFilesArray) back to the
+                // caller's options. Providers like GoogleVertex's native
+                // @google/genai stream path read `options.systemPrompt` directly
+                // — without this propagation the augmentation lives only on the
+                // local `multimodalOptions` clone and never reaches the model.
+                if (multimodalOptions.systemPrompt &&
+                    multimodalOptions.systemPrompt !== options.systemPrompt) {
+                    options.systemPrompt = multimodalOptions.systemPrompt;
+                }
             }
             else {
                 if (process.env.NEUROLINK_DEBUG === "true") {
@@ -214,6 +224,16 @@ export class MessageBuilder {
                     fileRegistry: options.fileRegistry,
                 };
                 messages = await buildMultimodalMessagesArray(multimodalOptions, this.providerName, this.modelName);
+                // Propagate any systemPrompt augmentation (e.g. inline-file
+                // handling guidance from processUnifiedFilesArray) back to the
+                // caller's options. Providers like GoogleVertex's native
+                // @google/genai stream path read `options.systemPrompt` directly
+                // — without this propagation the augmentation lives only on the
+                // local `multimodalOptions` clone and never reaches the model.
+                if (multimodalOptions.systemPrompt &&
+                    multimodalOptions.systemPrompt !== options.systemPrompt) {
+                    options.systemPrompt = multimodalOptions.systemPrompt;
+                }
             }
             else {
                 if (process.env.NEUROLINK_DEBUG === "true") {

package/dist/core/redisConversationMemoryManager.js

@@ -951,6 +951,12 @@ User message: "${userMessage}"`;
                 provider: this.config.summarizationProvider || "vertex",
                 model: this.config.summarizationModel || "gemini-2.5-flash",
                 disableTools: true, // Title generation doesn't need tools — saves ~600 tokens of tool descriptions
+                // A 20-25 letter title is well under 64 tokens; capping prevents
+                // Vertex 400 INVALID_ARGUMENT — Gemini 2.5 Flash on the native
+                // @google/genai SDK rejects requests with no maxOutputTokens cap
+                // when the prompt is short, which silently broke every
+                // `conversationMemory.enabled + context` test path.
+                maxTokens: 64,
             });
             // Clean up the generated title
             let title = result.content?.trim() || "New Conversation";

package/dist/evaluation/index.d.ts

@@ -12,6 +12,8 @@ export { BatchEvaluator } from "./BatchEvaluator.js";
 export { EvaluationAggregator } from "./EvaluationAggregator.js";
 export { EvaluatorFactory, getEvaluatorFactory } from "./EvaluatorFactory.js";
 export { EvaluatorRegistry, getEvaluatorRegistry, } from "./EvaluatorRegistry.js";
+export { RAGASEvaluator } from "./ragasEvaluator.js";
+export { RetryManager } from "./retryManager.js";
 /**
  * A centralized class for performing response evaluations. It supports different
  * evaluation strategies, with RAGAS-style model-based evaluation as the default.

package/dist/evaluation/index.js

@@ -19,6 +19,10 @@ export { BatchEvaluator } from "./BatchEvaluator.js";
 export { EvaluationAggregator } from "./EvaluationAggregator.js";
 export { EvaluatorFactory, getEvaluatorFactory } from "./EvaluatorFactory.js";
 export { EvaluatorRegistry, getEvaluatorRegistry, } from "./EvaluatorRegistry.js";
+// Re-export internal RAGAS classes so callers (and the evaluation test
+// suite) can instantiate them directly from the public surface.
+export { RAGASEvaluator } from "./ragasEvaluator.js";
+export { RetryManager } from "./retryManager.js";
 /**
  * A centralized class for performing response evaluations. It supports different
  * evaluation strategies, with RAGAS-style model-based evaluation as the default.

package/dist/factories/providerFactory.js

@@ -60,11 +60,17 @@ export class ProviderFactory {
         }
         // Map registered provider names to NeurolinkCredentials keys.
         // Most names match (openai, anthropic, vertex, bedrock, etc.)
-        // but some differ (google-ai → googleAiStudio, openai-compatible → openaiCompatible).
+        // but every kebab-case provider whose canonical credentials key is
+        // camelCase MUST be mapped here — otherwise per-call credential
+        // overrides silently get dropped (the factory looks up
+        // credentials["lm-studio"] which is undefined while the user wrote
+        // credentials.lmStudio).
         const credentialKeyMap = {
             "google-ai": "googleAiStudio",
             "openai-compatible": "openaiCompatible",
             huggingface: "huggingFace",
+            "lm-studio": "lmStudio",
+            "nvidia-nim": "nvidiaNim",
         };
         const credKey = credentialKeyMap[normalizedName] ?? normalizedName;
         // Extract provider-scoped credential slice (e.g. credentials.openai for OpenAI)