/**
 * Helpers for creating, validating, and comparing human-gold datasets.
 */
import type { Report, ReportHumanAgreement } from '../types/index.js';
import { type GoldDataset } from './gold-dataset.js';
import { type AgreementResult } from './human-gold.js';
export interface GoldCompareInput {
    report: Report;
    gold: GoldDataset;
    /** Variant to compare against gold. Default: first variant in report.meta.variants. */
    variant?: string;
    /** Bootstrap parameters. */
    samples?: number;
    seed?: number;
}
export interface GoldCompareResult {
    agreement: AgreementResult;
    /** Sample-level comparison rows for the renderer / per-row UI. */
    rows: Array<{
        sample_id: string;
        goldScore: number;
        judgeScore: number;
        diff: number;
    }>;
    /** Sample IDs in the gold set that were missing from the report. */
    missing: string[];
    /** Sample IDs in the gold set whose judge score was missing/non-numeric. */
    unscored: string[];
    /** Contamination warning string if annotator id matches any judge model id. */
    contaminationWarning?: string;
    /** Variant actually used. */
    variant: string;
}
/**
 * Compute agreement between gold annotations and the LLM judge's scores from
 * a finished report.
 *
 * Pure function — does not touch fs or stdout. The CLI handler wraps it.
 */
export declare function compareGoldToReport(input: GoldCompareInput): GoldCompareResult;
/**
 * Format the comparison result as a human-readable terminal report.
 */
export declare function formatGoldCompare(result: GoldCompareResult, gold: GoldDataset): string;
/**
 * Generate a starter dataset directory with a metadata.yaml and an
 * annotations.yaml stub. Errors out if the directory already has yaml files
 * (refuses to clobber).
 */
export declare function initGoldDataset(targetDir: string, options?: {
    annotator?: string;
}): string[];
/**
 * Convert an in-memory comparison result into the persisted ReportMeta shape.
 */
export declare function toPersistedAgreement(result: GoldCompareResult, gold: GoldDataset): ReportHumanAgreement;
/**
 * Side-effecting helper for `omk eval --gold-dir`: load gold, compute
 * agreement, mutate report.meta.humanAgreement, re-persist the report file,
 * print the human-readable comparison to stderr.
 *
 * Returns the comparison result so the CLI can also surface contamination
 * warnings programmatically.
 */
export declare function attachGoldAgreementToReport(input: {
    report: Report;
    goldDir: string;
    outputDir: string;
    samples?: number;
    seed?: number;
    variant?: string;
}): {
    result?: GoldCompareResult;
    gold?: GoldDataset;
    loadIssues: string[];
};
/**
 * Validate-only entry point. Returns issues; CLI exits non-zero if any.
 */
export declare function validateGoldDataset(dir: string): {
    ok: boolean;
    issues: string[];
    sampleCount: number;
};