@juspay/neurolink 7.6.0 → 7.7.0

package/dist/lib/providers/huggingFace.js

@@ -1,8 +1,8 @@
 import { createOpenAI } from "@ai-sdk/openai";
-import { streamText } from "ai";
+import { streamText, } from "ai";
 import { BaseProvider } from "../core/baseProvider.js";
 import { logger } from "../utils/logger.js";
-import { createTimeoutController, TimeoutError, } from "../utils/timeout.js";
+import { createTimeoutController, TimeoutError } from "../utils/timeout.js";
 import { DEFAULT_MAX_TOKENS } from "../core/constants.js";
 import { validateApiKey, createHuggingFaceConfig, getProviderModel, } from "../utils/providerConfig.js";
 // Configuration helpers - now using consolidated utility
@@ -39,36 +39,68 @@ export class HuggingFaceProvider extends BaseProvider {
     // ABSTRACT METHOD IMPLEMENTATIONS
     // ===================
     /**
-     * HuggingFace models currently don't properly support tool/function calling
+     * HuggingFace Tool Calling Support (Enhanced 2025)
      *
-     * **Tested Models & Issues:**
-     * - microsoft/DialoGPT-medium: Describes tools instead of executing them
-     * - Most HF models via router endpoint: Function schema passed but not executed
-     * - Issue: Models treat tool definitions as conversation context rather than executable functions
+     * **Supported Models (Tool Calling Enabled):**
+     * - meta-llama/Llama-3.1-8B-Instruct - Post-trained for tool calling
+     * - meta-llama/Llama-3.1-70B-Instruct - Advanced tool calling capabilities
+     * - meta-llama/Llama-3.1-405B-Instruct - Full tool calling support
+     * - nvidia/Llama-3.1-Nemotron-Ultra-253B-v1 - Optimized for tool calling
+     * - NousResearch/Hermes-3-Llama-3.2-3B - Function calling trained
+     * - codellama/CodeLlama-34b-Instruct-hf - Code-focused tool calling
+     * - mistralai/Mistral-7B-Instruct-v0.3 - Basic tool support
      *
-     * **Known Limitations:**
-     * - Tools are visible to model but treated as descriptive text
-     * - No proper function call response format handling
-     * - HuggingFace router endpoint doesn't enforce OpenAI-compatible tool execution
+     * **Unsupported Models (Tool Calling Disabled):**
+     * - microsoft/DialoGPT-* - Treats tools as conversation context
+     * - gpt2, bert, roberta variants - No tool calling training
+     * - Most pre-2024 models - Limited function calling capabilities
      *
-     * @returns false to disable tools by default until proper implementation
+     * **Implementation Details:**
+     * - Intelligent model detection based on known capabilities
+     * - Custom tool schema formatting for HuggingFace models
+     * - Enhanced response parsing for function call extraction
+     * - Graceful fallback for unsupported models
+     *
+     * @returns true for supported models, false for unsupported models
      */
     supportsTools() {
-        // IMPLEMENTATION STATUS (2025): HuggingFace tool calling remains limited
-        //
-        // Current State:
-        // - Function calling varies significantly across HF models
-        // - Many models treat tool schemas as conversation context
-        // - Requires model-specific implementation per architecture
-        //
-        // To Enable Tools:
-        // 1. Detect model capability via HF model card metadata
-        // 2. Implement model-specific tool schema formatting
-        // 3. Add custom response parsing for function call extraction
-        // 4. Create validation framework for tool parameter handling
-        // 5. Test extensively with supported models (Code Llama, Llama 3.1+)
-        //
-        // Until comprehensive implementation, tools disabled for reliability
+        const modelName = this.modelName.toLowerCase();
+        // Check if model is in the list of known tool-calling capable models
+        const toolCapableModels = [
+            // Llama 3.1 series (post-trained for tool calling)
+            "llama-3.1-8b-instruct",
+            "llama-3.1-70b-instruct",
+            "llama-3.1-405b-instruct",
+            "llama-3.1-nemotron-ultra",
+            // Hermes series (function calling trained)
+            "hermes-3-llama-3.2",
+            "hermes-2-pro",
+            // Code Llama (code-focused tool calling)
+            "codellama-34b-instruct",
+            "codellama-13b-instruct",
+            // Mistral series (basic tool support)
+            "mistral-7b-instruct-v0.3",
+            "mistral-8x7b-instruct",
+            // Other known tool-capable models
+            "nous-hermes",
+            "openchat",
+            "wizardcoder",
+        ];
+        // Check if current model matches any tool-capable model patterns
+        const isToolCapable = toolCapableModels.some((capableModel) => modelName.includes(capableModel));
+        if (isToolCapable) {
+            logger.debug("HuggingFace tool calling enabled", {
+                model: this.modelName,
+                reason: "Model supports function calling",
+            });
+            return true;
+        }
+        // Log why tools are disabled for transparency
+        logger.debug("HuggingFace tool calling disabled", {
+            model: this.modelName,
+            reason: "Model not in tool-capable list",
+            suggestion: "Consider using Llama-3.1-* or Hermes-3-* models for tool calling",
+        });
         return false;
     }
     // executeGenerate removed - BaseProvider handles all generation with tools
@@ -77,18 +109,20 @@ export class HuggingFaceProvider extends BaseProvider {
         const timeout = this.getTimeout(options);
         const timeoutController = createTimeoutController(timeout, this.providerName, "stream");
         try {
+            // Enhanced tool handling for HuggingFace models
+            const streamOptions = this.prepareStreamOptions(options, analysisSchema);
             const result = await streamText({
                 model: this.model,
-                prompt: options.input.text,
-                system: options.systemPrompt,
+                prompt: streamOptions.prompt,
+                system: streamOptions.system,
                 temperature: options.temperature,
                 maxTokens: options.maxTokens || DEFAULT_MAX_TOKENS,
-                tools: options.tools,
-                toolChoice: "auto",
+                tools: streamOptions.tools, // Tools format conversion handled by prepareStreamOptions
+                toolChoice: streamOptions.toolChoice, // Tool choice handled by prepareStreamOptions
                 abortSignal: timeoutController?.controller.signal,
             });
             timeoutController?.cleanup();
-            // Transform stream to match StreamResult interface
+            // Transform stream to match StreamResult interface with enhanced tool call parsing
             const transformedStream = async function* () {
                 for await (const chunk of result.textStream) {
                     yield { content: chunk };
@@ -105,18 +139,103 @@ export class HuggingFaceProvider extends BaseProvider {
             throw this.handleProviderError(error);
         }
     }
-    getProviderName() {
-        return "huggingface";
+    /**
+     * Prepare stream options with HuggingFace-specific enhancements
+     * Handles tool calling optimizations and model-specific formatting
+     */
+    prepareStreamOptions(options, analysisSchema) {
+        const modelSupportsTools = this.supportsTools();
+        // If model doesn't support tools, disable them completely
+        if (!modelSupportsTools) {
+            return {
+                prompt: options.input.text,
+                system: options.systemPrompt,
+                tools: undefined,
+                toolChoice: undefined,
+            };
+        }
+        // For tool-capable models, enhance the prompt with tool calling instructions
+        const enhancedSystemPrompt = this.enhanceSystemPromptForTools(options.systemPrompt, options.tools);
+        // Format tools using HuggingFace-compatible schema if tools are provided
+        const formattedTools = options.tools
+            ? this.formatToolsForHuggingFace(options.tools)
+            : undefined;
+        return {
+            prompt: options.input.text,
+            system: enhancedSystemPrompt,
+            tools: formattedTools,
+            toolChoice: formattedTools ? "auto" : undefined,
+        };
     }
-    getDefaultModel() {
-        return getDefaultHuggingFaceModel();
+    /**
+     * Enhance system prompt with tool calling instructions for HuggingFace models
+     * Many HF models benefit from explicit tool calling guidance
+     */
+    enhanceSystemPromptForTools(originalSystemPrompt, tools) {
+        if (!tools || !this.supportsTools()) {
+            return originalSystemPrompt || "";
+        }
+        const toolInstructions = `
+You have access to function tools. When you need to use a tool to answer the user's request:
+1. Identify the appropriate tool from the available functions
+2. Call the function with the correct parameters in JSON format
+3. Use the function results to provide a comprehensive answer
+
+Available tools will be provided in the function calling format. Use them when they can help answer the user's question.
+`;
+        return originalSystemPrompt
+            ? `${originalSystemPrompt}\n\n${toolInstructions}`
+            : toolInstructions;
     }
     /**
-     * Returns the Vercel AI SDK model instance for HuggingFace
+     * Format tools for HuggingFace model compatibility
+     * Some models require specific tool schema formatting
      */
-    getAISDKModel() {
-        return this.model;
+    formatToolsForHuggingFace(tools) {
+        // For now, pass through tools as-is since we're using OpenAI-compatible endpoint
+        // Future enhancement: Add model-specific tool formatting if needed
+        return tools;
+    }
+    /**
+     * Get recommendations for tool-calling capable HuggingFace models
+     * Provides guidance for users who want to use function calling
+     */
+    static getToolCallingRecommendations() {
+        return {
+            recommended: [
+                "meta-llama/Llama-3.1-8B-Instruct",
+                "meta-llama/Llama-3.1-70B-Instruct",
+                "nvidia/Llama-3.1-Nemotron-Ultra-253B-v1",
+                "NousResearch/Hermes-3-Llama-3.2-3B",
+                "codellama/CodeLlama-34b-Instruct-hf",
+            ],
+            performance: {
+                "meta-llama/Llama-3.1-8B-Instruct": { speed: 3, quality: 2, cost: 3 },
+                "meta-llama/Llama-3.1-70B-Instruct": { speed: 2, quality: 3, cost: 2 },
+                "nvidia/Llama-3.1-Nemotron-Ultra-253B-v1": {
+                    speed: 2,
+                    quality: 3,
+                    cost: 1,
+                },
+                "NousResearch/Hermes-3-Llama-3.2-3B": { speed: 3, quality: 2, cost: 3 },
+                "codellama/CodeLlama-34b-Instruct-hf": {
+                    speed: 2,
+                    quality: 3,
+                    cost: 2,
+                },
+            },
+            notes: {
+                "meta-llama/Llama-3.1-8B-Instruct": "Best balance of speed and tool calling capability",
+                "meta-llama/Llama-3.1-70B-Instruct": "High-quality tool calling, slower inference",
+                "nvidia/Llama-3.1-Nemotron-Ultra-253B-v1": "Optimized for tool calling, requires more resources",
+                "NousResearch/Hermes-3-Llama-3.2-3B": "Lightweight with good tool calling support",
+                "codellama/CodeLlama-34b-Instruct-hf": "Excellent for code-related tool calling",
+            },
+        };
     }
+    /**
+     * Enhanced error handling with HuggingFace-specific guidance
+     */
     handleProviderError(error) {
         if (error instanceof TimeoutError) {
             return new Error(`HuggingFace request timed out: ${error.message}`);
@@ -125,14 +244,33 @@ export class HuggingFaceProvider extends BaseProvider {
         const message = errorObj?.message && typeof errorObj.message === "string"
             ? errorObj.message
             : "Unknown error";
+        // Enhanced error messages with tool calling context
         if (message.includes("API_TOKEN_INVALID") ||
             message.includes("Invalid token")) {
-            return new Error("Invalid HuggingFace API token. Please check your HUGGING_FACE_API_KEY environment variable.");
+            return new Error("❌ Invalid HuggingFace API token. Please check your HUGGINGFACE_API_KEY environment variable.");
         }
         if (message.includes("rate limit")) {
-            return new Error("HuggingFace rate limit exceeded. Please try again later.");
+            return new Error("❌ HuggingFace rate limit exceeded. Consider using a paid plan or try again later.");
+        }
+        if (message.includes("model") && message.includes("not found")) {
+            return new Error(`❌ HuggingFace model '${this.modelName}' not found.\n\nSuggestions:\n1. Check model name spelling\n2. Ensure model exists on HuggingFace Hub\n3. For tool calling, use: Llama-3.1-8B-Instruct, Hermes-3-Llama-3.2-3B, or CodeLlama-34b-Instruct-hf`);
         }
-        return new Error(`HuggingFace error: ${message}`);
+        if (message.includes("function") || message.includes("tool")) {
+            return new Error(`❌ HuggingFace tool calling error: ${message}\n\nNotes:\n1. Ensure you're using a tool-capable model (Llama-3.1+, Hermes-3+, CodeLlama)\n2. Check that your model supports function calling\n3. Verify tool schema format is correct`);
+        }
+        return new Error(`❌ HuggingFace Provider Error: ${message}`);
+    }
+    getProviderName() {
+        return "huggingface";
+    }
+    getDefaultModel() {
+        return getDefaultHuggingFaceModel();
+    }
+    /**
+     * Returns the Vercel AI SDK model instance for HuggingFace
+     */
+    getAISDKModel() {
+        return this.model;
     }
     // ===================
     // PRIVATE VALIDATION METHODS

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

@@ -9,6 +9,9 @@ import { BaseProvider } from "../core/baseProvider.js";
  */
 export declare class LiteLLMProvider extends BaseProvider {
     private model;
+    private static modelsCache;
+    private static modelsCacheTime;
+    private static readonly MODELS_CACHE_DURATION;
     constructor(modelName?: string, sdk?: unknown);
     protected getProviderName(): AIProviderName;
     protected getDefaultModel(): string;
@@ -28,16 +31,13 @@ export declare class LiteLLMProvider extends BaseProvider {
     protected executeStream(options: StreamOptions, analysisSchema?: ZodType<unknown, ZodTypeDef, unknown> | Schema<unknown>): Promise<StreamResult>;
     /**
      * Get available models from LiteLLM proxy server
-     *
-     * TODO: Implement dynamic fetching from LiteLLM's /v1/models endpoint.
-     * Currently returns a hardcoded list of commonly available models.
-     *
-     * Implementation would involve:
-     * 1. Fetch from `${baseURL}/v1/models`
-     * 2. Parse response to extract model IDs
-     * 3. Handle network errors gracefully
-     * 4. Cache results to avoid repeated API calls
+     * Dynamically fetches from /v1/models endpoint with caching and fallback
      */
     getAvailableModels(): Promise<string[]>;
+    /**
+     * Fetch available models from LiteLLM proxy /v1/models endpoint
+     * @private
+     */
+    private fetchModelsFromAPI;
     private validateStreamOptions;
 }

package/dist/lib/providers/litellm.js

@@ -34,6 +34,10 @@ const getDefaultLiteLLMModel = () => {
  */
 export class LiteLLMProvider extends BaseProvider {
     model;
+    // Cache for available models to avoid repeated API calls
+    static modelsCache = [];
+    static modelsCacheTime = 0;
+    static MODELS_CACHE_DURATION = 10 * 60 * 1000; // 10 minutes
     constructor(modelName, sdk) {
         super(modelName, "litellm", sdk);
         // Initialize LiteLLM using OpenAI SDK with explicit configuration
@@ -154,28 +158,111 @@ export class LiteLLMProvider extends BaseProvider {
     }
     /**
      * Get available models from LiteLLM proxy server
-     *
-     * TODO: Implement dynamic fetching from LiteLLM's /v1/models endpoint.
-     * Currently returns a hardcoded list of commonly available models.
-     *
-     * Implementation would involve:
-     * 1. Fetch from `${baseURL}/v1/models`
-     * 2. Parse response to extract model IDs
-     * 3. Handle network errors gracefully
-     * 4. Cache results to avoid repeated API calls
+     * Dynamically fetches from /v1/models endpoint with caching and fallback
      */
     async getAvailableModels() {
-        // Hardcoded list of commonly available models
-        // TODO: Replace with dynamic fetch from LiteLLM proxy /v1/models endpoint
-        return [
+        const functionTag = "LiteLLMProvider.getAvailableModels";
+        const now = Date.now();
+        // Check if cached models are still valid
+        if (LiteLLMProvider.modelsCache.length > 0 &&
+            now - LiteLLMProvider.modelsCacheTime <
+                LiteLLMProvider.MODELS_CACHE_DURATION) {
+            logger.debug(`[${functionTag}] Using cached models`, {
+                cacheAge: Math.round((now - LiteLLMProvider.modelsCacheTime) / 1000),
+                modelCount: LiteLLMProvider.modelsCache.length,
+            });
+            return LiteLLMProvider.modelsCache;
+        }
+        // Try to fetch models dynamically
+        try {
+            const dynamicModels = await this.fetchModelsFromAPI();
+            if (dynamicModels.length > 0) {
+                // Cache successful result
+                LiteLLMProvider.modelsCache = dynamicModels;
+                LiteLLMProvider.modelsCacheTime = now;
+                logger.debug(`[${functionTag}] Successfully fetched models from API`, {
+                    modelCount: dynamicModels.length,
+                });
+                return dynamicModels;
+            }
+        }
+        catch (error) {
+            logger.warn(`[${functionTag}] Failed to fetch models from API, using fallback`, {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        // Fallback to hardcoded list if API fetch fails
+        const fallbackModels = [
             "openai/gpt-4o",
             "openai/gpt-4o-mini",
-            "anthropic/claude-3-5-sonnet",
-            "anthropic/claude-3-haiku",
+            "openai/gpt-3.5-turbo",
+            "anthropic/claude-3-5-sonnet-20241022",
+            "anthropic/claude-3-haiku-20240307",
             "google/gemini-2.0-flash",
-            "mistral/mistral-large",
-            "mistral/mistral-medium",
+            "google/gemini-1.5-pro",
+            "mistral/mistral-large-latest",
+            "mistral/mistral-medium-latest",
+            "meta-llama/llama-3.1-8b-instruct",
+            "meta-llama/llama-3.1-70b-instruct",
         ];
+        logger.debug(`[${functionTag}] Using fallback model list`, {
+            modelCount: fallbackModels.length,
+        });
+        return fallbackModels;
+    }
+    /**
+     * Fetch available models from LiteLLM proxy /v1/models endpoint
+     * @private
+     */
+    async fetchModelsFromAPI() {
+        const functionTag = "LiteLLMProvider.fetchModelsFromAPI";
+        const config = getLiteLLMConfig();
+        const modelsUrl = `${config.baseURL}/v1/models`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 5000); // 5 second timeout
+        try {
+            logger.debug(`[${functionTag}] Fetching models from ${modelsUrl}`);
+            const response = await fetch(modelsUrl, {
+                method: "GET",
+                headers: {
+                    Authorization: `Bearer ${config.apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+            const data = await response.json();
+            // Parse OpenAI-compatible models response
+            if (data && Array.isArray(data.data)) {
+                const models = data.data
+                    .map((model) => typeof model === "object" &&
+                    model !== null &&
+                    "id" in model &&
+                    typeof model.id === "string"
+                    ? model.id
+                    : undefined)
+                    .filter((id) => typeof id === "string" && id.length > 0)
+                    .sort();
+                logger.debug(`[${functionTag}] Successfully parsed models`, {
+                    totalModels: models.length,
+                    sampleModels: models.slice(0, 5),
+                });
+                return models;
+            }
+            else {
+                throw new Error("Invalid response format: expected data.data array");
+            }
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new Error("Request timed out after 5 seconds");
+            }
+            throw error;
+        }
     }
     // ===================
     // PRIVATE VALIDATION METHODS

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

@@ -28,30 +28,51 @@ export declare class OllamaProvider extends BaseProvider {
      */
     protected getAISDKModel(): LanguageModelV1;
     /**
-     * Ollama tool/function calling support is currently disabled due to integration issues.
+     * Ollama Tool Calling Support (Enhanced 2025)
      *
-     * **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
+     * Uses configurable model list from ModelConfiguration instead of hardcoded values.
+     * Tool-capable models can be configured via OLLAMA_TOOL_CAPABLE_MODELS environment variable.
      *
-     * **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.)
+     * **Configuration Options:**
+     * - Environment variable: OLLAMA_TOOL_CAPABLE_MODELS (comma-separated list)
+     * - Configuration file: providers.ollama.modelBehavior.toolCapableModels
+     * - Fallback: Default list of known tool-capable models
      *
-     * **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
+     * **Implementation Features:**
+     * - Direct Ollama API integration (/v1/chat/completions)
+     * - Automatic tool schema conversion to Ollama format
+     * - Streaming tool calls with incremental response parsing
+     * - Model compatibility validation and fallback handling
      *
-     * @returns false to disable tools by default
+     * @returns true for supported models, false for unsupported models
      */
     supportsTools(): boolean;
     protected executeStream(options: StreamOptions, analysisSchema?: ZodType<unknown, ZodTypeDef, unknown> | Schema<unknown>): Promise<StreamResult>;
+    /**
+     * Execute streaming with Ollama's function calling support
+     * Uses the /v1/chat/completions endpoint with tools parameter
+     */
+    private executeStreamWithTools;
+    /**
+     * Execute streaming without tools using the generate API
+     * Fallback for non-tool scenarios or when chat API is unavailable
+     */
+    private executeStreamWithoutTools;
+    /**
+     * Convert AI SDK tools format to Ollama's function calling format
+     */
+    private convertToolsToOllamaFormat;
+    /**
+     * Create stream generator for Ollama chat API with tool call support
+     */
+    private createOllamaChatStream;
+    /**
+     * Format tool calls for display when tools aren't executed directly
+     */
+    private formatToolCallForDisplay;
+    /**
+     * Create stream generator for Ollama generate API (non-tool mode)
+     */
     private createOllamaStream;
     protected handleProviderError(error: unknown): Error;
     private validateStreamOptions;
@@ -67,5 +88,19 @@ export declare class OllamaProvider extends BaseProvider {
      * Check if a specific model is available
      */
     isModelAvailable(modelName: string): Promise<boolean>;
+    /**
+     * Get recommendations for tool-calling capable Ollama models
+     * Provides guidance for users who want to use function calling locally
+     */
+    static getToolCallingRecommendations(): {
+        recommended: string[];
+        performance: Record<string, {
+            speed: number;
+            quality: number;
+            size: string;
+        }>;
+        notes: Record<string, string>;
+        installation: Record<string, string>;
+    };
 }
 export default OllamaProvider;