LLM Hallucination Detector & Judge Calibration Toolkit

A toolkit for detecting factual hallucinations in LLM outputs and evaluating the reliability of LLM-as-judge systems. Quantifies hallucination rates with confidence intervals, detects systematic judge biases (positional, verbosity, self-enhancement), and generates calibration curves.

The Problem

Everyone is deploying LLMs in production. Almost nobody is rigorously measuring whether the outputs are correct. The industry standard of using "LLM-as-judge" (GPT-4 grading GPT-3.5) is riddled with biases that most teams don't measure:

• Positional bias: judges prefer whichever answer appears first
• Verbosity bias: judges prefer longer answers regardless of accuracy
• Self-enhancement bias: GPT-4 rates GPT-4 outputs higher than equivalent human text
• Confidence miscalibration: a judge's "95% confident" might only be correct 60% of the time

This toolkit quantifies all of these.

Features

• Factual grounding checker: scores LLM outputs against source documents using semantic similarity, entity overlap, and claim-level entailment
• Hallucination rate estimation with bootstrap confidence intervals
• Judge bias detection suite: positional, verbosity, and self-enhancement bias tests with statistical significance
• Calibration curves: reliability diagrams showing how well confidence scores predict actual correctness
• Multiple LLM provider support: OpenAI, Anthropic, local models via Hugging Face
• FastAPI server for real-time hallucination scoring
• Streamlit dashboard for interactive analysis
• Fully typed, tested, Dockerized

Quick Start

git clone https://github.com/yourusername/llm-hallucination-detector.git
cd llm-hallucination-detector
pip install -e ".[dev]"

# set your API key
export OPENAI_API_KEY=sk-...

# check a single response against a source document
python -m hallucination_detector check \
    --source "The Eiffel Tower is 330 meters tall and was built in 1889." \
    --response "The Eiffel Tower, standing at 350 meters, was constructed in 1887."

# run judge bias analysis
python -m hallucination_detector judge-bias \
    --dataset data/judge_eval.jsonl \
    --judge gpt-4o

# launch the dashboard
python -m hallucination_detector dashboard

Architecture

Source Document ──▶ Claim Extractor ──▶ Per-Claim Grounding ──▶ Hallucination Score
                                            │
LLM Response ───────────────────────────────┘
                                            
Judge Outputs ──▶ Bias Detector ──▶ Positional / Verbosity / Self-Enhancement
                       │
                  Calibrator ──▶ Reliability Diagram + ECE Score

Project Structure

├── hallucination_detector/
│   ├── __init__.py
│   ├── __main__.py
│   ├── cli.py
│   ├── exceptions.py
│   ├── models.py           # Data classes for claims, scores, bias results
│   ├── grounding.py        # Factual grounding checker
│   ├── claim_extractor.py  # Break responses into atomic claims
│   ├── judge_bias.py       # Bias detection suite
│   ├── calibration.py      # Calibration curves and ECE
│   ├── metrics.py          # Semantic similarity, entity overlap, entailment
│   ├── client.py           # LLM API client wrapper
│   ├── server.py           # FastAPI endpoint
│   └── dashboard.py        # Streamlit dashboard
├── tests/
├── pyproject.toml
├── Dockerfile
└── .github/workflows/ci.yml

License

MIT