@juspay/neurolink 10.3.1 → 10.4.1

package/dist/lib/knowledge/normalize.js

@@ -0,0 +1,75 @@
+/**
+ * Deterministic text normalization for knowledge grounding.
+ *
+ * The SAME normalizer runs at index-build time and query time so that a
+ * configuration key, a technical identifier, and a user's phrasing all
+ * collapse to the same comparable token stream:
+ *
+ *   "Multi-Step Flow"        -> "multi step flow"
+ *   "enableMultiStepFlow"    -> "enable multi step flow"
+ *   "ACCOUNT_STATUS"         -> "account status"
+ *   "  Access   Policy  "    -> "access policy"
+ *
+ * The pipeline is intentionally conservative: it splits identifiers and
+ * separators and folds case/diacritics, but it NEVER invents synonyms.
+ * Reviewed acronym and spelling expansions belong in an entry's `aliases`,
+ * not in this function.
+ */
+/**
+ * Insert spaces at camelCase / PascalCase / acronym boundaries. Must run
+ * BEFORE lowercasing because it relies on case information.
+ *
+ *   "enableURLReading"            -> "enable URL Reading"
+ *   "customAccessOptionsV2"       -> "custom Access Options V2"
+ */
+const splitIdentifierBoundaries = (input) => input
+    // lower/number followed by an uppercase: "enableTwo" -> "enable Two"
+    .replace(/([\p{Ll}\p{N}])(\p{Lu})/gu, "$1 $2")
+    // acronym run followed by a Word: "URLReading" -> "URL Reading"
+    .replace(/(\p{Lu}+)(\p{Lu}\p{Ll})/gu, "$1 $2");
+/**
+ * Normalize an arbitrary string into a single space-delimited lowercase
+ * phrase. Idempotent: `normalizeText(normalizeText(x)) === normalizeText(x)`.
+ */
+export const normalizeText = (input) => {
+    if (!input) {
+        return "";
+    }
+    const boundaries = splitIdentifierBoundaries(
+    // NFKC folds compatibility forms; NFD + mark-strip removes diacritics.
+    input
+        .normalize("NFKC")
+        .normalize("NFD")
+        .replace(/\p{M}+/gu, ""));
+    return (boundaries
+        // any run of non-letter/non-number (snake_case, kebab-case, dots, slashes,
+        // punctuation, and existing whitespace) collapses to a single space.
+        .replace(/[^\p{L}\p{N}]+/gu, " ")
+        .trim()
+        .toLowerCase());
+};
+/**
+ * Normalize then split into tokens. Empty input yields an empty array.
+ * Numbers and alphanumeric identifiers are preserved as their own tokens.
+ */
+export const tokenize = (input) => {
+    const normalized = normalizeText(input);
+    return normalized ? normalized.split(" ") : [];
+};
+/**
+ * Normalize each candidate phrase and drop blanks/duplicates while preserving
+ * first-seen order. Used to build the exact-key and alias key sets.
+ */
+export const normalizePhrases = (phrases) => {
+    const seen = new Set();
+    const out = [];
+    for (const phrase of phrases) {
+        const normalized = normalizeText(phrase);
+        if (normalized && !seen.has(normalized)) {
+            seen.add(normalized);
+            out.push(normalized);
+        }
+    }
+    return out;
+};
+//# sourceMappingURL=normalize.js.map

package/dist/lib/knowledge/resolve.d.ts

@@ -0,0 +1,18 @@
+import type { KnowledgeEntryInput, KnowledgeManifest, KnowledgeNormalizeOptions, KnowledgeNormalizeResult, KnowledgeSource, NormalizedKnowledgeEntry } from "../types/index.js";
+/**
+ * Resolve one authored entry into a complete `NormalizedKnowledgeEntry`,
+ * materializing every omitted optional (optional arrays to `[]`, `body` to "",
+ * `kind` to "text", `status` to "active") so downstream code never re-checks
+ * it. Authored arrays are cloned so the normalized snapshot is isolated from
+ * caller-owned references.
+ */
+export declare const resolveEntry: (input: KnowledgeEntryInput, version: string) => NormalizedKnowledgeEntry;
+/** Expand a build manifest into sources — one per catalog. */
+export declare const manifestToSources: (manifest: KnowledgeManifest) => KnowledgeSource[];
+/**
+ * Resolve and validate every source into normalized entries. `validation.ok`
+ * is false when any error-level issue was found; the caller (index builder)
+ * must not swap in an index built from an invalid set. Async so the public
+ * contract is stable if a future source kind needs asynchronous loading.
+ */
+export declare const normalizeAndValidate: (sources: KnowledgeSource[], options: KnowledgeNormalizeOptions) => Promise<KnowledgeNormalizeResult>;

