@juspay/neurolink 7.48.1 → 7.50.0

package/dist/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/session/globalSessionState.d.ts

@@ -13,6 +13,32 @@ export declare class GlobalSessionManager {
     private loopSession;
     static getInstance(): GlobalSessionManager;
     setLoopSession(config?: ConversationMemoryConfig): string;
+    /**
+     * Restore a loop session with an existing sessionId and NeuroLink instance
+     * Used for conversation restoration
+     */
+    restoreLoopSession(sessionId: string, neurolinkInstance: NeuroLink, config?: ConversationMemoryConfig, sessionVariables?: Record<string, SessionVariableValue>): void;
+    /**
+     * Update session variables during restoration
+     */
+    restoreSessionVariables(variables: Record<string, SessionVariableValue>): void;
+    /**
+     * Check if a session is currently active
+     */
+    hasActiveSession(): boolean;
+    /**
+     * Get current session metadata for restoration purposes
+     */
+    getSessionMetadata(): {
+        sessionId?: string;
+        conversationMemoryConfig?: ConversationMemoryConfig;
+        sessionVariables: Record<string, SessionVariableValue>;
+        isActive: boolean;
+    };
+    /**
+     * Update the sessionId of the current session (used during restoration)
+     */
+    updateSessionId(newSessionId: string): void;
     getLoopSession(): LoopSessionState | null;
     clearLoopSession(): void;
     getOrCreateNeuroLink(): NeuroLink;

package/dist/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,
@@ -28,6 +59,55 @@ export class GlobalSessionManager {
         };
         return sessionId;
     }
+    /**
+     * Restore a loop session with an existing sessionId and NeuroLink instance
+     * Used for conversation restoration
+     */
+    restoreLoopSession(sessionId, neurolinkInstance, config, sessionVariables) {
+        this.loopSession = {
+            neurolinkInstance,
+            sessionId,
+            isActive: true,
+            conversationMemoryConfig: config,
+            sessionVariables: sessionVariables || {},
+        };
+    }
+    /**
+     * Update session variables during restoration
+     */
+    restoreSessionVariables(variables) {
+        const session = this.getLoopSession();
+        if (session) {
+            session.sessionVariables = { ...session.sessionVariables, ...variables };
+        }
+    }
+    /**
+     * Check if a session is currently active
+     */
+    hasActiveSession() {
+        return this.loopSession?.isActive ?? false;
+    }
+    /**
+     * Get current session metadata for restoration purposes
+     */
+    getSessionMetadata() {
+        const session = this.getLoopSession();
+        return {
+            sessionId: session?.sessionId,
+            conversationMemoryConfig: session?.conversationMemoryConfig,
+            sessionVariables: session?.sessionVariables || {},
+            isActive: session?.isActive ?? false,
+        };
+    }
+    /**
+     * Update the sessionId of the current session (used during restoration)
+     */
+    updateSessionId(newSessionId) {
+        const session = this.getLoopSession();
+        if (session) {
+            session.sessionId = newSessionId;
+        }
+    }
     getLoopSession() {
         return this.loopSession?.isActive ? this.loopSession : null;
     }
@@ -39,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/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/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/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/types/cli.d.ts

