What GroundLens is

GroundLens is an execution verification runtime for AI systems and agents. It turns observable AI execution into deterministic, policy-governed evidence that can be independently verified. It provides a vendor-neutral runtime and evidence protocol for observing AI executions, evaluating claims, tool calls, actions and outcomes against composable verifiers and policies, and producing signed, reproducible evidence records.

You don't have to trust GroundLens. You can verify the record

The unit is the execution: an ordered sequence of steps an AI system or agent takes, from a model call and a retrieval to a tool call, an action with side effects and a human approval. GroundLens records each step, checks it, decides, and seals the run into a signed record anyone can verify offline. Verifying a single answer is the smallest case, a run with one claim.

• an answer, and the claims inside it → PASS, REVIEW or FAIL
• a tool call or an action → ALLOW, REVIEW or DENY

Where a guardrail blocks or scores an output in the moment and leaves nothing behind, GroundLens leaves signed, hash-chained evidence a third party can check without trusting you. It runs locally, needs no access to your weights, prompts or architecture, and is built for teams shipping AI answers and agents into regulated or high-stakes workflows who need proof, not a score.

Verification Suite

You can verify the record yourself. The suite is how: checks anyone can run, in four parts, none of them a single "trust score".

• Conformance — does GroundLens do what it says? Seven contracts (evidence, policy, determinism, integrity, tamper detection, offline verification, scope), PASS or FAIL each: python suite/conformance.py
• Performance — latency, record size and throughput, as per-property percentiles: python suite/performance.py
• Interoperability — the same record verified by the Python API, the command line and an independent from-scratch verifier; a tampered record rejected by all three: python suite/interoperability.py
• Verifier evaluation — detection metrics for the individual verifiers, which are swappable. This measures the verifiers, not the infrastructure.

Every check traces to a public standard, RFC or regulation (Ed25519, SHA-256, canonical JSON, append-only logs, SLSA, C2PA, W3C Verifiable Credentials, EU AI Act Art. 12 and 15). See suite/STANDARDS.md. Full suite in suite/.

$ python suite/conformance.py
PASS  Evidence generation      PASS  Record integrity       PASS  Offline verification
PASS  Policy semantics         PASS  Tamper detection       PASS  Scope boundaries
PASS  Decision determinism
ALL CONTRACTS PASS

$ python suite/interoperability.py
Python API, command line and an independent verifier all accept the genuine record
all three reject a tampered record
PORTABLE AND INDEPENDENTLY VERIFIABLE

Quick start

pip install groundlens

The package installs the engine, the groundlens and glv commands, and needs no other dependency. Numbers and rules are checked out of the box; the model-based verifiers need one optional download, shown at the end.

Verify an answer

Check a model's answer against the sources it was given, under a policy, and get a record you can keep.

from groundlens import verify

question = "What is the invoice total?"
source   = "The total amount due is 10,000 dollars, payable within 30 days of receipt."
answer   = "The invoice total is 1,000 dollars, due in 30 days."

record = verify(answer, [("invoice.pdf#p1", source)], question=question)

print(record.decision)     # 'FAIL'
print(record.report())

FAIL  policy=groundlens_default_v1  record=rec_350455f44e60_4dbfea8eb79c
  c2   groundlens.numeric   contradicted   0.00   nearest in invoice.pdf#p1: '10,000 dollars'

Ten thousand is not one thousand. A similarity score would rate the right answer and the wrong one alike; the numeric verifier compares the quantities exactly and points at the source number the answer lost to. The 30 days are supported in both, so they do not appear in the report: it shows only what a reviewer needs to look at.

Every verification is sealed:

record.content_hash            # 'sha256:…' — same input, policy and bundle → same hash, any machine
record.verify()                # recompute every hash and the Ed25519 signature, offline; raises if altered
record.regulatory_mapping      # the articles this decision concerns, under the policy

Verify a run

Give GroundLens an MCP execution trace and an execution policy. It records the run as a hash-linked event log, gates it, and seals a signed run record.

from groundlens import verify_run

record = verify_run(
    "examples/run/trace.jsonl",            # an MCP session, as JSON-RPC lines
    "examples/run/execution-policy.yaml",  # the rules for what the agent may do
    run_id="run_demo",
    system="invoice-agent",
)

print(record.gate)         # 'DENY'  — the run called shell.exec, which the policy forbids
print(record.breaches)     # ()      — nothing *ran* against the policy; the call was denied, not executed
print(record.record_hash)  # 'sha256:…'  — signed and chained, like an answer record

gate is the verdict over the whole run: ALLOW, REVIEW or DENY, rolled up from the strictest step. breaches is different and narrower: it lists actions that actually executed against the policy, an action the policy forbade or one that needed a human approval that never came. Here the forbidden tool was stopped, so the run is DENY with no breach. The same thing on the command line, with the real output:

glv run verify --trace examples/run/trace.jsonl --policy examples/run/execution-policy.yaml \
  --run-id run_demo --system invoice-agent --log runs.jsonl
# exit code 1  (0 ALLOW · 3 REVIEW · 1 DENY)

glv run check runs.jsonl
# ok  1 run records, chain intact, all signatures verify

A runnable version of both is under examples/run.

Enable the model-based verifiers

The numeric and rules verifiers need nothing. The lexical, semantic and NLI verifiers need the base bundle: the multilingual encoder and a multilingual entailment model, their tokenizers, and a manifest of hashes.

groundlens bundle pull base      # downloaded once; the only command that uses the network

With the bundle installed, the lexical verifier runs (one row per content word, each anchored to the source word it was scored against), and so do the semantic verifier (sentence similarity to the nearest source) and groundlens.nli (entailment, neutral or contradiction for each statement). The download is verified against a hash pinned in the engine.

from groundlens import verify

record = verify(
    "El importe de la factura es de 10.000 euros, pagaderos en 30 días.",
    [("factura", "El importe total asciende a 10.000 euros, pagaderos en un plazo de 30 días.")],
    locale="es",
)

for e in record.evidence:
    if e.verifier_id == "groundlens.lexical":
        print(e.result, round(e.score, 2), e.source_text)