@elizaos/plugin-research 0.1.0

package/src/integrations/search-providers/stagehand-google.ts

@@ -0,0 +1,87 @@
+import { elizaLogger } from '@elizaos/core';
+import { SearchResult } from '../../types';
+
+export class StagehandGoogleSearchProvider {
+  public readonly name = 'StagehandGoogle';
+  
+  constructor(private stagehandService: any) {}
+  
+  async search(query: string, maxResults: number = 10): Promise<SearchResult[]> {
+    try {
+      elizaLogger.info(`[StagehandGoogle] Searching for: ${query}`);
+      
+      // Get or create a Stagehand session
+      const session = await this.stagehandService.getCurrentSession() || 
+                     await this.stagehandService.createSession(`search-${Date.now()}`);
+      
+      // Navigate to Google
+      await session.page.goto('https://www.google.com', { waitUntil: 'networkidle' });
+      
+      // Accept cookies if needed (for EU users)
+      try {
+        await session.page.click('button#L2AGLb', { timeout: 2000 });
+      } catch (e) {
+        // Cookie banner might not be present
+      }
+      
+      // Type search query
+      await session.stagehand.act({
+        action: 'type',
+        selector: 'textarea[name="q"], input[name="q"]',
+        text: query
+      });
+      
+      // Submit search
+      await session.page.keyboard.press('Enter');
+      await session.page.waitForNavigation({ waitUntil: 'networkidle' });
+      
+      // Extract search results using Stagehand's AI extraction
+      const searchResults = await session.stagehand.extract({
+        instruction: `Extract the top ${maxResults} organic search results. 
+                     For each result, get the title, URL, and snippet/description. 
+                     Skip ads, "People also ask", and other non-organic results.`,
+        schema: {
+          results: [{
+            title: 'string',
+            url: 'string', 
+            snippet: 'string'
+          }]
+        }
+      });
+      
+      if (!searchResults.results || searchResults.results.length === 0) {
+        // Fallback to manual extraction
+        const results = await session.page.evaluate(() => {
+          const items: any[] = [];
+          const searchResults = document.querySelectorAll('div[data-async-context] > div');
+          
+          searchResults.forEach((result) => {
+            const titleElement = result.querySelector('h3');
+            const linkElement = result.querySelector('a[href]');
+            const snippetElement = result.querySelector('span[style*="-webkit-line-clamp"]');
+            
+            if (titleElement && linkElement) {
+              items.push({
+                title: titleElement.textContent || '',
+                url: linkElement.getAttribute('href') || '',
+                snippet: snippetElement?.textContent || ''
+              });
+            }
+          });
+          
+          return items;
+        });
+        
+        elizaLogger.info(`[StagehandGoogle] Found ${results.length} results via DOM extraction`);
+        return results.slice(0, maxResults);
+      }
+      
+      elizaLogger.info(`[StagehandGoogle] Found ${searchResults.results.length} results via AI extraction`);
+      return searchResults.results.slice(0, maxResults);
+      
+    } catch (error) {
+      elizaLogger.error('[StagehandGoogle] Search error:', error);
+      throw error;
+    }
+  }
+} 

package/src/integrations/search-providers/tavily.ts

