hallucination-gate

Conservative grounding gate for RAG and fine-tuned LLMs.
Verify answers against your evidence → pass, rewrite, or abstain.

False release is the failure mode that matters. Neighbor chunks no longer veto a claim another chunk fully supports.

Install

pip install -U hallucination-gate
pip install "hallucination-gate[ocr]"   # Tesseract / EasyOCR / scanned PDFs

Quick start

from hallucination_gate import HallucinationGate, Evidence

gate = HallucinationGate()  # neural default (production)
# gate = HallucinationGate(use_heuristic=True)  # CI / offline smoke only

result = gate.check(
    query=user_query,
    answer=llm_answer,
    context=retrieved_docs,  # str | list[str] | LangChain Document | dict
)
return result.text  # show this to users

gate = HallucinationGate(mode="fine_tuned")
result = gate.check(query, answer, kb=your_knowledge_base)

# Images / PDFs / OCR
result = gate.check(query, answer, evidence=Evidence.from_image(path="warranty_card.jpg"))
result = gate.check(query, answer, evidence=Evidence.from_pdf("policy.pdf"))
result = gate.check(query, answer, evidence=Evidence.from_ocr(path="scanned.pdf"))

@gate.protect
def my_rag(query: str):
    docs = retriever(query)
    answer = llm(query, docs)
    return answer, docs

Inspect result.claims / result.diagnostics for claim↔chunk status, citations, and reasons.

OCR

pip install "hallucination-gate[ocr]"
# system: Tesseract binary (+ poppler for scanned PDFs)

from hallucination_gate import Evidence, ocr_available

print(ocr_available())  # pillow / tesseract / easyocr

ev = Evidence.from_image(path="card.jpg")          # auto-OCR + preprocess
ev = Evidence.from_ocr(path="scanned_policy.pdf")  # page OCR fallback

Upscale → contrast → denoise, then Tesseract and/or EasyOCR. Image-only PDFs OCR when text extract is empty.

Evidence patterns

Pattern	When
Full retriever top-k	Default. Per-chunk soft-OR handles mixed neighbors.
Reranked / answer-aligned top-k	Best production default.
Citation-level chunks	If the generator emits citations, pass only those.
Top-1 only	Demos; too brittle for real retrieval.

Pass a list[str] (or documents)—do not concatenate top-k into one bag.

Heuristic vs neural

Mode	How	Use for
Neural (default)	MiniLM + DeBERTa NLI	Production
Heuristic	Token / negation / number heuristics	CI smoke (`use_heuristic=True` or `RAG_EVAL_HEURISTIC=1`)

Heuristic is a wiring check, not a calibrated quality gate.

Optional judge on uncertain claims only: HALLUCINATION_GATE_JUDGE=1 + ANTHROPIC_API_KEY or OPENAI_API_KEY.

What this is (and is not)

It does	It does not
Ground claims in your chunks / KB / OCR / PDF	Know if the KB itself is wrong
Abstain on contradiction, invented entities, number clashes	Read fine-tune weights
Drop ungrounded sentences; abstain if the rest misses the query	Replace LLM-as-judge on subtle code/math proofs

Release is decided by claim grounding. BN scores are diagnostics only.

Eval

pip install -e ".[dev]"
set RAG_EVAL_HEURISTIC=1
pytest -q -m "not neural"
hallucination-gate eval-heldout

HTTP API (optional)

Library users do not need a server.

uvicorn bayesian_rag_evaluator.api.main:app --reload --port 8000

POST /v1/answer → {safe_answer, released, request_id, latency_ms} only.

License

MIT

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hallucination_gate-0.6.3.tar.gz (56.2 kB view details)

Uploaded Aug 15, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

hallucination_gate-0.6.3-py3-none-any.whl (61.9 kB view details)

Uploaded Aug 15, 2026 Python 3

File details

Details for the file hallucination_gate-0.6.3.tar.gz.

File metadata

Download URL: hallucination_gate-0.6.3.tar.gz
Upload date: Aug 15, 2026
Size: 56.2 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for hallucination_gate-0.6.3.tar.gz
Algorithm	Hash digest
SHA256	`24f41cbf67a6cd222a7d6ef19c80c8db401f34f7742066869432318ebdeeb9b4`
MD5	`da52a3a5e31cd783a608946e16efea30`
BLAKE2b-256	`c8a6306957dc80d6f06d19ec826bcdf66a0c10097bc385360b888f4edf64ac9c`

See more details on using hashes here.

Provenance

The following attestation bundles were made for hallucination_gate-0.6.3.tar.gz:

Publisher: publish.yml on shrey315/hallucination-gate

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: hallucination_gate-0.6.3.tar.gz
- Subject digest: 24f41cbf67a6cd222a7d6ef19c80c8db401f34f7742066869432318ebdeeb9b4
- Sigstore transparency entry: 2478367267
- Sigstore integration time: Aug 15, 2026
Source repository:
- Permalink: shrey315/hallucination-gate@aad5cb027c75d2353821b6a3b41953d677605a24
- Branch / Tag: refs/tags/v0.6.3
- Owner: https://github.com/shrey315
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@aad5cb027c75d2353821b6a3b41953d677605a24
- Trigger Event: release