open source · Apache-2.0

Groundlens checks what an answer tells people they have to do.

Obligations, deadlines, amounts and citations, compared with your own sources and your own rules.

Runs offline. No model in the path. Same inputs, same decision.

$pip install groundlens
Read the docs See a rule pack
the answer under check

“You must call us before you travel abroad. The annual fee is 45,00 EUR.”

escalate
BNK-001  the answer says ‘45,00 EUR’, the source says EUR 30
BNK-020  the answer tells the reader they must call, no source says that
BNK-031  a required disclosure block is missing
Two decisions, clear or escalate. Each finding names the rule and the words it came from.
Install & first check

One answer, its sources, your rules. Clear, or send it to a person.

There is no score and no threshold. A number between zero and one invites somebody to move the line later, and a control whose line moves is not a control. The only runtime dependency is pyyaml.

Read the quickstart
first_check.py 
from datetime import date
from groundlens import check

result = check(
    answer,
    [{"id": "terms.pdf#p2", "text": source_text}],
    ruleset="eu-retail-banking",
    metadata={"product_type": "credit-card",
              "disclosure_set": "es-2026"},
    reference_date=date(2026, 8, 8),
)

print(result.decision.value)
for f in result.findings:
    if f.severity.value == "fail":
        print(f.rule_id, f.message)

# escalate
# BNK-031 Required disclosure block present.
# BNK-020 The answer tells the reader 'You must call
#         us before you travel abroad', and no source
#         says that.
What it checks

An answer can be well written, well sourced, and still tell somebody the wrong thing they have to do.

A generated answer turns a “may” into a “must”, moves a deadline by a week, restates an amount that no document contains, or cites a section nobody supplied. Groundlens pulls those statements out of the answer as typed, checkable facts, each with the exact words it came from, and compares every one of them against the sources you passed and the rules you wrote.

Obligations
must · must not · may · need not · should

The five strengths are ranked, so an answer that is firmer than the evidence behind it is a finding, not a rounding error.

Deadlines and dates
within 14 days · by 31 March

Business days are not calendar days. Relative dates resolve against a date you pass in, never against the clock.

Amounts and rates
currency · number · percent

Compared as decimals, never as floats, and read through the pack’s locale rather than the machine’s.

Citations
article · section · clause

A citation has to resolve to a source you actually passed. Same instrument, wrong article, is caught.

The rules are a file, not code

A rule pack is YAML. Somebody who does not write Python can read it, diff two versions of it and sign the diff. Its identity is the hash of its bytes, and that hash goes into every record.

If a pack says the caller has to declare the product type and the caller does not, the answer escalates. There is no flag to switch that off.

The same inputs give the same answer tomorrow

No floating point in the decision path. No wall clock. No locale read from the environment. No randomness. Reruns reproduce the record byte for byte, and each row of the log is hashed against the row before it.

That is a property of the tool. It is not a claim about what any regulation requires of you.

What this is not

If you want to know how well an answer matches its source, use one of these instead.

Groundlens is narrow on purpose. It is not a hallucination detector and it does not produce a factual consistency score. Every tool below is good at the job next to it, and several teams will want Groundlens alongside one of them rather than instead of one.

You need Use Why it is better at this
Which words in an answer the retrieved text does not support LettuceDetect MIT, one pip install, runs offline with no LLM, returns token level spans over the whole answer. This is the general groundedness job and it does it well.
One number for how well a summary sticks to its source Vectara HHEM An open model built and tuned for exactly that score.
Metrics over a test set while you tune a RAG pipeline RAGAS, DeepEval Faithfulness, answer relevancy, context precision, dataset runners, CI reporting. Groundlens has none of that.
A managed service inside your cloud Azure AI Content Safety Hosted, supported, no weights to ship, and it covers the input side too.
Proof that a claim follows from an encoded policy AWS Bedrock Automated Reasoning checks Real logical verification against a policy model, with immutable numbered policy versions.
To measure how often a model hallucinates HalluLens A benchmark, which is a different thing from a control in a live pipeline.
It does not measure truth

If a claim is wrong and every source agrees with it, Groundlens clears it.

It does not read prose for meaning

A defect written in words it does not extract will pass. It catches what a pack asks for and nothing else.

It does not cover the input side

Prompt injection, harmful content and jailbreaks are somebody else’s job.

Research

Where Groundlens started, and the finding that moved it on.

Groundlens began as geometry. SGI and DGI measure where an answer sits relative to its question and to its source, with no model call, and they rank an answer that ignored the document it was given. That work is now optional and lives behind pip install "groundlens[geometry]".

The limit, from our own work. Hold the questions fixed and change only how a wrong answer is written. Detectability tracks how closely the wrong answer matches the register of the right one, and it falls toward chance as the two converge. A wrong value written in exactly the right style is close to invisible to any detector built on a single frozen sentence embedding.

That result is why the product moved to typed statements and written rules. A “must” where the source says “may” is in perfect register and geometry cannot see it. Read as a string, it is plain.

Five arXiv preprints. Each has been revised in response to reviews. None is a peer-reviewed publication.

Semantic Grounding Index — geometric bounds on context engagement in RAG systems arXiv:2512.13771 → A Geometric Taxonomy of Hallucinations in LLMs arXiv:2602.13224 → How Transformers Reject Wrong Answers — rotational dynamics of factual constraint arXiv:2603.13259 →
The Outer Geometry of Truth — register alignment and the limits of embedding-based detection preprint
The Geometry of Validity preprint
Geometry quickstart → Benchmarks → Source →
Integrations

Drop it into the stack you already run.

Check every answer where it is produced, hold the ones that escalate, and keep the record.

LangChain LangGraph CrewAI Semantic Kernel AutoGen
Claude · GPT · Gemini for the cases that escalate.
In your editor, the MCP server

The same check inside Claude, Cursor, and VS Code, with no model in the path.

groundlens-dev/groundlens-mcp →
Data handling

No server. No account. Runs on your infrastructure.

Read DATA_HANDLING.md
  • —The check runs on your machine. It never sends your data out.
  • —API keys are yours; calls go direct to the provider you choose.
  • —No telemetry. Same inputs, same decision. Metadata values never reach the record, only the key names.
Who maintains it

Javier Marín created the method and the library. Published in the open, maintained in the open. Five arXiv preprints are the method on the record. Each has been revised in response to reviews. None is a peer-reviewed publication.

GitHub → LinkedIn → javier@groundlens.dev
Fund the work

One person maintains this in the open. If it checks answers you ship, funding buys more of it and keeps it free for everyone else.

Support on Manifund