🛡️ 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 for semantic entailment verification.
• 🎯 100% Precision Hallucination Defense: Catches numerical errors, swapped entities, and unsupported claims with zero false approvals.
• 📚 Automated Citation Injection: Injects inline citation tags ([1]), footnotes, or HTML hover tooltips into the LLM output.
• 📊 Batch Dataset Evaluation: Benchmark entire RAG datasets and compute grounding accuracy, hallucination rate, and latency.

📦 Installation

pip install ragground

🚀 Quickstart

1. Basic Single-Query Verification

from ragground import RAGGround

# Initialize the guardrail
guard = RAGGround()

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("Verified Claims:   ", report.verified_count)        # 2
print("Hallucinations:    ", report.unsupported_count)     # 1

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

Output:

Is Grounded:        False
Grounding Score:    66.7%
Verified Claims:    2
Hallucinations:     1

Cited Answer:
Tesla reported Q3 automotive revenue of $20.02 billion, up 8% YoY. [1] 
Free cash flow reached $2.74 billion. [1] 
The company also announced a new smartphone for $999.

2. Multi-Document Verification

docs = {
    "doc_financials": "Google Q4 advertising revenue reached $65.5 billion.",
    "doc_cloud": "Google Cloud revenue grew 25.6% year-over-year to $9.2 billion."
}

answer = "Google Cloud grew 25.6% to $9.2B, while advertising brought in $65.5B."

report = guard.verify(context=docs, answer=answer)
print(report.cited_answer)

3. Evaluating a RAG Benchmark Dataset

from ragground import RAGGround

guard = RAGGround()

rag_dataset = [
    {
        "context": "Python was created by Guido van Rossum and released in 1991.",
        "answer": "Guido van Rossum released Python in 1991."
    },
    {
        "context": "The speed of light in vacuum is 299,792 km/s.",
        "answer": "Light travels at 5,000,000 km/s."
    }
]

results = guard.evaluate_dataset(rag_dataset)

print(f"Overall Accuracy:       {results.accuracy * 100:.1f}%")
print(f"Hallucination Rate:     {results.hallucination_rate * 100:.1f}%")
print(f"Mean Latency:           {results.avg_latency_ms:.2f} ms")

# Export to CSV report
results.to_csv("rag_evaluation_results.csv")

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..."

# Returns a GuardReport object directly
report = generate_rag_response(query="...", context="...")

⚙️ Configuration Options

💻 CLI Usage

# Verify from terminal
ragground verify -c "Context text..." -a "Answer text..."

# Benchmark performance on your hardware
ragground benchmark

# Pre-download ONNX model cache
ragground download-model

📄 License

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