figured 0.1.0__py3-none-any.whl

figured/__init__.py

@@ -0,0 +1,31 @@
+"""figured: show your work.
+
+Verify that every number in an LLM-generated answer traces to the rows it was derived from,
+directly or as a sum, difference, ratio, or percentage of them.
+
+    >>> from figured import trace
+    >>> report = trace("California has 39.3 million people.", [{"state": "CA", "pop": 39346023}])
+    >>> report.ok
+    True
+"""
+
+from figured.core import trace
+from figured.evidence import build_evidence
+from figured.extract import Figure, extract_numbers
+from figured.policy import DERIVATIONS, LENIENT, STRICT, Policy
+from figured.report import Report, Result
+
+__version__ = "0.1.0"
+__all__ = [
+    "DERIVATIONS",
+    "LENIENT",
+    "STRICT",
+    "Figure",
+    "Policy",
+    "Report",
+    "Result",
+    "__version__",
+    "build_evidence",
+    "extract_numbers",
+    "trace",
+]

figured/__main__.py

@@ -0,0 +1,41 @@
+"""Command line: figured "answer text" --rows rows.json [--tolerance 0.015] [--json]
+
+Exits 1 when any figure is untraceable, so it can gate a CI step or a pipeline.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from figured.core import trace
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="figured", description="Check that the numbers in a text trace to rows.")
+    p.add_argument("text", help="the generated text, or '-' to read it from stdin")
+    p.add_argument(
+        "--rows", required=True, help="JSON file: a list of objects, a list of arrays, or {columns, rows}"
+    )
+    p.add_argument("--tolerance", type=float, default=None, help="relative tolerance, default 0.015")
+    p.add_argument("--strict-percent", action="store_true", help="flag percentages that match nothing")
+    p.add_argument("--json", action="store_true", help="print the full report as JSON")
+    args = p.parse_args(argv)
+
+    text = sys.stdin.read() if args.text == "-" else args.text
+    rows = json.loads(Path(args.rows).read_text())
+    overrides: dict[str, Any] = {}
+    if args.tolerance is not None:
+        overrides["rel_tolerance"] = args.tolerance
+    if args.strict_percent:
+        overrides["unmatched_percent"] = "flag"
+    report = trace(text, rows, **overrides)
+    print(json.dumps(report.to_dict(), indent=2) if args.json else report.explain())
+    return 0 if report.ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

figured/core.py

@@ -0,0 +1,66 @@
+"""The one function: trace(text, rows) -> Report."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from figured.derive import Index
+from figured.evidence import build_evidence
+from figured.extract import Figure, extract_numbers
+from figured.policy import Policy
+from figured.report import Report, Result
+
+
+def trace(
+    text: str,
+    rows: Any = None,
+    *,
+    results: Iterable[Any] | None = None,
+    policy: Policy | None = None,
+    **overrides: Any,
+) -> Report:
+    """Check that every substantive number in `text` traces to `rows`.
+
+    `rows` is one result set in any common shape: a list of dicts, a list of sequences, a
+    pandas DataFrame, a DB-API cursor, or a {"columns": [...], "rows": [...]} mapping.
+    `results` is several of those, for answers written from more than one query.
+    Policy options can be passed as keywords: trace(text, rows, rel_tolerance=0.01).
+    """
+    pol = (policy or Policy()).with_overrides(**overrides)
+    ev = build_evidence(rows, results, parse_strings=pol.parse_strings)
+    figures = extract_numbers(text)
+    if ev.empty:
+        return Report(text, [_without_evidence(f, pol) for f in figures], 0)
+    index = Index(ev, pol)
+    return Report(text, [_check(f, index, pol) for f in figures], ev.size)
+
+
+def _without_evidence(fig: Figure, pol: Policy) -> Result:
+    if _is_year(fig, pol):
+        return Result(fig, "ignored", reason="year")
+    if fig.is_percent:
+        return Result(fig, "ignored", reason="percent without evidence")
+    if abs(fig.value) > pol.flag_without_evidence_above:
+        return Result(fig, "ungrounded", reason="no evidence")
+    return Result(fig, "ignored", reason="small")
+
+
+def _check(fig: Figure, index: Index, pol: Policy) -> Result:
+    if _is_year(fig, pol):
+        return Result(fig, "ignored", reason="year")
+    if not fig.is_percent and abs(fig.value) <= pol.ignore_below:
+        return Result(fig, "ignored", reason="small")
+    match = index.lookup(fig.value, pol, is_percent=fig.is_percent)
+    if match is None and fig.is_range:
+        match = index.lookup_range(*fig.bounds, pol, is_percent=fig.is_percent)
+    if match is not None:
+        return Result(fig, "grounded", match)
+    if fig.is_percent and pol.unmatched_percent == "pass":
+        return Result(fig, "ignored", reason="unmatched percent allowed by policy")
+    return Result(fig, "ungrounded")
+
+
+def _is_year(fig: Figure, pol: Policy) -> bool:
+    lo, hi = pol.year_range
+    return pol.ignore_years and fig.looks_like_year and lo <= fig.value <= hi

figured/derive.py

