rag-eval-node-ts 0.3.0

package/dist/evaluate.js

@@ -0,0 +1,208 @@
+"use strict";
+/**
+ * Core evaluate() and evaluateBatch() functions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluate = evaluate;
+exports.evaluateBatch = evaluateBatch;
+const index_1 = require("./metrics/index");
+const ALL_METRICS = [
+    'faithfulness',
+    'answerRelevance',
+    'contextPrecision',
+    'contextRecall',
+    'contextRelevance',
+    'answerCorrectness',
+    'hallucinationRate',
+];
+const DEFAULT_COMPOSITE_THRESHOLD = 0.6;
+const DEFAULT_CONCURRENCY = 4;
+const DEFAULT_REGRESSION_THRESHOLD = 0.05;
+/**
+ * Evaluate a single EvalSample against the requested metrics.
+ * Only heuristic mode is implemented; LLM/hybrid options are accepted but ignored.
+ */
+async function evaluate(sample, metrics, options) {
+    const start = Date.now();
+    const activeMetrics = metrics ?? ALL_METRICS;
+    const heuristicOptions = options?.heuristic;
+    const thresholds = options?.thresholds ?? {};
+    const compositeThreshold = options?.compositeThreshold ?? DEFAULT_COMPOSITE_THRESHOLD;
+    const compositeWeights = options?.compositeWeights ?? {};
+    const metricResults = {};
+    for (const metricId of activeMetrics) {
+        const result = await (0, index_1.computeMetric)(metricId, sample, heuristicOptions);
+        // Apply per-metric threshold overrides
+        const overrideThreshold = thresholds[metricId];
+        if (overrideThreshold !== undefined) {
+            const adjustedPassed = result.score !== null ? result.score >= overrideThreshold : null;
+            metricResults[metricId] = {
+                ...result,
+                threshold: overrideThreshold,
+                passed: adjustedPassed,
+            };
+        }
+        else {
+            metricResults[metricId] = result;
+        }
+    }
+    // Compute composite score: weighted average of non-null scores
+    let weightedSum = 0;
+    let totalWeight = 0;
+    let allPassed = true;
+    for (const metricId of activeMetrics) {
+        const r = metricResults[metricId];
+        if (!r)
+            continue;
+        if (r.score !== null) {
+            const w = compositeWeights[metricId] ?? 1;
+            weightedSum += r.score * w;
+            totalWeight += w;
+        }
+        if (r.passed === false)
+            allPassed = false;
+    }
+    const compositeScore = totalWeight > 0 ? weightedSum / totalWeight : null;
+    const compositePassed = compositeScore !== null ? compositeScore >= compositeThreshold : false;
+    const passed = allPassed && compositePassed;
+    const cost = {
+        llmCalls: 0,
+        estimatedInputTokens: 0,
+        estimatedOutputTokens: 0,
+        parseFailures: 0,
+    };
+    return {
+        sample,
+        metrics: metricResults,
+        compositeScore,
+        passed,
+        cost,
+        durationMs: Date.now() - start,
+        evaluatedAt: new Date().toISOString(),
+    };
+}
+function computeAggregate(metricId, results, _threshold) {
+    const scores = [];
+    let nullCount = 0;
+    let passCount = 0;
+    for (const r of results) {
+        const mr = r.metrics[metricId];
+        if (!mr)
+            continue;
+        if (mr.score === null) {
+            nullCount++;
+        }
+        else {
+            scores.push(mr.score);
+        }
+        if (mr.passed === true)
+            passCount++;
+    }
+    const total = results.length;
+    const nullRate = total > 0 ? nullCount / total : 0;
+    const passRate = total > 0 ? passCount / total : 0;
+    if (scores.length === 0) {
+        return { metricId, mean: 0, median: 0, min: 0, max: 0, stdDev: 0, passRate, nullRate };
+    }
+    const sorted = [...scores].sort((a, b) => a - b);
+    const mean = scores.reduce((a, b) => a + b, 0) / scores.length;
+    const median = sorted.length % 2 === 0
+        ? (sorted[sorted.length / 2 - 1] + sorted[sorted.length / 2]) / 2
+        : sorted[Math.floor(sorted.length / 2)];
+    const min = sorted[0];
+    const max = sorted[sorted.length - 1];
+    const variance = scores.reduce((acc, s) => acc + (s - mean) ** 2, 0) / scores.length;
+    const stdDev = Math.sqrt(variance);
+    return { metricId, mean, median, min, max, stdDev, passRate, nullRate };
+}
+function computeCompositeAggregate(results) {
+    const scores = results.map(r => r.compositeScore).filter((s) => s !== null);
+    if (scores.length === 0) {
+        return { mean: 0, median: 0, min: 0, max: 0, stdDev: 0, passRate: 0 };
+    }
+    const sorted = [...scores].sort((a, b) => a - b);
+    const mean = scores.reduce((a, b) => a + b, 0) / scores.length;
+    const median = sorted.length % 2 === 0
+        ? (sorted[sorted.length / 2 - 1] + sorted[sorted.length / 2]) / 2
+        : sorted[Math.floor(sorted.length / 2)];
+    const min = sorted[0];
+    const max = sorted[sorted.length - 1];
+    const variance = scores.reduce((acc, s) => acc + (s - mean) ** 2, 0) / scores.length;
+    const stdDev = Math.sqrt(variance);
+    const passRate = results.filter(r => r.passed).length / results.length;
+    return { mean, median, min, max, stdDev, passRate };
+}
+/**
+ * Evaluate a batch of EvalSamples with concurrency control.
+ */
+async function evaluateBatch(samples, metrics, options) {
+    const start = Date.now();
+    const concurrency = options?.concurrency ?? DEFAULT_CONCURRENCY;
+    const regressionThreshold = options?.regressionThreshold ?? DEFAULT_REGRESSION_THRESHOLD;
+    const onProgress = options?.onProgress;
+    const results = new Array(samples.length);
+    let completed = 0;
+    // Process with limited concurrency
+    async function processChunk(startIdx) {
+        for (let i = startIdx; i < samples.length; i += concurrency) {
+            results[i] = await evaluate(samples[i], metrics, options);
+            completed++;
+            onProgress?.(completed, samples.length);
+        }
+    }
+    const workers = [];
+    for (let i = 0; i < Math.min(concurrency, samples.length); i++) {
+        workers.push(processChunk(i));
+    }
+    await Promise.all(workers);
+    const activeMetrics = metrics ?? ALL_METRICS;
+    // Build aggregates
+    const thresholds = options?.thresholds ?? {};
+    const aggregates = {};
+    for (const metricId of activeMetrics) {
+        const defaultThreshold = results[0]?.metrics[metricId]?.threshold ?? 0.7;
+        const threshold = thresholds[metricId] ?? defaultThreshold;
+        aggregates[metricId] = computeAggregate(metricId, results, threshold);
+    }
+    const compositeAggregate = computeCompositeAggregate(results);
+    // Compute total cost
+    const totalCost = {
+        llmCalls: 0,
+        estimatedInputTokens: 0,
+        estimatedOutputTokens: 0,
+        parseFailures: 0,
+    };
+    // Regression detection
+    let regressions;
+    if (options?.baselineResult) {
+        regressions = [];
+        const baseline = options.baselineResult;
+        for (const metricId of activeMetrics) {
+            const baselineAgg = baseline.aggregates[metricId];
+            const currentAgg = aggregates[metricId];
+            if (!baselineAgg || !currentAgg)
+                continue;
+            const delta = currentAgg.mean - baselineAgg.mean;
+            const regressed = delta < -regressionThreshold;
+            regressions.push({
+                metricId,
+                baselineMean: baselineAgg.mean,
+                currentMean: currentAgg.mean,
+                delta,
+                regressed,
+            });
+        }
+    }
+    const passed = results.every(r => r.passed) && compositeAggregate.passRate >= 0.5;
+    return {
+        results,
+        aggregates: aggregates,
+        compositeAggregate,
+        passed,
+        totalCost,
+        totalDurationMs: Date.now() - start,
+        regressions,
+        evaluatedAt: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/evaluate.js.map

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

package/dist/evaluator.d.ts

@@ -0,0 +1,10 @@
+/**
+ * createEvaluator() factory: returns a pre-configured Evaluator instance.
+ */
+import type { EvaluatorConfig, Evaluator } from './types';
+/**
+ * Create a pre-configured Evaluator bound to the given config.
+ * Per-call options are merged with config, with per-call options taking precedence.
+ */
+export declare function createEvaluator(config: EvaluatorConfig): Evaluator;
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../src/evaluator.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,SAAS,EAOV,MAAM,SAAS,CAAC;AAGjB;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAqClE"}

package/dist/evaluator.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * createEvaluator() factory: returns a pre-configured Evaluator instance.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEvaluator = createEvaluator;
+const evaluate_1 = require("./evaluate");
+/**
+ * Create a pre-configured Evaluator bound to the given config.
+ * Per-call options are merged with config, with per-call options taking precedence.
+ */
+function createEvaluator(config) {
+    const defaultMetrics = config.metrics;
+    function mergeOptions(perCallOptions) {
+        if (!perCallOptions)
+            return config;
+        return {
+            ...config,
+            ...perCallOptions,
+            thresholds: { ...config.thresholds, ...perCallOptions.thresholds },
+            compositeWeights: { ...config.compositeWeights, ...perCallOptions.compositeWeights },
+            heuristic: { ...config.heuristic, ...perCallOptions.heuristic },
+        };
+    }
+    return {
+        config,
+        async evaluate(sample, metrics, options) {
+            const activeMetrics = metrics ?? defaultMetrics;
+            const merged = mergeOptions(options);
+            return (0, evaluate_1.evaluate)(sample, activeMetrics, merged);
+        },
+        async evaluateBatch(samples, metrics, options) {
+            const activeMetrics = metrics ?? defaultMetrics;
+            const merged = mergeOptions(options);
+            return (0, evaluate_1.evaluateBatch)(samples, activeMetrics, merged);
+        },
+    };
+}
+//# sourceMappingURL=evaluator.js.map

package/dist/evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.js","sourceRoot":"","sources":["../src/evaluator.ts"],"names":[],"mappings":";AAAA;;GAEG;;AAkBH,0CAqCC;AA3CD,yCAAqD;AAErD;;;GAGG;AACH,SAAgB,eAAe,CAAC,MAAuB;IACrD,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,CAAC;IAEtC,SAAS,YAAY,CAA4B,cAAkB;QACjE,IAAI,CAAC,cAAc;YAAE,OAAO,MAAsB,CAAC;QACnD,OAAO;YACL,GAAG,MAAM;YACT,GAAG,cAAc;YACjB,UAAU,EAAE,EAAE,GAAG,MAAM,CAAC,UAAU,EAAE,GAAG,cAAc,CAAC,UAAU,EAAE;YAClE,gBAAgB,EAAE,EAAE,GAAG,MAAM,CAAC,gBAAgB,EAAE,GAAG,cAAc,CAAC,gBAAgB,EAAE;YACpF,SAAS,EAAE,EAAE,GAAG,MAAM,CAAC,SAAS,EAAE,GAAG,cAAc,CAAC,SAAS,EAAE;SAChE,CAAC;IACJ,CAAC;IAED,OAAO;QACL,MAAM;QAEN,KAAK,CAAC,QAAQ,CACZ,MAAkB,EAClB,OAAoB,EACpB,OAAyB;YAEzB,MAAM,aAAa,GAAG,OAAO,IAAI,cAAc,CAAC;YAChD,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;YACrC,OAAO,IAAA,mBAAQ,EAAC,MAAM,EAAE,aAAa,EAAE,MAAM,CAAC,CAAC;QACjD,CAAC;QAED,KAAK,CAAC,aAAa,CACjB,OAAqB,EACrB,OAAoB,EACpB,OAA8B;YAE9B,MAAM,aAAa,GAAG,OAAO,IAAI,cAAc,CAAC;YAChD,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;YACrC,OAAO,IAAA,wBAAa,EAAC,OAAO,EAAE,aAAa,EAAE,MAAM,CAAC,CAAC;QACvD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/heuristic/ngrams.d.ts

@@ -0,0 +1,22 @@
+/**
+ * N-gram utilities for heuristic evaluation.
+ */
+/**
+ * Lowercase, split on whitespace and punctuation, filter empty tokens.
+ */
+export declare function tokenize(text: string): string[];
+/**
+ * Returns all n-grams from a token list as joined strings ("word1 word2").
+ */
+export declare function getNgrams(tokens: string[], n: number): string[];
+/**
+ * Jaccard-style n-gram overlap: |intersection| / |union| using set semantics.
+ * Default n=1 (unigram).
+ */
+export declare function ngramOverlap(a: string, b: string, n?: number): number;
+/**
+ * Weighted average of ngramOverlap for multiple n-gram sizes.
+ * Default: n=[1,2], weights=[0.7, 0.3].
+ */
+export declare function weightedNgramOverlap(a: string, b: string, ngramSizes?: number[], weights?: number[]): number;
+//# sourceMappingURL=ngrams.d.ts.map

package/dist/heuristic/ngrams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ngrams.d.ts","sourceRoot":"","sources":["../../src/heuristic/ngrams.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAK/C;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAO/D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,SAAI,GAAG,MAAM,CAgBhE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,UAAU,GAAE,MAAM,EAAW,EAC7B,OAAO,GAAE,MAAM,EAAe,GAC7B,MAAM,CAcR"}

package/dist/heuristic/ngrams.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * N-gram utilities for heuristic evaluation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tokenize = tokenize;
+exports.getNgrams = getNgrams;
+exports.ngramOverlap = ngramOverlap;
+exports.weightedNgramOverlap = weightedNgramOverlap;
+/**
+ * Lowercase, split on whitespace and punctuation, filter empty tokens.
+ */
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[\s\p{P}]+/u)
+        .filter(t => t.length > 0);
+}
+/**
+ * Returns all n-grams from a token list as joined strings ("word1 word2").
+ */
+function getNgrams(tokens, n) {
+    if (tokens.length < n)
+        return [];
+    const result = [];
+    for (let i = 0; i <= tokens.length - n; i++) {
+        result.push(tokens.slice(i, i + n).join(' '));
+    }
+    return result;
+}
+/**
+ * Jaccard-style n-gram overlap: |intersection| / |union| using set semantics.
+ * Default n=1 (unigram).
+ */
+function ngramOverlap(a, b, n = 1) {
+    const tokensA = tokenize(a);
+    const tokensB = tokenize(b);
+    const ngramsA = new Set(getNgrams(tokensA, n));
+    const ngramsB = new Set(getNgrams(tokensB, n));
+    if (ngramsA.size === 0 && ngramsB.size === 0)
+        return 1.0;
+    if (ngramsA.size === 0 || ngramsB.size === 0)
+        return 0.0;
+    let intersectionCount = 0;
+    for (const ng of ngramsA) {
+        if (ngramsB.has(ng))
+            intersectionCount++;
+    }
+    const unionCount = ngramsA.size + ngramsB.size - intersectionCount;
+    return intersectionCount / unionCount;
+}
+/**
+ * Weighted average of ngramOverlap for multiple n-gram sizes.
+ * Default: n=[1,2], weights=[0.7, 0.3].
+ */
+function weightedNgramOverlap(a, b, ngramSizes = [1, 2], weights = [0.7, 0.3]) {
+    let totalWeight = 0;
+    let weightedSum = 0;
+    for (let i = 0; i < ngramSizes.length; i++) {
+        const n = ngramSizes[i];
+        const w = weights[i] ?? 1;
+        const overlap = ngramOverlap(a, b, n);
+        weightedSum += overlap * w;
+        totalWeight += w;
+    }
+    if (totalWeight === 0)
+        return 0;
+    return weightedSum / totalWeight;
+}
+//# sourceMappingURL=ngrams.js.map

