/**
 * Research Tool Handlers
 *
 * Handlers for research and quick_fetch tools.
 * These provide simplified, research-focused browsing workflows.
 */
import type { SmartBrowser } from '../../core/smart-browser.js';
import { type McpResponse } from '../response-formatters.js';
import { type ContradictionResult } from '../contradiction-detector.js';
/**
 * Arguments for research tool
 */
export interface ResearchArgs {
    scope: string;
    outputSchema?: Record<string, unknown>;
    strategy?: 'authoritative' | 'comprehensive' | 'quick';
    maxSources?: number;
    language?: string;
    preferredDomains?: string[];
    extractSnippets?: boolean;
    snippetLength?: number;
    /**
     * Use LLM-assisted synthesis for more accurate structured data extraction.
     * Requires an LLM provider API key (ANTHROPIC_API_KEY, OPENAI_API_KEY, or OLLAMA_BASE_URL).
     * Falls back to regex-only extraction if no provider is available.
     */
    useLlmSynthesis?: boolean;
    /**
     * Enable progressive refinement - returns results faster by not waiting for all sources.
     * Default: true for 'quick' and 'authoritative' strategies, false for 'comprehensive'.
     *
     * When enabled:
     * - Returns after 2+ high-authority sources OR 3+ any sources complete
     * - Includes metadata about pending sources in the response
     * - Much faster for typical queries (500ms-2s vs 5-30s)
     */
    progressiveMode?: boolean;
    /**
     * Quality threshold for progressive mode early return.
     * Higher values wait longer for more sources.
     */
    progressiveThreshold?: {
        /** Min high-authority sources (score >= 0.8) before early return. Default: 2 */
        minHighAuthority?: number;
        /** Min total successful sources before early return. Default: 3 */
        minTotalSources?: number;
        /** Max wait time in ms. Default: 5000 */
        maxWaitMs?: number;
        /** Min wait time in ms (ensures fast sources get a chance). Default: 500 */
        minWaitMs?: number;
    };
    /**
     * Output format for research results.
     * - 'json': Structured JSON response (default)
     * - 'report': Markdown report with sections
     * - 'both': Both JSON and report
     */
    outputFormat?: 'json' | 'report' | 'both';
    /**
     * Report style when outputFormat includes 'report'.
     * - 'executive': Brief summary with key findings
     * - 'detailed': Full analysis with all sections (default)
     * - 'academic': Detailed + APA citations + methodology
     */
    reportStyle?: 'executive' | 'detailed' | 'academic';
    /**
     * Enable iterative deepening - multi-pass research with follow-up questions.
     * Default: false (single-pass research)
     *
     * When enabled:
     * - Iteration 1: Initial research with main queries
     * - Assess confidence and detect gaps/contradictions
     * - Iteration 2+: Generate follow-up queries to fill gaps
     * - Continue until confidence threshold met OR max iterations reached
     *
     * This matches Claude Deep Research's multi-round exploration approach.
     */
    enableIterativeDeepening?: boolean;
    /**
     * Confidence threshold for iterative deepening.
     * Stop iterating when confidence reaches this level.
     * Default: 0.85 for authoritative, 0.80 for comprehensive, 0.70 for quick
     */
    confidenceThreshold?: number;
    /**
     * Maximum iterations for iterative deepening.
     * Default: 3 (prevents runaway costs)
     */
    maxIterations?: number;
    /**
     * Use search snippets only - skip browsing for maximum speed.
     *
     * When true, uses search result descriptions (snippets) directly instead of
     * browsing each URL. This matches Claude WebSearch behavior and achieves
     * ~300-500ms response times vs 2-60+ seconds with full browsing.
     *
     * Trade-offs:
     * - PRO: 10-100x faster (no browser rendering)
     * - PRO: Still includes source classification, authority scoring, contradiction detection
     * - CON: Less content (100-300 char snippets vs full pages)
     * - CON: Cannot extract structured data with outputSchema
     *
     * Best for: Quick factual lookups, policy change detection, source discovery
     * Not for: Deep extraction, content requiring full page context
     *
     * Default: false
     */
    snippetsOnly?: boolean;
}
/**
 * Arguments for quick_fetch tool
 */
export interface QuickFetchArgs {
    url: string;
    maxChars?: number;
}
/**
 * Source classification result
 */
export interface SourceClassification {
    sourceType: 'government' | 'official' | 'news' | 'reference' | 'developer' | 'blog' | 'unknown';
    authorityScore: number;
}
/**
 * Classify a source by its domain
 * Exported for testing
 *
 * Order matters! More specific checks (developer sites, reference sites)
 * must run BEFORE generic TLD checks (.org, .edu) to avoid misclassification.
 */
export declare function classifySource(url: string): SourceClassification;
/**
 * Generate search queries from scope
 * Exported for testing
 *
 * Generates targeted search queries based on strategy:
 * - authoritative: Prioritizes government and official sources
 * - comprehensive: Broad coverage with multiple angles
 * - quick: Minimal queries for speed
 */
export declare function generateSearchQueries(scope: string, strategy: string, language?: string): string[];
/**
 * Detect content freshness based on year mentions
 * Returns a freshness score (0-1) and the most recent year found
 */
export declare function detectContentFreshness(content: string, targetYear?: number): {
    freshnessScore: number;
    mostRecentYear: number | null;
    yearMentions: Record<number, number>;
};
/**
 * Extract structured data from content based on an output schema
 * Implements lightweight extraction when outputSchema is provided
 * Exported for testing
 */
export declare function extractStructuredData(content: string, schema?: Record<string, unknown>): Record<string, unknown> | undefined;
/**
 * Research gap detection - identifies missing or low-confidence fields
 * Exported for testing
 */
export interface ResearchGap {
    type: 'missing_field' | 'low_confidence' | 'contradiction' | 'temporal_gap';
    field?: string;
    description: string;
    currentConfidence?: number;
    suggestedQuery: string;
}
export declare function detectResearchGaps(input: {
    scope: string;
    outputSchema?: Record<string, unknown>;
    extractedData?: Record<string, unknown>;
    confidence: number;
    contradictions?: ContradictionResult;
    sources: Array<{
        mostRecentYear?: number | null;
        excerpt: string;
        sourceType: string;
        authorityScore: number;
    }>;
    strategy: string;
}): ResearchGap[];
/**
 * Generate follow-up search queries based on detected gaps
 * Exported for testing
 */
export declare function generateFollowUpQueries(gaps: ResearchGap[], maxQueries?: number): string[];
/**
 * Check if we should continue iterating
 * Exported for testing
 */
export declare function shouldContinueIterating(input: {
    iteration: number;
    maxIterations: number;
    confidence: number;
    confidenceThreshold: number;
    gaps: ResearchGap[];
}): {
    continue: boolean;
    reason: string;
};
/**
 * Handle research tool call
 */
export declare function handleResearch(smartBrowser: SmartBrowser, args: ResearchArgs): Promise<McpResponse>;
/**
 * Handle quick_fetch tool call
 */
export declare function handleQuickFetch(smartBrowser: SmartBrowser, args: QuickFetchArgs): Promise<McpResponse>;
//# sourceMappingURL=research-handlers.d.ts.map