Metadata-Version: 2.4
Name: ragground
Version: 0.1.1
Summary: Fast, deterministic & ONNX-powered hallucination guardrail & citation verifier for RAG
Project-URL: Homepage, https://github.com/anoopchandra/ragground
Project-URL: Documentation, https://github.com/anoopchandra/ragground/blob/main/docs/README.md
Project-URL: Repository, https://github.com/anoopchandra/ragground
Project-URL: Issues, https://github.com/anoopchandra/ragground/issues
Author-email: Anoop Chandra <anoop@example.com>
License: Apache-2.0
License-File: LICENSE
Keywords: citation-verification,grounding,guardrails,hallucination-detection,llm-evaluation,nli,onnx,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: numpy>=1.20.0
Requires-Dist: onnxruntime>=1.15.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tokenizers>=0.15.0
Requires-Dist: tqdm>=4.64.0
Provides-Extra: all
Requires-Dist: mypy>=1.5.0; extra == 'all'
Requires-Dist: pytest-cov>=4.0.0; extra == 'all'
Requires-Dist: pytest>=7.0.0; extra == 'all'
Requires-Dist: ruff>=0.3.0; extra == 'all'
Requires-Dist: spacy>=3.5.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Provides-Extra: spacy
Requires-Dist: spacy>=3.5.0; extra == 'spacy'
Description-Content-Type: text/markdown

<div align="center">

# 🛡️ RAGGround

**Sub-15ms Deterministic & ONNX-Powered Hallucination Guardrail & Citation Verifier for RAG**

[![PyPI version](https://img.shields.io/pypi/v/ragground.svg?color=blue)](https://pypi.org/project/ragground/)
[![Python versions](https://img.shields.io/pypi/pyversions/ragground.svg)](https://pypi.org/project/ragground/)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-green.svg)](LICENSE)
[![Type Checked: mypy](https://img.shields.io/badge/typing-typed-blue.svg)](py.typed)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)

*Stop wasting 4 seconds and thousands of dollars on LLM-as-a-judge evaluators. Verify groundedness, highlight hallucinations at sentence-level granularity, and inject verified citations in sub-15 milliseconds.*

</div>

---

## ⚡ Why RAGGround?

Most RAG teams evaluate hallucinations using **Ragas** or **LLM-as-a-judge**. In production, this causes 3 critical problems:
1. **Unusable Latency:** Calling GPT-4 to judge an answer adds **3,000–8,000 ms** to every response.
2. **Double API Bills:** Every token generated requires an extra LLM call to evaluate.
3. **No Span Citations:** LLM judges give vague scores (`0.75`) without pinpointing the exact hallucinated sentence or linking claims to documents.

**RAGGround solves this with a 2-Tiered Local Engine:**
- ⚡ **Tier 1 (Sub-1ms):** Deterministic token-alignment, sequence matching (LCS), and entity consistency verification.
- 🧠 **Tier 2 (~10ms CPU):** Quantized INT8 Natural Language Inference (NLI) model executed locally with ONNX Runtime. Zero PyTorch installation required (< 45MB RAM).

---

## 🚀 Quickstart

### 1. Installation
```bash
pip install ragground
```

### 2. Verify RAG Outputs (Python API)
```python
from ragground import RAGGround

guard = RAGGround()

context = """
Tesla reported Q3 revenue of $25.18 billion, an 8% increase year-over-year.
Operating margin came in at 10.8% with free cash flow of $2.74 billion.
"""

answer = """
Tesla's Q3 revenue rose 8% to $25.18 billion.
Free cash flow reached $2.74 billion.
The company also announced plans to launch humanoid robots by Christmas.
"""

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

print(f"Grounded: {report.is_grounded}")          # False
print(f"Score: {report.grounding_score:.2f}")     # 0.67 (2 of 3 verified)
print(f"Latency: {report.latency_ms} ms")         # 11.2 ms

# Inspect flagged hallucinations
for h in report.hallucinations:
    print(f"⚠️ Hallucination: {h.text}")
    print(f"   Status: {h.status.value} (Confidence: {h.confidence:.2f})")

# View augmented answer with exact citations injected
print("\n--- Cited Output ---")
print(report.cited_answer)
```

---

## 📊 Benchmark: RAGGround vs. LLM-as-a-Judge

| Metric | RAGGround (Tier 1 + ONNX) | Ragas (GPT-4o-mini / 3.5) | Regex / Exact Match |
| :--- | :--- | :--- | :--- |
| **P50 Latency (per query)** | **~8.2 ms** ⚡ *(300x faster)* | ~3,400 ms 🐢 | < 1 ms |
| **P99 Latency (per query)** | **~14.5 ms** | ~6,800 ms | < 2 ms |
| **Cloud API Cost** | **$0.00 (Runs locally)** | $150–$400 / 100k calls | $0.00 |
| **Paraphrase Understanding** | ✅ High (Neural NLI) | ✅ High | ❌ None (Breaks on synonyms) |
| **Number & Entity Checking** | ✅ Strict Entity Matching | ⚠️ LLM Drift | ⚠️ High False Positives |
| **Deterministic Output** | ✅ 100% Reproducible | ❌ Nondeterministic | ✅ 100% Reproducible |
| **Citations Generated** | ✅ Exact Sentence-to-Source | ⚠️ Vague Overall Score | ❌ None |

---

## 💻 Command Line Interface (CLI)

Audit any context and answer directly in your terminal:

```bash
ragground verify \
  -c "Python 3.12 introduced improved error messages and isolated subinterpreters." \
  -a "Python 3.12 added isolated subinterpreters. It also removed the GIL completely."
```

Benchmark your local CPU:
```bash
ragground benchmark
```

---

## 🏗️ Architecture

```
[ User Context & Answer ] ──► [ Claim Decomposition ] ──► [ Tier 1: Token & LCS Shortcut (< 1ms) ]
                                                                     │
                                  ┌──────────────────────────────────┴─────────────────────────────────┐
                                  ▼ (High Overlap)                                                     ▼ (Paraphrased / Fuzzy)
                         [ Mark Verified ]                                                [ Tier 2: ONNX NLI Transformer (~10ms) ]
                                  │                                                                    │
                                  └───────────────────────────────┬────────────────────────────────────┘
                                                                  ▼
                                                   [ Citation & GuardReport ]
```

---

## 📚 Documentation

For in-depth guides and references, check the [`docs/`](docs/) directory:
- [Getting Started](docs/getting-started.md)
- [System Architecture](docs/architecture.md)
- [API Reference](docs/api-reference.md)
- [Benchmarks](docs/benchmarks.md)
- [FastAPI & LangChain Integration Guide](docs/guides/production-rag.md)
- [Custom ONNX Models](docs/guides/custom-models.md)

---

## 📄 License

Apache 2.0 License. See [LICENSE](LICENSE) for details.
