/**
 * 벡터 검색 품질 검증 헬퍼
 * 벡터 검색 결과 순서 보존 검증 및 품질 지표 비교
 * Consolidation 점수 반영 전/후 비교를 위한 지표 계산
 */
import type { SearchResult, GroundTruth } from './search-quality-metrics.js';
import type { HybridSearchResult } from '@memento/core/domains/search/algorithms/hybrid-search-engine.js';
/**
 * 벡터-only 검색 결과와 Consolidation 반영 후 검색 결과 쌍
 */
export interface SearchResultPair {
    /**
     * 벡터 유사도만 사용한 검색 결과 (점수 순으로 정렬됨)
     */
    vectorOnly: SearchResult[];
    /**
     * Consolidation 점수 반영 후 검색 결과 (점수 순으로 정렬됨)
     */
    withConsolidation: SearchResult[];
}
/**
 * 순서 보존 지표
 * 벡터-only 결과와 Consolidation 반영 후 결과 간의 순서 일치도를 측정
 */
export interface OrderPreservationMetrics {
    /**
     * Kendall's Tau 순서 일치도 (-1 ~ 1)
     * 1에 가까울수록 순서가 일치함
     */
    kendallTau: number;
    /**
     * Spearman's Rho 순서 일치도 (-1 ~ 1)
     * 1에 가까울수록 순서가 일치함 (선택적)
     */
    spearmanRho?: number;
    /**
     * 상위 K개 결과 유지율 (0 ~ 1)
     * 벡터-only 상위 K개가 Consolidation 반영 후에도 상위에 유지되는 비율
     */
    topKRetention: Record<number, number>;
    /**
     * Top10 유지율 (0 ~ 1)
     * 벡터-only 상위 10개가 Consolidation 반영 후에도 상위에 유지되는 비율
     */
    top10Retention: number;
    /**
     * Top5 유지율 (0 ~ 1)
     * 벡터-only 상위 5개가 Consolidation 반영 후에도 상위에 유지되는 비율
     */
    top5Retention: number;
    /**
     * 전체 결과 수
     */
    totalResults: number;
}
/**
 * 순서 보존 검증 결과 리포트
 */
export interface OrderPreservationReport {
    /**
     * 리포트 생성 시간 (ISO 8601 형식)
     */
    timestamp?: string;
    /**
     * 순서 보존 지표
     */
    metrics: OrderPreservationMetrics;
    /**
     * 검증 통과 여부
     */
    passed: boolean;
    /**
     * 검증 실패 사유 (통과 시 undefined)
     */
    failureReasons?: string[];
    /**
     * 상세 검증 결과
     */
    validation: {
        /**
         * Kendall's Tau >= 0.7 검증
         */
        kendallTauValid: boolean;
        /**
         * Top10 유지율 >= 80% 검증
         */
        top10RetentionValid: boolean;
        /**
         * Top5 유지율 >= 90% 검증
         */
        top5RetentionValid: boolean;
    };
    /**
     * 검증 임계값 (선택적)
     */
    thresholds?: {
        kendallTauThreshold?: number;
        top10RetentionThreshold?: number;
        top5RetentionThreshold?: number;
    };
}
/**
 * Kendall's Tau-b 순서 일치도 계산
 * 두 순서 간의 순위 상관관계를 측정 (-1 ~ 1)
 *
 * Tau-b는 동점(tie)을 처리하는 버전으로, 검색 결과에서 동일 점수를 가진 항목들을 올바르게 처리합니다.
 *
 * @param order1 첫 번째 순서 (ID 배열, 점수 순으로 정렬됨)
 * @param order2 두 번째 순서 (ID 배열, 점수 순으로 정렬됨)
 * @returns Kendall's Tau-b 값 (-1 ~ 1)
 *   - 1: 완전히 일치하는 순서
 *   - 0: 무관한 순서
 *   - -1: 완전히 반대인 순서
 *
 * @example
 * ```typescript
 * const order1 = ['id1', 'id2', 'id3', 'id4'];
 * const order2 = ['id1', 'id3', 'id2', 'id4'];
 * const tau = calculateKendallTau(order1, order2);
 * // tau는 0.67 정도 (부분적으로 일치)
 * ```
 */
export declare function calculateKendallTau(order1: string[], order2: string[]): number;
/**
 * Spearman's Rho 순서 일치도 계산
 * 두 순서 간의 순위 상관관계를 측정 (-1 ~ 1)
 *
 * Spearman's Rho는 순위 차이를 기반으로 계산되며, Kendall's Tau와 함께 사용하여
 * 순서 보존 정도를 다각도로 검증할 수 있습니다.
 *
 * @param order1 첫 번째 순서 (ID 배열, 점수 순으로 정렬됨)
 * @param order2 두 번째 순서 (ID 배열, 점수 순으로 정렬됨)
 * @returns Spearman's Rho 값 (-1 ~ 1)
 *   - 1: 완전히 일치하는 순서
 *   - 0: 무관한 순서
 *   - -1: 완전히 반대인 순서
 *
 * @example
 * ```typescript
 * const order1 = ['id1', 'id2', 'id3', 'id4'];
 * const order2 = ['id1', 'id3', 'id2', 'id4'];
 * const rho = calculateSpearmanRho(order1, order2);
 * // rho는 0.8 정도 (대체로 일치)
 * ```
 */
export declare function calculateSpearmanRho(order1: string[], order2: string[]): number;
/**
 * 상위 K개 결과 유지율 계산
 * 벡터-only 상위 K개가 Consolidation 반영 후에도 상위에 유지되는 비율
 *
 * Acceptance Criteria:
 * - Top10 유지율 >= 80%
 * - Top5 유지율 >= 90%
 *
 * @param pair 벡터-only와 Consolidation 반영 후 검색 결과 쌍
 * @param kValues 계산할 K 값 배열 (예: [5, 10])
 * @returns K 값별 유지율 (0 ~ 1)
 *
 * @example
 * ```typescript
 * const pair = {
 *   vectorOnly: [{ id: 'id1' }, { id: 'id2' }, { id: 'id3' }, ...],
 *   withConsolidation: [{ id: 'id1' }, { id: 'id3' }, { id: 'id2' }, ...]
 * };
 * const retention = calculateTopKRetention(pair, [5, 10]);
 * // retention = { 5: 0.8, 10: 0.7 }
 * ```
 */