@@ -0,0 +1,359 @@
+"""Everything the rows could legitimately produce, searched on demand rather than enumerated.
+
+Cells, column sums, and adjacent-cell sums are indexed once. Differences, ratios, percentages,
+and percent changes are found per figure by solving for the partner cell and bisecting for it,
+so the cost is O(cells · log cells) per figure instead of O(cells²) up front.
+"""
+
+from __future__ import annotations
+
+from bisect import bisect_left, bisect_right
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from figured.evidence import Cell, Evidence
+from figured.policy import Policy
+
+RANK = {
+    "cell": 0,
+    "column_sum": 1,
+    "row_sum": 2,
+    "difference": 3,
+    "ratio": 4,
+    "percent": 4,
+    "percent_change": 5,
+}
+
+
+@dataclass(frozen=True, slots=True)
+class Candidate:
+    value: float
+    kind: str
+    explanation: str
+
+    @property
+    def rank(self) -> int:
+        return RANK[self.kind]
+
+
+@dataclass(frozen=True, slots=True)
+class Match:
+    candidate: Candidate
+    error: float
+
+    @property
+    def kind(self) -> str:
+        return self.candidate.kind
+
+    @property
+    def explanation(self) -> str:
+        return self.candidate.explanation
+
+    @property
+    def value(self) -> float:
+        return self.candidate.value
+
+
+def fmt(v: float) -> str:
+    if abs(v) >= 1e15:
+        return f"{v:.3g}"
+    if float(v).is_integer():
+        return f"{int(v):,}"
+    if abs(v) >= 100:
+        return f"{v:,.1f}"
+    return f"{v:,.4g}"
+
+
+Scorer = Callable[[float], float | None]
+
+
+class Index:
+    """Sorted views over the evidence plus on-demand derivation search."""
+
+    def __init__(self, ev: Evidence, policy: Policy) -> None:
+        self.ev = ev
+        self.policy = policy
+        allowed = policy.derivations
+        self.allowed = allowed
+
+        sets = ev.results
+        flat_abs: list[float] = []
+        self.set_start: list[int] = []
+        for rs in sets:
+            self.set_start.append(len(flat_abs))
+            flat_abs.extend(map(abs, rs.values))
+        self.flat_abs = flat_abs
+        if "cell" in allowed and flat_abs:
+            order = sorted(range(len(flat_abs)), key=flat_abs.__getitem__)
+            self.cell_keys = [flat_abs[i] for i in order]
+            self.cell_order = order
+        else:
+            self.cell_keys = []
+            self.cell_order = []
+
+        agg: list[tuple[float, str, str]] = []
+        if "column_sum" in allowed:
+            agg.extend(self._column_sums())
+        agg.sort(key=lambda t: t[0])
+        self.agg_keys = [a for a, _, _ in agg]
+        self.agg_items = agg
+        self._row_sums: list[tuple[float, int, int, int, int]] | None = None
+        self._row_sum_keys: list[float] = []
+
+        pair_idx: list[int] = []
+        for rs, base in zip(sets, self.set_start, strict=True):
+            limit = rs.row_start[min(policy.max_rows, len(rs.row_start) - 1)]
+            pair_idx.extend(range(base, base + limit))
+        pair_idx = pair_idx[: policy.max_cells]
+        signed = self._signed
+        pair_idx.sort(key=signed)
+        self.pair_vals = [signed(i) for i in pair_idx]
+        self.pair_refs = pair_idx
+        by_abs = sorted(pair_idx, key=flat_abs.__getitem__)
+        self.pair_abs = [flat_abs[i] for i in by_abs]
+        self.pair_abs_refs = by_abs
+
+    def _signed(self, g: int) -> float:
+        rs_i = bisect_right(self.set_start, g) - 1
+        return self.ev.results[rs_i].values[g - self.set_start[rs_i]]
+
+    def cell(self, g: int) -> Cell:
+        rs_i = bisect_right(self.set_start, g) - 1
+        return self.ev.results[rs_i].cell(g - self.set_start[rs_i])
+
+    def lookup(self, value: float, policy: Policy, *, is_percent: bool = False) -> Match | None:
+        v = abs(value)
+        tol = max(v * policy.rel_tolerance, policy.abs_tolerance)
+
+        def score(d: float) -> float | None:
+            if not policy.close(v, d):
+                return None
+            return abs(v - d) / d if d else abs(v - d)
+
+        return self._search(v - tol, v + tol, v, score, is_percent)
+
+    def lookup_range(self, lo: float, hi: float, policy: Policy, *, is_percent: bool = False) -> Match | None:
+        lo_t = min(lo * (1 - policy.rel_tolerance), lo - policy.abs_tolerance)
+        hi_t = max(hi * (1 + policy.rel_tolerance), hi + policy.abs_tolerance)
+
+        def score(d: float) -> float | None:
+            if d < lo_t or d > hi_t:
+                return None
+            return 0.0 if lo <= d <= hi else min(abs(d - lo), abs(d - hi)) / max(d, 1e-12)
+
+        return self._search(lo_t, hi_t, (lo + hi) / 2, score, is_percent)
+
+    def _search(self, lo: float, hi: float, v: float, score: Scorer, is_percent: bool) -> Match | None:
+        allowed = self.allowed
+        if self.cell_keys:
+            m = self._best_sorted(self.cell_keys, lo, hi, score, self._cell_candidate)
+            if m:
+                return m
+        if self.agg_keys:
+            m = self._best_sorted(self.agg_keys, lo, hi, score, self._agg_candidate)
+            if m:
+                return m
+        if "row_sum" in allowed:
+            sums = self._row_sum_index()
+            if sums:
+                m = self._best_sorted(self._row_sum_keys, lo, hi, score, self._row_candidate)
+                if m:
+                    return m
+        if not self.pair_vals:
+            return None
+        if "difference" in allowed:
+            m = self._differences(lo, hi, score)
+            if m:
+                return m
+        kind = "percent" if is_percent else "ratio"
+        if kind in allowed:
+            m = self._ratios(lo, hi, kind, score)
+            if m:
+                return m
+        if "percent_change" in allowed:
+            m = self._percent_changes(lo, hi, score)
+            if m:
+                return m
+        return None
+
+    @staticmethod
+    def _best_sorted(
+        keys: list[float], lo: float, hi: float, score: Scorer, make: Callable[[int], Candidate]
+    ) -> Match | None:
+        best: tuple[float, int] | None = None
+        for i in range(bisect_left(keys, lo), bisect_right(keys, hi)):
+            err = score(keys[i])
+            if err is not None and (best is None or err < best[0]):
+                best = (err, i)
+        return Match(make(best[1]), best[0]) if best else None
+
+    def _cell_candidate(self, i: int) -> Candidate:
+        c = self.cell(self.cell_order[i])
+        return Candidate(c.value, "cell", f"{c.ref()} = {fmt(c.value)}")
+
+    def _agg_candidate(self, i: int) -> Candidate:
+        a, kind, text = self.agg_items[i]
+        return Candidate(a, kind, text)
+
+    def _row_candidate(self, i: int) -> Candidate:
+        assert self._row_sums is not None
+        _, rs_index, r, a, b = self._row_sums[i]
+        rs = self.ev.results[rs_index]
+        s = rs.row_start[r]
+        signed = sum(rs.values[s + a : s + b + 1])
+        head, tail = rs.columns[rs.col_of[s + a]], rs.columns[rs.col_of[s + b]]
+        return Candidate(signed, "row_sum", f"{head}..{tail}[{rs.labels[r]}] summed = {fmt(signed)}")
+
+    def _column_sums(self) -> list[tuple[float, str, str]]:
+        out: list[tuple[float, str, str]] = []
+        for rs in self.ev.results:
+            for c, (total, n) in enumerate(zip(rs.col_totals, rs.col_counts, strict=True)):
+                if n >= 2:
+                    out.append(
+                        (abs(total), "column_sum", f"sum of {rs.columns[c]} over {n} rows = {fmt(total)}")
+                    )
+        return out
+
+    def _row_sum_index(self) -> list[tuple[float, int, int, int, int]]:
+        """Adjacent-cell sums (2 to 6 cells) over the first max_rows rows, formatted only on a match."""
+        if self._row_sums is None:
+            out: list[tuple[float, int, int, int, int]] = []
+            for rs in self.ev.results:
+                vals, starts, idx = rs.values, rs.row_start, rs.index
+                for r in range(min(self.policy.max_rows, len(starts) - 1)):
+                    s, e = starts[r], starts[r + 1]
+                    n = e - s
+                    for i in range(n - 1):
+                        total = vals[s + i]
+                        for j in range(i + 1, min(n, i + 6)):
+                            total += vals[s + j]
+                            out.append((abs(total), idx, r, i, j))
+            out.sort(key=lambda t: t[0])
+            self._row_sums = out
+            self._row_sum_keys = [t[0] for t in out]
+        return self._row_sums
+
+    def _differences(self, lo: float, hi: float, score: Scorer) -> Match | None:
+        """Pairs with |a − b| in [lo, hi]. Both windows slide right as b grows, so two pointers suffice."""
+        vals, n = self.pair_vals, len(self.pair_vals)
+        best: tuple[float, int, int] | None = None
+        s1 = e1 = s2 = e2 = 0
+        for j in range(n):
+            b = vals[j]
+            a_lo, a_hi = b + lo, b + hi
+            while s1 < n and vals[s1] < a_lo:
+                s1 += 1
+            while e1 < n and vals[e1] <= a_hi:
+                e1 += 1
+            for i in range(s1, e1):
+                if i != j:
+                    err = score(vals[i] - b)
+                    if err is not None and (best is None or err < best[0]):
+                        best = (err, i, j)
+            a_lo, a_hi = b - hi, b - lo
+            while s2 < n and vals[s2] < a_lo:
+                s2 += 1
+            while e2 < n and vals[e2] <= a_hi:
+                e2 += 1
+            for i in range(s2, e2):
+                if i != j:
+                    err = score(b - vals[i])
+                    if err is not None and (best is None or err < best[0]):
+                        best = (err, i, j)
+        if best is None:
+            return None
+        _, i, j = best
+        ca, cb = self.cell(self.pair_refs[i]), self.cell(self.pair_refs[j])
+        d = ca.value - cb.value
+        return Match(
+            Candidate(
+                d, "difference", f"{ca.ref()} − {cb.ref()} = {fmt(ca.value)} − {fmt(cb.value)} = {fmt(d)}"
+            ),
+            best[0],
+        )
+
+    def _ratios(self, lo: float, hi: float, kind: str, score: Scorer) -> Match | None:
+        """A percent figure is searched as a ÷ b × 100, a plain figure as a ÷ b."""
+        scale = 100.0 if kind == "percent" else 1.0
+        vals, n = self.pair_abs, len(self.pair_abs)
+        best: tuple[float, int, int, str, float] | None = None
+        r_lo, r_hi = lo / scale, hi / scale
+        if r_hi <= 0:
+            return None
+        r_lo = max(r_lo, 1e-300)
+        s1 = e1 = s2 = e2 = 0
+        for j in range(n):
+            b = vals[j]
+            if b == 0:
+                continue
+            a_lo, a_hi = b * r_lo, b * r_hi
+            while s1 < n and vals[s1] < a_lo:
+                s1 += 1
+            while e1 < n and vals[e1] <= a_hi:
+                e1 += 1
+            for i in range(s1, e1):
+                if i != j:
+                    err = score(vals[i] / b * scale)
+                    if err is not None and (best is None or err < best[0]):
+                        best = (err, i, j, kind, scale)
+            a_lo, a_hi = b / r_hi, b / r_lo
+            while s2 < n and vals[s2] < a_lo:
+                s2 += 1
+            while e2 < n and vals[e2] <= a_hi:
+                e2 += 1
+            for i in range(s2, e2):
+                if i != j and vals[i]:
+                    err = score(b / vals[i] * scale)
+                    if err is not None and (best is None or err < best[0]):
+                        best = (err, j, i, kind, scale)
+        if best is None:
+            return None
+        err, num_i, den_i, kind, scale = best
+        ca, cb = self.cell(self.pair_abs_refs[num_i]), self.cell(self.pair_abs_refs[den_i])
+        value = abs(ca.value / cb.value) * scale
+        text = f"{ca.ref()} ÷ {cb.ref()} = {fmt(value)}" + ("%" if scale == 100.0 else "")
+        return Match(Candidate(value, kind, text), err)
+
+    def _percent_changes(self, lo: float, hi: float, score: Scorer) -> Match | None:
+        """(a − b) ÷ b × 100 in ±[lo, hi]. Positive b slides monotonically; negatives fall back to bisect."""
+        vals, n = self.pair_vals, len(self.pair_vals)
+        f_lo, f_hi = lo / 100, hi / 100
+        best: tuple[float, int, int] | None = None
+        s1 = e1 = s2 = e2 = 0
+        for j in range(n):
+            b = vals[j]
+            if b == 0:
+                continue
+            if b > 0:
+                a_lo, a_hi = b * (1 + f_lo), b * (1 + f_hi)
+                while s1 < n and vals[s1] < a_lo:
+                    s1 += 1
+                while e1 < n and vals[e1] <= a_hi:
+                    e1 += 1
+                r1 = range(s1, e1)
+                a_lo, a_hi = b * (1 - f_hi), b * (1 - f_lo)
+                while s2 < n and vals[s2] < a_lo:
+                    s2 += 1
+                while e2 < n and vals[e2] <= a_hi:
+                    e2 += 1
+                r2 = range(s2, e2)
+            else:
+                w1 = sorted((b * (1 + f_lo), b * (1 + f_hi)))
+                w2 = sorted((b * (1 - f_hi), b * (1 - f_lo)))
+                r1 = range(bisect_left(vals, w1[0]), bisect_right(vals, w1[1]))
+                r2 = range(bisect_left(vals, w2[0]), bisect_right(vals, w2[1]))
+            for rng in (r1, r2):
+                for i in rng:
+                    if i != j:
+                        err = score(abs((vals[i] - b) / b * 100))
+                        if err is not None and (best is None or err < best[0]):
+                            best = (err, i, j)
+        if best is None:
+            return None
+        _, i, j = best
+        ca, cb = self.cell(self.pair_refs[i]), self.cell(self.pair_refs[j])
+        pc = (ca.value - cb.value) / cb.value * 100
+        return Match(
+            Candidate(pc, "percent_change", f"({ca.ref()} − {cb.ref()}) ÷ {cb.ref()} = {fmt(pc)}%"),
+            best[0],
+        )

