feat(research): Introduce research API with provider implementations, docs and tests

ts/provider.anthropic.ts

@@ -1,13 +1,16 @@
 import * as plugins from './plugins.js';
 import * as paths from './paths.js';
 import { MultiModalModel } from './abstract.classes.multimodal.js';
-import type { ChatOptions, ChatResponse, ChatMessage } from './abstract.classes.multimodal.js';
+import type { ChatOptions, ChatResponse, ChatMessage, ResearchOptions, ResearchResponse } from './abstract.classes.multimodal.js';
 import type { ImageBlockParam, TextBlockParam } from '@anthropic-ai/sdk/resources/messages';
 
 type ContentBlock = ImageBlockParam | TextBlockParam;
 
 export interface IAnthropicProviderOptions {
   anthropicToken: string;
+  enableWebSearch?: boolean;
+  searchDomainAllowList?: string[];
+  searchDomainBlockList?: string[];
 }
 
 export class AnthropicProvider extends MultiModalModel {
@@ -239,4 +242,121 @@ export class AnthropicProvider extends MultiModalModel {
       }
     };
   }
+
+  public async research(optionsArg: ResearchOptions): Promise<ResearchResponse> {
+    // Prepare the messages for the research request
+    const systemMessage = `You are a research assistant with web search capabilities.
+    Provide comprehensive, well-researched answers with citations and sources.
+    When searching the web, be thorough and cite your sources accurately.`;
+
+    try {
+      // Build the tool configuration for web search
+      const tools = this.options.enableWebSearch ? [
+        {
+          type: 'computer_20241022' as const,
+          name: 'web_search',
+          description: 'Search the web for current information',
+          input_schema: {
+            type: 'object' as const,
+            properties: {
+              query: {
+                type: 'string',
+                description: 'The search query'
+              }
+            },
+            required: ['query']
+          }
+        }
+      ] : [];
+
+      // Configure the request based on search depth
+      const maxTokens = optionsArg.searchDepth === 'deep' ? 8192 :
+                        optionsArg.searchDepth === 'advanced' ? 6144 : 4096;
+
+      // Create the research request
+      const requestParams: any = {
+        model: 'claude-3-opus-20240229',
+        system: systemMessage,
+        messages: [
+          {
+            role: 'user' as const,
+            content: optionsArg.query
+          }
+        ],
+        max_tokens: maxTokens,
+        temperature: 0.7
+      };
+
+      // Add tools if web search is enabled
+      if (tools.length > 0) {
+        requestParams.tools = tools;
+        requestParams.tool_choice = { type: 'auto' };
+      }
+
+      // Execute the research request
+      const result = await this.anthropicApiClient.messages.create(requestParams);
+
+      // Extract the answer from content blocks
+      let answer = '';
+      const sources: Array<{ url: string; title: string; snippet: string }> = [];
+      const searchQueries: string[] = [];
+
+      // Process content blocks
+      for (const block of result.content) {
+        if ('text' in block) {
+          answer += block.text;
+        }
+      }
+
+      // Parse sources from the answer (Claude includes citations in various formats)
+      const urlRegex = /\[([^\]]+)\]\(([^)]+)\)/g;
+      let match: RegExpExecArray | null;
+
+      while ((match = urlRegex.exec(answer)) !== null) {
+        sources.push({
+          title: match[1],
+          url: match[2],
+          snippet: ''
+        });
+      }
+
+      // Also look for plain URLs
+      const plainUrlRegex = /https?:\/\/[^\s\)]+/g;
+      const plainUrls = answer.match(plainUrlRegex) || [];
+
+      for (const url of plainUrls) {
+        // Check if this URL is already in sources
+        if (!sources.some(s => s.url === url)) {
+          sources.push({
+            title: new URL(url).hostname,
+            url: url,
+            snippet: ''
+          });
+        }
+      }
+
+      // Extract tool use information if available
+      if ('tool_use' in result && Array.isArray(result.tool_use)) {
+        for (const toolUse of result.tool_use) {
+          if (toolUse.name === 'web_search' && toolUse.input?.query) {
+            searchQueries.push(toolUse.input.query);
+          }
+        }
+      }
+
+      return {
+        answer,
+        sources,
+        searchQueries: searchQueries.length > 0 ? searchQueries : undefined,
+        metadata: {
+          model: 'claude-3-opus-20240229',
+          searchDepth: optionsArg.searchDepth || 'basic',
+          tokensUsed: result.usage?.output_tokens
+        }
+      };
+    } catch (error) {
+      console.error('Anthropic research error:', error);
+      throw new Error(`Failed to perform research: ${error.message}`);
+    }
+  }
 }