export declare function calculateTopKRetention(pair: SearchResultPair, kValues?: number[]): Record<number, number>;
/**
 * 벡터 유사도만 사용한 검색 결과 생성
 * Consolidation 점수를 제외하고 벡터 유사도만으로 정렬한 결과를 생성합니다.
 *
 * 이 함수는 실제 검색 결과를 받아서 벡터 유사도만으로 재정렬합니다.
 * 벡터 유사도가 없는 경우 textScore를 사용하거나, 해당 결과를 제외할 수 있습니다.
 *
 * @param searchResults 실제 검색 결과 (HybridSearchResult 배열)
 * @param limit 반환할 결과 수 (기본값: 전체)
 * @returns 벡터 유사도만으로 정렬된 SearchResult 배열
 *
 * @example
 * ```typescript
 * const results = await hybridSearchEngine.search(query, options);
 * const vectorOnlyResults = generateVectorOnlySearchResults(results);
 * ```
 */
export declare function generateVectorOnlySearchResults(searchResults: HybridSearchResult[], limit?: number): SearchResult[];
/**
 * Consolidation 점수 반영 후 검색 결과 생성
 * 벡터 유사도와 Consolidation 점수가 모두 반영된 최종 점수로 정렬한 결과를 생성합니다.
 *
 * 이 함수는 실제 검색 결과를 받아서 finalScore(벡터 유사도 + Consolidation 점수)로 정렬합니다.
 * finalScore는 이미 검색 엔진에서 계산된 최종 점수입니다.
 *
 * @param searchResults 실제 검색 결과 (HybridSearchResult 배열)
 * @param limit 반환할 결과 수 (기본값: 전체)
 * @returns Consolidation 점수 반영 후 정렬된 SearchResult 배열
 *
 * @example
 * ```typescript
 * const results = await hybridSearchEngine.search(query, options);
 * const consolidationResults = generateConsolidationSearchResults(results);
 * ```
 */
export declare function generateConsolidationSearchResults(searchResults: HybridSearchResult[], limit?: number): SearchResult[];
/**
 * 순서 보존 검증 결과 리포트 생성
 * 벡터-only 결과와 Consolidation 반영 후 결과 간의 순서 보존 정도를 검증하고 리포트를 생성합니다.
 *
 * Acceptance Criteria:
 * - Kendall's Tau >= 0.7
 * - Top10 유지율 >= 80%
 * - Top5 유지율 >= 90%
 *
 * @param pair 벡터-only와 Consolidation 반영 후 검색 결과 쌍
 * @param options 리포트 생성 옵션
 * @param options.includeSpearmanRho Spearman's Rho 계산 포함 여부 (기본값: false)
 * @param options.kValues TopK 유지율 계산할 K 값 배열 (기본값: [5, 10])
 * @param options.kendallTauThreshold Kendall's Tau 임계값 (기본값: 0.7)
 * @param options.top10RetentionThreshold Top10 유지율 임계값 (기본값: 0.8)
 * @param options.top5RetentionThreshold Top5 유지율 임계값 (기본값: 0.9)
 * @returns 순서 보존 검증 결과 리포트
 *
 * @example
 * ```typescript
 * const pair = {
 *   vectorOnly: vectorOnlyResults,
 *   withConsolidation: consolidationResults
 * };
 * const report = generateOrderPreservationReport(pair);
 * console.log(`검증 통과: ${report.passed}`);
 * ```
 */
export declare function generateOrderPreservationReport(pair: SearchResultPair, options?: {
    includeSpearmanRho?: boolean;
    kValues?: number[];
    kendallTauThreshold?: number;
    top10RetentionThreshold?: number;
    top5RetentionThreshold?: number;
}): OrderPreservationReport;
/**
 * 품질 지표 인터페이스
 */
export interface QualityMetrics {
    /**
     * Precision@K 값들 (K 값별)
     */
    precision: Record<number, number>;
    /**
     * Recall@K 값들 (K 값별)
     */
    recall: Record<number, number>;
    /**
     * NDCG@K 값들 (K 값별)
     */
    ndcg: Record<number, number>;
}
/**
 * 벡터 유사도만 사용한 검색 결과에서 품질 지표 측정
 * Ground Truth를 기반으로 Precision/Recall/NDCG를 계산합니다.
 *
 * @param results 벡터 유사도만으로 정렬된 검색 결과
 * @param groundTruth Ground Truth (관련 결과 ID 목록)
 * @param kValues 계산할 K 값 배열 (기본값: [1, 5, 10])
 * @returns 품질 지표 (Precision/Recall/NDCG)
 *
 * @example
 * ```typescript
 * const vectorOnlyResults = generateVectorOnlySearchResults(searchResults);
 * const groundTruth = { queryId: 'query1', relevantIds: ['id1', 'id2', 'id3'] };
 * const metrics = measureVectorOnlyQuality(vectorOnlyResults, groundTruth);
 * console.log(`NDCG@5: ${metrics.ndcg[5]}`);
 * ```
 */
export declare function measureVectorOnlyQuality(results: SearchResult[], groundTruth: {
    queryId: string;
    relevantIds: string[];
}, kValues?: number[]): QualityMetrics;
/**
 * Consolidation 점수 반영 후 검색 결과에서 품질 지표 측정
 * Ground Truth를 기반으로 Precision/Recall/NDCG를 계산합니다.
 *
 * @param results Consolidation 점수 반영 후 정렬된 검색 결과
 * @param groundTruth Ground Truth (관련 결과 ID 목록)
 * @param kValues 계산할 K 값 배열 (기본값: [1, 5, 10])
 * @returns 품질 지표 (Precision/Recall/NDCG)
 *
 * @example
 * ```typescript
 * const consolidationResults = generateConsolidationSearchResults(searchResults);
 * const groundTruth = { queryId: 'query1', relevantIds: ['id1', 'id2', 'id3'] };
 * const metrics = measureConsolidationQuality(consolidationResults, groundTruth);
 * console.log(`NDCG@5: ${metrics.ndcg[5]}`);
 * ```
 */
