/**
 * Document-level RAG eval runner (P1.2).
 *
 * Ties the three already-existing layers together so a `.kern` RAG spec becomes
 * an executable, self-testing artifact:
 *   parse → `collectRagSemanticFacts` → run each `ragEval` against a REAL
 *   {@link EmbeddingRagIndex} retriever via the existing
 *   `evaluateRagEvalContract` seam.
 *
 * This is the dbt-test shape: retrieval + verification run in the KERN toolchain
 * (single implementation, one engine), not in emitted target code — so there is
 * no TS↔Python surface here. The corpus is supplied by the caller; on-disk
 * ingestion (`source uri=…` globs) lands in P1.5.
 */
import { type RagProviderEmbeddingOptions } from './rag-embed-resolver.js';
import { type AsyncEmbedder, type Embedder } from './rag-embedding.js';
import { type RagChunkInput, type RagEvalContractOptions, type RagEvalContractResult } from './rag-runtime.js';
import { type SemanticViolation } from './semantic-validator.js';
export interface RagEvalDocumentOptions extends RagEvalContractOptions {
    /** Embedder behind the retrieval seam. Defaults to the local semantic embedder. */
    readonly embedder?: Embedder;
    /** Reproducibility metadata for the corpus source feeding this eval. */
    readonly corpusSource?: RagEvalDocumentCorpusSource;
}
export interface RagEvalAsyncDocumentOptions extends Omit<RagEvalDocumentOptions, 'embedder'> {
    /** Optional explicit embedder override; otherwise resolved from retriever embed declarations. */
    readonly embedder?: AsyncEmbedder;
    /** Provider options. Supplying OpenAI here is the only path that can make network calls. */
    readonly providers?: RagProviderEmbeddingOptions;
}
export interface RagEvalDeclaredDocumentOptions extends Omit<RagEvalDocumentOptions, 'corpusSource'> {
    /** Path to the .kern file being evaluated; local source globs resolve relative to this file. */
    readonly sourcePath: string;
}
export interface RagEvalDeclaredAsyncDocumentOptions extends Omit<RagEvalAsyncDocumentOptions, 'corpusSource'> {
    /** Path to the .kern file being evaluated; local source globs resolve relative to this file. */
    readonly sourcePath: string;
}
export interface RagEvalDocumentEntry {
    readonly ragName: string;
    readonly evalName?: string;
    readonly result: RagEvalContractResult;
}
export interface RagEvalDocumentReport {
    /** Identity of the embedder used, recorded for reproducibility. */
    readonly embedderId: string;
    /** All embedder identities used by the evaluated pipelines. */
    readonly embedderIds?: readonly string[];
    /** Corpus source mode and provenance, recorded so eval reports are replayable/comparable. */
    readonly corpusSource: RagEvalDocumentCorpusSource;
    /** RAG semantic violations. Non-empty ⇒ the spec is invalid and no eval ran (fail-closed). */
    readonly diagnostics: readonly SemanticViolation[];
    readonly evals: readonly RagEvalDocumentEntry[];
    /** True only when the spec is valid, at least one eval ran, and every eval passed. */
    readonly passed: boolean;
}
export type RagEvalDocumentCorpusSourceMode = 'explicit-corpus-json' | 'declared-local-sources';
export interface RagEvalDocumentCorpusSource {
    readonly mode: RagEvalDocumentCorpusSourceMode;
    readonly sourcePath?: string;
    readonly rootDir?: string;
    readonly patterns?: readonly string[];
    readonly files?: readonly string[];
    readonly fileCount?: number;
    readonly chunkCount: number;
    readonly corpusSha256: string;
    readonly chunkIdVersion?: string;
    readonly chunkerVersion?: string;
    readonly chunkerVersions?: readonly string[];
}
/**
 * Parse `source`, build a cosine retriever over `chunks`, and execute every
 * `ragEval` contract declared in the document against it.
 *
 * Fails closed: if the RAG graph is semantically invalid (unresolved/duplicate
 * declarations, out-of-range params, …) no eval runs and `passed` is false —
 * running a contract against a broken spec would report a meaningless verdict.
 */
export declare function evaluateRagEvalDocument(source: string, chunks: Iterable<RagChunkInput>, options?: RagEvalDocumentOptions): RagEvalDocumentReport;
export declare function evaluateRagEvalDocumentAsync(source: string, chunks: Iterable<RagChunkInput>, options?: RagEvalAsyncDocumentOptions): Promise<RagEvalDocumentReport>;
export declare function evaluateRagEvalDocumentFromDeclaredSources(source: string, options: RagEvalDeclaredDocumentOptions): RagEvalDocumentReport;
export declare function evaluateRagEvalDocumentFromDeclaredSourcesAsync(source: string, options: RagEvalDeclaredAsyncDocumentOptions): Promise<RagEvalDocumentReport>;