@claude-flow/embeddings/dist/ir-metrics.d.ts

V3 Embedding Service - OpenAI, Transformers.js, Agentic-Flow (ONNX), Mock providers with hyperbolic embeddings, normalization, and chunking

/**
 * ADR-121 Phase 13 — Standard IR evaluation metrics.
 *
 * These are the metrics every retrieval benchmark reports: recall@k,
 * precision@k, mean reciprocal rank (MRR), and normalized discounted
 * cumulative gain (nDCG@k). Used by the RAG benchmark harness to
 * compare the 5 search_text_* primitives on the same corpus.
 *
 * Definitions (standard IR textbook):
 *
 *   recall@k    = |relevant ∩ retrieved_top_k| / |relevant|
 *   precision@k = |relevant ∩ retrieved_top_k| / k
 *   reciprocal rank = 1 / rank_of_first_relevant  (0 if none in top-k)
 *   MRR         = mean of reciprocal ranks over a query set
 *
 *   DCG@k  = Σ_{i=1..k}  rel_i / log2(i + 1)         (binary or graded)
 *   IDCG@k = DCG@k of the ideal ordering (relevant items first)
 *   nDCG@k = DCG@k / IDCG@k    (0..1; 1 = perfect ordering)
 *
 * Inputs are intentionally generic: each metric takes a retrieved-id
 * list and either a relevant-id set (binary judgements) or a
 * id→relevance-grade map (graded judgements). No coupling to the
 * retrieval tools — anything that produces a ranked list of ids can
 * be evaluated.
 */
export type RelevanceSet = ReadonlySet<string> | ReadonlyArray<string>;
export type GradedRelevance = ReadonlyMap<string, number> | Readonly<Record<string, number>>;
/**
 * recall@k = how much of the relevant set we found in the top-k.
 * Returns 0 when relevant is empty (no signal to recall).
 */
export declare function recallAtK(retrieved: ReadonlyArray<string>, relevant: RelevanceSet, k: number): number;
/**
 * precision@k = what fraction of the top-k is relevant. Returns 0
 * for k<=0.
 */
export declare function precisionAtK(retrieved: ReadonlyArray<string>, relevant: RelevanceSet, k: number): number;
/**
 * Reciprocal rank: 1 / (1-based rank of first relevant item in the
 * retrieved list). 0 if no relevant item appears at all.
 */
export declare function reciprocalRank(retrieved: ReadonlyArray<string>, relevant: RelevanceSet): number;
/**
 * Mean reciprocal rank over a set of (retrieved, relevant) pairs.
 * The standard MRR over a query set.
 */
export declare function meanReciprocalRank(queries: ReadonlyArray<{
    retrieved: ReadonlyArray<string>;
    relevant: RelevanceSet;
}>): number;
/**
 * DCG@k over GRADED judgements:
 *   DCG@k = Σ_{i=1..k} rel_i / log2(i + 1)
 * Treats missing ids as relevance 0.
 */
export declare function dcgAtK(retrieved: ReadonlyArray<string>, graded: GradedRelevance, k: number): number;
/**
 * IDCG@k — ideal DCG: assumes the top-k contains the k highest-graded
 * items from the judgement pool.
 */
export declare function idcgAtK(graded: GradedRelevance, k: number): number;
/**
 * nDCG@k = DCG@k / IDCG@k, clamped to [0, 1]. Returns 0 when no
 * relevant items exist (IDCG is 0).
 *
 * Supports both binary judgements (pass a Set/Array → grade=1 each)
 * and graded judgements (pass a Map/Record).
 */
export declare function ndcgAtK(retrieved: ReadonlyArray<string>, judgements: RelevanceSet | GradedRelevance, k: number): number;
/**
 * Compare a ranking against judgements across MULTIPLE k values in
 * one pass. Standard benchmarking pattern — `recall@1 / 5 / 10` plus
 * `nDCG@1 / 5 / 10` plus MRR all in a single call. Cheaper than
 * calling each metric N times.
 *
 * Returns:
 *   {
 *     recall:   { 1: number, 5: number, 10: number, ... },
 *     ndcg:     { 1: number, 5: number, 10: number, ... },
 *     precision:{ 1: number, 5: number, 10: number, ... },
 *     mrr: number,
 *   }
 */
export interface RankingComparison {
    readonly recall: Readonly<Record<number, number>>;
    readonly precision: Readonly<Record<number, number>>;
    readonly ndcg: Readonly<Record<number, number>>;
    readonly mrr: number;
}
export declare function compareRankings(retrieved: ReadonlyArray<string>, judgements: RelevanceSet | GradedRelevance, ks: ReadonlyArray<number>): RankingComparison;
/**
 * Convenience: roll up a metric over a query set (mean across queries).
 * Skips queries with empty relevant sets (no signal).
 */
export declare function meanMetric(queries: ReadonlyArray<{
    retrieved: ReadonlyArray<string>;
    relevant: RelevanceSet | GradedRelevance;
}>, metric: (retrieved: ReadonlyArray<string>, judgements: RelevanceSet | GradedRelevance) => number): number;
//# sourceMappingURL=ir-metrics.d.ts.map