@@ -0,0 +1,187 @@
+import axios, { AxiosError } from 'axios';
+import { SearchResult } from '../../types';
+import { elizaLogger } from '@elizaos/core';
+import { z } from 'zod';
+
+// Tavily API response schema validation
+const TavilyResultSchema = z.object({
+  title: z.string().optional(),
+  url: z.string(),
+  content: z.string().optional(),
+  snippet: z.string().optional(),
+  raw_content: z.string().nullable().optional(),
+  score: z.number().optional(),
+});
+
+const TavilyResponseSchema = z.object({
+  query: z.string(),
+  results: z.array(TavilyResultSchema),
+  answer: z.string().optional(),
+  follow_up_questions: z.array(z.string()).nullable().optional(),
+  images: z
+    .array(
+      z.union([
+        z.string(),
+        z.object({
+          url: z.string(),
+          description: z.string().optional(),
+        })
+      ])
+    )
+    .optional(),
+});
+
+export interface TavilyConfig {
+  apiKey: string;
+  searchDepth?: 'basic' | 'advanced';
+  includeAnswer?: boolean;
+  includeRawContent?: boolean;
+  maxResults?: number;
+  includeImages?: boolean;
+  useCache?: boolean;
+}
+
+export class TavilySearchProvider {
+  private readonly apiKey: string;
+  private readonly baseUrl = 'https://api.tavily.com/search';
+  private readonly config: TavilyConfig;
+
+  constructor(config: TavilyConfig) {
+    if (!config.apiKey) {
+      throw new Error('Tavily API key is required');
+    }
+    this.apiKey = config.apiKey;
+    this.config = {
+      searchDepth: 'advanced',
+      includeAnswer: true,
+      includeRawContent: true,
+      maxResults: 10,
+      includeImages: false,
+      useCache: true,
+      ...config,
+    };
+  }
+
+  async search(query: string, maxResults?: number): Promise<SearchResult[]> {
+    const startTime = Date.now();
+
+    try {
+      elizaLogger.info(`[Tavily] Searching for: ${query}`);
+
+      const response = await axios.post(
+        this.baseUrl,
+        {
+          api_key: this.apiKey,
+          query,
+          search_depth: this.config.searchDepth,
+          include_answer: this.config.includeAnswer,
+          include_raw_content: this.config.includeRawContent,
+          max_results: maxResults || this.config.maxResults,
+          include_images: this.config.includeImages,
+        },
+        {
+          timeout: 30000, // 30 second timeout
+          headers: {
+            'Content-Type': 'application/json',
+          },
+        }
+      );
+
+      // Check if response has error detail
+      if (response.data?.detail?.error) {
+        throw new Error(response.data.detail.error);
+      }
+
+      // Check if response has an error field
+      if (response.data?.error) {
+        throw new Error(response.data.error);
+      }
+
+      // Validate response
+      const validatedData = TavilyResponseSchema.parse(response.data);
+
+      const results: SearchResult[] = validatedData.results.map((result) => ({
+        title: result.title || new URL(result.url).hostname || 'Untitled',
+        url: result.url,
+        snippet: result.snippet || result.content?.substring(0, 200) || '',
+        content: result.raw_content || result.content,
+        score: result.score || 0.5,
+        provider: 'tavily',
+        metadata: {
+          language: 'en',
+          domain: new URL(result.url).hostname,
+        },
+      }));
+
+      const duration = Date.now() - startTime;
+      elizaLogger.info(`[Tavily] Found ${results.length} results in ${duration}ms`);
+
+      return results;
+    } catch (error) {
+      const duration = Date.now() - startTime;
+
+      if (axios.isAxiosError(error)) {
+        const axiosError = error as AxiosError;
+
+        // Handle specific error cases
+        if (axiosError.response?.status === 401) {
+          elizaLogger.error('[Tavily] Invalid API key');
+          throw new Error('Invalid Tavily API key');
+        } else if (axiosError.response?.status === 429) {
+          elizaLogger.error('[Tavily] Rate limit exceeded');
+          throw new Error('Tavily rate limit exceeded');
+        } else if (axiosError.code === 'ECONNABORTED') {
+          elizaLogger.error(`[Tavily] Request timeout after ${duration}ms`);
+          throw new Error('Tavily search timeout');
+        }
+
+        elizaLogger.error(`[Tavily] API error: ${axiosError.message}`, {
+          status: axiosError.response?.status,
+          data: axiosError.response?.data,
+        });
+      } else if (error instanceof z.ZodError) {
+        elizaLogger.error('[Tavily] Invalid response format:', error.issues);
+        throw new Error('Invalid Tavily API response format');
+      } else {
+        elizaLogger.error('[Tavily] Unknown error:', error);
+      }
+
+      throw error;
+    }
+  }
+
+  async searchWithRetry(query: string, maxRetries: number = 3): Promise<SearchResult[]> {
+    let lastError: Error | null = null;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        return await this.search(query);
+      } catch (error) {
+        lastError = error as Error;
+
+        if (attempt < maxRetries) {
+          const delay = Math.min(1000 * Math.pow(2, attempt - 1), 10000);
+          elizaLogger.warn(`[Tavily] Retry attempt ${attempt} after ${delay}ms`);
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+      }
+    }
+
+    throw lastError || new Error('Search failed after retries');
+  }
+
+  // Get current API usage (if Tavily provides this endpoint)
+  async getUsage(): Promise<{ searches: number; limit: number } | null> {
+    try {
+      // Note: This is a hypothetical endpoint - check Tavily docs
+      const response = await axios.get('https://api.tavily.com/usage', {
+        headers: { Authorization: `Bearer ${this.apiKey}` },
+      });
+
+      return response.data;
+    } catch (error) {
+      elizaLogger.warn('[Tavily] Could not fetch usage data');
+      return null;
+    }
+  }
+}

