@aid-framework/runtime 0.0.0 → 0.1.39

package/dist/retrieval/gate.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Running the retrieval gate through the shipped statistical gate.
+ *
+ * No gate logic lives here. {@link RetrievalGate} samples a retriever over retrieval
+ * cases, turns each per-run mean into a real {@link MetricRun}, and hands a real
+ * {@link EvalRun} to the real {@link BaselineGate}. That matters for the falsification
+ * test, which must show the *shipped* gate rejecting a worse retriever; a comparator
+ * written for the occasion would prove only that the comparator works.
+ *
+ * Two deliberate details:
+ *
+ * **The metrics hand-off needs a cast.** `BaselineGate` annotates `metrics` as
+ * `Metric[]`, and the shipped `Metric` requires `score(entry: EvalCase, prediction:
+ * string)`, which a retrieval metric cannot implement. What the gate actually consumes
+ * from that argument is only `name` and `deterministic` -- that is the entirety of
+ * `checkMetricEligibility` -- so a cast is sound here, and is confined to one line
+ * with this comment rather than spread through the runtime. The eligibility check it
+ * feeds is real: a retrieval metric reporting `deterministic = false` is refused,
+ * which a test asserts.
+ *
+ * **`allowNondeterministic` is not exposed.** The shipped gate has the flag for local
+ * exploration, and wiring it through would make it reachable from a gate. There is no
+ * retrieval metric in Phase 1 that is non-deterministic; if one ever appears, the
+ * metric is what needs fixing.
+ *
+ * `runs` is a required argument rather than a default, because it is not a tuning
+ * knob: at `runs = 1` the run-to-run standard deviation is zero and the statistical
+ * half of the gate cannot fire at all, so a gate built on one run silently degrades to
+ * a mean comparison.
+ */
+import { type EvalBaseline, EvalRun, type GateResult, type Threshold } from '../evals/gate.js';
+import type { RetrievalCase, RetrievalMetric } from './metrics.js';
+import type { Retriever } from './retriever.js';
+/** Samples a retriever and decides whether its retrieval regressed. */
+export declare class RetrievalGate {
+    private readonly _metrics;
+    private readonly _gate;
+    constructor(thresholds: readonly Threshold[], options?: {
+        readonly metrics?: readonly RetrievalMetric[];
+    });
+    get thresholds(): readonly Threshold[];
+    get metrics(): readonly RetrievalMetric[];
+    /** Run every case `runs` times, producing one mean per metric per run. */
+    sample(cases: readonly RetrievalCase[], retriever: Retriever, init: {
+        readonly runs: number;
+        readonly dataset: string;
+        readonly datasetVersion: string;
+    }): Promise<EvalRun>;
+    /** Delegate to the shipped gate; there is no verdict logic in this module. */
+    evaluate(run: EvalRun, baseline: EvalBaseline): GateResult;
+}
+//# sourceMappingURL=gate.d.ts.map

package/dist/retrieval/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/retrieval/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,OAAO,EAEL,KAAK,YAAY,EACjB,OAAO,EACP,KAAK,UAAU,EAEf,KAAK,SAAS,EACf,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,uEAAuE;AACvE,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IAErC,YACE,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,OAAO,GAAE;QAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,eAAe,EAAE,CAAA;KAAO,EAQhE;IAED,IAAI,UAAU,IAAI,SAAS,SAAS,EAAE,CAErC;IAED,IAAI,OAAO,IAAI,SAAS,eAAe,EAAE,CAExC;IAED,0EAA0E;IACpE,MAAM,CACV,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;KAAE,GACzF,OAAO,CAAC,OAAO,CAAC,CAsClB;IAED,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,GAAG,UAAU,CAEzD;CACF"}

package/dist/retrieval/gate.js

