/**
 * pipeline/grader-comparison.ts
 *
 * Pure computation module for inter-grader comparison.
 *
 * Takes score data from multiple grader models (each having graded the same
 * set of responses) and produces a comparison matrix with correlations,
 * bias measurements, and per-area deltas between every grader pair.
 *
 * This module has NO side effects — no file I/O, no API calls.
 * It operates on pre-collected data only.
 *
 * @see docs/archive/exec-plans/grader-reliability.md — Phase 3
 */
import type { ComparisonReport, ScoreSummary } from "./types.js";
/** Per-dimension comparison between two graders */
export interface DimensionPairComparison {
    /** Systematic bias for this dimension */
    bias: number;
    /** Pearson correlation for this dimension */
    correlation: number;
    /** Number of paired observations */
    count: number;
    /** Mean absolute difference for this dimension */
    meanAbsDiff: number;
}
/** Full inter-grader comparison result */
export interface GraderComparison {
    /** The baseline grader model ID */
    baselineGrader: string;
    /** Candidate grader model IDs */
    candidateGraders: string[];
    /** When this comparison was generated */
    generatedAt: string;
    /** Pairwise comparisons between the baseline and each candidate */
    pairwise: GraderPairComparison[];
    /** Recommendation summary per candidate */
    recommendations: GraderRecommendation[];
    /** ScoreSummary-level comparison reports (reuses compare() primitive) */
    scoreSummaryComparisons?: ComparisonReport[];
}
/** Comparison between a pair of grader models */
export interface GraderPairComparison {
    /** Systematic bias: mean(B scores - A scores). Positive = B grades higher */
    bias: number;
    /** Pearson correlation between the two graders' scores */
    correlation: number;
    /** Grader A model ID */
    graderA: string;
    /** Grader B model ID */
    graderB: string;
    /** Mean absolute difference between scores */
    meanAbsDiff: number;
    /** Per-dimension comparisons (keyed by kebab-case dimension name) */
    perDimension: Record<string, DimensionPairComparison>;
}
/** Recommendation for a candidate grader */
export interface GraderRecommendation {
    /** Candidate grader model ID */
    modelId: string;
    /** Short explanation */
    reason: string;
    /** Human-readable recommendation */
    recommendation: "comparable" | "divergent" | "strongly-divergent";
}
/** Score data from a single grader model on one (task, dimension) judgment */
export interface GraderScore {
    /** Feature area (e.g., "groq") */
    area: string;
    /** Which scoring dimension (kebab-case, e.g. 'task-completion') */
    dimension: string;
    /** Score assigned by this grader (0–100) */
    score: number;
    /** Task ID (e.g., "groq-blog-queries") */
    taskId: string;
}
/** Score data from a single grader model across all judgments */
export interface GraderScoreSet {
    /** Grader model label (human-readable) */
    label: string;
    /** Grader model ID (e.g., "openai:gpt-5-2025-08-07") */
    modelId: string;
    /** All scores from this grader */
    scores: GraderScore[];
}
/**
 * Compare graders at the ScoreSummary level using the existing compare() primitive.
 *
 * This extends a basic GraderComparison with full ComparisonReport objects,
 * showing per-area and per-dimension deltas at the aggregate score level.
 *
 * @param comparison Basic grader comparison (from compareGraders)
 * @param baselineSummary ScoreSummary produced using the baseline grader
 * @param candidateSummaries ScoreSummaries produced using each candidate grader
 * @returns The comparison object augmented with scoreSummaryComparisons
 */
export declare function attachScoreSummaryComparisons(comparison: GraderComparison, baselineSummary: ScoreSummary, candidateSummaries: ScoreSummary[]): GraderComparison;
/**
 * Compare multiple grader models against a baseline grader.
 *
 * This is the main entry point — a pure function with no side effects.
 *
 * @param baseline Score data from the baseline grader
 * @param candidates Score data from candidate grader(s)
 * @returns GraderComparison with pairwise metrics and recommendations
 */
export declare function compareGraders(baseline: GraderScoreSet, candidates: GraderScoreSet[]): GraderComparison;
