figured 0.1.0__tar.gz

figured-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy
+      - run: pytest --cov=figured --cov-report=term-missing --cov-fail-under=95

figured-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Check that the tag matches the package version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          test "$tag" = "$version" || { echo "tag v$tag does not match version $version"; exit 1; }
+      - run: pip install -e ".[dev]" build
+      - run: ruff check . && mypy && pytest -q
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

figured-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+coverage.xml
+htmlcov/
+.DS_Store

figured-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- `trace(text, rows)` checks every number in a text against the rows it was written from.
+- Derived values: column sums, adjacent-cell sums, differences, ratios, percentages, and percent change, within and across rows.
+- Number extraction with thousands separators, decimals, scientific notation, currency, scale words, percent markers, and ranges.
+- Evidence from lists of dicts, lists of sequences, `{columns, rows}` mappings, pandas DataFrames, and DB-API cursors, with numeric-string parsing.
+- Per-figure report with the matching derivation spelled out, a one-line caveat, JSON output, and a CLI that exits non-zero on untraceable figures.
+- Optional `[judge]` extra for a model-based second opinion on comparative words.
+- Language-neutral conformance vectors in `tests/vectors/`.

figured-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+```bash
+git clone https://github.com/nisheshshukla/figured
+cd figured
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+CI runs ruff, mypy in strict mode, and pytest with a 95 percent coverage gate on Python 3.10 through 3.13.
+
+`python benchmarks/bench.py` prints the time per check at several result-set sizes. A change that makes the typical case slower needs a reason in the pull request.
+
+## Adding a case
+
+Most behavior changes should start as a conformance vector in `tests/vectors/`. Each vector is a text, some rows, an optional policy, and what the report must say. Vectors are language-neutral so that ports in other languages can be held to the same behavior.
+
+## Design rules
+
+- No runtime dependencies. Optional integrations live behind extras.
+- The check must stay deterministic: no model calls, no clock, no network inside `trace`.
+- A false flag is worse than a miss. When in doubt, add a derivation or a tolerance knob rather than a stricter default.
+- Every grounded figure must carry an explanation a person can verify by hand.
+
+## Releasing
+
+Releases are published to PyPI by the `release` workflow through trusted publishing, so no API token is stored anywhere.
+
+One-time setup, by the repository owner:
+
+1. On pypi.org, under your account's Publishing settings, add a pending publisher: project `figured`, owner `nisheshshukla`, repository `figured`, workflow `release.yml`, environment `pypi`.
+2. In the GitHub repository settings, create an environment named `pypi`.
+
+Each release:
+
+1. Bump `version` in `pyproject.toml` and add a section to `CHANGELOG.md`.
+2. Commit, then tag and push: `git tag v0.1.0 && git push origin main --tags`.
+
+The workflow refuses to publish when the tag and the package version disagree.

figured-0.1.0/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.

figured-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,176 @@
+# 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/benchmarks/bench.py

@@ -0,0 +1,52 @@
+"""Run: python benchmarks/bench.py  — microseconds per trace() across result-set sizes."""
+
+from __future__ import annotations
+
+import random
+import statistics
+import time
+
+from figured import trace
+
+random.seed(7)
+
+TEXT = (
+    "California has 39.3 million people (39,346,023), about 10.7 million more than Texas, "
+    "which is 72.8% of its size. Median income is $79,243, roughly $10,940 above Nevada, "
+    "and the region grew 2.3% while 12% of households moved. Together they hold 68 million."
+)
+
+
+def rows(n: int, cols: int) -> list[dict[str, float | str]]:
+    out = []
+    for i in range(n):
+        r: dict[str, float | str] = {"name": f"row{i}"}
+        for c in range(cols):
+            r[f"c{c}"] = float(random.randint(1_000, 50_000_000))
+        out.append(r)
+    out[0].update({"c0": 39346023.0, "c1": 28635442.0, "c2": 79243.4})
+    if n > 1:
+        out[1].update({"c0": 68303.1, "c1": 220000.0, "c2": 225060.0})
+    return out
+
+
+def bench(label: str, data: object, reps: int) -> None:
+    times = []
+    for _ in range(reps):
+        t = time.perf_counter()
+        trace(TEXT, data)
+        times.append(time.perf_counter() - t)
+    med = statistics.median(times) * 1e6
+    print(f"{label:<28} {med:9.0f} µs   (min {min(times) * 1e6:7.0f} µs)")
+
+
+if __name__ == "__main__":
+    bench("2 rows × 3 cols", rows(2, 3), 300)
+    bench("12 rows × 5 cols", rows(12, 5), 200)
+    bench("200 rows × 10 cols", rows(200, 10), 50)
+    bench("2,000 rows × 10 cols", rows(2000, 10), 10)
+    bench("2,000 rows, max_cells=400", rows(2000, 10), 5) if False else None
+    print()
+    t = time.perf_counter()
+    r = trace(TEXT, rows(2000, 10), max_cells=400)
+    print(f"{'2,000 rows, max_cells=400':<28} {(time.perf_counter() - t) * 1e6:9.0f} µs   ok={r.ok}")

figured-0.1.0/examples/basic.py

@@ -0,0 +1,19 @@
+"""Run: python examples/basic.py"""
+
+from figured import trace
+
+rows = [
+    {"state": "California", "population": 39_346_023, "moe": 79_849},
+    {"state": "Texas", "population": 28_635_442, "moe": 65_120},
+]
+
+answer = (
+    "California has about 39.3 million people (±79,849), roughly 10.7 million more than Texas. "
+    "Texas is 72.8% of California's size. Combined they hold 68 million people, "
+    "and about 4.1 million of them moved last year."
+)
+
+report = trace(answer, rows)
+print(report.explain())
+print()
+print(report.caveat() or "Every figure traced.")

figured-0.1.0/examples/promptfoo_assert.py

@@ -0,0 +1,39 @@
+"""A promptfoo Python assertion.
+
+In promptfooconfig.yaml:
+
+    tests:
+      - vars:
+          question: "What is the population of California?"
+          rows: [{"state": "CA", "population": 39346023}]
+        assert:
+          - type: python
+            value: file://examples/promptfoo_assert.py
+
+promptfoo calls get_assert(output, context) and uses the returned dict.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from figured import trace
+
+
+def get_assert(output: str, context: dict[str, Any]) -> dict[str, Any]:
+    rows = context.get("vars", {}).get("rows", [])
+    report = trace(output, rows)
+    return {
+        "pass": report.ok,
+        "score": 1.0 if report.ok else max(0.0, 1 - len(report.ungrounded) / max(report.checked, 1)),
+        "reason": report.caveat() or f"{report.checked} figures traced",
+        "componentResults": [
+            {
+                "pass": r.status != "ungrounded",
+                "score": 1.0 if r.status != "ungrounded" else 0.0,
+                "reason": r.literal,
+            }
+            for r in report.results
+            if r.status != "ignored"
+        ],
+    }