feat: add web search support for AI expert mode

- Add web search capabilities for OpenAI (O3), Anthropic (Claude 4), Google (Gemini 2.5), and xAI (Grok 4)
- Implement provider-specific web search tools (web_search_preview, webSearch_20250305, googleSearch, built-in)
- Fix Anthropic model IDs to match Vercel AI SDK (claude-opus-4-20250514, claude-sonnet-4-20250514)
- Add warning when web search is requested for unsupported models
- Update documentation with web search usage and cost approval guidelines
- Enable web search by default for supported models with --no-web-search option to disable

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: avivsinai

CLAUDE.md

@@ -132,6 +132,7 @@ After recent changes:
 - Debug logging uses the `debug` npm package with namespace `promptcode:*`
 - All tests pass - run with `cd packages/cli && bun test`
 - To release: Create a tag and push to trigger GitHub Actions
+- DO NOT make shortcuts, always use the most idiomatic and generic solution
 
 <!-- PROMPTCODE-CLI-START -->
 # PromptCode CLI
@@ -147,6 +148,12 @@ promptcode generate src/api/handler.ts src/utils/*.ts
 # Ask AI experts questions with code context
 promptcode expert "Why is this slow?" src/api/handler.ts
 
+# Web search is enabled by default for supported models (O3, Gemini, Claude, Grok)
+promptcode expert "What are the latest React 19 features?" src/components/*.tsx
+
+# Explicitly disable web search if needed
+promptcode expert "Review this code" src/api/*.ts --no-web-search
+
 # Use presets for common file patterns
 promptcode preset list                    # See available presets
 promptcode preset info <name>             # Show preset details & token count
@@ -193,12 +200,41 @@ promptcode generate src/**/*.ts --instructions "Find performance bottlenecks"
 promptcode expert "Review this code for security issues" src/api/**/*.ts
 ```
 
+## Web Search Support
+
+The expert command now includes built-in web search capabilities for supported models:
+
+**Models with Web Search:**
+- **OpenAI**: O3, O3 Pro, O3 Mini - Uses web_search_preview tool
+- **Google**: Gemini 2.5 Pro/Flash - Uses Google Search grounding
+- **Anthropic**: Claude Opus 4, Sonnet 4 - Uses web_search tool
+- **xAI**: Grok 4 - Has built-in real-time web access
+
+**Usage:**
+```bash
+# Web search is enabled by default for supported models
+promptcode expert "What are the breaking changes in TypeScript 5.8?"
+
+# Explicitly enable web search
+promptcode expert "Latest best practices for React Server Components" --web-search
+
+# Disable web search when you don't need current information
+promptcode expert "Review this code for bugs" src/**/*.ts --no-web-search
+```
+
+**Benefits:**
+- Access to current documentation and recent updates
+- Real-time information for rapidly evolving technologies
+- Grounded responses with source citations
+- Better accuracy for questions about recent events or releases
+
 ## Tips for AI Agents
 
 1. **Always check token counts** - Use `promptcode preset info` to see total tokens before generating
 2. **Be specific with patterns** - Use `src/api/*.ts` not `**/*.ts` to avoid huge contexts
 3. **Leverage existing presets** - Check `promptcode preset list` before creating new ones
 4. **Use descriptive preset names** - `auth-system` not `preset1`
+5. **Use web search for current info** - Enabled by default for questions about latest features, docs, or best practices
 
 ## Important: Cost Approval for AI Agents
 

packages/cli/src/commands/expert.ts

@@ -23,6 +23,7 @@ interface ExpertOptions {
   models?: boolean;
   savePreset?: string;
   yes?: boolean;
+  webSearch?: boolean;
 }
 
 const SYSTEM_PROMPT = `You are an expert software engineer helping analyze and improve code. Provide constructive, actionable feedback.
@@ -294,6 +295,19 @@ export async function expertCommand(question: string | undefined, options: Exper
       console.log(chalk.gray('⏳ This may take a moment...\n'));
     }
 
+    // Determine web search setting
+    // Commander.js sets webSearch to false when --no-web-search is used
+    // undefined means use default (enabled for supported models)
+    const webSearchEnabled = options.webSearch;
+    
+    // Show web search status and warnings
+    if (modelConfig.supportsWebSearch && webSearchEnabled !== false) {
+      console.log(chalk.cyan('🔍 Web search enabled for current information\n'));
+    } else if (webSearchEnabled === true && !modelConfig.supportsWebSearch) {
+      // User explicitly requested web search but model doesn't support it
+      console.log(chalk.yellow(`⚠️  ${modelConfig.name} does not support web search. Proceeding without web search.\n`));
+    }
+    
     // Call AI
     const startTime = Date.now();
     let response: { text: string; usage?: any };