export declare function measureConsolidationQuality(results: SearchResult[], groundTruth: {
    queryId: string;
    relevantIds: string[];
}, kValues?: number[]): QualityMetrics;
/**
 * 품질 저하율 인터페이스
 */
export interface QualityDegradation {
    /**
     * Precision@K 저하율 (K 값별, 0-1)
     * 양수면 저하, 음수면 개선
     */
    precision: Record<number, number>;
    /**
     * Recall@K 저하율 (K 값별, 0-1)
     * 양수면 저하, 음수면 개선
     */
    recall: Record<number, number>;
    /**
     * NDCG@K 저하율 (K 값별, 0-1)
     * 양수면 저하, 음수면 개선
     */
    ndcg: Record<number, number>;
}
/**
 * 품질 저하율 계산
 * 벡터-only 품질과 Consolidation 반영 후 품질을 비교하여 저하율을 계산합니다.
 *
 * 저하율 공식: (vectorOnly - consolidation) / vectorOnly
 * - 양수: 품질 저하
 * - 음수: 품질 개선
 * - 0: 변화 없음
 *
 * @param vectorOnlyMetrics 벡터-only 품질 지표
 * @param consolidationMetrics Consolidation 반영 후 품질 지표
 * @param kValues 계산할 K 값 배열 (기본값: [1, 5, 10])
 * @returns 품질 저하율 (K 값별)
 *
 * @example
 * ```typescript
 * const vectorOnlyMetrics = measureVectorOnlyQuality(vectorOnlyResults, groundTruth);
 * const consolidationMetrics = measureConsolidationQuality(consolidationResults, groundTruth);
 * const degradation = calculateQualityDegradation(vectorOnlyMetrics, consolidationMetrics);
 * console.log(`NDCG@5 저하율: ${(degradation.ndcg[5] * 100).toFixed(2)}%`);
 * ```
 */
export declare function calculateQualityDegradation(vectorOnlyMetrics: QualityMetrics, consolidationMetrics: QualityMetrics, kValues?: number[]): QualityDegradation;
/**
 * 품질 저하 임계값 검증 결과
 */
export interface QualityThresholdValidation {
    /**
     * 검증 통과 여부
     */
    passed: boolean;
    /**
     * 검증 실패 사유 (통과 시 undefined)
     */
    failureReasons?: string[];
    /**
     * 상세 검증 결과
     */
    validation: {
        /**
         * NDCG@5 저하율 < 5% 검증
         */
        ndcg5Valid: boolean;
        /**
         * Precision@5 저하율 < 10% 검증
         */
        precision5Valid: boolean;
        /**
         * Recall@5 저하율 < 10% 검증
         */
        recall5Valid: boolean;
    };
    /**
     * 실제 저하율 값
     */
    degradation: {
        ndcg5: number;
        precision5: number;
        recall5: number;
    };
}
/**
 * 품질 저하 임계값 검증
 * 품질 저하율이 임계값을 초과하지 않는지 검증합니다.
 *
 * Acceptance Criteria:
 * - NDCG@5 저하율 < 5%
 * - Precision@5 저하율 < 10%
 * - Recall@5 저하율 < 10%
 *
 * @param degradation 품질 저하율
 * @param options 검증 옵션
 * @param options.ndcg5Threshold NDCG@5 저하율 임계값 (기본값: 0.05 = 5%)
 * @param options.precision5Threshold Precision@5 저하율 임계값 (기본값: 0.10 = 10%)
 * @param options.recall5Threshold Recall@5 저하율 임계값 (기본값: 0.10 = 10%)
 * @returns 검증 결과
 *
 * @example
 * ```typescript
 * const degradation = calculateQualityDegradation(vectorOnlyMetrics, consolidationMetrics);
 * const validation = validateQualityThresholds(degradation);
 * if (!validation.passed) {
 *   console.error('품질 저하 임계값 초과:', validation.failureReasons);
 * }
 * ```
 */
export declare function validateQualityThresholds(degradation: QualityDegradation, options?: {
    ndcg5Threshold?: number;
    precision5Threshold?: number;
    recall5Threshold?: number;
}): QualityThresholdValidation;
/**
 * Ground Truth 기반 품질 비교 결과
 */
export interface QualityComparison {
    /**
     * 벡터-only 품질 지표
     */
    vectorOnly: QualityMetrics;
    /**
     * Consolidation 반영 후 품질 지표
     */
    consolidation: QualityMetrics;
    /**
     * 품질 저하율
     */
    degradation: QualityDegradation;
    /**
     * 품질 저하 임계값 검증 결과
     */
    thresholdValidation: QualityThresholdValidation;
}
/**
 * Ground Truth 기반 품질 비교
 * 벡터-only 결과와 Consolidation 반영 후 결과를 Ground Truth와 비교하여 품질을 측정하고 비교합니다.
 *
 * @param vectorOnlyResults 벡터 유사도만으로 정렬된 검색 결과
 * @param consolidationResults Consolidation 점수 반영 후 정렬된 검색 결과
 * @param groundTruth Ground Truth (관련 결과 ID 목록)
 * @param kValues 계산할 K 값 배열 (기본값: [1, 5, 10])
 * @param thresholdOptions 품질 저하 임계값 검증 옵션
 * @returns 품질 비교 결과
 *
 * @example
 * ```typescript
 * const vectorOnlyResults = generateVectorOnlySearchResults(searchResults);
 * const consolidationResults = generateConsolidationSearchResults(searchResults);
 * const groundTruth = { queryId: 'query1', relevantIds: ['id1', 'id2', 'id3'] };
 * const comparison = compareQualityWithGroundTruth(
 *   vectorOnlyResults,
 *   consolidationResults,
 *   groundTruth
 * );
 * console.log(`벡터-only NDCG@5: ${comparison.vectorOnly.ndcg[5]}`);
 * console.log(`Consolidation NDCG@5: ${comparison.consolidation.ndcg[5]}`);
 * console.log(`검증 통과: ${comparison.thresholdValidation.passed}`);
 * ```
 */
