@juspay/neurolink 9.24.0 → 9.25.1

package/dist/lib/neurolink.d.ts

@@ -10,6 +10,8 @@ import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import type { RedisConversationMemoryManager } from "./core/redisConversationMemoryManager.js";
 import { ExternalServerManager } from "./mcp/externalServerManager.js";
 import { MCPToolRegistry } from "./mcp/toolRegistry.js";
+import type { MetricsSummary, TraceView } from "./observability/metricsAggregator.js";
+import type { SpanData } from "./observability/types/spanTypes.js";
 import type { JsonObject, NeuroLinkEvents, TypedEventEmitter } from "./types/common.js";
 import type { NeurolinkConstructorConfig } from "./types/configTypes.js";
 import type { ChatMessage } from "./types/conversation.js";
@@ -21,78 +23,6 @@ import type { ObservabilityConfig } from "./types/observability.js";
 import type { StreamOptions, StreamResult } from "./types/streamTypes.js";
 import type { ToolExecutionContext, ToolExecutionSummary, ToolInfo } from "./types/tools.js";
 import type { BatchOperationResult } from "./types/typeAliases.js";
-/**
- * NeuroLink - Universal AI Development Platform
- *
- * Main SDK class providing unified access to 14+ AI providers with enterprise features:
- * - Multi-provider support (OpenAI, Anthropic, Google AI Studio, Google Vertex, AWS Bedrock, etc.)
- * - MCP (Model Context Protocol) tool integration with 58+ external servers
- * - Human-in-the-Loop (HITL) security workflows for regulated industries
- * - Redis-based conversation memory and persistence
- * - Enterprise middleware system for monitoring and control
- * - Automatic provider fallback and retry logic
- * - Streaming with real-time token delivery
- * - Multimodal support (text, images, PDFs, CSV)
- *
- * @category Core
- *
- * @example Basic usage
- * ```typescript
- * import { NeuroLink } from '@juspay/neurolink';
- *
- * const neurolink = new NeuroLink();
- *
- * const result = await neurolink.generate({
- *   input: { text: 'Explain quantum computing' },
- *   provider: 'vertex',
- *   model: 'gemini-3-flash'
- * });
- *
- * console.log(result.content);
- * ```
- *
- * @example With HITL security
- * ```typescript
- * const neurolink = new NeuroLink({
- *   hitl: {
- *     enabled: true,
- *     requireApproval: ['writeFile', 'executeCode'],
- *     confidenceThreshold: 0.85
- *   }
- * });
- * ```
- *
- * @example With Redis memory
- * ```typescript
- * const neurolink = new NeuroLink({
- *   conversationMemory: {
- *     enabled: true,
- *     redis: {
- *       url: 'redis://localhost:6379'
- *     }
- *   }
- * });
- * ```
- *
- * @example With MCP tools
- * ```typescript
- * const neurolink = new NeuroLink();
- *
- * // Discover available tools
- * const tools = await neurolink.getAvailableTools();
- *
- * // Use tools in generation
- * const result = await neurolink.generate({
- *   input: { text: 'Read the README.md file' },
- *   tools: ['readFile']
- * });
- * ```
- *
- * @see {@link GenerateOptions} for generation options
- * @see {@link StreamOptions} for streaming options
- * @see {@link NeurolinkConstructorConfig} for configuration options
- * @since 1.0.0
- */
 export declare class NeuroLink {
     private mcpInitialized;
     private mcpInitPromise;
@@ -203,6 +133,13 @@ export declare class NeuroLink {
      * @throws {Error} When HITL configuration is invalid (if enabled)
      */
     private observabilityConfig?;
+    private metricsAggregator;
+    /**
+     * Per-request metrics trace context backed by AsyncLocalStorage.
+     * Safe for concurrent requests on the same SDK instance.
+     * Context is set via metricsTraceContextStorage.run() in generate/stream.
+     */
+    private get _metricsTraceContext();
     constructor(config?: NeurolinkConstructorConfig);
     /**
      * Initialize provider registry with security settings
@@ -385,6 +322,56 @@ export declare class NeuroLink {
      * Centralized utility to avoid duplication across providers
      */
     isTelemetryEnabled(): boolean;
+    /**
+     * Get comprehensive telemetry status including Langfuse, OTel, and exporter health
+     */
+    getTelemetryStatus(): {
+        enabled: boolean;
+        langfuse?: {
+            enabled: boolean;
+            baseUrl?: string;
+            environment?: string;
+        };
+        openTelemetry?: {
+            enabled: boolean;
+            endpoint?: string;
+            serviceName?: string;
+        };
+        exporters?: Array<{
+            name: string;
+            enabled: boolean;
+            healthy: boolean;
+            pendingSpans: number;
+            lastExportTime?: string;
+            latencyMs?: number;
+            errors?: string[];
+        }>;
+    };
+    /**
+     * Get aggregated observability metrics (latency, tokens, cost, success rate)
+     */
+    getMetrics(): MetricsSummary;
+    /**
+     * Get all recorded spans
+     */
+    getSpans(): SpanData[];
+    /**
+     * Get traces (spans grouped by traceId with parent-child hierarchy)
+     */
+    getTraces(): TraceView[];
+    /**
+     * Reset all collected metrics and spans
+     */
+    resetMetrics(): void;
+    /**
+     * Record a span for metrics tracking
+     */
+    recordMetricsSpan(span: SpanData): void;
+    /**
+     * Record a memory operation span to both instance and global metrics aggregators.
+     * This ensures memory spans are visible via sdk.getSpans() and getMetricsAggregator().getSpans().
+     */
+    private recordMemorySpan;
     /**
      * Public method to initialize Langfuse observability
      * This method can be called externally to ensure Langfuse is properly initialized
@@ -394,6 +381,11 @@ export declare class NeuroLink {
      * Gracefully shutdown NeuroLink and all MCP connections
      */
     shutdown(): Promise<void>;
+    /**
+     * Initialize event listeners that feed span data to MetricsAggregator.
+     * Listens to generation:end, stream:complete, and tool:end events.
+     */
+    private initializeMetricsListeners;
     /**
      * Generate AI response with comprehensive feature support.
      *