@@ -0,0 +1,91 @@
+/**
+ * Running the retrieval gate through the shipped statistical gate.
+ *
+ * No gate logic lives here. {@link RetrievalGate} samples a retriever over retrieval
+ * cases, turns each per-run mean into a real {@link MetricRun}, and hands a real
+ * {@link EvalRun} to the real {@link BaselineGate}. That matters for the falsification
+ * test, which must show the *shipped* gate rejecting a worse retriever; a comparator
+ * written for the occasion would prove only that the comparator works.
+ *
+ * Two deliberate details:
+ *
+ * **The metrics hand-off needs a cast.** `BaselineGate` annotates `metrics` as
+ * `Metric[]`, and the shipped `Metric` requires `score(entry: EvalCase, prediction:
+ * string)`, which a retrieval metric cannot implement. What the gate actually consumes
+ * from that argument is only `name` and `deterministic` -- that is the entirety of
+ * `checkMetricEligibility` -- so a cast is sound here, and is confined to one line
+ * with this comment rather than spread through the runtime. The eligibility check it
+ * feeds is real: a retrieval metric reporting `deterministic = false` is refused,
+ * which a test asserts.
+ *
+ * **`allowNondeterministic` is not exposed.** The shipped gate has the flag for local
+ * exploration, and wiring it through would make it reachable from a gate. There is no
+ * retrieval metric in Phase 1 that is non-deterministic; if one ever appears, the
+ * metric is what needs fixing.
+ *
+ * `runs` is a required argument rather than a default, because it is not a tuning
+ * knob: at `runs = 1` the run-to-run standard deviation is zero and the statistical
+ * half of the gate cannot fire at all, so a gate built on one run silently degrades to
+ * a mean comparison.
+ */
+// biome-ignore lint/suspicious/noShadowRestrictedNames: the framework's own error name, matching the Python runtime's public surface
+import { EvalError } from '../errors.js';
+import { BaselineGate, EvalRun, MetricRun, } from '../evals/gate.js';
+/** Samples a retriever and decides whether its retrieval regressed. */
+export class RetrievalGate {
+    _metrics;
+    _gate;
+    constructor(thresholds, options = {}) {
+        this._metrics = [...(options.metrics ?? [])];
+        // See the module docstring: the gate reads only `name` and `deterministic` from
+        // these, which is the part of the protocol a retrieval metric shares.
+        this._gate = new BaselineGate(thresholds, {
+            metrics: this._metrics,
+        });
+    }
+    get thresholds() {
+        return this._gate.thresholds;
+    }
+    get metrics() {
+        return this._metrics;
+    }
+    /** Run every case `runs` times, producing one mean per metric per run. */
+    async sample(cases, retriever, init) {
+        if (cases.length === 0) {
+            throw new EvalError('a retrieval run needs at least one case');
+        }
+        if (init.runs < 1) {
+            throw new EvalError(`a retrieval run needs at least one run, got ${init.runs}`);
+        }
+        if (this._metrics.length === 0) {
+            throw new EvalError('a retrieval run needs at least one metric');
+        }
+        const samples = new Map(this._metrics.map((metric) => [metric.name, []]));
+        for (let run = 0; run < init.runs; run += 1) {
+            const totals = new Map(this._metrics.map((metric) => [metric.name, 0.0]));
+            for (const entry of cases) {
+                // k comes from the case, because a case is what says how many passages count
+                // as an answer; a retriever's own topK is a default.
+                const retrieved = await retriever.retrieve(entry.query, { topK: entry.k });
+                for (const metric of this._metrics) {
+                    const result = await metric.score(entry, retrieved);
+                    totals.set(metric.name, (totals.get(metric.name) ?? 0.0) + result.score);
+                }
+            }
+            for (const [name, total] of totals) {
+                samples.get(name)?.push(total / cases.length);
+            }
+        }
+        return new EvalRun({
+            dataset: init.dataset,
+            datasetVersion: init.datasetVersion,
+            runs: init.runs,
+            metrics: [...samples.entries()].map(([name, values]) => new MetricRun({ metric: name, values })),
+        });
+    }
+    /** Delegate to the shipped gate; there is no verdict logic in this module. */
+    evaluate(run, baseline) {
+        return this._gate.evaluate(run, baseline);
+    }
+}
+//# sourceMappingURL=gate.js.map

package/dist/retrieval/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../src/retrieval/gate.ts"],"names":[],"mappings":"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"}

