@juspay/neurolink 9.54.5 → 9.54.7

package/dist/lib/proxy/sseInterceptor.js

@@ -69,6 +69,9 @@ function extractSSEEvents(buffer) {
     }
     return { events, remainder: buffer.slice(cursor) };
 }
+// ---------------------------------------------------------------------------
+// Telemetry accumulator
+// ---------------------------------------------------------------------------
 function createAccumulator(captureRawText) {
     return {
         messageId: "",
@@ -338,6 +341,9 @@ function processEvent(acc, event) {
             break;
     }
 }
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
 /**
  * Create an SSE interceptor that extracts telemetry from an Anthropic
  * streaming response while passing all bytes through unmodified.

package/dist/lib/proxy/updateChecker.d.ts

@@ -6,11 +6,7 @@
  * Designed to be non-blocking and failure-tolerant — any error (network,
  * timeout, parse) silently returns `updateAvailable: false`.
  */
-type UpdateCheckResult = {
-    currentVersion: string;
-    latestVersion: string;
-    updateAvailable: boolean;
-};
+import type { UpdateCheckResult } from "../types/index.js";
 /**
  * Query npm for the latest version of `@juspay/neurolink` and compare it
  * against {@link currentVersion}.
@@ -19,4 +15,3 @@ type UpdateCheckResult = {
  * `{ updateAvailable: false, latestVersion: currentVersion }`.
  */
 export declare function checkForUpdate(currentVersion: string): Promise<UpdateCheckResult>;
-export {};

package/dist/lib/proxy/updateState.d.ts

@@ -6,17 +6,7 @@
  * State file location: ~/.neurolink/update-state.json
  * Suppressed versions expire after 24 hours.
  */
-type SuppressedVersion = {
-    suppressedAt: string;
-    reason: string;
-};
-type UpdateState = {
-    lastCheckAt: string;
-    lastCheckVersion: string;
-    suppressedVersions: Record<string, SuppressedVersion>;
-    lastUpdateAt: string | null;
-    lastUpdateVersion: string | null;
-};
+import type { UpdateState } from "../types/index.js";
 /**
  * Return an empty/initial UpdateState.
  */
@@ -65,4 +55,3 @@ export declare function recordSuccessfulUpdate(version: string, stateFilePath?:
  * @param stateFilePath - Override path for testing
  */
 export declare function recordCheck(latestVersion: string, stateFilePath?: string): void;
-export {};

package/dist/lib/rag/chunkers/BaseChunker.js

@@ -6,6 +6,8 @@
  */
 import { v4 as uuidv4 } from "uuid";
 import { ChunkingError, RAGErrorCodes } from "../errors/RAGError.js";
+import { withSpan } from "../../telemetry/withSpan.js";
+import { tracers } from "../../telemetry/tracers.js";
 /**
  * Default chunker configuration
  */
@@ -64,29 +66,41 @@ export class BaseChunker {
      * Chunk content into smaller pieces
      */
     async chunk(content, config) {
-        const effectiveConfig = { ...this.config, ...config };
-        if (!content || content.trim().length === 0) {
-            throw new ChunkingError("Content is empty", {
-                code: RAGErrorCodes.CHUNKING_EMPTY_CONTENT,
-                strategy: this.strategy,
-                contentLength: 0,
-            });
-        }
-        try {
-            const chunks = await this.doChunk(content, effectiveConfig);
-            return this.filterChunks(chunks, effectiveConfig);
-        }
-        catch (error) {
-            if (error instanceof ChunkingError) {
-                throw error;
+        return withSpan({
+            name: "neurolink.rag.chunk",
+            tracer: tracers.rag,
+            attributes: {
+                "rag.chunker.strategy": this.strategy,
+                "rag.chunker.content_chars": content.length,
+                "rag.chunker.content_bytes": Buffer.byteLength(content, "utf8"),
+            },
+        }, async (span) => {
+            const effectiveConfig = { ...this.config, ...config };
+            if (!content || content.trim().length === 0) {
+                throw new ChunkingError("Content is empty", {
+                    code: RAGErrorCodes.CHUNKING_EMPTY_CONTENT,
+                    strategy: this.strategy,
+                    contentLength: 0,
+                });
             }
-            throw new ChunkingError(`Chunking failed: ${error instanceof Error ? error.message : String(error)}`, {
-                code: RAGErrorCodes.CHUNKING_ERROR,
-                cause: error instanceof Error ? error : undefined,
-                strategy: this.strategy,
-                contentLength: content.length,
-            });
-        }
+            try {
+                const chunks = await this.doChunk(content, effectiveConfig);
+                const result = this.filterChunks(chunks, effectiveConfig);
+                span.setAttribute("rag.chunker.chunk_count", result.length);
+                return result;
+            }
+            catch (error) {
+                if (error instanceof ChunkingError) {
+                    throw error;
+                }
+                throw new ChunkingError(`Chunking failed: ${error instanceof Error ? error.message : String(error)}`, {
+                    code: RAGErrorCodes.CHUNKING_ERROR,
+                    cause: error instanceof Error ? error : undefined,
+                    strategy: this.strategy,
+                    contentLength: content.length,
+                });
+            }
+        }); // end withSpan
     }
     /**
      * Filter chunks based on minimum size

package/dist/lib/rag/chunking/jsonChunker.d.ts

@@ -4,7 +4,7 @@
  * Splits JSON documents based on structure (arrays, objects, keys).
  * Best for API responses, configuration files, and structured data.
  */
-import type { Chunker, Chunk, ChunkerValidationResult, JSONChunkerConfig, BaseChunkerConfig } from "../../types/index.js";
+import type { BaseChunkerConfig, Chunk, Chunker, ChunkerValidationResult, JSONChunkerConfig } from "../../types/index.js";
 /**
  * JSON-aware chunker implementation
  * Splits based on JSON structure

package/dist/lib/rag/errors/RAGError.d.ts

@@ -6,6 +6,7 @@
  * Uses the NeuroLinkFeatureError pattern for consistency.
  */
 import { NeuroLinkFeatureError } from "../../core/infrastructure/index.js";
+import type { RAGErrorCode } from "../../types/index.js";
 /**
  * RAG error codes for all RAG-related operations
  */
@@ -43,7 +44,6 @@ export declare const RAGErrorCodes: {
     readonly RETRY_EXHAUSTED: "RAG_RETRY_EXHAUSTED";
     readonly INVALID_CONFIGURATION: "RAG_INVALID_CONFIGURATION";
 };
-type RAGErrorCode = (typeof RAGErrorCodes)[keyof typeof RAGErrorCodes];
 /**
  * RAG error factory using the infrastructure pattern
  */
@@ -242,4 +242,3 @@ export declare function isRetryableRAGError(error: unknown): boolean;
  * Type guard for partial failure errors
  */
 export declare function isPartialFailure(error: unknown): error is PipelineError;
-export {};

package/dist/lib/rag/ragIntegration.js

@@ -13,6 +13,8 @@ import { SpanSerializer, SpanType, SpanStatus, getMetricsAggregator, } from "../
 import { logger } from "../utils/logger.js";
 import { createChunker } from "./ChunkerFactory.js";
 import { createVectorQueryTool, InMemoryVectorStore, } from "./retrieval/vectorQueryTool.js";
+import { withSpan } from "../telemetry/withSpan.js";
+import { tracers } from "../telemetry/tracers.js";
 /**
  * Maps file extensions to recommended chunking strategies
  */
@@ -272,40 +274,51 @@ async function _prepareRAGToolInner(ragConfig, fallbackProvider) {
                 .describe("The search query to find relevant information"),
         }),
         execute: async ({ query }) => {
-            // For the in-memory store with simple embeddings,
-            // generate a query embedding using the same method
-            const queryEmbedding = generateSimpleEmbedding(query, EMBEDDING_DIMENSION);
-            // Fetch more candidates than needed so diversity can select across files
-            const fetchK = fileContents.length > 1 ? topK * 3 : topK;
-            const rawResults = await vectorStore.query({
-                indexName,
-                queryVector: queryEmbedding,
-                topK: fetchK,
-            });
-            // Apply source-file diversity for multi-file RAG
-            const results = fileContents.length > 1
-                ? diversifyResults(rawResults, topK)
-                : rawResults.slice(0, topK);
-            if (results.length === 0) {
+            return withSpan({
+                name: "neurolink.rag.search",
+                tracer: tracers.rag,
+                attributes: {
+                    "rag.query_length": query ? String(query).length : 0,
+                    "rag.top_k": topK ?? 5,
+                },
+            }, async (span) => {
+                // For the in-memory store with simple embeddings,
+                // generate a query embedding using the same method
+                const queryEmbedding = generateSimpleEmbedding(query, EMBEDDING_DIMENSION);
+                // Fetch more candidates than needed so diversity can select across files
+                const fetchK = fileContents.length > 1 ? topK * 3 : topK;
+                const rawResults = await vectorStore.query({
+                    indexName,
+                    queryVector: queryEmbedding,
+                    topK: fetchK,
+                });
+                // Apply source-file diversity for multi-file RAG
+                const results = fileContents.length > 1
+                    ? diversifyResults(rawResults, topK)
+                    : rawResults.slice(0, topK);
+                if (results.length === 0) {
+                    span.setAttribute("rag.results_count", 0);
+                    return {
+                        relevantContext: "No relevant documents found for the query.",
+                        sources: [],
+                        totalResults: 0,
+                    };
+                }
+                const relevantContext = results
+                    .map((r, i) => `[${i + 1}] ${r.metadata?.text || r.text || ""}`)
+                    .join("\n\n");
+                span.setAttribute("rag.results_count", results.length);
                 return {
-                    relevantContext: "No relevant documents found for the query.",
-                    sources: [],
-                    totalResults: 0,
+                    relevantContext,
+                    sources: results.map((r) => ({
+                        id: r.id,
+                        score: r.score,
+                        source: r.metadata?.source,
+                        text: (r.metadata?.text || r.text || "").slice(0, 200),
+                    })),
+                    totalResults: results.length,
                 };
-            }
-            const relevantContext = results
-                .map((r, i) => `[${i + 1}] ${r.metadata?.text || r.text || ""}`)
-                .join("\n\n");
-            return {
-                relevantContext,
-                sources: results.map((r) => ({
-                    id: r.id,
-                    score: r.score,
-                    source: r.metadata?.source,
-                    text: (r.metadata?.text || r.text || "").slice(0, 200),
-                })),
-                totalResults: results.length,
-            };
+            });
         },
     };
     return {

package/dist/lib/rag/reranker/reranker.js

@@ -4,6 +4,8 @@
  * Multi-factor scoring system for reranking retrieval results.
  * Combines semantic relevance (LLM-based), vector similarity, and position.
  */
+import { withSpan } from "../../telemetry/withSpan.js";
+import { tracers } from "../../telemetry/tracers.js";
 import { logger } from "../../utils/logger.js";
 /**
  * Default scoring weights
@@ -28,60 +30,73 @@ const DEFAULT_WEIGHTS = {
  * @returns Reranked results with detailed scores
  */
 export async function rerank(results, query, model, options) {
-    const { queryEmbedding: _queryEmbedding, topK = 3, weights = DEFAULT_WEIGHTS, } = options || {};
-    if (results.length === 0) {
-        return [];
-    }
-    // Validate weights sum to 1.0
-    const totalWeight = (weights.semantic || DEFAULT_WEIGHTS.semantic) +
-        (weights.vector || DEFAULT_WEIGHTS.vector) +
-        (weights.position || DEFAULT_WEIGHTS.position);
-    if (Math.abs(totalWeight - 1.0) > 0.01) {
-        logger.warn("[Reranker] Weights do not sum to 1.0, normalizing", {
-            original: weights,
-            total: totalWeight,
-        });
-    }
-    const normalizedWeights = {
-        semantic: (weights.semantic || DEFAULT_WEIGHTS.semantic) / totalWeight,
-        vector: (weights.vector || DEFAULT_WEIGHTS.vector) / totalWeight,
-        position: (weights.position || DEFAULT_WEIGHTS.position) / totalWeight,
-    };
-    const rerankedResults = [];
-    // Process results in parallel batches for efficiency
-    const batchSize = 5;
-    for (let i = 0; i < results.length; i += batchSize) {
-        const batch = results.slice(i, i + batchSize);
-        const batchPromises = batch.map(async (result, batchIndex) => {
-            const globalIndex = i + batchIndex;
-            // Calculate vector score (use existing score or 0)
-            const vectorScore = result.score ?? 0;
-            // Calculate position score (inverse of position)
-            const positionScore = 1 - globalIndex / results.length;
-            // Calculate semantic score using LLM
-            const semanticResult = await calculateSemanticScore(query, result.text || result.metadata?.text || "", model);
-            // Combine scores
-            const combinedScore = normalizedWeights.semantic * semanticResult.score +
-                normalizedWeights.vector * vectorScore +
-                normalizedWeights.position * positionScore;
-            return {
-                result,
-                score: combinedScore,
-                details: {
-                    semantic: semanticResult.score,
-                    vector: vectorScore,
-                    position: positionScore,
-                    queryAnalysis: semanticResult.analysis,
-                },
-            };
-        });
-        const batchResults = await Promise.all(batchPromises);
-        rerankedResults.push(...batchResults);
-    }
-    // Sort by combined score descending
-    rerankedResults.sort((a, b) => b.score - a.score);
-    // Return top K results
-    return rerankedResults.slice(0, topK);
+    return withSpan({
+        name: "neurolink.rag.rerank",
+        tracer: tracers.rag,
+        attributes: {
+            "rag.reranker.input_count": results.length,
+            "rag.reranker.top_k": options?.topK ?? 3,
+            "rag.reranker.query_length": query.length,
+        },
+    }, async (span) => {
+        const { queryEmbedding: _queryEmbedding, topK = 3, weights = DEFAULT_WEIGHTS, } = options || {};
+        if (results.length === 0) {
+            span.setAttribute("rag.reranker.output_count", 0);
+            return [];
+        }
+        // Validate weights sum to 1.0
+        const totalWeight = (weights.semantic || DEFAULT_WEIGHTS.semantic) +
+            (weights.vector || DEFAULT_WEIGHTS.vector) +
+            (weights.position || DEFAULT_WEIGHTS.position);
+        if (Math.abs(totalWeight - 1.0) > 0.01) {
+            logger.warn("[Reranker] Weights do not sum to 1.0, normalizing", {
+                original: weights,
+                total: totalWeight,
+            });
+        }
+        const normalizedWeights = {
+            semantic: (weights.semantic || DEFAULT_WEIGHTS.semantic) / totalWeight,
+            vector: (weights.vector || DEFAULT_WEIGHTS.vector) / totalWeight,
+            position: (weights.position || DEFAULT_WEIGHTS.position) / totalWeight,
+        };
+        const rerankedResults = [];
+        // Process results in parallel batches for efficiency
+        const batchSize = 5;
+        for (let i = 0; i < results.length; i += batchSize) {
+            const batch = results.slice(i, i + batchSize);
+            const batchPromises = batch.map(async (result, batchIndex) => {
+                const globalIndex = i + batchIndex;
+                // Calculate vector score (use existing score or 0)
+                const vectorScore = result.score ?? 0;
+                // Calculate position score (inverse of position)
+                const positionScore = 1 - globalIndex / results.length;
+                // Calculate semantic score using LLM
+                const semanticResult = await calculateSemanticScore(query, result.text || result.metadata?.text || "", model);
+                // Combine scores
+                const combinedScore = normalizedWeights.semantic * semanticResult.score +
+                    normalizedWeights.vector * vectorScore +
+                    normalizedWeights.position * positionScore;
+                return {
+                    result,
+                    score: combinedScore,
+                    details: {
+                        semantic: semanticResult.score,
+                        vector: vectorScore,
+                        position: positionScore,
+                        queryAnalysis: semanticResult.analysis,
+                    },
+                };
+            });
+            const batchResults = await Promise.all(batchPromises);
+            rerankedResults.push(...batchResults);
+        }
+        // Sort by combined score descending
+        rerankedResults.sort((a, b) => b.score - a.score);
+        // Return top K results
+        const output = rerankedResults.slice(0, topK);
+        span.setAttribute("rag.reranker.output_count", output.length);
+        return output;
+    }); // end withSpan
 }
 /**
  * Calculate semantic relevance score using LLM
@@ -135,24 +150,35 @@ Score:`;
  * @returns Reranked results
  */
 export async function batchRerank(results, query, model, options) {
-    const { topK = 3, weights = DEFAULT_WEIGHTS } = options || {};
-    if (results.length === 0) {
-        return [];
-    }
-    // Normalize weights
-    const totalWeight = (weights.semantic || DEFAULT_WEIGHTS.semantic) +
-        (weights.vector || DEFAULT_WEIGHTS.vector) +
-        (weights.position || DEFAULT_WEIGHTS.position);
-    const normalizedWeights = {
-        semantic: (weights.semantic || DEFAULT_WEIGHTS.semantic) / totalWeight,
-        vector: (weights.vector || DEFAULT_WEIGHTS.vector) / totalWeight,
-        position: (weights.position || DEFAULT_WEIGHTS.position) / totalWeight,
-    };
-    // Build batch scoring prompt
-    const documentsText = results
-        .map((r, i) => `[${i + 1}] ${(r.text || r.metadata?.text || "").slice(0, 300)}`)
-        .join("\n\n");
-    const prompt = `Rate the relevance of each document to the query on a scale of 0 to 1.
+    return withSpan({
+        name: "neurolink.rag.batchRerank",
+        tracer: tracers.rag,
+        attributes: {
+            "rag.reranker.input_count": results.length,
+            "rag.reranker.top_k": options?.topK ?? 3,
+            "rag.reranker.query_length": query.length,
+            "rag.reranker.batch": true,
+        },
+    }, async (span) => {
+        const { topK = 3, weights = DEFAULT_WEIGHTS } = options || {};
+        if (results.length === 0) {
+            span.setAttribute("rag.reranker.output_count", 0);
+            return [];
+        }
+        // Normalize weights
+        const totalWeight = (weights.semantic || DEFAULT_WEIGHTS.semantic) +
+            (weights.vector || DEFAULT_WEIGHTS.vector) +
+            (weights.position || DEFAULT_WEIGHTS.position);
+        const normalizedWeights = {
+            semantic: (weights.semantic || DEFAULT_WEIGHTS.semantic) / totalWeight,
+            vector: (weights.vector || DEFAULT_WEIGHTS.vector) / totalWeight,
+            position: (weights.position || DEFAULT_WEIGHTS.position) / totalWeight,
+        };
+        // Build batch scoring prompt
+        const documentsText = results
+            .map((r, i) => `[${i + 1}] ${(r.text || r.metadata?.text || "").slice(0, 300)}`)
+            .join("\n\n");
+        const prompt = `Rate the relevance of each document to the query on a scale of 0 to 1.
 
 Query: ${query}
 
@@ -161,58 +187,61 @@ ${documentsText}
 
 For each document, provide a score between 0 and 1.
 Respond with only the scores, one per line, in order:`;
-    try {
-        const result = await model.generate({
-            prompt,
-            maxTokens: 50,
-            temperature: 0,
-        });
-        // Parse scores from response
-        const scoreLines = (result?.content || "")
-            .trim()
-            .split("\n")
-            .map((line) => line.trim())
-            .filter((line) => line.length > 0);
-        const semanticScores = [];
-        for (let i = 0; i < results.length; i++) {
-            const scoreLine = scoreLines[i];
-            if (scoreLine) {
-                const score = parseFloat(scoreLine.match(/[\d.]+/)?.[0] || "0.5");
-                semanticScores.push(isNaN(score) || score < 0 || score > 1 ? 0.5 : score);
-            }
-            else {
-                semanticScores.push(0.5);
+        try {
+            const result = await model.generate({
+                prompt,
+                maxTokens: 50,
+                temperature: 0,
+            });
+            // Parse scores from response
+            const scoreLines = (result?.content || "")
+                .trim()
+                .split("\n")
+                .map((line) => line.trim())
+                .filter((line) => line.length > 0);
+            const semanticScores = [];
+            for (let i = 0; i < results.length; i++) {
+                const scoreLine = scoreLines[i];
+                if (scoreLine) {
+                    const score = parseFloat(scoreLine.match(/[\d.]+/)?.[0] || "0.5");
+                    semanticScores.push(isNaN(score) || score < 0 || score > 1 ? 0.5 : score);
+                }
+                else {
+                    semanticScores.push(0.5);
+                }
             }
+            // Calculate combined scores
+            const rerankedResults = results.map((result, i) => {
+                const vectorScore = result.score ?? 0;
+                const positionScore = 1 - i / results.length;
+                const semanticScore = semanticScores[i] ?? 0.5;
+                const combinedScore = normalizedWeights.semantic * semanticScore +
+                    normalizedWeights.vector * vectorScore +
+                    normalizedWeights.position * positionScore;
+                return {
+                    result,
+                    score: combinedScore,
+                    details: {
+                        semantic: semanticScore,
+                        vector: vectorScore,
+                        position: positionScore,
+                    },
+                };
+            });
+            // Sort and return top K
+            rerankedResults.sort((a, b) => b.score - a.score);
+            const output = rerankedResults.slice(0, topK);
+            span.setAttribute("rag.reranker.output_count", output.length);
+            return output;
         }
-        // Calculate combined scores
-        const rerankedResults = results.map((result, i) => {
-            const vectorScore = result.score ?? 0;
-            const positionScore = 1 - i / results.length;
-            const semanticScore = semanticScores[i] ?? 0.5;
-            const combinedScore = normalizedWeights.semantic * semanticScore +
-                normalizedWeights.vector * vectorScore +
-                normalizedWeights.position * positionScore;
-            return {
-                result,
-                score: combinedScore,
-                details: {
-                    semantic: semanticScore,
-                    vector: vectorScore,
-                    position: positionScore,
-                },
-            };
-        });
-        // Sort and return top K
-        rerankedResults.sort((a, b) => b.score - a.score);
-        return rerankedResults.slice(0, topK);
-    }
-    catch (error) {
-        logger.warn("[Reranker] Batch scoring failed, using individual scoring", {
-            error: error instanceof Error ? error.message : String(error),
-        });
-        // Fall back to individual scoring
-        return rerank(results, query, model, options);
-    }
+        catch (error) {
+            logger.warn("[Reranker] Batch scoring failed, using individual scoring", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            // Fall back to individual scoring
+            return rerank(results, query, model, options);
+        }
+    }); // end withSpan
 }
 /**
  * Simple position-based reranker (no LLM required)