@juspay/neurolink 9.24.0 → 9.25.1

package/dist/lib/files/fileTools.d.ts

@@ -337,11 +337,11 @@ export declare function createFileTools(registry: FileReferenceRegistry): {
         format: z.ZodOptional<z.ZodEnum<["text", "detailed", "summary"]>>;
     }, "strip", z.ZodTypeAny, {
         file_id: string;
+        end_time?: number | undefined;
+        start_time?: number | undefined;
         format?: "text" | "summary" | "detailed" | undefined;
         sheet?: string | undefined;
         columns?: string[] | undefined;
-        start_time?: number | undefined;
-        end_time?: number | undefined;
         frame_count?: number | undefined;
         pages?: number[] | undefined;
         page_range?: {
@@ -355,11 +355,11 @@ export declare function createFileTools(registry: FileReferenceRegistry): {
         entry_path?: string | undefined;
     }, {
         file_id: string;
+        end_time?: number | undefined;
+        start_time?: number | undefined;
         format?: "text" | "summary" | "detailed" | undefined;
         sheet?: string | undefined;
         columns?: string[] | undefined;
-        start_time?: number | undefined;
-        end_time?: number | undefined;
         frame_count?: number | undefined;
         pages?: number[] | undefined;
         page_range?: {
@@ -388,11 +388,11 @@ export declare function createFileTools(registry: FileReferenceRegistry): {
     }> & {
         execute: (args: {
             file_id: string;
+            end_time?: number | undefined;
+            start_time?: number | undefined;
             format?: "text" | "summary" | "detailed" | undefined;
             sheet?: string | undefined;
             columns?: string[] | undefined;
-            start_time?: number | undefined;
-            end_time?: number | undefined;
             frame_count?: number | undefined;
             pages?: number[] | undefined;
             page_range?: {

package/dist/lib/index.d.ts

@@ -33,17 +33,17 @@
  */
 import { AIProviderFactory } from "./core/factory.js";
 export { AIProviderFactory };
+export { GoogleTTSHandler } from "./adapters/tts/googleTTSHandler.js";
 export { NeuroLinkConfigManager as ConfigManager } from "./config/configManager.js";
 export { AIProviderName, BedrockModels, OpenAIModels, VertexModels, } from "./constants/enums.js";
 export { dynamicModelProvider } from "./core/dynamicModels.js";
 export { validateTool } from "./sdk/toolRegistration.js";
 export * from "./types/index.js";
 export type { DynamicModelConfig, ModelRegistry } from "./types/modelTypes.js";
-export { getAvailableProviders, getBestProvider, isValidProvider, } from "./utils/providerUtils.js";
-export { calculateCost, hasPricing } from "./utils/pricing.js";
 export { isAbortError } from "./utils/errorHandling.js";
+export { calculateCost, hasPricing } from "./utils/pricing.js";
+export { getAvailableProviders, getBestProvider, isValidProvider, } from "./utils/providerUtils.js";
 export { TTSProcessor } from "./utils/ttsProcessor.js";
-export { GoogleTTSHandler } from "./adapters/tts/googleTTSHandler.js";
 import { NeuroLink } from "./neurolink.js";
 export { NeuroLink };
 export type { MCPServerInfo } from "./types/mcpTypes.js";
@@ -54,6 +54,15 @@ export type { LangfuseContext } from "./services/server/ai/observability/instrum
 export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, getLangfuseSpanProcessor, getTracerProvider, isOpenTelemetryInitialized, getSpanProcessors, createContextEnricher, isUsingExternalTracerProvider, getLangfuseContext, getTracer, runWithCurrentLangfuseContext, };
 export { clearAnalyticsMetrics, createAnalyticsMiddleware, getAnalyticsMetrics, } from "./middleware/builtin/analytics.js";
 export { MiddlewareFactory } from "./middleware/factory.js";
+export { ExporterRegistry } from "./observability/exporterRegistry.js";
+export { NoOpExporter } from "./observability/exporters/baseExporter.js";
+export type { LatencyStats, MetricsSummary, ModelCostStats, ProviderCostStats, TraceView, } from "./observability/metricsAggregator.js";
+export { getMetricsAggregator, MetricsAggregator, resetMetricsAggregator, } from "./observability/metricsAggregator.js";
+export { AlwaysSampler, NeverSampler, } from "./observability/sampling/samplers.js";
+export { TokenTracker } from "./observability/tokenTracker.js";
+export type { SpanAttributes, SpanData, SpanEvent, } from "./observability/types/spanTypes.js";
+export { GENAI_ATTRIBUTES, SpanStatus, SpanType, } from "./observability/types/spanTypes.js";
+export { SpanSerializer } from "./observability/utils/spanSerializer.js";
 export type { MiddlewareConfig, MiddlewareContext, MiddlewareFactoryOptions, MiddlewarePreset, NeuroLinkMiddleware, } from "./types/middlewareTypes.js";
 export declare const VERSION = "1.0.0";
 /**
@@ -274,17 +283,17 @@ export declare function generateText(options: import("./types/index.js").TextGen
  * console.log('Total time:', result.workflow?.metrics?.totalTime);
  * ```
  */
-export type { WorkflowConfig, WorkflowResult, ModelConfig, JudgeConfig, ModelGroup, EnsembleResponse, JudgeScores, MultiJudgeScores, WorkflowType, ExecutionStrategy, WorkflowValidationResult, } from "./workflow/types.js";
-export { runWorkflow } from "./workflow/core/workflowRunner.js";
+export { clearRegistry as clearWorkflowRegistry, getWorkflow, listWorkflows, registerWorkflow, } from "./workflow/core/workflowRegistry.js";
 export type { RunWorkflowOptions } from "./workflow/core/workflowRunner.js";
-export { registerWorkflow, getWorkflow, listWorkflows, clearRegistry as clearWorkflowRegistry, } from "./workflow/core/workflowRegistry.js";
-export { CONSENSUS_3_WORKFLOW, CONSENSUS_3_FAST_WORKFLOW, createConsensus3WithPrompt, } from "./workflow/workflows/consensusWorkflow.js";
-export { FAST_FALLBACK_WORKFLOW, AGGRESSIVE_FALLBACK_WORKFLOW, } from "./workflow/workflows/fallbackWorkflow.js";
-export { MULTI_JUDGE_5_WORKFLOW, MULTI_JUDGE_3_WORKFLOW, createMultiJudgeWorkflow, } from "./workflow/workflows/multiJudgeWorkflow.js";
-export { QUALITY_MAX_WORKFLOW, SPEED_FIRST_WORKFLOW, BALANCED_ADAPTIVE_WORKFLOW, createAdaptiveWorkflow, } from "./workflow/workflows/adaptiveWorkflow.js";
-export { validateWorkflow } from "./workflow/utils/workflowValidation.js";
+export { runWorkflow } from "./workflow/core/workflowRunner.js";
+export { DEFAULT_SCORE_SCALE, WORKFLOW_ENGINE_VERSION, } from "./workflow/index.js";
+export type { EnsembleResponse, ExecutionStrategy, JudgeConfig, JudgeScores, ModelConfig, ModelGroup, MultiJudgeScores, WorkflowConfig, WorkflowResult, WorkflowType, WorkflowValidationResult, } from "./workflow/types.js";
 export { calculateModelMetrics, compareWorkflows, generateSummaryStats, } from "./workflow/utils/workflowMetrics.js";
-export { WORKFLOW_ENGINE_VERSION, DEFAULT_SCORE_SCALE, } from "./workflow/index.js";
+export { validateWorkflow } from "./workflow/utils/workflowValidation.js";
+export { BALANCED_ADAPTIVE_WORKFLOW, createAdaptiveWorkflow, QUALITY_MAX_WORKFLOW, SPEED_FIRST_WORKFLOW, } from "./workflow/workflows/adaptiveWorkflow.js";
+export { CONSENSUS_3_FAST_WORKFLOW, CONSENSUS_3_WORKFLOW, createConsensus3WithPrompt, } from "./workflow/workflows/consensusWorkflow.js";
+export { AGGRESSIVE_FALLBACK_WORKFLOW, FAST_FALLBACK_WORKFLOW, } from "./workflow/workflows/fallbackWorkflow.js";
+export { createMultiJudgeWorkflow, MULTI_JUDGE_3_WORKFLOW, MULTI_JUDGE_5_WORKFLOW, } from "./workflow/workflows/multiJudgeWorkflow.js";
 export type { AgentExecuteRequest, AgentExecuteResponse, AuthConfig, AuthenticatedUser, AuthResult, AuthStrategy, BodyParserConfig, CacheConfig, CacheEntry, CacheStore, CORSConfig, CreateRoutesOptions, DataEvent, DataStreamEvent, DataStreamEventType, DataStreamResponseConfig, DataStreamWriter, DataStreamWriterConfig, ErrorCategoryType, ErrorEvent, ErrorResponse, ErrorSeverityType, FinishEvent, HealthResponse, HttpMethod, LoggingConfig, MCPServerStatusResponse, MiddlewareDefinition, MiddlewareHandler, OpenAPIGeneratorConfig, OpenAPISpec, PropertySchema, RateLimitConfig as ServerRateLimitConfig, RateLimitMiddlewareConfig, RateLimitStore, ReadyResponse, RequiredServerAdapterConfig, RouteDefinition, RouteGroup, RouteHandler, ServerAdapterConfig, ServerAdapterErrorCodeType, ServerAdapterErrorContext, ServerAdapterEvents, ServerAdapterFactoryOptions, ServerContext, ServerFramework, ServerResponse, ServerStatus, SSEWriteOptions, StreamingConfig, TextDeltaEvent, TextEndEvent, TextStartEvent, ToolCallEvent, ToolExecuteRequest, ToolExecuteResponse, ToolResultEvent, ValidationConfig, ValidationResult, ValidationSchema, WebSocketAuthConfig, WebSocketConfig, WebSocketConnection, WebSocketHandler, WebSocketMessage, WebSocketMessageType, } from "./server/index.js";
 /**
  * Server Adapters for exposing NeuroLink as HTTP APIs
@@ -336,3 +345,28 @@ export type { BaseChunkerConfig, BM25Result, CharacterChunkerConfig, Chunk, Chun
  * ```
  */
 export { assembleContext, batchRerank, CharacterChunker, ChunkerRegistry, CohereRelevanceScorer, CrossEncoderReranker, CSVLoader, chunkText, createChunker, createContextWindow, createHybridSearch, createRAGPipeline, createVectorQueryTool, executeWithCircuitBreaker, extractMetadata, formatContextWithCitations, GraphRAG, getAvailableStrategies, getCircuitBreaker, getDefaultChunkerConfig, getRecommendedStrategy, HTMLChunker, HTMLLoader, InMemoryBM25Index, InMemoryVectorStore, JSONChunker as RAGJSONChunker, JSONLoader, LaTeXChunker, LLMMetadataExtractor, linearCombination, loadDocument, loadDocuments, MarkdownChunker, MarkdownLoader, MDocument, PDFLoader, prepareRAGTool, processDocument, RAGCircuitBreaker, type RAGCircuitBreakerConfig, type RAGCircuitBreakerEvents, RAGCircuitBreakerManager, type RAGCircuitBreakerStats, RAGPipeline, RAGRetryHandler, RecursiveChunker, ragCircuitBreakerManager, reciprocalRankFusion, rerank, SemanticChunker, SentenceChunker, simpleRerank, summarizeContext, TextLoader, TokenChunker, WebLoader, } from "./rag/index.js";
+export { ContextBuilder } from "./evaluation/contextBuilder.js";
+/**
+ * Evaluation system for AI response quality assessment.
+ *
+ * Uses RAGAS-style model-based evaluation with a "judge" LLM to score
+ * responses on relevance, accuracy, completeness, and overall quality.
+ * Supports retry logic with progressive prompt improvement.
+ *
+ * @example
+ * ```typescript
+ * import { Evaluator, RAGASEvaluator, ContextBuilder, RetryManager } from '@juspay/neurolink';
+ *
+ * const evaluator = new Evaluator({
+ *   evaluationModel: 'gemini-1.5-flash',
+ *   provider: 'vertex',
+ *   threshold: 7,
+ * });
+ * ```
+ */
+export { Evaluator } from "./evaluation/index.js";
+export { PromptBuilder } from "./evaluation/prompts.js";
+export { RAGASEvaluator } from "./evaluation/ragasEvaluator.js";
+export { RetryManager } from "./evaluation/retryManager.js";
+export { mapToEvaluationData } from "./evaluation/scoring.js";
+export type { EnhancedConversationTurn, EnhancedEvaluationContext, EvaluationConfig, EvaluationResult, GetPromptFunction, QualityErrorDetails, QueryIntentAnalysis, } from "./types/evaluationTypes.js";

package/dist/lib/index.js

@@ -34,6 +34,7 @@
 // Core exports
 import { AIProviderFactory } from "./core/factory.js";
 export { AIProviderFactory };
+export { GoogleTTSHandler } from "./adapters/tts/googleTTSHandler.js";
 // Config Manager export
 export { NeuroLinkConfigManager as ConfigManager } from "./config/configManager.js";
 export { AIProviderName, BedrockModels, OpenAIModels, VertexModels, } from "./constants/enums.js";
@@ -43,15 +44,14 @@ export { dynamicModelProvider } from "./core/dynamicModels.js";
 export { validateTool } from "./sdk/toolRegistration.js";
 // Export ALL types from the centralized type barrel
 export * from "./types/index.js";
-// Utility exports
-export { getAvailableProviders, getBestProvider, isValidProvider, } from "./utils/providerUtils.js";
-// Pricing utilities
-export { calculateCost, hasPricing } from "./utils/pricing.js";
 // Error utilities
 export { isAbortError } from "./utils/errorHandling.js";
+// Pricing utilities
+export { calculateCost, hasPricing } from "./utils/pricing.js";
+// Utility exports
+export { getAvailableProviders, getBestProvider, isValidProvider, } from "./utils/providerUtils.js";
 // TTS utilities
 export { TTSProcessor } from "./utils/ttsProcessor.js";
-export { GoogleTTSHandler } from "./adapters/tts/googleTTSHandler.js";
 // Main NeuroLink wrapper class and diagnostic types
 import { NeuroLink } from "./neurolink.js";
 export { NeuroLink };
@@ -72,6 +72,14 @@ runWithCurrentLangfuseContext, };
 // Analytics Middleware exports
 export { clearAnalyticsMetrics, createAnalyticsMiddleware, getAnalyticsMetrics, } from "./middleware/builtin/analytics.js";
 export { MiddlewareFactory } from "./middleware/factory.js";
+export { ExporterRegistry } from "./observability/exporterRegistry.js";
+export { NoOpExporter } from "./observability/exporters/baseExporter.js";
+// Observability modules and types
+export { getMetricsAggregator, MetricsAggregator, resetMetricsAggregator, } from "./observability/metricsAggregator.js";
+export { AlwaysSampler, NeverSampler, } from "./observability/sampling/samplers.js";
+export { TokenTracker } from "./observability/tokenTracker.js";
+export { GENAI_ATTRIBUTES, SpanStatus, SpanType, } from "./observability/types/spanTypes.js";
+export { SpanSerializer } from "./observability/utils/spanSerializer.js";
 // Version
 export const VERSION = "1.0.0";
 /**
@@ -299,23 +307,50 @@ export async function generateText(options) {
     const neurolink = new NeuroLink();
     return await neurolink.generateText(options);
 }
+// ============================================================================
+// WORKFLOW ENGINE - Multi-Model Orchestration with Judge Scoring
+// ============================================================================
+/**
+ * Workflow Engine for multi-model ensembles with judge-based evaluation
+ *
+ * Enables sophisticated AI orchestration patterns:
+ * - Ensemble execution (parallel multi-model)
+ * - Chain execution (sequential fallback)
+ * - Adaptive execution (tier-based quality/cost optimization)
+ * - Multi-judge voting for consensus
+ *
+ * @example
+ * ```typescript
+ * import { neurolink, CONSENSUS_3_WORKFLOW } from '@juspay/neurolink';
+ *
+ * // Use workflow via generate() with workflowConfig option
+ * const result = await neurolink.generate({
+ *   input: { text: 'Explain quantum computing' },
+ *   workflowConfig: CONSENSUS_3_WORKFLOW,
+ * });
+ *
+ * console.log('Best response:', result.content);
+ * console.log('Selected model:', result.workflow?.selectedModel);
+ * console.log('Total time:', result.workflow?.metrics?.totalTime);
+ * ```
+ */
+// Workflow registry
+export { clearRegistry as clearWorkflowRegistry, getWorkflow, listWorkflows, registerWorkflow, } from "./workflow/core/workflowRegistry.js";
 // Workflow execution
 export { runWorkflow } from "./workflow/core/workflowRunner.js";
-// Workflow registry
-export { registerWorkflow, getWorkflow, listWorkflows, clearRegistry as clearWorkflowRegistry, } from "./workflow/core/workflowRegistry.js";
+// Workflow constants
+export { DEFAULT_SCORE_SCALE, WORKFLOW_ENGINE_VERSION, } from "./workflow/index.js";
+export { calculateModelMetrics, compareWorkflows, generateSummaryStats, } from "./workflow/utils/workflowMetrics.js";
+// Validation and metrics
+export { validateWorkflow } from "./workflow/utils/workflowValidation.js";
+// Pre-built workflows - Adaptive
+export { BALANCED_ADAPTIVE_WORKFLOW, createAdaptiveWorkflow, QUALITY_MAX_WORKFLOW, SPEED_FIRST_WORKFLOW, } from "./workflow/workflows/adaptiveWorkflow.js";
 // Pre-built workflows - Consensus
-export { CONSENSUS_3_WORKFLOW, CONSENSUS_3_FAST_WORKFLOW, createConsensus3WithPrompt, } from "./workflow/workflows/consensusWorkflow.js";
+export { CONSENSUS_3_FAST_WORKFLOW, CONSENSUS_3_WORKFLOW, createConsensus3WithPrompt, } from "./workflow/workflows/consensusWorkflow.js";
 // Pre-built workflows - Fallback
-export { FAST_FALLBACK_WORKFLOW, AGGRESSIVE_FALLBACK_WORKFLOW, } from "./workflow/workflows/fallbackWorkflow.js";
+export { AGGRESSIVE_FALLBACK_WORKFLOW, FAST_FALLBACK_WORKFLOW, } from "./workflow/workflows/fallbackWorkflow.js";
 // Pre-built workflows - Multi-judge
-export { MULTI_JUDGE_5_WORKFLOW, MULTI_JUDGE_3_WORKFLOW, createMultiJudgeWorkflow, } from "./workflow/workflows/multiJudgeWorkflow.js";
-// Pre-built workflows - Adaptive
-export { QUALITY_MAX_WORKFLOW, SPEED_FIRST_WORKFLOW, BALANCED_ADAPTIVE_WORKFLOW, createAdaptiveWorkflow, } from "./workflow/workflows/adaptiveWorkflow.js";
-// Validation and metrics
-export { validateWorkflow } from "./workflow/utils/workflowValidation.js";
-export { calculateModelMetrics, compareWorkflows, generateSummaryStats, } from "./workflow/utils/workflowMetrics.js";
-// Workflow constants
-export { WORKFLOW_ENGINE_VERSION, DEFAULT_SCORE_SCALE, } from "./workflow/index.js";
+export { createMultiJudgeWorkflow, MULTI_JUDGE_3_WORKFLOW, MULTI_JUDGE_5_WORKFLOW, } from "./workflow/workflows/multiJudgeWorkflow.js";
 /**
  * Server Adapters for exposing NeuroLink as HTTP APIs
  *
@@ -403,4 +438,31 @@ extractMetadata, formatContextWithCitations,
 GraphRAG, getAvailableStrategies, getCircuitBreaker, getDefaultChunkerConfig, getRecommendedStrategy, HTMLChunker, HTMLLoader, InMemoryBM25Index, InMemoryVectorStore, JSONChunker as RAGJSONChunker, JSONLoader, LaTeXChunker, LLMMetadataExtractor, linearCombination, loadDocument, loadDocuments, MarkdownChunker, MarkdownLoader, MDocument, PDFLoader, 
 // RAG Integration for generate/stream
 prepareRAGTool, processDocument, RAGCircuitBreaker, RAGCircuitBreakerManager, RAGPipeline, RAGRetryHandler, RecursiveChunker, ragCircuitBreakerManager, reciprocalRankFusion, rerank, SemanticChunker, SentenceChunker, simpleRerank, summarizeContext, TextLoader, TokenChunker, WebLoader, } from "./rag/index.js";
+// ============================================================================
+// EVALUATION / SCORING - RAGAS-style Response Quality Evaluation
+// ============================================================================
+export { ContextBuilder } from "./evaluation/contextBuilder.js";
+/**
+ * Evaluation system for AI response quality assessment.
+ *
+ * Uses RAGAS-style model-based evaluation with a "judge" LLM to score
+ * responses on relevance, accuracy, completeness, and overall quality.
+ * Supports retry logic with progressive prompt improvement.
+ *
+ * @example
+ * ```typescript
+ * import { Evaluator, RAGASEvaluator, ContextBuilder, RetryManager } from '@juspay/neurolink';
+ *
+ * const evaluator = new Evaluator({
+ *   evaluationModel: 'gemini-1.5-flash',
+ *   provider: 'vertex',
+ *   threshold: 7,
+ * });
+ * ```
+ */
+export { Evaluator } from "./evaluation/index.js";
+export { PromptBuilder } from "./evaluation/prompts.js";
+export { RAGASEvaluator } from "./evaluation/ragasEvaluator.js";
+export { RetryManager } from "./evaluation/retryManager.js";
+export { mapToEvaluationData } from "./evaluation/scoring.js";
 //# sourceMappingURL=index.js.map

package/dist/lib/mcp/httpRateLimiter.js

@@ -4,6 +4,8 @@
  * Provides fault tolerance and prevents server overload
  */
 import { mcpLogger } from "../utils/logger.js";
+import { SpanSerializer, SpanType, SpanStatus, } from "../observability/index.js";
+import { getMetricsAggregator } from "../observability/index.js";
 /**
  * Default rate limit configuration
  * Provides sensible defaults for most MCP HTTP transport use cases
@@ -71,19 +73,44 @@ export class HTTPRateLimiter {
      * @throws Error if the wait queue is too long
      */
     async acquire() {
-        // First, try to acquire without waiting
-        if (this.tryAcquire()) {
-            return;
-        }
-        // Add to wait queue
-        return new Promise((resolve, reject) => {
-            this.waitQueue.push({ resolve, reject });
-            mcpLogger.debug(`[HTTPRateLimiter] Request queued, queue length: ${this.waitQueue.length}`);
-            // Start processing the queue if not already processing
-            if (!this.processingQueue) {
-                this.processQueue();
-            }
+        const span = SpanSerializer.createSpan(SpanType.MCP_TRANSPORT, "mcp.rateLimit", {
+            "mcp.transport": "http",
+            "mcp.operation": "rateLimit",
+            "mcp.rateLimit.tokensAvailable": this.tokens,
+            "mcp.rateLimit.maxBurst": this.config.maxBurst,
         });
+        const startTime = Date.now();
+        try {
+            // First, try to acquire without waiting
+            if (this.tryAcquire()) {
+                span.durationMs = Date.now() - startTime;
+                span.attributes["mcp.rateLimit.waited"] = false;
+                const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
+                getMetricsAggregator().recordSpan(endedSpan);
+                return;
+            }
+            // Add to wait queue
+            await new Promise((resolve, reject) => {
+                this.waitQueue.push({ resolve, reject });
+                mcpLogger.debug(`[HTTPRateLimiter] Request queued, queue length: ${this.waitQueue.length}`);
+                // Start processing the queue if not already processing
+                if (!this.processingQueue) {
+                    this.processQueue();
+                }
+            });
+            span.durationMs = Date.now() - startTime;
+            span.attributes["mcp.rateLimit.waited"] = true;
+            const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
+            getMetricsAggregator().recordSpan(endedSpan);
+        }
+        catch (error) {
+            span.durationMs = Date.now() - startTime;
+            const endedSpan = SpanSerializer.endSpan(span, SpanStatus.ERROR);
+            endedSpan.statusMessage =
+                error instanceof Error ? error.message : String(error);
+            getMetricsAggregator().recordSpan(endedSpan);
+            throw error;
+        }
     }
     /**
      * Process the wait queue, granting tokens as they become available

package/dist/lib/mcp/httpRetryHandler.js

@@ -7,6 +7,8 @@
 import { isAbortError } from "../utils/errorHandling.js";
 import { calculateBackoffDelay } from "../utils/retryHandler.js";
 import { logger } from "../utils/logger.js";
+import { SpanSerializer, SpanType, SpanStatus, } from "../observability/index.js";
+import { getMetricsAggregator } from "../observability/index.js";
 /**
  * Default HTTP retry configuration
  */
@@ -129,10 +131,23 @@ export async function withHTTPRetry(operation, config = {}) {
         ...DEFAULT_HTTP_RETRY_CONFIG,
         ...config,
     };
+    const span = SpanSerializer.createSpan(SpanType.MCP_TRANSPORT, "mcp.retry", {
+        "mcp.transport": "http",
+        "mcp.operation": "retry",
+        "mcp.maxAttempts": mergedConfig.maxAttempts,
+    });
+    const startTime = Date.now();
     let lastError;
+    let actualAttempts = 0;
     for (let attempt = 1; attempt <= mergedConfig.maxAttempts; attempt++) {
+        actualAttempts = attempt;
         try {
-            return await operation();
+            const result = await operation();
+            span.durationMs = Date.now() - startTime;
+            span.attributes["mcp.retryAttempt"] = attempt;
+            const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
+            getMetricsAggregator().recordSpan(endedSpan);
+            return result;
         }
         catch (error) {
             lastError = error;
@@ -153,6 +168,12 @@ export async function withHTTPRetry(operation, config = {}) {
             await sleep(delay);
         }
     }
+    span.durationMs = Date.now() - startTime;
+    span.attributes["mcp.retryAttempt"] = actualAttempts;
+    const endedSpan = SpanSerializer.endSpan(span, SpanStatus.ERROR);
+    endedSpan.statusMessage =
+        lastError instanceof Error ? lastError.message : String(lastError);
+    getMetricsAggregator().recordSpan(endedSpan);
     throw lastError;
 }
 //# sourceMappingURL=httpRetryHandler.js.map

package/dist/lib/mcp/mcpClientFactory.js

@@ -15,8 +15,8 @@ import { globalCircuitBreakerManager } from "./mcpCircuitBreaker.js";
 import { withHTTPRetry, DEFAULT_HTTP_RETRY_CONFIG, } from "./httpRetryHandler.js";
 import { globalRateLimiterManager } from "./httpRateLimiter.js";
 import { NeuroLinkOAuthProvider, InMemoryTokenStorage } from "./auth/index.js";
-import { tracers } from "../telemetry/tracers.js";
-import { SpanStatusCode } from "@opentelemetry/api";
+import { SpanSerializer, SpanType, SpanStatus, } from "../observability/index.js";
+import { getMetricsAggregator } from "../observability/index.js";
 /**
  * MCPClientFactory
  * Factory class for creating MCP clients with different transports
@@ -38,12 +38,10 @@ export class MCPClientFactory {
      */
     static async createClient(config, timeout = 10000) {
         const startTime = Date.now();
-        const span = tracers.mcp.startSpan("neurolink.mcp.client.create", {
-            attributes: {
-                "mcp.server_id": config.id,
-                "mcp.transport": config.transport,
-                "mcp.timeout_ms": timeout,
-            },
+        const obsSpan = SpanSerializer.createSpan(SpanType.MCP_TRANSPORT, "mcp.connect", {
+            "mcp.transport": config.transport,
+            "mcp.operation": "connect",
+            "mcp.server_id": config.id,
         });
         try {
             mcpLogger.info(`[MCPClientFactory] Creating client for ${config.id}`, {
@@ -103,7 +101,9 @@ export class MCPClientFactory {
                 duration: Date.now() - startTime,
                 capabilities: result.capabilities,
             });
-            span.setStatus({ code: SpanStatusCode.OK });
+            obsSpan.durationMs = Date.now() - startTime;
+            const endedObsSpan = SpanSerializer.endSpan(obsSpan, SpanStatus.OK);
+            getMetricsAggregator().recordSpan(endedObsSpan);
             return {
                 ...result,
                 success: true,
@@ -113,18 +113,16 @@ export class MCPClientFactory {
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
             mcpLogger.error(`[MCPClientFactory] Failed to create client for ${config.id}:`, error);
-            // NLK-GAP-004 fix: Record both exception AND error status on span
-            span.recordException(error instanceof Error ? error : new Error(errorMessage));
-            span.setStatus({ code: SpanStatusCode.ERROR, message: errorMessage });
+            obsSpan.durationMs = Date.now() - startTime;
+            const endedObsSpan = SpanSerializer.endSpan(obsSpan, SpanStatus.ERROR);
+            endedObsSpan.statusMessage = errorMessage;
+            getMetricsAggregator().recordSpan(endedObsSpan);
             return {
                 success: false,
                 error: errorMessage,
                 duration: Date.now() - startTime,
             };
         }
-        finally {
-            span.end();
-        }
     }
     /**
      * Internal client creation logic

package/dist/lib/memory/memoryRetrievalTools.js

@@ -9,6 +9,8 @@
 import { tool } from "ai";
 import { z } from "zod";
 import { logger } from "../utils/logger.js";
+import { SpanSerializer, SpanType, SpanStatus, } from "../observability/index.js";
+import { getMetricsAggregator } from "../observability/index.js";
 /** Maximum characters returned per retrieval request */
 const DEFAULT_RETRIEVAL_LIMIT = 50_000;
 /** Hard maximum for user/LLM-supplied limit to prevent massive tool outputs */
@@ -62,9 +64,18 @@ export function createMemoryRetrievalTools(memoryManager) {
                     "Returns matching lines with line numbers."),
             }),
             execute: async (args) => {
+                const span = SpanSerializer.createSpan(SpanType.MEMORY, "memory.retrieve", {
+                    "memory.operation": "retrieve",
+                    "memory.store": "redis",
+                    "memory.query": args.search || args.messageId || `lastN:${args.lastN ?? "all"}`,
+                });
+                const startTime = Date.now();
                 try {
                     const conversation = await memoryManager.getSessionRaw(args.sessionId);
                     if (!conversation) {
+                        span.durationMs = Date.now() - startTime;
+                        const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
+                        getMetricsAggregator().recordSpan(endedSpan);
                         return { error: "Session not found", sessionId: args.sessionId };
                     }
                     let messages = conversation.messages;
@@ -72,6 +83,9 @@ export function createMemoryRetrievalTools(memoryManager) {
                     if (args.messageId) {
                         const msg = messages.find((m) => m.id === args.messageId);
                         if (!msg) {
+                            span.durationMs = Date.now() - startTime;
+                            const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
+                            getMetricsAggregator().recordSpan(endedSpan);
                             return { error: "Message not found", messageId: args.messageId };
                         }
                         messages = [msg];
@@ -130,9 +144,17 @@ export function createMemoryRetrievalTools(memoryManager) {
                             hasMore: end < content.length,
                         };
                     });
+                    span.durationMs = Date.now() - startTime;
+                    const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
+                    getMetricsAggregator().recordSpan(endedSpan);
                     return { messages: results, totalMessages: results.length };
                 }
                 catch (error) {
+                    span.durationMs = Date.now() - startTime;
+                    const endedSpan = SpanSerializer.endSpan(span, SpanStatus.ERROR);
+                    endedSpan.statusMessage =
+                        error instanceof Error ? error.message : String(error);
+                    getMetricsAggregator().recordSpan(endedSpan);
                     logger.error("[MemoryRetrievalTools] Error retrieving context", {
                         error: error instanceof Error ? error.message : String(error),
                     });