package/dist/retrieval/hybrid.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Lexical scoring and rank fusion.
+ *
+ * Vector similarity cannot carry retrieval on its own, and the reason is not
+ * aesthetic: cosine similarity is dominated by embedding geometry while exact terms
+ * -- an identifier, an error code, a flag name -- are what a developer actually
+ * greps for. So a retriever fuses a vector ranking with a lexical one.
+ *
+ * The lexical half is BM25, implemented here rather than delegated to a search engine
+ * so that the same scoring applies to both store adapters and to a store that has no
+ * database behind it.
+ *
+ * The fusion is Reciprocal Rank Fusion, and it fuses *ranks* rather than scores. That
+ * is the whole reason to pick it: BM25 scores and cosine similarities are unbounded
+ * and on incomparable scales, so any weighted score sum would need a per-corpus
+ * normalisation constant that nobody can justify. Ranks are already comparable, and
+ * RRF's `1 / (k + rank)` says something defensible -- being ranked highly by either
+ * retriever is evidence, being ranked highly by both is stronger evidence.
+ *
+ * Everything here is a pure function of its inputs, so retrieval order is
+ * reproducible and a re-ingested corpus ranks identically.
+ */
+/** A ranked chunk id and the score that ranked it. */
+export declare class RankedId {
+    readonly chunkId: string;
+    readonly score: number;
+    constructor(init: {
+        readonly chunkId: string;
+        readonly score: number;
+    });
+}
+/**
+ * Lowercase alphanumeric runs.
+ *
+ * No stemming and no stop-word list: both are language-specific, and a retrieval
+ * runtime that silently mangles identifiers by stemming them is worse at its actual
+ * job than one that keeps the tokens it was given.
+ */
+export declare function tokenize(text: string): readonly string[];
+/**
+ * BM25 score of every document for `query`, in the order given.
+ *
+ * Saturated term frequency (a term repeated ten times is not ten times as
+ * informative) and length normalisation (a long chunk should not win merely by
+ * containing more words) -- those two properties are the reason to use BM25 rather
+ * than a raw term count.
+ */
+export declare function bm25Scores(documents: readonly string[], query: string, options?: {
+    readonly k1?: number;
+    readonly b?: number;
+}): readonly number[];
+/**
+ * The `topK` documents with a non-zero lexical score, best first.
+ *
+ * Ties break on chunk id so that equal-scoring matches rank identically on every run
+ * and in both store adapters.
+ */
+export declare function lexicalRanking(documents: readonly string[], ids: readonly string[], query: string, options: {
+    readonly topK: number;
+}): readonly RankedId[];
+/** The reciprocal-rank contribution of a 1-based `rank`. */
+export declare function rrfScore(rank: number, options?: {
+    readonly k?: number;
+}): number;
+/**
+ * Reciprocal Rank Fusion of rank-ordered id lists.
+ *
+ * Each ranking contributes `1 / (k + rank)` per id; an id absent from a ranking
+ * contributes nothing from it. An id that appears in several rankings therefore
+ * outranks one that is top of a single ranking, which is the behaviour that makes
+ * fusion worth doing.
+ */
+export declare function fuse(rankings: readonly (readonly string[])[], options?: {
+    readonly k?: number;
+}): readonly RankedId[];
+//# sourceMappingURL=hybrid.d.ts.map

package/dist/retrieval/hybrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid.d.ts","sourceRoot":"","sources":["../../src/retrieval/hybrid.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAmBH,sDAAsD;AACtD,qBAAa,QAAQ;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,YAAY,IAAI,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAMrE;CACF;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAExD;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1D,SAAS,MAAM,EAAE,CAwCnB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,GAAG,EAAE,SAAS,MAAM,EAAE,EACtB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjC,SAAS,QAAQ,EAAE,CAgBrB;AAED,4DAA4D;AAC5D,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,CAKpF;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAClB,QAAQ,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,EACxC,OAAO,GAAE;IAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAA;CAAO,GACpC,SAAS,QAAQ,EAAE,CAarB"}

package/dist/retrieval/hybrid.js

