@juspay/neurolink 7.49.0 → 7.50.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [7.50.0](https://github.com/juspay/neurolink/compare/v7.49.0...v7.50.0) (2025-10-08)
+
+### Features
+
+- **(observability):** add langfuse and telemetry support ([4172d28](https://github.com/juspay/neurolink/commit/4172d283ebce0c6dddae356d278eeceb42aa8464))
+
 ## [7.49.0](https://github.com/juspay/neurolink/compare/v7.48.1...v7.49.0) (2025-10-07)
 
 ### Features

package/dist/cli/factories/commandFactory.d.ts

@@ -156,4 +156,8 @@ export declare class CLICommandFactory {
      * Execute completion command
      */
     private static executeCompletion;
+    /**
+     * Flush Langfuse traces before exit
+     */
+    private static flushLangfuseTraces;
 }

package/dist/cli/factories/commandFactory.js

@@ -1044,6 +1044,7 @@ export class CLICommandFactory {
                     logger.debug("Mode: DRY-RUN (no actual API calls made)");
                 }
                 if (!globalSession.getCurrentSessionId()) {
+                    await this.flushLangfuseTraces();
                     process.exit(0);
                 }
             }
@@ -1120,6 +1121,7 @@ export class CLICommandFactory {
                 }
             }
             if (!globalSession.getCurrentSessionId()) {
+                await this.flushLangfuseTraces();
                 process.exit(0);
             }
         }
@@ -1228,6 +1230,7 @@ export class CLICommandFactory {
             logger.debug("Mode: DRY-RUN (no actual API calls made)");
         }
         if (!globalSession.getCurrentSessionId()) {
+            await this.flushLangfuseTraces();
             process.exit(0);
         }
     }
@@ -1489,6 +1492,7 @@ export class CLICommandFactory {
             const fullContent = await this.executeRealStream(argv, options, inputText, contextMetadata);
             await this.handleStreamOutput(options, fullContent);
             if (!globalSession.getCurrentSessionId()) {
+                await this.flushLangfuseTraces();
                 process.exit(0);
             }
         }
@@ -1610,6 +1614,7 @@ export class CLICommandFactory {
             // Handle output with universal formatting
             this.handleOutput(results, options);
             if (!globalSession.getCurrentSessionId()) {
+                await this.flushLangfuseTraces();
                 process.exit(0);
             }
         }
@@ -2005,4 +2010,18 @@ export class CLICommandFactory {
             handleError(error, "Completion generation");
         }
     }
+    /**
+     * Flush Langfuse traces before exit
+     */
+    static async flushLangfuseTraces() {
+        try {
+            logger.debug("[CLI] Flushing Langfuse traces before exit...");
+            const { flushOpenTelemetry } = await import("../../lib/services/server/ai/observability/instrumentation.js");
+            await flushOpenTelemetry();
+            logger.debug("[CLI] Langfuse traces flushed successfully");
+        }
+        catch (error) {
+            logger.error("[CLI] Error flushing Langfuse traces", { error });
+        }
+    }
 }

package/dist/cli/index.js

@@ -32,17 +32,28 @@ const cli = initializeCliParser();
     try {
         // Parse and execute commands
         await cli.parse();
+        await cleanup();
     }
     catch (error) {
         // Global error handler - should not reach here due to fail() handler
         process.stderr.write(chalk.red(`Unexpected CLI _error: ${error.message}\n`));
+        await cleanup();
         process.exit(1);
     }
 })();
 // Cleanup on exit