figured/evidence.py

@@ -0,0 +1,202 @@
+"""Normalize whatever the caller has (rows, dicts, a DataFrame, a cursor) into numeric cells.
+
+Storage is columnar and flat: one list of values across all result sets, with offsets. Cell
+objects are created only for the handful of cells that end up in an explanation.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from bisect import bisect_right
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass, field
+from decimal import Decimal
+from typing import Any
+
+_NUMERIC_STRING = re.compile(r"^[-+]?[$€£¥]?\s?(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?(?:[eE][-+]?\d+)?%?$")
+_MONEY = str.maketrans("", "", ",$€£¥")
+
+
+@dataclass(frozen=True, slots=True)
+class Cell:
+    value: float
+    column: str
+    row: int
+    result: int
+    label: str
+
+    def ref(self) -> str:
+        return f"{self.column}[{self.label}]"
+
+
+@dataclass(slots=True)
+class ResultSet:
+    columns: list[str]
+    index: int
+    values: list[float] = field(default_factory=list)
+    col_of: list[int] = field(default_factory=list)
+    row_start: list[int] = field(default_factory=list)
+    labels: list[str] = field(default_factory=list)
+    col_totals: list[float] = field(default_factory=list)
+    col_counts: list[int] = field(default_factory=list)
+
+    @property
+    def rows(self) -> list[list[Cell]]:
+        return [
+            [self.cell(k) for k in range(self.row_start[r], self.row_start[r + 1])]
+            for r in range(len(self.labels))
+        ]
+
+    def row_of(self, k: int) -> int:
+        return bisect_right(self.row_start, k) - 1
+
+    def cell(self, k: int) -> Cell:
+        r = self.row_of(k)
+        return Cell(self.values[k], self.columns[self.col_of[k]], r, self.index, self.labels[r])
+
+
+@dataclass(slots=True)
+class Evidence:
+    results: list[ResultSet] = field(default_factory=list)
+
+    @property
+    def cells(self) -> list[Cell]:
+        return [rs.cell(k) for rs in self.results for k in range(len(rs.values))]
+
+    @property
+    def size(self) -> int:
+        return sum(len(rs.values) for rs in self.results)
+
+    @property
+    def empty(self) -> bool:
+        return self.size == 0
+
+
+def build_evidence(
+    rows: Any = None,
+    results: Iterable[Any] | None = None,
+    *,
+    parse_strings: bool = True,
+) -> Evidence:
+    """Accept one result set (`rows`) and/or several (`results`) in any common shape."""
+    sets: list[Any] = []
+    if rows is not None:
+        sets.append(rows)
+    if results is not None:
+        sets.extend(results)
+    ev = Evidence()
+    for i, obj in enumerate(sets):
+        columns, raw_rows = _to_table(obj)
+        ev.results.append(_result_set(columns, raw_rows, i, parse_strings))
+    return ev
+
+
+def _to_table(obj: Any) -> tuple[list[str], list[Sequence[Any]]]:
+    if obj is None:
+        return [], []
+    if isinstance(obj, Mapping) and "rows" in obj:
+        cols = [str(c) for c in obj.get("columns") or []]
+        return cols, [_dict_row(r, cols) if isinstance(r, Mapping) else r for r in obj["rows"]]
+    if hasattr(obj, "to_dict") and hasattr(obj, "columns"):
+        cols = [str(c) for c in obj.columns]
+        return cols, [[rec.get(c) for c in cols] for rec in obj.to_dict("records")]
+    if hasattr(obj, "fetchall") and hasattr(obj, "description"):
+        return [str(d[0]) for d in obj.description or []], list(obj.fetchall())
+    rows = obj if isinstance(obj, list) else list(obj)
+    if not rows:
+        return [], []
+    first = rows[0]
+    if isinstance(first, Mapping):
+        keys: list[Any] = list(first.keys())
+        seen = set(keys)
+        for r in rows:
+            if len(r) != len(keys) or r.keys() != seen:
+                for k in r:
+                    if k not in seen:
+                        seen.add(k)
+                        keys.append(k)
+        return [str(k) for k in keys], [[r.get(c) for c in keys] for r in rows]
+    if isinstance(first, str | bytes | int | float | Decimal):
+        return [], [[r] for r in rows]
+    return [], rows
+
+
+def _dict_row(r: Mapping[str, Any], cols: list[str]) -> list[Any]:
+    return [r.get(c) for c in cols] if cols else list(r.values())
+
+
+def _result_set(
+    columns: list[str], raw_rows: list[Sequence[Any]], index: int, parse_strings: bool
+) -> ResultSet:
+    width = max((len(r) for r in raw_rows), default=0)
+    if len(columns) < width:
+        columns = columns + [f"c{i}" for i in range(len(columns), width)]
+    rs = ResultSet(columns, index)
+    values, col_of, row_start, labels = rs.values, rs.col_of, rs.row_start, rs.labels
+    totals, counts = [0.0] * width, [0] * width
+    push_v, push_c, push_label, push_start = values.append, col_of.append, labels.append, row_start.append
+    isfinite = math.isfinite
+    for raw in raw_rows:
+        push_start(len(values))
+        label = ""
+        for ci, v in enumerate(raw):
+            t = type(v)
+            if t is float:
+                if not isfinite(v):
+                    continue
+            elif t is int:
+                v = float(v)
+            elif t is str:
+                s = v.strip()
+                if _NUMERIC_STRING.match(s):
+                    if not parse_strings:
+                        continue
+                    num = _parse_numeric_string(s)
+                    if num is None:
+                        continue
+                    v = num
+                else:
+                    if not label and s:
+                        label = s[:40]
+                    continue
+            else:
+                num = to_number(v, parse_strings)
+                if num is None:
+                    continue
+                v = num
+            push_v(v)
+            push_c(ci)
+            totals[ci] += v
+            counts[ci] += 1
+        push_label(label or f"row {len(labels)}")
+    push_start(len(values))
+    rs.col_totals, rs.col_counts = totals, counts
+    return rs
+
+
+def _parse_numeric_string(s: str) -> float | None:
+    try:
+        return float(s.rstrip("%").translate(_MONEY))
+    except ValueError:
+        return None
+
+
+def to_number(v: Any, parse_strings: bool = True) -> float | None:
+    if v is None or isinstance(v, bool):
+        return None
+    if isinstance(v, int | float):
+        f = float(v)
+        return f if math.isfinite(f) else None
+    if isinstance(v, Decimal):
+        return float(v) if v.is_finite() else None
+    if isinstance(v, str):
+        s = v.strip()
+        return _parse_numeric_string(s) if parse_strings and _NUMERIC_STRING.match(s) else None
+    if hasattr(v, "__float__"):
+        try:
+            f = float(v)
+        except (TypeError, ValueError):
+            return None
+        return f if math.isfinite(f) else None
+    return None

figured/extract.py

@@ -0,0 +1,149 @@
+"""Find the numbers in a piece of text, with their positions and meaning."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+SCALES: dict[str, float] = {
+    "thousand": 1e3,
+    "k": 1e3,
+    "million": 1e6,
+    "mn": 1e6,
+    "m": 1e6,
+    "mm": 1e6,
+    "billion": 1e9,
+    "bn": 1e9,
+    "b": 1e9,
+    "trillion": 1e12,
+    "tn": 1e12,
+    "t": 1e12,
+}
+PERCENT_WORDS = frozenset({"%", "percent", "pct", "percentage points", "pp"})
+
+_NUMBER = re.compile(
+    r"""
+    (?<![\w.])
+    (?P<sign>[-−]\s?)?
+    (?P<currency>[$€£¥])?
+    (?P<body>
+        \d+(?:\.\d+)?[eE][+-]?\d+
+      | \d{1,3}(?:,\d{3})+(?:\.\d+)?
+      | \d+(?:\.\d+)?
+    )
+    (?!\d)
+    (?!(?:st|nd|rd|th)\b)
+    (?:
+        \s?(?P<pct>%)
+      | \s?(?P<word>percentage\ points|percent|pct|pp|thousand|million|billion|trillion|mn|mm|bn|tn|k|m|b|t)\b
+    )?
+    (?![A-Za-z_])
+    """,
+    re.VERBOSE | re.IGNORECASE,
+)
+_START = re.compile(r"(?:[-−]\s?)?[$€£¥]?\d")
+_RANGE_JOIN = re.compile(r"^\s*(?:to|and|or|-|–|—)\s*$", re.IGNORECASE)
+
+
+@dataclass(frozen=True)
+class Figure:
+    """One number found in the text."""
+
+    literal: str
+    value: float
+    start: int
+    end: int
+    is_percent: bool = False
+    is_currency: bool = False
+    has_scale: bool = False
+    range_partner: float | None = None
+
+    @property
+    def is_range(self) -> bool:
+        return self.range_partner is not None
+
+    @property
+    def bounds(self) -> tuple[float, float]:
+        other = self.range_partner if self.range_partner is not None else self.value
+        lo, hi = sorted((abs(self.value), abs(other)))
+        return lo, hi
+
+    @property
+    def looks_like_year(self) -> bool:
+        body = self.literal.lstrip("-−$€£¥ ").strip()
+        return body.isdigit() and len(body) == 4 and not self.is_percent and not self.has_scale
+
+
+def extract_numbers(text: str) -> list[Figure]:
+    """Return every number-like token in reading order.
+
+    Handles thousands separators, decimals, scientific notation, currency symbols, scale
+    words (thousand, million, k, bn, ...), percent markers, and ranges such as
+    "40 to 50 million", where the scale of the second number is applied to the first.
+    """
+    out: list[Figure] = []
+    pos = 0
+    match = _NUMBER.match
+    for start in _START.finditer(text):
+        at = start.start()
+        if at < pos:
+            continue
+        m = match(text, at) or (match(text, start.end() - 1) if start.end() - 1 > at else None)
+        if m is None:
+            continue
+        pos = m.end()
+        body = m.group("body").replace(",", "")
+        value = float(body)
+        word = (m.group("word") or "").lower()
+        pct = bool(m.group("pct")) or word in PERCENT_WORDS
+        scale = SCALES.get(word)
+        if scale:
+            value *= scale
+        if m.group("sign"):
+            value = -value
+        out.append(
+            Figure(
+                literal=m.group(0).strip(),
+                value=value,
+                start=m.start(),
+                end=m.end(),
+                is_percent=pct,
+                is_currency=bool(m.group("currency")),
+                has_scale=scale is not None,
+            )
+        )
+    return _apply_ranges(text, out)
+
+
+def _apply_ranges(text: str, figures: list[Figure]) -> list[Figure]:
+    if len(figures) < 2:
+        return figures
+    fixed = list(figures)
+    for i in range(len(fixed) - 1):
+        a, b = fixed[i], fixed[i + 1]
+        if not _RANGE_JOIN.match(text[a.end : b.start]):
+            continue
+        if b.has_scale and not a.has_scale and not a.is_percent:
+            a = Figure(a.literal, a.value * _scale_of(b), a.start, a.end, False, a.is_currency, True)
+        elif b.is_percent and not a.is_percent and not a.has_scale:
+            a = Figure(a.literal, a.value, a.start, a.end, True, a.is_currency, False)
+        if a.is_percent == b.is_percent and a.looks_like_year == b.looks_like_year and not a.looks_like_year:
+            fixed[i] = Figure(
+                a.literal, a.value, a.start, a.end, a.is_percent, a.is_currency, a.has_scale, b.value
+            )
+            fixed[i + 1] = Figure(
+                b.literal, b.value, b.start, b.end, b.is_percent, b.is_currency, b.has_scale, a.value
+            )
+        else:
+            fixed[i] = a
+    return fixed
+
+
+def _scale_of(fig: Figure) -> float:
+    word = fig.literal.split()[-1].lower() if " " in fig.literal else _trailing_word(fig.literal)
+    return SCALES.get(word, 1.0)
+
+
+def _trailing_word(literal: str) -> str:
+    m = re.search(r"[a-z]+$", literal, re.IGNORECASE)
+    return m.group(0).lower() if m else ""