@@ -0,0 +1,150 @@
+/**
+ * Lexical scoring and rank fusion.
+ *
+ * Vector similarity cannot carry retrieval on its own, and the reason is not
+ * aesthetic: cosine similarity is dominated by embedding geometry while exact terms
+ * -- an identifier, an error code, a flag name -- are what a developer actually
+ * greps for. So a retriever fuses a vector ranking with a lexical one.
+ *
+ * The lexical half is BM25, implemented here rather than delegated to a search engine
+ * so that the same scoring applies to both store adapters and to a store that has no
+ * database behind it.
+ *
+ * The fusion is Reciprocal Rank Fusion, and it fuses *ranks* rather than scores. That
+ * is the whole reason to pick it: BM25 scores and cosine similarities are unbounded
+ * and on incomparable scales, so any weighted score sum would need a per-corpus
+ * normalisation constant that nobody can justify. Ranks are already comparable, and
+ * RRF's `1 / (k + rank)` says something defensible -- being ranked highly by either
+ * retriever is evidence, being ranked highly by both is stronger evidence.
+ *
+ * Everything here is a pure function of its inputs, so retrieval order is
+ * reproducible and a re-ingested corpus ranks identically.
+ */
+/**
+ * The RRF constant from the original formulation: it damps the influence of the very
+ * top ranks so one retriever's confident first hit cannot alone decide the fused
+ * order.
+ */
+const RRF_K = 60;
+/**
+ * BM25 saturation and length-normalisation. The usual defaults, and defaults are the
+ * right call here: they are tuned against judged-relevance corpora, and this runtime
+ * has no such corpus to tune against.
+ */
+const BM25_K1 = 1.5;
+const BM25_B = 0.75;
+const TOKEN = /[a-z0-9]+/g;
+/** A ranked chunk id and the score that ranked it. */
+export class RankedId {
+    chunkId;
+    score;
+    constructor(init) {
+        if (init.chunkId.length === 0) {
+            throw new RangeError('chunkId must not be empty');
+        }
+        this.chunkId = init.chunkId;
+        this.score = init.score;
+    }
+}
+/**
+ * Lowercase alphanumeric runs.
+ *
+ * No stemming and no stop-word list: both are language-specific, and a retrieval
+ * runtime that silently mangles identifiers by stemming them is worse at its actual
+ * job than one that keeps the tokens it was given.
+ */
+export function tokenize(text) {
+    return text.toLowerCase().match(TOKEN) ?? [];
+}
+/**
+ * BM25 score of every document for `query`, in the order given.
+ *
+ * Saturated term frequency (a term repeated ten times is not ten times as
+ * informative) and length normalisation (a long chunk should not win merely by
+ * containing more words) -- those two properties are the reason to use BM25 rather
+ * than a raw term count.
+ */
+export function bm25Scores(documents, query, options = {}) {
+    const k1 = options.k1 ?? BM25_K1;
+    const b = options.b ?? BM25_B;
+    const tokenised = documents.map((document) => tokenize(document));
+    const terms = tokenize(query);
+    if (tokenised.length === 0 || terms.length === 0) {
+        return documents.map(() => 0.0);
+    }
+    const total = tokenised.length;
+    const lengths = tokenised.map((tokens) => tokens.length);
+    const averageLength = lengths.reduce((sum, length) => sum + length, 0) / total;
+    const counts = tokenised.map((tokens) => {
+        const frequencies = new Map();
+        for (const token of tokens) {
+            frequencies.set(token, (frequencies.get(token) ?? 0) + 1);
+        }
+        return frequencies;
+    });
+    const scores = [];
+    for (const [index, frequencies] of counts.entries()) {
+        const length = lengths[index] ?? 0;
+        let score = 0.0;
+        for (const term of terms) {
+            const frequency = frequencies.get(term) ?? 0;
+            if (frequency === 0)
+                continue;
+            const documentFrequency = counts.reduce((count, other) => (other.has(term) ? count + 1 : count), 0);
+            const inverseFrequency = Math.log(1.0 + (total - documentFrequency + 0.5) / (documentFrequency + 0.5));
+            const norm = averageLength > 0 ? 1.0 - b + b * (length / averageLength) : 1.0;
+            score += (inverseFrequency * (frequency * (k1 + 1.0))) / (frequency + k1 * norm);
+        }
+        scores.push(score);
+    }
+    return scores;
+}
+/**
+ * The `topK` documents with a non-zero lexical score, best first.
+ *
+ * Ties break on chunk id so that equal-scoring matches rank identically on every run
+ * and in both store adapters.
+ */
+export function lexicalRanking(documents, ids, query, options) {
+    if (documents.length !== ids.length) {
+        throw new RangeError('documents and ids must be parallel sequences');
+    }
+    const scores = bm25Scores(documents, query);
+    const scored = [];
+    for (const [index, chunkId] of ids.entries()) {
+        const score = scores[index] ?? 0.0;
+        if (score > 0.0) {
+            scored.push(new RankedId({ chunkId, score }));
+        }
+    }
+    scored.sort((left, right) => left.score !== right.score ? right.score - left.score : left.chunkId < right.chunkId ? -1 : 1);
+    return scored.slice(0, options.topK);
+}
+/** The reciprocal-rank contribution of a 1-based `rank`. */
+export function rrfScore(rank, options = {}) {
+    if (rank < 1) {
+        throw new RangeError('rank is 1-based');
+    }
+    return 1.0 / ((options.k ?? RRF_K) + rank);
+}
+/**
+ * Reciprocal Rank Fusion of rank-ordered id lists.
+ *
+ * Each ranking contributes `1 / (k + rank)` per id; an id absent from a ranking
+ * contributes nothing from it. An id that appears in several rankings therefore
+ * outranks one that is top of a single ranking, which is the behaviour that makes
+ * fusion worth doing.
+ */
+export function fuse(rankings, options = {}) {
+    const k = options.k ?? RRF_K;
+    const totals = new Map();
+    for (const ranking of rankings) {
+        for (const [offset, chunkId] of ranking.entries()) {
+            totals.set(chunkId, (totals.get(chunkId) ?? 0.0) + rrfScore(offset + 1, { k }));
+        }
+    }
+    const fused = [...totals.entries()].map(([chunkId, score]) => new RankedId({ chunkId, score }));
+    fused.sort((left, right) => left.score !== right.score ? right.score - left.score : left.chunkId < right.chunkId ? -1 : 1);
+    return fused;
+}
+//# sourceMappingURL=hybrid.js.map