export declare function compareQualityWithGroundTruth(vectorOnlyResults: SearchResult[], consolidationResults: SearchResult[], groundTruth: {
    queryId: string;
    relevantIds: string[];
}, kValues?: number[], thresholdOptions?: {
    ndcg5Threshold?: number;
    precision5Threshold?: number;
    recall5Threshold?: number;
}): QualityComparison;
/**
 * 품질 비교 결과 리포트
 */
export interface QualityComparisonReport {
    /**
     * 리포트 생성 시간
     */
    timestamp: string;
    /**
     * Ground Truth 정보
     */
    groundTruth: {
        queryId: string;
        relevantIdsCount: number;
    };
    /**
     * 벡터-only 품질 지표
     */
    vectorOnly: QualityMetrics;
    /**
     * Consolidation 반영 후 품질 지표
     */
    withConsolidation: QualityMetrics;
    /**
     * 품질 저하율
     */
    degradation: QualityDegradation;
    /**
     * 품질 저하 임계값 검증 결과
     */
    thresholdValidation: QualityThresholdValidation;
    /**
     * 요약 정보
     */
    summary: {
        /**
         * 검증 통과 여부
         */
        passed: boolean;
        /**
         * 주요 지표 요약 (K=5 기준)
         */
        keyMetrics: {
            vectorOnlyNDCG5: number;
            consolidationNDCG5: number;
            ndcg5Degradation: number;
        };
    };
}
/**
 * 품질 비교 결과 리포트 생성
 * Ground Truth 기반 품질 비교 결과를 구조화된 리포트 형식으로 생성합니다.
 *
 * @param comparison 품질 비교 결과
 * @param groundTruth Ground Truth 정보
 * @returns 품질 비교 결과 리포트
 *
 * @example
 * ```typescript
 * const comparison = compareQualityWithGroundTruth(
 *   vectorOnlyResults,
 *   consolidationResults,
 *   groundTruth
 * );
 * const report = generateQualityComparisonReport(comparison, groundTruth);
 * console.log(JSON.stringify(report, null, 2));
 * ```
 */
export declare function generateQualityComparisonReport(comparison: QualityComparison, groundTruth: {
    queryId: string;
    relevantIds: string[];
}): QualityComparisonReport;
/**
 * 품질 비교 결과 시각화
 * 품질 비교 결과를 Markdown 표 형식으로 시각화합니다.
 *
 * @param report 품질 비교 결과 리포트
 * @param options 시각화 옵션
 * @param options.kValues 표시할 K 값 배열 (기본값: [1, 5, 10])
 * @param options.includeDegradation 저하율 포함 여부 (기본값: true)
 * @returns Markdown 형식의 시각화된 리포트
 *
 * @example
 * ```typescript
 * const report = generateQualityComparisonReport(comparison, groundTruth);
 * const visualization = visualizeQualityComparison(report);
 * console.log(visualization);
 * ```
 */
export declare function visualizeQualityComparison(report: QualityComparisonReport, options?: {
    kValues?: number[];
    includeDegradation?: boolean;
}): string;
/**
 * 극단적 시나리오 검증 결과
 */
export interface ExtremeScenarioValidation {
    /**
     * 검증 통과 여부
     */
    passed: boolean;
    /**
     * 검증 실패 사유 (통과 시 undefined)
     */
    failureReasons?: string[];
    /**
     * 최종 점수 범위
     */
    finalScoreRange: {
        min: number;
        max: number;
        average: number;
    };
    /**
     * 벡터 유사도 통계
     */
    vectorSimilarityStats: {
        min: number;
        max: number;
        average: number;
    };
    /**
     * Consolidation 점수 통계
     */
    consolidationScoreStats: {
        min: number;
        max: number;
        average: number;
    };
}
/**
 * 저벡터 유사도 + 고 consolidation 점수 시나리오 검증
 * 벡터 유사도는 낮지만 consolidation 점수가 매우 높은 경우의 랭킹을 검증합니다.
 *
 * 예: 벡터 유사도 0.3, consolidation 0.9
 * 최종 점수가 합리적인 범위 내인지 검증합니다.
 *
 * @param results 검색 결과 (HybridSearchResult 배열)
 * @param options 검증 옵션
 * @param options.lowVectorThreshold 저벡터 유사도 임계값 (기본값: 0.4)
 * @param options.highConsolidationThreshold 고 consolidation 점수 임계값 (기본값: 0.7)
 * @param options.minFinalScore 최종 점수 최소값 (기본값: 0.0)
 * @param options.maxFinalScore 최종 점수 최대값 (기본값: 1.0)
 * @returns 검증 결과
 *
 * @example
 * ```typescript
 * const results = await hybridSearchEngine.search(query, options);
 * const validation = validateLowVectorHighConsolidation(results);
 * if (!validation.passed) {
 *   console.error('극단적 시나리오 검증 실패:', validation.failureReasons);
 * }
 * ```
 */