figured/judge.py

@@ -0,0 +1,69 @@
+"""Optional second opinion from a model, for what arithmetic cannot see: wrong words around right numbers.
+
+Requires the `judge` extra: pip install "figured[judge]". The judge receives the question, the
+rows, and the answer, nothing else, and returns a strict verdict.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Literal
+
+JUDGE_SYSTEM = """You audit answers produced by a data assistant. You are given the user's question, the rows the assistant retrieved, and the assistant's answer. Judge strictly and only from what is shown.
+
+faithful: every number in the answer is supported by the rows, allowing rounding and values derived from them (sums, differences, ratios, percentages), and every comparative word (higher, lower, most, fewer) agrees with the rows.
+responsive: the answer addresses the question that was asked, or clearly explains what part cannot be answered.
+caveats_ok: if the answer relies on an approximation or omits part of the question, it says so. True when no caveat was needed.
+issues: short, specific strings; empty when none.
+verdict: "pass" only if faithful and responsive are both true."""
+
+
+def judge(
+    question: str,
+    answer: str,
+    rows: Any,
+    *,
+    model: str = "claude-opus-5",
+    client: Any = None,
+    max_rows: int = 30,
+) -> dict[str, Any]:
+    """Return {"verdict", "faithful", "responsive", "caveats_ok", "issues", "model"}."""
+    try:
+        import anthropic
+        from pydantic import BaseModel
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError('the judge needs the extra: pip install "figured[judge]"') from exc
+
+    class Verdict(BaseModel):  # type: ignore[misc]
+        faithful: bool
+        responsive: bool
+        caveats_ok: bool
+        issues: list[str]
+        verdict: Literal["pass", "fail"]
+
+    from figured.evidence import build_evidence
+
+    ev = build_evidence(rows)
+    evidence = [
+        {
+            "columns": rs.columns,
+            "rows": [[c.value for c in row] for row in rs.rows[:max_rows]],
+        }
+        for rs in ev.results
+    ]
+    prompt = (
+        f"Question:\n{question}\n\nRetrieved rows (JSON):\n{json.dumps(evidence)[:12000]}"
+        f"\n\nAssistant answer:\n{answer}"
+    )
+    client = client or anthropic.Anthropic()
+    resp = client.messages.parse(
+        model=model,
+        max_tokens=600,
+        system=JUDGE_SYSTEM,
+        messages=[{"role": "user", "content": prompt}],
+        output_format=Verdict,
+    )
+    parsed = resp.parsed_output
+    if parsed is None:
+        return {"verdict": "error", "issues": ["no parsed output"], "model": model}
+    return {**parsed.model_dump(), "model": model}

figured/policy.py

@@ -0,0 +1,60 @@
+"""Tunable rules for what counts as grounded."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Any, Literal
+
+DERIVATIONS = ("cell", "column_sum", "row_sum", "difference", "ratio", "percent", "percent_change")
+
+
+@dataclass(frozen=True)
+class Policy:
+    """How strictly to match, what to ignore, and which derivations to allow.
+
+    rel_tolerance: relative error allowed between a figure and a candidate (0.015 is 1.5%).
+    abs_tolerance: absolute error allowed in addition to the relative one.
+    ignore_below: figures at or below this absolute value are not checked (counts of items, rankings).
+    ignore_years: treat bare four-digit integers between year_range as years and skip them.
+    unmatched_percent: "pass" lets a percentage through when nothing matches, since shares of a
+        total outside the rows are common; "flag" treats it like any other figure.
+    max_rows / max_cells: how many rows and flat cells feed the pairwise derivations.
+    derivations: which candidate kinds are generated.
+    parse_strings: coerce numeric strings in the rows ("39,346,023", "$1,200", "12%").
+    flag_without_evidence_above: with no rows at all, figures above this are flagged.
+    """
+
+    rel_tolerance: float = 0.015
+    abs_tolerance: float = 0.0
+    ignore_below: float = 100.0
+    ignore_years: bool = True
+    year_range: tuple[int, int] = (1900, 2100)
+    unmatched_percent: Literal["pass", "flag"] = "pass"
+    max_rows: int = 12
+    max_cells: int = 40
+    derivations: frozenset[str] = frozenset(DERIVATIONS)
+    parse_strings: bool = True
+    flag_without_evidence_above: float = 1000.0
+
+    def with_overrides(self, **overrides: Any) -> Policy:
+        if not overrides:
+            return self
+        if "derivations" in overrides and not isinstance(overrides["derivations"], frozenset):
+            overrides["derivations"] = frozenset(overrides["derivations"])
+        unknown = set(overrides) - set(self.__dataclass_fields__)
+        if unknown:
+            raise TypeError(f"unknown policy option(s): {', '.join(sorted(unknown))}")
+        return replace(self, **overrides)
+
+    def close(self, a: float, b: float) -> bool:
+        if a == b:
+            return True
+        if abs(a - b) <= self.abs_tolerance:
+            return True
+        if b == 0:
+            return abs(a) <= self.abs_tolerance
+        return abs(a - b) / abs(b) <= self.rel_tolerance
+
+
+STRICT = Policy(rel_tolerance=0.005, unmatched_percent="flag", ignore_below=10.0)
+LENIENT = Policy(rel_tolerance=0.05)

