/**
 * @file EvaluationAggregator - Aggregates and analyzes evaluation results.
 * Provides statistical analysis, trend detection, and summary generation.
 */
import type { EvaluationData } from "../types/evaluation.js";
/**
 * Statistical summary of evaluation scores.
 */
export interface ScoreStatistics {
    /** Minimum score */
    min: number;
    /** Maximum score */
    max: number;
    /** Mean (average) score */
    mean: number;
    /** Median score */
    median: number;
    /** Standard deviation */
    stdDev: number;
    /** Variance */
    variance: number;
    /** 25th percentile */
    p25: number;
    /** 75th percentile */
    p75: number;
    /** 90th percentile */
    p90: number;
    /** 95th percentile */
    p95: number;
}
/**
 * Score distribution across ranges.
 */
export interface ScoreDistribution {
    /** Items scoring 1-3 (poor) */
    poor: number;
    /** Items scoring 4-5 (below average) */
    belowAverage: number;
    /** Items scoring 6-7 (average) */
    average: number;
    /** Items scoring 8-9 (good) */
    good: number;
    /** Items scoring 10 (excellent) */
    excellent: number;
}
/**
 * Trend analysis results.
 */
export interface TrendAnalysis {
    /** Direction of the trend */
    direction: "improving" | "declining" | "stable";
    /** Slope of the linear regression */
    slope: number;
    /** R-squared value (fit quality) */
    rSquared: number;
    /** Percentage change from first to last */
    percentChange: number;
    /** Moving average of last N evaluations */
    movingAverage: number;
}
/**
 * Dimension-specific analysis for RAGAS metrics.
 */
export interface DimensionAnalysis {
    /** Relevance score statistics */
    relevance: ScoreStatistics;
    /** Accuracy score statistics */
    accuracy: ScoreStatistics;
    /** Completeness score statistics */
    completeness: ScoreStatistics;
    /** Overall score statistics */
    overall: ScoreStatistics;
    /** Correlation matrix between dimensions */
    correlations: {
        relevanceAccuracy: number;
        relevanceCompleteness: number;
        accuracyCompleteness: number;
    };
}
/**
 * Quality alerts summary.
 */
export interface AlertSummary {
    /** Total number of alerts */
    total: number;
    /** Number of high severity alerts */
    high: number;
    /** Number of medium severity alerts */
    medium: number;
    /** Number of items marked as off-topic */
    offTopic: number;
    /** Alert rate as percentage */
    alertRate: number;
}
/**
 * Comprehensive aggregation result.
 */
export interface AggregationResult {
    /** Number of evaluations aggregated */
    count: number;
    /** Statistics for overall scores */
    statistics: ScoreStatistics;
    /** Score distribution */
    distribution: ScoreDistribution;
    /** Dimension-specific analysis */
    dimensions: DimensionAnalysis;
    /** Sequence trend analysis based on insertion order (not time-based) */
    sequenceTrend?: TrendAnalysis;
    /** Alert summary */
    alerts: AlertSummary;
    /** Passing rate based on threshold */
    passingRate: number;
    /** Average evaluation time */
    avgEvaluationTime: number;
    /** Aggregation metadata */
    metadata: {
        aggregatedAt: string;
        threshold: number;
        evaluationModels: string[];
    };
}
/**
 * EvaluationAggregator - Aggregates evaluation results and provides analytics.
 * Supports statistical analysis, trend detection, and quality monitoring.
 *
 * @example
 * ```typescript
 * const aggregator = new EvaluationAggregator();
 *
 * // Add evaluations
 * aggregator.addEvaluation(evaluation1);
 * aggregator.addEvaluation(evaluation2);
 *
 * // Get aggregation
 * const result = aggregator.aggregate({ threshold: 7 });
 * console.log(`Average score: ${result.statistics.mean}`);
 * console.log(`Passing rate: ${result.passingRate}%`);
 *
 * // Get trend analysis
 * const trend = aggregator.analyzeSequenceTrend();
 * console.log(`Quality is ${trend.direction}`);
 * ```
 */
export declare class EvaluationAggregator {
    private evaluations;
    /**
     * Adds an evaluation to the aggregator.
     *
     * @param evaluation - The evaluation data to add
     */
    addEvaluation(evaluation: EvaluationData): void;
    /**
     * Adds multiple evaluations to the aggregator.
     *
     * @param evaluations - Array of evaluation data to add
     */
    addEvaluations(evaluations: EvaluationData[]): void;
    /**
     * Clears all evaluations from the aggregator.
     */
    clear(): void;
    /**
     * Gets the current number of evaluations.
     */
    getCount(): number;
    /**
     * Gets all evaluations.
     */
    getEvaluations(): EvaluationData[];
    /**
     * Aggregates all evaluations and returns comprehensive statistics.
     *
     * @param options - Aggregation options
     * @returns Comprehensive aggregation result
     */
    aggregate(options?: {
        threshold?: number;
    }): AggregationResult;
    /**
     * Calculates statistical summary for a set of scores.
     *
     * @param scores - Array of scores
     * @returns Statistical summary
     */
    calculateStatistics(scores: number[]): ScoreStatistics;
    /**
     * Calculates the distribution of scores across quality ranges.
     *
     * @param scores - Array of scores
     * @returns Score distribution
     */
    calculateDistribution(scores: number[]): ScoreDistribution;
    /**
     * Analyzes sequence-based trends in evaluation scores (based on insertion order, not time).
     *
     * @param windowSize - Moving average window size (default: 5)
     * @returns Trend analysis
     */
    analyzeSequenceTrend(windowSize?: number): TrendAnalysis;
    /**
     * Analyzes each evaluation dimension separately.
     *
     * @param relevance - Relevance scores
     * @param accuracy - Accuracy scores
     * @param completeness - Completeness scores
     * @param overall - Overall scores
     * @returns Dimension analysis
     */
    private analyzeDimensions;
    /**
     * Summarizes alert information from evaluations.
     *
     * @returns Alert summary
     */
    private summarizeAlerts;
    /**
     * Calculates a specific percentile from sorted data.
     *
     * @param sorted - Sorted array of numbers
     * @param p - Percentile (0-100)
     * @returns The value at the percentile
     */
    private percentile;
    /**
     * Calculates Pearson correlation between two arrays.
     *
     * @param x - First array
     * @param y - Second array
     * @returns Correlation coefficient (-1 to 1)
     */
    private correlation;
    /**
     * Gets evaluations that failed to meet the threshold.
     *
     * @param threshold - The passing threshold
     * @returns Array of failing evaluations
     */
    getFailingEvaluations(threshold?: number): EvaluationData[];
    /**
     * Gets evaluations with high severity alerts.
     *
     * @returns Array of high-alert evaluations
     */
    getHighAlertEvaluations(): EvaluationData[];
    /**
     * Gets evaluations marked as off-topic.
     *
     * @returns Array of off-topic evaluations
     */
    getOffTopicEvaluations(): EvaluationData[];
    /**
     * Gets the top N performing evaluations.
     *
     * @param n - Number of evaluations to return
     * @returns Array of top evaluations
     */
    getTopEvaluations(n?: number): EvaluationData[];
    /**
     * Gets the bottom N performing evaluations.
     *
     * @param n - Number of evaluations to return
     * @returns Array of bottom evaluations
     */
    getBottomEvaluations(n?: number): EvaluationData[];
    /**
     * Generates a text summary of the aggregation.
     *
     * @param threshold - The passing threshold
     * @returns Human-readable summary
     */
    generateSummary(threshold?: number): string;
}