package/dist/heuristic/ngrams.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ngrams.js","sourceRoot":"","sources":["../../src/heuristic/ngrams.ts"],"names":[],"mappings":";AAAA;;GAEG;;AAKH,4BAKC;AAKD,8BAOC;AAMD,oCAgBC;AAMD,oDAmBC;AAnED;;GAEG;AACH,SAAgB,QAAQ,CAAC,IAAY;IACnC,OAAO,IAAI;SACR,WAAW,EAAE;SACb,KAAK,CAAC,aAAa,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,SAAgB,SAAS,CAAC,MAAgB,EAAE,CAAS;IACnD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5C,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,SAAgB,YAAY,CAAC,CAAS,EAAE,CAAS,EAAE,CAAC,GAAG,CAAC;IACtD,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;IAE/C,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IACzD,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IAEzD,IAAI,iBAAiB,GAAG,CAAC,CAAC;IAC1B,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;QACzB,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,iBAAiB,EAAE,CAAC;IAC3C,CAAC;IAED,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,GAAG,iBAAiB,CAAC;IACnE,OAAO,iBAAiB,GAAG,UAAU,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,SAAgB,oBAAoB,CAClC,CAAS,EACT,CAAS,EACT,aAAuB,CAAC,CAAC,EAAE,CAAC,CAAC,EAC7B,UAAoB,CAAC,GAAG,EAAE,GAAG,CAAC;IAE9B,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,WAAW,GAAG,CAAC,CAAC;IAEpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;QACxB,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC1B,MAAM,OAAO,GAAG,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACtC,WAAW,IAAI,OAAO,GAAG,CAAC,CAAC;QAC3B,WAAW,IAAI,CAAC,CAAC;IACnB,CAAC;IAED,IAAI,WAAW,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAChC,OAAO,WAAW,GAAG,WAAW,CAAC;AACnC,CAAC"}

