truthguard-ai 0.2.0 → 0.4.0

package/dist-npm/Matchers/index.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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)
+ */
+import type { ToleranceConfig, UnitType } from '../types';
+export interface MatchResult {
+    matched: boolean;
+    /** Numeric deviation (absolute relative difference for numbers). */
+    deviation?: number;
+    /** Similarity score 0–1 (for name matching). */
+    similarity?: number;
+    /** Human-readable explanation of the match decision. */
+    explanation: string;
+}
+/**
+ * Compare two numeric values using a configurable relative tolerance.
+ */
+export declare function matchNumeric(claimed: number, source: number, tolerances: Pick<ToleranceConfig, 'numericRelativeTolerance'>): MatchResult;
+/** Normalise a unit string to its canonical form. */
+export declare function normaliseUnit(raw: string): UnitType | string;
+/**
+ * Try to convert `sourceValue` (in `sourceUnit`) to `claimUnit`.
+ * Returns the converted value, or null if no conversion path exists.
+ */
+export declare function tryUnitConversion(sourceValue: number, sourceUnit: string, claimUnit: string): number | 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.
+ */
+export declare function matchNumericWithUnits(claimed: number, claimUnit: UnitType | string | undefined, source: number, sourceUnit: string | undefined, tolerances: Pick<ToleranceConfig, 'numericRelativeTolerance'>): MatchResult;
+/**
+ * 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`.
+ */
+export declare function isTransposedDigits(claimed: number, source: number): boolean;
+/**
+ * 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)
+ */
+export declare function matchCount(claimed: number, source: number, tolerances: Pick<ToleranceConfig, 'countExactMatch'>): MatchResult;
+/**
+ * Compare two ISO-8601 date strings (YYYY-MM-DD).
+ * Normalises both values before comparison.
+ */
+export declare function matchDate(claimed: string, source: string, _tolerances: Pick<ToleranceConfig, 'dateExactMatch'>): MatchResult;
+/**
+ * Compute Jaro similarity between two strings.
+ * Returns a value in [0, 1].
+ */
+export declare function jaroSimilarity(s1: string, s2: string): number;
+/**
+ * Compute Jaro-Winkler similarity (boosts prefix matches).
+ */
+export declare function jaroWinklerSimilarity(s1: string, s2: string, prefixScale?: number): number;
+export declare function matchName(claimed: string, source: string, tolerances: Pick<ToleranceConfig, 'nameSimilarityThreshold'>): MatchResult;
+/**
+ * Recursively extract all leaf values from a JSON-like tool output.
+ * Returns strings and numbers found anywhere in the output tree.
+ */
+export declare function extractValuesFromOutput(output: unknown): Array<number | string>;
+/** A value extracted from tool output, optionally annotated with its field name. */
+export interface ExtractedValue {
+    value: number | string;
+    /** The JSON key path (e.g. "total_minutes", "employee.hours_worked"). */
+    fieldName?: string;
+}
+/**
+ * Recursively extract all leaf values with their field names.
+ */
+export declare function extractValuesWithKeys(output: unknown): ExtractedValue[];
+/**
+ * Infer a unit from a JSON field name.
+ * E.g. "total_minutes" → "minutes", "hours_worked" → "hours"
+ */
+export declare function inferUnitFromFieldName(fieldName: string | undefined): UnitType | 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.
+ */
+export declare function extractCountFromOutput(output: unknown): number | null;
+//# sourceMappingURL=index.d.ts.map

package/dist-npm/Matchers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Matchers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAO1D,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD;;GAEG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,IAAI,CAAC,eAAe,EAAE,0BAA0B,CAAC,GAC5D,WAAW,CAyBb;AA8JD,qDAAqD;AACrD,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAG5D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAWf;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,EACxC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,UAAU,EAAE,IAAI,CAAC,eAAe,EAAE,0BAA0B,CAAC,GAC5D,WAAW,CA8Db;AAMD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAkB3E;AAMD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,IAAI,CAAC,eAAe,EAAE,iBAAiB,CAAC,GACnD,WAAW,CAyBb;AAMD;;;GAGG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,IAAI,CAAC,eAAe,EAAE,gBAAgB,CAAC,GACnD,WAAW,CA+Cb;AAMD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAsC7D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,SAAM,GAAG,MAAM,CAMvF;AAgBD,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,IAAI,CAAC,eAAe,EAAE,yBAAyB,CAAC,GAC3D,WAAW,CAqGb;AAMD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,OAAO,GAAG,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAE/E;AAED,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,cAAc,EAAE,CAoCvE;AAmBD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAY1F;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAWrE"}