GroundLens

Quickstart

# pip install groundlensimport groundlens as gl
verifier = gl.Verifier(sink=gl.sinks.jsonl("records/"))record = verifier.check(answer="Revenue was €42.1 million.", passages=["Revenue reached €41.2 million."])print(record.decision, record.reasons)

FAIL ['c2: groundlens.numeric contradicted: €42.1 million not in sources; nearest 41200000 EUR in ctx-0 (relative distance 0.021)']

Runs locally: no account, no API key, no model, no network. The signed record is in records/ before check returns.

Integration

The same check, wired into your stack:

from langfuse import get_clientverifier = gl.Verifier(sink=gl.sinks.jsonl("records/"), observers=[gl.integrations.langfuse(get_client())])

verifier = gl.Verifier(sink=gl.sinks.jsonl("records/"), observers=[gl.integrations.otel()])

import boto3verifier = gl.Verifier(    signer=gl.signers.aws_kms(boto3.client("kms"), key_id),           # the key never leaves KMS    sink=gl.sinks.s3_object_lock(boto3.client("s3"), "audit-records", retain_days=3650),)

LLM-as-a-judge

The exact checks catch a figure that is wrong, miscalculated, from another company or of another kind than asked. They cannot catch a real figure taken from the wrong row of the right table, or a sentence the passages never say. For that you connect a model that reads: the judge. GroundLens ships no model; you pass the client you already use.

from openai import OpenAI
verifier = gl.Verifier(    "credit_desk.yaml",                                       # a policy that allows a judge, below    judge=gl.judges.openai_compatible(OpenAI(), "gpt-4.1"),    sink=gl.sinks.jsonl("records/"),)

The shipped policies forbid a judge, so the policy that uses one says so:

id: credit_deskversion: 1.0.0extends: eu_ai_act_high_risk_v1verifiers:  forbidden: []          # allow llm_judge.*judge:  required: true         # no judge, or a judge that fails: REVIEW  contradicted: REVIEW   # or FAIL  unsupported: REVIEW

The judge can escalate, never pass. It labels each sentence supported, unsupported, contradicted or uncertain. supported resolves nothing on its own, so a judge that is wrong, or that a passage has talked into agreeing, cannot let through an answer the exact checks fail. A timeout, an error or a malformed reply is REVIEW.

You see exactly what it is sent. One prompt per answer, from a fixed template (groundlens.judge/1): what PASS means for you, the scope, the question, the answer and every passage with its provenance. Passages sit between markers they cannot contain, so text inside them is data, not instructions. groundlens judge show-template prints the exact prompt before anything is sent anywhere.

The record keeps the trail. The template id, the hash of the prompt, the model the provider says answered and the hash of its reply, with each sentence's label, the passages it cited and its one-line reason. In Langfuse the judge appears as a generation, next to your own model calls.

Architecture

GroundLens splits verification into five parts that never mix: claims, verifiers, evidence, policy and record.

1. The answer is cut into claims: each figure and each sentence, with its character offsets.
2. Verifiers examine each claim against the passages and return evidence (supported, contradicted, unsupported), never a verdict. The shipped ones are exact: numeric (exact fractions, locales, units, recomputed sums and ratios), scope, intent, and your rules. The judge, if you connect one, is the model you already use, asked through a fixed template.
3. The evidence graph keeps what each verifier said about each claim, and where they disagree.
4. The policy, a YAML file you own, turns evidence into a decision: PASS, REVIEW or FAIL, with reasons.
5. The record holds the input hash, the evidence, the policy hash and the decision, chained to the previous record and signed. It is stored before check returns; observers are told after.

The engine is Rust, shipped as a Python wheel (abi3, Python 3.10+), with a standalone glv binary that checks records without Python. It runs in your process: no server, no network, no runtime dependencies. From Rust, cargo add groundlens; for the binary, cargo install groundlens-cli.

Parameters

Policy

The checks produce evidence. The policy decides what that evidence means for you: what fails, what goes to a person, and what PASS allows. It is a short YAML file that you own and version with your code. The same answer under two policies can get two different decisions, and both are correct; that difference is your risk appetite, written down.

Two policies ship with GroundLens:

Write your own policy

Extend a shipped policy and write only what differs:

id: credit_deskversion: 1.2.0extends: eu_ai_act_high_risk_v1pass_means: "may be shown to the analyst as a summary of the filing"locale: es-ES                     # how the documents write numbers: 1.234,56rounding: half_even               # how a recomputed figure may roundscope:  required: [entity]              # every request must name the borrower  missing_scope: REVIEW           # or FAIL; never PASSrisk_classes:  default: credit_information  mandatory_review: [credit_limit_change]   # always seen by a person

verifier = gl.Verifier("policies/credit_desk.yaml")verifier.check(answer=a, passages=p, scope={"entity": "Talleres Norte"}, risk_class="credit_limit_change")

Unknown keys are errors, not ignored: a misspelt rule never silently does nothing.

Failure is not a PASS

The final decision is the worst outcome of all checks.

Check your policy

groundlens policy lint policies/credit_desk.yaml                # errors before you deploygroundlens policy show --resolved policies/credit_desk.yaml     # every default filled in

The hash of the resolved policy goes into every record it decides, so each decision can be traced to the exact rules that produced it.

Before you change a policy,you have to measure it:

• groundlens measure estimates the share of wrong answers among those that passed, from a small sample your team labels without seeing the verdicts, with a 95 % confidence interval, per risk class, and the cost per decision.
• groundlens replay runs past traffic under the new policy and lists the decisions that would change.

Both reports are signed. Full reference: Writing policies.

Security

GroundLens sits on the path between a model and a decision, and its records are meant to be evidence. Both make it a target: an attacker may try to get a wrong answer through, or to alter the trail afterwards.

Report vulnerabilities privately through GitHub security advisories. See SECURITY.md.

Contributing

If GroundLens got one of your answers wrong, that case is the most valuable contribution there is. Checks, connectors and documentation are welcome too; CONTRIBUTING.md explains how to start.

Open source

Apache-2.0, all of it: engine, checks, policies, connectors, command line and MCP server. Verification evidence has to be checkable by anyone, without our software or our permission, and that only holds if the verifier is open.

Contact

You can contact the developer at [email protected]

_{1. GroundLens 6.0.5, default policy, no judge. Financial answers: 189 real answers by Claude Haiku from a RAG over FinQA 10-K pages (e5 embeddings, top 4 passages), on multi-step questions never used while developing GroundLens. Each answer labelled twice by a language model (Claude Opus 5.5, claude-opus-5-5) against fixed written criteria, blind to GroundLens, with a third pass on the 3 disagreements; labels were frozen before GroundLens ran. 22 answers were wrong (1 in 9): 17 got FAIL or REVIEW (77 %, 95 % CI 57–90 %). Of the 129 answers that passed, 5 were wrong (3.9 %, 95 % CI 1.7–8.8 %). The price: 60 of 189 answers (32 %) went to FAIL or REVIEW, including 38 of 110 correct ones. Median 10.6 ms per check in a fresh process. Public claims: LLM-AggreFact test split (29,320 claim–document pairs from 11 sets, human labels), never used while developing GroundLens. Of the 1,616 unsupported claims that contain a number, 796 got FAIL or REVIEW (49 %, 95 % CI 47–52 %); among the claims with a number that passed, 16.3 % were unsupported, against 25.4 % before the check. Claims without a number all passed: GroundLens caught none of their errors. Median 4.0 ms per check. All results, including the sets where it does not help, in BENCHMARK.md.}