@@ -411,6 +411,34 @@ export type JSONOutput = {
 export type ConsoleOverride = {
     [method: string]: (() => void) | undefined;
 };
+/**
+ * Conversation choice for inquirer prompt
+ */
+export type ConversationChoice = {
+    name: string;
+    value: string | "NEW_CONVERSATION";
+    short: string;
+};
+/**
+ * Session restore result
+ */
+export type SessionRestoreResult = {
+    success: boolean;
+    sessionId: string;
+    messageCount: number;
+    error?: string;
+    lastActivity?: string;
+};
+/**
+ * Tool context for restored sessions
+ */
+export type RestorationToolContext = Record<string, unknown> & {
+    sessionId: string;
+    userId: string;
+    source: string;
+    restored: boolean;
+    timestamp: string;
+};
 /**
  * Type guard for generate result
  */

package/dist/types/content.d.ts

@@ -5,14 +5,14 @@
 /**
  * Text content type for multimodal messages
  */
-export interface TextContent {
+export type TextContent = {
     type: "text";
     text: string;
-}
+};
 /**
  * Image content type for multimodal messages
  */
-export interface ImageContent {
+export type ImageContent = {
     type: "image";
     data: Buffer | string;
     mediaType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp" | "image/bmp" | "image/tiff";
@@ -25,11 +25,24 @@ export interface ImageContent {
         };
         filename?: string;
     };
-}
+};
+/**
+ * CSV content type for multimodal messages
+ */
+export type CSVContent = {
+    type: "csv";
+    data: Buffer | string;
+    metadata?: {
+        filename?: string;
+        maxRows?: number;
+        formatStyle?: "raw" | "markdown" | "json";
+        description?: string;
+    };
+};
 /**
  * Union type for all content types
  */
-export type Content = TextContent | ImageContent;
+export type Content = TextContent | ImageContent | CSVContent;
 /**
  * Vision capability information for providers
  */

package/dist/types/contextTypes.d.ts

@@ -3,6 +3,7 @@
  * Provides type-safe context integration for AI generation
  */
 import type { JsonObject } from "./common.js";
+import type { ExecutionContext } from "../types/tools.js";
 /**
  * Base context interface for all AI operations
  */
