RagWarden

An inline hallucination gate for production RAG pipelines.

RagWarden doesn't compete with RAGAS or UQLM — it's the runtime enforcement layer that uses signals like theirs (and its own fast detectors) to make a bounded-latency, explainable decision inline in production, with a policy engine enterprises can tune to their own risk tolerance.

An answer generated by any RAG pipeline is broken into atomic, independently-checkable claims. Each claim runs through a cascade of checks ordered cheapest-first:

1. Tier 0 — retrieval heuristics (deterministic, near-zero cost, always on)
2. Tier 1 — claim-vs-evidence entailment (fast encoder models: NLI, HHEM, LettuceDetect, MiniCheck)
3. Tier 2 — uncertainty quantification (consistency sampling; token log-probs if available)
4. Tier 3 — LLM-as-judge (structured chain-of-thought, budget-capped, only the ambiguous remainder)

Per-claim verdicts combine into a composite reliability score. A configurable policy engine turns that score into an action — ALLOW, REDACT_CLAIMS, RETRY, ABSTAIN, or ESCALATE — and every decision comes with a full explanation trail.

gate() does not fail your request. Every external dependency — a Tier-1 detector, your generate_fn, your judge_fn — is fault-isolated and time-boxed; an unexpected failure anywhere in the cascade degrades to a safe ABSTAIN instead of an unhandled exception. See Running in production.

Status

v0.3.0 — all 13 build phases complete (contracts → cascade → policy → actions → adapters → observability → docs → release pipeline → hardening), plus a production-hardening pass (fault isolation, timeouts, an async API, startup warmup). Benchmark numbers are an honest baseline, not yet competitive. On the path to a v1.0 that locks ragwarden.contracts under semver.

Current baseline (honest, not competitive yet)

ragwarden benchmark --dataset ragtruth --detector nli on 150 shuffled RAGTruth test rows (DeBERTa-v3-base NLI, default policy, Tiers 0–1 only):

The gate currently over-flags (very high recall, low precision) — the expected over-abstention baseline before Tier 2/3, calibration, and better claim decomposition land. Full run outputs live in benchmarks/results/.

Install

pip install ragwarden                 # core: light, no ML dependencies
pip install 'ragwarden[nli]'          # + DeBERTa-v3 NLI Tier-1 detector
pip install 'ragwarden[opensearch]'   # + OpenSearch adapter
pip install 'ragwarden[all]'          # everything (OSI-licensed extras)

The core install pulls only a YAML parser and a pure-Python sentence splitter — no torch, transformers, or numpy for Tier-0-only usage.

Quickstart

from ragwarden import gate, Policy
from ragwarden.models import Chunk, Context, Answer

context = Context(
    query="When was the Eiffel Tower completed?",
    chunks=[Chunk(text="The Eiffel Tower was completed in 1889.", score=0.91, source_id="doc-1")],
    retrieval_method="hybrid",
)
answer = Answer(text="The Eiffel Tower was completed in 1889.")

result = gate(context, answer, policy=Policy.default())
print(result.action)  # GateAction.ALLOW
print(result.reliability_score)  # composite 0.0-1.0
print(result.explanation)  # human-readable decision trail

How it relates to existing tools

RagWarden is complementary, not competitive — it is the runtime enforcement layer that turns signals (its own, or others') into a bounded-latency, explainable inline decision.

Honest limitations

• A gate cannot fix bad retrieval. If the wrong evidence was retrieved, no downstream check recovers the right answer — this bounds the whole system's ceiling.
• Every detector has its own error rate. The composite reliability score is a calibrated confidence estimate, not ground truth.
• Over-aggressive gating trades hallucination risk for over-abstention. Calibration against your own traffic (ragwarden calibrate) is the actual product experience, not optional polish.
• Latency / cost budgets are real constraints. The tiered design exists because "run an LLM judge on everything" is correct but unusable at production scale.
• v0.1 claim decomposition is sentence splitting — a known simplification vs. atomic-claim extraction; it bounds achievable span-level precision. See design decisions.

License

Apache-2.0 (explicit patent grant — matches Transformers, TensorFlow, NeMo, RAGAS). See LICENSE.