GroundLens

Guardrails for LLM answers

GroundLens checks AI answers against your documents: the figures, who they are about, and whether they answer the question.

On financial answers it had never seen, it stopped 3 of 4 wrong ones; on public claims with numbers, half of the unsupported ones. About 10 ms per check, deterministic, no LLM in the loop. 1

🤔 Already running an LLM‑as‑judge? Keep it. GroundLens runs the exact checks first, and a FAIL never reaches the judge. Your judge only sees the answers the exact checks could not reject.

Deterministic Exact checks first, no LLM judge needed

Provable PASS, REVIEW or FAIL, with a signed record

Measured Measure the error rate of what passes, on your answers

Portable Rust engine: the same hash on every OS

Works with

Quickstart

# pip install groundlens

import 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:

Langfuse · pip install "groundlens[langfuse]"

from langfuse import get_client

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

Call check inside the observation that produced the answer, and its trace gets:

• Score `groundlens.decision`: categorical, PASS, REVIEW or FAIL, on the check and on its trace. Filter traces by it, chart it, export it.
• Observation `groundlens.check`: type guardrail. The reasons are its status message, one per line. Its level follows Langfuse's own scale: PASS is DEFAULT, REVIEW is WARNING, FAIL is ERROR.
• Metadata of the check: decision, reason codes (groundlens.scope.contradicted), policy, and the id and hash of the signed record behind it.
• Judge: a generation observation with the model name, next to your own model calls.
• Spans: one per verifier, plus the store, each with its duration. Log View shows them in milliseconds.
• SDK: Python v3 and v4. Tested on Langfuse Cloud and self-hosted Langfuse 4.58.

Grafana and OpenTelemetry · pip install "groundlens[otel]"

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

Spans and metrics go through the providers your application already configured: Tempo, Prometheus, or any OpenTelemetry backend.

• Metrics: groundlens_decisions_total{decision, policy}, groundlens_reasons_total{reason, decision}, groundlens_check_duration_seconds{stage} with stage total, engine, judge, sign, store.
• Spans: groundlens.check with groundlens.decision, groundlens.reasons, record id and hash; children per verifier, the judge (gen_ai.*) and the store.
• Dashboard: the one in the image. gl.integrations.grafana_dashboard() returns the path of its JSON; import it in Dashboards → New → Import.
• PromQL, share of answers that failed:

  sum(rate(groundlens_decisions_total{decision="FAIL"}[15m])) / sum(rate(groundlens_decisions_total[15m]))

• Alert when more than 5 % fail:

  - alert: GroundLensFailRateHigh

expr: sum(rate(groundlens_decisions_total{decision="FAIL"}[15m])) / sum(rate(groundlens_decisions_total[15m])) > 0.05 for: 10m

• Try it: docker run -p 3000:3000 -p 4318:4318 grafana/otel-lgtm, then python examples/observability/credit_copilot.py grafana --minutes 5. Tested on Grafana 12 with Tempo and Prometheus.

Claude, Codex, Cursor, VS Code and other MCP clients · uvx --from "groundlens[mcp]" groundlens mcp

Your assistant checks its own draft before it answers. Three read-only tools over stdio: verify_answer, verify_run, verify_records. Needs uv.

• Claude Code (plugin: the MCP server plus a skill that tells Claude when to check):

  claude plugin marketplace add groundlens-dev/groundlens

claude plugin install groundlens@groundlens

• Codex:

  codex mcp add groundlens -- uvx --from "groundlens[mcp]" groundlens mcp

• Any MCP client (Claude Desktop, Windsurf, Zed...):

  { "mcpServers": { "groundlens": { "command": "uvx", "args": ["--from", "groundlens[mcp]", "groundlens", "mcp"] } } }

With the package installed (pip install "groundlens[mcp]"), "command": "groundlens-mcp" is enough.

• Nothing to install: the Hugging Face Space is also a remote MCP server, with verify_answer, at https://groundlens-groundlens.hf.space/gradio_api/mcp/.

OpenClaw · clawhub install groundlens

A skill on ClawHub, the skill registry of OpenClaw. Before your assistant sends an answer with figures taken from your documents, it runs groundlens verify on its draft:

• PASS: the answer goes out.
• FAIL: it fixes the figure from the source and checks again.
• REVIEW: the answer goes out, saying which figure it could not confirm.

Runs on your machine, with no API key and no second model. The skill is in plugins/groundlens/skills/groundlens, the same one the Claude Code plugin uses. OpenClaw can also use the MCP server directly, with openclaw mcp add.

Where records are kept · sink=

check() returns only after the signed record is stored. If it cannot be stored, check() raises and no decision comes back. Each sink keeps a chain: every record carries the hash of the one before it.

impo