rag-eval-node-ts 0.3.0

package/README.md

@@ -0,0 +1,204 @@
+# rag-eval-node-ts
+
+Lightweight RAG evaluation metrics for CI/CD pipelines. Provides seven metrics for measuring RAG pipeline quality, with heuristic evaluation mode (zero LLM cost) and a pluggable LLM-as-judge interface for hybrid or full LLM modes.
+
+## Installation
+
+```bash
+npm install rag-eval-node-ts
+```
+
+For LLM-as-judge mode, install optional peer dependencies:
+
+```bash
+# OpenAI
+npm install openai
+
+# Anthropic
+npm install @anthropic-ai/sdk
+```
+
+## Quick Start
+
+### Heuristic mode (zero LLM cost)
+
+```ts
+import { evaluate } from 'rag-eval-node-ts';
+
+const result = await evaluate({
+  question: 'What is retrieval-augmented generation?',
+  answer: 'RAG combines retrieval with generation to produce grounded answers.',
+  contexts: [
+    'Retrieval-augmented generation (RAG) is a technique that combines information retrieval with text generation.',
+  ],
+  groundTruth: 'RAG is a method that retrieves relevant documents and uses them to generate accurate responses.',
+});
+
+console.log(result.compositeScore); // 0.0 - 1.0
+console.log(result.passed);        // true if all metrics pass thresholds
+```
+
+### Pre-configured evaluator
+
+```ts
+import { createEvaluator } from 'rag-eval-node-ts';
+
+const evaluator = createEvaluator({
+  mode: 'heuristic',
+  metrics: ['faithfulness', 'answerRelevance', 'contextPrecision'],
+  thresholds: { faithfulness: 0.8 },
+  compositeThreshold: 0.7,
+});
+
+const result = await evaluator.evaluate(sample);
+const batchResult = await evaluator.evaluateBatch(samples);
+```
+
+### Batch evaluation
+
+```ts
+import { evaluateBatch } from 'rag-eval-node-ts';
+
+const batchResult = await evaluateBatch(samples, undefined, {
+  concurrency: 8,
+  onProgress: (completed, total) => console.log(`${completed}/${total}`),
+});
+
+console.log(batchResult.aggregates.faithfulness.mean);
+console.log(batchResult.compositeAggregate.passRate);
+```
+
+### Regression detection
+
+```ts
+const baseline = await evaluateBatch(baselineSamples);
+const current = await evaluateBatch(currentSamples, undefined, {
+  baselineResult: baseline,
+  regressionThreshold: 0.05,
+});
+
+for (const r of current.regressions ?? []) {
+  if (r.regressed) {
+    console.warn(`${r.metricId}: dropped by ${Math.abs(r.delta).toFixed(3)}`);
+  }
+}
+```
+
+## API
+
+### `evaluate(sample, metrics?, options?): Promise<EvalResult>`
+
+Evaluates a single `EvalSample` and returns an `EvalResult`.
+
+- `sample` — the input (question, answer, contexts, optional groundTruth)
+- `metrics` — subset of `MetricId[]` to compute (default: all 7)
+- `options` — `EvaluateOptions` (thresholds, compositeThreshold, compositeWeights, heuristic tuning)
+
+### `evaluateBatch(samples, metrics?, options?): Promise<BatchEvalResult>`
+
+Evaluates a batch of samples with concurrency control and optional regression detection.
+
+- `options.concurrency` — max parallel evaluations (default: 4)
+- `options.onProgress` — progress callback
+- `options.baselineResult` — prior `BatchEvalResult` for regression comparison
+- `options.regressionThreshold` — minimum mean drop to flag a regression (default: 0.05)
+
+### `createEvaluator(config): Evaluator`
+
+Returns a pre-configured `Evaluator` instance. Config is merged with per-call options; per-call options win on conflict.
+
+```ts
+const evaluator = createEvaluator({
+  mode: 'heuristic',
+  metrics: ['faithfulness', 'answerRelevance'],
+  thresholds: { faithfulness: 0.8 },
+  compositeThreshold: 0.65,
+  heuristic: { claimSupportThreshold: 0.2 },
+});
+
+// evaluate() and evaluateBatch() are bound to this config
+const result = await evaluator.evaluate(sample);
+```
+
+## Metrics
+
+All 7 metrics operate in heuristic mode using text overlap, TF-IDF similarity, and token-level F1.
+
+| Metric | `MetricId` | Requires `groundTruth` | Default Threshold | Description |
+|--------|-----------|----------------------|-------------------|-------------|
+| Faithfulness | `faithfulness` | No | 0.7 | Is the answer supported by the contexts? Scores each answer sentence against the best-matching context chunk using weighted n-gram overlap. |
+| Answer Relevance | `answerRelevance` | No | 0.7 | Is the answer relevant to the question? Averages TF-IDF cosine similarity and unigram Jaccard overlap between question and answer. |
+| Context Precision | `contextPrecision` | No | 0.7 | Are retrieved contexts relevant to the question? Average TF-IDF similarity of each context chunk against the question. |
+| Context Recall | `contextRecall` | Yes | 0.7 | Do contexts cover the ground truth? Fraction of ground-truth sentences with unigram overlap >= 0.3 against any context chunk. |
+| Context Relevance | `contextRelevance` | No | 0.6 | Stricter relevance check: fraction of context chunks with weighted n-gram overlap >= `chunkRelevanceThreshold` (default 0.2). |
+| Answer Correctness | `answerCorrectness` | Yes | 0.6 | Is the answer factually correct vs ground truth? Blends token F1 (70%) and unigram Jaccard (30%). |
+| Hallucination Rate | `hallucinationRate` | No | 0.7 | Does the answer contain unsupported claims? Score = 1 − (fraction of answer sentences with max context overlap < `claimSupportThreshold`). |
+
+## Heuristic Options
+
+Pass via `options.heuristic` or `EvaluatorConfig.heuristic`:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `claimSupportThreshold` | 0.15 | Min unigram overlap for a sentence to be considered context-supported (hallucinationRate). |
+| `chunkRelevanceThreshold` | 0.2 | Min weighted n-gram overlap for a chunk to count as relevant (contextRelevance). |
+| `ngramSizes` | `[1, 2]` | N-gram sizes for weighted overlap. |
+| `ngramWeights` | `[0.7, 0.3]` | Weights for each n-gram size. |
+
+## Signals
+
+Each `MetricResult` includes a `signals` array of `EvalSignal` objects flagging specific findings:
+
+| Severity | When emitted |
+|----------|-------------|
+| `warning` | Answer sentence has low context support (faithfulness), answer relevance is low, answer correctness is low |
+| `info` | Context chunks with low precision score listed (contextPrecision) |
+| `critical` | Specific unsupported answer sentences (hallucinationRate) |
+
+## Exports
+
+### Functions
+- `evaluate` — single sample evaluation
+- `evaluateBatch` — batch evaluation with concurrency
+- `createEvaluator` — pre-configured evaluator factory
+
+### Metric functions
+- `scoreFaithfulness`, `scoreAnswerRelevance`, `scoreContextPrecision`
+- `scoreContextRecall`, `scoreContextRelevance`, `scoreAnswerCorrectness`
+- `scoreHallucinationRate`
+- `computeMetric` — dispatch by MetricId
+
+### Heuristic primitives
+- `tokenize`, `getNgrams`, `ngramOverlap`, `weightedNgramOverlap`
+- `buildTfIdfVectors`, `cosineSimilarity`, `tfidfSimilarity`
+- `tokenF1`
+- `splitSentences`, `filterFactualSentences`
+
+### Types
+All 18 types are exported: `MetricId`, `EvaluationMode`, `EvalSample`, `EvalSignal`, `MetricResult`, `CostTracker`, `EvalResult`, `MetricAggregate`, `MetricRegression`, `BatchEvalResult`, `JudgeFn`, `PromptOverrides`, `MetricThresholds`, `HeuristicOptions`, `EvaluateOptions`, `BatchEvaluateOptions`, `EvaluatorConfig`, `Evaluator`.
+
+## Evaluation Modes
+
+| Mode | Description | LLM Cost |
+|------|-------------|----------|
+| `heuristic` | Deterministic text-overlap and TF-IDF heuristics | None |
+| `llm` | LLM-as-judge via a pluggable `JudgeFn` | Per-call |
+| `hybrid` | Routes each metric to heuristic or LLM based on config | Partial |
+
+LLM and hybrid modes are accepted by the API but currently route to heuristic; full LLM judge integration is planned.
+
+## Adapters
+
+LLM adapters are available as subpath imports:
+
+```ts
+// OpenAI
+import { createOpenAIJudge } from 'rag-eval-node-ts/adapters/openai';
+
+// Anthropic
+import { createAnthropicJudge } from 'rag-eval-node-ts/adapters/anthropic';
+```
+
+## License
+
+MIT