-process.on("SIGINT", () => {
+process.on("SIGINT", async () => {
+    await cleanup();
     process.exit(0);
 });
-process.on("SIGTERM", () => {
+process.on("SIGTERM", async () => {
+    await cleanup();
     process.exit(0);
 });
+process.on("beforeExit", async () => {
+    await cleanup();
+});
+async function cleanup() {
+    const { flushOpenTelemetry } = await import("../lib/services/server/ai/observability/instrumentation.js");
+    await flushOpenTelemetry();
+}

package/dist/core/baseProvider.d.ts

@@ -236,4 +236,13 @@ export declare abstract class BaseProvider implements AIProvider {
      * @returns Array of prompt chunks
      */
     static chunkPrompt(prompt: string, maxChunkSize?: number, overlap?: number): string[];
+    /**
+     * Create telemetry configuration for Vercel AI SDK experimental_telemetry
+     * This enables automatic OpenTelemetry tracing when telemetry is enabled
+     */
+    protected getStreamTelemetryConfig(options: StreamOptions | TextGenerationOptions, operationType?: "stream" | "generate"): {
+        isEnabled: boolean;
+        functionId?: string;
+        metadata?: Record<string, string | number | boolean>;
+    } | undefined;
 }

package/dist/core/baseProvider.js

@@ -6,6 +6,8 @@ import { DEFAULT_MAX_STEPS, STEP_LIMITS } from "../core/constants.js";
 import { directAgentTools } from "../agent/directTools.js";
 import { getSafeMaxTokens } from "../utils/tokenLimits.js";
 import { createTimeoutController, TimeoutError } from "../utils/timeout.js";
+import { nanoid } from "nanoid";
+import { createAnalytics } from "./analytics.js";
 import { shouldDisableBuiltinTools } from "../utils/toolUtils.js";
 import { buildMessagesArray, buildMultimodalMessagesArray, } from "../utils/messageBuilder.js";
 import { getKeysAsString, getKeyCount } from "../utils/transformationUtils.js";
@@ -304,6 +306,7 @@ export class BaseProvider {
             toolChoice: shouldUseTools ? "auto" : "none",
             temperature: options.temperature,
             maxTokens: options.maxTokens,
+            experimental_telemetry: this.getStreamTelemetryConfig(options, "generate"),
             onStepFinish: ({ toolCalls, toolResults }) => {
                 logger.info("Tool execution completed", { toolResults, toolCalls });
                 // Handle tool execution storage
@@ -1283,9 +1286,8 @@ export class BaseProvider {
      */
     async createStreamAnalytics(result, startTime, options) {
         try {
-            const { createAnalytics } = await import("./analytics.js");
             const analytics = createAnalytics(this.providerName, this.modelName, result, Date.now() - startTime, {
-                requestId: `${this.providerName}-stream-${Date.now()}`,
+                requestId: `${this.providerName}-stream-${nanoid()}`,
                 streamingMode: true,
                 ...options.context,
             });
@@ -1518,7 +1520,7 @@ export class BaseProvider {
         }
         const sessionId = options.context?.sessionId ||
             options.sessionId ||
-            `session-${Date.now()}`;
+            `session-${nanoid()}`;
         const userId = options.context?.userId ||
             options.userId;
         try {
@@ -1565,4 +1567,35 @@ export class BaseProvider {
         }
         return chunks;
     }
+    /**
+     * Create telemetry configuration for Vercel AI SDK experimental_telemetry
+     * This enables automatic OpenTelemetry tracing when telemetry is enabled
+     */
+    getStreamTelemetryConfig(options, operationType = "stream") {
+        // Check if telemetry is enabled via NeuroLink observability config
+        if (!this.neurolink?.isTelemetryEnabled()) {
+            return undefined;
+        }
+        const functionId = `${this.providerName}-${operationType}-${nanoid()}`;
+        const metadata = {
+            provider: this.providerName,
+            model: this.modelName,
+            toolsEnabled: !options.disableTools,
+            neurolink: true,
+        };
+        // Add sessionId if available
+        if ("sessionId" in options && options.sessionId) {
+            const sessionId = options.sessionId;
+            if (typeof sessionId === "string" ||
+                typeof sessionId === "number" ||
+                typeof sessionId === "boolean") {
+                metadata.sessionId = sessionId;
+            }
+        }
+        return {
+            isEnabled: true,
+            functionId,
+            metadata,
+        };
+    }
 }

package/dist/index.d.ts

@@ -21,6 +21,9 @@ import { NeuroLink } from "./neurolink.js";
 export { NeuroLink };
 export type { ProviderStatus, MCPStatus } from "./neurolink.js";
 export type { MCPServerInfo } from "./types/mcpTypes.js";
+export type { ObservabilityConfig, LangfuseConfig, OpenTelemetryConfig, } from "./types/observability.js";
+import { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus } from "./services/server/ai/observability/instrumentation.js";
+export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, };
 export type { NeuroLinkMiddleware, MiddlewareContext, MiddlewareFactoryOptions, MiddlewarePreset, MiddlewareConfig, } from "./types/middlewareTypes.js";
 export { MiddlewareFactory } from "./middleware/factory.js";
 export declare const VERSION = "1.0.0";
@@ -82,10 +85,13 @@ export declare function createBestAIProvider(requestedProvider?: string, modelNa
 export { initializeMCPEcosystem, listMCPs, executeMCP, getMCPStats, mcpLogger, } from "./mcp/index.js";
 export type { McpMetadata, ExecutionContext, DiscoveredMcp, ToolInfo, ToolExecutionResult, LogLevel, } from "./mcp/index.js";
 export declare function initializeTelemetry(): Promise<boolean>;
-export declare function getTelemetryStatus(): {
+export declare function getTelemetryStatus(): Promise<{
     enabled: boolean;
     initialized: boolean;
-};
+    endpoint?: string;
+    service?: string;
+    version?: string;
+}>;
 export type { TextGenerationOptions, TextGenerationResult, AnalyticsData, EvaluationData, } from "./types/index.js";
 /**
  * BACKWARD COMPATIBILITY: Legacy generateText function

package/dist/index.js

@@ -19,6 +19,9 @@ export { dynamicModelProvider } from "./core/dynamicModels.js";
 // Main NeuroLink wrapper class and diagnostic types
 import { NeuroLink } from "./neurolink.js";
 export { NeuroLink };
+import { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, } from "./services/server/ai/observability/instrumentation.js";
+import { initializeTelemetry as init, getTelemetryStatus as getStatus, } from "./telemetry/index.js";
+export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, };
 export { MiddlewareFactory } from "./middleware/factory.js";
 // Version
 export const VERSION = "1.0.0";
@@ -96,20 +99,18 @@ initializeMCPEcosystem, listMCPs, executeMCP, getMCPStats, mcpLogger, } from "./
 // Real-time Services (Phase 1) - Basic SSE functionality only
 // export { createEnhancedChatService } from './chat/index.js';
 // export type * from './services/types.js';
-// Optional Telemetry (Phase 2) - Conditional export based on feature flag
+// Optional Telemetry (Phase 2) - Telemetry service initialization
 export async function initializeTelemetry() {
-    if (process.env.NEUROLINK_TELEMETRY_ENABLED === "true") {
-        const { initializeTelemetry: init } = await import("./telemetry/index.js");
+    try {
         const result = await init();
-        return !!result; // Convert TelemetryService to boolean
+        return !!result;
     }
-    return Promise.resolve(false);
-}
-export function getTelemetryStatus() {
-    if (process.env.NEUROLINK_TELEMETRY_ENABLED === "true") {
-        return { enabled: true, initialized: false };
+    catch {
+        return false;
     }
-    return { enabled: false, initialized: false };
+}
+export async function getTelemetryStatus() {
+    return getStatus();
 }
 /**
  * BACKWARD COMPATIBILITY: Legacy generateText function

package/dist/lib/core/baseProvider.d.ts

@@ -236,4 +236,13 @@ export declare abstract class BaseProvider implements AIProvider {
      * @returns Array of prompt chunks
      */
     static chunkPrompt(prompt: string, maxChunkSize?: number, overlap?: number): string[];
+    /**
+     * Create telemetry configuration for Vercel AI SDK experimental_telemetry
+     * This enables automatic OpenTelemetry tracing when telemetry is enabled
+     */
+    protected getStreamTelemetryConfig(options: StreamOptions | TextGenerationOptions, operationType?: "stream" | "generate"): {
+        isEnabled: boolean;
+        functionId?: string;
+        metadata?: Record<string, string | number | boolean>;
+    } | undefined;
 }

package/dist/lib/core/baseProvider.js

@@ -6,6 +6,8 @@ import { DEFAULT_MAX_STEPS, STEP_LIMITS } from "../core/constants.js";
 import { directAgentTools } from "../agent/directTools.js";
 import { getSafeMaxTokens } from "../utils/tokenLimits.js";
 import { createTimeoutController, TimeoutError } from "../utils/timeout.js";
+import { nanoid } from "nanoid";
+import { createAnalytics } from "./analytics.js";
 import { shouldDisableBuiltinTools } from "../utils/toolUtils.js";
 import { buildMessagesArray, buildMultimodalMessagesArray, } from "../utils/messageBuilder.js";
 import { getKeysAsString, getKeyCount } from "../utils/transformationUtils.js";
@@ -304,6 +306,7 @@ export class BaseProvider {
             toolChoice: shouldUseTools ? "auto" : "none",
             temperature: options.temperature,
             maxTokens: options.maxTokens,
+            experimental_telemetry: this.getStreamTelemetryConfig(options, "generate"),
             onStepFinish: ({ toolCalls, toolResults }) => {
                 logger.info("Tool execution completed", { toolResults, toolCalls });
                 // Handle tool execution storage
@@ -1283,9 +1286,8 @@ export class BaseProvider {
      */
     async createStreamAnalytics(result, startTime, options) {
         try {
-            const { createAnalytics } = await import("./analytics.js");
             const analytics = createAnalytics(this.providerName, this.modelName, result, Date.now() - startTime, {
-                requestId: `${this.providerName}-stream-${Date.now()}`,
+                requestId: `${this.providerName}-stream-${nanoid()}`,
                 streamingMode: true,
                 ...options.context,
             });
@@ -1518,7 +1520,7 @@ export class BaseProvider {
         }
         const sessionId = options.context?.sessionId ||
             options.sessionId ||
-            `session-${Date.now()}`;
+            `session-${nanoid()}`;
         const userId = options.context?.userId ||
             options.userId;
         try {
@@ -1565,4 +1567,35 @@ export class BaseProvider {
         }
         return chunks;
     }
+    /**
+     * Create telemetry configuration for Vercel AI SDK experimental_telemetry
+     * This enables automatic OpenTelemetry tracing when telemetry is enabled
+     */
+    getStreamTelemetryConfig(options, operationType = "stream") {
+        // Check if telemetry is enabled via NeuroLink observability config
+        if (!this.neurolink?.isTelemetryEnabled()) {
+            return undefined;
+        }
+        const functionId = `${this.providerName}-${operationType}-${nanoid()}`;
+        const metadata = {
+            provider: this.providerName,
+            model: this.modelName,
+            toolsEnabled: !options.disableTools,
+            neurolink: true,
+        };
+        // Add sessionId if available
+        if ("sessionId" in options && options.sessionId) {
+            const sessionId = options.sessionId;
+            if (typeof sessionId === "string" ||
+                typeof sessionId === "number" ||
+                typeof sessionId === "boolean") {
+                metadata.sessionId = sessionId;
+            }
+        }
+        return {
+            isEnabled: true,
+            functionId,
+            metadata,
+        };
+    }
 }

package/dist/lib/index.d.ts

@@ -21,6 +21,9 @@ import { NeuroLink } from "./neurolink.js";
 export { NeuroLink };
 export type { ProviderStatus, MCPStatus } from "./neurolink.js";
 export type { MCPServerInfo } from "./types/mcpTypes.js";
+export type { ObservabilityConfig, LangfuseConfig, OpenTelemetryConfig, } from "./types/observability.js";
+import { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus } from "./services/server/ai/observability/instrumentation.js";
+export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, };
 export type { NeuroLinkMiddleware, MiddlewareContext, MiddlewareFactoryOptions, MiddlewarePreset, MiddlewareConfig, } from "./types/middlewareTypes.js";
 export { MiddlewareFactory } from "./middleware/factory.js";
 export declare const VERSION = "1.0.0";
@@ -82,10 +85,13 @@ export declare function createBestAIProvider(requestedProvider?: string, modelNa
 export { initializeMCPEcosystem, listMCPs, executeMCP, getMCPStats, mcpLogger, } from "./mcp/index.js";
 export type { McpMetadata, ExecutionContext, DiscoveredMcp, ToolInfo, ToolExecutionResult, LogLevel, } from "./mcp/index.js";
 export declare function initializeTelemetry(): Promise<boolean>;
-export declare function getTelemetryStatus(): {
+export declare function getTelemetryStatus(): Promise<{
     enabled: boolean;
     initialized: boolean;
-};
+    endpoint?: string;
+    service?: string;
+    version?: string;
+}>;
 export type { TextGenerationOptions, TextGenerationResult, AnalyticsData, EvaluationData, } from "./types/index.js";
 /**
  * BACKWARD COMPATIBILITY: Legacy generateText function

package/dist/lib/index.js

@@ -19,6 +19,9 @@ export { dynamicModelProvider } from "./core/dynamicModels.js";
 // Main NeuroLink wrapper class and diagnostic types
 import { NeuroLink } from "./neurolink.js";
 export { NeuroLink };
+import { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, } from "./services/server/ai/observability/instrumentation.js";
+import { initializeTelemetry as init, getTelemetryStatus as getStatus, } from "./telemetry/index.js";
+export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, };
 export { MiddlewareFactory } from "./middleware/factory.js";
 // Version
 export const VERSION = "1.0.0";
@@ -96,20 +99,18 @@ initializeMCPEcosystem, listMCPs, executeMCP, getMCPStats, mcpLogger, } from "./
 // Real-time Services (Phase 1) - Basic SSE functionality only
 // export { createEnhancedChatService } from './chat/index.js';
 // export type * from './services/types.js';
-// Optional Telemetry (Phase 2) - Conditional export based on feature flag
+// Optional Telemetry (Phase 2) - Telemetry service initialization
 export async function initializeTelemetry() {
-    if (process.env.NEUROLINK_TELEMETRY_ENABLED === "true") {
-        const { initializeTelemetry: init } = await import("./telemetry/index.js");
+    try {
         const result = await init();
-        return !!result; // Convert TelemetryService to boolean
+        return !!result;
     }
-    return Promise.resolve(false);
-}
-export function getTelemetryStatus() {
-    if (process.env.NEUROLINK_TELEMETRY_ENABLED === "true") {
-        return { enabled: true, initialized: false };
+    catch {
+        return false;
     }
-    return { enabled: false, initialized: false };
+}
+export async function getTelemetryStatus() {
+    return getStatus();
 }
 /**
  * BACKWARD COMPATIBILITY: Legacy generateText function

package/dist/lib/neurolink.d.ts

@@ -19,6 +19,17 @@ import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import { RedisConversationMemoryManager } from "./core/redisConversationMemoryManager.js";
 import type { HITLConfig } from "./hitl/types.js";
 import type { ExternalMCPServerInstance, ExternalMCPOperationResult, ExternalMCPToolInfo } from "./types/externalMcp.js";
+import type { ObservabilityConfig } from "./types/observability.js";
+/**
+ * Configuration object for NeuroLink constructor.
+ */
+export interface NeurolinkConstructorConfig {
+    conversationMemory?: Partial<ConversationMemoryConfig>;
+    enableOrchestration?: boolean;
+    hitl?: HITLConfig;
+    toolRegistry?: MCPToolRegistry;
+    observability?: ObservabilityConfig;
+}
 export interface ProviderStatus {
     provider: string;
     status: "working" | "failed" | "not-configured";
@@ -138,12 +149,8 @@ export declare class NeuroLink {
      * @throws {Error} When external server manager initialization fails
      * @throws {Error} When HITL configuration is invalid (if enabled)
      */
-    constructor(config?: {
-        conversationMemory?: Partial<ConversationMemoryConfig>;
-        enableOrchestration?: boolean;
-        hitl?: HITLConfig;
-        toolRegistry?: MCPToolRegistry;
-    });
+    private observabilityConfig?;
+    constructor(config?: NeurolinkConstructorConfig);
     /**
      * Initialize provider registry with security settings
      */
@@ -170,6 +177,10 @@ export declare class NeuroLink {
      * Setup event handlers for external server manager
      */
     private setupExternalServerEventHandlers;
+    /**
+     * Initialize Langfuse observability for AI operations tracking
+     */
+    private initializeLangfuse;
     /**
      * Log constructor completion with final state summary
      */
@@ -279,6 +290,24 @@ export declare class NeuroLink {
      * @throws {Error} When all providers fail to generate content
      * @throws {Error} When conversation memory operations fail (if enabled)
      */
+    /**
+     * Get observability configuration
+     */
+    getObservabilityConfig(): ObservabilityConfig | undefined;
+    /**
+     * Check if Langfuse telemetry is enabled
+     * Centralized utility to avoid duplication across providers
+     */
+    isTelemetryEnabled(): boolean;
+    /**
+     * Public method to initialize Langfuse observability
+     * This method can be called externally to ensure Langfuse is properly initialized
+     */
+    initializeLangfuseObservability(): Promise<void>;
+    /**
+     * Gracefully shutdown NeuroLink and all MCP connections
+     */
+    shutdown(): Promise<void>;
     generate(optionsOrPrompt: GenerateOptions | string): Promise<GenerateResult>;
     /**
      * BACKWARD COMPATIBILITY: Legacy generateText method

package/dist/lib/neurolink.js

@@ -39,6 +39,7 @@ import { directToolsServer } from "./mcp/servers/agent/directToolsServer.js";
 // Import orchestration components
 import { ModelRouter } from "./utils/modelRouter.js";
 import { BinaryTaskClassifier } from "./utils/taskClassifier.js";
+import { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, } from "./services/server/ai/observability/instrumentation.js";
 import { isNonNullObject } from "./utils/typeUtils.js";
 import { isZodSchema } from "./utils/schemaConversion.js";
 // Core types imported from "./types/index.js"
@@ -178,8 +179,10 @@ export class NeuroLink {
      * @throws {Error} When external server manager initialization fails
      * @throws {Error} When HITL configuration is invalid (if enabled)
      */
+    observabilityConfig;
     constructor(config) {
         this.toolRegistry = config?.toolRegistry || new MCPToolRegistry();
+        this.observabilityConfig = config?.observability;
         // Initialize orchestration setting
         this.enableOrchestration = config?.enableOrchestration ?? false;
         // Read tool cache duration from environment variables, with a default
@@ -194,6 +197,7 @@ export class NeuroLink {
         this.initializeConversationMemory(config, constructorId, constructorStartTime, constructorHrTimeStart);
         this.initializeExternalServerManager(constructorId, constructorStartTime, constructorHrTimeStart);
         this.initializeHITL(config, constructorId, constructorStartTime, constructorHrTimeStart);
+        this.initializeLangfuse(constructorId, constructorStartTime, constructorHrTimeStart);
         this.logConstructorComplete(constructorId, constructorStartTime, constructorHrTimeStart);
     }
     /**
@@ -494,6 +498,81 @@ export class NeuroLink {
             this.unregisterExternalMCPToolFromRegistry(event.toolName);
         });
     }
+    /**
+     * Initialize Langfuse observability for AI operations tracking
+     */
+    initializeLangfuse(constructorId, constructorStartTime, constructorHrTimeStart) {
+        const langfuseInitStartTime = process.hrtime.bigint();
+        try {
+            const langfuseConfig = this.observabilityConfig?.langfuse;
+            if (langfuseConfig?.enabled) {
+                logger.debug(`[NeuroLink] 📊 LOG_POINT_C019_LANGFUSE_INIT_START`, {
+                    logPoint: "C019_LANGFUSE_INIT_START",
+                    constructorId,
+                    timestamp: new Date().toISOString(),
+                    elapsedMs: Date.now() - constructorStartTime,
+                    elapsedNs: (process.hrtime.bigint() - constructorHrTimeStart).toString(),
+                    langfuseInitStartTimeNs: langfuseInitStartTime.toString(),
+                    message: "Starting Langfuse observability initialization",
+                });
+                // Initialize OpenTelemetry FIRST (required for Langfuse v4)
+                initializeOpenTelemetry(langfuseConfig);
+                const healthStatus = getLangfuseHealthStatus();
+                const langfuseInitDurationNs = process.hrtime.bigint() - langfuseInitStartTime;
+                if (healthStatus.initialized &&
+                    healthStatus.hasProcessor &&
+                    healthStatus.isHealthy) {
+                    logger.debug(`[NeuroLink] ✅ LOG_POINT_C020_LANGFUSE_INIT_SUCCESS`, {
+                        logPoint: "C020_LANGFUSE_INIT_SUCCESS",
+                        constructorId,
+                        timestamp: new Date().toISOString(),
+                        elapsedMs: Date.now() - constructorStartTime,
+                        elapsedNs: (process.hrtime.bigint() - constructorHrTimeStart).toString(),
+                        langfuseInitDurationNs: langfuseInitDurationNs.toString(),
+                        langfuseInitDurationMs: Number(langfuseInitDurationNs) / 1_000_000,
+                        healthStatus,
+                        message: "Langfuse observability initialized successfully",
+                    });
+                }
+                else {
+                    logger.warn(`[NeuroLink] ⚠️ LOG_POINT_C021_LANGFUSE_INIT_WARNING`, {
+                        logPoint: "C021_LANGFUSE_INIT_WARNING",
+                        constructorId,
+                        timestamp: new Date().toISOString(),
+                        elapsedMs: Date.now() - constructorStartTime,
+                        elapsedNs: (process.hrtime.bigint() - constructorHrTimeStart).toString(),
+                        langfuseInitDurationNs: langfuseInitDurationNs.toString(),
+                        healthStatus,
+                        message: "Langfuse initialized but not healthy",
+                    });
+                }
+            }
+            else {
+                logger.debug(`[NeuroLink] 🚫 LOG_POINT_C022_LANGFUSE_DISABLED`, {
+                    logPoint: "C022_LANGFUSE_DISABLED",
+                    constructorId,
+                    timestamp: new Date().toISOString(),
+                    elapsedMs: Date.now() - constructorStartTime,
+                    elapsedNs: (process.hrtime.bigint() - constructorHrTimeStart).toString(),
+                    message: "Langfuse observability not enabled - skipping initialization",
+                });
+            }
+        }
+        catch (error) {
+            const langfuseInitErrorDurationNs = process.hrtime.bigint() - langfuseInitStartTime;
+            logger.error(`[NeuroLink] ❌ LOG_POINT_C023_LANGFUSE_INIT_ERROR`, {
+                logPoint: "C023_LANGFUSE_INIT_ERROR",
+                constructorId,
+                timestamp: new Date().toISOString(),
+                elapsedMs: Date.now() - constructorStartTime,
+                elapsedNs: (process.hrtime.bigint() - constructorHrTimeStart).toString(),
+                langfuseInitDurationNs: langfuseInitErrorDurationNs.toString(),
+                errorMessage: error instanceof Error ? error.message : String(error),
+                errorStack: error instanceof Error ? error.stack : undefined,
+                message: "Langfuse observability initialization failed",
+            });
+        }
+    }
     /**
      * Log constructor completion with final state summary
      */
@@ -992,6 +1071,68 @@ export class NeuroLink {
      * @throws {Error} When all providers fail to generate content
      * @throws {Error} When conversation memory operations fail (if enabled)
      */
+    /**
+     * Get observability configuration
+     */
+    getObservabilityConfig() {
+        return this.observabilityConfig;
+    }
+    /**
+     * Check if Langfuse telemetry is enabled
+     * Centralized utility to avoid duplication across providers
+     */
+    isTelemetryEnabled() {
+        return this.observabilityConfig?.langfuse?.enabled || false;
+    }
+    /**
+     * Public method to initialize Langfuse observability
+     * This method can be called externally to ensure Langfuse is properly initialized
+     */
+    async initializeLangfuseObservability() {
+        try {
+            const langfuseConfig = this.observabilityConfig?.langfuse;
+            if (langfuseConfig?.enabled) {
+                initializeOpenTelemetry(langfuseConfig);
+                logger.debug("[NeuroLink] Langfuse observability initialized via public method");
+            }
+            else {
+                logger.debug("[NeuroLink] Langfuse not enabled, skipping initialization");
+            }
+        }
+        catch (error) {
+            logger.warn("[NeuroLink] Failed to initialize Langfuse observability:", error);
+        }
+    }
+    /**
+     * Gracefully shutdown NeuroLink and all MCP connections
+     */
+    async shutdown() {
+        try {
+            logger.debug("[NeuroLink] Starting graceful shutdown");
+            try {
+                await flushOpenTelemetry();
+                await shutdownOpenTelemetry();
+                logger.debug("[NeuroLink] OpenTelemetry shutdown completed");
+            }
+            catch (error) {
+                logger.warn("[NeuroLink] OpenTelemetry shutdown failed:", error);
+            }
+            if (this.externalServerManager) {
+                try {
+                    await this.externalServerManager.shutdown();
+                    logger.debug("[NeuroLink] MCP servers shutdown completed");
+                }
+                catch (error) {
+                    logger.warn("[NeuroLink] MCP servers shutdown failed:", error);
+                }
+            }
+            logger.debug("[NeuroLink] Graceful shutdown completed");
+        }
+        catch (error) {
+            logger.error("[NeuroLink] Shutdown failed:", error);
+            throw error;
+        }
+    }
     async generate(optionsOrPrompt) {
         const originalPrompt = this._extractOriginalPrompt(optionsOrPrompt);
         // Convert string prompt to full options