package/dist/lib/knowledge/resolve.js

@@ -0,0 +1,157 @@
+/**
+ * Source loading, default resolution, and generic validation.
+ *
+ * Required fields (id/title/summary/domain/integrations) come straight
+ * from the authored entry; omitted optionals fall back to SDK defaults. This
+ * covers only provider-neutral invariants (ids, required fields, enum values,
+ * relationship integrity). Host-specific rules — configuration-key coverage,
+ * taxonomy conflicts — are enforced by the host build BEFORE the manifest
+ * reaches NeuroLink. Errors block indexing; warnings are surfaced but do not.
+ */
+import { decodeArray, decodeString } from "type-decoder/dist/index.js";
+import { normalizeText } from "./normalize.js";
+const SDK_DEFAULT_KIND = "text";
+const SDK_DEFAULT_STATUS = "active";
+const STATUSES = new Set(["draft", "active", "deprecated"]);
+const KINDS = new Set([
+    "concept",
+    "text",
+    "configuration",
+    "tool",
+    "procedure",
+    "policy",
+    "troubleshooting",
+]);
+/**
+ * Resolve one authored entry into a complete `NormalizedKnowledgeEntry`,
+ * materializing every omitted optional (optional arrays to `[]`, `body` to "",
+ * `kind` to "text", `status` to "active") so downstream code never re-checks
+ * it. Authored arrays are cloned so the normalized snapshot is isolated from
+ * caller-owned references.
+ */
+export const resolveEntry = (input, version) => ({
+    id: input.id,
+    title: input.title,
+    summary: input.summary,
+    domain: input.domain,
+    integrations: decodeArray(input.integrations, decodeString) ?? [],
+    kind: input.kind ?? SDK_DEFAULT_KIND,
+    status: input.status ?? SDK_DEFAULT_STATUS,
+    body: input.body ?? "",
+    aliases: [...(input.aliases ?? [])],
+    keywords: [...(input.keywords ?? [])],
+    relatedEntryIds: [...(input.relatedEntryIds ?? [])],
+    parentEntryId: input.parentEntryId,
+    version,
+});
+/** Expand a build manifest into sources — one per catalog. */
+export const manifestToSources = (manifest) => manifest.catalogs.map((catalog) => ({
+    id: catalog.id,
+    version: manifest.contentVersion,
+    entries: catalog.entries,
+}));
+/** Resolve a source's entries and its effective version. */
+const loadSourceEntries = (source, manifestVersion) => ({
+    id: source.id,
+    version: source.version ?? manifestVersion,
+    entries: source.entries,
+});
+const error = (code, message, extra) => ({ level: "error", code, message, ...extra });
+const warn = (code, message, extra) => ({ level: "warning", code, message, ...extra });
+/**
+ * Resolve and validate every source into normalized entries. `validation.ok`
+ * is false when any error-level issue was found; the caller (index builder)
+ * must not swap in an index built from an invalid set. Async so the public
+ * contract is stable if a future source kind needs asynchronous loading.
+ */
+export const normalizeAndValidate = async (sources, options) => {
+    const issues = [];
+    const entries = [];
+    const seenIds = new Set();
+    const aliasOwner = new Map();
+    for (const source of sources) {
+        const loaded = loadSourceEntries(source, options.manifestVersion);
+        if (!loaded.id) {
+            issues.push(error("missing-source-id", "Source has no id"));
+        }
+        for (const input of loaded.entries) {
+            if (!input.id) {
+                issues.push(error("missing-entry-id", "Entry has no id", { sourceId: loaded.id }));
+                continue;
+            }
+            if (seenIds.has(input.id)) {
+                issues.push(error("duplicate-entry-id", `Duplicate entry id "${input.id}"`, {
+                    entryId: input.id,
+                }));
+                continue;
+            }
+            seenIds.add(input.id);
+            if (!input.title || !input.title.trim()) {
+                issues.push(error("missing-title", "Entry is missing a title", {
+                    entryId: input.id,
+                }));
+            }
+            if (!input.summary || !input.summary.trim()) {
+                issues.push(error("missing-summary", "Entry is missing a summary", {
+                    entryId: input.id,
+                }));
+            }
+            if (!input.domain || !input.domain.trim()) {
+                issues.push(error("missing-domain", "Entry is missing a domain", {
+                    entryId: input.id,
+                }));
+            }
+            if (input.integrations === undefined) {
+                issues.push(error("missing-integrations", "Entry is missing integrations", {
+                    entryId: input.id,
+                }));
+            }
+            else if (decodeArray(input.integrations, decodeString) === null) {
+                issues.push(error("bad-integrations", "Entry integrations must be an array of strings", { entryId: input.id }));
+            }
+            const normalized = resolveEntry(input, loaded.version);
+            if (!KINDS.has(normalized.kind)) {
+                issues.push(error("bad-kind", `Unsupported kind "${normalized.kind}"`, {
+                    entryId: normalized.id,
+                }));
+            }
+            if (!STATUSES.has(normalized.status)) {
+                issues.push(error("bad-status", `Unsupported status "${normalized.status}"`, {
+                    entryId: normalized.id,
+                }));
+            }
+            for (const alias of normalized.aliases) {
+                const key = normalizeText(alias);
+                if (!key) {
+                    issues.push(warn("empty-alias", `Alias "${alias}" is empty after normalization`, { entryId: normalized.id }));
+                    continue;
+                }
+                const owner = aliasOwner.get(key);
+                if (owner && owner !== normalized.id) {
+                    issues.push(warn("duplicate-alias", `Alias "${alias}" also used by "${owner}"`, { entryId: normalized.id }));
+                }
+                else {
+                    aliasOwner.set(key, normalized.id);
+                }
+            }
+            entries.push(normalized);
+        }
+    }
+    // Relationship integrity — resolved after all entries are collected.
+    const idSet = new Set(entries.map((entry) => entry.id));
+    for (const entry of entries) {
+        for (const related of entry.relatedEntryIds) {
+            if (!idSet.has(related)) {
+                issues.push(warn("broken-relation", `relatedEntryId "${related}" not found`, {
+                    entryId: entry.id,
+                }));
+            }
+        }
+        if (entry.parentEntryId && !idSet.has(entry.parentEntryId)) {
+            issues.push(warn("broken-parent", `parentEntryId "${entry.parentEntryId}" not found`, { entryId: entry.id }));
+        }
+    }
+    const ok = !issues.some((issue) => issue.level === "error");
+    return { entries, validation: { ok, issues } };
+};
+//# sourceMappingURL=resolve.js.map

