memento-mcp-server 1.15.0 → 1.16.0-a

package/dist/test/helpers/vector-search-quality-metrics.d.ts

@@ -0,0 +1,1287 @@
+/**
+ * 벡터 검색 품질 검증 헬퍼
+ * 벡터 검색 결과 순서 보존 검증 및 품질 지표 비교
+ * Consolidation 점수 반영 전/후 비교를 위한 지표 계산
+ */
+import type { SearchResult, GroundTruth } from './search-quality-metrics.js';
+import type { HybridSearchResult } from '../../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 반영 후 품질 지표
+     */
+    consolidation: 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[];
+/**
+ * 리포트 저장 옵션
+ */
+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