package/dist/heuristic/sentences.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Sentence segmentation utilities for heuristic evaluation.
+ */
+/**
+ * Split text into sentences on . ! ? followed by whitespace+uppercase or end of string.
+ * Filters empty strings.
+ */
+export declare function splitSentences(text: string): string[];
+/**
+ * Keep sentences with at least 3 words (simple heuristic for factual content).
+ */
+export declare function filterFactualSentences(sentences: string[]): string[];
+//# sourceMappingURL=sentences.d.ts.map

package/dist/heuristic/sentences.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentences.d.ts","sourceRoot":"","sources":["../../src/heuristic/sentences.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAIrD;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAEpE"}

package/dist/heuristic/sentences.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Sentence segmentation utilities for heuristic evaluation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitSentences = splitSentences;
+exports.filterFactualSentences = filterFactualSentences;
+/**
+ * Split text into sentences on . ! ? followed by whitespace+uppercase or end of string.
+ * Filters empty strings.
+ */
+function splitSentences(text) {
+    // Split on sentence-ending punctuation followed by whitespace+uppercase or end of string
+    const raw = text.split(/(?<=[.!?])\s+(?=[A-Z])|(?<=[.!?])\s*$/);
+    return raw.map(s => s.trim()).filter(s => s.length > 0);
+}
+/**
+ * Keep sentences with at least 3 words (simple heuristic for factual content).
+ */
+function filterFactualSentences(sentences) {
+    return sentences.filter(s => s.split(/\s+/).filter(w => w.length > 0).length >= 3);
+}
+//# sourceMappingURL=sentences.js.map

