@iflow-mcp/jakeliume-webpeel 0.22.0

package/dist/core/deep-research.d.ts

@@ -0,0 +1,141 @@
+/**
+ * WebPeel Deep Research
+ *
+ * Multi-step search agent that turns one question into a comprehensive,
+ * cited research report. Orchestrates:
+ *
+ *   1. Query Decomposition  — LLM breaks question into 3-5 sub-queries
+ *   2. Parallel Multi-Search — All sub-queries across DDG + Stealth
+ *   3. Source Fetching       — peel() on top results per sub-query
+ *   4. Relevance Scoring     — BM25 against the original question
+ *   5. Gap Detection         — LLM: "Is there enough info? What's missing?"
+ *   6. Re-Search Loop        — Generate new queries if gaps found (max N rounds)
+ *   7. Synthesis             — LLM generates final cited report
+ */
+import { type WebSearchResult } from './search-provider.js';
+import { type LLMConfig } from './llm-provider.js';
+export type ProgressEventType = 'decomposing' | 'searching' | 'fetching' | 'scoring' | 'gap_check' | 'quality_check' | 'researching' | 'verification' | 'synthesizing' | 'done' | 'error';
+export interface DeepResearchProgressEvent {
+    type: ProgressEventType;
+    message: string;
+    round?: number;
+    data?: Record<string, unknown>;
+}
+export interface Citation {
+    index: number;
+    title: string;
+    url: string;
+    snippet: string;
+    relevanceScore: number;
+}
+export interface DeepResearchRequest {
+    question: string;
+    llm?: LLMConfig;
+    /** Maximum research rounds (default: 3) */
+    maxRounds?: number;
+    /** Maximum sources to consider (default: 20) */
+    maxSources?: number;
+    stream?: boolean;
+    /** Called with incremental report text when stream=true */
+    onChunk?: (text: string) => void;
+    /** Called with progress updates */
+    onProgress?: (event: DeepResearchProgressEvent) => void;
+    signal?: AbortSignal;
+}
+export interface DeepResearchResponse {
+    report: string;
+    citations: Citation[];
+    sourcesUsed: number;
+    roundsCompleted: number;
+    totalSearchQueries: number;
+    llmProvider: string;
+    tokensUsed: {
+        input: number;
+        output: number;
+    };
+    elapsed: number;
+    /** Overall research quality score (0-100), computed deterministically */
+    qualityScore?: number;
+    /** Breakdown of quality score by dimension */
+    qualityBreakdown?: Record<string, number>;
+    /** Conflicts found between sources during research */
+    conflictsFound?: string[];
+    /** Conflicts that were resolved by additional research */
+    conflictsResolved?: string[];
+}
+/** Source credibility assessment */
+export interface SourceCredibility {
+    /** Credibility tier */
+    tier: 'official' | 'verified' | 'general';
+    /** Star rating (1–3) */
+    stars: number;
+    /** Human-readable label */
+    label: string;
+}
+interface FetchedSource {
+    result: WebSearchResult;
+    content: string;
+    relevanceScore: number;
+    subQuery: string;
+    /** Credibility assessment (populated after fetchSources) */
+    credibility?: SourceCredibility;
+}
+/**
+ * Assess the credibility of a source URL.
+ *
+ * Returns:
+ *   - tier: 'official' | 'verified' | 'general'
+ *   - stars: 3 / 2 / 1
+ *   - label: human-readable string for the synthesis prompt
+ */
+export declare function getSourceCredibility(url: string): SourceCredibility;
+/** Render stars string for a credibility tier */
+export declare function starsString(stars: number): string;
+interface GapDetectionResult {
+    hasEnoughInfo: boolean;
+    gaps: string[];
+    additionalQueries: string[];
+    /** Detected source conflicts (optional, from LLM analysis) */
+    conflicts?: string[];
+    /** Overall confidence level based on source quality */
+    confidence?: 'high' | 'medium' | 'low';
+    /** Conflicts that were addressed/resolved in subsequent rounds */
+    conflictsResolved?: string[];
+}
+interface VerificationSummary {
+    conflicts: string[];
+    confidence: 'high' | 'medium' | 'low';
+    sourceDiversity: boolean;
+    officialCount: number;
+    verifiedCount: number;
+    generalCount: number;
+}
+/**
+ * Compute a verification summary from fetched sources and optional gap detection result.
+ * Used to emit the 'verification' progress event before synthesis.
+ */
+export declare function computeVerificationSummary(sources: FetchedSource[], gapResult?: GapDetectionResult): VerificationSummary;
+export interface QualityScoreResult {
+    score: number;
+    breakdown: Record<string, number>;
+    suggestions: string[];
+}
+/**
+ * Compute a deterministic 0-100 quality score for the current research state.
+ *
+ * Dimensions:
+ *   - Source diversity   (0-20): unique domains vs total sources
+ *   - Credibility mix    (0-25): weighted score from official/verified/general
+ *   - Coverage breadth   (0-25): sub-queries with ≥2 relevant sources
+ *   - Conflict resolution(0-15): whether conflicts are detected and addressed
+ *   - Recency            (0-15): bonus for sources with recent year patterns
+ */
+export declare function scoreResearchQuality(sources: FetchedSource[], _question: string, gapResult: GapDetectionResult): QualityScoreResult;
+/**
+ * Run a deep research session.
+ *
+ * Orchestrates query decomposition → multi-search → source fetching →
+ * relevance scoring → gap detection → re-search loop → synthesis.
+ */
+export declare function runDeepResearch(req: DeepResearchRequest): Promise<DeepResearchResponse>;
+export {};