🛡️ RAGGround

RAGGround is a lightweight, sub-millisecond hallucination guardrail, citation verifier, and RAG evaluation engine.

It verifies whether an LLM-generated answer is strictly grounded in the retrieved context documents, automatically detects extrinsic fabrications and numerical contradictions, and injects clean inline citations ([1], [2]).

⚡ Key Highlights

• 🚀 Sub-Millisecond Execution: Tier 1 deterministic alignment evaluates in < 0.3 ms on standard CPU.
• 🧠 Neural NLI Verification: Backed by quantized cross-encoder models with zero silent fallback.
• 🎯 Conservative Hallucination Defense: Routes numerical discrepancies, changed entities, and uncertain paraphrases through neural verification instead of approving them from fuzzy overlap alone.
• 🩺 Production Readiness & Health Checks: Explicit startup diagnostics (guard.health_check(), ragground doctor).
• 🔒 Strict Production Mode: require_model=True fails fast if neural model weights are missing or offline.
• 🧵 Thread-Safe Multi-Worker Concurrency: Verified safe across Flask, Gunicorn, and FastAPI server workers.
• 📚 Automated Citation Injection: Injects inline citation tags ([1]), footnotes, or HTML hover tooltips.
• 📊 Dataset Tuning & Evaluation: Auto-tune optimal grounding and contradiction thresholds on your custom dataset.

🎯 Scope & Boundaries (When to Use & When NOT to Use)

✅ Recommended Use Cases (What RAGGround is Made For):

• Factual Q&A RAG Pipelines: Verifying that the LLM only answers with information present in retrieved chunks.
• Extrinsic Hallucination Defense: Catching invented dates, names, prices, and features not stated in reference documents.
• Inline Citation Injection: Automatically mapping each verified sentence back to its source document ID.
• Latency-Critical Applications: High-throughput APIs where calling an external LLM for evaluation is too slow or costly.

⚠️ Scope & Known Limitations (When NOT to Use as Sole Arbiter):

• World Truth Fact-Checking: RAGGround verifies grounding against retrieved text, not cosmic world truth. If the retrieved context contains false information, an answer faithfully repeating that context will be marked as grounded.
• Complex Multi-Step Math: Not a symbolic calculator or formal proof engine.
• Raw Code & JSON Schemas: Optimized for natural language English prose; structured data and raw code syntax may require custom extraction.
• Contexts Exceeding 512 Tokens: Operates best on chunk-level contexts (100–300 words). Large document contexts should be split into passages.
• Non-English / Multilingual: Current quantized NLI models are trained primarily on English datasets.

📦 Installation

pip install ragground

🚀 Quickstart

1. Basic Single-Query Verification

from ragground.app import RAGGround

# 1. Initialize guard (InsightFace-style)
guard = RAGGround(name="nli-deberta-v3-xsmall")
guard.prepare(ctx_id=-1)  # -1 for CPU, 0 for GPU

context = """
Tesla reported Q3 automotive revenue of $20.02 billion, representing an 8% increase 
year-over-year. Free cash flow for the quarter was $2.74 billion.
"""

answer = """
Tesla reported Q3 automotive revenue of $20.02 billion, up 8% YoY. 
Free cash flow reached $2.74 billion. 
The company also announced a new smartphone for $999.
"""

report = guard.verify(context=context, answer=answer)

print("Is Grounded:       ", report.is_grounded)          # False
print("Grounding Score:   ", f"{report.grounding_score*100:.1f}%")  # 66.7%
print("Model Loaded:      ", report.model_loaded)          # True
print("Used Neural Model: ", report.used_neural_model)     # True
print("Verified Claims:   ", report.verified_count)        # 2
print("Hallucinations:    ", report.unsupported_count)     # 1

print("\nCited Answer:")
print(report.cited_answer)

2. Strict Production Mode (No Silent Failures)

In enterprise deployments, ensure the neural model is genuinely active and never silently falling back:

from ragground import RAGGround, ModelNotReadyError

# Fails fast with ModelNotReadyError if model weights are missing
guard = RAGGround(require_model=True, auto_download=False)

# Check health during app startup
health = guard.health_check()
if health["status"] != "healthy":
    raise SystemError(f"RAGGround is not healthy: {health}")

3. Threshold Tuning for Customer Datasets

Automatically find the optimal precision/recall threshold configuration for your domain:

guard = RAGGround()

# Your labeled evaluation dataset
labeled_dataset = [
    {"context": "Water is H2O.", "answer": "Water is composed of H2O.", "grounded": True},
    {"context": "Sky is blue.", "answer": "Sky is purple with yellow dots.", "grounded": False}
]

tuning = guard.tune_thresholds(labeled_dataset)
print("Recommended Threshold:", tuning["recommended_grounding_threshold"])
print("Accuracy at Recommended:", tuning["evaluation_metrics"]["accuracy"])

4. Function Decorator for Python RAG Pipelines

from ragground.decorators import verify_grounding

@verify_grounding(raise_on_hallucination=False)
def generate_rag_response(query: str, context: str) -> str:
    # Your LLM call here
    return "LLM generated response..."

report = generate_rag_response(query="...", context="...")

🛠️ Production CLI Reference

# 🩺 Health Check & Diagnostic Audit
ragground doctor
# (or: ragground verify-installation)

# 📥 Pre-download ONNX model inside Dockerfile
ragground download-model --name nli-deberta-v3-xsmall

# 🔍 Audit answer from terminal
ragground verify -c "Context text..." -a "Answer text..."

# 🎯 Auto-tune thresholds on labeled JSON dataset
ragground tune-thresholds --dataset test_data.json

# ⚡ Benchmark local CPU/GPU hardware throughput
ragground benchmark

⚙️ Configuration Options

📄 License

MIT License. Free for commercial and open-source use.