@kernlang/core 3.5.9-canary.220.1.c398cd95 → 4.0.0

package/dist/rag-runtime.d.ts

@@ -0,0 +1,169 @@
+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 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' | 'invalid';
+export type RagAnswerContractDiagnosticCode = 'ANSWER_EMPTY' | '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 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 minGroundingCoverage?: number;
+}
+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 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 hashRetrievedChunkText(text: string): string;
+export declare function tokenizeForRetrieval(value: string): ReadonlySet<string>;