figured/report.py

@@ -0,0 +1,105 @@
+"""What came back: every figure, whether it traced, and how."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from figured.derive import Match, fmt
+from figured.extract import Figure
+
+Status = Literal["grounded", "ungrounded", "ignored"]
+
+
+@dataclass(frozen=True)
+class Result:
+    figure: Figure
+    status: Status
+    match: Match | None = None
+    reason: str = ""
+
+    @property
+    def literal(self) -> str:
+        return self.figure.literal
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "literal": self.figure.literal,
+            "value": self.figure.value,
+            "span": [self.figure.start, self.figure.end],
+            "status": self.status,
+        }
+        if self.match:
+            d["match"] = {
+                "kind": self.match.kind,
+                "value": self.match.value,
+                "error": self.match.error,
+                "explanation": self.match.explanation,
+            }
+        if self.reason:
+            d["reason"] = self.reason
+        return d
+
+
+@dataclass
+class Report:
+    text: str
+    results: list[Result]
+    evidence_cells: int
+
+    @property
+    def ok(self) -> bool:
+        return not self.ungrounded
+
+    @property
+    def grounded(self) -> list[Result]:
+        return [r for r in self.results if r.status == "grounded"]
+
+    @property
+    def ungrounded(self) -> list[str]:
+        return [r.figure.literal for r in self.results if r.status == "ungrounded"]
+
+    @property
+    def ignored(self) -> list[Result]:
+        return [r for r in self.results if r.status == "ignored"]
+
+    @property
+    def checked(self) -> int:
+        return sum(1 for r in self.results if r.status != "ignored")
+
+    def caveat(self, limit: int = 4) -> str:
+        if self.ok:
+            return ""
+        shown = ", ".join(self.ungrounded[:limit])
+        more = len(self.ungrounded) - limit
+        tail = f" and {more} more" if more > 0 else ""
+        return (
+            f"Note: these figures could not be traced to the data: {shown}{tail}. Treat them as approximate."
+        )
+
+    def explain(self) -> str:
+        head = "OK" if self.ok else "UNGROUNDED"
+        lines = [f"{head} · {self.checked} checked · {len(self.ungrounded)} untraceable"]
+        for r in self.results:
+            if r.status == "grounded" and r.match:
+                lines.append(f"  ✓ {r.literal:<16} {r.match.kind:<14} {r.match.explanation}")
+            elif r.status == "ungrounded":
+                lines.append(f"  ✗ {r.literal:<16} no cell, sum, difference, or ratio within tolerance")
+            else:
+                lines.append(f"  · {r.literal:<16} ignored ({r.reason})")
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "ok": self.ok,
+            "checked": self.checked,
+            "ungrounded": self.ungrounded,
+            "evidence_cells": self.evidence_cells,
+            "figures": [r.to_dict() for r in self.results],
+        }
+
+    def __repr__(self) -> str:
+        return f"Report(ok={self.ok}, checked={self.checked}, ungrounded={self.ungrounded})"
+
+
+__all__ = ["Report", "Result", "Status", "fmt"]

figured-0.1.0.dist-info/METADATA

@@ -0,0 +1,211 @@
+Metadata-Version: 2.5
+Name: figured
+Version: 0.1.0
+Summary: Show your work: verify that every number in an LLM-generated answer traces to the rows it was derived from.
+Project-URL: Homepage, https://github.com/nisheshshukla/figured
+Project-URL: Repository, https://github.com/nisheshshukla/figured
+Project-URL: Issues, https://github.com/nisheshshukla/figured/issues
+Project-URL: Changelog, https://github.com/nisheshshukla/figured/blob/main/CHANGELOG.md
+Author: Nishesh Shukla
+License-Expression: MIT
+License-File: LICENSE
+Keywords: evaluation,faithfulness,grounding,guardrails,hallucination,llm,text-to-sql
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: judge
+Requires-Dist: anthropic>=1.0; extra == 'judge'
+Requires-Dist: pydantic>=2.0; extra == 'judge'
+Description-Content-Type: text/markdown
+
+# figured
+
+**Show your work.** Verify that every number in an LLM-generated answer traces to the rows it was written from.
+
+```python
+from figured import trace
+
+rows = [{"state": "California", "pop": 39_346_023}, {"state": "Texas", "pop": 28_635_442}]
+answer = "California has 39.3 million people, about 10.7 million more than Texas, and 4.1 million of them moved last year."
+
+report = trace(answer, rows)
+report.ok  # False
+report.ungrounded  # ['4.1 million']
+print(report.explain())
+```
+
+```
+UNGROUNDED · 3 checked · 1 untraceable
+  ✓ 39.3 million     cell           pop[California] = 39,346,023
+  ✓ 10.7 million     difference     pop[California] − pop[Texas] = 39,346,023 − 28,635,442 = 10,710,581
+  ✗ 4.1 million      no cell, sum, difference, or ratio within tolerance
+```
+
+Zero dependencies. Deterministic. About 150 µs for a typical answer, 1 ms for 200 rows. Python 3.10+.
+
+```bash
+pip install figured
+```
+
+## Why
+
+Text-to-SQL agents and RAG-over-tables pipelines validate the query and trust the prose. The model reads the rows and writes a paragraph, and nothing checks that the paragraph's numbers came from the rows. When it invents a figure, the SQL was fine, the rows were fine, and the user sees a confident wrong number.
+
+The usual answer is an LLM judge, which is slow, costs money per answer, and is itself wrong sometimes: in one published test, a faithfulness metric scored a fabricated price as fully faithful five times in a row. `figured` is the deterministic check that runs on every answer before a judge is needed. It is the "grounding" step the authors of this library shipped inside a Census data agent, extracted so anyone can use it.
+
+## What counts as grounded
+
+Every substantive number in the text must be within a tolerance (default 1.5 percent) of something the rows could legitimately produce:
+
+| Derivation | Example | Explanation you get back |
+|---|---|---|
+| cell | "39,346,023 people" | `pop[California] = 39,346,023` |
+| column sum | "together, 1,000,000 residents" | `sum of pop over 3 rows = 1,000,000` |
+| adjacent-cell sum | "the three youngest bands total 1,200" | `a..c[row 0] summed = 1,200` |
+| difference | "10.7 million more than Texas" | `pop[California] − pop[Texas] = ... = 10,710,581` |
+| ratio | "3.0 to one" | `a[row 0] ÷ b[row 0] = 3` |
+| percent | "72.8% of California" | `pop[Texas] ÷ pop[California] = 72.8%` |
+| percent change | "grew 2.3%" | `(y2020 − y2019) ÷ y2019 = 2.3%` |
+
+Differences, ratios, and percentages are searched within a row and across rows. A stated range such as "between 39 and 40 million" is grounded when a candidate lies inside it. Numbers at or below 100 and bare four-digit years are ignored by default, because "top 5 counties in 2020" is not a claim about the data.
+
+Two rules keep the search honest. A figure written as a percentage is searched as `a ÷ b × 100`, and a plain figure as `a ÷ b`, never both, so "150" cannot pass by coincidentally matching a 150% share. And the pairwise and adjacent-cell derivations cover the first `max_rows` rows (12 by default), which is the part of a result a model has usually read; cells and column sums cover every row. Raise `max_rows` if your prompt includes more.
+
+Each grounded figure carries the derivation that matched, so a reviewer can check it by hand. Each ungrounded figure is named. Nothing blocks: you decide whether to append the caveat, change a badge, or fail a test.
+
+## What it reads
+
+`trace(text, rows)` accepts the rows in whatever shape you already have:
+
+- a list of dicts, as most drivers and ORMs return
+- a list of lists or tuples, with or without column names
+- a `{"columns": [...], "rows": [...]}` mapping
+- a pandas DataFrame
+- a DB-API cursor after `execute`
+- several result sets at once: `trace(text, results=[rows_a, rows_b])`
+
+Numeric strings in the rows are parsed by default, so `"39,346,023"`, `"$1,200"`, and `"12%"` all count. Decimals from database drivers are handled. Booleans are not numbers.
+
+## Text it understands
+
+Thousands separators, decimals, scientific notation (`1.2e6`), currency symbols, scale words (`39.3 million`, `2.5bn`, `3k`), percent markers (`12%`, `12 percent`, `3 percentage points`), negatives, and ranges with a shared unit (`40 to 50 million`). Identifiers such as `B01003e1` or request ids are not mistaken for numbers, and ordinals are skipped.
+
+## Tuning
+
+```python
+from figured import trace, Policy, STRICT, LENIENT
+
+trace(answer, rows, rel_tolerance=0.005)  # tighter rounding
+trace(answer, rows, unmatched_percent="flag")  # a percentage must match something
+trace(answer, rows, derivations={"cell", "column_sum"})  # no pairwise arithmetic
+trace(answer, rows, policy=STRICT)  # 0.5%, percentages must match, checks down to 10
+trace(answer, rows, ignore_below=0, ignore_years=False)
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `rel_tolerance` | 0.015 | relative error allowed, covers rounding to three significant figures |
+| `abs_tolerance` | 0 | absolute error allowed in addition |
+| `ignore_below` | 100 | figures at or below this are counts of things, not claims |
+| `ignore_years` | True | bare four-digit integers in `year_range` are skipped |
+| `unmatched_percent` | "pass" | shares of totals outside the rows are common, so a lone percentage passes |
+| `max_rows`, `max_cells` | 12, 40 | how much of the result feeds the pairwise and adjacent-sum search |
+| `derivations` | all seven | which candidate kinds are generated |
+| `parse_strings` | True | coerce numeric strings in the rows |
+
+## Speed
+
+Measured with `python benchmarks/bench.py` on a laptop, one answer with nine figures:
+
+| Result set | Time per check |
+|---|---|
+| 2 rows × 3 columns | 150 µs |
+| 12 rows × 5 columns | 360 µs |
+| 200 rows × 10 columns | 1.1 ms |
+| 2,000 rows × 10 columns | 9 ms |
+
+Nothing is enumerated up front. Cells and column sums are indexed once; differences, ratios, percentages, and percent changes are found per figure by solving for the partner cell and bisecting for it. Explanations are formatted only for the figure that matched. For comparison, a model-based faithfulness judge takes seconds and costs a request.
+
+## Command line
+
+```bash
+figured "California has 39.3 million people." --rows rows.json
+figured - --rows rows.json < answer.txt
+figured "..." --rows rows.json --json --tolerance 0.01 --strict-percent
+```
+
+Exit code 1 when any figure is untraceable, so it can gate a pipeline step.
+
+## Using it in a pipeline
+
+**After every answer**, append the caveat and flip a badge:
+
+```python
+report = trace(answer, rows)
+if not report.ok:
+    answer += "\n\n" + report.caveat()
+    badge = "check figures"
+```
+
+**In promptfoo**, as a Python assertion: see `examples/promptfoo_assert.py`.
+
+**In DeepEval or any custom metric**, wrap `trace` and return `1 - len(report.ungrounded) / report.checked`.
+
+**With a model judge for the rest.** Arithmetic cannot see a wrong word around a right number: "Nevada is richer than Utah" with the two correct medians reversed passes. The optional `judge` extra sends the question, the rows, and the answer to a model and returns a strict verdict on faithfulness, responsiveness, and caveats:
+
+```bash
+pip install "figured[judge]"
+```
+
+```python
+from figured.judge import judge
+
+judge("Which state is richer?", answer, rows)  # {"verdict": "fail", "issues": ["comparison reversed"], ...}
+```
+
+## What it does not do
+
+- It cannot catch a correct number attached to the wrong claim. That is what the judge extra is for.
+- With large result sets the derived set is big, and a hallucinated figure can land within tolerance of some difference by coincidence. The defaults cap the pairwise search at 12 rows and 40 cells; tighten the tolerance or restrict `derivations` for sensitive uses. A flag on a correct figure is treated as the worse error, because people stop reading badges that cry wolf.
+- Numbers written as words ("two million") are not extracted.
+- It does not know what the rows mean. If the agent queried the wrong column and described it faithfully, every figure traces.
+
+## How it compares
+
+| | rows as evidence | derived arithmetic | deterministic | names each figure | packaged |
+|---|---|---|---|---|---|
+| **figured** | yes | sums, differences, ratios, percentages, ranges | yes | yes, with the derivation | pip, zero deps |
+| llmground | no, a source string | no | yes | yes | pip |
+| @demystify/grounding | no, cited facts | no | yes | yes | npm |
+| pcn-core (Proof-Carrying Numbers) | claim values you supply | no | yes | yes, needs model-emitted tags | pip |
+| NumProof | yes | yes | yes | yes | hosted API |
+| DeepEval / Ragas faithfulness | text context | n/a | no, LLM or NLI | no | pip |
+
+The Proof-Carrying Numbers policy vocabulary (exact, rounded, scale alias, tolerance, percent, range, year) is the clearest statement of the matching problem, and this library borrows its shape. The difference is the evidence contract: rows in, free text in, no cooperation from the model required.
+
+## Ports
+
+Behavior is pinned by the conformance vectors in `tests/vectors/`. A port in another language is correct when it passes them unchanged. A TypeScript port is the natural next one; open an issue if you want to take it.
+
+## Origin
+
+Built inside a Census data agent whose answers had to be traceable to the ACS rows behind them. The first version only derived values within a row, so a correct "about $10,900 higher" comparison across two state rows was flagged as suspect. That false flag is now a named test vector, and it is why the defaults lean toward trusting the model when the arithmetic works out.
+
+## License
+
+MIT.

figured-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+figured/__init__.py,sha256=KfstOh4RrhIVyLWctCyq-mqm3ViEQPTINEo5wKVagyM,801
+figured/__main__.py,sha256=X5TxIAVDwbQeZZIKqSIRL9-o_7TyfR69olsPbLxit_U,1561
+figured/core.py,sha256=TSQZGNvTmpltU0CihpaFU6YAl5761tI52xb0GsJvn4Q,2576
+figured/derive.py,sha256=idVOAY57JFrkEwCHZzvZz3_e7OcNVyX8vur3zZCriks,13774
+figured/evidence.py,sha256=b2_aqiqjAc9o2IwSnq1qQS9NIQLVzuJb6YQAANxiYFM,6652
+figured/extract.py,sha256=WyWxPX6edy-tvMJtTAnJuvJx2VWaJmlnvuB3Rx862Us,4632
+figured/judge.py,sha256=H36V2fsR6uNZeX7iP1vLVSQUocxQJ8LGNRLv2wSLZCs,2677
+figured/policy.py,sha256=ScBM63WDvUZO2Q0PEfiB5QBUzSAZzlMuNnyKUW9TpFQ,2557
+figured/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+figured/report.py,sha256=nrA-Uic7OmhU9cNAbPP8CW48nk9NdGlanhnKy55Fhog,3213
+figured-0.1.0.dist-info/METADATA,sha256=c4hYUZmSJPfK48QQNlXSSBjJ0K7MjorHqyJl7xoZ-5s,11207
+figured-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+figured-0.1.0.dist-info/entry_points.txt,sha256=mh91KVuIvpJy6DIGjjsmEcuJaOGMoldaFyyRXdSgW7Q,50
+figured-0.1.0.dist-info/licenses/LICENSE,sha256=SHGKk_adXxNMC1rM63eWqTyDr6nbLVzVZcMi7OReWNA,1071
+figured-0.1.0.dist-info/RECORD,,

figured-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

figured-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+figured = figured.__main__:main

figured-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nishesh Shukla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.