@juspay/neurolink 5.0.0 → 5.2.0

package/dist/lib/providers/mcp-provider.d.ts

@@ -2,9 +2,11 @@
  * NeuroLink MCP-Aware AI Provider
  * Integrates MCP tools with AI providers following Lighthouse's pattern
  */
-import type { AIProvider, TextGenerationOptions, StreamTextOptions, EnhancedGenerateTextResult } from "../core/types.js";
-import type { StreamTextResult, ToolSet, Schema, GenerateTextResult } from "ai";
+import type { AIProvider, TextGenerationOptions, EnhancedGenerateResult } from "../core/types.js";
+import type { Schema } from "ai";
+import type { GenerateResult } from "../types/generate-types.js";
 import type { ZodType, ZodTypeDef } from "zod";
+import type { StreamOptions, StreamResult } from "../types/stream-types.js";
 /**
  * MCP-Aware Provider Configuration
  */
@@ -31,8 +33,12 @@ export declare class MCPAwareProvider implements AIProvider {
      * Initialize MCP tools for this session
      */
     private initializeMCP;
-    generateText(optionsOrPrompt: TextGenerationOptions | string, analysisSchema?: ZodType<unknown, ZodTypeDef, unknown> | Schema<unknown>): Promise<GenerateTextResult<ToolSet, unknown> | null>;
-    streamText(optionsOrPrompt: StreamTextOptions | string, analysisSchema?: ZodType<unknown, ZodTypeDef, unknown> | Schema<unknown>): Promise<StreamTextResult<ToolSet, unknown> | null>;
+    /**
+     * PRIMARY METHOD: Stream content using AI (recommended for new code)
+     * Future-ready for multi-modal capabilities with current text focus
+     */
+    stream(optionsOrPrompt: StreamOptions | string, analysisSchema?: any): Promise<StreamResult>;
+    generate(optionsOrPrompt: TextGenerationOptions | string, analysisSchema?: ZodType<unknown, ZodTypeDef, unknown> | Schema<unknown>): Promise<GenerateResult>;
     /**
      * Detect if the prompt is requesting tool usage
      */
@@ -52,13 +58,12 @@ export declare class MCPAwareProvider implements AIProvider {
      */
     cleanup(): Promise<void>;
     /**
-     * Alias for generateText() - CLI-SDK consistency
+     * Alias for generate() - CLI-SDK consistency
      */
-    generate(optionsOrPrompt: TextGenerationOptions | string, analysisSchema?: any): Promise<EnhancedGenerateTextResult | null>;
     /**
-     * Short alias for generateText() - CLI-SDK consistency
+     * Short alias for generate() - CLI-SDK consistency
      */
-    gen(optionsOrPrompt: TextGenerationOptions | string, analysisSchema?: any): Promise<EnhancedGenerateTextResult | null>;
+    gen(optionsOrPrompt: TextGenerationOptions | string, analysisSchema?: any): Promise<EnhancedGenerateResult | null>;
 }
 /**
  * Create an MCP-aware provider

package/dist/lib/providers/mcp-provider.js

@@ -83,13 +83,50 @@ export class MCPAwareProvider {
             // Continue without MCP tools if initialization fails
         }
     }
-    async generateText(optionsOrPrompt, analysisSchema) {
+    /**
+     * PRIMARY METHOD: Stream content using AI (recommended for new code)
+     * Future-ready for multi-modal capabilities with current text focus
+     */
+    async stream(optionsOrPrompt, analysisSchema) {
+        const functionTag = "MCPAwareProvider.stream";
+        const startTime = Date.now();
+        // Parse parameters - support both string and options object
+        const options = typeof optionsOrPrompt === "string"
+            ? { input: { text: optionsOrPrompt } }
+            : optionsOrPrompt;
+        // Validate input
+        if (!options?.input?.text ||
+            typeof options.input.text !== "string" ||
+            options.input.text.trim() === "") {
+            throw new Error("Stream options must include input.text as a non-empty string");
+        }
+        // Use base provider's stream implementation
+        const baseResult = await this.baseProvider.stream(options);
+        if (!baseResult) {
+            throw new Error("No stream response received from provider");
+        }
+        // Return the result with MCP metadata
+        return {
+            ...baseResult,
+            provider: "mcp",
+            model: options.model || "unknown",
+            metadata: {
+                streamId: `mcp-${Date.now()}`,
+                startTime,
+            },
+        };
+    }
+    async generate(optionsOrPrompt, analysisSchema) {
         // Ensure MCP is initialized
         await this.initializeMCP();
         // Parse options
         const options = typeof optionsOrPrompt === "string"
             ? { prompt: optionsOrPrompt }
             : optionsOrPrompt;
+        // Validate prompt is provided
+        if (!options.prompt || options.prompt.trim() === "") {
+            throw new Error("MCP Provider requires a valid prompt. Please provide a non-empty prompt string.");
+        }
         // Check if prompt requests tool usage
         const needsTools = this.detectToolRequest(options.prompt);
         if (needsTools && this.mcpInitialized) {
@@ -114,15 +151,19 @@ PARAMS: <json_params>
 
 Otherwise, provide a direct response.`;
             // Generate response with enhanced prompt
-            const response = await this.baseProvider.generateText({
+            const response = await this.baseProvider.generate({
                 ...options,
                 prompt: enhancedPrompt,
             }, analysisSchema);
             if (!response) {
-                return null;
+                return {
+                    content: "No response generated",
+                    provider: "mcp",
+                    model: "unknown",
+                };
             }
             // Check if response includes tool invocation
-            const toolMatch = response.text.match(/TOOL:\s*(\S+)\s*\nPARAMS:\s*({.*})/s);
+            const toolMatch = response.content.match(/TOOL:\s*(\S+)\s*\nPARAMS:\s*({.*})/s);
             if (toolMatch) {
                 const toolName = toolMatch[1];
                 const toolParams = JSON.parse(toolMatch[2]);
@@ -135,12 +176,16 @@ Tool ${toolName} was executed with result:
 ${JSON.stringify(toolResult, null, 2)}
 
 Please provide a response based on this information.`;
-                const finalResponse = await this.baseProvider.generateText({
+                const finalResponse = await this.baseProvider.generate({
                     ...options,
                     prompt: finalPrompt,
                 }, analysisSchema);
                 if (!finalResponse) {
-                    return null;
+                    return {
+                        content: "Tool execution failed",
+                        provider: "mcp",
+                        model: "unknown",
+                    };
                 }
                 // Return response (tool usage is tracked internally)
                 return finalResponse;
@@ -148,12 +193,15 @@ Please provide a response based on this information.`;
             return response;
         }
         // Regular generation without tools
-        return this.baseProvider.generateText(options);
-    }
-    async streamText(optionsOrPrompt, analysisSchema) {
-        // For now, streaming doesn't support tool usage
-        // This matches Lighthouse's approach where MCP is used for non-streaming requests
-        return this.baseProvider.streamText(optionsOrPrompt, analysisSchema);
+        const result = await this.baseProvider.generate(options);
+        if (!result) {
+            return {
+                content: "Base provider returned no result",
+                provider: "mcp",
+                model: "unknown",
+            };
+        }
+        return result;
     }
     /**
      * Detect if the prompt is requesting tool usage
@@ -193,16 +241,13 @@ Please provide a response based on this information.`;
         }
     }
     /**
-     * Alias for generateText() - CLI-SDK consistency
+     * Alias for generate() - CLI-SDK consistency
      */
-    async generate(optionsOrPrompt, analysisSchema) {
-        return this.generateText(optionsOrPrompt, analysisSchema);
-    }
     /**
-     * Short alias for generateText() - CLI-SDK consistency
+     * Short alias for generate() - CLI-SDK consistency
      */
     async gen(optionsOrPrompt, analysisSchema) {
-        return this.generateText(optionsOrPrompt, analysisSchema);
+        return this.generate(optionsOrPrompt, analysisSchema);
     }
 }
 /**

package/dist/lib/providers/mistral.d.ts

@@ -0,0 +1,42 @@
+import type { ZodType, ZodTypeDef } from "zod";
+import { type Schema, type LanguageModelV1 } from "ai";
+import type { AIProviderName } from "../core/types.js";
+import type { StreamOptions, StreamResult } from "../types/stream-types.js";
+import { BaseProvider } from "../core/base-provider.js";
+/**
+ * Mistral AI Provider v2 - BaseProvider Implementation
+ *
+ * PHASE 3.6: Simple BaseProvider wrap around existing @ai-sdk/mistral implementation
+ *
+ * Features:
+ * - Extends BaseProvider for shared functionality
+ * - Uses pre-configured Mistral instance for efficiency
+ * - Enhanced error handling with setup guidance
+ * - Supports all Mistral models (mistral-small, mistral-medium, mistral-large)
+ */
+export declare class MistralProvider extends BaseProvider {
+    private mistral;
+    private model;
+    constructor(modelName?: string, sdk?: any);
+    protected getProviderName(): AIProviderName;
+    protected getDefaultModel(): string;
+    /**
+     * Returns the Vercel AI SDK model instance for Mistral
+     */
+    protected getAISDKModel(): LanguageModelV1;
+    protected executeStream(options: StreamOptions, analysisSchema?: ZodType<unknown, ZodTypeDef, unknown> | Schema<unknown>): Promise<StreamResult>;
+    protected handleProviderError(error: any): Error;
+    private validateStreamOptions;
+    /**
+     * Check available Mistral models
+     * @returns Array of available model names
+     */
+    getAvailableModels(): string[];
+    /**
+     * Get recommended model based on use case
+     * @param useCase - The intended use case
+     * @returns Recommended model name
+     */
+    getRecommendedModel(useCase: "speed" | "balanced" | "quality"): string;
+}
+export default MistralProvider;

package/dist/lib/providers/mistral.js

@@ -0,0 +1,160 @@
+import { createMistral } from "@ai-sdk/mistral";
+import { streamText } from "ai";
+import { BaseProvider } from "../core/base-provider.js";
+import { logger } from "../utils/logger.js";
+import { TimeoutError, } from "../utils/timeout.js";
+import { DEFAULT_MAX_TOKENS } from "../core/constants.js";
+// Configuration helpers
+const getMistralApiKey = () => {
+    const apiKey = process.env.MISTRAL_API_KEY;
+    if (!apiKey) {
+        throw new Error(`❌ Mistral AI Provider Configuration Error\n\nMissing required environment variable: MISTRAL_API_KEY\n\n🔧 Step 1: Get Mistral AI API Key\n1. Visit: https://console.mistral.ai/\n2. Sign in or create an account\n3. Go to API Keys section\n4. Create a new API key\n\n🔧 Step 2: Set Environment Variable\nAdd to your .env file:\nMISTRAL_API_KEY=your_api_key_here\n\n🔧 Step 3: Restart Application\nRestart your application to load the new environment variables.`);
+    }
+    return apiKey;
+};
+const getDefaultMistralModel = () => {
+    return process.env.MISTRAL_MODEL || "mistral-small";
+};
+const hasMistralCredentials = () => {
+    return !!process.env.MISTRAL_API_KEY;
+};
+/**
+ * Mistral AI Provider v2 - BaseProvider Implementation
+ *
+ * PHASE 3.6: Simple BaseProvider wrap around existing @ai-sdk/mistral implementation
+ *
+ * Features:
+ * - Extends BaseProvider for shared functionality
+ * - Uses pre-configured Mistral instance for efficiency
+ * - Enhanced error handling with setup guidance
+ * - Supports all Mistral models (mistral-small, mistral-medium, mistral-large)
+ */
+export class MistralProvider extends BaseProvider {
+    mistral;
+    model;
+    constructor(modelName, sdk) {
+        super(modelName, "mistral", sdk);
+        // Validate Mistral API credentials
+        if (!hasMistralCredentials()) {
+            throw new Error(`❌ Mistral AI Provider Configuration Error\n\nMissing Mistral AI API key.\n\n🔧 Required Environment Variable:\nMISTRAL_API_KEY=your_api_key_here\n\n🔧 Get API Key:\n1. Visit: https://console.mistral.ai/\n2. Sign in or create account\n3. Generate API key\n4. Add to .env file\n\n🔧 Restart Application\nRestart your application to load the new environment variables.`);
+        }
+        // Initialize Mistral provider
+        this.mistral = createMistral({
+            apiKey: getMistralApiKey(),
+        });
+        // Pre-initialize model for efficiency
+        this.model = this.mistral(this.modelName || getDefaultMistralModel());
+        logger.debug("Mistral AI BaseProvider v2 initialized", {
+            modelName: this.modelName,
+            provider: this.providerName,
+        });
+    }
+    getProviderName() {
+        return "mistral";
+    }
+    getDefaultModel() {
+        return getDefaultMistralModel();
+    }
+    /**
+     * Returns the Vercel AI SDK model instance for Mistral
+     */
+    getAISDKModel() {
+        return this.model;
+    }
+    // executeGenerate removed - BaseProvider handles all generation with tools
+    async executeStream(options, analysisSchema) {
+        try {
+            this.validateStreamOptions(options);
+            const result = await streamText({
+                model: this.model,
+                prompt: options.input.text,
+                system: options.systemPrompt,
+                maxTokens: options.maxTokens || DEFAULT_MAX_TOKENS,
+                temperature: options.temperature,
+            });
+            return {
+                stream: (async function* () {
+                    for await (const chunk of result.textStream) {
+                        yield { content: chunk };
+                    }
+                })(),
+                provider: this.providerName,
+                model: this.modelName,
+            };
+        }
+        catch (error) {
+            throw this.handleProviderError(error);
+        }
+    }
+    handleProviderError(error) {
+        if (error.name === "TimeoutError") {
+            return new TimeoutError(`Mistral AI request timed out. Consider increasing timeout or using a lighter model.`, this.defaultTimeout);
+        }
+        if (error.message?.includes("401") ||
+            error.message?.includes("Unauthorized")) {
+            return new Error(`❌ Mistral AI Authentication Error\n\nYour API key is invalid or expired.\n\n🔧 Steps to Fix:\n1. Check your MISTRAL_API_KEY in .env file\n2. Verify the API key is correct and active\n3. Generate a new API key if needed at https://console.mistral.ai/\n4. Restart your application after updating`);
+        }
+        if (error.message?.includes("403") ||
+            error.message?.includes("Forbidden")) {
+            return new Error(`❌ Mistral AI Access Denied\n\nYour account doesn't have permission to access this model.\n\n🔧 Possible Solutions:\n1. Check if your account has access to the model: ${this.modelName}\n2. Try a different model (e.g., 'mistral-small')\n3. Verify your subscription status\n4. Contact Mistral AI support if needed`);
+        }
+        if (error.message?.includes("429") ||
+            error.message?.includes("rate limit")) {
+            return new Error(`❌ Mistral AI Rate Limit Exceeded\n\n${error.message}\n\n🔧 Solutions:\n1. Wait a moment before retrying\n2. Reduce request frequency\n3. Check your usage quotas\n4. Consider upgrading your plan`);
+        }
+        if (error.message?.includes("400") ||
+            error.message?.includes("Bad Request")) {
+            return new Error(`❌ Mistral AI Invalid Request\n\n${error.message}\n\n🔧 Check:\n1. Input text is properly formatted\n2. Model name is correct: ${this.modelName}\n3. Parameters are within limits\n4. Request format matches API requirements`);
+        }
+        if (error.message?.includes("404") ||
+            error.message?.includes("Not Found")) {
+            return new Error(`❌ Mistral AI Model Not Found\n\nModel '${this.modelName}' is not available.\n\n🔧 Available Models:\n- mistral-small (fastest, cost-effective)\n- mistral-medium (balanced performance)\n- mistral-large (highest quality)\n\n🔧 Fix: Update MISTRAL_MODEL environment variable`);
+        }
+        return new Error(`❌ Mistral AI Provider Error\n\n${error.message || "Unknown error occurred"}\n\n🔧 Troubleshooting:\n1. Check API key and network connectivity\n2. Verify model availability\n3. Review request parameters\n4. Check Mistral AI status page`);
+    }
+    validateStreamOptions(options) {
+        if (!options.input?.text?.trim()) {
+            throw new Error("Prompt is required for streaming");
+        }
+        if (options.maxTokens &&
+            (options.maxTokens < 1 || options.maxTokens > 32768)) {
+            throw new Error("maxTokens must be between 1 and 32768 for Mistral AI");
+        }
+        if (options.temperature &&
+            (options.temperature < 0 || options.temperature > 1)) {
+            throw new Error("temperature must be between 0 and 1");
+        }
+    }
+    /**
+     * Check available Mistral models
+     * @returns Array of available model names
+     */
+    getAvailableModels() {
+        return [
+            "mistral-small",
+            "mistral-medium",
+            "mistral-large",
+            "mistral-7b-instruct",
+            "mistral-8x7b-instruct",
+            "mistral-8x22b-instruct",
+        ];
+    }
+    /**
+     * Get recommended model based on use case
+     * @param useCase - The intended use case
+     * @returns Recommended model name
+     */
+    getRecommendedModel(useCase) {
+        switch (useCase) {
+            case "speed":
+                return "mistral-small";
+            case "balanced":
+                return "mistral-medium";
+            case "quality":
+                return "mistral-large";
+            default:
+                return "mistral-small";
+        }
+    }
+}
+export default MistralProvider;

package/dist/lib/providers/ollama.d.ts

@@ -1,53 +1,70 @@
+import type { AIProviderName } from "../core/types.js";
+import type { LanguageModelV1 } from "ai";
+import type { StreamOptions, StreamResult } from "../types/stream-types.js";
+import type { ZodType, ZodTypeDef } from "zod";
+import type { Schema } from "ai";
+import { BaseProvider } from "../core/base-provider.js";
 /**
- * Ollama Provider for NeuroLink
+ * Ollama Provider v2 - BaseProvider Implementation
  *
- * Local AI model deployment and management using Ollama.
- * Provides offline AI capabilities with local model hosting.
+ * PHASE 3.7: BaseProvider wrap around existing custom Ollama implementation
  *
  * Features:
- * - Local model deployment (privacy-first)
- * - Model management (download, list, remove)
- * - Health checking and service validation
- * - Streaming and non-streaming text generation
+ * - Extends BaseProvider for shared functionality
+ * - Preserves custom OllamaLanguageModel implementation
+ * - Local model management and health checking
+ * - Enhanced error handling with Ollama-specific guidance
  */
-import type { AIProvider, TextGenerationOptions, StreamTextOptions, EnhancedGenerateTextResult } from "../core/types.js";
-import type { GenerateTextResult, StreamTextResult, ToolSet } from "ai";
-import type { ZodType, ZodTypeDef } from "zod";
-import type { Schema } from "ai";
-export declare class Ollama implements AIProvider {
+export declare class OllamaProvider extends BaseProvider {
+    private ollamaModel;
     private baseUrl;
-    private modelName;
-    private defaultTimeout;
+    private timeout;
     constructor(modelName?: string);
+    protected getProviderName(): AIProviderName;
+    protected getDefaultModel(): string;
     /**
-     * Gets the appropriate model instance
-     * @private
-     */
-    private getModel;
-    /**
-     * Health check - verify Ollama service is running and accessible
+     * Returns the Vercel AI SDK model instance for Ollama
      */
-    checkHealth(): Promise<boolean>;
+    protected getAISDKModel(): LanguageModelV1;
     /**
-     * List available models on the Ollama instance
+     * Ollama tool/function calling support is currently disabled due to integration issues.
+     *
+     * **Current Issues:**
+     * 1. The OllamaLanguageModel from @ai-sdk/provider-utils doesn't properly integrate
+     *    with BaseProvider's tool calling mechanism
+     * 2. Ollama models require specific prompt formatting for function calls that differs
+     *    from the standardized AI SDK format
+     * 3. Tool response parsing and execution flow needs custom implementation
+     *
+     * **What's needed to enable tool support:**
+     * - Create a custom OllamaLanguageModel wrapper that handles tool schema formatting
+     * - Implement Ollama-specific tool calling prompt templates
+     * - Add proper response parsing for Ollama's function call format
+     * - Test with models that support function calling (llama3.1, mistral, etc.)
+     *
+     * **Tracking:**
+     * - See BaseProvider tool integration patterns in other providers
+     * - Monitor Ollama function calling documentation: https://ollama.com/blog/tool-support
+     * - Track AI SDK updates for better Ollama integration
+     *
+     * @returns false to disable tools by default
      */
-    listModels(): Promise<string[]>;
+    supportsTools(): boolean;
+    protected executeStream(options: StreamOptions, analysisSchema?: ZodType<unknown, ZodTypeDef, unknown> | Schema<unknown>): Promise<StreamResult>;
+    private createOllamaStream;
+    protected handleProviderError(error: any): Error;
+    private validateStreamOptions;
     /**
-     * Check if a specific model is available
-     */
-    isModelAvailable(modelName: string): Promise<boolean>;
-    /**
-     * Pull/download a model to the local Ollama instance
+     * Check if Ollama service is healthy and accessible
      */
-    pullModel(modelName: string): Promise<void>;
+    private checkOllamaHealth;
     /**
-     * Generate text using Ollama local models
+     * Get available models from Ollama
      */
-    generateText(optionsOrPrompt: TextGenerationOptions | string, analysisSchema?: ZodType<unknown, ZodTypeDef, unknown> | Schema<unknown>): Promise<GenerateTextResult<ToolSet, unknown> | null>;
+    getAvailableModels(): Promise<string[]>;
     /**
-     * Generate streaming text using Ollama local models
+     * Check if a specific model is available
      */
-    streamText(optionsOrPrompt: StreamTextOptions | string, analysisSchema?: ZodType<unknown, ZodTypeDef, unknown> | Schema<unknown>): Promise<StreamTextResult<ToolSet, unknown> | null>;
-    generate(optionsOrPrompt: TextGenerationOptions | string, analysisSchema?: any): Promise<EnhancedGenerateTextResult | null>;
-    gen(optionsOrPrompt: TextGenerationOptions | string, analysisSchema?: any): Promise<EnhancedGenerateTextResult | null>;
+    isModelAvailable(modelName: string): Promise<boolean>;
 }
+export default OllamaProvider;