package/dist/__tests__/evaluate.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=evaluate.test.d.ts.map

package/dist/__tests__/evaluate.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/evaluate.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/evaluate.test.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const evaluate_1 = require("../evaluate");
+const ALL_METRIC_IDS = [
+    'faithfulness',
+    'answerRelevance',
+    'contextPrecision',
+    'contextRecall',
+    'contextRelevance',
+    'answerCorrectness',
+    'hallucinationRate',
+];
+const sample = {
+    question: 'What is retrieval-augmented generation?',
+    answer: 'RAG combines retrieval with generation to produce grounded answers.',
+    contexts: [
+        'Retrieval-augmented generation (RAG) is a technique that combines information retrieval with text generation to produce grounded answers.',
+        'RAG pipelines retrieve relevant documents and feed them to an LLM as context.',
+    ],
+    groundTruth: 'RAG is a method that retrieves relevant documents and uses them to generate accurate responses.',
+};
+(0, vitest_1.describe)('evaluate()', () => {
+    (0, vitest_1.it)('returns an EvalResult with the correct shape', async () => {
+        const result = await (0, evaluate_1.evaluate)(sample);
+        (0, vitest_1.expect)(result.sample).toBe(sample);
+        (0, vitest_1.expect)(typeof result.compositeScore).toBe('number');
+        (0, vitest_1.expect)(typeof result.passed).toBe('boolean');
+        (0, vitest_1.expect)(typeof result.durationMs).toBe('number');
+        (0, vitest_1.expect)(typeof result.evaluatedAt).toBe('string');
+        (0, vitest_1.expect)(result.evaluatedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+    });
+    (0, vitest_1.it)('includes all 7 metrics by default', async () => {
+        const result = await (0, evaluate_1.evaluate)(sample);
+        for (const id of ALL_METRIC_IDS) {
+            (0, vitest_1.expect)(result.metrics[id]).toBeDefined();
+            (0, vitest_1.expect)(result.metrics[id].metricId).toBe(id);
+        }
+    });
+    (0, vitest_1.it)('compositeScore is between 0 and 1', async () => {
+        const result = await (0, evaluate_1.evaluate)(sample);
+        (0, vitest_1.expect)(result.compositeScore).not.toBeNull();
+        (0, vitest_1.expect)(result.compositeScore).toBeGreaterThanOrEqual(0);
+        (0, vitest_1.expect)(result.compositeScore).toBeLessThanOrEqual(1);
+    });
+    (0, vitest_1.it)('allows selecting a subset of metrics', async () => {
+        const metrics = ['faithfulness', 'answerRelevance'];
+        const result = await (0, evaluate_1.evaluate)(sample, metrics);
+        (0, vitest_1.expect)(result.metrics['faithfulness']).toBeDefined();
+        (0, vitest_1.expect)(result.metrics['answerRelevance']).toBeDefined();
+    });
+    (0, vitest_1.it)('metrics requiring groundTruth return null score when missing', async () => {
+        const sampleWithoutGT = {
+            question: 'What is RAG?',
+            answer: 'RAG combines retrieval with generation.',
+            contexts: ['RAG is a retrieval-augmented generation technique.'],
+        };
+        const result = await (0, evaluate_1.evaluate)(sampleWithoutGT, ['contextRecall', 'answerCorrectness']);
+        (0, vitest_1.expect)(result.metrics['contextRecall'].score).toBeNull();
+        (0, vitest_1.expect)(result.metrics['answerCorrectness'].score).toBeNull();
+        (0, vitest_1.expect)(result.metrics['contextRecall'].passed).toBeNull();
+    });
+    (0, vitest_1.it)('respects threshold overrides', async () => {
+        const result = await (0, evaluate_1.evaluate)(sample, ['faithfulness'], {
+            thresholds: { faithfulness: 0.99 },
+        });
+        (0, vitest_1.expect)(result.metrics['faithfulness'].threshold).toBe(0.99);
+    });
+    (0, vitest_1.it)('cost tracker has llmCalls: 0 for heuristic mode', async () => {
+        const result = await (0, evaluate_1.evaluate)(sample);
+        (0, vitest_1.expect)(result.cost.llmCalls).toBe(0);
+    });
+});
+(0, vitest_1.describe)('evaluateBatch()', () => {
+    const samples = [
+        {
+            question: 'What is RAG?',
+            answer: 'RAG combines retrieval with generation.',
+            contexts: ['RAG is a retrieval-augmented generation technique.'],
+            groundTruth: 'RAG retrieves documents and generates answers.',
+        },
+        {
+            question: 'What is machine learning?',
+            answer: 'Machine learning trains models on data.',
+            contexts: ['Machine learning is a field of AI that trains models on data.'],
+            groundTruth: 'Machine learning trains models on data to make predictions.',
+        },
+    ];
+    (0, vitest_1.it)('returns BatchEvalResult with correct shape', async () => {
+        const result = await (0, evaluate_1.evaluateBatch)(samples);
+        (0, vitest_1.expect)(result.results).toHaveLength(2);
+        (0, vitest_1.expect)(typeof result.compositeAggregate.mean).toBe('number');
+        (0, vitest_1.expect)(typeof result.passed).toBe('boolean');
+        (0, vitest_1.expect)(typeof result.totalDurationMs).toBe('number');
+        (0, vitest_1.expect)(result.evaluatedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+    });
+    (0, vitest_1.it)('computes aggregates for all metrics', async () => {
+        const result = await (0, evaluate_1.evaluateBatch)(samples);
+        for (const id of ALL_METRIC_IDS) {
+            (0, vitest_1.expect)(result.aggregates[id]).toBeDefined();
+            (0, vitest_1.expect)(typeof result.aggregates[id].mean).toBe('number');
+            (0, vitest_1.expect)(typeof result.aggregates[id].passRate).toBe('number');
+        }
+    });
+    (0, vitest_1.it)('detects regressions when baseline is provided', async () => {
+        const baseline = await (0, evaluate_1.evaluateBatch)(samples);
+        // Create samples with less relevant contexts to produce lower scores
+        const degradedSamples = samples.map(s => ({
+            ...s,
+            answer: 'The weather is unpredictable and changes frequently.',
+            contexts: ['Unrelated context about sports and entertainment.'],
+        }));
+        const current = await (0, evaluate_1.evaluateBatch)(degradedSamples, undefined, {
+            baselineResult: baseline,
+            regressionThreshold: 0.01,
+        });
+        (0, vitest_1.expect)(current.regressions).toBeDefined();
+        (0, vitest_1.expect)(Array.isArray(current.regressions)).toBe(true);
+    });
+    (0, vitest_1.it)('respects concurrency option', async () => {
+        const manySamples = Array.from({ length: 8 }, (_, i) => ({
+            question: `Question ${i}?`,
+            answer: `Answer ${i}.`,
+            contexts: [`Context for question ${i}.`],
+        }));
+        const result = await (0, evaluate_1.evaluateBatch)(manySamples, undefined, { concurrency: 2 });
+        (0, vitest_1.expect)(result.results).toHaveLength(8);
+    });
+});
+//# sourceMappingURL=evaluate.test.js.map

package/dist/__tests__/evaluate.test.js.map

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

package/dist/__tests__/evaluator.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=evaluator.test.d.ts.map

package/dist/__tests__/evaluator.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/evaluator.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/evaluator.test.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const evaluator_1 = require("../evaluator");
+const sample = {
+    question: 'What is RAG?',
+    answer: 'RAG combines retrieval with generation to produce grounded answers.',
+    contexts: [
+        'Retrieval-augmented generation combines retrieval with generation.',
+        'RAG pipelines improve answer accuracy by grounding in retrieved documents.',
+    ],
+    groundTruth: 'RAG retrieves documents and uses them to generate accurate answers.',
+};
+(0, vitest_1.describe)('createEvaluator()', () => {
+    (0, vitest_1.it)('returns an Evaluator with evaluate, evaluateBatch, and config', () => {
+        const evaluator = (0, evaluator_1.createEvaluator)({ mode: 'heuristic' });
+        (0, vitest_1.expect)(typeof evaluator.evaluate).toBe('function');
+        (0, vitest_1.expect)(typeof evaluator.evaluateBatch).toBe('function');
+        (0, vitest_1.expect)(evaluator.config).toBeDefined();
+        (0, vitest_1.expect)(evaluator.config.mode).toBe('heuristic');
+    });
+    (0, vitest_1.it)('evaluate() returns a valid EvalResult', async () => {
+        const evaluator = (0, evaluator_1.createEvaluator)({ mode: 'heuristic' });
+        const result = await evaluator.evaluate(sample);
+        (0, vitest_1.expect)(result.sample).toBe(sample);
+        (0, vitest_1.expect)(typeof result.compositeScore).toBe('number');
+        (0, vitest_1.expect)(typeof result.passed).toBe('boolean');
+    });
+    (0, vitest_1.it)('uses default metrics from config when none specified per-call', async () => {
+        const config = {
+            mode: 'heuristic',
+            metrics: ['faithfulness', 'answerRelevance'],
+        };
+        const evaluator = (0, evaluator_1.createEvaluator)(config);
+        const result = await evaluator.evaluate(sample);
+        (0, vitest_1.expect)(result.metrics['faithfulness']).toBeDefined();
+        (0, vitest_1.expect)(result.metrics['answerRelevance']).toBeDefined();
+        // contextPrecision not in default metrics
+        (0, vitest_1.expect)(result.metrics['contextPrecision']).toBeUndefined();
+    });
+    (0, vitest_1.it)('per-call metrics override config defaults', async () => {
+        const config = {
+            mode: 'heuristic',
+            metrics: ['faithfulness'],
+        };
+        const evaluator = (0, evaluator_1.createEvaluator)(config);
+        const result = await evaluator.evaluate(sample, ['answerRelevance', 'contextPrecision']);
+        (0, vitest_1.expect)(result.metrics['answerRelevance']).toBeDefined();
+        (0, vitest_1.expect)(result.metrics['contextPrecision']).toBeDefined();
+        (0, vitest_1.expect)(result.metrics['faithfulness']).toBeUndefined();
+    });
+    (0, vitest_1.it)('per-call threshold options override config thresholds', async () => {
+        const evaluator = (0, evaluator_1.createEvaluator)({
+            mode: 'heuristic',
+            thresholds: { faithfulness: 0.5 },
+        });
+        const result = await evaluator.evaluate(sample, ['faithfulness'], {
+            thresholds: { faithfulness: 0.95 },
+        });
+        (0, vitest_1.expect)(result.metrics['faithfulness'].threshold).toBe(0.95);
+    });
+    (0, vitest_1.it)('evaluateBatch() returns a valid BatchEvalResult', async () => {
+        const evaluator = (0, evaluator_1.createEvaluator)({ mode: 'heuristic' });
+        const samples = [
+            sample,
+            {
+                question: 'What is ML?',
+                answer: 'ML trains models on data.',
+                contexts: ['Machine learning trains models on data.'],
+            },
+        ];
+        const result = await evaluator.evaluateBatch(samples);
+        (0, vitest_1.expect)(result.results).toHaveLength(2);
+        (0, vitest_1.expect)(typeof result.compositeAggregate.mean).toBe('number');
+        (0, vitest_1.expect)(typeof result.passed).toBe('boolean');
+        (0, vitest_1.expect)(result.evaluatedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+    });
+    (0, vitest_1.it)('compositeThreshold from config affects pass/fail', async () => {
+        const evaluatorHigh = (0, evaluator_1.createEvaluator)({ mode: 'heuristic', compositeThreshold: 0.99 });
+        const evaluatorLow = (0, evaluator_1.createEvaluator)({ mode: 'heuristic', compositeThreshold: 0.01 });
+        const resultHigh = await evaluatorHigh.evaluate(sample, ['faithfulness', 'answerRelevance']);
+        const resultLow = await evaluatorLow.evaluate(sample, ['faithfulness', 'answerRelevance']);
+        // Low threshold should be easier to pass
+        if (!resultLow.passed) {
+            // This can only fail if both metric scores are 0, which is unlikely for this sample
+        }
+        // At least verify shapes are correct
+        (0, vitest_1.expect)(typeof resultHigh.passed).toBe('boolean');
+        (0, vitest_1.expect)(typeof resultLow.passed).toBe('boolean');
+    });
+});
+//# sourceMappingURL=evaluator.test.js.map

package/dist/__tests__/evaluator.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.test.js","sourceRoot":"","sources":["../../src/__tests__/evaluator.test.ts"],"names":[],"mappings":";;AAAA,mCAA8C;AAC9C,4CAA+C;AAG/C,MAAM,MAAM,GAAe;IACzB,QAAQ,EAAE,cAAc;IACxB,MAAM,EAAE,qEAAqE;IAC7E,QAAQ,EAAE;QACR,oEAAoE;QACpE,4EAA4E;KAC7E;IACD,WAAW,EAAE,qEAAqE;CACnF,CAAC;AAEF,IAAA,iBAAQ,EAAC,mBAAmB,EAAE,GAAG,EAAE;IACjC,IAAA,WAAE,EAAC,+DAA+D,EAAE,GAAG,EAAE;QACvE,MAAM,SAAS,GAAG,IAAA,2BAAe,EAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;QACzD,IAAA,eAAM,EAAC,OAAO,SAAS,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACnD,IAAA,eAAM,EAAC,OAAO,SAAS,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACxD,IAAA,eAAM,EAAC,SAAS,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;QACvC,IAAA,eAAM,EAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,uCAAuC,EAAE,KAAK,IAAI,EAAE;QACrD,MAAM,SAAS,GAAG,IAAA,2BAAe,EAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;QACzD,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAChD,IAAA,eAAM,EAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACnC,IAAA,eAAM,EAAC,OAAO,MAAM,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACpD,IAAA,eAAM,EAAC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,+DAA+D,EAAE,KAAK,IAAI,EAAE;QAC7E,MAAM,MAAM,GAAoB;YAC9B,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,CAAC,cAAc,EAAE,iBAAiB,CAAC;SAC7C,CAAC;QACF,MAAM,SAAS,GAAG,IAAA,2BAAe,EAAC,MAAM,CAAC,CAAC;QAC1C,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAChD,IAAA,eAAM,EAAC,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QACrD,IAAA,eAAM,EAAC,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QACxD,0CAA0C;QAC1C,IAAA,eAAM,EAAC,MAAM,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC;IAC7D,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,2CAA2C,EAAE,KAAK,IAAI,EAAE;QACzD,MAAM,MAAM,GAAoB;YAC9B,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,CAAC,cAAc,CAAC;SAC1B,CAAC;QACF,MAAM,SAAS,GAAG,IAAA,2BAAe,EAAC,MAAM,CAAC,CAAC;QAC1C,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,iBAAiB,EAAE,kBAAkB,CAAC,CAAC,CAAC;QACzF,IAAA,eAAM,EAAC,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QACxD,IAAA,eAAM,EAAC,MAAM,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QACzD,IAAA,eAAM,EAAC,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,uDAAuD,EAAE,KAAK,IAAI,EAAE;QACrE,MAAM,SAAS,GAAG,IAAA,2BAAe,EAAC;YAChC,IAAI,EAAE,WAAW;YACjB,UAAU,EAAE,EAAE,YAAY,EAAE,GAAG,EAAE;SAClC,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,cAAc,CAAC,EAAE;YAChE,UAAU,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;SACnC,CAAC,CAAC;QACH,IAAA,eAAM,EAAC,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9D,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,iDAAiD,EAAE,KAAK,IAAI,EAAE;QAC/D,MAAM,SAAS,GAAG,IAAA,2BAAe,EAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;QACzD,MAAM,OAAO,GAAiB;YAC5B,MAAM;YACN;gBACE,QAAQ,EAAE,aAAa;gBACvB,MAAM,EAAE,2BAA2B;gBACnC,QAAQ,EAAE,CAAC,yCAAyC,CAAC;aACtD;SACF,CAAC;QACF,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QACtD,IAAA,eAAM,EAAC,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACvC,IAAA,eAAM,EAAC,OAAO,MAAM,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC7D,IAAA,eAAM,EAAC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC7C,IAAA,eAAM,EAAC,MAAM,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,kDAAkD,EAAE,KAAK,IAAI,EAAE;QAChE,MAAM,aAAa,GAAG,IAAA,2BAAe,EAAC,EAAE,IAAI,EAAE,WAAW,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC,CAAC;QACvF,MAAM,YAAY,GAAG,IAAA,2BAAe,EAAC,EAAE,IAAI,EAAE,WAAW,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC,CAAC;QAEtF,MAAM,UAAU,GAAG,MAAM,aAAa,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,cAAc,EAAE,iBAAiB,CAAC,CAAC,CAAC;QAC7F,MAAM,SAAS,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,cAAc,EAAE,iBAAiB,CAAC,CAAC,CAAC;QAE3F,yCAAyC;QACzC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;YACtB,oFAAoF;QACtF,CAAC;QACD,qCAAqC;QACrC,IAAA,eAAM,EAAC,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACjD,IAAA,eAAM,EAAC,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/heuristic/ngrams.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ngrams.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ngrams.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/heuristic/ngrams.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/heuristic/ngrams.test.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const ngrams_1 = require("../../heuristic/ngrams");
+(0, vitest_1.describe)('tokenize', () => {
+    (0, vitest_1.it)('lowercases and splits on whitespace and punctuation', () => {
+        const tokens = (0, ngrams_1.tokenize)('Hello, World! This is a test.');
+        (0, vitest_1.expect)(tokens).toContain('hello');
+        (0, vitest_1.expect)(tokens).toContain('world');
+        (0, vitest_1.expect)(tokens).toContain('this');
+        (0, vitest_1.expect)(tokens).toContain('is');
+        (0, vitest_1.expect)(tokens).toContain('a');
+        (0, vitest_1.expect)(tokens).toContain('test');
+        // punctuation stripped
+        (0, vitest_1.expect)(tokens).not.toContain(',');
+        (0, vitest_1.expect)(tokens).not.toContain('!');
+        (0, vitest_1.expect)(tokens).not.toContain('.');
+    });
+    (0, vitest_1.it)('filters empty tokens', () => {
+        const tokens = (0, ngrams_1.tokenize)('  hello   world  ');
+        (0, vitest_1.expect)(tokens.every(t => t.length > 0)).toBe(true);
+    });
+    (0, vitest_1.it)('returns empty array for empty string', () => {
+        (0, vitest_1.expect)((0, ngrams_1.tokenize)('')).toEqual([]);
+    });
+});
+(0, vitest_1.describe)('getNgrams', () => {
+    (0, vitest_1.it)('returns unigrams for n=1', () => {
+        const tokens = ['a', 'b', 'c'];
+        (0, vitest_1.expect)((0, ngrams_1.getNgrams)(tokens, 1)).toEqual(['a', 'b', 'c']);
+    });
+    (0, vitest_1.it)('returns bigrams for n=2', () => {
+        const tokens = ['a', 'b', 'c'];
+        (0, vitest_1.expect)((0, ngrams_1.getNgrams)(tokens, 2)).toEqual(['a b', 'b c']);
+    });
+    (0, vitest_1.it)('returns empty for tokens shorter than n', () => {
+        (0, vitest_1.expect)((0, ngrams_1.getNgrams)(['a'], 2)).toEqual([]);
+    });
+    (0, vitest_1.it)('returns empty for empty tokens', () => {
+        (0, vitest_1.expect)((0, ngrams_1.getNgrams)([], 1)).toEqual([]);
+    });
+});
+(0, vitest_1.describe)('ngramOverlap', () => {
+    (0, vitest_1.it)('returns 1.0 for identical strings', () => {
+        (0, vitest_1.expect)((0, ngrams_1.ngramOverlap)('the cat sat on the mat', 'the cat sat on the mat')).toBeCloseTo(1.0);
+    });
+    (0, vitest_1.it)('returns 0.0 for completely disjoint strings', () => {
+        (0, vitest_1.expect)((0, ngrams_1.ngramOverlap)('alpha beta gamma', 'delta epsilon zeta')).toBeCloseTo(0.0);
+    });
+    (0, vitest_1.it)('returns approximately 0.5 for 50% token overlap', () => {
+        // "a b" vs "a c" — intersection={a}, union={a,b,c} → 1/3
+        // "a b c" vs "a b d" — intersection={a,b}, union={a,b,c,d} → 2/4 = 0.5
+        const overlap = (0, ngrams_1.ngramOverlap)('a b c', 'a b d');
+        (0, vitest_1.expect)(overlap).toBeCloseTo(0.5, 1);
+    });
+    (0, vitest_1.it)('returns 1.0 for both empty strings', () => {
+        (0, vitest_1.expect)((0, ngrams_1.ngramOverlap)('', '')).toBe(1.0);
+    });
+    (0, vitest_1.it)('returns 0.0 when one string is empty', () => {
+        (0, vitest_1.expect)((0, ngrams_1.ngramOverlap)('hello world', '')).toBe(0.0);
+        (0, vitest_1.expect)((0, ngrams_1.ngramOverlap)('', 'hello world')).toBe(0.0);
+    });
+    (0, vitest_1.it)('supports bigram overlap', () => {
+        const overlap = (0, ngrams_1.ngramOverlap)('the quick brown fox', 'the quick red fox', 2);
+        // bigrams a: {the quick, quick brown, brown fox}
+        // bigrams b: {the quick, quick red, red fox}
+        // intersection: {the quick} = 1, union = 5
+        (0, vitest_1.expect)(overlap).toBeCloseTo(1 / 5, 3);
+    });
+});
+(0, vitest_1.describe)('weightedNgramOverlap', () => {
+    (0, vitest_1.it)('returns 1.0 for identical strings', () => {
+        (0, vitest_1.expect)((0, ngrams_1.weightedNgramOverlap)('hello world test', 'hello world test')).toBeCloseTo(1.0);
+    });
+    (0, vitest_1.it)('returns 0.0 for completely disjoint strings', () => {
+        (0, vitest_1.expect)((0, ngrams_1.weightedNgramOverlap)('alpha beta', 'gamma delta')).toBeCloseTo(0.0);
+    });
+    (0, vitest_1.it)('returns value between 0 and 1 for partial overlap', () => {
+        const score = (0, ngrams_1.weightedNgramOverlap)('the cat sat', 'the cat ran');
+        (0, vitest_1.expect)(score).toBeGreaterThan(0);
+        (0, vitest_1.expect)(score).toBeLessThan(1);
+    });
+    (0, vitest_1.it)('uses custom ngramSizes and weights', () => {
+        const score = (0, ngrams_1.weightedNgramOverlap)('a b c', 'a b d', [1], [1.0]);
+        // unigram: intersection={a,b}, union={a,b,c,d} = 2/4 = 0.5
+        (0, vitest_1.expect)(score).toBeCloseTo(0.5, 1);
+    });
+});
+//# sourceMappingURL=ngrams.test.js.map

package/dist/__tests__/heuristic/ngrams.test.js.map

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

package/dist/__tests__/heuristic/tfidf.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tfidf.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tfidf.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/heuristic/tfidf.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/heuristic/tfidf.test.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const tfidf_1 = require("../../heuristic/tfidf");
+(0, vitest_1.describe)('tfidfSimilarity', () => {
+    (0, vitest_1.it)('returns a high score for identical texts', () => {
+        const text = 'the quick brown fox jumps over the lazy dog';
+        const score = (0, tfidf_1.tfidfSimilarity)(text, text);
+        (0, vitest_1.expect)(score).toBeGreaterThan(0.9);
+    });
+    (0, vitest_1.it)('returns a low score for unrelated texts', () => {
+        const score = (0, tfidf_1.tfidfSimilarity)('quantum physics relativity wave particle', 'cooking recipes pasta sauce garlic');
+        (0, vitest_1.expect)(score).toBeLessThan(0.2);
+    });
+    (0, vitest_1.it)('returns a value in [0,1]', () => {
+        const score = (0, tfidf_1.tfidfSimilarity)('hello world', 'world peace');
+        (0, vitest_1.expect)(score).toBeGreaterThanOrEqual(0);
+        (0, vitest_1.expect)(score).toBeLessThanOrEqual(1);
+    });
+    (0, vitest_1.it)('returns 0 for empty query', () => {
+        const score = (0, tfidf_1.tfidfSimilarity)('', 'some document text');
+        (0, vitest_1.expect)(score).toBe(0);
+    });
+    (0, vitest_1.it)('returns higher similarity for related texts than unrelated', () => {
+        const query = 'retrieval augmented generation RAG pipeline';
+        const related = 'RAG combines retrieval with generation for grounded answers';
+        const unrelated = 'the weather is sunny today';
+        (0, vitest_1.expect)((0, tfidf_1.tfidfSimilarity)(query, related)).toBeGreaterThan((0, tfidf_1.tfidfSimilarity)(query, unrelated));
+    });
+});
+(0, vitest_1.describe)('cosineSimilarity', () => {
+    (0, vitest_1.it)('returns 1.0 for identical vectors', () => {
+        const vec = new Map([['a', 0.5], ['b', 0.3]]);
+        (0, vitest_1.expect)((0, tfidf_1.cosineSimilarity)(vec, vec)).toBeCloseTo(1.0);
+    });
+    (0, vitest_1.it)('returns 0.0 for orthogonal vectors', () => {
+        const a = new Map([['x', 1.0]]);
+        const b = new Map([['y', 1.0]]);
+        (0, vitest_1.expect)((0, tfidf_1.cosineSimilarity)(a, b)).toBe(0);
+    });
+    (0, vitest_1.it)('returns 0.0 for empty vectors', () => {
+        (0, vitest_1.expect)((0, tfidf_1.cosineSimilarity)(new Map(), new Map())).toBe(0);
+    });
+});
+(0, vitest_1.describe)('buildTfIdfVectors', () => {
+    (0, vitest_1.it)('builds query and document vectors with correct structure', () => {
+        const { queryVec, docVecs } = (0, tfidf_1.buildTfIdfVectors)('hello world', ['hello there', 'another doc']);
+        (0, vitest_1.expect)(queryVec instanceof Map).toBe(true);
+        (0, vitest_1.expect)(docVecs).toHaveLength(2);
+        (0, vitest_1.expect)(docVecs[0] instanceof Map).toBe(true);
+    });
+    (0, vitest_1.it)('assigns non-zero weight to terms in query', () => {
+        const { queryVec } = (0, tfidf_1.buildTfIdfVectors)('hello world', ['unrelated content']);
+        (0, vitest_1.expect)(queryVec.size).toBeGreaterThan(0);
+    });
+});
+//# sourceMappingURL=tfidf.test.js.map

package/dist/__tests__/heuristic/tfidf.test.js.map

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