@@ -303,12 +317,14 @@ export async function expertCommand(question: string | undefined, options: Exper
         systemPrompt: SYSTEM_PROMPT,
         maxTokens: availableTokens,
         onChunk: (chunk) => process.stdout.write(chunk),
+        webSearch: webSearchEnabled,
       });
       console.log(); // Add newline after streaming
     } else {
       response = await aiProvider.generateText(modelKey, fullPrompt, {
         systemPrompt: SYSTEM_PROMPT,
         maxTokens: availableTokens,
+        webSearch: webSearchEnabled,
       });
     }
 

packages/cli/src/index.ts

@@ -249,6 +249,8 @@ Examples:
   .option('--stream', 'stream response in real-time')
   .option('--save-preset <name>', 'save file patterns as a preset')
   .option('-y, --yes', 'automatically confirm prompts')
+  .option('--web-search', 'enable web search for current information (enabled by default for supported models)')
+  .option('--no-web-search', 'disable web search even for supported models')
   .action(async (question, options) => {
     await expertCommand(question, options);
   });

packages/cli/src/providers/ai-provider.ts

@@ -4,9 +4,9 @@
  * Now powered by ConfigService (no process.env mutation side-effects).
  */
 
-import { createOpenAI } from '@ai-sdk/openai';
-import { createAnthropic } from '@ai-sdk/anthropic';
-import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import { createOpenAI, openai } from '@ai-sdk/openai';
+import { createAnthropic, anthropic } from '@ai-sdk/anthropic';
+import { createGoogleGenerativeAI, google } from '@ai-sdk/google';
 import { createXai } from '@ai-sdk/xai';
 import { generateText, streamText, LanguageModel } from 'ai';
 import { MODELS, ModelConfig } from './models';
