Runnable notebooks applying Groundlens to real AI agent verification cases: what a deterministic stack can resolve on its own, and what it has to escalate.
Each notebook is self-contained: installs groundlens from PyPI, sets up the case, runs the geometric and rule-based layers, and produces an audit table a Model Risk Committee can read.
| Case | Domain | Methods run | Notebook |
|---|---|---|---|
| Banking decision-rationale governance: text-only vs mechanical enforcement | Credit / AML / KYC / sanctions | SGI, DGI domain-calibrated, groundlens_banking_rules (20 rules across 5 sub-scores) |
decision_rationale_eval.ipynb |
Each notebook answers the same question: what can a deterministic stack (geometry plus rules) resolve on its own, and what must it escalate?
Geometry does not substitute for an entailment check or a model judge on in-register content. That is its characterized blind spot, and it is measured: on confabulations that stay inside the register of a correct answer, every embedding-similarity method declines toward chance (classic encoders 0.62 to 0.68 AUROC, raw cosine 0.595), while an entailment cross-encoder does not (0.887). Holding authorship constant, the ceiling of the whole embedding-similarity class is in the high 0.6s.
What geometry substitutes for is volume. It runs on everything, deterministically, in milliseconds, for free, and it hands the expensive verifier a much smaller pile. The rule layer adds the checks a policy can express, with a citation per rule. What neither layer can settle, a plausible wrong figure inside a well-formed rationale, is escalated. That escalation is the point, and in a governance setting it is also the deliverable: a documented account of which cases went to a human and why.
See The Register Wall: What Similarity-Based Hallucination Detectors Actually Measure (under review) for the controlled evaluation.
There is no LLM-as-judge baseline in this repository. An earlier version of this README claimed that a deterministic stack could substitute for one "with domain calibration and a domain-specific rule set". That claim was not backed by anything in the repo, and it is withdrawn. If a judge comparison is added later, it will ship with the executed cells, the prompts and the labels.
Click the badge above. The devcontainer ships with Python 3.10 and groundlens pre-installed. Everything in the notebook runs locally: no API key is required.
git clone https://github.com/groundlens-dev/Groundlens-Cookbook
cd Groundlens-Cookbook
pip install --upgrade "groundlens>=2026.7.13"
jupyter notebook decision_rationale_eval.ipynb- Python 3.10+
groundlens >= 2026.7.13
The methods these notebooks apply are documented in:
- Marin, J. (2025). Semantic Grounding Index for LLM Hallucination Detection. arXiv:2512.13771
- Marin, J. (2026). A Geometric Taxonomy of Hallucinations in Large Language Models. arXiv:2602.13224
- Marin, J. (2026). Rotational Dynamics of Factual Constraint Processing in Large Language Models. arXiv:2603.13259
- Marin, J. (2026). Defendable Rules for LLM Rationale Evaluation in Banking Governance: A Multi-Source Provenance Framework. Preprint, available on request.
- Marin, J. (2026). The Register Wall: What Similarity-Based Hallucination Detectors Actually Measure. Under review. It supersedes the detection claims in the first two.
Apache 2.0. See LICENSE.