@juspay/neurolink 10.3.1 → 10.4.1

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

@@ -1,6 +1,7 @@
 import type { AIProviderName } from "../constants/enums.js";
 import type { EvaluationData } from "./evaluation.js";
 import type { RAGConfig } from "./rag.js";
+import type { KnowledgeGroundingMetadata, KnowledgeRequestScope } from "./knowledge.js";
 import type { SkillsCallOptions } from "./skills.js";
 import type { AnalyticsData, ToolExecutionEvent, ToolExecutionSummary } from "../types/index.js";
 import type { MiddlewareFactoryOptions, OnChunkCallback, OnErrorCallback, OnFinishCallback } from "../types/middleware.js";
@@ -169,6 +170,17 @@ export type StreamChunk = {
     audio: TTSChunk;
 };
 export type StreamOptions = {
+    /**
+     * Opt this stream call into the knowledge grounding configured on the
+     * NeuroLink instance. Defaults to `false` when omitted.
+     */
+    useKnowledgeGrounding?: boolean;
+    /**
+     * Enabled integrations used to scope knowledge retrieval for this turn.
+     * Used only when `useKnowledgeGrounding` is true and knowledge grounding is
+     * enabled on the NeuroLink instance.
+     */
+    knowledgeContext?: KnowledgeRequestScope;
     input: {
         /** Prompt text. Optional for media-only modes (avatar, music) that are driven by uploaded files rather than a prompt. */
         text?: string;
@@ -552,6 +564,8 @@ export type StreamOptions = {
  * Future-ready for multi-modal outputs while maintaining text focus
  */
 export type StreamResult = {
+    /** Knowledge-grounding diagnostics for this turn (present only when grounding ran). */
+    knowledge?: KnowledgeGroundingMetadata;
     stream: AsyncIterable<{
         content: string;
         reasoning?: string;

package/dist/neurolink.d.ts

@@ -6,7 +6,7 @@
  * Uses real MCP infrastructure for tool discovery and execution.
  */
 import type { AgentDefinition, AgentNetworkConfig, NetworkExecutionInput, NetworkExecutionOptions, NetworkExecutionResult, NetworkStreamChunk } from "./types/index.js";
-import type { CompactionConfig, CompactionResult, SpanData, ObservabilityConfig, MetricsSummary, MCPToolAnnotations, TraceView, AuthenticatedContext, AuthProvider, JsonObject, NeuroLinkEvents, TypedEventEmitter, MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig, ChatMessage, ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPToolInfo, GenerateOptions, GenerateResult, ProviderStatus, TextGenerationOptions, TextGenerationResult, MCPExecutableTool, MCPServerInfo, MCPStatus, StreamOptions, StreamResult, ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions, BatchOperationResult, StreamGenerationEndContext, ToolRoutingServerDescriptor, ToolDedupConfig, ToolConfig } from "./types/index.js";
+import type { CompactionConfig, CompactionResult, SpanData, ObservabilityConfig, MetricsSummary, MCPToolAnnotations, TraceView, AuthenticatedContext, AuthProvider, JsonObject, NeuroLinkEvents, TypedEventEmitter, MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig, ChatMessage, ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPToolInfo, GenerateOptions, GenerateResult, ProviderStatus, TextGenerationOptions, TextGenerationResult, MCPExecutableTool, MCPServerInfo, MCPStatus, StreamOptions, StreamResult, ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions, BatchOperationResult, StreamGenerationEndContext, ToolRoutingServerDescriptor, ToolDedupConfig, ToolConfig, KnowledgeEngineStatus } from "./types/index.js";
 import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import type { RedisConversationMemoryManager } from "./core/redisConversationMemoryManager.js";
 import { ExternalServerManager } from "./mcp/externalServerManager.js";
@@ -107,6 +107,7 @@ export declare class NeuroLink {
     private toolRoutingConfig?;
     private toolRoutingCacheInstance?;
     private toolRoutingVectorCache?;
+    private knowledgeGroundingEngine?;
     private toolDedupConfig?;
     private toolsConfig?;
     /** Session-scoped pins of tools discovered via search_tools (tools.discovery mode). */
@@ -629,6 +630,7 @@ export declare class NeuroLink {
      * @param optionsOrPrompt.maxTokens - Maximum tokens to generate
      * @param optionsOrPrompt.thinkingConfig - Extended thinking configuration (thinkingLevel: 'minimal'|'low'|'medium'|'high')
      * @param optionsOrPrompt.context - Context with conversationId and userId for memory
+     * @param optionsOrPrompt.useKnowledgeGrounding - Whether to use the instance's configured knowledge for this call
      * @returns Promise resolving to generation result with content and metadata
      *
      * @example Basic text generation
@@ -904,6 +906,7 @@ export declare class NeuroLink {
      * @param options.enableEvaluation - Whether to include response quality evaluation
      * @param options.context - Additional context for the request
      * @param options.evaluationDomain - Domain for specialized evaluation
+     * @param options.useKnowledgeGrounding - Whether to use the instance's configured knowledge for this call
      *
      * @returns Promise resolving to StreamResult with an async iterable stream
      *
@@ -989,6 +992,16 @@ export declare class NeuroLink {
      * alone does not activate it.
      */
     setToolRoutingServers(servers: ToolRoutingServerDescriptor[]): void;
+    /** Knowledge-grounding engine health (null when it was not configured). */
+    getKnowledgeStatus(): KnowledgeEngineStatus | null;
+    private appendKnowledgeGroundingBlockToSystemPrompt;
+    /**
+     * Retrieve knowledge grounding for a public generate/stream call without
+     * mutating its options. The outer call boundary decides how to apply the
+     * returned context. Returns undefined when the call does not opt in,
+     * grounding is disabled/not applicable, or retrieval fails open.
+     */
+    private retrieveKnowledgeGrounding;
     private validateStreamRequestOptions;
     private maybeHandleWorkflowStreamRequest;
     private runStandardStreamRequest;

package/dist/neurolink.js

@@ -32,6 +32,7 @@ import { SYSTEM_LIMITS, DEFAULT_TOOL_ROUTING_TIMEOUT_MS, MIN_RECOVERY_TURN_BUDGE
 import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import { buildToolRoutingCatalog, buildRoutingQueryFromHistory, resolveToolRoutingExclusions, } from "./core/toolRouting.js";
 import { ToolRoutingCache } from "./core/toolRoutingCache.js";
+import { DEFAULT_RECENT_TURNS, KnowledgeGroundingEngine, } from "./knowledge/index.js";
 import { AIProviderFactory } from "./core/factory.js";
 import { createToolEventPayload } from "./core/toolEvents.js";
 import { ProviderRegistry } from "./factories/providerRegistry.js";
@@ -405,6 +406,9 @@ export class NeuroLink {
     // vectors are computed once. Cleared when the catalog changes via
     // setToolRoutingServers() so stale vectors are never reused.
     toolRoutingVectorCache;
+    // Knowledge grounding: lexical-first host-supplied retrieval engine. Built
+    // once from constructor config and undefined unless grounding is enabled.
+    knowledgeGroundingEngine;
     // Opt-in tool-signature deduplication config.
     toolDedupConfig;
     toolsConfig;
@@ -837,6 +841,18 @@ export class NeuroLink {
             // multiple NeuroLink instances.
             this.toolRoutingConfig = { ...config.toolRouting };
         }
+        const knowledgeGroundingConfig = config?.knowledgeGrounding;
+        if (knowledgeGroundingConfig?.enabled) {
+            if (Array.isArray(knowledgeGroundingConfig.sources) &&
+                knowledgeGroundingConfig.sources.length > 0) {
+                // The engine builds its immutable index asynchronously; eligible
+                // generate() and stream() calls await readiness before retrieval.
+                this.knowledgeGroundingEngine = new KnowledgeGroundingEngine(knowledgeGroundingConfig);
+            }
+            else {
+                logger.warn("[KnowledgeGrounding] enabled but no sources were provided; grounding disabled for this instance");
+            }
+        }
         if (config?.toolDedup) {
             this.toolDedupConfig = { ...config.toolDedup };
         }
@@ -853,7 +869,9 @@ export class NeuroLink {
         // generate() (marked so it never recursively re-routes). Fails open.
         this.classifierRouter = config?.classifierRouter?.enabled
             ? new ClassifierRouter(config.classifierRouter, {
-                generate: (genOptions) => this.generate(genOptions),
+                generate: (genOptions) => this.generate({
+                    ...genOptions,
+                }),
                 logger: {
                     debug: (message, meta) => logger.debug(message, meta),
                     warn: (message, meta) => logger.warn(message, meta),
@@ -3045,6 +3063,7 @@ Current user's request: ${currentInput}`;
      * @param optionsOrPrompt.maxTokens - Maximum tokens to generate
      * @param optionsOrPrompt.thinkingConfig - Extended thinking configuration (thinkingLevel: 'minimal'|'low'|'medium'|'high')
      * @param optionsOrPrompt.context - Context with conversationId and userId for memory
+     * @param optionsOrPrompt.useKnowledgeGrounding - Whether to use the instance's configured knowledge for this call
      * @returns Promise resolving to generation result with content and metadata
      *
      * @example Basic text generation
@@ -3131,9 +3150,22 @@ Current user's request: ${currentInput}`;
         if (typeof optionsOrPrompt !== "string") {
             optionsOrPrompt = cloneOptionsForCallIsolation(optionsOrPrompt);
         }
+        // Retrieve once at the public call boundary so fallback attempts reuse the
+        // same grounding block and internal preparation cannot inject it twice.
+        const groundingOptions = typeof optionsOrPrompt === "string"
+            ? { input: { text: optionsOrPrompt } }
+            : optionsOrPrompt;
+        const knowledgeOutcome = await this.retrieveKnowledgeGrounding(groundingOptions);
+        if (knowledgeOutcome?.ephemeralContext) {
+            const block = knowledgeOutcome.ephemeralContext.content;
+            optionsOrPrompt = {
+                ...groundingOptions,
+                systemPrompt: this.appendKnowledgeGroundingBlockToSystemPrompt(groundingOptions.systemPrompt, block),
+            };
+        }
         const startedAt = Date.now();
         try {
-            return await this.runWithFallbackOrchestration(optionsOrPrompt, "generate", (opts) => {
+            const result = await this.runWithFallbackOrchestration(optionsOrPrompt, "generate", (opts) => {
                 // Capture root-ness before startActiveSpan makes generateSpan active.
                 // The actual guest-rescue stamp is deferred to executeGenerateRequest,
                 // AFTER prepareGenerateRequest merges auth/requestContext-derived
@@ -3142,6 +3174,10 @@ Current user's request: ${currentInput}`;
                 const generateIsRoot = !trace.getSpan(context.active());
                 return tracers.sdk.startActiveSpan("neurolink.generate", { kind: SpanKind.INTERNAL }, (generateSpan) => this.executeGenerateWithMetricsContext(opts, generateSpan, generateIsRoot));
             });
+            if (knowledgeOutcome) {
+                result.knowledge = knowledgeOutcome.metadata;
+            }
+            return result;
         }
         catch (error) {
             // Lifecycle middleware (wrapGenerate.catch in builtin/lifecycle.ts)
@@ -6204,6 +6240,7 @@ Current user's request: ${currentInput}`;
      * @param options.enableEvaluation - Whether to include response quality evaluation
      * @param options.context - Additional context for the request
      * @param options.evaluationDomain - Domain for specialized evaluation
+     * @param options.useKnowledgeGrounding - Whether to use the instance's configured knowledge for this call
      *
      * @returns Promise resolving to StreamResult with an async iterable stream
      *
@@ -6261,8 +6298,23 @@ Current user's request: ${currentInput}`;
         // top-level keys and left `options.input` shared with the caller.
         options = cloneOptionsForCallIsolation(options);
         const startedAt = Date.now();
+        // Retrieve once before provider/model fallback orchestration. Every fallback
+        // receives the same explicitly enriched options, without the retrieval helper
+        // mutating its input or injecting the same block more than once.
+        const knowledgeOutcome = await this.retrieveKnowledgeGrounding(options);
+        if (knowledgeOutcome?.ephemeralContext) {
+            const block = knowledgeOutcome.ephemeralContext.content;
+            options = {
+                ...options,
+                systemPrompt: this.appendKnowledgeGroundingBlockToSystemPrompt(options.systemPrompt, block),
+            };
+        }
         try {
-            return await this.streamWithIterationFallback(options);
+            const result = await this.streamWithIterationFallback(options);
+            if (knowledgeOutcome) {
+                result.knowledge = knowledgeOutcome.metadata;
+            }
+            return result;
         }
         catch (error) {
             // Mirror generate(): fire consumer onError for failures that
@@ -6930,6 +6982,63 @@ Current user's request: ${currentInput}`;
         // to recompute exclusions against the new server/tool set.
         this.toolRoutingCacheInstance = undefined;
     }
+    /** Knowledge-grounding engine health (null when it was not configured). */
+    getKnowledgeStatus() {
+        return this.knowledgeGroundingEngine?.getStatus() ?? null;
+    }
+    appendKnowledgeGroundingBlockToSystemPrompt(systemPrompt, block) {
+        if (typeof systemPrompt === "function") {
+            const originalSystemPrompt = systemPrompt;
+            return async (context) => {
+                const resolved = await resolveDynamicArgument(originalSystemPrompt, context);
+                return resolved.value ? `${resolved.value}\n\n${block}` : block;
+            };
+        }
+        return systemPrompt ? `${systemPrompt}\n\n${block}` : block;
+    }
+    /**
+     * Retrieve knowledge grounding for a public generate/stream call without
+     * mutating its options. The outer call boundary decides how to apply the
+     * returned context. Returns undefined when the call does not opt in,
+     * grounding is disabled/not applicable, or retrieval fails open.
+     */
+    async retrieveKnowledgeGrounding(options) {
+        const engine = this.knowledgeGroundingEngine;
+        if (!engine ||
+            !engine.isEnabled() ||
+            options.useKnowledgeGrounding !== true) {
+            return undefined;
+        }
+        const query = options.input?.text;
+        if (!query) {
+            return undefined;
+        }
+        try {
+            const conversationMessages = options.conversationMessages !== undefined
+                ? options.conversationMessages
+                : await this.fetchRecentRoutingHistory(options);
+            const recentTurns = conversationMessages
+                .filter((message) => message.role === "user" || message.role === "assistant")
+                .slice(-DEFAULT_RECENT_TURNS)
+                .map((message) => ({
+                role: message.role === "assistant"
+                    ? "assistant"
+                    : "user",
+                text: typeof message.content === "string" ? message.content : "",
+            }));
+            return await engine.ground({
+                query,
+                recentTurns,
+                scope: options.knowledgeContext,
+            });
+        }
+        catch (error) {
+            logger.warn("[KnowledgeGrounding] grounding hook failed open", {
+                error: String(error),
+            });
+            return undefined;
+        }
+    }
     async validateStreamRequestOptions(options, startTime) {
         await this.validateStreamInput(options);
         // Input validation for stream

package/dist/types/config.d.ts

@@ -13,6 +13,7 @@ import type { ModelPoolConfig } from "./modelPool.js";
 import type { RequestRouter } from "./requestRouter.js";
 import type { ClassifierRouterConfig } from "./classifierRouter.js";
 import type { SkillsConfig } from "./skills.js";
+import type { KnowledgeGroundingConfig } from "./knowledge.js";
 /**
  * Main NeuroLink configuration type
  */
@@ -130,6 +131,17 @@ export type NeurolinkConstructorConfig = {
      * Opt-in and fails open on read paths. See {@link SkillsConfig}.
      */
     skills?: SkillsConfig;
+    /**
+     * Knowledge grounding: lexical-first host-supplied knowledge retrieval. When
+     * enabled with at least one source, a deterministic in-memory retrieval runs
+     * before each generate()/stream() turn — independently of tool routing — and
+     * attaches a token-bounded, ephemeral knowledge block to the model call. No
+     * embeddings or vector store. Opt-in (`enabled: false` by default) and fails
+     * open: any retrieval failure leaves the turn ungrounded. Sources are fixed
+     * for the lifetime of the instance. See
+     * {@link KnowledgeGroundingConfig}.
+     */
+    knowledgeGrounding?: KnowledgeGroundingConfig;
 };
 /**
  * Configuration for MCP enhancement modules wired into generate()/stream() paths.

package/dist/types/conversation.d.ts

@@ -429,7 +429,7 @@ export type SessionMetadata = {
  * Report type for agentic loop reports
  * Identifies the platform or category of the report
  */
-export type AgenticLoopReportType = "META" | "GOOGLEADS" | "GOOGLEGA4" | "OTHER";
+export type AgenticLoopReportType = "META" | "GOOGLEADS" | "GOOGLEGA4" | "SHOPIFY" | "BREEZE" | "OTHER";
 /**
  * Status of an agentic loop report
  */

package/dist/types/dynamic.d.ts

@@ -7,6 +7,7 @@
  * @module types/dynamic
  */
 import type { AIProviderName } from "../constants/enums.js";
+import type { KnowledgeRequestScope } from "./knowledge.js";
 /**
  * Context passed to context-aware dynamic argument functions.
  * `requestContext` is whatever the consumer passed as `dynamicContext` —
@@ -39,6 +40,17 @@ export type DynamicArgument<T> = T | (() => T) | (() => Promise<T>) | ((context:
  * instead of static values for context-aware resolution.
  */
 export type DynamicOptions = {
+    /**
+     * Opt this call into the knowledge grounding configured on the NeuroLink
+     * instance. This flag is intentionally static because grounding runs before
+     * dynamic arguments are resolved.
+     */
+    useKnowledgeGrounding?: boolean;
+    /**
+     * Enabled integrations used to scope knowledge retrieval for this turn.
+     * This scope is intentionally static for the same reason.
+     */
+    knowledgeContext?: KnowledgeRequestScope;
     model?: DynamicArgument<string>;
     provider?: DynamicArgument<AIProviderName | string>;
     temperature?: DynamicArgument<number>;

package/dist/types/generate.d.ts

@@ -1,5 +1,6 @@
 import type { AIProviderName } from "../constants/enums.js";
 import type { RAGConfig } from "./rag.js";
+import type { KnowledgeGroundingMetadata, KnowledgeRequestScope } from "./knowledge.js";
 import type { SkillsCallOptions } from "./skills.js";
 import type { AnalyticsData, TokenUsage } from "./analytics.js";
 import type { JsonValue } from "./common.js";
@@ -545,6 +546,17 @@ export type GenerateOptions = {
     onError?: OnErrorCallback;
     /** Pre-validated user context for the request */
     requestContext?: Record<string, unknown>;
+    /**
+     * Opt this generation call into the knowledge grounding configured on the
+     * NeuroLink instance. Defaults to `false` when omitted.
+     */
+    useKnowledgeGrounding?: boolean;
+    /**
+     * Enabled integrations used to scope knowledge retrieval for this turn.
+     * Used only when `useKnowledgeGrounding` is true and knowledge grounding is
+     * enabled on the NeuroLink instance.
+     */
+    knowledgeContext?: KnowledgeRequestScope;
     /** Raw auth token — validated by configured auth provider */
     auth?: {
         token: string;
@@ -690,6 +702,8 @@ export type GenerateStopReason = "completed" | "step-cap" | "context-cap" | "tim
  */
 export type GenerateResult = {
     content: string;
+    /** Knowledge-grounding diagnostics for this turn (present only when grounding ran). */
+    knowledge?: KnowledgeGroundingMetadata;
     /**
      * Parsed structured object when a `schema` was requested. Populated from
      * AI-SDK experimental_output, or from text-mode coercion (balanced-scan +

package/dist/types/index.d.ts

@@ -28,6 +28,7 @@ export * from "./generate.js";
 export * from "./grounding.js";
 export * from "./guardrails.js";
 export * from "./hitl.js";
+export * from "./knowledge.js";
 export * from "./livekit.js";
 export * from "./mcp.js";
 export * from "./mcpOutput.js";

package/dist/types/index.js

@@ -29,6 +29,7 @@ export * from "./generate.js";
 export * from "./grounding.js";
 export * from "./guardrails.js";
 export * from "./hitl.js";
+export * from "./knowledge.js";
 export * from "./livekit.js";
 export * from "./mcp.js";
 export * from "./mcpOutput.js";