truthguard-ai 0.2.0 → 0.3.0

package/dist-npm/Matchers/index.js

@@ -0,0 +1,690 @@
+"use strict";
+/**
+ * Matchers
+ *
+ * Matching strategies for comparing extracted claim values against
+ * values found in tool outputs.
+ *
+ * V1 supports:
+ *   - NumericMatcher   (relative tolerance)
+ *   - CountMatcher     (exact match)
+ *   - DateMatcher      (exact ISO-8601 match)
+ *   - NameMatcher      (fuzzy / Jaro-Winkler-like similarity)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchNumeric = matchNumeric;
+exports.normaliseUnit = normaliseUnit;
+exports.tryUnitConversion = tryUnitConversion;
+exports.matchNumericWithUnits = matchNumericWithUnits;
+exports.isTransposedDigits = isTransposedDigits;
+exports.matchCount = matchCount;
+exports.matchDate = matchDate;
+exports.jaroSimilarity = jaroSimilarity;
+exports.jaroWinklerSimilarity = jaroWinklerSimilarity;
+exports.matchName = matchName;
+exports.extractValuesFromOutput = extractValuesFromOutput;
+exports.extractValuesWithKeys = extractValuesWithKeys;
+exports.inferUnitFromFieldName = inferUnitFromFieldName;
+exports.extractCountFromOutput = extractCountFromOutput;
+const Claims_1 = require("../Claims");
+// ---------------------------------------------------------------------------
+// Numeric matcher
+// ---------------------------------------------------------------------------
+/**
+ * Compare two numeric values using a configurable relative tolerance.
+ */
+function matchNumeric(claimed, source, tolerances) {
+    if (source === 0 && claimed === 0) {
+        return { matched: true, deviation: 0, explanation: 'Both values are 0.' };
+    }
+    if (source === 0) {
+        // Source is 0 but claim is non-zero → definite mismatch
+        return {
+            matched: false,
+            deviation: 1,
+            explanation: `Source is 0 but claim is ${claimed}.`,
+        };
+    }
+    const relDev = Math.abs(claimed - source) / Math.abs(source);
+    const tol = tolerances.numericRelativeTolerance;
+    const matched = relDev <= tol;
+    return {
+        matched,
+        deviation: relDev,
+        explanation: matched
+            ? `${claimed} is within ${(tol * 100).toFixed(0)}% of ${source} (deviation: ${(relDev * 100).toFixed(2)}%).`
+            : `${claimed} deviates ${(relDev * 100).toFixed(2)}% from ${source} (tolerance: ${(tol * 100).toFixed(0)}%).`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Unit conversion table
+// ---------------------------------------------------------------------------
+/**
+ * Conversion factors between common units.
+ * Key format: "fromUnit→toUnit", value: multiply source by this to get target unit.
+ */
+const UNIT_CONVERSIONS = {
+    'minutes→hours': 1 / 60,
+    'hours→minutes': 60,
+    'seconds→minutes': 1 / 60,
+    'minutes→seconds': 60,
+    'seconds→hours': 1 / 3600,
+    'hours→seconds': 3600,
+    'days→hours': 24,
+    'hours→days': 1 / 24,
+    'days→minutes': 1440,
+    'minutes→days': 1 / 1440,
+    'weeks→days': 7,
+    'days→weeks': 1 / 7,
+    'months→days': 30,
+    'days→months': 1 / 30,
+    'years→days': 365,
+    'days→years': 1 / 365,
+    'years→months': 12,
+    'months→years': 1 / 12,
+    'km→meters': 1000,
+    'meters→km': 1 / 1000,
+    'km→miles': 0.621371,
+    'miles→km': 1.60934,
+    'kg→lbs': 2.20462,
+    'lbs→kg': 0.453592,
+    'bytes→kb': 1 / 1024,
+    'kb→bytes': 1024,
+    'kb→mb': 1 / 1024,
+    'mb→kb': 1024,
+    'mb→gb': 1 / 1024,
+    'gb→mb': 1024,
+};
+/**
+ * Canonical unit aliases — maps alternative forms to UnitType canonical values.
+ * Covers 11 languages: EN, ES, FR, PT, SR, RU, HI, AR, BN, ZH, JA.
+ */
+const UNIT_ALIASES = {
+    // ── English ──
+    minute: 'minutes', mins: 'minutes', min: 'minutes',
+    hour: 'hours', hrs: 'hours', hr: 'hours', h: 'hours',
+    second: 'seconds', secs: 'seconds', sec: 'seconds', s: 'seconds',
+    day: 'days', d: 'days',
+    week: 'weeks', wk: 'weeks', wks: 'weeks',
+    month: 'months', mo: 'months', mos: 'months',
+    year: 'years', yr: 'years', yrs: 'years',
+    kilometer: 'km', kilometers: 'km', kilometre: 'km', kilometres: 'km',
+    meter: 'meters', metre: 'meters', metres: 'meters',
+    mile: 'miles', mi: 'miles',
+    kilogram: 'kg', kilograms: 'kg',
+    pound: 'lbs', pounds: 'lbs', lb: 'lbs',
+    byte: 'bytes',
+    kilobyte: 'kb', kilobytes: 'kb',
+    megabyte: 'mb', megabytes: 'mb',
+    gigabyte: 'gb', gigabytes: 'gb',
+    percent: 'percent', percentage: 'percent',
+    degree: 'degrees',
+    // ── Spanish (es) ──
+    segundo: 'seconds', segundos: 'seconds',
+    minuto: 'minutes', minutos: 'minutes',
+    hora: 'hours', horas: 'hours',
+    'día': 'days', dia: 'days', 'días': 'days', dias: 'days',
+    semana: 'weeks', semanas: 'weeks',
+    mes: 'months', meses: 'months',
+    'año': 'years', 'años': 'years',
+    porcentaje: 'percent',
+    grado: 'degrees', grados: 'degrees',
+    // ── French (fr) ──
+    seconde: 'seconds', secondes: 'seconds',
+    heure: 'hours', heures: 'hours',
+    jour: 'days', jours: 'days',
+    semaine: 'weeks', semaines: 'weeks',
+    mois: 'months',
+    an: 'years', ans: 'years', 'année': 'years', 'années': 'years',
+    pourcent: 'percent', pourcentage: 'percent',
+    'degré': 'degrees', 'degrés': 'degrees',
+    // ── Portuguese (pt) ──
+    'mês': 'months',
+    ano: 'years', anos: 'years',
+    porcentagem: 'percent', porcento: 'percent',
+    grau: 'degrees', graus: 'degrees',
+    // ── Serbian (sr) ──
+    sekunda: 'seconds', sekundi: 'seconds', sekunde: 'seconds',
+    minut: 'minutes', minuta: 'minutes', minuti: 'minutes',
+    sat: 'hours', sati: 'hours',
+    dan: 'days', dana: 'days', dani: 'days',
+    nedelja: 'weeks', nedelje: 'weeks', sedmica: 'weeks', sedmice: 'weeks',
+    mesec: 'months', meseci: 'months', meseca: 'months',
+    godina: 'years', godine: 'years',
+    procenat: 'percent', procenata: 'percent', posto: 'percent',
+    stepen: 'degrees', stepeni: 'degrees', stepena: 'degrees',
+    // ── Russian (ru) ──
+    'секунда': 'seconds', 'секунды': 'seconds', 'секунд': 'seconds',
+    'минута': 'minutes', 'минуты': 'minutes', 'минут': 'minutes',
+    'час': 'hours', 'часа': 'hours', 'часов': 'hours',
+    'день': 'days', 'дня': 'days', 'дней': 'days',
+    'неделя': 'weeks', 'недели': 'weeks', 'недель': 'weeks',
+    'месяц': 'months', 'месяца': 'months', 'месяцев': 'months',
+    'год': 'years', 'года': 'years', 'лет': 'years',
+    'процент': 'percent', 'процентов': 'percent', 'процента': 'percent',
+    'градус': 'degrees', 'градуса': 'degrees', 'градусов': 'degrees',
+    // ── Hindi (hi) ──
+    'सेकंड': 'seconds',
+    'मिनट': 'minutes',
+    'घंटा': 'hours', 'घंटे': 'hours', 'घंटों': 'hours',
+    'दिन': 'days', 'दिनों': 'days',
+    'हफ्ता': 'weeks', 'हफ्ते': 'weeks', 'हफ्तों': 'weeks', 'सप्ताह': 'weeks',
+    'महीना': 'months', 'महीने': 'months', 'महीनों': 'months',
+    'साल': 'years', 'वर्ष': 'years',
+    'प्रतिशत': 'percent', 'डिग्री': 'degrees',
+    // ── Arabic (ar) ──
+    'ثانية': 'seconds', 'ثوان': 'seconds', 'ثواني': 'seconds',
+    'دقيقة': 'minutes', 'دقائق': 'minutes',
+    'ساعة': 'hours', 'ساعات': 'hours',
+    'يوم': 'days', 'أيام': 'days',
+    'أسبوع': 'weeks', 'أسابيع': 'weeks',
+    'شهر': 'months', 'أشهر': 'months', 'شهور': 'months',
+    'سنة': 'years', 'سنوات': 'years',
+    'بالمئة': 'percent', 'نسبة': 'percent',
+    'درجة': 'degrees', 'درجات': 'degrees',
+    // ── Bengali (bn) ──
+    'সেকেন্ড': 'seconds', 'মিনিট': 'minutes', 'ঘণ্টা': 'hours',
+    'দিন': 'days', 'সপ্তাহ': 'weeks', 'মাস': 'months', 'বছর': 'years',
+    'শতাংশ': 'percent', 'ডিগ্রি': 'degrees',
+    // ── Mandarin Chinese (zh) ──
+    '秒': 'seconds', '分钟': 'minutes', '小时': 'hours',
+    '天': 'days', '日': 'days',
+    '周': 'weeks', '星期': 'weeks',
+    '个月': 'months', '月': 'months', '年': 'years',
+    '百分比': 'percent', '度': 'degrees',
+    // ── Japanese (ja) ──
+    '時間': 'hours', '分': 'minutes',
+    '週間': 'weeks', '週': 'weeks',
+    'ヶ月': 'months', 'か月': 'months',
+    'パーセント': 'percent',
+    // ── Currency symbols / codes ──
+    '$': 'usd', 'usd': 'usd', 'dollar': 'usd', 'dollars': 'usd',
+    '€': 'eur', 'eur': 'eur', 'euro': 'eur', 'euros': 'eur', 'evro': 'eur', 'evra': 'eur',
+    '£': 'gbp', 'gbp': 'gbp', 'funta': 'gbp', 'funti': 'gbp',
+    'rsd': 'rsd', 'din': 'rsd', 'dinara': 'rsd', 'dinar': 'rsd', 'dinari': 'rsd',
+    'chf': 'chf', 'franc': 'chf', 'francs': 'chf', 'franak': 'chf', 'franaka': 'chf',
+    'jpy': 'jpy', 'yen': 'jpy', '円': 'jpy', '¥': 'jpy',
+    'cny': 'cny', 'yuan': 'cny', '元': 'cny',
+    'rub': 'rub', 'ruble': 'rub', 'rubles': 'rub', 'рубль': 'rub', 'рублей': 'rub', 'рубля': 'rub',
+    'inr': 'inr', 'rupee': 'inr', 'rupees': 'inr', 'रुपये': 'inr', 'रुपया': 'inr',
+    'brl': 'brl', 'real': 'brl', 'reais': 'brl',
+};
+/** Normalise a unit string to its canonical form. */
+function normaliseUnit(raw) {
+    const lower = raw.toLowerCase().trim();
+    return UNIT_ALIASES[lower] ?? lower;
+}
+/**
+ * Try to convert `sourceValue` (in `sourceUnit`) to `claimUnit`.
+ * Returns the converted value, or null if no conversion path exists.
+ */
+function tryUnitConversion(sourceValue, sourceUnit, claimUnit) {
+    const from = normaliseUnit(sourceUnit);
+    const to = normaliseUnit(claimUnit);
+    if (from === to)
+        return sourceValue;
+    const key = `${from}→${to}`;
+    const factor = UNIT_CONVERSIONS[key];
+    if (factor !== undefined) {
+        return sourceValue * factor;
+    }
+    return null;
+}
+/**
+ * Compare two numbers with optional unit conversion.
+ * If units differ, attempts conversion before comparing.
+ *
+ * Special handling for percentages:
+ * - If claim is "45 percent" and source is 0.45 (or vice versa),
+ *   normalises both to the same scale before comparing.
+ */
+function matchNumericWithUnits(claimed, claimUnit, source, sourceUnit, tolerances) {
+    // Direct match first
+    const direct = matchNumeric(claimed, source, tolerances);
+    if (direct.matched)
+        return direct;
+    // Percentage normalisation: 0.45 ↔ 45%
+    // If claim unit is percent and source is a fraction (0–1 exclusive), scale source ×100.
+    // If source unit is percent and claimed is a fraction, scale claimed ×100.
+    const normClaim = claimUnit ? normaliseUnit(claimUnit) : undefined;
+    const normSource = sourceUnit ? normaliseUnit(sourceUnit) : undefined;
+    if (normClaim === 'percent' && !normSource) {
+        // Claim says "45%" and source is a decimal fraction like 0.45
+        if (source > 0 && source < 1 && claimed >= 1 && claimed <= 100) {
+            const scaled = matchNumeric(claimed, source * 100, tolerances);
+            if (scaled.matched) {
+                return {
+                    ...scaled,
+                    explanation: `${claimed}% matches source ${source} (interpreted as ${source * 100}%, deviation: ${((scaled.deviation ?? 0) * 100).toFixed(2)}%).`,
+                };
+            }
+        }
+        // Claim says "0.45%" (fraction-as-percent) and source is 45
+        if (claimed > 0 && claimed < 1 && source >= 1 && source <= 100) {
+            const scaled = matchNumeric(claimed * 100, source, tolerances);
+            if (scaled.matched) {
+                return {
+                    ...scaled,
+                    explanation: `${claimed}% (=${claimed * 100}%) matches source ${source} (deviation: ${((scaled.deviation ?? 0) * 100).toFixed(2)}%).`,
+                };
+            }
+        }
+    }
+    if (!normClaim && normSource === 'percent') {
+        // Source is "45%" and claim is 0.45 fraction
+        if (claimed > 0 && claimed < 1 && source >= 1 && source <= 100) {
+            const scaled = matchNumeric(claimed * 100, source, tolerances);
+            if (scaled.matched) {
+                return {
+                    ...scaled,
+                    explanation: `Claimed ${claimed} matches source ${source}% (normalised to ${claimed * 100}%, deviation: ${((scaled.deviation ?? 0) * 100).toFixed(2)}%).`,
+                };
+            }
+        }
+    }
+    // If both units are known and different, try conversion
+    if (claimUnit && sourceUnit) {
+        const converted = tryUnitConversion(source, sourceUnit, claimUnit);
+        if (converted !== null) {
+            const result = matchNumeric(claimed, converted, tolerances);
+            return {
+                ...result,
+                explanation: result.matched
+                    ? `${claimed} ${claimUnit} matches ${source} ${sourceUnit} after unit conversion (=${converted.toFixed(2)} ${claimUnit}, deviation: ${((result.deviation ?? 0) * 100).toFixed(2)}%).`
+                    : `${claimed} ${claimUnit} does not match ${source} ${sourceUnit} even after conversion (=${converted.toFixed(2)} ${claimUnit}, deviation: ${((result.deviation ?? 0) * 100).toFixed(2)}%).`,
+            };
+        }
+    }
+    return direct;
+}
+// ---------------------------------------------------------------------------
+// Transposed digits detection
+// ---------------------------------------------------------------------------
+/**
+ * Check if two numbers differ only by a digit transposition.
+ * E.g. 23 vs 32, 1234 vs 1243, 156 vs 165.
+ * Returns true if swapping exactly one pair of adjacent digits in `claimed`
+ * produces `source`.
+ */
+function isTransposedDigits(claimed, source) {
+    if (claimed === source)
+        return false;
+    // Only for positive integers
+    if (!Number.isInteger(claimed) || !Number.isInteger(source))
+        return false;
+    if (claimed < 0 || source < 0)
+        return false;
+    const a = String(claimed);
+    const b = String(source);
+    if (a.length !== b.length)
+        return false;
+    if (a.length < 2)
+        return false;
+    // Try swapping each adjacent pair in `a` and check against `b`
+    for (let i = 0; i < a.length - 1; i++) {
+        if (a[i] === a[i + 1])
+            continue; // swapping identical digits is no-op
+        const swapped = a.slice(0, i) + a[i + 1] + a[i] + a.slice(i + 2);
+        if (swapped === b)
+            return true;
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Count matcher
+// ---------------------------------------------------------------------------
+/**
+ * Compare two count values (exact or within 1 for approximate matches).
+ *
+ * Deviation is returned as a **relative** fraction (same scale as numeric matcher)
+ * so that downstream rules (e.g. data_ignored) can apply a uniform threshold.
+ *   matched counts → deviation 0
+ *   mismatched     → |claimed - source| / max(|source|, 1)
+ */
+function matchCount(claimed, source, tolerances) {
+    const relDev = source === 0 && claimed === 0
+        ? 0
+        : Math.abs(claimed - source) / Math.max(Math.abs(source), 1);
+    if (tolerances.countExactMatch) {
+        const matched = claimed === source;
+        return {
+            matched,
+            deviation: relDev,
+            explanation: matched
+                ? `Count ${claimed} exactly matches ${source}.`
+                : `Count ${claimed} does not match ${source} (exact match required).`,
+        };
+    }
+    // Non-exact: treat as numeric with 0% tolerance (effectively same as exact)
+    return {
+        matched: claimed === source,
+        deviation: relDev,
+        explanation: claimed === source
+            ? `Count ${claimed} matches ${source}.`
+            : `Count ${claimed} differs from ${source} by ${Math.abs(claimed - source)}.`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Date matcher
+// ---------------------------------------------------------------------------
+/**
+ * Compare two ISO-8601 date strings (YYYY-MM-DD).
+ * Normalises both values before comparison.
+ */
+function matchDate(claimed, source, _tolerances) {
+    const normClaimed = claimed.trim().substring(0, 10);
+    const normSource = source.trim().substring(0, 10);
+    // Partial date support: if claimed has year 0000 (no year specified,
+    // e.g. European short "15.3." → "0000-03-15"), match only month-day.
+    let matched;
+    if (normClaimed.startsWith('0000-') && /^\d{4}-\d{2}-\d{2}$/.test(normSource)) {
+        matched = normClaimed.substring(5) === normSource.substring(5);
+    }
+    else {
+        matched = normClaimed === normSource;
+    }
+    // Fallback 1: if source is longer than a date string, search for the
+    // claimed ISO date as a substring within it (handles dates embedded in prose).
+    if (!matched && source.length > 10 && /^\d{4}-\d{2}-\d{2}$/.test(normClaimed)) {
+        if (source.includes(normClaimed)) {
+            matched = true;
+        }
+        else {
+            // Also search for European DD.MM.YYYY format within source
+            const [y, m, d] = normClaimed.split('-');
+            if (source.includes(`${d}.${m}.${y}`) || source.includes(`${parseInt(d)}.${parseInt(m)}.${y}`)) {
+                matched = true;
+            }
+        }
+    }
+    // Fallback 2: parse the source through tryParseDate to normalise
+    // different date formats (e.g. "01.03.2026" → "2026-03-01").
+    if (!matched && !matched && source.trim().length > 0 && source.trim().length <= 30) {
+        const parsed = (0, Claims_1.tryParseDate)(source.trim());
+        if (parsed) {
+            const normParsed = parsed.substring(0, 10);
+            if (normClaimed.startsWith('0000-') && /^\d{4}-\d{2}-\d{2}$/.test(normParsed)) {
+                matched = normClaimed.substring(5) === normParsed.substring(5);
+            }
+            else {
+                matched = normClaimed === normParsed;
+            }
+        }
+    }
+    return {
+        matched,
+        explanation: matched
+            ? `Date "${claimed}" matches "${source}".`
+            : `Date "${claimed}" does not match "${source}".`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Name / fuzzy matcher  (Jaro-Winkler inspired)
+// ---------------------------------------------------------------------------
+/**
+ * Compute Jaro similarity between two strings.
+ * Returns a value in [0, 1].
+ */
+function jaroSimilarity(s1, s2) {
+    if (s1 === s2)
+        return 1.0;
+    const len1 = s1.length;
+    const len2 = s2.length;
+    if (len1 === 0 || len2 === 0)
+        return 0.0;
+    const matchDist = Math.floor(Math.max(len1, len2) / 2) - 1;
+    const s1Matches = new Array(len1).fill(false);
+    const s2Matches = new Array(len2).fill(false);
+    let matches = 0;
+    let transpositions = 0;
+    for (let i = 0; i < len1; i++) {
+        const start = Math.max(0, i - matchDist);
+        const end = Math.min(i + matchDist + 1, len2);
+        for (let j = start; j < end; j++) {
+            if (s2Matches[j] || s1[i] !== s2[j])
+                continue;
+            s1Matches[i] = true;
+            s2Matches[j] = true;
+            matches++;
+            break;
+        }
+    }
+    if (matches === 0)
+        return 0.0;
+    let k = 0;
+    for (let i = 0; i < len1; i++) {
+        if (!s1Matches[i])
+            continue;
+        while (!s2Matches[k])
+            k++;
+        if (s1[i] !== s2[k])
+            transpositions++;
+        k++;
+    }
+    return ((matches / len1 + matches / len2 + (matches - transpositions / 2) / matches) / 3);
+}
+/**
+ * Compute Jaro-Winkler similarity (boosts prefix matches).
+ */
+function jaroWinklerSimilarity(s1, s2, prefixScale = 0.1) {
+    const jaro = jaroSimilarity(s1, s2);
+    let prefixLen = 0;
+    const maxPrefix = Math.min(4, Math.min(s1.length, s2.length));
+    while (prefixLen < maxPrefix && s1[prefixLen] === s2[prefixLen])
+        prefixLen++;
+    return jaro + prefixLen * prefixScale * (1 - jaro);
+}
+/**
+ * Fuzzy-match two name strings using Jaro-Winkler similarity.
+ * Case-insensitive.
+ */
+/**
+ * Strip diacritics / combining marks so that "Jović" → "Jovic",
+ * "č" → "c", etc.  Uses Unicode NFD normalization.
+ */
+function stripDiacritics(s) {
+    // NFD decomposes most diacritics (ć, č, š, ž) into base + combining mark,
+    // but đ (U+0111) and Đ (U+0110) are atomic codepoints — handle them explicitly.
+    return s.replace(/đ/g, 'd').replace(/Đ/g, 'D').normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+}
+function matchName(claimed, source, tolerances) {
+    const a = stripDiacritics(claimed.trim().toLowerCase());
+    const b = stripDiacritics(source.trim().toLowerCase());
+    if (a === b) {
+        return {
+            matched: true,
+            similarity: 1.0,
+            explanation: `"${claimed}" exactly matches "${source}".`,
+        };
+    }
+    const sim = jaroWinklerSimilarity(a, b);
+    const threshold = tolerances.nameSimilarityThreshold;
+    // Token-level matching for multi-token names (first + last).
+    // For multi-word names, full-string Jaro-Winkler is unreliable because
+    // Serbian surnames share suffixes (-ović, -ić) which inflate similarity:
+    //   "Boban Stojković" vs "Boban Đokić" = 0.91 (different person!)
+    //   "Miloš Tasić" vs "Slađana Tasić" = ~1.0 (same surname, different person!)
+    // So for multi-token names we ALWAYS use per-token matching.
+    const claimedTokens = stripDiacritics(claimed.trim().toLowerCase()).split(/\s+/).filter((t) => t.length >= 3);
+    const sourceTokens = stripDiacritics(source.trim().toLowerCase()).split(/\s+/).filter((t) => t.length >= 3);
+    const isMultiToken = claimedTokens.length >= 2 && sourceTokens.length >= 2;
+    // For single-token names, use full-string similarity
+    if (!isMultiToken && sim >= threshold) {
+        return {
+            matched: true,
+            similarity: sim,
+            explanation: `"${claimed}" is similar to "${source}" (similarity: ${sim.toFixed(3)} ≥ ${threshold}).`,
+        };
+    }
+    // Token-level matching: each significant token (≥3 chars) from the claimed
+    // name must match a token in the source name.
+    // Handles cases like "Zdravo Slavica" vs "Slavica Stojanović" where a
+    // greeting word dilutes the full-string similarity.
+    // Use a stricter threshold because Jaro-Winkler inflates scores on short
+    // strings (e.g. "markovic" ≈ "rajkovic" = 0.87 is a false match).
+    const tokenThreshold = Math.max(threshold, 0.92);
+    // For multi-token names (first + last), require BOTH tokens to match a
+    // DIFFERENT source token each.  A single-token match (e.g. "Tasić" matching
+    // "Slađana Tasić" when claimed is "Miloš Tasić") produces false positives —
+    // different people share surnames.
+    //
+    // However, if the claimed text contains a non-name token (greeting, common
+    // word) that merely accompanies a real name (e.g. "Zdravo Slavica"), we
+    // count only the name-like tokens for the "must match 2" requirement.
+    const GREETING_TOKENS = new Set([
+        'zdravo', 'cao', 'hej', 'bok', 'hello', 'hi', 'hey',
+        'good', 'morning', 'afternoon', 'evening', 'dear',
+        'pozdrav', 'dobar', 'dobro', 'jutro', 'dan', 'vece',
+    ]);
+    const namelikeClaimedTokens = claimedTokens.filter((t) => !GREETING_TOKENS.has(t));
+    const requiredMatches = namelikeClaimedTokens.length >= 2 && sourceTokens.length >= 2
+        ? 2
+        : 1;
+    let matchedTokens = 0;
+    let bestSim = 0;
+    let bestClaimedToken = '';
+    let bestSourceToken = '';
+    const usedSourceIndices = new Set();
+    for (const ct of claimedTokens) {
+        let bestIdx = -1;
+        let bestTokenSim = 0;
+        for (let si = 0; si < sourceTokens.length; si++) {
+            if (usedSourceIndices.has(si))
+                continue;
+            const tokenSim = jaroWinklerSimilarity(ct, sourceTokens[si]);
+            if (tokenSim >= tokenThreshold && tokenSim > bestTokenSim) {
+                bestTokenSim = tokenSim;
+                bestIdx = si;
+            }
+        }
+        if (bestIdx >= 0) {
+            matchedTokens++;
+            usedSourceIndices.add(bestIdx);
+            if (bestTokenSim > bestSim) {
+                bestSim = bestTokenSim;
+                bestClaimedToken = ct;
+                bestSourceToken = sourceTokens[bestIdx];
+            }
+        }
+    }
+    if (matchedTokens >= requiredMatches) {
+        return {
+            matched: true,
+            similarity: bestSim,
+            explanation: `Token "${bestClaimedToken}" matches "${bestSourceToken}" in "${source}" (similarity: ${bestSim.toFixed(3)} ≥ ${threshold}).`,
+        };
+    }
+    return {
+        matched: false,
+        similarity: isMultiToken ? (bestSim || sim) : sim,
+        explanation: isMultiToken
+            ? `"${claimed}" failed per-token matching against "${source}" (${matchedTokens}/${requiredMatches} tokens matched, best token similarity: ${(bestSim || 0).toFixed(3)}).`
+            : `"${claimed}" is not sufficiently similar to "${source}" (similarity: ${sim.toFixed(3)} < ${threshold}).`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Value extractor — pull scalar numbers/dates/strings from tool output
+// ---------------------------------------------------------------------------
+/**
+ * Recursively extract all leaf values from a JSON-like tool output.
+ * Returns strings and numbers found anywhere in the output tree.
+ */
+function extractValuesFromOutput(output) {
+    return extractValuesWithKeys(output).map((e) => e.value);
+}
+/**
+ * Recursively extract all leaf values with their field names.
+ */
+function extractValuesWithKeys(output) {
+    const results = [];
+    function walk(v, key) {
+        if (v === null || v === undefined)
+            return;
+        if (typeof v === 'number') {
+            results.push({ value: v, fieldName: key });
+        }
+        else if (typeof v === 'string') {
+            results.push({ value: v, fieldName: key });
+            // Coerce numeric strings (e.g. "44" from DB) to numbers so they
+            // can match numeric/count claims as well.
+            if (/^-?\d+(\.\d+)?$/.test(v.trim())) {
+                results.push({ value: parseFloat(v.trim()), fieldName: key });
+            }
+            // HH:MM duration strings (e.g. "6738:25" = 6738 hours 25 minutes).
+            // Extract the hours component as a number and total minutes.
+            const hhmmMatch = v.trim().match(/^(\d+):(\d{2})$/);
+            if (hhmmMatch && parseInt(hhmmMatch[2], 10) < 60) {
+                const hours = parseInt(hhmmMatch[1], 10);
+                const minutes = parseInt(hhmmMatch[2], 10);
+                results.push({ value: hours, fieldName: key });
+                if (minutes > 0) {
+                    results.push({ value: hours * 60 + minutes, fieldName: key ? `${key}_total_minutes` : '_total_minutes' });
+                }
+            }
+        }
+        else if (Array.isArray(v)) {
+            v.forEach((item, i) => walk(item, key ? `${key}[${i}]` : `[${i}]`));
+        }
+        else if (typeof v === 'object') {
+            for (const [k, val] of Object.entries(v)) {
+                walk(val, key ? `${key}.${k}` : k);
+            }
+        }
+    }
+    walk(output);
+    return results;
+}
+/** Known unit-bearing field name patterns. */
+const FIELD_UNIT_PATTERNS = [
+    [/minutes?$/i, 'minutes'],
+    [/hours?$/i, 'hours'],
+    [/seconds?$/i, 'seconds'],
+    [/days?$/i, 'days'],
+    [/weeks?$/i, 'weeks'],
+    [/months?$/i, 'months'],
+    [/years?$/i, 'years'],
+    [/\bkm$/i, 'km'],
+    [/meters?$/i, 'meters'],
+    [/miles?$/i, 'miles'],
+    [/\bkg$/i, 'kg'],
+    [/\blbs?$/i, 'lbs'],
+    [/bytes?$/i, 'bytes'],
+];
+/**
+ * Infer a unit from a JSON field name.
+ * E.g. "total_minutes" → "minutes", "hours_worked" → "hours"
+ */
+function inferUnitFromFieldName(fieldName) {
+    if (!fieldName)
+        return undefined;
+    // Take the last segment of the key path
+    const lastPart = fieldName.split('.').pop() ?? fieldName;
+    // Split on underscores/camelCase
+    const parts = lastPart.replace(/([a-z])([A-Z])/g, '$1_$2').toLowerCase().split(/[_\s]+/);
+    for (const part of parts) {
+        for (const [pattern, unit] of FIELD_UNIT_PATTERNS) {
+            if (pattern.test(part))
+                return unit;
+        }
+    }
+    return undefined;
+}
+/**
+ * Extracts the count of items from a tool output.
+ * If the output is an array, returns its length.
+ * If it has a "count" / "total" / "length" field, returns that.
+ * Otherwise returns null.
+ */
+function extractCountFromOutput(output) {
+    if (Array.isArray(output))
+        return output.length;
+    if (output !== null && typeof output === 'object') {
+        const obj = output;
+        for (const key of ['count', 'total', 'length', 'size', 'num', 'number']) {
+            if (typeof obj[key] === 'number')
+                return obj[key];
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=index.js.map