package/dist/retrieval/hybrid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid.js","sourceRoot":"","sources":["../../src/retrieval/hybrid.ts"],"names":[],"mappings":"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"}

package/dist/retrieval/metrics.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Metrics over a retrieved set.
+ *
+ * The shipped `Metric` scores `(case, prediction: string)`. That signature cannot
+ * express these metrics: recall@k and MRR score a *ranked set of passages with
+ * provenance*, and a citation-grounding score has to look at where each passage came
+ * from. Encoding a retrieved set into one string would make every metric re-parse it,
+ * and the parse would become the thing under test.
+ *
+ * So the retrieval metrics get their own protocol here rather than widening the
+ * shipped one. Widening `Metric` would change the meaning of an interface the eval
+ * gate already threshold-checks, and would do so for every existing implementation.
+ * The new protocol is additive and reuses {@link MetricResult}.
+ *
+ * The two protocols share the part the gate actually consumes -- `name` and
+ * `deterministic` -- which is what lets retrieval metrics be handed to the shipped
+ * gate's `metrics` option. See `retrieval/gate.ts` for why that hand-off needs a cast
+ * and why the cast is sound.
+ *
+ * `deterministic` is `true` for all three, and that is a claim the gate enforces:
+ * none of these metrics calls a model, and every tie is broken by chunk id, so the
+ * same retrieved set always scores the same.
+ */
+import { MetricResult } from '../evals/metrics.js';
+import type { RetrievalResult } from './citations.js';
+import type { RetrievalMetricSpec } from './types.js';
+/**
+ * One retrieval question and the documents that should answer it.
+ *
+ * This mirrors the IR's `retrieval` metric node field for field, and it exists
+ * because `EvalCase` carries `metadata: Record<string, string>` -- a string map,
+ * which cannot hold `expectDocs` without inventing an encoding. The expected
+ * documents, and `k`, are what a retrieval metric needs, so they are typed here
+ * instead of smuggled through a string.
+ */
+export declare class RetrievalCase {
+    readonly id: string;
+    readonly query: string;
+    readonly expectDocs: readonly string[];
+    readonly k: number;
+    constructor(init: {
+        readonly id: string;
+        readonly query: string;
+        readonly expectDocs: readonly string[];
+        readonly k: number;
+    });
+    /** Build a case from the IR's `{kind, expectDocs, k}` node. */
+    static fromSpec(init: {
+        readonly caseId: string;
+        readonly query: string;
+        readonly spec: RetrievalMetricSpec;
+    }): RetrievalCase;
+}
+/**
+ * Scores a ranked, cited retrieved set.
+ *
+ * `name` and `deterministic` are part of the contract because the shipped gate reads
+ * exactly those two properties when it checks that a thresholded metric is allowed to
+ * gate CI.
+ */
+export interface RetrievalMetric {
+    readonly name: string;
+    readonly deterministic: boolean;
+    score(entry: RetrievalCase, retrieved: RetrievalResult): Promise<MetricResult>;
+}
+/**
+ * Fraction of expected documents present in the top `k`.
+ *
+ * Duplicated passages do not inflate the score: {@link RetrievalResult.docIds} is
+ * de-duplicated, so a document that contributed three passages counts once. Recall is
+ * about which documents were found.
+ */
+export declare class RecallAtK implements RetrievalMetric {
+    private readonly _name;
+    private readonly _minScore;
+    constructor(options?: {
+        readonly name?: string;
+        readonly minScore?: number;
+    });
+    get name(): string;
+    get deterministic(): boolean;
+    score(entry: RetrievalCase, retrieved: RetrievalResult): Promise<MetricResult>;
+}
+/**
+ * Reciprocal rank of the first expected document, averaged over cases.
+ *
+ * Scored per case, so the "mean" is taken by the gate across cases and runs. One
+ * number per case keeps the metric a drop-in for the gate's per-case arithmetic.
+ */
+export declare class MeanReciprocalRank implements RetrievalMetric {
+    private readonly _name;
+    private readonly _minScore;
+    constructor(options?: {
+        readonly name?: string;
+        readonly minScore?: number;
+    });
+    get name(): string;
+    get deterministic(): boolean;
+    score(entry: RetrievalCase, retrieved: RetrievalResult): Promise<MetricResult>;
+}
+/**
+ * Fraction of expected documents that a returned item cites *correctly*.
+ *
+ * Distinct from recall because it scores citations rather than document ids, and
+ * because it checks integrity first: a citation whose `chunkId` or `docId` disagrees
+ * with the passage it is attached to is worse than a missing citation, since it sends
+ * a reader to the wrong place while looking authoritative. Any such mismatch scores 0
+ * regardless of what was retrieved.
+ *
+ * This definition is authored here: the IR has no citation metric kind, so there is
+ * no upstream semantics to match. It is stated rather than derived.
+ */
+export declare class CitationGrounding implements RetrievalMetric {
+    private readonly _name;
+    private readonly _minScore;
+    constructor(options?: {
+        readonly name?: string;
+        readonly minScore?: number;
+    });
+    get name(): string;
+    get deterministic(): boolean;
+    score(entry: RetrievalCase, retrieved: RetrievalResult): Promise<MetricResult>;
+}
+/** The retrieval metrics this runtime ships, in a stable order. */
+export declare function retrievalMetrics(): readonly RetrievalMetric[];
+//# sourceMappingURL=metrics.d.ts.map