package/dist/heuristic/sentences.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentences.js","sourceRoot":"","sources":["../../src/heuristic/sentences.ts"],"names":[],"mappings":";AAAA;;GAEG;;AAMH,wCAIC;AAKD,wDAEC;AAfD;;;GAGG;AACH,SAAgB,cAAc,CAAC,IAAY;IACzC,yFAAyF;IACzF,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAChE,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED;;GAEG;AACH,SAAgB,sBAAsB,CAAC,SAAmB;IACxD,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC;AACrF,CAAC"}

package/dist/heuristic/tfidf.d.ts

@@ -0,0 +1,21 @@
+/**
+ * TF-IDF vectorization and cosine similarity utilities for heuristic evaluation.
+ */
+/**
+ * Build TF-IDF vectors for a query and a set of documents.
+ * TF = count/total, IDF = log((N+1)/(df+1))+1 (sklearn-style smooth IDF).
+ */
+export declare function buildTfIdfVectors(query: string, documents: string[]): {
+    queryVec: Map<string, number>;
+    docVecs: Map<string, number>[];
+};
+/**
+ * Cosine similarity between two TF-IDF vectors.
+ * Returns 0 if either vector is zero.
+ */
+export declare function cosineSimilarity(a: Map<string, number>, b: Map<string, number>): number;
+/**
+ * Convenience: compute TF-IDF cosine similarity between a query and a document.
+ */
+export declare function tfidfSimilarity(query: string, document: string): number;
+//# sourceMappingURL=tfidf.d.ts.map

