@juspay/neurolink 7.49.0 → 7.50.0

package/dist/lib/providers/anthropic.js

@@ -147,6 +147,7 @@ export class AnthropicProvider extends BaseProvider {
                 maxSteps: options.maxSteps || DEFAULT_MAX_STEPS,
                 toolChoice: shouldUseTools ? "auto" : "none",
                 abortSignal: timeoutController?.controller.signal,
+                experimental_telemetry: this.getStreamTelemetryConfig(options),
                 onStepFinish: ({ toolCalls, toolResults }) => {
                     this.handleToolExecutionStorage(toolCalls, toolResults, options, new Date()).catch((error) => {
                         logger.warn("[AnthropicProvider] Failed to store tool executions", {

package/dist/lib/providers/azureOpenai.js

@@ -162,6 +162,7 @@ export class AzureOpenAIProvider extends BaseProvider {
                     : {}),
                 tools,
                 toolChoice: shouldUseTools ? "auto" : "none",
+                experimental_telemetry: this.getStreamTelemetryConfig(options),
                 onStepFinish: ({ toolCalls, toolResults }) => {
                     this.handleToolExecutionStorage(toolCalls, toolResults, options, new Date()).catch((error) => {
                         logger.warn("[AzureOpenaiProvider] Failed to store tool executions", {

package/dist/lib/providers/googleAiStudio.js

@@ -141,6 +141,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                 maxSteps: options.maxSteps || DEFAULT_MAX_STEPS,
                 toolChoice: shouldUseTools ? "auto" : "none",
                 abortSignal: timeoutController?.controller.signal,
+                experimental_telemetry: this.getStreamTelemetryConfig(options),
                 onStepFinish: ({ toolCalls, toolResults }) => {
                     this.handleToolExecutionStorage(toolCalls, toolResults, options, new Date()).catch((error) => {
                         logger.warn("[GoogleAiStudioProvider] Failed to store tool executions", {

package/dist/lib/providers/googleVertex.js

@@ -666,6 +666,7 @@ export class GoogleVertexProvider extends BaseProvider {
                     maxSteps: options.maxSteps || DEFAULT_MAX_STEPS,
                 }),
                 abortSignal: timeoutController?.controller.signal,
+                experimental_telemetry: this.getStreamTelemetryConfig(options),
                 onError: (event) => {
                     const error = event.error;
                     const errorMessage = error instanceof Error ? error.message : String(error);

package/dist/lib/providers/openAI.js

@@ -316,6 +316,7 @@ export class OpenAIProvider extends BaseProvider {
                 maxSteps: options.maxSteps || DEFAULT_MAX_STEPS,
                 toolChoice: shouldUseTools && Object.keys(tools).length > 0 ? "auto" : "none",
                 abortSignal: timeoutController?.controller.signal,
+                experimental_telemetry: this.getStreamTelemetryConfig(options),
                 onStepFinish: ({ toolCalls, toolResults }) => {
                     logger.info("Tool execution completed", { toolResults, toolCalls });
                     // Handle tool execution storage

package/dist/lib/services/server/ai/observability/instrumentation.d.ts

@@ -0,0 +1,57 @@
+/**
+ * OpenTelemetry Instrumentation for Langfuse v4
+ *
+ * Configures OpenTelemetry TracerProvider with LangfuseSpanProcessor to capture
+ * traces from Vercel AI SDK's experimental_telemetry feature.
+ *
+ * Flow: Vercel AI SDK → OpenTelemetry Spans → LangfuseSpanProcessor → Langfuse Platform
+ */
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { LangfuseSpanProcessor } from "@langfuse/otel";
+import type { LangfuseConfig } from "../../../../types/observability.js";
+/**
+ * Initialize OpenTelemetry with Langfuse span processor
+ *
+ * This connects Vercel AI SDK's experimental_telemetry to Langfuse by:
+ * 1. Creating LangfuseSpanProcessor with Langfuse credentials
+ * 2. Creating a NodeTracerProvider with service metadata and span processor
+ * 3. Registering the provider globally for AI SDK to use
+ *
+ * @param config - Langfuse configuration passed from parent application
+ */
+export declare function initializeOpenTelemetry(config: LangfuseConfig): void;
+/**
+ * Flush all pending spans to Langfuse
+ */
+export declare function flushOpenTelemetry(): Promise<void>;
+/**
+ * Shutdown OpenTelemetry and Langfuse span processor
+ */
+export declare function shutdownOpenTelemetry(): Promise<void>;
+/**
+ * Get the Langfuse span processor
+ */
+export declare function getLangfuseSpanProcessor(): LangfuseSpanProcessor | null;
+/**
+ * Get the tracer provider
+ */
+export declare function getTracerProvider(): NodeTracerProvider | null;
+/**
+ * Check if OpenTelemetry is initialized
+ */
+export declare function isOpenTelemetryInitialized(): boolean;
+/**
+ * Get health status for Langfuse observability
+ */
+export declare function getLangfuseHealthStatus(): {
+    isHealthy: boolean | undefined;
+    initialized: boolean;
+    credentialsValid: boolean;
+    enabled: boolean;
+    hasProcessor: boolean;
+    config: {
+        baseUrl: string;
+        environment: string;
+        release: string;
+    } | undefined;
+};

package/dist/lib/services/server/ai/observability/instrumentation.js

@@ -0,0 +1,170 @@
+/**
+ * OpenTelemetry Instrumentation for Langfuse v4
+ *
+ * Configures OpenTelemetry TracerProvider with LangfuseSpanProcessor to capture
+ * traces from Vercel AI SDK's experimental_telemetry feature.
+ *
+ * Flow: Vercel AI SDK → OpenTelemetry Spans → LangfuseSpanProcessor → Langfuse Platform
+ */
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { LangfuseSpanProcessor } from "@langfuse/otel";
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } from "@opentelemetry/semantic-conventions";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { logger } from "../../../../utils/logger.js";
+const LOG_PREFIX = "[OpenTelemetry]";
+let tracerProvider = null;
+let langfuseProcessor = null;
+let isInitialized = false;
+let isCredentialsValid = false;
+let currentConfig = null;
+/**
+ * Initialize OpenTelemetry with Langfuse span processor
+ *
+ * This connects Vercel AI SDK's experimental_telemetry to Langfuse by:
+ * 1. Creating LangfuseSpanProcessor with Langfuse credentials
+ * 2. Creating a NodeTracerProvider with service metadata and span processor
+ * 3. Registering the provider globally for AI SDK to use
+ *
+ * @param config - Langfuse configuration passed from parent application
+ */
+export function initializeOpenTelemetry(config) {
+    if (isInitialized) {
+        logger.debug(`${LOG_PREFIX} Already initialized`);
+        return;
+    }
+    if (!config.enabled) {
+        logger.debug(`${LOG_PREFIX} Langfuse disabled, skipping initialization`);
+        isInitialized = true;
+        return;
+    }
+    if (!config.publicKey || !config.secretKey) {
+        logger.warn(`${LOG_PREFIX} Langfuse enabled but missing credentials, skipping initialization`);
+        isInitialized = true;
+        isCredentialsValid = false;
+        return;
+    }
+    try {
+        currentConfig = config;
+        isCredentialsValid = true;
+        // Create Langfuse span processor with configuration
+        langfuseProcessor = new LangfuseSpanProcessor({
+            publicKey: config.publicKey,
+            secretKey: config.secretKey,
+            baseUrl: config.baseUrl || "https://cloud.langfuse.com",
+            environment: config.environment || "dev",
+            release: config.release || "v1.0.0",
+        });
+        // Create resource with service metadata (v2.x API)
+        const resource = resourceFromAttributes({
+            [ATTR_SERVICE_NAME]: "neurolink",
+            [ATTR_SERVICE_VERSION]: config.release || "v1.0.0",
+            "deployment.environment": config.environment || "dev",
+        });
+        // Initialize tracer provider with span processor and resource
+        tracerProvider = new NodeTracerProvider({
+            resource,
+            spanProcessors: [langfuseProcessor],
+        });
+        // Register provider globally so Vercel AI SDK can use it
+        tracerProvider.register();
+        isInitialized = true;
+        logger.info(`${LOG_PREFIX} Initialized with Langfuse span processor`, {
+            baseUrl: config.baseUrl || "https://cloud.langfuse.com",
+            environment: config.environment || "dev",
+            release: config.release || "v1.0.0",
+        });
+    }
+    catch (error) {
+        logger.error(`${LOG_PREFIX} Initialization failed`, {
+            error: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : undefined,
+        });
+        throw error;
+    }
+}
+/**
+ * Flush all pending spans to Langfuse
+ */
+export async function flushOpenTelemetry() {
+    if (!isInitialized) {
+        logger.debug(`${LOG_PREFIX} Not initialized, skipping flush`);
+        return;
+    }
+    if (!langfuseProcessor) {
+        logger.debug(`${LOG_PREFIX} No processor to flush (Langfuse disabled)`);
+        return;
+    }
+    try {
+        logger.info(`${LOG_PREFIX} Flushing pending spans to Langfuse...`);
+        await langfuseProcessor.forceFlush();
+        logger.info(`${LOG_PREFIX} Successfully flushed spans to Langfuse`);
+    }
+    catch (error) {
+        logger.error(`${LOG_PREFIX} Flush failed`, {
+            error: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : undefined,
+        });
+        throw error;
+    }
+}
+/**
+ * Shutdown OpenTelemetry and Langfuse span processor
+ */
+export async function shutdownOpenTelemetry() {
+    if (!isInitialized || !tracerProvider) {
+        return;
+    }
+    try {
+        await tracerProvider.shutdown();
+        tracerProvider = null;
+        langfuseProcessor = null;
+        isInitialized = false;
+        isCredentialsValid = false;
+        logger.debug(`${LOG_PREFIX} Shutdown complete`);
+    }
+    catch (error) {
+        logger.error(`${LOG_PREFIX} Shutdown failed`, {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Get the Langfuse span processor
+ */
+export function getLangfuseSpanProcessor() {
+    return langfuseProcessor;
+}
+/**
+ * Get the tracer provider
+ */
+export function getTracerProvider() {
+    return tracerProvider;
+}
+/**
+ * Check if OpenTelemetry is initialized
+ */
+export function isOpenTelemetryInitialized() {
+    return isInitialized;
+}
+/**
+ * Get health status for Langfuse observability
+ */
+export function getLangfuseHealthStatus() {
+    return {
+        isHealthy: currentConfig?.enabled &&
+            isInitialized &&
+            isCredentialsValid &&
+            langfuseProcessor !== null,
+        initialized: isInitialized,
+        credentialsValid: isCredentialsValid,
+        enabled: currentConfig?.enabled || false,
+        hasProcessor: langfuseProcessor !== null,
+        config: currentConfig
+            ? {
+                baseUrl: currentConfig.baseUrl || "https://cloud.langfuse.com",
+                environment: currentConfig.environment || "dev",
+                release: currentConfig.release || "v1.0.0",
+            }
+            : undefined,
+    };
+}

package/dist/lib/session/globalSessionState.js

@@ -1,5 +1,31 @@
 import { nanoid } from "nanoid";
 import { NeuroLink } from "../neurolink.js";
+/**
+ * Build observability config from environment variables
+ * Used by CLI to configure NeuroLink instances
+ */
+function buildObservabilityConfigFromEnv() {
+    const langfuseEnabled = process.env.LANGFUSE_ENABLED?.trim().toLowerCase() === "true";
+    const publicKey = process.env.LANGFUSE_PUBLIC_KEY?.trim();
+    const secretKey = process.env.LANGFUSE_SECRET_KEY?.trim();
+    if (!langfuseEnabled || !publicKey || !secretKey) {
+        return undefined;
+    }
+    return {
+        langfuse: {
+            enabled: langfuseEnabled,
+            publicKey,
+            secretKey,
+            baseUrl: process.env.LANGFUSE_BASE_URL?.trim() || "https://cloud.langfuse.com",
+            environment: process.env.LANGFUSE_ENVIRONMENT?.trim() ||
+                process.env.PUBLIC_APP_ENVIRONMENT?.trim() ||
+                "dev",
+            release: process.env.PUBLIC_APP_VERSION?.trim() ||
+                process.env.npm_package_version?.trim() ||
+                "v1.0.0",
+        },
+    };
+}
 export class GlobalSessionManager {
     static instance;
     loopSession = null;
@@ -19,6 +45,11 @@ export class GlobalSessionManager {
                 maxTurnsPerSession: config.maxTurnsPerSession,
             };
         }
+        // Add observability config from environment variables (CLI usage)
+        const observabilityConfig = buildObservabilityConfigFromEnv();
+        if (observabilityConfig) {
+            neurolinkOptions.observability = observabilityConfig;
+        }
         this.loopSession = {
             neurolinkInstance: new NeuroLink(neurolinkOptions),
             sessionId,
@@ -88,7 +119,12 @@ export class GlobalSessionManager {
     }
     getOrCreateNeuroLink() {
         const session = this.getLoopSession();
-        return session ? session.neurolinkInstance : new NeuroLink();
+        if (session) {
+            return session.neurolinkInstance;
+        }
+        // Create new NeuroLink with observability config from environment (CLI usage)
+        const observabilityConfig = buildObservabilityConfigFromEnv();
+        return new NeuroLink(observabilityConfig ? { observability: observabilityConfig } : undefined);
     }
     getCurrentSessionId() {
         return this.getLoopSession()?.sessionId;

package/dist/lib/telemetry/index.d.ts

@@ -9,6 +9,7 @@ export declare function initializeTelemetry(): Promise<import("./telemetryServic
  */
 export declare function getTelemetryStatus(): Promise<{
     enabled: boolean;
+    initialized: boolean;
     endpoint?: string;
     service?: string;
     version?: string;

package/dist/lib/telemetry/telemetryService.d.ts

@@ -10,6 +10,7 @@ export declare class TelemetryService {
     private static instance;
     private sdk?;
     private enabled;
+    private initialized;
     private meter?;
     private tracer?;
     private aiRequestCounter?;
@@ -43,6 +44,7 @@ export declare class TelemetryService {
     isEnabled(): boolean;
     getStatus(): {
         enabled: boolean;
+        initialized: boolean;
         endpoint?: string;
         service?: string;
         version?: string;

package/dist/lib/telemetry/telemetryService.js

@@ -1,14 +1,14 @@
 import { NodeSDK } from "@opentelemetry/sdk-node";
 import { metrics, trace, } from "@opentelemetry/api";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
-import { Resource } from "@opentelemetry/resources";
+import { resourceFromAttributes } from "@opentelemetry/resources";
 import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } from "@opentelemetry/semantic-conventions";
 import { logger } from "../utils/logger.js";
 export class TelemetryService {
     static instance;
     sdk;
     enabled = false;
+    initialized = false;
     meter;
     tracer;
     // Optional Metrics (only created when enabled)
@@ -47,16 +47,12 @@ export class TelemetryService {
     }
     initializeTelemetry() {
         try {
-            const resource = new Resource({
+            const resource = resourceFromAttributes({
                 [ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME || "neurolink-ai",
                 [ATTR_SERVICE_VERSION]: process.env.OTEL_SERVICE_VERSION || "3.0.1",
             });
             this.sdk = new NodeSDK({
                 resource,
-                traceExporter: new OTLPTraceExporter({
-                    url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ||
-                        `${process.env.OTEL_EXPORTER_OTLP_ENDPOINT}/v1/traces`,
-                }),
                 // Note: Metric reader configured separately
                 instrumentations: [getNodeAutoInstrumentations()],
             });
@@ -102,11 +98,13 @@ export class TelemetryService {
         }
         try {
             await this.sdk?.start();
+            this.initialized = true;
             logger.debug("[Telemetry] SDK started successfully");
         }
         catch (error) {
             logger.error("[Telemetry] Failed to start SDK:", error);
             this.enabled = false;
+            this.initialized = false;
         }
     }
     // AI Operation Tracing (NO-OP when disabled)
@@ -250,6 +248,7 @@ export class TelemetryService {
     getStatus() {
         return {
             enabled: this.enabled,
+            initialized: this.initialized,
             endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
             service: process.env.OTEL_SERVICE_NAME || "neurolink-ai",
             version: process.env.OTEL_SERVICE_VERSION || "3.0.1",
@@ -285,6 +284,7 @@ export class TelemetryService {
         if (this.enabled && this.sdk) {
             try {
                 await this.sdk.shutdown();
+                this.initialized = false;
                 logger.debug("[Telemetry] SDK shutdown completed");
             }
             catch (error) {

package/dist/lib/types/conversation.d.ts

@@ -157,6 +157,8 @@ export interface NeurolinkOptions {
     conversationMemory?: ConversationMemoryConfig;
     /** Session identifier for conversation context */
     sessionId?: string;
+    /** Observability configuration */
+    observability?: import("./observability.js").ObservabilityConfig;
 }
 /**
  * Session identifier for Redis storage operations

package/dist/lib/types/modelTypes.d.ts

@@ -87,8 +87,8 @@ export declare const ModelConfigSchema: z.ZodObject<{
     releaseDate: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     id: string;
-    capabilities: string[];
     displayName: string;
+    capabilities: string[];
     deprecated: boolean;
     pricing: {
         input: number;
@@ -98,8 +98,8 @@ export declare const ModelConfigSchema: z.ZodObject<{
     releaseDate: string;
 }, {
     id: string;
-    capabilities: string[];
     displayName: string;
+    capabilities: string[];
     deprecated: boolean;
     pricing: {
         input: number;
@@ -133,8 +133,8 @@ export declare const ModelRegistrySchema: z.ZodObject<{
         releaseDate: z.ZodString;
     }, "strip", z.ZodTypeAny, {
         id: string;
-        capabilities: string[];
         displayName: string;
+        capabilities: string[];
         deprecated: boolean;
         pricing: {
             input: number;
@@ -144,8 +144,8 @@ export declare const ModelRegistrySchema: z.ZodObject<{
         releaseDate: string;
     }, {
         id: string;
-        capabilities: string[];
         displayName: string;
+        capabilities: string[];
         deprecated: boolean;
         pricing: {
             input: number;
@@ -160,8 +160,8 @@ export declare const ModelRegistrySchema: z.ZodObject<{
     version: string;
     models: Record<string, Record<string, {
         id: string;
-        capabilities: string[];
         displayName: string;
+        capabilities: string[];
         deprecated: boolean;
         pricing: {
             input: number;
@@ -177,8 +177,8 @@ export declare const ModelRegistrySchema: z.ZodObject<{
     version: string;
     models: Record<string, Record<string, {
         id: string;
-        capabilities: string[];
         displayName: string;
+        capabilities: string[];
         deprecated: boolean;
         pricing: {
             input: number;

package/dist/lib/types/observability.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Observability Configuration Types
+ * These configs are passed from the parent application (e.g., Lighthouse)
+ * to enable telemetry and observability features in Neurolink SDK
+ */
+/**
+ * Langfuse observability configuration
+ */
+export interface LangfuseConfig {
+    /** Whether Langfuse is enabled */
+    enabled: boolean;
+    /** Langfuse public key */
+    publicKey: string;
+    /**
+     * Langfuse secret key
+     * @sensitive
+     * WARNING: This is a sensitive credential. Handle securely.
+     * Do NOT log, expose, or share this key. Follow best practices for secret management.
+     */
+    secretKey: string;
+    /** Langfuse base URL (default: https://cloud.langfuse.com) */
+    baseUrl?: string;
+    /** Environment name (e.g., dev, staging, prod) */
+    environment?: string;
+    /** Release/version identifier */
+    release?: string;
+}
+/**
+ * OpenTelemetry configuration
+ */
+export interface OpenTelemetryConfig {
+    /** Whether OpenTelemetry is enabled */
+    enabled: boolean;
+    /** OTLP endpoint URL */
+    endpoint?: string;
+    /** Service name for traces */
+    serviceName?: string;
+    /** Service version */
+    serviceVersion?: string;
+}
+/**
+ * Complete observability configuration for Neurolink SDK
+ */
+export interface ObservabilityConfig {
+    /** Langfuse configuration */
+    langfuse?: LangfuseConfig;
+    /** OpenTelemetry configuration */
+    openTelemetry?: OpenTelemetryConfig;
+}

package/dist/lib/types/observability.js

@@ -0,0 +1,6 @@
+/**
+ * Observability Configuration Types
+ * These configs are passed from the parent application (e.g., Lighthouse)
+ * to enable telemetry and observability features in Neurolink SDK
+ */
+export {};

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