@juspay/neurolink 5.0.0 → 5.2.0

package/dist/neurolink.d.ts

@@ -1,72 +1,48 @@
 /**
  * NeuroLink - Unified AI Interface with Real MCP Tool Integration
  *
+ * REDESIGNED FALLBACK CHAIN - NO CIRCULAR DEPENDENCIES
  * Enhanced AI provider system with natural MCP tool access.
  * Uses real MCP infrastructure for tool discovery and execution.
  */
-import type { AIProviderName } from "./core/types.js";
-export interface TextGenerationOptions {
-    prompt: string;
-    provider?: "openai" | "bedrock" | "vertex" | "anthropic" | "azure" | "google-ai" | "huggingface" | "ollama" | "mistral" | "auto";
+import type { TextGenerationOptions, TextGenerationResult } from "./core/types.js";
+import type { GenerateOptions, GenerateResult } from "./types/generate-types.js";
+import type { StreamOptions, StreamResult } from "./types/stream-types.js";
+import type { SimpleTool } from "./sdk/tool-registration.js";
+import type { InMemoryMCPServerConfig } from "./types/mcp-types.js";
+export interface ProviderStatus {
+    provider: string;
+    status: "working" | "failed" | "not-configured";
+    configured: boolean;
+    authenticated: boolean;
+    error?: string;
+    responseTime?: number;
     model?: string;
-    temperature?: number;
-    maxTokens?: number;
-    systemPrompt?: string;
-    schema?: any;
-    timeout?: number | string;
-    disableTools?: boolean;
-    enableAnalytics?: boolean;
-    enableEvaluation?: boolean;
-    context?: Record<string, any>;
-    evaluationDomain?: string;
-    toolUsageContext?: string;
-    conversationHistory?: Array<{
-        role: string;
-        content: string;
-    }>;
 }
-export interface StreamTextOptions {
-    prompt: string;
-    provider?: "openai" | "bedrock" | "vertex" | "anthropic" | "azure" | "google-ai" | "huggingface" | "ollama" | "mistral" | "auto";
-    model?: string;
-    temperature?: number;
-    maxTokens?: number;
-    systemPrompt?: string;
-    schema?: any;
-    timeout?: number | string;
-    disableTools?: boolean;
-    enableAnalytics?: boolean;
-    enableEvaluation?: boolean;
-    context?: Record<string, any>;
+export interface MCPStatus {
+    mcpInitialized: boolean;
+    totalServers: number;
+    availableServers: number;
+    autoDiscoveredCount: number;
+    totalTools: number;
+    autoDiscoveredServers: MCPServerInfo[];
+    customToolsCount: number;
+    inMemoryServersCount: number;
+    error?: string;
 }
-export interface TextGenerationResult {
-    content: string;
-    provider?: string;
-    model?: string;
-    usage?: {
-        promptTokens?: number;
-        completionTokens?: number;
-        totalTokens?: number;
-    };
-    responseTime?: number;
-    toolsUsed?: string[];
-    toolExecutions?: Array<{
-        toolName: string;
-        executionTime: number;
-        success: boolean;
-        serverId?: string;
-    }>;
-    enhancedWithTools?: boolean;
-    availableTools?: Array<{
-        name: string;
-        description: string;
-        server: string;
-        category?: string;
-    }>;
+export interface MCPServerInfo {
+    id: string;
+    name: string;
+    source: string;
+    status: "connected" | "discovered" | "failed";
+    hasServer: boolean;
+    metadata?: any;
 }
 export declare class NeuroLink {
     private mcpInitialized;
     private contextManager;
+    private customTools;
+    private inMemoryServers;
     constructor();
     /**
      * Initialize MCP registry with enhanced error handling and resource cleanup
@@ -74,146 +50,157 @@ export declare class NeuroLink {
      */
     private initializeMCP;
     /**
-     * Isolated MCP initialization to prevent context-dependent hanging
+     * MAIN ENTRY POINT: Enhanced generate method with new function signature
+     * Replaces both generateText and legacy methods
      */
-    private doIsolatedMCPInitialization;
+    generate(optionsOrPrompt: GenerateOptions | string): Promise<GenerateResult>;
     /**
-     * Generate text using the best available AI provider with automatic fallback
-     * Tools are ENABLED BY DEFAULT for natural AI behavior
+     * BACKWARD COMPATIBILITY: Legacy generateText method
+     * Internally calls generate() and converts result format
      */
     generateText(options: TextGenerationOptions): Promise<TextGenerationResult>;
     /**
-     * Generate text with real MCP tool integration using automatic detection
+     * REDESIGNED INTERNAL GENERATION - NO CIRCULAR DEPENDENCIES
+     *
+     * This method implements a clean fallback chain:
+     * 1. Try MCP-enhanced generation if available
+     * 2. Fall back to direct provider generation
+     * 3. No recursive calls - each method has a specific purpose
+     */
+    private generateTextInternal;
+    /**
+     * Try MCP-enhanced generation (no fallback recursion)
      */
-    private generateTextWithTools;
+    private tryMCPGeneration;
     /**
-     * Regular text generation (existing logic)
+     * Direct provider generation (no MCP, no recursion)
      */
-    private generateTextRegular;
+    private directProviderGeneration;
     /**
      * Create tool-aware system prompt that informs AI about available tools
      */
     private createToolAwareSystemPrompt;
     /**
-     * Generate streaming text using the best available AI provider with automatic fallback
+     * BACKWARD COMPATIBILITY: Legacy streamText method
+     * Internally calls stream() and converts result format
      */
-    generateTextStream(options: StreamTextOptions): Promise<AsyncIterable<{
-        content: string;
-    }>>;
+    streamText(prompt: string, options?: Partial<StreamOptions>): Promise<AsyncIterable<string>>;
     /**
-     * Get the best available AI provider
+     * PRIMARY METHOD: Stream content using AI (recommended for new code)
+     * Future-ready for multi-modal capabilities with current text focus
      */
-    getBestProvider(): Promise<string>;
+    stream(options: StreamOptions): Promise<StreamResult>;
     /**
-     * Test a specific provider
+     * Register a custom tool that will be available to all AI providers
+     * @param name - Unique name for the tool
+     * @param tool - Tool configuration
      */
-    testProvider(providerName: AIProviderName, testPrompt?: string): Promise<boolean>;
+    registerTool(name: string, tool: SimpleTool): void;
     /**
-     * Get access to the unified MCP registry for tool inspection and management
+     * Register multiple tools at once
+     * @param tools - Object mapping tool names to configurations
      */
-    getUnifiedRegistry(): import("./mcp/unified-registry.js").UnifiedMCPRegistry;
+    registerTools(tools: Record<string, SimpleTool>): void;
     /**
-     * Initialize MCP and return discovery statistics
+     * Unregister a custom tool
+     * @param name - Name of the tool to remove
+     * @returns true if the tool was removed, false if it didn't exist
      */
-    getMCPStatus(): Promise<{
-        mcpInitialized: boolean;
-        totalServers: number;
-        availableServers: number;
-        autoDiscoveredCount: number;
-        totalTools: number;
-        autoDiscoveredServers: {
-            id: string;
-            name: string;
-            source: "core" | "project" | "installed";
-            status: string;
-            hasServer: boolean;
-        }[];
-    }>;
+    unregisterTool(name: string): boolean;
     /**
-     * Add a new MCP server programmatically
-     *
-     * Allows dynamic registration of MCP servers at runtime for enhanced
-     * tool ecosystem management. Perfect for integrating external services
-     * like Bitbucket, Slack, databases, etc.
-     *
-     * @param serverId - Unique identifier for the server (e.g., 'bitbucket', 'slack-api')
-     * @param config - Server configuration with command and execution parameters
-     * @returns Promise that resolves when server is successfully added and connected
-     *
-     * @example
-     * ```typescript
-     * // Add Bitbucket MCP server
-     * await neurolink.addMCPServer('bitbucket', {
-     *   command: 'npx',
-     *   args: ['-y', '@nexus2520/bitbucket-mcp-server'],
-     *   env: {
-     *     BITBUCKET_USERNAME: 'your-username',
-     *     BITBUCKET_APP_PASSWORD: 'your-app-password'
-     *   }
-     * });
-     *
-     * // Add custom database connector
-     * await neurolink.addMCPServer('database', {
-     *   command: 'node',
-     *   args: ['./custom-db-mcp-server.js'],
-     *   env: { DB_CONNECTION_STRING: 'postgresql://...' }
-     * });
-     * ```
-     */
-    addMCPServer(serverId: string, config: {
-        command: string;
-        args?: string[];
-        env?: Record<string, string>;
-        cwd?: string;
-        type?: "stdio" | "sse" | "http";
-        url?: string;
-        headers?: Record<string, string>;
+     * Get all registered custom tools
+     * @returns Map of tool names to configurations
+     */
+    getCustomTools(): Map<string, SimpleTool>;
+    /**
+     * Add an in-memory MCP server (from git diff)
+     * Allows registration of pre-instantiated server objects
+     * @param serverId - Unique identifier for the server
+     * @param config - Server configuration
+     */
+    addInMemoryMCPServer(serverId: string, config: InMemoryMCPServerConfig): Promise<void>;
+    /**
+     * Get all registered in-memory servers
+     * @returns Map of server IDs to configurations
+     */
+    getInMemoryServers(): Map<string, InMemoryMCPServerConfig>;
+    /**
+     * Execute a specific tool by name (from git diff)
+     * Supports both custom tools and MCP server tools
+     * @param toolName - Name of the tool to execute
+     * @param params - Parameters to pass to the tool
+     * @param options - Execution options
+     * @returns Tool execution result
+     */
+    executeTool<T = any>(toolName: string, params?: any, options?: {
         timeout?: number;
-    }): Promise<void>;
-    /**
-     * Alias for generateText() - CLI-SDK consistency
-     * @param options - Text generation options
-     * @returns Promise resolving to text generation result
-     */
-    generate(options: TextGenerationOptions): Promise<TextGenerationResult>;
-    /**
-     * Short alias for generateText() - CLI-SDK consistency
-     * @param options - Text generation options
-     * @returns Promise resolving to text generation result
-     */
-    gen(options: TextGenerationOptions): Promise<TextGenerationResult>;
-    /**
-     * Get the connection client for a specific MCP server
-     * @param serverId - The ID of the server to get connection for
-     * @returns Client connection object or undefined if not connected
-     */
-    getConnection(serverId: string): import("@modelcontextprotocol/sdk/client/index.js").Client<{
-        method: string;
-        params?: {
-            [x: string]: unknown;
-            _meta?: {
-                [x: string]: unknown;
-                progressToken?: string | number | undefined;
-            } | undefined;
-        } | undefined;
-    }, {
-        method: string;
-        params?: {
-            [x: string]: unknown;
-            _meta?: {
-                [x: string]: unknown;
-            } | undefined;
-        } | undefined;
-    }, {
-        [x: string]: unknown;
-        _meta?: {
-            [x: string]: unknown;
-        } | undefined;
-    }> | undefined;
-    /**
-     * Check if a specific MCP server is currently connected
-     * @param serverId - The ID of the server to check
-     * @returns True if server is connected, false otherwise
-     */
-    isConnected(serverId: string): boolean;
+    }): Promise<T>;
+    /**
+     * Get all available tools including custom and in-memory ones
+     * @returns Array of available tools with metadata
+     */
+    getAllAvailableTools(): Promise<{
+        serverId: string;
+        serverTitle: string;
+        toolName: string;
+        namespacedName: string;
+        description: string;
+        isImplemented: boolean;
+    }[]>;
+    /**
+     * Get comprehensive status of all AI providers
+     * Primary method for provider health checking and diagnostics
+     */
+    getProviderStatus(): Promise<ProviderStatus[]>;
+    /**
+     * Test a specific AI provider's connectivity and authentication
+     * @param providerName - Name of the provider to test
+     * @returns Promise resolving to true if provider is working
+     */
+    testProvider(providerName: string): Promise<boolean>;
+    /**
+     * Internal method to test provider connection with minimal generation call
+     */
+    private testProviderConnection;
+    /**
+     * Check if a provider has required environment variables configured
+     * @param providerName - Name of the provider to check
+     * @returns True if provider has required environment variables
+     */
+    hasProviderEnvVars(providerName: string): Promise<boolean>;
+    /**
+     * Get the best available AI provider based on configuration and availability
+     * @param requestedProvider - Optional preferred provider name
+     * @returns Promise resolving to the best provider name
+     */
+    getBestProvider(requestedProvider?: string): Promise<string>;
+    /**
+     * Get list of all available AI provider names
+     * @returns Array of supported provider names
+     */
+    getAvailableProviders(): Promise<string[]>;
+    /**
+     * Validate if a provider name is supported
+     * @param providerName - Provider name to validate
+     * @returns True if provider name is valid
+     */
+    isValidProvider(providerName: string): Promise<boolean>;
+    /**
+     * Get comprehensive MCP (Model Context Protocol) status information
+     * @returns Promise resolving to MCP status details
+     */
+    getMCPStatus(): Promise<MCPStatus>;
+    /**
+     * List all configured MCP servers with their status
+     * @returns Promise resolving to array of MCP server information
+     */
+    listMCPServers(): Promise<MCPServerInfo[]>;
+    /**
+     * Test connectivity to a specific MCP server
+     * @param serverId - ID of the MCP server to test
+     * @returns Promise resolving to true if server is reachable
+     */
+    testMCPServer(serverId: string): Promise<boolean>;
 }
+export declare const neurolink: NeuroLink;
+export default neurolink;