export declare function validateLowVectorHighConsolidation(results: HybridSearchResult[], options?: {
    lowVectorThreshold?: number;
    highConsolidationThreshold?: number;
    minFinalScore?: number;
    maxFinalScore?: number;
}): ExtremeScenarioValidation;
/**
 * 고벡터 유사도 + 저 consolidation 점수 시나리오 검증
 * 벡터 유사도는 높지만 consolidation 점수가 낮은 경우의 랭킹을 검증합니다.
 *
 * 예: 벡터 유사도 0.9, consolidation 0.1
 * 벡터 유사도가 우선 반영되는지 검증합니다.
 *
 * @param results 검색 결과 (HybridSearchResult 배열)
 * @param options 검증 옵션
 * @param options.highVectorThreshold 고벡터 유사도 임계값 (기본값: 0.7)
 * @param options.lowConsolidationThreshold 저 consolidation 점수 임계값 (기본값: 0.3)
 * @param options.vectorPriorityRatio 벡터 유사도가 최종 점수에 미치는 최소 영향 비율 (기본값: 0.6)
 * @returns 검증 결과
 *
 * @example
 * ```typescript
 * const results = await hybridSearchEngine.search(query, options);
 * const validation = validateHighVectorLowConsolidation(results);
 * if (!validation.passed) {
 *   console.error('극단적 시나리오 검증 실패:', validation.failureReasons);
 * }
 * ```
 */
export declare function validateHighVectorLowConsolidation(results: HybridSearchResult[], options?: {
    highVectorThreshold?: number;
    lowConsolidationThreshold?: number;
    vectorPriorityRatio?: number;
}): ExtremeScenarioValidation;
/**
 * w2 상한 검증 결과
 */
export interface W2UpperBoundValidation {
    /**
     * 검증 통과 여부
     */
    passed: boolean;
    /**
     * 검증 실패 사유 (통과 시 undefined)
     */
    failureReasons?: string[];
    /**
     * w2=0.4일 때 품질 지표
     */
    w2_04: QualityMetrics;
    /**
     * w2=0.6일 때 품질 지표
     */
    w2_06: QualityMetrics;
    /**
     * 품질 저하율 (w2=0.4 대비 w2=0.6)
     */
    degradation: QualityDegradation;
    /**
     * w2 상한이 품질을 보호하는지 여부
     */
    w2UpperBoundProtects: boolean;
}
/**
 * w2 상한(0.4) 검증
 * w2=0.4일 때와 w2=0.6일 때의 품질을 비교하여 w2 상한이 벡터 검색 품질을 보호하는지 검증합니다.
 *
 * w2가 높을수록 consolidation 점수의 영향이 커지므로, w2=0.6일 때 품질이 저하되는지 확인합니다.
 *
 * @param originalResults 원본 검색 결과 (HybridSearchResult 배열, vectorScore와 consolidation_score 포함)
 * @param groundTruth Ground Truth
 * @param kValues 계산할 K 값 배열 (기본값: [1, 5, 10])
 * @returns 검증 결과
 *
 * @example
 * ```typescript
 * const results = await hybridSearchEngine.search(query, options);
 * const validation = validateW2UpperBound(results, groundTruth);
 * console.log(`w2 상한 보호: ${validation.w2UpperBoundProtects}`);
 * ```
 */
export declare function validateW2UpperBound(originalResults: HybridSearchResult[], groundTruth: {
    queryId: string;
    relevantIds: string[];
}, kValues?: number[]): W2UpperBoundValidation;
/**
 * 극단적 시나리오 검증 결과 리포트
 */
export interface ExtremeScenarioReport {
    /**
     * 리포트 생성 시간
     */
    timestamp: string;
    /**
     * 저벡터 유사도 + 고 consolidation 점수 검증 결과
     */
    lowVectorHighConsolidation: ExtremeScenarioValidation;
    /**
     * 고벡터 유사도 + 저 consolidation 점수 검증 결과
     */
    highVectorLowConsolidation: ExtremeScenarioValidation;
    /**
     * w2 상한 검증 결과
     */
    w2UpperBound: W2UpperBoundValidation;
    /**
     * 전체 검증 통과 여부
     */
    overallPassed: boolean;
    /**
     * 요약 정보
     */
    summary: {
        /**
         * 검증 통과한 시나리오 수
         */
        passedCount: number;
        /**
         * 전체 시나리오 수
         */
        totalCount: number;
        /**
         * 실패한 시나리오 목록
         */
        failedScenarios: string[];
    };
}
/**
 * 극단적 시나리오 검증 결과 리포트 생성
 * 저벡터+고 consolidation, 고벡터+저 consolidation, w2 상한 검증 결과를 종합하여 리포트를 생성합니다.
 *
 * @param lowVectorHighConsolidation 저벡터 유사도 + 고 consolidation 점수 검증 결과
 * @param highVectorLowConsolidation 고벡터 유사도 + 저 consolidation 점수 검증 결과
 * @param w2UpperBound w2 상한 검증 결과
 * @returns 극단적 시나리오 검증 결과 리포트
 *
 * @example
 * ```typescript
 * const lowVectorHigh = validateLowVectorHighConsolidation(results);
 * const highVectorLow = validateHighVectorLowConsolidation(results);
 * const w2Validation = validateW2UpperBound(results, groundTruth);
 * const report = generateExtremeScenarioReport(
 *   lowVectorHigh,
 *   highVectorLow,
 *   w2Validation
 * );
 * console.log(`전체 검증 통과: ${report.overallPassed}`);
 * ```
 */
export declare function generateExtremeScenarioReport(lowVectorHighConsolidation: ExtremeScenarioValidation, highVectorLowConsolidation: ExtremeScenarioValidation, w2UpperBound: W2UpperBoundValidation): ExtremeScenarioReport;
/**
 * Baseline 스냅샷 인터페이스
 * 벡터 검색 품질의 baseline을 저장하고 비교하기 위한 구조
 */
