@juspay/neurolink 7.1.0 → 7.2.0

package/dist/types/contextTypes.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Context Types for NeuroLink - Factory Pattern Implementation
+ * Provides type-safe context integration for AI generation
+ */
+import { JsonObject } from "./common.js";
+/**
+ * Base context interface for all AI operations
+ */
+export interface BaseContext {
+    userId?: string;
+    sessionId?: string;
+    requestId?: string;
+    userRole?: string;
+    userPreferences?: JsonObject;
+    userMetadata?: JsonObject;
+    applicationContext?: {
+        name: string;
+        version?: string;
+        environment?: "development" | "staging" | "production";
+    };
+    organizationId?: string;
+    departmentId?: string;
+    projectId?: string;
+    [key: string]: unknown;
+}
+/**
+ * Context integration mode types
+ */
+export type ContextIntegrationMode = "prompt_prefix" | "prompt_suffix" | "system_prompt" | "metadata_only" | "structured_prompt" | "none";
+/**
+ * Context configuration for AI generation
+ */
+export interface ContextConfig {
+    mode: ContextIntegrationMode;
+    includeInPrompt?: boolean;
+    includeInAnalytics?: boolean;
+    includeInEvaluation?: boolean;
+    template?: string;
+    maxLength?: number;
+}
+/**
+ * Context processing result
+ */
+export interface ProcessedContext {
+    originalContext: BaseContext;
+    processedContext: string | null;
+    config: ContextConfig;
+    metadata: {
+        truncated: boolean;
+        processingTime: number;
+        template: string;
+        mode: ContextIntegrationMode;
+    };
+}
+/**
+ * Factory for context processing
+ */
+export declare class ContextFactory {
+    /**
+     * Default context configuration
+     */
+    static readonly DEFAULT_CONFIG: ContextConfig;
+    /**
+     * Validate and normalize context data
+     */
+    static validateContext(context: unknown): BaseContext | null;
+    /**
+     * Process context for AI generation based on configuration
+     */
+    static processContext(context: BaseContext, config?: Partial<ContextConfig>): ProcessedContext;
+    /**
+     * Format context for prompt integration
+     */
+    private static formatContextForPrompt;
+    /**
+     * Format context as prompt prefix
+     */
+    private static formatAsPrefix;
+    /**
+     * Format context as prompt suffix
+     */
+    private static formatAsSuffix;
+    /**
+     * Format context for system prompt
+     */
+    private static formatForSystemPrompt;
+    /**
+     * Format context in structured format
+     */
+    private static formatStructured;
+    /**
+     * Extract analytics data from context
+     */
+    static extractAnalyticsContext(context: BaseContext): JsonObject;
+    /**
+     * Extract evaluation context
+     */
+    static extractEvaluationContext(context: BaseContext): JsonObject;
+}
+/**
+ * Type guard to check if value is valid context
+ */
+export declare function isValidContext(value: unknown): value is BaseContext;
+/**
+ * Context integration options for AI generation
+ */
+export interface ContextIntegrationOptions {
+    context?: BaseContext;
+    contextConfig?: Partial<ContextConfig>;
+}

package/dist/types/contextTypes.js

