groundrails 1.0.31

Grounding guardrails for agentic RAG - deterministic claim verification

groundrails

Grounding guardrails for agentic RAG - deterministic, torch-free claim verification.

groundrails checks whether each claim in an answer is backed by your source, and tells you exactly where the support is - or flags it as a hallucination or contradiction. No LLM in the loop, runs on CPU, same answer every time.

Why

Agentic RAG can assert things its sources never said. The usual fix - a second LLM grading each claim - is slow, costs a model call per claim, is non-deterministic, and gives no reason for its verdict. groundrails is the deterministic gate that runs before the answer reaches the user: milliseconds per claim, no GPU, no API call, and an auditable pointer to the exact supporting passage.

Quickstart

pip install groundrails

# extract the claims from an answer, check each against the evidence
groundrails ground answer.md evidence.txt --json

[!IMPORTANT] groundrails grounds plain text only (UTF-8). Convert a PDF, DOCX, or scanned document to markdown or text first - with a separate document-processing tool - then ground the result.

You get back a grounding document: per claim, a verdict, a confidence score, and exactly where the support sits in the evidence - the quoted passage and its line / character offset. This is what an agent reads to cite a source or retract a claim:

{
  "summary": {"total": 12, "grounded": 9, "ungrounded": 3},
  "claims": [
    {
      "claim": "The tower was completed in 1889.",
      "claim_location": {"line": 5, "char_start": 120, "char_end": 152},
      "grounded": true,
      "score": 0.94,
      "support": {
        "source_path": "evidence.txt",
        "matched_text": "the Eiffel Tower was completed in 1889",
        "line_start": 12, "char_start": 210, "char_end": 248
      }
    }
  ]
}

Read it like this:

• grounded - true if the evidence backs the claim, false if it is unsupported or contradicted
• score - confidence in the verdict, 0 to 1
• support - the exact passage that backs the claim, with its source, line, and character offset
• contradiction - the conflicting value (a number or entity) when the claim disagrees with the source

Three ways to supply the claims; the rest of the positionals are always evidence:

groundrails ground answer.md evidence1.txt evidence2.txt          # claims extracted from a document
groundrails ground --claims claims.json evidence.txt              # a claims file
groundrails ground --claim "The tower is in Paris." evidence.txt  # inline (repeatable)

A claims.json is what extract-claims writes - a list of {claim, ...} objects (only claim is required; id and the location fields are optional). It can also be a plain list of strings, or a text file with one claim per line.

[
  {"id": "c01", "claim": "The Eiffel Tower is in Paris.", "line_number": 5, "char_start": 120, "char_end": 152},
  {"id": "c02", "claim": "It was completed in 1889.", "line_number": 5, "char_start": 153, "char_end": 178}
]

Drop --json for a readable line per claim; add --full-output for the per-scorer detail. From Python:

from groundrails import grounding_document

doc = grounding_document(
    ["The Eiffel Tower is in Paris."],
    [("evidence.txt", "The Eiffel Tower is located in Paris, France.")],
)

Cross-lingual claims and a deeper semantic check are opt-in: install groundrails[semantic-grounder] and add --semantic 1.

What you get

• Where the support is - the quoted passage, source, line, and character offset for every grounded claim
• Hallucination and contradiction flags - claims the source never made, and value conflicts like 512 vs 1000 or H100 vs A100
• Cross-lingual checks - a claim in one language against evidence in another, fully on-device
• A deterministic answer with a reason - frozen weights, same verdict every run, an auditable score behind each decision

Languages

English is native. Nine more work through an on-device translation bridge: Danish, German, Spanish, French, Italian, Norwegian Bokmål, Dutch, Portuguese, Swedish. A claim in any other language is blocked rather than silently mis-scored; add one with argospm install translate-<code>_en.

How it works & how it performs

Two layers: a fast deterministic lexical grounder, and an optional model-based cascade (--semantic) that escalates only the claims the fast path is unsure about. On a verified gold set the lexical grounder reaches macro-F1 0.76, and the semantic switch lifts it to 0.82. The full design, benchmarks, and comparison to published methods live in the two SOTA write-ups:

• lexical-grounding-sota.md - the deterministic lexical grounder
• semantic-grounding-sota.md - the optional model-based cascade

Documentation

• docs/api-reference.md - the functions, the grounding-document fields, and the CLI
• docs/grounding_concept.md - what grounding means here and how a verdict is assembled
• the two SOTA docs above, plus the full research history under docs/experiments/

License

MIT