export interface BaselineSnapshot {
    /**
     * 스냅샷 버전
     */
    version: string;
    /**
     * 스냅샷 생성 시간 (ISO 8601 형식)
     */
    timestamp: string;
    /**
     * 테스트 설정 정보
     */
    testConfiguration: {
        /**
         * 테스트 데이터 크기
         */
        dataSize: number;
        /**
         * 가중치 설정
         */
        weights: {
            /**
             * 벡터 유사도 가중치 (w1)
             */
            vectorSimilarity: number;
            /**
             * Consolidation 점수 가중치 (w2)
             */
            consolidationScore: number;
        };
    };
    /**
     * 품질 지표
     */
    metrics: {
        /**
         * 순서 보존 지표
         */
        orderPreservation: {
            /**
             * Kendall's Tau 순서 일치도
             */
            kendallTau: number;
            /**
             * 상위 10개 결과 유지율
             */
            top10Retention: number;
            /**
             * 상위 5개 결과 유지율
             */
            top5Retention: number;
        };
        /**
         * 품질 지표 (Precision, Recall, NDCG)
         */
        quality: {
            /**
             * Precision@K (K 값별 Precision)
             */
            precision: Record<number, number>;
            /**
             * Recall@K (K 값별 Recall)
             */
            recall: Record<number, number>;
            /**
             * NDCG@K (K 값별 NDCG)
             */
            ndcg: Record<number, number>;
        };
        /**
         * 극단적 시나리오 검증 결과
         */
        extremeScenarios: {
            /**
             * 저벡터 유사도 + 고 consolidation 점수 검증 통과 여부 (1: 통과, 0: 실패)
             */
            lowVectorHighConsolidation: number;
            /**
             * 고벡터 유사도 + 저 consolidation 점수 검증 통과 여부 (1: 통과, 0: 실패)
             */
            highVectorLowConsolidation: number;
        };
    };
}
/**
 * Baseline 스냅샷 저장
 * Baseline 스냅샷을 JSON 형식으로 파일에 저장합니다.
 *
 * @param snapshot 저장할 Baseline 스냅샷
 * @param filePath 저장할 파일 경로 (기본값: `data/vector-search-quality-baseline.json`)
 * @throws 파일 저장 실패 시 에러 발생
 *
 * @example
 * ```typescript
 * const snapshot: BaselineSnapshot = {
 *   version: '1.0.0',
 *   timestamp: new Date().toISOString(),
 *   testConfiguration: { dataSize: 100, weights: { vectorSimilarity: 0.6, consolidationScore: 0.4 } },
 *   metrics: {
 *     orderPreservation: { kendallTau: 0.85, top10Retention: 0.9, top5Retention: 0.95 },
 *     quality: { precision: {}, recall: {}, ndcg: {} },
 *     extremeScenarios: { lowVectorHighConsolidation: 1, highVectorLowConsolidation: 1 }
 *   }
 * };
 * saveBaselineSnapshot(snapshot);
 * ```
 */
export declare function saveBaselineSnapshot(snapshot: BaselineSnapshot, filePath?: string): void;
/**
 * Baseline 스냅샷 로드
 * 저장된 Baseline 스냅샷을 파일에서 로드합니다.
 *
 * @param filePath 로드할 파일 경로 (기본값: `data/vector-search-quality-baseline.json`)
 * @returns 로드된 Baseline 스냅샷 또는 null (파일이 없거나 로드 실패 시)
 *
 * @example
 * ```typescript
 * const snapshot = loadBaselineSnapshot();
 * if (snapshot) {
 *   console.log(`Baseline 버전: ${snapshot.version}`);
 *   console.log(`Baseline 생성 시간: ${snapshot.timestamp}`);
 * } else {
 *   console.log('Baseline 스냅샷이 없습니다.');
 * }
 * ```
 */
export declare function loadBaselineSnapshot(filePath?: string): BaselineSnapshot | null;
/**
 * Baseline 비교 결과
 */
export interface BaselineComparisonResult {
    /**
     * Baseline 스냅샷 정보
     */
    baseline: {
        version: string;
        timestamp: string;
    };
    /**
     * 순서 보존 지표 비교 결과
     */
    orderPreservation: {
        /**
         * Kendall's Tau 변화 (현재 - baseline)
         */
        kendallTauChange: number;
        /**
         * Top10 유지율 변화 (현재 - baseline)
         */
        top10RetentionChange: number;
        /**
         * Top5 유지율 변화 (현재 - baseline)
         */
        top5RetentionChange: number;
    };
    /**
     * 품질 지표 비교 결과
     */
    quality: {
        /**
         * Precision@K 변화율 (K 값별)
         */
        precisionChange: Record<number, number>;
        /**
         * Recall@K 변화율 (K 값별)
         */
        recallChange: Record<number, number>;
        /**
         * NDCG@K 변화율 (K 값별)
         */
        ndcgChange: Record<number, number>;
    };
    /**
     * 극단적 시나리오 검증 비교 결과
     */
    extremeScenarios: {
        /**
         * 저벡터 유사도 + 고 consolidation 점수 검증 변화 (현재 - baseline)
         */
        lowVectorHighConsolidationChange: number;
        /**
         * 고벡터 유사도 + 저 consolidation 점수 검증 변화 (현재 - baseline)
         */
        highVectorLowConsolidationChange: number;
    };
    /**
     * 전체 품질 저하 여부
     */
    hasDegradation: boolean;
    /**
     * 품질 저하 세부 사항
     */
    degradationDetails: string[];
}
/**
 * Baseline과 현재 결과 비교
 * Baseline 스냅샷과 현재 검증 결과를 비교하여 품질 저하를 감지합니다.
 *
 * @param baseline Baseline 스냅샷
 * @param currentOrderPreservation 현재 순서 보존 검증 결과
 * @param currentQuality 현재 품질 지표 (QualityMetrics)
 * @param currentExtremeScenarios 현재 극단적 시나리오 검증 결과
 * @param kValues 비교할 K 값 배열 (기본값: [1, 5, 10])
 * @returns Baseline 비교 결과
 *
 * @example
 * ```typescript
 * const baseline = loadBaselineSnapshot();
 * if (baseline) {
 *   const comparison = compareWithBaseline(
 *     baseline,
 *     orderPreservationReport,
 *     qualityMetrics,
 *     extremeScenarioReport
 *   );
 *   if (comparison.hasDegradation) {
 *     console.warn('품질 저하 감지:', comparison.degradationDetails);
 *   }
 * }
 * ```
 */
