import type { RagSemanticAnswerContractFact, RagSemanticEvalFact, RagSemanticMcpRetrievalFact } from './semantic-validator.js';
export interface RagCitation {
    readonly uri?: string;
    readonly locator?: string;
}
export interface RagChunkInput {
    readonly id: string;
    readonly text: string;
    readonly source: string;
    readonly citation?: RagCitation;
    readonly metadata?: Record<string, unknown>;
}
export interface RetrievedChunk {
    readonly id: string;
    readonly text: string;
    readonly score: number;
    readonly source: string;
    readonly citation: RagCitation;
    readonly metadata?: Record<string, unknown>;
}
export interface RetrieveOptions {
    readonly topK?: number;
    readonly minScore?: number;
}
export interface RetrieveResult {
    readonly query: string;
    readonly chunks: readonly RetrievedChunk[];
}
export type InMemoryRagRetriever = (query: string, options?: RetrieveOptions) => RetrieveResult;
export type RagContractRetriever = (query: string, options?: RetrieveOptions) => RetrieveResult;
export type AsyncRagContractRetriever = (query: string, options?: RetrieveOptions) => Promise<RetrieveResult>;
export declare const MAX_IN_MEMORY_RAG_TOP_K = 1000;
export type RagRuntimeProvenanceStatus = 'success' | 'retriever_error' | 'eval_failed';
export interface RagRuntimeProvenance {
    readonly runId: string;
    readonly retrieverName?: string;
    readonly targetKind?: 'retriever' | 'rag';
    readonly targetName?: string;
    readonly query: string;
    readonly retrieveOptions: RetrieveOptions;
    readonly citationsRequired: boolean;
    readonly startedAtMs: number;
    readonly durationMs: number;
    readonly chunkCount: number;
    readonly chunkHashes: readonly string[];
    readonly sources: readonly string[];
    readonly contractStatus: RagRuntimeProvenanceStatus;
}
export interface RagRuntimeProvenanceOptions {
    readonly runId?: string;
    readonly retrieverName?: string;
    readonly targetKind?: 'retriever' | 'rag';
    readonly targetName?: string;
    readonly retrieveOptions?: RetrieveOptions;
    readonly citationsRequired?: boolean;
    readonly startedAtMs?: number;
    readonly durationMs?: number;
    readonly contractStatus?: RagRuntimeProvenanceStatus;
}
export interface ProvenancedRetrieveResult extends RetrieveResult {
    readonly provenance: RagRuntimeProvenance;
}
export interface RagMcpRetrieveProvenanceMapping {
    readonly outputShape?: string;
    readonly outputItemShape?: string;
    readonly citationField?: string;
    readonly sourceField?: string;
    readonly scoreField?: string;
    readonly provenance?: string;
    readonly citationsRequired: boolean;
    readonly contractStatus: RagSemanticMcpRetrievalFact['contractStatus'];
    readonly compatible: boolean;
}
export type RagAnswerContractStatus = 'grounded' | 'partially_grounded' | 'ungrounded' | 'abstained' | 'invalid';
export type RagAnswerContractDiagnosticCode = 'ANSWER_EMPTY' | 'ABSTAIN_ANSWER_MISMATCH' | 'ABSTAIN_EVIDENCE_POLICY_REQUIRED' | 'ABSTAIN_NOT_ALLOWED' | 'ABSTAIN_WITH_SUFFICIENT_EVIDENCE' | 'CITED_CHUNKS_BELOW_MINIMUM' | 'EVIDENCE_INSUFFICIENT' | 'QUERY_MISMATCH' | 'RETRIEVER_ERROR' | 'PROVENANCE_MISMATCH' | 'SPAN_INVALID' | 'SPAN_UNGROUNDED' | 'CHUNK_REF_UNKNOWN' | 'CITATION_REQUIRED' | 'GROUNDING_BELOW_THRESHOLD';
export interface RagAnswerGroundingSpan {
    readonly start: number;
    readonly end: number;
    readonly chunkIds: readonly string[];
    readonly required?: boolean;
}
export interface RagAnswerEvidencePolicy {
    readonly minRetrievedChunks?: number;
    readonly minTopScore?: number;
}
export interface RagAnswerContract {
    readonly id?: string;
    readonly ragName?: string;
    readonly prompt?: string;
    readonly query: string;
    readonly answer: string;
    readonly retrieval: RetrieveResult | ProvenancedRetrieveResult;
    readonly provenance?: RagRuntimeProvenance;
    readonly groundingSpans?: readonly RagAnswerGroundingSpan[];
    readonly requireCitations?: boolean;
    readonly minCitedChunks?: number;
    readonly minGroundingCoverage?: number;
    readonly evidencePolicy?: RagAnswerEvidencePolicy;
    readonly abstained?: boolean;
    readonly allowAbstain?: boolean;
    readonly abstainAnswer?: string;
}
export interface RagAnswerContractDiagnostic {
    readonly code: RagAnswerContractDiagnosticCode;
    readonly message: string;
    readonly spanIndex?: number;
    readonly chunkId?: string;
}
export interface RagAnswerContractResult {
    readonly id?: string;
    readonly ragName?: string;
    readonly query: string;
    readonly passed: boolean;
    readonly status: RagAnswerContractStatus;
    readonly groundingCoverage: number;
    readonly groundedChars: number;
    readonly answerChars: number;
    readonly evidenceSufficient: boolean;
    readonly abstained: boolean;
    readonly citedChunkIds: readonly string[];
    readonly sources: readonly string[];
    readonly provenance?: RagRuntimeProvenance;
    readonly diagnostics: readonly RagAnswerContractDiagnostic[];
}
export type RagEvalAssertionCode = 'PASS' | 'ASSERTION_FAIL' | 'INVALID_ASSERTION' | 'RETRIEVER_ERROR' | 'UNSUPPORTED_ASSERTION';
export interface RagEvalContractOptions {
    readonly sourceGlobCaseSensitive?: boolean;
    readonly now?: () => number;
}
export interface RagEvalAssertionResult {
    readonly kind: string;
    readonly required?: boolean;
    readonly passed: boolean;
    readonly code: RagEvalAssertionCode;
    readonly message: string;
    readonly expected?: unknown;
    readonly actual?: unknown;
}
export interface RagEvalCaseResult {
    readonly name: string;
    readonly query: string;
    readonly passed: boolean;
    readonly durationMs: number;
    readonly retrieveOptions: RetrieveOptions;
    readonly chunks: readonly RetrievedChunk[];
    readonly assertions: readonly RagEvalAssertionResult[];
}
export interface RagEvalContractResult {
    readonly passed: boolean;
    readonly ragName?: string;
    readonly evalName?: string;
    readonly caseCount: number;
    readonly passedCaseCount: number;
    readonly assertionCount: number;
    readonly passedAssertionCount: number;
    readonly durationMs: number;
    readonly cases: readonly RagEvalCaseResult[];
}
export interface RagSemanticAnswerContractOptions {
    readonly provenance?: RagRuntimeProvenance;
}
export declare class InMemoryRagCorpus {
    private readonly chunks;
    constructor(chunks?: Iterable<RagChunkInput>);
    get size(): number;
    add(chunk: RagChunkInput): void;
    get(id: string): RagChunkInput | undefined;
    all(): RagChunkInput[];
    retrieve(query: string, options?: RetrieveOptions): RetrieveResult;
}
export declare function createInMemoryRetriever(corpus: InMemoryRagCorpus): InMemoryRagRetriever;
export declare function retrieveFromInMemoryCorpus(corpus: InMemoryRagCorpus, query: string, options?: RetrieveOptions): RetrieveResult;
export declare function createRagRuntimeProvenance(result: RetrieveResult, options?: RagRuntimeProvenanceOptions): RagRuntimeProvenance;
export declare function withRagRuntimeProvenance(result: RetrieveResult, options?: RagRuntimeProvenanceOptions): ProvenancedRetrieveResult;
export declare function ragMcpRetrieveProvenanceMapping(retrieval: RagSemanticMcpRetrievalFact | null | undefined): RagMcpRetrieveProvenanceMapping;
export declare function evaluateRagAnswerContract(contract: RagAnswerContract): RagAnswerContractResult;
export declare function ragAnswerContractFromSemanticFact(fact: RagSemanticAnswerContractFact, retrieval: RetrieveResult | ProvenancedRetrieveResult, options?: RagSemanticAnswerContractOptions): RagAnswerContract;
export declare function evaluateRagSemanticAnswerContract(fact: RagSemanticAnswerContractFact, retrieval: RetrieveResult | ProvenancedRetrieveResult, options?: RagSemanticAnswerContractOptions): RagAnswerContractResult;
export declare function evaluateRagEvalContract(evaluation: RagSemanticEvalFact, retriever: RagContractRetriever, options?: RagEvalContractOptions): RagEvalContractResult;
export declare function evaluateRagEvalContractAsync(evaluation: RagSemanticEvalFact, retriever: AsyncRagContractRetriever, options?: RagEvalContractOptions): Promise<RagEvalContractResult>;
export declare function hashRetrievedChunkText(text: string): string;
export declare function tokenizeForRetrieval(value: string): ReadonlySet<string>;