package/dist/retrieval/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/retrieval/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;;;;;GAQG;AACH,qBAAa,aAAa;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAEnB,YAAY,IAAI,EAAE;QAChB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;QACvC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;KACpB,EAYA;IAED,+DAA+D;IAC/D,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;QACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;KACpC,GAAG,aAAa,CAOhB;CACF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,KAAK,CAAC,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAChF;AAED;;;;;;GAMG;AACH,qBAAa,SAAU,YAAW,eAAe;IAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,YAAY,OAAO,GAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,EAG/E;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,aAAa,IAAI,OAAO,CAE3B;IAEK,KAAK,CAAC,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,CAAC,CAcnF;CACF;AAED;;;;;GAKG;AACH,qBAAa,kBAAmB,YAAW,eAAe;IACxD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,YAAY,OAAO,GAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,EAG/E;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,aAAa,IAAI,OAAO,CAE3B;IAEK,KAAK,CAAC,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,CAAC,CAsBnF;CACF;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAkB,YAAW,eAAe;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,YAAY,OAAO,GAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,EAG/E;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,aAAa,IAAI,OAAO,CAE3B;IAEK,KAAK,CAAC,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,CAAC,CA6BnF;CACF;AAED,mEAAmE;AACnE,wBAAgB,gBAAgB,IAAI,SAAS,eAAe,EAAE,CAE7D"}