@@ -118,8 +118,41 @@ export class AIProvider {
    * Helpers
    * ──────────────────────────── */
 
+  private getWebSearchTools(modelKey: string): Record<string, any> | undefined {
+    const config = MODELS[modelKey];
+    if (!config || !config.supportsWebSearch) return undefined;
+
+    switch (config.provider) {
+      case 'openai':
+        // OpenAI requires using the responses API for web search
+        // This is handled in getModel method with a special case
+        return {
+          web_search_preview: openai.tools.webSearchPreview({})
+        };
+      
+      case 'google':
+        return {
+          google_search: google.tools.googleSearch({})
+        };
+      
+      case 'anthropic':
+        // Anthropic web search tool - using the provider-defined tool
+        return {
+          web_search: anthropic.tools.webSearch_20250305({
+            maxUses: 5
+          })
+        };
+      
+      case 'xai':
+        // xAI Grok has built-in web access, no explicit tool needed
+        return undefined;
+      
+      default:
+        return undefined;
+    }
+  }
 
-  private getModel(modelKey: string): LanguageModel {
+  private getModel(modelKey: string, useWebSearch: boolean = false): LanguageModel {
     // Skip model initialization in mock mode
     if (process.env.PROMPTCODE_MOCK_LLM === '1') {
       return {} as LanguageModel; // Return dummy model object
@@ -128,6 +161,21 @@ export class AIProvider {
     const config = MODELS[modelKey];
     if (!config) throw new Error(`Unknown model: ${modelKey}`);
 
+    // Special handling for OpenAI with web search
+    if (config.provider === 'openai' && useWebSearch && config.supportsWebSearch) {
+      const keys = this.config.getAllKeys();
+      if (!keys.openai) {
+        throw new Error(
+          `API key not configured for openai. ` +
+          `Set via "promptcode config --set-openai-key <key>" ` +
+          `or export OPENAI_API_KEY=...`
+        );
+      }
+      // Use responses API for web search support
+      const openaiProvider = createOpenAI({ apiKey: keys.openai });
+      return openaiProvider.responses(config.modelId);
+    }
+
     const providerInstance = this.providers[config.provider];
     if (!providerInstance) {
       const envName = config.provider.toUpperCase() + '_API_KEY';
@@ -152,6 +200,7 @@ export class AIProvider {
       maxTokens?: number;
       temperature?: number;
       systemPrompt?: string;
+      webSearch?: boolean;
     } = {}
   ): Promise<AIResponse> {
     // Mock mode for testing
@@ -167,7 +216,9 @@ export class AIProvider {
       };
     }
 
-    const model = this.getModel(modelKey);
+    const modelConfig = MODELS[modelKey];
+    const enableWebSearch = options.webSearch !== false && modelConfig?.supportsWebSearch;
+    const model = this.getModel(modelKey, enableWebSearch);
 
     const messages: any[] = [];
 
@@ -177,12 +228,23 @@ export class AIProvider {
 
     messages.push({ role: 'user', content: prompt });
 
-    const result = await generateText({
+    // Prepare the request configuration
+    const requestConfig: any = {
       model,
       messages,
       maxCompletionTokens: options.maxTokens || 4096,
       temperature: options.temperature || 0.7,
-    });
+    };
+    
+    // Add web search tools if enabled
+    if (enableWebSearch) {
+      const tools = this.getWebSearchTools(modelKey);
+      if (tools) {
+        requestConfig.tools = tools;
+      }
+    }
+    
+    const result = await generateText(requestConfig);
 
     return {
       text: result.text,
@@ -198,6 +260,7 @@ export class AIProvider {
       temperature?: number;
       systemPrompt?: string;
       onChunk?: (chunk: string) => void;
+      webSearch?: boolean;
     } = {}
   ): Promise<AIResponse> {
     // Mock mode for testing
@@ -222,7 +285,9 @@ export class AIProvider {
       };
     }
 
-    const model = this.getModel(modelKey);
+    const modelConfig = MODELS[modelKey];
+    const enableWebSearch = options.webSearch !== false && modelConfig?.supportsWebSearch;
+    const model = this.getModel(modelKey, enableWebSearch);
 
     const messages: any[] = [];
 
@@ -232,12 +297,23 @@ export class AIProvider {
 
     messages.push({ role: 'user', content: prompt });
 
-    const result = await streamText({
+    // Prepare the request configuration
+    const requestConfig: any = {
       model,
       messages,
       maxCompletionTokens: options.maxTokens || 4096,
       temperature: options.temperature || 0.7,
-    });
+    };
+    
+    // Add web search tools if enabled
+    if (enableWebSearch) {
+      const tools = this.getWebSearchTools(modelKey);
+      if (tools) {
+        requestConfig.tools = tools;
+      }
+    }
+    
+    const result = await streamText(requestConfig);
 
     let fullText = '';
     for await (const chunk of result.textStream) {

packages/cli/src/providers/models.ts

@@ -28,6 +28,7 @@ const ModelSchema = z.object({
     input: z.number().nonnegative(),
     output: z.number().nonnegative(),
   }),
+  supportsWebSearch: z.boolean().optional().default(false),
 });
 
 // Type derives from schema so TS & runtime always match
@@ -41,41 +42,46 @@ export const MODELS: Record<string, ModelConfig> = {
     name: 'O3',
     description: 'Advanced reasoning model with deep thinking capabilities',
     contextWindow: 200000,
-    pricing: { input: 2, output: 8 }
+    pricing: { input: 2, output: 8 },
+    supportsWebSearch: true
   },
   'o3-pro': {
     provider: 'openai',
     modelId: 'o3-pro',
     name: 'O3 Pro',
     description: 'Most advanced reasoning model with extended thinking',
     contextWindow: 200000,
-    pricing: { input: 20, output: 80 }
+    pricing: { input: 20, output: 80 },
+    supportsWebSearch: true
   },
   'o3-mini': {
     provider: 'openai',
     modelId: 'o3-mini',
     name: 'O3 Mini',
     description: 'Fast reasoning model for quick tasks',
     contextWindow: 200000,
-    pricing: { input: 0.5, output: 2 }
+    pricing: { input: 0.5, output: 2 },
+    supportsWebSearch: true
   },
 
   // Anthropic models (2025 SOTA)
   'opus-4': {
     provider: 'anthropic',
-    modelId: 'claude-opus-4-20250101',
+    modelId: 'claude-opus-4-20250514',
     name: 'Claude Opus 4',
     description: 'Most advanced Claude model with breakthrough capabilities',
     contextWindow: 500000,
-    pricing: { input: 25, output: 100 }
+    pricing: { input: 25, output: 100 },
+    supportsWebSearch: true
   },
   'sonnet-4': {
     provider: 'anthropic',
-    modelId: 'claude-sonnet-4-20250101',
+    modelId: 'claude-sonnet-4-20250514',
     name: 'Claude Sonnet 4',
     description: 'Balanced power and efficiency for production use',
     contextWindow: 500000,
-    pricing: { input: 5, output: 20 }
+    pricing: { input: 5, output: 20 },
+    supportsWebSearch: true
   },
 
   // Google models (2025 SOTA)
@@ -85,15 +91,17 @@ export const MODELS: Record<string, ModelConfig> = {
     name: 'Gemini 2.5 Pro',
     description: 'Latest Gemini with enhanced multimodal understanding',
     contextWindow: 3000000,
-    pricing: { input: 3, output: 12 }
+    pricing: { input: 3, output: 12 },
+    supportsWebSearch: true
   },
   'gemini-2.5-flash': {
     provider: 'google',
     modelId: 'gemini-2.5-flash',
     name: 'Gemini 2.5 Flash',
     description: 'Ultra-fast model for real-time applications',
     contextWindow: 1000000,
-    pricing: { input: 0.3, output: 1.2 }
+    pricing: { input: 0.3, output: 1.2 },
+    supportsWebSearch: true
   },
 
   // xAI models (2025 SOTA)
@@ -103,7 +111,8 @@ export const MODELS: Record<string, ModelConfig> = {
     name: 'Grok 4',
     description: 'xAI\'s most advanced model with real-time web access',
     contextWindow: 200000,
-    pricing: { input: 5, output: 15 }
+    pricing: { input: 5, output: 15 },
+    supportsWebSearch: true
   }
 };