@@ -0,0 +1,177 @@
+/**
+ * Context Types for NeuroLink - Factory Pattern Implementation
+ * Provides type-safe context integration for AI generation
+ */
+import { JsonValue, JsonObject } from "./common.js";
+/**
+ * Factory for context processing
+ */
+export class ContextFactory {
+    /**
+     * Default context configuration
+     */
+    static DEFAULT_CONFIG = {
+        mode: "metadata_only",
+        includeInPrompt: false,
+        includeInAnalytics: true,
+        includeInEvaluation: true,
+        maxLength: 1000,
+    };
+    /**
+     * Validate and normalize context data
+     */
+    static validateContext(context) {
+        if (!context || typeof context !== "object") {
+            return null;
+        }
+        try {
+            // Ensure it's JSON serializable
+            const serialized = JSON.stringify(context);
+            const parsed = JSON.parse(serialized);
+            // Basic validation
+            if (typeof parsed !== "object" || Array.isArray(parsed)) {
+                return null;
+            }
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Process context for AI generation based on configuration
+     */
+    static processContext(context, config = {}) {
+        const startTime = Date.now();
+        const finalConfig = { ...this.DEFAULT_CONFIG, ...config };
+        let processedContext = null;
+        const template = "default";
+        let truncated = false;
+        if (finalConfig.includeInPrompt && finalConfig.mode !== "metadata_only") {
+            processedContext = this.formatContextForPrompt(context, finalConfig);
+            // Truncate if necessary
+            if (finalConfig.maxLength &&
+                processedContext.length > finalConfig.maxLength) {
+                processedContext =
+                    processedContext.substring(0, finalConfig.maxLength) + "...";
+                truncated = true;
+            }
+        }
+        const processingTime = Date.now() - startTime;
+        return {
+            originalContext: context,
+            processedContext,
+            config: finalConfig,
+            metadata: {
+                truncated,
+                processingTime,
+                template,
+                mode: finalConfig.mode,
+            },
+        };
+    }
+    /**
+     * Format context for prompt integration
+     */
+    static formatContextForPrompt(context, config) {
+        switch (config.mode) {
+            case "prompt_prefix":
+                return this.formatAsPrefix(context);
+            case "prompt_suffix":
+                return this.formatAsSuffix(context);
+            case "system_prompt":
+                return this.formatForSystemPrompt(context);
+            case "structured_prompt":
+                return this.formatStructured(context);
+            case "metadata_only":
+            case "none":
+            default:
+                return "";
+        }
+    }
+    /**
+     * Format context as prompt prefix
+     */
+    static formatAsPrefix(context) {
+        const parts = [];
+        if (context.userId) {
+            parts.push(`User: ${context.userId}`);
+        }
+        if (context.userRole) {
+            parts.push(`Role: ${context.userRole}`);
+        }
+        if (context.sessionId) {
+            parts.push(`Session: ${context.sessionId}`);
+        }
+        if (parts.length === 0) {
+            return "";
+        }
+        return `Context: ${parts.join(", ")}\n\n`;
+    }
+    /**
+     * Format context as prompt suffix
+     */
+    static formatAsSuffix(context) {
+        const relevantKeys = Object.keys(context).filter((key) => !["userId", "sessionId", "requestId"].includes(key));
+        if (relevantKeys.length === 0) {
+            return "";
+        }
+        const contextData = relevantKeys.reduce((acc, key) => {
+            acc[key] = context[key];
+            return acc;
+        }, {});
+        return `\n\nAdditional Context: ${JSON.stringify(contextData, null, 2)}`;
+    }
+    /**
+     * Format context for system prompt
+     */
+    static formatForSystemPrompt(context) {
+        const parts = [];
+        if (context.userRole) {
+            parts.push(`You are assisting a user with the role: ${context.userRole}`);
+        }
+        if (context.organizationId) {
+            parts.push(`Organization context: ${context.organizationId}`);
+        }
+        if (context.userPreferences) {
+            parts.push(`User preferences: ${JSON.stringify(context.userPreferences)}`);
+        }
+        return parts.join(". ");
+    }
+    /**
+     * Format context in structured format
+     */
+    static formatStructured(context) {
+        return `[CONTEXT]\n${JSON.stringify(context, null, 2)}\n[/CONTEXT]\n\n`;
+    }
+    /**
+     * Extract analytics data from context
+     */
+    static extractAnalyticsContext(context) {
+        return {
+            hasUserId: !!context.userId,
+            hasSessionId: !!context.sessionId,
+            hasUserRole: !!context.userRole,
+            hasOrgContext: !!context.organizationId,
+            contextKeys: Object.keys(context),
+            contextSize: JSON.stringify(context).length,
+        };
+    }
+    /**
+     * Extract evaluation context
+     */
+    static extractEvaluationContext(context) {
+        return {
+            userRole: context.userRole || "unknown",
+            applicationContext: context.applicationContext?.name || "unknown",
+            organizationContext: context.organizationId || "unknown",
+            hasPreferences: !!context.userPreferences,
+        };
+    }
+}
+/**
+ * Type guard to check if value is valid context
+ */
+export function isValidContext(value) {
+    return ContextFactory.validateContext(value) !== null;
+}

package/dist/types/index.d.ts

@@ -9,4 +9,7 @@ export * from "./cli.js";
 export type { Unknown, UnknownRecord, UnknownArray, JsonValue, JsonObject, JsonArray, ErrorInfo, Result, FunctionParameters, } from "./common.js";
 export type { ToolArgs, ToolContext, ToolResult, ToolDefinition, SimpleTool, AvailableTool, ToolExecution, } from "./tools.js";
 export type { AISDKModel, ProviderError, TokenUsage, AnalyticsData, EvaluationData, ProviderConfig, } from "./providers.js";
-export type { BaseCommandArgs, GenerateCommandArgs, CommandResult, GenerateResult, StreamChunk, } from "./cli.js";
+export type { BaseCommandArgs, GenerateCommandArgs, MCPCommandArgs, ModelsCommandArgs, CommandResult, GenerateResult, StreamChunk, } from "./cli.js";
+export type { MCPTransportType, MCPServerStatus, MCPDiscoveredServer, MCPConnectedServer, MCPServerConfig, MCPToolInfo, MCPServerMetadata, MCPToolMetadata, MCPServerRegistryEntry, } from "./mcpTypes.js";
+export type { ModelCapability, ModelUseCase, ModelFilter, ModelResolutionContext, ModelStats, ModelPricing, } from "./providers.js";
+export type { ToolCallResults, ToolCalls, StreamAnalyticsData, } from "./streamTypes.js";

package/dist/types/mcpTypes.d.ts

@@ -2,6 +2,7 @@
  * MCP Types for In-Memory Server Support
  * Enables Lighthouse and other integrations to register tools directly
  */
+import type { JsonValue, JsonObject } from "./common.js";
 /**
  * In-memory MCP server configuration
  */
@@ -88,6 +89,121 @@ export interface InMemoryToolResult {
         [key: string]: unknown;
     };
 }
+/**
+ * MCP Transport Types - Maximally Reusable
+ */
+export type MCPTransportType = "stdio" | "websocket" | "tcp" | "unix";
+/**
+ * MCP Server Status for CLI Operations - High Reusability
+ */
+export interface MCPServerStatus {
+    /** Whether MCP is initialized */
+    mcpInitialized: boolean;
+    /** Total number of servers */
+    totalServers: number;
+    /** Number of available servers */
+    availableServers: number;
+    /** Number of auto-discovered servers */
+    autoDiscoveredCount: number;
+    /** Total number of tools */
+    totalTools: number;
+    /** Number of custom tools */
+    customToolsCount: number;
+    /** Number of in-memory servers */
+    inMemoryServersCount: number;
+    /** Error message if any */
+    error?: string;
+    /** Auto-discovered servers from various sources */
+    autoDiscoveredServers?: MCPDiscoveredServer[];
+    /** Currently connected servers */
+    connectedServers: MCPConnectedServer[];
+    /** Available tools across all servers */
+    availableTools: MCPToolInfo[];
+    /** Server registry entries */
+    serverRegistry?: Record<string, MCPServerConfig>;
+}
+/**
+ * Auto-discovered MCP Server - High Reusability
+ */
+export interface MCPDiscoveredServer {
+    name: string;
+    status: "connected" | "disconnected" | "error" | "pending" | "failed";
+    source: string;
+    transport: MCPTransportType;
+    description?: string;
+    url?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    metadata?: MCPServerMetadata;
+}
+/**
+ * Connected MCP Server - High Reusability
+ */
+export interface MCPConnectedServer {
+    name: string;
+    transport: MCPTransportType;
+    connected: boolean;
+    description?: string;
+    tools: MCPToolInfo[];
+    lastSeen?: Date;
+    connectionTime?: Date;
+    metadata?: MCPServerMetadata;
+}
+/**
+ * MCP Server Configuration - Maximally Reusable
+ */
+export interface MCPServerConfig {
+    name: string;
+    transport: MCPTransportType;
+    description?: string;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    timeout?: number;
+    retries?: number;
+    metadata?: MCPServerMetadata;
+}
+/**
+ * MCP Tool Information - High Reusability
+ */
+export interface MCPToolInfo {
+    name: string;
+    description: string;
+    serverId: string;
+    isExternal: boolean;
+    isImplemented?: boolean;
+    inputSchema?: JsonObject;
+    outputSchema?: JsonObject;
+    metadata?: MCPToolMetadata;
+}
+/**
+ * MCP Server Metadata - Extensible
+ */
+export type MCPServerMetadata = {
+    [key: string]: JsonValue;
+} & {
+    provider?: string;
+    version?: string;
+    author?: string;
+    category?: string;
+    tags?: string[];
+};
+/**
+ * MCP Tool Metadata - Extensible
+ */
+export type MCPToolMetadata = {
+    [key: string]: JsonValue;
+} & {
+    category?: string;
+    tags?: string[];
+    complexity?: "simple" | "medium" | "complex";
+    executionTime?: number;
+};
+/**
+ * MCP Server Registry Entry - For Object.entries() usage
+ */
+export type MCPServerRegistryEntry = [string, MCPServerConfig];
 /**
  * Unified MCP Registry interface
  */
@@ -99,16 +215,11 @@ export interface UnifiedMCPRegistry {
     /**
      * Get all available tools
      */
-    getAllTools(): Promise<Array<{
-        name: string;
-        serverId: string;
-        description: string;
-        isExternal: boolean;
-    }>>;
+    getAllTools(): Promise<MCPToolInfo[]>;
     /**
      * Execute a tool
      */
-    executeTool(toolName: string, params: unknown, context: unknown): Promise<unknown>;
+    executeTool(toolName: string, params: JsonObject, context: JsonObject): Promise<InMemoryToolResult>;
     /**
      * Check if connected to a server
      */

package/dist/types/providers.d.ts

@@ -42,6 +42,87 @@ export interface AnalyticsData {
     context?: JsonValue;
     [key: string]: JsonValue | undefined;
 }
+/**
+ * Model Capabilities - Maximally Reusable
+ */
+export type ModelCapability = "text" | "vision" | "function-calling" | "embedding" | "audio" | "video" | "code" | "reasoning" | "multimodal";
+/**
+ * Model Use Cases - High Reusability
+ */
+export type ModelUseCase = "chat" | "completion" | "analysis" | "coding" | "creative" | "reasoning" | "translation" | "summarization" | "classification";
+/**
+ * Model Filter Configuration - High Reusability
+ */
+export interface ModelFilter {
+    provider?: string;
+    capability?: ModelCapability;
+    useCase?: ModelUseCase;
+    requireVision?: boolean;
+    requireFunctionCalling?: boolean;
+    maxTokens?: number;
+    costLimit?: number;
+}
+/**
+ * Model Resolution Context - High Reusability
+ */
+export interface ModelResolutionContext {
+    requireCapabilities?: ModelCapability[];
+    preferredProviders?: string[];
+    useCase?: ModelUseCase;
+    budgetConstraints?: {
+        maxCostPerRequest?: number;
+        maxTokens?: number;
+    };
+    performance?: {
+        maxLatency?: number;
+        minQuality?: number;
+    };
+}
+/**
+ * Model Statistics Object - High Reusability
+ */
+export interface ModelStats {
+    name: string;
+    provider: string;
+    capabilities: ModelCapability[];
+    useCases: ModelUseCase[];
+    performance: {
+        avgLatency?: number;
+        avgTokensPerSecond?: number;
+        reliability?: number;
+    };
+    pricing?: ModelPricing;
+    metadata: {
+        [key: string]: JsonValue;
+    } & {
+        version?: string;
+        lastUpdated?: Date;
+    };
+}
+/**
+ * Model Pricing Information - High Reusability
+ */
+export interface ModelPricing {
+    inputTokens?: {
+        price: number;
+        currency: string;
+        per: number;
+    };
+    outputTokens?: {
+        price: number;
+        currency: string;
+        per: number;
+    };
+    requestPrice?: {
+        price: number;
+        currency: string;
+    };
+    tier?: "free" | "basic" | "premium" | "enterprise";
+    average?: number;
+    min?: number;
+    max?: number;
+    free?: boolean;
+}
 /**
  * Evaluation data structure
  */

package/dist/types/streamTypes.d.ts

@@ -1,25 +1,62 @@
 import type { ZodType, ZodTypeDef } from "zod";
 import type { Tool, Schema } from "ai";
 import type { AIProviderName, AnalyticsData, EvaluationData } from "../core/types.js";
-import type { UnknownRecord, Unknown } from "./common.js";
+import type { UnknownRecord, JsonValue } from "./common.js";
 /**
- * Interface for tool execution calls
+ * Interface for tool execution calls (AI SDK compatible)
  */
 export interface ToolCall {
+    type?: "tool-call";
+    toolCallId?: string;
     toolName: string;
-    parameters: UnknownRecord;
+    parameters?: UnknownRecord;
+    args?: UnknownRecord;
     id?: string;
 }
 /**
- * Interface for tool execution results
+ * Interface for tool execution results - Enhanced for type safety
  */
 export interface ToolResult {
     toolName: string;
     status: "success" | "failure";
-    output?: Unknown;
+    output?: JsonValue;
     error?: string;
     id?: string;
     executionTime?: number;
+    metadata?: {
+        [key: string]: JsonValue;
+    } & {
+        serverId?: string;
+        toolCategory?: string;
+        isExternal?: boolean;
+    };
+}
+/**
+ * Tool Call Results Array - High Reusability
+ */
+export type ToolCallResults = Array<ToolResult>;
+/**
+ * Tool Calls Array - High Reusability
+ */
+export type ToolCalls = Array<ToolCall>;
+/**
+ * Stream Analytics Data - Enhanced for performance tracking
+ */
+export interface StreamAnalyticsData {
+    /** Tool execution results with timing */
+    toolResults?: Promise<ToolCallResults>;
+    /** Tool calls made during stream */
+    toolCalls?: Promise<ToolCalls>;
+    /** Stream performance metrics */
+    performance?: {
+        startTime: number;
+        endTime?: number;
+        chunkCount: number;
+        avgChunkSize: number;
+        totalBytes: number;
+    };
+    /** Provider analytics */
+    providerAnalytics?: AnalyticsData;
 }
 /**
  * Stream function options interface - Primary method for streaming content
@@ -83,8 +120,8 @@ export interface StreamResult {
         responseTime?: number;
         fallback?: boolean;
     };
-    analytics?: AnalyticsData;
-    evaluation?: EvaluationData;
+    analytics?: AnalyticsData | Promise<AnalyticsData>;
+    evaluation?: EvaluationData | Promise<EvaluationData>;
 }
 /**
  * Enhanced provider interface with stream method

package/dist/types/tools.d.ts

@@ -136,6 +136,15 @@ export interface ToolCall {
     parameters: ToolArgs;
     id?: string;
 }
+/**
+ * AI SDK Tool Call format (from Vercel AI SDK)
+ */
+export interface AiSdkToolCall {
+    type: "tool-call";
+    toolCallId: string;
+    toolName: string;
+    args: ToolArgs;
+}
 /**
  * Tool call result (for AI SDK integration)
  */

package/dist/types/universalProviderOptions.d.ts

@@ -2,6 +2,7 @@
  * Universal Provider Options Interface (Phase 1: Factory Pattern)
  * Based on TypeScript factory pattern best practices for AI provider abstraction
  */
+import { BaseContext, ContextConfig } from "./contextTypes.js";
 /**
  * Base configuration interface for all AI providers
  * Uses Parameter Object Pattern for flexible, extensible configuration
@@ -14,7 +15,8 @@ export interface UniversalProviderOptions {
     systemPrompt?: string;
     enableAnalytics?: boolean;
     enableEvaluation?: boolean;
-    context?: Record<string, unknown>;
+    context?: BaseContext;
+    contextConfig?: Partial<ContextConfig>;
     metadata?: Record<string, unknown>;
     extensionOptions?: Record<string, unknown>;
 }

package/dist/types/universalProviderOptions.js

@@ -2,6 +2,7 @@
  * Universal Provider Options Interface (Phase 1: Factory Pattern)
  * Based on TypeScript factory pattern best practices for AI provider abstraction
  */
+import { BaseContext, ContextConfig } from "./contextTypes.js";
 /**
  * Parameter normalization utilities
  * Converts between different parameter formats for backward compatibility
@@ -45,8 +46,9 @@ export class ParameterNormalizer {
         return {
             ...defaults,
             ...options,
-            // Merge nested objects
+            // Merge nested objects (type-safe context merging)
             context: { ...defaults.context, ...options.context },
+            contextConfig: { ...defaults.contextConfig, ...options.contextConfig },
             metadata: { ...defaults.metadata, ...options.metadata },
         };
     }

package/dist/utils/logger.d.ts

@@ -47,6 +47,12 @@ declare class NeuroLinkLogger {
      * @param args - The arguments to log. These are passed directly to `console.log`.
      */
     always(...args: unknown[]): void;
+    /**
+     * Displays tabular data unconditionally using `console.table`.
+     *
+     * @param data - The data to display in table format
+     */
+    table(data: unknown): void;
 }
 export declare const logger: {
     debug: (...args: unknown[]) => void;
@@ -54,6 +60,7 @@ export declare const logger: {
     warn: (...args: unknown[]) => void;
     error: (...args: unknown[]) => void;
     always: (...args: unknown[]) => void;
+    table: (data: unknown) => void;
     setLogLevel: (level: LogLevel) => void;
     getLogs: (level?: LogLevel) => LogEntry[];
     clearLogs: () => void;