package/src/processing/relevance-analyzer.ts

@@ -0,0 +1,353 @@
+import { elizaLogger, IAgentRuntime, ModelType } from '@elizaos/core';
+import { SearchResult, ResearchSource, ResearchFinding } from '../types';
+
+export interface RelevanceScore {
+  score: number; // 0-1
+  reasoning: string;
+  queryAlignment: number; // How well it addresses the query
+  topicRelevance: number; // How relevant to the topic
+  specificity: number; // How specific vs generic
+}
+
+export interface RelevanceAnalysis {
+  queryIntent: string;
+  keyTopics: string[];
+  requiredElements: string[];
+  exclusionCriteria: string[];
+}
+
+/**
+ * Analyzes and scores relevance of search results and findings to the original research query
+ */
+export class RelevanceAnalyzer {
+  constructor(private runtime: IAgentRuntime) {}
+
+  /**
+   * Analyze the research query to understand what constitutes relevance
+   */
+  async analyzeQueryRelevance(query: string): Promise<RelevanceAnalysis> {
+    elizaLogger.info(`[RelevanceAnalyzer] Analyzing query intent: ${query}`);
+
+    const prompt = `Analyze this research query to define what makes a source or finding relevant:
+
+Query: "${query}"
+
+Extract:
+1. Query Intent: What is the user really asking for?
+2. Key Topics: Core topics that MUST be addressed
+3. Required Elements: Specific elements that relevant sources should contain
+4. Exclusion Criteria: What should be filtered out as irrelevant
+
+Format as JSON:
+{
+  "queryIntent": "clear statement of what user wants",
+  "keyTopics": ["topic1", "topic2", "topic3"],
+  "requiredElements": ["element1", "element2"],
+  "exclusionCriteria": ["avoid1", "avoid2"]
+}`;
+
+    try {
+      const response = await this.runtime.useModel(ModelType.TEXT_LARGE, {
+        messages: [
+          { 
+            role: 'system', 
+            content: 'You are a research query analyst. Extract query intent and relevance criteria precisely.' 
+          },
+          { role: 'user', content: prompt }
+        ],
+        temperature: 0.3,
+      });
+
+      const responseContent = typeof response === 'string' ? response : (response as any).content || '';
+      const jsonMatch = responseContent.match(/\{[\s\S]*\}/);
+      
+      if (jsonMatch) {
+        const analysis = JSON.parse(jsonMatch[0]);
+        elizaLogger.info(`[RelevanceAnalyzer] Query analysis complete:`, {
+          intent: analysis.queryIntent,
+          keyTopicsCount: analysis.keyTopics?.length || 0,
+          requiredElementsCount: analysis.requiredElements?.length || 0
+        });
+        return analysis;
+      }
+    } catch (error) {
+      elizaLogger.error('[RelevanceAnalyzer] Failed to analyze query relevance:', error);
+    }
+
+    // Fallback analysis
+    return {
+      queryIntent: query,
+      keyTopics: this.extractKeywordsFromQuery(query),
+      requiredElements: [],
+      exclusionCriteria: []
+    };
+  }
+
+  /**
+   * Score search result relevance before content extraction
+   */
+  async scoreSearchResultRelevance(
+    result: SearchResult, 
+    queryAnalysis: RelevanceAnalysis
+  ): Promise<RelevanceScore> {
+    elizaLogger.debug(`[RelevanceAnalyzer] Scoring search result: ${result.title}`);
+
+    const prompt = `Score the relevance of this search result to the research query:
+
+QUERY INTENT: ${queryAnalysis.queryIntent}
+KEY TOPICS: ${queryAnalysis.keyTopics.join(', ')}
+REQUIRED ELEMENTS: ${queryAnalysis.requiredElements.join(', ')}
+
+SEARCH RESULT:
+Title: ${result.title}
+Snippet: ${result.snippet}
+URL: ${result.url}
+
+Rate 0-1 for each dimension:
+1. Query Alignment: How directly does this address the query intent?
+2. Topic Relevance: How well does it cover the key topics?
+3. Specificity: How specific (vs generic) is the content to the query?
+
+Provide reasoning for the scores.
+
+Format as JSON:
+{
+  "queryAlignment": 0.8,
+  "topicRelevance": 0.9,
+  "specificity": 0.7,
+  "reasoning": "detailed explanation of why this result is/isn't relevant",
+  "score": 0.8
+}`;
+
+    try {
+      const response = await this.runtime.useModel(ModelType.TEXT_LARGE, {
+        messages: [
+          { 
+            role: 'system', 
+            content: 'You are a search result relevance scorer. Be critical - only high relevance should get high scores.' 
+          },
+          { role: 'user', content: prompt }
+        ],
+        temperature: 0.2,
+      });
+
+      const responseContent = typeof response === 'string' ? response : (response as any).content || '';
+      const jsonMatch = responseContent.match(/\{[\s\S]*\}/);
+      
+      if (jsonMatch) {
+        const score = JSON.parse(jsonMatch[0]);
+        const finalScore = (score.queryAlignment + score.topicRelevance + score.specificity) / 3;
+        
+        elizaLogger.debug(`[RelevanceAnalyzer] Search result scored:`, {
+          url: result.url,
+          score: finalScore,
+          breakdown: {
+            queryAlignment: score.queryAlignment,
+            topicRelevance: score.topicRelevance,
+            specificity: score.specificity
+          }
+        });
+
+        return {
+          score: finalScore,
+          reasoning: score.reasoning,
+          queryAlignment: score.queryAlignment,
+          topicRelevance: score.topicRelevance,
+          specificity: score.specificity
+        };
+      }
+    } catch (error) {
+      elizaLogger.error('[RelevanceAnalyzer] Failed to score search result:', error);
+    }
+
+    // Fallback: Simple keyword matching
+    const titleScore = this.calculateKeywordScore(result.title, queryAnalysis.keyTopics);
+    const snippetScore = this.calculateKeywordScore(result.snippet, queryAnalysis.keyTopics);
+    const fallbackScore = (titleScore + snippetScore) / 2;
+
+    return {
+      score: fallbackScore,
+      reasoning: `Fallback keyword scoring: title=${titleScore.toFixed(2)}, snippet=${snippetScore.toFixed(2)}`,
+      queryAlignment: fallbackScore,
+      topicRelevance: fallbackScore,
+      specificity: 0.5
+    };
+  }
+
+  /**
+   * Score finding relevance after extraction
+   */
+  async scoreFindingRelevance(
+    finding: ResearchFinding,
+    queryAnalysis: RelevanceAnalysis,
+    originalQuery: string
+  ): Promise<RelevanceScore> {
+    elizaLogger.debug(`[RelevanceAnalyzer] Scoring finding relevance`);
+
+    const prompt = `Score how well this research finding answers the original query:
+
+ORIGINAL QUERY: "${originalQuery}"
+QUERY INTENT: ${queryAnalysis.queryIntent}
+KEY TOPICS: ${queryAnalysis.keyTopics.join(', ')}
+
+FINDING:
+Content: ${finding.content}
+Category: ${finding.category}
+Source: ${finding.source.title}
+
+Critical Assessment:
+1. Does this finding DIRECTLY address the query intent?
+2. Does it cover the key topics meaningfully?
+3. Is it specific to the query or generic information?
+4. Would this help someone answer the original question?
+
+Rate 0-1 for each dimension and overall relevance.
+
+Format as JSON:
+{
+  "queryAlignment": 0.8,
+  "topicRelevance": 0.9,
+  "specificity": 0.7,
+  "reasoning": "detailed explanation of relevance to original query",
+  "score": 0.8
+}`;
+
+    try {
+      const response = await this.runtime.useModel(ModelType.TEXT_LARGE, {
+        messages: [
+          { 
+            role: 'system', 
+            content: 'You are a research finding relevance judge. Be strict - only findings that directly address the query should score high.' 
+          },
+          { role: 'user', content: prompt }
+        ],
+        temperature: 0.2,
+      });
+
+      const responseContent = typeof response === 'string' ? response : (response as any).content || '';
+      const jsonMatch = responseContent.match(/\{[\s\S]*\}/);
+      
+      if (jsonMatch) {
+        const score = JSON.parse(jsonMatch[0]);
+        const finalScore = (score.queryAlignment + score.topicRelevance + score.specificity) / 3;
+        
+        elizaLogger.debug(`[RelevanceAnalyzer] Finding scored:`, {
+          score: finalScore,
+          category: finding.category,
+          sourceUrl: finding.source.url
+        });
+
+        return {
+          score: finalScore,
+          reasoning: score.reasoning,
+          queryAlignment: score.queryAlignment,
+          topicRelevance: score.topicRelevance,
+          specificity: score.specificity
+        };
+      }
+    } catch (error) {
+      elizaLogger.error('[RelevanceAnalyzer] Failed to score finding:', error);
+    }
+
+    // Fallback scoring
+    const keywordScore = this.calculateKeywordScore(finding.content, queryAnalysis.keyTopics);
+    return {
+      score: keywordScore,
+      reasoning: `Fallback keyword scoring: ${keywordScore.toFixed(2)}`,
+      queryAlignment: keywordScore,
+      topicRelevance: keywordScore,
+      specificity: 0.5
+    };
+  }
+
+  /**
+   * Verify that extracted findings actually answer the research query
+   */
+  async verifyQueryAnswering(
+    findings: ResearchFinding[],
+    originalQuery: string
+  ): Promise<{
+    coverage: number;
+    gaps: string[];
+    recommendations: string[];
+  }> {
+    elizaLogger.info(`[RelevanceAnalyzer] Verifying query answering for ${findings.length} findings`);
+
+    const findingSummaries = findings
+      .slice(0, 20) // Limit for prompt size
+      .map((f, i) => `${i + 1}. ${f.content.substring(0, 200)}...`)
+      .join('\n');
+
+    const prompt = `Assess how well these research findings answer the original query:
+
+ORIGINAL QUERY: "${originalQuery}"
+
+FINDINGS:
+${findingSummaries}
+
+Assessment:
+1. Coverage Score (0-1): How well do these findings collectively answer the query?
+2. Gaps: What important aspects of the query are NOT addressed?
+3. Recommendations: What additional research is needed?
+
+Format as JSON:
+{
+  "coverage": 0.7,
+  "gaps": ["gap1", "gap2"],
+  "recommendations": ["rec1", "rec2"]
+}`;
+
+    try {
+      const response = await this.runtime.useModel(ModelType.TEXT_LARGE, {
+        messages: [
+          { 
+            role: 'system', 
+            content: 'You are a research completeness assessor. Evaluate if findings actually answer the research question.' 
+          },
+          { role: 'user', content: prompt }
+        ],
+        temperature: 0.3,
+      });
+
+      const responseContent = typeof response === 'string' ? response : (response as any).content || '';
+      const jsonMatch = responseContent.match(/\{[\s\S]*\}/);
+      
+      if (jsonMatch) {
+        const assessment = JSON.parse(jsonMatch[0]);
+        elizaLogger.info(`[RelevanceAnalyzer] Query answering assessment:`, {
+          coverage: assessment.coverage,
+          gapsCount: assessment.gaps?.length || 0,
+          recommendationsCount: assessment.recommendations?.length || 0
+        });
+        return assessment;
+      }
+    } catch (error) {
+      elizaLogger.error('[RelevanceAnalyzer] Failed to verify query answering:', error);
+    }
+
+    return {
+      coverage: findings.length > 0 ? 0.5 : 0,
+      gaps: ['Unable to assess coverage'],
+      recommendations: ['Manual review recommended']
+    };
+  }
+
+  private extractKeywordsFromQuery(query: string): string[] {
+    // Simple keyword extraction as fallback
+    const words = query.toLowerCase()
+      .replace(/[^\w\s]/g, ' ')
+      .split(/\s+/)
+      .filter(word => word.length > 3)
+      .filter(word => !['what', 'how', 'why', 'when', 'where', 'which', 'that', 'this', 'with', 'from', 'they', 'have', 'been', 'will', 'are'].includes(word));
+    
+    return words.slice(0, 5);
+  }
+
+  private calculateKeywordScore(text: string, keywords: string[]): number {
+    if (!keywords.length) return 0.5;
+    
+    const lowerText = text.toLowerCase();
+    const matches = keywords.filter(keyword => lowerText.includes(keyword.toLowerCase()));
+    return matches.length / keywords.length;
+  }
+}