HalluciScope 🔬

Automated Hallucination Detection and Explainability Framework for Large Language Models

---

Overview

HalluciScope is a research-grade framework that detects, categorizes, and explains hallucinations in Large Language Model (LLM) outputs. As LLMs are increasingly deployed in high-stakes domains (medicine, law, finance), understanding when and why they hallucinate becomes critical.

This project provides:

• Detection — NLI-based hallucination detection using DeBERTa cross-encoder
• Categorization — Classification into hallucination types (factual, reasoning, context, fabrication)
• Explainability — Token/phrase-level analysis identifying what caused the hallucination
• REST API — FastAPI backend for integration into any pipeline
• Evaluation Pipeline — Batch evaluation with statistical reporting

---

Architecture

HalluciScope/
├── src/
│   ├── detector/           # NLI-based hallucination detection
│   │   ├── hallucination_detector.py
│   │   └── llm_generator.py
│   ├── categorizer/        # Hallucination type classification
│   │   └── hallucination_categorizer.py
│   ├── explainer/          # Token-level explainability
│   │   └── hallucination_explainer.py
│   └── api/                # FastAPI REST API
│       └── main.py
├── data/
│   ├── prompts/            # Evaluation datasets
│   └── results/            # Output CSV reports
├── evaluate.py             # Full evaluation pipeline
├── Dockerfile
└── requirements.txt

---

Methodology

1. Detection (NLI-based)

Uses cross-encoder/nli-deberta-v3-base to perform Natural Language Inference between:

• Premise: Ground truth answer
• Hypothesis: LLM-generated response

A high contradiction score (> 0.5) indicates hallucination.

2. Categorization

Uses GPT to classify hallucinations into:

Type	Description
factual	Wrong facts — incorrect dates, names, statistics
reasoning	Logical errors or wrong inference
context	Ignores or contradicts provided context
fabrication	Completely made-up information

3. Explainability

Uses sentence-transformers to compute semantic similarity between each phrase in the LLM response and the ground truth. Phrases with cosine similarity < 0.3 are flagged as suspicious/hallucinated.

---

Setup

1. Clone the repository

git clone https://github.com/niharikabanothu/HalluciScope.git
cd HalluciScope

2. Create virtual environment

python -m venv venv
source venv/bin/activate        # Linux/Mac
venv\Scripts\activate           # Windows

3. Install dependencies

pip install -r requirements.txt

4. Configure environment

cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

---

Usage

Run Evaluation Pipeline

python evaluate.py
python evaluate.py --model gpt-4o-mini

Start API Server

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

API docs available at: http://localhost:8000/docs

API Example

curl -X POST "http://localhost:8000/analyze" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Who invented the telephone?",
    "ground_truth": "Alexander Graham Bell invented the telephone in 1876.",
    "llm_response": "Thomas Edison invented the telephone in 1879."
  }'

Docker

docker build -t halluci-scope .
docker run -p 8000:8000 --env-file .env halluci-scope

---

Sample Output

{
  "is_hallucination": true,
  "confidence": 0.89,
  "contradiction_score": 0.89,
  "entailment_score": 0.04,
  "category": "factual",
  "severity": "high",
  "explanation": "The response incorrectly attributes the telephone to Thomas Edison instead of Alexander Graham Bell.",
  "suspicious_phrases": [["Thomas Edison invented the telephone in 1879", 0.12]],
  "overall_similarity": 0.31
}

---

Evaluation Results

Metric	Value
Dataset Size	10 samples
Hallucination Rate	~40% (varies by model)
Avg Contradiction Score	0.43
Avg Entailment Score	0.38

Results vary across models. GPT-4 shows lower hallucination rates than GPT-3.5-turbo.

---

Research Motivation

This project is motivated by challenges in LLM Reliability and Trustworthiness, an active area of research at organizations like Google DeepMind, Anthropic, and Meta AI. Hallucination detection is a prerequisite for safe deployment of LLMs in production systems.

Key research questions addressed:

1. Can NLI models reliably detect semantic contradictions in LLM outputs?
2. Are certain prompt categories more hallucination-prone?
3. Which token-level features correlate with hallucinated content?

---

Author

Niharika Banothu M.Tech Artificial Intelligence | MANIT Bhopal (NIT Bhopal)

• GitHub: github.com/niharikabanothu
• LinkedIn: linkedin.com/in/niharikabanothu

---

License

MIT License — see LICENSE for details.