@juspay/neurolink 5.1.0 → 5.2.0

package/dist/lib/neurolink.d.ts

@@ -1,15 +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, TextGenerationOptions, TextGenerationResult } from "./core/types.js";
+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;
+}
+export interface MCPStatus {
+    mcpInitialized: boolean;
+    totalServers: number;
+    availableServers: number;
+    autoDiscoveredCount: number;
+    totalTools: number;
+    autoDiscoveredServers: MCPServerInfo[];
+    customToolsCount: number;
+    inMemoryServersCount: number;
+    error?: 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
@@ -17,151 +50,157 @@ export declare class NeuroLink {
      */
     private initializeMCP;
     /**
-     * Isolated MCP initialization to prevent context-dependent hanging
-     */
-    private doIsolatedMCPInitialization;
-    /**
-     * PRIMARY METHOD: Generate content using AI (recommended for new code)
-     * Future-ready for multi-modal capabilities with current text focus
+     * MAIN ENTRY POINT: Enhanced generate method with new function signature
+     * Replaces both generateText and legacy methods
      */
-    generate(options: GenerateOptions): Promise<GenerateResult>;
+    generate(optionsOrPrompt: GenerateOptions | string): Promise<GenerateResult>;
     /**
      * 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 generateWithTools;
+    private tryMCPGeneration;
     /**
-     * Regular text generation (existing logic)
+     * Direct provider generation (no MCP, no recursion)
      */
-    private generateRegular;
+    private directProviderGeneration;
     /**
      * Create tool-aware system prompt that informs AI about available tools
      */
     private createToolAwareSystemPrompt;
+    /**
+     * BACKWARD COMPATIBILITY: Legacy streamText method
+     * Internally calls stream() and converts result format
+     */
+    streamText(prompt: string, options?: Partial<StreamOptions>): Promise<AsyncIterable<string>>;
     /**
      * PRIMARY METHOD: Stream content using AI (recommended for new code)
      * Future-ready for multi-modal capabilities with current text focus
      */
     stream(options: StreamOptions): Promise<StreamResult>;
     /**
-     * BACKWARD COMPATIBILITY: Legacy streamText method
-     * Internally calls stream() and converts result format
+     * Register a custom tool that will be available to all AI providers
+     * @param name - Unique name for the tool
+     * @param tool - Tool configuration
      */
-    streamText(options: TextGenerationOptions): Promise<AsyncIterable<{
-        content: string;
-    }>>;
+    registerTool(name: string, tool: SimpleTool): void;
     /**
-     * Get the best available AI provider
+     * Register multiple tools at once
+     * @param tools - Object mapping tool names to configurations
      */
-    getBestProvider(): Promise<string>;
+    registerTools(tools: Record<string, SimpleTool>): void;
     /**
-     * Test a specific provider
+     * 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
      */
-    testProvider(providerName: AIProviderName, testPrompt?: string): Promise<boolean>;
+    unregisterTool(name: string): boolean;
     /**
-     * Get access to the unified MCP registry for tool inspection and management
+     * Get all registered custom tools
+     * @returns Map of tool names to configurations
      */
-    getUnifiedRegistry(): import("./mcp/unified-registry.js").UnifiedMCPRegistry;
+    getCustomTools(): Map<string, SimpleTool>;
     /**
-     * Initialize MCP and return discovery statistics
+     * 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
      */
-    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;
-        }[];
-    }>;
+    addInMemoryMCPServer(serverId: string, config: InMemoryMCPServerConfig): Promise<void>;
     /**
-     * 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 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>;
-    /**
-     * Short alias for generate() - 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;