@framers/agentos-ext-web-search 1.1.1 → 1.2.0

package/src/tools/factCheck.ts

@@ -1,300 +0,0 @@
-/**
- * Fact Check Tool — verify statements against web sources.
- *
- * Updated to conform to AgentOS `ITool` (inputSchema + ToolExecutionContext).
- *
- * @module @framers/agentos-ext-web-search
- */
-
-import type { ITool, JSONSchemaObject, ToolExecutionContext, ToolExecutionResult } from '@framers/agentos';
-import type { ProviderResponse, MultiSearchResponse } from '../services/searchProvider.js';
-import { SearchProviderService } from '../services/searchProvider.js';
-
-export interface FactCheckInput {
-  statement: string;
-  checkSources?: boolean;
-  confidence?: 'low' | 'medium' | 'high';
-  multiSearch?: boolean;
-}
-
-export interface FactCheckOutput {
-  statement: string;
-  verdict: 'TRUE' | 'FALSE' | 'UNVERIFIED' | 'PARTIALLY TRUE';
-  confidence: number;
-  confidenceLevel: 'low' | 'medium' | 'high';
-  explanation: string;
-  sources: Array<{ title: string; url: string; snippet: string; provider: string; query: string }>;
-  contradictingSources: string[];
-  supportingSources: string[];
-  meetsRequiredConfidence: boolean;
-  timestamp: string;
-}
-
-export class FactCheckTool implements ITool<FactCheckInput, FactCheckOutput> {
-  public readonly id = 'fact-check-v1';
-  /** Tool call name used by the LLM / ToolExecutor. */
-  public readonly name = 'fact_check';
-  public readonly displayName = 'Fact Check';
-  public readonly description = 'Verify a statement against web sources and return a verdict with confidence.';
-  public readonly category = 'research';
-  public readonly hasSideEffects = false;
-
-  public readonly inputSchema: JSONSchemaObject = {
-    type: 'object',
-    required: ['statement'],
-    properties: {
-      statement: {
-        type: 'string',
-        description: 'The statement to fact-check',
-        minLength: 5,
-      },
-      checkSources: {
-        type: 'boolean',
-        description: 'Whether to include source citations',
-        default: true,
-      },
-      confidence: {
-        type: 'string',
-        description: 'Required confidence level for the verdict',
-        enum: ['low', 'medium', 'high'],
-        default: 'medium',
-      },
-      multiSearch: {
-        type: 'boolean',
-        description:
-          'When true, each verification query fans out to ALL available providers in parallel for higher-confidence cross-provider consensus.',
-        default: false,
-      },
-    },
-    additionalProperties: false,
-  };
-
-  public readonly requiredCapabilities = ['capability:web_search'];
-
-  constructor(
-    private readonly searchService: SearchProviderService,
-    private readonly defaultMultiSearch: boolean = false,
-  ) {}
-
-  async execute(input: FactCheckInput, _context: ToolExecutionContext): Promise<ToolExecutionResult<FactCheckOutput>> {
-    try {
-      const checkSources = input.checkSources !== false;
-      const requiredConfidence = input.confidence || 'medium';
-      const useMultiSearch = input.multiSearch ?? this.defaultMultiSearch;
-
-      const queries = this.generateFactCheckQueries(input.statement);
-
-      let searchResults: ProviderResponse[];
-
-      if (useMultiSearch) {
-        const multiPromises = queries.map((query) =>
-          this.searchService
-            .multiSearch(query, { maxResults: 5 })
-            .then((multi): ProviderResponse => ({
-              provider: 'multi',
-              results: multi.results,
-              metadata: { query, timestamp: multi.metadata.timestamp },
-            }))
-            .catch((err) => ({
-              provider: 'error',
-              results: [],
-              metadata: { query, error: err?.message || String(err), timestamp: new Date().toISOString() },
-            }))
-        );
-        searchResults = (await Promise.all(multiPromises)) as ProviderResponse[];
-      } else {
-        const searchPromises = queries.map((query) =>
-          this.searchService
-            .search(query, { maxResults: 5 })
-            .catch((err) => ({
-              provider: 'error',
-              results: [],
-              metadata: { query, error: err?.message || String(err), timestamp: new Date().toISOString() },
-            }))
-        );
-        searchResults = (await Promise.all(searchPromises)) as ProviderResponse[];
-      }
-
-      const analysis = this.analyzeFactCheckResults(input.statement, searchResults, requiredConfidence);
-      const sources = checkSources ? this.compileSources(searchResults) : [];
-
-      return {
-        success: true,
-        output: {
-          statement: input.statement,
-          verdict: analysis.verdict,
-          confidence: analysis.confidence,
-          confidenceLevel: analysis.confidenceLevel,
-          explanation: analysis.explanation,
-          sources,
-          contradictingSources: analysis.contradictingSources,
-          supportingSources: analysis.supportingSources,
-          meetsRequiredConfidence: analysis.meetsRequiredConfidence,
-          timestamp: new Date().toISOString(),
-        },
-      };
-    } catch (error: any) {
-      return { success: false, error: error?.message || String(error) };
-    }
-  }
-
-  validateArgs(input: Record<string, any>): { isValid: boolean; errors?: any[] } {
-    const errors: string[] = [];
-
-    if (!input.statement) {
-      errors.push('Statement is required');
-    } else if (typeof input.statement !== 'string') {
-      errors.push('Statement must be a string');
-    } else if (input.statement.length < 5) {
-      errors.push('Statement must be at least 5 characters long');
-    }
-
-    if (input.confidence !== undefined) {
-      if (!['low', 'medium', 'high'].includes(input.confidence)) {
-        errors.push('Confidence must be low, medium, or high');
-      }
-    }
-
-    if (input.checkSources !== undefined && typeof input.checkSources !== 'boolean') {
-      errors.push('checkSources must be a boolean');
-    }
-
-    if (input.multiSearch !== undefined && typeof input.multiSearch !== 'boolean') {
-      errors.push('multiSearch must be a boolean');
-    }
-
-    return errors.length === 0 ? { isValid: true } : { isValid: false, errors };
-  }
-
-  // ============================================================================
-  // Internals (ported from the previous implementation)
-  // ============================================================================
-
-  private generateFactCheckQueries(statement: string): string[] {
-    return [
-      statement,
-      `"${statement}" fact check`,
-      `${statement} true or false`,
-      `${statement} debunked myths`,
-      `is it true that ${statement}`,
-    ];
-  }
-
-  private analyzeFactCheckResults(statement: string, searchResults: any[], requiredConfidence: string): any {
-    let supportingCount = 0;
-    let contradictingCount = 0;
-    let neutralCount = 0;
-    const supportingSources: string[] = [];
-    const contradictingSources: string[] = [];
-
-    const statementLower = statement.toLowerCase();
-    void statementLower; // retained for future use
-
-    const negativeIndicators = ['false', 'myth', 'debunked', 'incorrect', 'wrong', 'not true', 'fake'];
-    const positiveIndicators = ['true', 'correct', 'accurate', 'confirmed', 'verified', 'fact'];
-
-    for (const searchResult of searchResults) {
-      if (!searchResult.results) continue;
-
-      for (const result of searchResult.results) {
-        const contentLower = (String(result.title || '') + ' ' + String(result.snippet || '')).toLowerCase();
-
-        const isFactCheckSite =
-          String(result.url || '').includes('snopes') ||
-          String(result.url || '').includes('factcheck') ||
-          String(result.url || '').includes('politifact');
-
-        // Multi-search results with cross-provider agreement get extra weight
-        const agreementBonus = typeof result.agreementCount === 'number' ? Math.max(0, result.agreementCount - 1) : 0;
-        const weight = (isFactCheckSite ? 2 : 1) + agreementBonus;
-
-        const hasNegative = negativeIndicators.some((ind) => contentLower.includes(ind));
-        const hasPositive = positiveIndicators.some((ind) => contentLower.includes(ind));
-
-        if (hasNegative && !hasPositive) {
-          contradictingCount += weight;
-          if (result.url) contradictingSources.push(String(result.url));
-        } else if (hasPositive && !hasNegative) {
-          supportingCount += weight;
-          if (result.url) supportingSources.push(String(result.url));
-        } else {
-          neutralCount += 1;
-        }
-      }
-    }
-
-    const total = supportingCount + contradictingCount + neutralCount;
-    let confidence: number;
-    let verdict: FactCheckOutput['verdict'];
-    let explanation: string;
-
-    if (total === 0) {
-      verdict = 'UNVERIFIED';
-      confidence = 0;
-      explanation = 'No relevant sources found to verify this statement.';
-    } else {
-      const supportRatio = supportingCount / total;
-      const contradictRatio = contradictingCount / total;
-
-      if (supportRatio > 0.7) {
-        verdict = 'TRUE';
-        confidence = supportRatio * 100;
-        explanation = `Strong evidence supports this statement (${supportingCount} supporting sources).`;
-      } else if (contradictRatio > 0.7) {
-        verdict = 'FALSE';
-        confidence = contradictRatio * 100;
-        explanation = `Strong evidence contradicts this statement (${contradictingCount} contradicting sources).`;
-      } else if (supportRatio > 0.4 && contradictRatio > 0.4) {
-        verdict = 'PARTIALLY TRUE';
-        confidence = 50;
-        explanation = 'Mixed evidence with both supporting and contradicting sources.';
-      } else {
-        verdict = 'UNVERIFIED';
-        confidence = Math.max(supportRatio, contradictRatio) * 100;
-        explanation = 'Insufficient clear evidence to verify this statement.';
-      }
-    }
-
-    const confidenceLevel: 'low' | 'medium' | 'high' = confidence > 80 ? 'high' : confidence > 50 ? 'medium' : 'low';
-
-    return {
-      verdict,
-      confidence: Math.round(confidence),
-      confidenceLevel,
-      explanation,
-      supportingSources: supportingSources.slice(0, 5),
-      contradictingSources: contradictingSources.slice(0, 5),
-      meetsRequiredConfidence: this.meetsConfidenceRequirement(confidenceLevel, requiredConfidence),
-    };
-  }
-
-  private meetsConfidenceRequirement(actual: string, required: string): boolean {
-    const levels = { low: 1, medium: 2, high: 3 };
-    return levels[actual as keyof typeof levels] >= levels[required as keyof typeof levels];
-  }
-
-  private compileSources(searchResults: any[]): Array<{ title: string; url: string; snippet: string; provider: string; query: string }> {
-    const sources: Array<{ title: string; url: string; snippet: string; provider: string; query: string }> = [];
-    const seenUrls = new Set<string>();
-
-    for (const searchResult of searchResults) {
-      if (!searchResult.results) continue;
-
-      for (const result of searchResult.results) {
-        if (!result.url) continue;
-        if (seenUrls.has(result.url)) continue;
-        seenUrls.add(result.url);
-
-        sources.push({
-          title: String(result.title || ''),
-          url: String(result.url),
-          snippet: String(result.snippet || ''),
-          provider: String(searchResult.provider || 'unknown'),
-          query: String(searchResult.metadata?.query || ''),
-        });
-      }
-    }
-
-    return sources.slice(0, 10);
-  }
-}

