import { KnowledgeGraph } from '../../contracts/graph.js';
import { type CorpusBaselineSource } from './corpus.js';
import { type BenchmarkQuestionSpec } from './questions.js';
import { type PromptRunnerUsage } from '../prompt-runner.js';
import { type BenchmarkPromptArtifacts, type BenchmarkPromptExecution, type BenchmarkPromptRunnerResult, type BenchmarkPromptTokenSource } from './runner.js';
export interface GoldQuestion {
    question: string;
    expected_labels: string[];
}
export type QualityQuestionInput = GoldQuestion | BenchmarkQuestionSpec;
export interface QualityResult {
    question: string;
    bucket: string;
    expected_labels: string[];
    returned_labels: string[];
    matched_labels: string[];
    missing_labels: string[];
    precision: number;
    recall: number;
    reciprocal_rank: number;
    snippet_coverage: number;
    grounded_match_rate: number;
    tokens_used: number;
    total_tokens: number | null;
    prompt_tokens_estimated: number | null;
    prompt_token_source: BenchmarkPromptTokenSource | null;
    usage: PromptRunnerUsage | null;
    answer_text: string | null;
    elapsed_ms: number | null;
    artifacts: BenchmarkPromptArtifacts | null;
}
export interface QualityBucketSummary {
    bucket: string;
    questions: number;
    avg_recall: number;
    mrr: number;
    avg_snippet_coverage: number;
    avg_grounded_match_rate: number;
}
export interface QualityReport {
    questions: QualityResult[];
    skipped_questions: number;
    avg_precision: number;
    avg_recall: number;
    mrr: number;
    avg_snippet_coverage: number;
    avg_grounded_match_rate: number;
    questions_with_hits: number;
    total_questions: number;
    avg_tokens_used: number;
    avg_total_tokens: number | null;
    corpus_tokens: number;
    corpus_source: CorpusBaselineSource;
    compression_ratio: number;
    bucket_summaries: QualityBucketSummary[];
}
export interface QualityOptions {
    graphPath?: string;
    corpusWords?: number | null;
    execTemplate?: string;
    outputDir?: string;
    now?: Date;
    runner?: (execution: BenchmarkPromptExecution) => Promise<BenchmarkPromptRunnerResult>;
}
/**
 * Gold-standard questions for madar itself.
 * Each expected_labels entry is compared after the same normalization used by
 * benchmark matching (lowercase, non-alphanumeric stripped).
 */
export declare const GOLD_QUESTIONS: GoldQuestion[];
export declare function evaluateRetrievalQuality(graph: KnowledgeGraph, questions: ReadonlyArray<QualityQuestionInput> | undefined, budget: number | undefined, options: QualityOptions & {
    execTemplate: string;
}): Promise<QualityReport>;
export declare function evaluateRetrievalQuality(graph: KnowledgeGraph, questions?: ReadonlyArray<QualityQuestionInput>, budget?: number, options?: QualityOptions): QualityReport;
export declare function formatQualityReport(report: QualityReport): string;