export declare function compareWithBaseline(baseline: BaselineSnapshot, currentOrderPreservation: OrderPreservationReport, currentQuality: QualityMetrics, currentExtremeScenarios: ExtremeScenarioReport, kValues?: number[]): BaselineComparisonResult;
/**
 * 품질 저하 감지 결과
 */
export interface QualityDegradationDetection {
    /**
     * 품질 저하 감지 여부
     */
    detected: boolean;
    /**
     * 심각도 레벨
     */
    severity: 'none' | 'warning' | 'critical';
    /**
     * 품질 저하 메시지 목록
     */
    messages: string[];
    /**
     * Baseline 비교 결과
     */
    comparison: BaselineComparisonResult;
    /**
     * 권장 조치 사항
     */
    recommendations: string[];
}
/**
 * 품질 저하 감지 및 알림
 * Baseline 비교 결과를 분석하여 품질 저하를 감지하고 알림을 생성합니다.
 *
 * @param comparison Baseline 비교 결과
 * @param options 감지 옵션
 * @param options.ndcg5Threshold NDCG@5 저하 임계값 (기본값: 0.05 = 5%)
 * @param options.precision5Threshold Precision@5 저하 임계값 (기본값: 0.10 = 10%)
 * @param options.recall5Threshold Recall@5 저하 임계값 (기본값: 0.10 = 10%)
 * @param options.kendallTauThreshold Kendall's Tau 저하 임계값 (기본값: 0.1)
 * @param options.criticalThreshold 심각한 저하 임계값 (기본값: 0.20 = 20%)
 * @returns 품질 저하 감지 결과
 *
 * @example
 * ```typescript
 * const comparison = compareWithBaseline(baseline, ...);
 * const detection = detectQualityDegradation(comparison);
 * if (detection.detected) {
 *   console.warn(`[${detection.severity.toUpperCase()}] 품질 저하 감지:`);
 *   detection.messages.forEach(msg => console.warn(`  - ${msg}`));
 * }
 * ```
 */
export declare function detectQualityDegradation(comparison: BaselineComparisonResult, options?: {
    ndcg5Threshold?: number;
    precision5Threshold?: number;
    recall5Threshold?: number;
    kendallTauThreshold?: number;
    criticalThreshold?: number;
}): QualityDegradationDetection;
/**
 * 경고 메시지 출력 옵션
 */
export interface QualityAlertOptions {
    /**
     * 출력 대상 ('console' | 'file' | 'both')
     */
    output?: 'console' | 'file' | 'both';
    /**
     * 파일 경로 (output이 'file' 또는 'both'일 때 사용)
     */
    filePath?: string;
    /**
     * 색상 사용 여부 (콘솔 출력 시, 기본값: true)
     */
    useColors?: boolean;
    /**
     * 상세 정보 포함 여부 (기본값: true)
     */
    includeDetails?: boolean;
    /**
     * Baseline 정보 포함 여부 (기본값: true)
     */
    includeBaselineInfo?: boolean;
}
/**
 * 품질 저하 경고 메시지 출력
 * 품질 저하 감지 결과를 사용자 친화적인 형식으로 출력합니다.
 *
 * @param detection 품질 저하 감지 결과
 * @param options 출력 옵션
 *
 * @example
 * ```typescript
 * const detection = detectQualityDegradation(comparison);
 * printQualityAlert(detection, { output: 'console', useColors: true });
 * ```
 */
export declare function printQualityAlert(detection: QualityDegradationDetection, options?: QualityAlertOptions): void;
/**
 * 품질 저하 감지 및 경고 출력 (통합 함수)
 * Baseline 비교 결과를 분석하여 품질 저하를 감지하고 경고 메시지를 출력합니다.
 *
 * @param comparison Baseline 비교 결과
 * @param detectionOptions 감지 옵션
 * @param alertOptions 경고 출력 옵션
 * @returns 품질 저하 감지 결과
 *
 * @example
 * ```typescript
 * const comparison = compareWithBaseline(baseline, currentMetrics);
 * detectAndAlertQualityDegradation(comparison, {}, { output: 'console' });
 * ```
 */
export declare function detectAndAlertQualityDegradation(comparison: BaselineComparisonResult, detectionOptions?: Parameters<typeof detectQualityDegradation>[1], alertOptions?: QualityAlertOptions): QualityDegradationDetection;
/**
 * Ground Truth 생성 옵션
 */
export interface GroundTruthGenerationOptions {
    /**
     * 시드 값 (재현성을 위해 사용, 기본값: 12345)
     */
    seed?: number;
    /**
     * 쿼리 목록 (기본값: ['React', 'TypeScript', 'database', 'MCP', 'optimization'])
     */
    queries?: string[];
    /**
     * 각 쿼리당 관련 결과 수 (기본값: 5)
     */
    relevantCountPerQuery?: number;
    /**
     * 관련 결과 선택 전략 (기본값: 'random')
     * - 'random': 랜덤 선택
     * - 'first': 처음 N개 선택
     * - 'pattern': 패턴 기반 선택 (i % 3 === 0 등)
     */
    selectionStrategy?: 'random' | 'first' | 'pattern';
}
/**
 * Ground Truth 자동 생성
 * 시드 기반으로 재현 가능한 Ground Truth 생성
 *
 * @param memoryIds 메모리 ID 배열
 * @param options 생성 옵션
 * @returns Ground Truth 배열
 *
 * @example
 * ```typescript
 * // 기본 옵션으로 생성
 * const groundTruths = generateGroundTruth(memoryIds);
 *
 * // 시드와 쿼리 지정
 * const groundTruths = generateGroundTruth(memoryIds, {
 *   seed: 12345,
 *   queries: ['React', 'TypeScript'],
 *   relevantCountPerQuery: 3
 * });
 * ```
 */
