@juspay/neurolink 7.14.7 → 7.15.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [7.15.0](https://github.com/juspay/neurolink/compare/v7.14.8...v7.15.0) (2025-08-19)
+
+### Features
+
+- **(tools):** add websearch tool using Gemini AI for Google search integration BZ-43347 ([bcd5160](https://github.com/juspay/neurolink/commit/bcd516019db8a6b89ba6ecb39037b257fd955df0))
+
+## [7.14.8](https://github.com/juspay/neurolink/compare/v7.14.7...v7.14.8) (2025-08-19)
+
+### Bug Fixes
+
+- **(mcp):** implement generic error handling for all MCP server response formats ([5aa707a](https://github.com/juspay/neurolink/commit/5aa707aa9874ed76ab067a1f7fb6e8301519ce7f))
+
 ## [7.14.7](https://github.com/juspay/neurolink/compare/v7.14.6...v7.14.7) (2025-08-18)
 
 ### Bug Fixes

package/README.md

@@ -284,6 +284,11 @@ echo 'OPENAI_API_KEY="sk-your-openai-key"' > .env
 echo 'GOOGLE_AI_API_KEY="AIza-your-google-ai-key"' >> .env
 echo 'AWS_ACCESS_KEY_ID="your-aws-access-key"' >> .env
 
+# 🆕 NEW: Google Vertex AI for Websearch Tool
+echo 'GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"' >> .env
+echo 'GOOGLE_VERTEX_PROJECT="your-gcp-project-id"' >> .env
+echo 'GOOGLE_VERTEX_LOCATION="us-central1"' >> .env
+
 # Test configuration
 npx @juspay/neurolink status
 ```
@@ -337,12 +342,63 @@ console.log(productData.name, productData.price, productData.features);
 
 **📖 [Complete Setup Guide](./docs/CONFIGURATION.md)** - All providers with detailed instructions
 
+## 🔍 **NEW: Websearch Tool with Google Vertex AI Grounding**
+
+**NeuroLink now includes a powerful websearch tool** that uses Google's native search grounding technology for real-time web information:
+
+- **🔍 Native Google Search** - Uses Google's search grounding via Vertex AI
+- **🎯 Real-time Results** - Access current web information during AI conversations
+- **🔒 Credential Protection** - Only activates when Google Vertex AI credentials are properly configured
+
+### Quick Setup & Test
+
+```bash
+# 1. Build the project first
+pnpm run build
+
+# 2. Set up environment variables (see detailed setup below)
+cp .env.example .env
+# Edit .env with your Google Vertex AI credentials
+
+# 3. Test the websearch tool directly
+node test-websearch-grounding.j
+```
+
+### Complete Google Vertex AI Setup
+
+#### Configure Environment Variables
+
+```bash
+# Add to your .env file
+GOOGLE_APPLICATION_CREDENTIALS="/absolute/path/to/neurolink-service-account.json"
+GOOGLE_VERTEX_PROJECT="YOUR-PROJECT-ID"
+GOOGLE_VERTEX_LOCATION="us-central1"
+```
+
+#### Step 3: Test the Setup
+
+````bash
+# Build the project first
+pnpm run build
+
+# Run the dedicated test script
+node test-websearch-grounding.js
+
+### Using the Websearch Tool
+
+#### CLI Usage (Works with All Providers)
+
+# With specific providers - websearch works across all providers
+npx @juspay/neurolink generate "Weather in Tokyo now" --provider vertex
+
+**Note:** The websearch tool gracefully handles missing credentials - it only activates when valid Google Vertex AI credentials are configured. Without proper credentials, other tools continue to work normally and AI responses fall back to training data.
+
 ## ✨ Key Features
 
 - 🔗 **LiteLLM Integration** - **Access 100+ AI models** from all major providers through unified interface
 - 🔍 **Smart Model Auto-Discovery** - OpenAI Compatible provider automatically detects available models via `/v1/models` endpoint
 - 🏭 **Factory Pattern Architecture** - Unified provider management with BaseProvider inheritance
-- 🔧 **Tools-First Design** - All providers automatically include 6 direct tools (getCurrentTime, readFile, listDirectory, calculateMath, writeFile, searchFiles)
+- 🔧 **Tools-First Design** - All providers automatically include 7 direct tools (getCurrentTime, readFile, listDirectory, calculateMath, writeFile, searchFiles, websearchGrounding)
 - 🔄 **12 AI Providers** - OpenAI, Bedrock, Vertex AI, Google AI Studio, Anthropic, Azure, **LiteLLM**, **OpenAI Compatible**, Hugging Face, Ollama, Mistral AI, **SageMaker**
 - 💰 **Cost Optimization** - Automatic selection of cheapest models and LiteLLM routing
 - ⚡ **Automatic Fallback** - Never fail when providers are down, intelligent provider switching
@@ -398,7 +454,7 @@ const result = await neurolink.generate({
 
 # Discover available MCP servers
 npx @juspay/neurolink mcp discover --format table
-```
+````
 
 ### 🔧 SDK Custom Tool Registration (NEW!)
 

package/dist/agent/directTools.d.ts

@@ -346,6 +346,139 @@ export declare const directAgentTools: {
             count?: undefined;
         }>;
     };
+    websearchGrounding: import("ai").Tool<z.ZodObject<{
+        query: z.ZodString;
+        maxResults: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        maxWords: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    }, "strip", z.ZodTypeAny, {
+        query: string;
+        maxResults: number;
+        maxWords: number;
+    }, {
+        query: string;
+        maxResults?: number | undefined;
+        maxWords?: number | undefined;
+    }>, {
+        success: boolean;
+        error: string;
+        requiredEnvVars: string[];
+        query?: undefined;
+        searchResults?: undefined;
+        rawContent?: undefined;
+        totalResults?: undefined;
+        provider?: undefined;
+        model?: undefined;
+        responseTime?: undefined;
+        timestamp?: undefined;
+        grounded?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        query: string;
+        requiredEnvVars?: undefined;
+        searchResults?: undefined;
+        rawContent?: undefined;
+        totalResults?: undefined;
+        provider?: undefined;
+        model?: undefined;
+        responseTime?: undefined;
+        timestamp?: undefined;
+        grounded?: undefined;
+    } | {
+        success: boolean;
+        query: string;
+        searchResults: {
+            title: string;
+            url: string;
+            snippet: string;
+            domain: string;
+        }[];
+        rawContent: string;
+        totalResults: number;
+        provider: string;
+        model: string;
+        responseTime: number;
+        timestamp: number;
+        grounded: boolean;
+        error?: undefined;
+        requiredEnvVars?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        query: string;
+        provider: string;
+        requiredEnvVars?: undefined;
+        searchResults?: undefined;
+        rawContent?: undefined;
+        totalResults?: undefined;
+        model?: undefined;
+        responseTime?: undefined;
+        timestamp?: undefined;
+        grounded?: undefined;
+    }> & {
+        execute: (args: {
+            query: string;
+            maxResults: number;
+            maxWords: number;
+        }, options: import("ai").ToolExecutionOptions) => PromiseLike<{
+            success: boolean;
+            error: string;
+            requiredEnvVars: string[];
+            query?: undefined;
+            searchResults?: undefined;
+            rawContent?: undefined;
+            totalResults?: undefined;
+            provider?: undefined;
+            model?: undefined;
+            responseTime?: undefined;
+            timestamp?: undefined;
+            grounded?: undefined;
+        } | {
+            success: boolean;
+            error: string;
+            query: string;
+            requiredEnvVars?: undefined;
+            searchResults?: undefined;
+            rawContent?: undefined;
+            totalResults?: undefined;
+            provider?: undefined;
+            model?: undefined;
+            responseTime?: undefined;
+            timestamp?: undefined;
+            grounded?: undefined;
+        } | {
+            success: boolean;
+            query: string;
+            searchResults: {
+                title: string;
+                url: string;
+                snippet: string;
+                domain: string;
+            }[];
+            rawContent: string;
+            totalResults: number;
+            provider: string;
+            model: string;
+            responseTime: number;
+            timestamp: number;
+            grounded: boolean;
+            error?: undefined;
+            requiredEnvVars?: undefined;
+        } | {
+            success: boolean;
+            error: string;
+            query: string;
+            provider: string;
+            requiredEnvVars?: undefined;
+            searchResults?: undefined;
+            rawContent?: undefined;
+            totalResults?: undefined;
+            model?: undefined;
+            responseTime?: undefined;
+            timestamp?: undefined;
+            grounded?: undefined;
+        }>;
+    };
 };
 /**
  * Type aliases for specific tool categories

package/dist/agent/directTools.js

@@ -7,6 +7,18 @@ import { z } from "zod";
 import * as fs from "fs";
 import * as path from "path";
 import { logger } from "../utils/logger.js";
+import { VertexAI } from "@google-cloud/vertexai";
+// Runtime Google Search tool creation - bypasses TypeScript strict typing
+function createGoogleSearchTools() {
+    const searchTool = {};
+    // Dynamically assign google_search property at runtime
+    Object.defineProperty(searchTool, "google_search", {
+        value: {},
+        enumerable: true,
+        configurable: true,
+    });
+    return [searchTool];
+}
 /**
  * Direct tool definitions that work immediately with Gemini/AI SDK
  * These bypass MCP complexity and provide reliable agent functionality
@@ -324,6 +336,128 @@ export const directAgentTools = {
             }
         },
     }),
+    websearchGrounding: tool({
+        description: "Search the web for current information using Google Search grounding. Returns raw search data for AI processing.",
+        parameters: z.object({
+            query: z.string().describe("Search query to find information about"),
+            maxResults: z
+                .number()
+                .optional()
+                .default(3)
+                .describe("Maximum number of search results to return (1-5)"),
+            maxWords: z
+                .number()
+                .optional()
+                .default(50)
+                .describe("Maximum number of words in the response 50"),
+        }),
+        execute: async ({ query, maxResults = 3, maxWords = 50 }) => {
+            try {
+                const hasCredentials = process.env.GOOGLE_APPLICATION_CREDENTIALS;
+                const hasProjectId = process.env.GOOGLE_VERTEX_PROJECT;
+                const projectLocation = process.env.GOOGLE_VERTEX_LOCATION || "us-central1";
+                if (!hasCredentials || !hasProjectId) {
+                    return {
+                        success: false,
+                        error: "Google Vertex AI credentials not configured. Please set GOOGLE_APPLICATION_CREDENTIALS and GOOGLE_VERTEX_PROJECT environment variables.",
+                        requiredEnvVars: [
+                            "GOOGLE_APPLICATION_CREDENTIALS",
+                            "GOOGLE_VERTEX_PROJECT",
+                        ],
+                    };
+                }
+                const limitedResults = Math.min(Math.max(maxResults, 1), 5);
+                const vertex_ai = new VertexAI({
+                    project: hasProjectId,
+                    location: projectLocation,
+                });
+                const websearchModel = "gemini-2.5-flash-lite";
+                const model = vertex_ai.getGenerativeModel({
+                    model: websearchModel,
+                    tools: createGoogleSearchTools(),
+                });
+                // Search query with word limit constraint
+                const searchPrompt = `Search for: "${query}". Provide a concise summary in no more than ${maxWords} words.`;
+                const startTime = Date.now();
+                const response = await model.generateContent({
+                    contents: [
+                        {
+                            role: "user",
+                            parts: [{ text: searchPrompt }],
+                        },
+                    ],
+                });
+                const responseTime = Date.now() - startTime;
+                // Extract grounding metadata and search results
+                const result = response.response;
+                const candidates = result.candidates;
+                if (!candidates || candidates.length === 0) {
+                    return {
+                        success: false,
+                        error: "No search results returned",
+                        query,
+                    };
+                }
+                const content = candidates[0].content;
+                if (!content || !content.parts || content.parts.length === 0) {
+                    return {
+                        success: false,
+                        error: "No search content found",
+                        query,
+                    };
+                }
+                // Extract raw search content
+                const searchContent = content.parts[0].text || "";
+                // Extract grounding sources if available
+                const groundingMetadata = candidates[0]?.groundingMetadata;
+                const searchResults = [];
+                if (groundingMetadata?.groundingChunks) {
+                    for (const chunk of groundingMetadata.groundingChunks.slice(0, limitedResults)) {
+                        if (chunk.web) {
+                            searchResults.push({
+                                title: chunk.web.title || "No title",
+                                url: chunk.web.uri || "",
+                                snippet: searchContent, // Use full content since maxWords already limits length
+                                domain: chunk.web.uri
+                                    ? new URL(chunk.web.uri).hostname
+                                    : "unknown",
+                            });
+                        }
+                    }
+                }
+                // If no grounding metadata, create basic result structure
+                if (searchResults.length === 0) {
+                    searchResults.push({
+                        title: `Search results for: ${query}`,
+                        url: "",
+                        snippet: searchContent,
+                        domain: "google-search",
+                    });
+                }
+                return {
+                    success: true,
+                    query,
+                    searchResults,
+                    rawContent: searchContent,
+                    totalResults: searchResults.length,
+                    provider: "google-search-grounding",
+                    model: websearchModel,
+                    responseTime,
+                    timestamp: startTime,
+                    grounded: true,
+                };
+            }
+            catch (error) {
+                logger.error("Web search grounding error:", error);
+                return {
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                    query,
+                    provider: "google-search-grounding",
+                };
+            }
+        },
+    }),
 };
 // eslint-disable-next-line no-redeclare
 export function getToolsForCategory(category = "all") {

package/dist/core/baseProvider.js

@@ -395,12 +395,41 @@ export class BaseProvider {
                             parameters: z.object({}), // Use empty schema for custom tools
                             execute: async (params) => {
                                 logger.debug(`[BaseProvider] Executing custom tool: ${toolName}`, { params });
-                                // Use the tool executor if available (from setupToolExecutor)
-                                if (this.toolExecutor) {
-                                    return await this.toolExecutor(toolName, params);
+                                try {
+                                    // Use the tool executor if available (from setupToolExecutor)
+                                    let result;
+                                    if (this.toolExecutor) {
+                                        result = await this.toolExecutor(toolName, params);
+                                    }
+                                    else {
+                                        result = await typedToolDef.execute(params);
+                                    }
+                                    // Log successful execution
+                                    logger.debug(`[BaseProvider] Tool execution successful: ${toolName}`, {
+                                        resultType: typeof result,
+                                        hasResult: result !== null && result !== undefined,
+                                        toolName,
+                                    });
+                                    return result;
                                 }
-                                else {
-                                    return await typedToolDef.execute(params);
+                                catch (error) {
+                                    logger.warn(`[BaseProvider] Tool execution failed: ${toolName}`, {
+                                        error: error instanceof Error ? error.message : String(error),
+                                        params,
+                                        toolName,
+                                    });
+                                    // GENERIC ERROR HANDLING FOR ALL MCP TOOLS:
+                                    // Return a generic error object that works with any MCP server
+                                    // The AI can interpret this and try different approaches
+                                    return {
+                                        _neurolinkToolError: true,
+                                        toolName: toolName,
+                                        error: error instanceof Error ? error.message : String(error),
+                                        timestamp: new Date().toISOString(),
+                                        params: params,
+                                        // Keep it simple - just indicate an error occurred
+                                        message: `Error calling ${toolName}: ${error instanceof Error ? error.message : String(error)}`
+                                    };
                                 }
                             },
                         });

package/dist/lib/agent/directTools.d.ts

@@ -346,6 +346,139 @@ export declare const directAgentTools: {
             count?: undefined;
         }>;
     };
+    websearchGrounding: import("ai").Tool<z.ZodObject<{
+        query: z.ZodString;
+        maxResults: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        maxWords: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    }, "strip", z.ZodTypeAny, {
+        query: string;
+        maxResults: number;
+        maxWords: number;
+    }, {
+        query: string;
+        maxResults?: number | undefined;
+        maxWords?: number | undefined;
+    }>, {
+        success: boolean;
+        error: string;
+        requiredEnvVars: string[];
+        query?: undefined;
+        searchResults?: undefined;
+        rawContent?: undefined;
+        totalResults?: undefined;
+        provider?: undefined;
+        model?: undefined;
+        responseTime?: undefined;
+        timestamp?: undefined;
+        grounded?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        query: string;
+        requiredEnvVars?: undefined;
+        searchResults?: undefined;
+        rawContent?: undefined;
+        totalResults?: undefined;
+        provider?: undefined;
+        model?: undefined;
+        responseTime?: undefined;
+        timestamp?: undefined;
+        grounded?: undefined;
+    } | {
+        success: boolean;
+        query: string;
+        searchResults: {
+            title: string;
+            url: string;
+            snippet: string;
+            domain: string;
+        }[];
+        rawContent: string;
+        totalResults: number;
+        provider: string;
+        model: string;
+        responseTime: number;
+        timestamp: number;
+        grounded: boolean;
+        error?: undefined;
+        requiredEnvVars?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        query: string;
+        provider: string;
+        requiredEnvVars?: undefined;
+        searchResults?: undefined;
+        rawContent?: undefined;
+        totalResults?: undefined;
+        model?: undefined;
+        responseTime?: undefined;
+        timestamp?: undefined;
+        grounded?: undefined;
+    }> & {
+        execute: (args: {
+            query: string;
+            maxResults: number;
+            maxWords: number;
+        }, options: import("ai").ToolExecutionOptions) => PromiseLike<{
+            success: boolean;
+            error: string;
+            requiredEnvVars: string[];
+            query?: undefined;
+            searchResults?: undefined;
+            rawContent?: undefined;
+            totalResults?: undefined;
+            provider?: undefined;
+            model?: undefined;
+            responseTime?: undefined;
+            timestamp?: undefined;
+            grounded?: undefined;
+        } | {
+            success: boolean;
+            error: string;
+            query: string;
+            requiredEnvVars?: undefined;
+            searchResults?: undefined;
+            rawContent?: undefined;
+            totalResults?: undefined;
+            provider?: undefined;
+            model?: undefined;
+            responseTime?: undefined;
+            timestamp?: undefined;
+            grounded?: undefined;
+        } | {
+            success: boolean;
+            query: string;
+            searchResults: {
+                title: string;
+                url: string;
+                snippet: string;
+                domain: string;
+            }[];
+            rawContent: string;
+            totalResults: number;
+            provider: string;
+            model: string;
+            responseTime: number;
+            timestamp: number;
+            grounded: boolean;
+            error?: undefined;
+            requiredEnvVars?: undefined;
+        } | {
+            success: boolean;
+            error: string;
+            query: string;
+            provider: string;
+            requiredEnvVars?: undefined;
+            searchResults?: undefined;
+            rawContent?: undefined;
+            totalResults?: undefined;
+            model?: undefined;
+            responseTime?: undefined;
+            timestamp?: undefined;
+            grounded?: undefined;
+        }>;
+    };
 };
 /**
  * Type aliases for specific tool categories