package/dist/lib/knowledge/retrieval.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Lexical-first retrieval pipeline.
+ *
+ * For one turn: authorize/filter BEFORE ranking, resolve exact identifiers and
+ * reviewed aliases via query n-gram lookup, add field-aware BM25 over a bounded
+ * query+history window, combine the deterministic signals, take the top
+ * candidates, expand a bounded set of directly-related entries, and classify
+ * confidence. No LLM, no embeddings, no vector store.
+ */
+import type { KnowledgeIndexSnapshot, KnowledgeResolvedRetrieval, KnowledgeRetrievalRequest, KnowledgeSelection } from "../types/index.js";
+/**
+ * Run retrieval against a ready snapshot. Returns the primary selection, a
+ * bounded relationship expansion, the scored candidate list (diagnostics), and
+ * a confidence class. Context assembly is a separate, later step.
+ */
+export declare const retrieve: (snapshot: KnowledgeIndexSnapshot, request: KnowledgeRetrievalRequest, config: KnowledgeResolvedRetrieval, blockedDomains?: string[]) => KnowledgeSelection;

package/dist/lib/knowledge/retrieval.js

@@ -0,0 +1,222 @@
+/**
+ * Lexical-first retrieval pipeline.
+ *
+ * For one turn: authorize/filter BEFORE ranking, resolve exact identifiers and
+ * reviewed aliases via query n-gram lookup, add field-aware BM25 over a bounded
+ * query+history window, combine the deterministic signals, take the top
+ * candidates, expand a bounded set of directly-related entries, and classify
+ * confidence. No LLM, no embeddings, no vector store.
+ */
+import { tokenize } from "./normalize.js";
+/** Per-turn history text cap so a long prior turn cannot dominate the query. */
+const HISTORY_TURN_CHARS = 400;
+/** All contiguous token n-grams (length 1..maxLen), de-duplicated. */
+const generateNGrams = (tokens, maxLen) => {
+    const grams = [];
+    const seen = new Set();
+    const limit = Math.min(maxLen, tokens.length);
+    for (let size = 1; size <= limit; size += 1) {
+        for (let start = 0; start + size <= tokens.length; start += 1) {
+            const gram = tokens.slice(start, start + size).join(" ");
+            if (!seen.has(gram)) {
+                seen.add(gram);
+                grams.push(gram);
+            }
+        }
+    }
+    return grams;
+};
+/** Longest indexed exact/alias phrase length, derived from the active snapshot. */
+const getMaxIndexedPhraseLen = (...indexes) => {
+    let maxLen = 0;
+    for (const index of indexes) {
+        for (const phrase of index.keys()) {
+            const length = phrase === "" ? 0 : phrase.split(" ").length;
+            maxLen = Math.max(maxLen, length);
+        }
+    }
+    return maxLen;
+};
+/** Look each n-gram up in a phrase index; returns entry id -> matched phrases. */
+const lookupPhrases = (grams, index) => {
+    const hits = new Map();
+    for (const gram of grams) {
+        const ids = index.get(gram);
+        if (!ids) {
+            continue;
+        }
+        for (const id of ids) {
+            const matched = hits.get(id) ?? [];
+            matched.push(gram);
+            hits.set(id, matched);
+        }
+    }
+    return hits;
+};
+/** Tokens fed to BM25: the current query plus a bounded recent-turn window. */
+const buildLexicalTokens = (request) => {
+    const parts = [request.query];
+    for (const turn of request.recentTurns) {
+        parts.push(turn.text.slice(0, HISTORY_TURN_CHARS));
+    }
+    return parts.flatMap((part) => tokenize(part));
+};
+/**
+ * Authorization + metadata filter. Applied BEFORE ranking so restricted or
+ * disabled-integration content never enters candidates, traces, or model context.
+ */
+const isAuthorized = (entry, request, blockedDomains) => {
+    if (entry.status !== "active") {
+        return false;
+    }
+    if (blockedDomains && blockedDomains.includes(entry.domain)) {
+        return false;
+    }
+    if (entry.integrations.length > 0) {
+        const active = new Set();
+        for (const integration of request.enabledIntegrations) {
+            active.add(integration.toLowerCase());
+        }
+        if (!entry.integrations.some((integration) => active.has(integration.toLowerCase()))) {
+            return false;
+        }
+    }
+    return true;
+};
+const compareCandidates = (left, right) => {
+    if (right.score !== left.score) {
+        return right.score - left.score;
+    }
+    if (left.id < right.id) {
+        return -1;
+    }
+    if (left.id > right.id) {
+        return 1;
+    }
+    return 0;
+};
+/**
+ * Confidence class. `high` requires an exact/alias hit at the top; otherwise a
+ * multi-field or dominant lexical top is `medium`, a single weak signal is
+ * `low`, and no candidates is `none`. Thresholds are pre-tuning heuristics.
+ */
+const classifyConfidence = (candidates) => {
+    if (candidates.length === 0) {
+        return "none";
+    }
+    const [top, second] = candidates;
+    if (top.exact || top.alias) {
+        return "high";
+    }
+    const fieldsMatched = Object.keys(top.fieldScores).length;
+    const dominant = second ? top.score >= 1.5 * second.score : false;
+    if (fieldsMatched >= 2 || dominant) {
+        return "medium";
+    }
+    return "low";
+};
+/**
+ * Run retrieval against a ready snapshot. Returns the primary selection, a
+ * bounded relationship expansion, the scored candidate list (diagnostics), and
+ * a confidence class. Context assembly is a separate, later step.
+ */
+export const retrieve = (snapshot, request, config, blockedDomains) => {
+    const queryTokens = tokenize(request.query);
+    const maxPhraseLen = getMaxIndexedPhraseLen(snapshot.exactIndex, snapshot.aliasIndex);
+    const grams = generateNGrams(queryTokens, maxPhraseLen);
+    const exactHits = lookupPhrases(grams, snapshot.exactIndex);
+    const aliasHits = lookupPhrases(grams, snapshot.aliasIndex);
+    const eligibleEntryIds = new Set();
+    for (const [id, entry] of snapshot.entriesById) {
+        if (isAuthorized(entry, request, blockedDomains)) {
+            eligibleEntryIds.add(id);
+        }
+    }
+    const lexicalTokens = buildLexicalTokens(request);
+    const lexicalMatches = snapshot.lexical.search(lexicalTokens, config.candidateLimit * 2, eligibleEntryIds);
+    const lexicalById = new Map(lexicalMatches.map((match) => [match.id, match]));
+    const candidateIds = new Set();
+    for (const id of exactHits.keys()) {
+        if (eligibleEntryIds.has(id)) {
+            candidateIds.add(id);
+        }
+    }
+    for (const id of aliasHits.keys()) {
+        if (eligibleEntryIds.has(id)) {
+            candidateIds.add(id);
+        }
+    }
+    for (const match of lexicalMatches) {
+        candidateIds.add(match.id);
+    }
+    const candidates = [];
+    for (const id of candidateIds) {
+        const entry = snapshot.entriesById.get(id);
+        if (!entry) {
+            continue;
+        }
+        const exact = exactHits.has(id);
+        const alias = aliasHits.has(id);
+        const lexicalMatch = lexicalById.get(id);
+        const lexical = lexicalMatch?.score ?? 0;
+        let score = lexical;
+        if (exact) {
+            score += config.exactBoost;
+        }
+        if (alias) {
+            score += config.aliasBoost;
+        }
+        candidates.push({
+            id,
+            score,
+            exact,
+            alias,
+            lexical,
+            fieldScores: lexicalMatch?.fieldScores ?? {},
+            matchedPhrases: [
+                ...(exactHits.get(id) ?? []),
+                ...(aliasHits.get(id) ?? []),
+            ],
+        });
+    }
+    candidates.sort(compareCandidates);
+    const trimmed = candidates.slice(0, config.candidateLimit);
+    const primary = [];
+    for (const candidate of trimmed.slice(0, config.resultLimit)) {
+        const entry = snapshot.entriesById.get(candidate.id);
+        if (entry) {
+            primary.push(entry);
+        }
+    }
+    const selectedIds = new Set(primary.map((entry) => entry.id));
+    const expanded = [];
+    for (const entry of primary) {
+        if (expanded.length >= config.relationLimit) {
+            break;
+        }
+        const relations = snapshot.relationIndex.get(entry.id) ?? [];
+        for (const relatedId of relations) {
+            if (expanded.length >= config.relationLimit) {
+                break;
+            }
+            if (selectedIds.has(relatedId)) {
+                continue;
+            }
+            const relatedEntry = snapshot.entriesById.get(relatedId);
+            if (!relatedEntry ||
+                !isAuthorized(relatedEntry, request, blockedDomains)) {
+                continue;
+            }
+            selectedIds.add(relatedId);
+            expanded.push(relatedEntry);
+        }
+    }
+    return {
+        primary,
+        expanded,
+        candidates: trimmed,
+        confidence: classifyConfidence(trimmed),
+        candidateCount: candidates.length,
+    };
+};
+//# sourceMappingURL=retrieval.js.map

package/dist/lib/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;