export declare function generateGroundTruth(memoryIds: string[], options?: GroundTruthGenerationOptions): GroundTruth[];
/**
 * Ground Truth 저장
 * JSON 파일로 Ground Truth를 저장합니다.
 *
 * @param groundTruths 저장할 Ground Truth 배열
 * @param filePath 저장할 파일 경로 (기본값: `data/vector-search-quality-ground-truth.json`)
 *
 * @example
 * ```typescript
 * const groundTruths = generateGroundTruth(memoryIds);
 * saveGroundTruth(groundTruths);
 * ```
 */
export declare function saveGroundTruth(groundTruths: GroundTruth[], filePath?: string): void;
/**
 * Ground Truth 로드
 * JSON 파일에서 Ground Truth를 로드합니다.
 *
 * @param filePath 로드할 파일 경로 (기본값: `data/vector-search-quality-ground-truth.json`)
 * @returns 로드된 Ground Truth 배열 또는 null (파일이 없거나 로드 실패 시)
 *
 * @example
 * ```typescript
 * const groundTruths = loadGroundTruth();
 * if (groundTruths) {
 *   console.log(`로드된 Ground Truth 수: ${groundTruths.length}`);
 * } else {
 *   console.log('Ground Truth 파일이 없습니다. 새로 생성합니다.');
 *   const newGroundTruths = generateGroundTruth(memoryIds);
 *   saveGroundTruth(newGroundTruths);
 * }
 * ```
 */
export declare function loadGroundTruth(filePath?: string): GroundTruth[] | null;
/**
 * Ground Truth 생성 또는 로드
 * 파일이 있으면 로드하고, 없으면 자동 생성하여 저장합니다.
 *
 * @param memoryIds 메모리 ID 배열
 * @param options 생성 옵션 (파일이 없을 때만 사용)
 * @param filePath Ground Truth 파일 경로 (기본값: `data/vector-search-quality-ground-truth.json`)
 * @returns Ground Truth 배열
 *
 * @example
 * ```typescript
 * // 파일이 있으면 로드, 없으면 생성
 * const groundTruths = generateOrLoadGroundTruth(memoryIds, {
 *   seed: 12345,
 *   queries: ['React', 'TypeScript']
 * });
 * ```
 */
export declare function generateOrLoadGroundTruth(memoryIds: string[], options?: GroundTruthGenerationOptions, filePath?: string): GroundTruth[];
/**
 * strict benchmark fixture에서 사람이 확정한 Ground Truth를 로드합니다.
 *
 * @param benchmarkDir benchmark fixture 디렉터리
 * @returns strict benchmark 검증을 통과한 Ground Truth 배열
 */
export declare function loadStrictBenchmarkGroundTruth(benchmarkDir?: string): GroundTruth[];
/**
 * 리포트 저장 옵션
 */
export interface ReportSaveOptions {
    /**
     * 저장할 파일 경로 (기본값: 리포트 타입에 따라 자동 생성)
     */
    filePath?: string;
    /**
     * 저장 형식 ('json' | 'markdown' | 'both')
     */
    format?: 'json' | 'markdown' | 'both';
    /**
     * 파일명에 타임스탬프 포함 여부 (기본값: true)
     */
    includeTimestamp?: boolean;
}
/**
 * 순서 보존 리포트 저장
 * 순서 보존 리포트를 JSON 또는 Markdown 형식으로 파일에 저장합니다.
 *
 * @param report 저장할 순서 보존 리포트
 * @param options 저장 옵션
 *
 * @example
 * ```typescript
 * const report = generateOrderPreservationReport(pair);
 * saveOrderPreservationReport(report, { format: 'markdown' });
 * ```
 */
export declare function saveOrderPreservationReport(report: OrderPreservationReport, options?: ReportSaveOptions): void;
/**
 * 품질 비교 리포트 저장
 * 품질 비교 리포트를 JSON 또는 Markdown 형식으로 파일에 저장합니다.
 *
 * @param report 저장할 품질 비교 리포트
 * @param options 저장 옵션
 *
 * @example
 * ```typescript
 * const report = generateQualityComparisonReport(comparison, groundTruth);
 * saveQualityComparisonReport(report, { format: 'markdown' });
 * ```
 */
export declare function saveQualityComparisonReport(report: QualityComparisonReport, options?: ReportSaveOptions): void;
/**
 * 극단적 시나리오 리포트 저장
 * 극단적 시나리오 리포트를 JSON 또는 Markdown 형식으로 파일에 저장합니다.
 *
 * @param report 저장할 극단적 시나리오 리포트
 * @param options 저장 옵션
 *
 * @example
 * ```typescript
 * const report = generateExtremeScenarioReport(lowVectorHigh, highVectorLow, w2Validation);
 * saveExtremeScenarioReport(report, { format: 'markdown' });
 * ```
 */
export declare function saveExtremeScenarioReport(report: ExtremeScenarioReport, options?: ReportSaveOptions): void;
/**
 * 통합 리포트 저장
 * 모든 리포트(순서 보존, 품질 비교, 극단적 시나리오)를 하나의 파일로 저장합니다.
 *
 * @param reports 저장할 리포트들
 * @param options 저장 옵션
 *
 * @example
 * ```typescript
 * const orderReport = generateOrderPreservationReport(pair);
 * const qualityReport = generateQualityComparisonReport(comparison, groundTruth);
 * const extremeReport = generateExtremeScenarioReport(lowVectorHigh, highVectorLow, w2Validation);
 * saveIntegratedReport({ orderReport, qualityReport, extremeReport }, { format: 'markdown' });
 * ```
 */
export interface IntegratedReports {
    orderReport?: OrderPreservationReport;
    qualityReport?: QualityComparisonReport;
    extremeReport?: ExtremeScenarioReport;
    baselineComparison?: BaselineComparisonResult;
    qualityDegradation?: QualityDegradationDetection;
}
export declare function saveIntegratedReport(reports: IntegratedReports, options?: ReportSaveOptions): void;
//# sourceMappingURL=vector-search-quality-metrics.d.ts.map