package/dist/heuristic/tfidf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tfidf.d.ts","sourceRoot":"","sources":["../../src/heuristic/tfidf.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EAAE,GAClB;IAAE,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAA;CAAE,CAmDnE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EACtB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GACrB,MAAM,CAgBR;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGvE"}

package/dist/heuristic/tfidf.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * TF-IDF vectorization and cosine similarity utilities for heuristic evaluation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTfIdfVectors = buildTfIdfVectors;
+exports.cosineSimilarity = cosineSimilarity;
+exports.tfidfSimilarity = tfidfSimilarity;
+const ngrams_1 = require("./ngrams");
+/**
+ * Build TF-IDF vectors for a query and a set of documents.
+ * TF = count/total, IDF = log((N+1)/(df+1))+1 (sklearn-style smooth IDF).
+ */
+function buildTfIdfVectors(query, documents) {
+    const allTexts = [query, ...documents];
+    const tokenLists = allTexts.map(t => (0, ngrams_1.tokenize)(t));
+    // Build vocabulary
+    const vocab = new Set();
+    for (const tokens of tokenLists) {
+        for (const t of tokens)
+            vocab.add(t);
+    }
+    const N = allTexts.length;
+    // Compute document frequencies
+    const df = new Map();
+    for (const term of vocab) {
+        let count = 0;
+        for (const tokens of tokenLists) {
+            if (tokens.includes(term))
+                count++;
+        }
+        df.set(term, count);
+    }
+    // Compute IDF (sklearn smooth): log((N+1)/(df+1)) + 1
+    const idf = new Map();
+    for (const term of vocab) {
+        const docFreq = df.get(term) ?? 0;
+        idf.set(term, Math.log((N + 1) / (docFreq + 1)) + 1);
+    }
+    // Build TF-IDF vector for a token list
+    function buildVec(tokens) {
+        const vec = new Map();
+        if (tokens.length === 0)
+            return vec;
+        const counts = new Map();
+        for (const t of tokens) {
+            counts.set(t, (counts.get(t) ?? 0) + 1);
+        }
+        for (const [term, count] of counts) {
+            const tf = count / tokens.length;
+            const termIdf = idf.get(term) ?? 1;
+            vec.set(term, tf * termIdf);
+        }
+        return vec;
+    }
+    const queryVec = buildVec(tokenLists[0]);
+    const docVecs = tokenLists.slice(1).map(tl => buildVec(tl));
+    return { queryVec, docVecs };
+}
+/**
+ * Cosine similarity between two TF-IDF vectors.
+ * Returns 0 if either vector is zero.
+ */
+function cosineSimilarity(a, b) {
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (const [term, val] of a) {
+        normA += val * val;
+        const bVal = b.get(term) ?? 0;
+        dot += val * bVal;
+    }
+    for (const [, val] of b) {
+        normB += val * val;
+    }
+    if (normA === 0 || normB === 0)
+        return 0;
+    return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+/**
+ * Convenience: compute TF-IDF cosine similarity between a query and a document.
+ */
+function tfidfSimilarity(query, document) {
+    const { queryVec, docVecs } = buildTfIdfVectors(query, [document]);
+    return cosineSimilarity(queryVec, docVecs[0]);
+}
+//# sourceMappingURL=tfidf.js.map

package/dist/heuristic/tfidf.js.map

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

package/dist/heuristic/token-f1.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Token-level F1 score for answer correctness evaluation.
+ */
+/**
+ * Compute token-level F1 using multiset intersection (counting duplicates).
+ * precision = |common| / |hypothesis tokens|
+ * recall    = |common| / |reference tokens|
+ * F1 = 2 * precision * recall / (precision + recall)
+ * Returns 0 if either input is empty.
+ */
+export declare function tokenF1(reference: string, hypothesis: string): number;
+//# sourceMappingURL=token-f1.d.ts.map

package/dist/heuristic/token-f1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-f1.d.ts","sourceRoot":"","sources":["../../src/heuristic/token-f1.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CA8BrE"}

package/dist/heuristic/token-f1.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * Token-level F1 score for answer correctness evaluation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tokenF1 = tokenF1;
+const ngrams_1 = require("./ngrams");
+/**
+ * Compute token-level F1 using multiset intersection (counting duplicates).
+ * precision = |common| / |hypothesis tokens|
+ * recall    = |common| / |reference tokens|
+ * F1 = 2 * precision * recall / (precision + recall)
+ * Returns 0 if either input is empty.
+ */
+function tokenF1(reference, hypothesis) {
+    const refTokens = (0, ngrams_1.tokenize)(reference);
+    const hypTokens = (0, ngrams_1.tokenize)(hypothesis);
+    if (refTokens.length === 0 || hypTokens.length === 0)
+        return 0;
+    // Build frequency maps
+    const refCounts = new Map();
+    for (const t of refTokens) {
+        refCounts.set(t, (refCounts.get(t) ?? 0) + 1);
+    }
+    const hypCounts = new Map();
+    for (const t of hypTokens) {
+        hypCounts.set(t, (hypCounts.get(t) ?? 0) + 1);
+    }
+    // Multiset intersection count
+    let commonCount = 0;
+    for (const [term, refCount] of refCounts) {
+        const hypCount = hypCounts.get(term) ?? 0;
+        commonCount += Math.min(refCount, hypCount);
+    }
+    if (commonCount === 0)
+        return 0;
+    const precision = commonCount / hypTokens.length;
+    const recall = commonCount / refTokens.length;
+    return (2 * precision * recall) / (precision + recall);
+}
+//# sourceMappingURL=token-f1.js.map

package/dist/heuristic/token-f1.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-f1.js","sourceRoot":"","sources":["../../src/heuristic/token-f1.ts"],"names":[],"mappings":";AAAA;;GAEG;;AAWH,0BA8BC;AAvCD,qCAAoC;AAEpC;;;;;;GAMG;AACH,SAAgB,OAAO,CAAC,SAAiB,EAAE,UAAkB;IAC3D,MAAM,SAAS,GAAG,IAAA,iBAAQ,EAAC,SAAS,CAAC,CAAC;IACtC,MAAM,SAAS,GAAG,IAAA,iBAAQ,EAAC,UAAU,CAAC,CAAC;IAEvC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAE/D,uBAAuB;IACvB,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,8BAA8B;IAC9B,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,SAAS,EAAE,CAAC;QACzC,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1C,WAAW,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC9C,CAAC;IAED,IAAI,WAAW,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAEhC,MAAM,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC,MAAM,CAAC;IACjD,MAAM,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC,MAAM,CAAC;IAE9C,OAAO,CAAC,CAAC,GAAG,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,GAAG,MAAM,CAAC,CAAC;AACzD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export type { MetricId, EvaluationMode, EvalSample, EvalSignal, MetricResult, CostTracker, EvalResult, MetricAggregate, MetricRegression, BatchEvalResult, JudgeFn, PromptOverrides, MetricThresholds, HeuristicOptions, EvaluateOptions, BatchEvaluateOptions, EvaluatorConfig, Evaluator, } from './types';
+export { evaluate, evaluateBatch } from './evaluate';
+export { createEvaluator } from './evaluator';
+export { scoreFaithfulness, scoreAnswerRelevance, scoreContextPrecision, scoreContextRecall, scoreContextRelevance, scoreAnswerCorrectness, scoreHallucinationRate, computeMetric, } from './metrics/index';
+export { splitSentences, filterFactualSentences } from './heuristic/sentences';
+export { tokenize, getNgrams, ngramOverlap, weightedNgramOverlap } from './heuristic/ngrams';
+export { buildTfIdfVectors, cosineSimilarity, tfidfSimilarity } from './heuristic/tfidf';
+export { tokenF1 } from './heuristic/token-f1';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,QAAQ,EACR,cAAc,EACd,UAAU,EACV,UAAU,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,OAAO,EACP,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,eAAe,EACf,SAAS,GACV,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGrD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,aAAa,GACd,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC7F,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzF,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC"}