package/src/tools/researchAggregator.ts

@@ -1,289 +0,0 @@
-/**
- * Research Aggregator Tool — runs multiple searches on a topic and aggregates results.
- *
- * Updated to conform to AgentOS `ITool` (inputSchema + ToolExecutionContext).
- *
- * @module @framers/agentos-ext-web-search
- */
-
-import type { ITool, JSONSchemaObject, ToolExecutionContext, ToolExecutionResult } from '@framers/agentos';
-import type { ProviderResponse, MultiSearchResponse } from '../services/searchProvider.js';
-import { SearchProviderService } from '../services/searchProvider.js';
-
-export interface ResearchAggregatorInput {
-  topic: string;
-  sources?: number;
-  depth?: 'quick' | 'moderate' | 'comprehensive';
-  multiSearch?: boolean;
-}
-
-export interface ResearchAggregatorOutput {
-  topic: string;
-  sources: number;
-  depth: 'quick' | 'moderate' | 'comprehensive';
-  queries: string[];
-  aggregatedResults: any;
-  timestamp: string;
-}
-
-export class ResearchAggregatorTool implements ITool<ResearchAggregatorInput, ResearchAggregatorOutput> {
-  public readonly id = 'research-aggregator-v1';
-  /** Tool call name used by the LLM / ToolExecutor. */
-  public readonly name = 'research_aggregate';
-  public readonly displayName = 'Research Aggregator';
-  public readonly description = 'Aggregate research from multiple web searches on a topic (deduplicated + categorized).';
-  public readonly category = 'research';
-  public readonly hasSideEffects = false;
-
-  public readonly inputSchema: JSONSchemaObject = {
-    type: 'object',
-    required: ['topic'],
-    properties: {
-      topic: {
-        type: 'string',
-        description: 'The research topic to aggregate information about',
-      },
-      sources: {
-        type: 'integer',
-        description: 'Number of different search angles to explore',
-        default: 3,
-        minimum: 1,
-        maximum: 10,
-      },
-      depth: {
-        type: 'string',
-        description: 'Research depth level',
-        enum: ['quick', 'moderate', 'comprehensive'],
-        default: 'moderate',
-      },
-      multiSearch: {
-        type: 'boolean',
-        description:
-          'When true, each search query fans out to ALL available providers in parallel, returning merged and deduplicated results ranked by cross-provider agreement.',
-        default: false,
-      },
-    },
-    additionalProperties: false,
-  };
-
-  public readonly requiredCapabilities = ['capability:web_search'];
-
-  constructor(
-    private readonly searchService: SearchProviderService,
-    private readonly defaultMultiSearch: boolean = false,
-  ) {}
-
-  async execute(
-    input: ResearchAggregatorInput,
-    _context: ToolExecutionContext,
-  ): Promise<ToolExecutionResult<ResearchAggregatorOutput>> {
-    try {
-      const sources = input.sources || 3;
-      const depth = input.depth || 'moderate';
-      const useMultiSearch = input.multiSearch ?? this.defaultMultiSearch;
-
-      const queries = this.generateSearchQueries(input.topic, sources, depth);
-
-      const perQueryMaxResults = depth === 'quick' ? 5 : depth === 'moderate' ? 10 : 15;
-
-      let searchResults: ProviderResponse[];
-
-      if (useMultiSearch) {
-        // Fan out each query to ALL providers in parallel, then normalize into ProviderResponse shape
-        const multiPromises = queries.map((query) =>
-          this.searchService
-            .multiSearch(query, { maxResults: perQueryMaxResults })
-            .then((multi): ProviderResponse => ({
-              provider: 'multi',
-              results: multi.results,
-              metadata: { query, timestamp: multi.metadata.timestamp },
-            }))
-            .catch((err) => ({
-              provider: 'error',
-              results: [],
-              metadata: { query, error: err?.message || String(err), timestamp: new Date().toISOString() },
-            }))
-        );
-        searchResults = (await Promise.all(multiPromises)) as ProviderResponse[];
-      } else {
-        const searchPromises = queries.map((query) =>
-          this.searchService
-            .search(query, { maxResults: perQueryMaxResults })
-            .catch((err) => ({
-              provider: 'error',
-              results: [],
-              metadata: { query, error: err?.message || String(err), timestamp: new Date().toISOString() },
-            }))
-        );
-        searchResults = (await Promise.all(searchPromises)) as ProviderResponse[];
-      }
-
-      const aggregatedResults = this.aggregateResults(searchResults, input.topic);
-
-      return {
-        success: true,
-        output: {
-          topic: input.topic,
-          sources,
-          depth,
-          queries,
-          aggregatedResults,
-          timestamp: new Date().toISOString(),
-        },
-      };
-    } catch (error: any) {
-      return { success: false, error: error?.message || String(error) };
-    }
-  }
-
-  validateArgs(input: Record<string, any>): { isValid: boolean; errors?: any[] } {
-    const errors: string[] = [];
-
-    if (!input.topic) {
-      errors.push('Topic is required');
-    } else if (typeof input.topic !== 'string') {
-      errors.push('Topic must be a string');
-    }
-
-    if (input.sources !== undefined) {
-      if (typeof input.sources !== 'number' || input.sources < 1 || input.sources > 10) {
-        errors.push('Sources must be a number between 1 and 10');
-      }
-    }
-
-    if (input.depth !== undefined) {
-      if (!['quick', 'moderate', 'comprehensive'].includes(input.depth)) {
-        errors.push('Depth must be quick, moderate, or comprehensive');
-      }
-    }
-
-    if (input.multiSearch !== undefined && typeof input.multiSearch !== 'boolean') {
-      errors.push('multiSearch must be a boolean');
-    }
-
-    return errors.length === 0 ? { isValid: true } : { isValid: false, errors };
-  }
-
-  // ============================================================================
-  // Internals (ported from the previous implementation)
-  // ============================================================================
-
-  private generateSearchQueries(topic: string, count: number, depth: string): string[] {
-    const queries: string[] = [topic];
-
-    const modifiers = {
-      quick: ['overview', 'summary'],
-      moderate: ['overview', 'recent developments', 'key concepts', 'applications'],
-      comprehensive: [
-        'overview',
-        'recent research',
-        'state of the art',
-        'challenges',
-        'future directions',
-        'industry applications',
-        'academic papers',
-        'expert opinions',
-      ],
-    };
-
-    const selectedModifiers = modifiers[depth as keyof typeof modifiers];
-
-    for (let i = 1; i < Math.min(count, selectedModifiers.length + 1); i++) {
-      if (selectedModifiers[i - 1]) {
-        queries.push(`${topic} ${selectedModifiers[i - 1]}`);
-      }
-    }
-
-    return queries;
-  }
-
-  private aggregateResults(searchResults: any[], topic: string): any {
-    const seenUrls = new Set<string>();
-    const categories = {
-      overview: [] as any[],
-      research: [] as any[],
-      applications: [] as any[],
-      resources: [] as any[],
-    };
-
-    for (const searchResult of searchResults) {
-      if (!searchResult.results) continue;
-
-      for (const result of searchResult.results) {
-        if (seenUrls.has(result.url)) continue;
-        seenUrls.add(result.url);
-
-        const lowerTitle = String(result.title || '').toLowerCase();
-
-        if (lowerTitle.includes('overview') || lowerTitle.includes('introduction') || lowerTitle.includes('what is')) {
-          categories.overview.push(result);
-        } else if (
-          lowerTitle.includes('research') ||
-          lowerTitle.includes('study') ||
-          lowerTitle.includes('paper') ||
-          lowerTitle.includes('journal')
-        ) {
-          categories.research.push(result);
-        } else if (
-          lowerTitle.includes('application') ||
-          lowerTitle.includes('use case') ||
-          lowerTitle.includes('implementation')
-        ) {
-          categories.applications.push(result);
-        } else {
-          categories.resources.push(result);
-        }
-      }
-    }
-
-    const scoredCategories = Object.entries(categories).reduce((acc, [key, items]) => {
-      acc[key] = items
-        .map((item: any) => ({
-          ...item,
-          relevanceScore: this.calculateRelevance(item, topic),
-        }))
-        .sort((a: any, b: any) => b.relevanceScore - a.relevanceScore);
-      return acc;
-    }, {} as any);
-
-    return {
-      categories: scoredCategories,
-      totalResults: seenUrls.size,
-      topResults: this.getTopResults(scoredCategories, 10),
-    };
-  }
-
-  private calculateRelevance(result: any, topic: string): number {
-    let score = 50;
-
-    const topicWords = topic.toLowerCase().split(/\s+/);
-    const titleWords = String(result.title || '').toLowerCase();
-    const snippetWords = String(result.snippet || '').toLowerCase();
-
-    for (const word of topicWords) {
-      if (titleWords.includes(word)) score += 15;
-      if (snippetWords.includes(word)) score += 5;
-    }
-
-    if (titleWords.includes('official')) score += 10;
-    if (titleWords.includes('guide')) score += 5;
-    if (titleWords.includes('tutorial')) score += 5;
-
-    // Bonus for multi-search results with cross-provider agreement
-    if (typeof result.confidenceScore === 'number') {
-      score += (result.confidenceScore / 100) * 20;
-    }
-
-    return Math.min(100, score);
-  }
-
-  private getTopResults(categories: any, count: number): any[] {
-    const allResults: any[] = [];
-
-    for (const items of Object.values(categories)) {
-      allResults.push(...(items as any[]));
-    }
-
-    return allResults.sort((a, b) => b.relevanceScore - a.relevanceScore).slice(0, count);
-  }
-}