@@ -149,7 +150,6 @@ export declare class ContextFactory {
  * Context conversion utilities for domain-specific data
  * Replaces hardcoded business context with generic domain context
  */
-import type { ExecutionContext } from "../mcp/contracts/mcpContract.js";
 interface ContextConversionOptions {
     preserveLegacyFields?: boolean;
     validateDomainData?: boolean;

package/dist/types/conversation.d.ts

@@ -148,6 +148,18 @@ export declare class ConversationMemoryError extends Error {
     details?: Record<string, unknown> | undefined;
     constructor(message: string, code: "STORAGE_ERROR" | "CONFIG_ERROR" | "SESSION_NOT_FOUND" | "CLEANUP_ERROR", details?: Record<string, unknown> | undefined);
 }
+/**
+ * NeuroLink initialization options
+ * Configuration for creating NeuroLink instances with conversation memory
+ */
+export interface NeurolinkOptions {
+    /** Conversation memory configuration */
+    conversationMemory?: ConversationMemoryConfig;
+    /** Session identifier for conversation context */
+    sessionId?: string;
+    /** Observability configuration */
+    observability?: import("./observability.js").ObservabilityConfig;
+}
 /**
  * Session identifier for Redis storage operations
  */
@@ -166,10 +178,10 @@ export interface SessionMetadata {
     updatedAt: string;
 }
 /**
- * New Redis conversation storage object format
- * Contains conversation metadata and history in a single object
+ * Base conversation metadata (shared fields across all conversation types)
+ * Contains essential conversation information without heavy data arrays
  */
-export type RedisConversationObject = {
+export interface ConversationBase {
     /** Unique conversation identifier (UUID v4) */
     id: string;
     /** Auto-generated conversation title */
@@ -182,9 +194,50 @@ export type RedisConversationObject = {
     createdAt: string;
     /** When this conversation was last updated */
     updatedAt: string;
+}
+/**
+ * Redis conversation storage object format
+ * Contains conversation metadata and full message history
+ */
+export interface RedisConversationObject extends ConversationBase {
     /** Array of conversation messages */
     messages: ChatMessage[];
-};
+}
+/**
+ * Full conversation data for session restoration and manipulation
+ * Extends Redis storage object with additional loop mode metadata
+ */
+export interface ConversationData extends RedisConversationObject {
+    /** Optional metadata for session variables and other loop mode data */
+    metadata?: {
+        /** Session variables set during loop mode */
+        sessionVariables?: Record<string, string | number | boolean>;
+        /** Message count (for compatibility) */
+        messageCount?: number;
+        /** Additional metadata can be added here */
+        [key: string]: unknown;
+    };
+}
+/**
+ * Conversation summary for listing and selection
+ * Contains conversation preview information without heavy message arrays
+ */
+export interface ConversationSummary extends ConversationBase {
+    /** First message preview (for conversation preview) */
+    firstMessage: {
+        content: string;
+        timestamp: string;
+    };
+    /** Last message preview (for conversation preview) */
+    lastMessage: {
+        content: string;
+        timestamp: string;
+    };
+    /** Total number of messages in conversation */
+    messageCount: number;
+    /** Human-readable time since last update (e.g., "2 hours ago") */
+    duration: string;
+}
 /**
  * Redis storage configuration
  */

package/dist/types/fileTypes.d.ts

@@ -0,0 +1,65 @@
+/**
+ * File detection and processing types for unified file handling
+ */
+/**
+ * Supported file types for multimodal input
+ */
+export type FileType = "csv" | "image" | "pdf" | "text" | "unknown";
+/**
+ * File input can be Buffer or string (path/URL/data URI)
+ */
+export type FileInput = Buffer | string;
+/**
+ * File source type for tracking input origin
+ */
+export type FileSource = "url" | "path" | "buffer" | "datauri";
+/**
+ * File detection result with confidence scoring
+ */
+export type FileDetectionResult = {
+    type: FileType;
+    mimeType: string;
+    extension: string | null;
+    source: FileSource;
+    metadata: {
+        size?: number;
+        filename?: string;
+        confidence: number;
+    };
+};
+/**
+ * File processing result after detection and conversion
+ */
+export type FileProcessingResult = {
+    type: FileType;
+    content: string | Buffer;
+    mimeType: string;
+    metadata: {
+        confidence: number;
+        size?: number;
+        filename?: string;
+        rowCount?: number;
+        columnCount?: number;
+        columnNames?: string[];
+        sampleData?: string;
+        hasEmptyColumns?: boolean;
+    };
+};
+/**
+ * CSV processor options
+ */
+export type CSVProcessorOptions = {
+    maxRows?: number;
+    formatStyle?: "raw" | "markdown" | "json";
+    includeHeaders?: boolean;
+};
+/**
+ * File detector options
+ */
+export type FileDetectorOptions = {
+    maxSize?: number;
+    timeout?: number;
+    allowedTypes?: FileType[];
+    csvOptions?: CSVProcessorOptions;
+    confidenceThreshold?: number;
+};

package/dist/types/fileTypes.js

@@ -0,0 +1,4 @@
+/**
+ * File detection and processing types for unified file handling
+ */
+export {};

package/dist/types/generateTypes.d.ts

@@ -15,11 +15,18 @@ export type GenerateOptions = {
     input: {
         text: string;
         images?: Array<Buffer | string>;
+        csvFiles?: Array<Buffer | string>;
+        files?: Array<Buffer | string>;
         content?: Array<TextContent | ImageContent>;
     };
     output?: {
         format?: "text" | "structured" | "json";
     };
+    csvOptions?: {
+        maxRows?: number;
+        formatStyle?: "raw" | "markdown" | "json";
+        includeHeaders?: boolean;
+    };
     provider?: AIProviderName | string;
     model?: string;
     region?: string;
@@ -168,6 +175,11 @@ export type TextGenerationOptions = {
     middleware?: MiddlewareFactoryOptions;
     expectedOutcome?: string;
     evaluationCriteria?: string[];
+    csvOptions?: {
+        maxRows?: number;
+        formatStyle?: "raw" | "markdown" | "json";
+        includeHeaders?: boolean;
+    };
 };
 /**
  * Text generation result (consolidated from core types)