/**
 * Temporal Analysis and Date-Aware Routing
 *
 * Extracts date/era information from queries and filters sources
 * based on their historical coverage.
 * @module core/search/temporal
 */
import type { DateRange } from '../query/types.js';
export interface SourceCoverage {
    /** Source identifier */
    source: string;
    /** Start year of coverage */
    fromYear: number;
    /** End year of coverage */
    toYear: number;
    /** Description of coverage */
    description: string;
}
export interface TemporalFilterResult {
    /** Sources that cover the date range */
    includedSources: string[];
    /** Sources excluded with reasons */
    excludedSources: Record<string, string>;
    /** Date range used for filtering */
    dateRange: DateRange;
}
/** Content types a source provides */
export type ContentType = 'newspaper' | 'image' | 'document' | 'object' | 'record' | 'map' | 'film' | 'audio';
/** Extended source coverage with content types and strengths */
export interface ExtendedSourceCoverage extends SourceCoverage {
    /** Types of content available from this source */
    contentTypes: ContentType[];
    /** What this source is best for */
    strengths: string[];
    /** Notable coverage gaps or limitations */
    limitations?: string;
}
/** Analysis of how a source covers a specific date range */
export interface SourceCoverageAnalysis {
    /** Source identifier */
    source: string;
    /** Coverage level for the query range */
    coverage: 'full' | 'partial' | 'none';
    /** Source's available date range */
    availableRange: {
        from: number;
        to: number;
    };
    /** Overlap between source and query (null if none) */
    overlapWithQuery: {
        from: number;
        to: number;
    } | null;
    /** Human-readable notes about coverage */
    notes: string;
    /** Content types available */
    contentTypes: ContentType[];
    /** Source strengths relevant to query period */
    strengths: string[];
}
/** Suggested research phase based on temporal coverage */
export interface SuggestedPhase {
    /** Phase number (1, 2, 3...) */
    phase: number;
    /** Period covered (e.g., "1920-1930") */
    period: string;
    /** Sources to query in this phase */
    sources: string[];
    /** Why this phase and these sources */
    rationale: string;
}
/** Complete temporal analysis for a research query */
export interface TemporalAnalysis {
    /** Per-source coverage analysis */
    coverageMatrix: Record<string, SourceCoverageAnalysis>;
    /** Actionable recommendations */
    recommendations: string[];
    /** Suggested research phases ordered by priority */
    suggestedPhases: SuggestedPhase[];
    /** Periods with no or limited coverage */
    gaps: string[];
    /** Date range analysed */
    queryRange: {
        from: number;
        to: number;
    };
}
/**
 * Historical date coverage for each source.
 * Used to exclude sources that don't cover the query's time period.
 */
export declare const SOURCE_COVERAGE: SourceCoverage[];
/**
 * Extended coverage data with content types and strengths.
 * Used for intelligent source routing and phase recommendations.
 */
export declare const EXTENDED_COVERAGE: ExtendedSourceCoverage[];
/**
 * Get coverage info for a source.
 */
export declare function getSourceCoverage(source: string): SourceCoverage | undefined;
/**
 * Check if a source covers a given date range.
 *
 * @param source - Source identifier
 * @param fromYear - Start year (or undefined for open start)
 * @param toYear - End year (or undefined for open end)
 * @returns true if any overlap exists
 */
export declare function sourceCoversDates(source: string, fromYear?: number, toYear?: number): boolean;
/**
 * Filter sources based on date coverage.
 *
 * @param sources - Source identifiers to filter
 * @param dateRange - Date range to filter by
 * @returns Filtered sources with exclusion reasons
 */
export declare function filterByDateCoverage(sources: string[], dateRange: DateRange): TemporalFilterResult;
/**
 * Parse a year from a date string.
 * Handles YYYY format.
 */
export declare function parseYear(dateStr: string): number | undefined;
/**
 * Get extended coverage info for a source.
 */
export declare function getExtendedCoverage(source: string): ExtendedSourceCoverage | undefined;
/**
 * Generate coverage analysis for each source against a date range.
 *
 * @param fromYear - Start year of query range
 * @param toYear - End year of query range
 * @param sources - Sources to analyse
 * @returns Per-source coverage analysis
 */
export declare function generateCoverageMatrix(fromYear: number, toYear: number, sources: string[]): Record<string, SourceCoverageAnalysis>;
/**
 * Generate recommended research phases based on coverage analysis.
 *
 * @param fromYear - Start year of query range
 * @param toYear - End year of query range
 * @param coverageMatrix - Per-source coverage analysis
 * @returns Ordered list of suggested research phases
 */
export declare function generatePhaseRecommendations(fromYear: number, toYear: number, coverageMatrix: Record<string, SourceCoverageAnalysis>): SuggestedPhase[];
/**
 * Identify gaps in coverage for the query period.
 *
 * @param fromYear - Start year of query range
 * @param toYear - End year of query range
 * @param coverageMatrix - Per-source coverage analysis
 * @returns List of gap descriptions
 */
export declare function identifyGaps(fromYear: number, toYear: number, coverageMatrix: Record<string, SourceCoverageAnalysis>): string[];
/**
 * Perform comprehensive temporal analysis for a research query.
 *
 * @param dateRange - Date range to analyse
 * @param sources - Sources to include in analysis (defaults to all)
 * @returns Complete temporal analysis with recommendations
 */
export declare function analyzeTemporalCoverage(dateRange: DateRange, sources?: string[]): TemporalAnalysis;
//# sourceMappingURL=temporal.d.ts.map