Production-grade, sub-millisecond LLM Hallucination Detection & Fact Verification Engine built in Go.
Automatically decomposes AI answers into atomic factual claims, grounds each claim against trusted reference documents, detects intrinsic contradictions, numeric/temporal distortions, and entity fabrications, and flags unreliable answers.
Large Language Models (LLMs) frequently generate answers that sound fluent and authoritative but contain subtle, high-risk hallucinations:
- Numeric Distortions: Inventing or altering revenue, percentages, dosages, or dates (e.g. source says
$480M, AI says$750M). - Intrinsic Contradictions: Reversing polarity or stating the inverse of facts in the source document.
- Extrinsic Hallucinations: Hallucinating ungrounded entities, organizations, or events not present in the reference documents.
- Attribution & Context Twisting: Misattributing actions or blending disjoint facts together.
VeriFact / HalluciDetect solves this problem by providing an automated verification pipeline that checks any AI response against authoritative source documents.
ββββββββββββββββββββββββββββββββββββββββββ
β AI-Generated Text Response β
βββββββββββββββββββββ¬βββββββββββββββββββββ
β
βΌ
ββββββββββββββββββββββββββββββββββββββββββ
β Claim Decomposition Engine β
β - Sentence Boundary Detection β
β - Conversational Filler Stripping β
β - Named Entity & Number Extraction β
βββββββββββββββββββββ¬βββββββββββββββββββββ
β Atomic Claims
βΌ
ββββββββββββββββββββββββ ββββββββββββββββββββββββββββββββββββββββββ
β Trusted Source Docs β βββββΊ β Inverted BM25 Search Index β
β (.txt, .md, context) β β Hierarchical & Sliding-Window Chunks β
ββββββββββββββββββββββββ βββββββββββββββββββββ¬βββββββββββββββββββββ
β Candidate Passages
βΌ
ββββββββββββββββββββββββββββββββββββββββββ
β Multi-Tier Verification Pipeline β
β ββ Strict Numeric / Temporal Checker β
β ββ Entity Grounding & Absence Tracker β
β ββ Polarity / Negation Inversion NLI β
β ββ Lexical Coverage & Jaccard Metric β
β ββ (Optional) LLM-as-a-Judge Refiner β
βββββββββββββββββββββ¬βββββββββββββββββββββ
β
βΌ
ββββββββββββββββββββββββββββββββββββββββββ
β Comprehensive Audit Report β
β ββ Faithfulness Score & Risk Level β
β ββ Color-Coded Highlight Grounding Map β
β ββ Formats: CLI, JSON, Markdown, SARIF β
β ββ Interactive Web UI Dashboard β
ββββββββββββββββββββββββββββββββββββββββββ
Every claim evaluated by VeriFact is categorized under a fine-grained failure taxonomy:
| Status | Failure Taxonomy | Description | Real-World Example |
|---|---|---|---|
π’ SUPPORTED |
NONE |
Claim is directly grounded in source document | Source: $480M rev, Claim: $480M rev |
π΄ CONTRADICTED |
NUMERIC_MISMATCH |
Number, percentage, or date altered | Source: 14% growth, Claim: 35% growth |
π΄ CONTRADICTED |
INTRINSIC |
Explicit polarity inversion or negation | Source: Drug failed trial, Claim: Drug succeeded |
π‘ UNSUPPORTED |
EXTRINSIC |
Completely fabricated ungrounded claim | Source: Tech report, Claim: Bought Spanish island |
π‘ UNSUPPORTED |
ENTITY_CONFUSION |
Proper nouns or entities not in source | Claim references Elon Musk, source does not |
π΅ PARTIAL |
OUT_OF_CONTEXT |
Conceptual overlap but distorted scope | Broad extrapolation beyond evidence |
- Sub-Millisecond Heuristic Verification: Zero external API dependencies required. Evaluates typical multi-paragraph texts in < 5ms using algorithmic NLI, BM25 indexing, and entity-numeric grounding.
- Pluggable LLM-as-a-Judge: Optional integration with Gemini (
gemini-2.5-flash), OpenAI (gpt-4o-mini), or local Ollama instances for deep semantic dispute resolution. - Embedded Interactive Web UI: Fully self-contained single-page application built directly into the binary using Go's
embed.FS. No Node.js or web server required! - CI/CD Quality Gates: Built-in
--fail-on-hallucinationflag returning exit code1when hallucinations are detected, blocking ungrounded answers from merging or shipping. - Multi-Format Export: Generates rich ANSI terminal output, GitHub-flavored Markdown reports, JSON payloads, and OASIS SARIF v2.1.0 for GitHub Code Scanning.
git clone https://github.com/ATLURI0001/llm-hallucination-detector.git
cd llm-hallucination-detector
go build -o hallucidetect ./cmd/hallucidetectdocker build -t hallucidetect .
docker run -p 8080:8080 hallucidetecthallucidetect check \
--source "Acme Corp reported $480M revenue in 2024. Sarah Jenkins was appointed CEO." \
--answer "Acme Corp reported $950M revenue in 2024. Sarah Jenkins was appointed CEO." \
--format tablehallucidetect check \
-s testdata/financial_source.txt \
-a testdata/financial_answer.txt \
-f markdown \
-o audit_report.mdhallucidetect check \
-s reference_docs.txt \
-a model_output.txt \
--fail-on-hallucination
# Exits with 0 if faithful, 1 if hallucination detectedhallucidetect serve --port 8080
# Open http://localhost:8080 in your browserhallucidetect benchmarkWhen launched with hallucidetect serve, the engine exposes high-performance HTTP endpoints.
Evaluates an AI answer against source text.
Request:
curl -X POST http://localhost:8080/api/v1/verify \
-H "Content-Type: application/json" \
-d '{
"source_text": "The Python language was created by Guido van Rossum and first released in 1991.",
"answer_text": "Python was released in 1991 by Guido van Rossum. It was designed by James Gosling in 2005.",
"options": {
"threshold": 0.65,
"strict_numeric_verification": true
}
}'Response:
{
"id": "vr_1794063765673183100",
"verdict": "UNRELIABLE",
"risk_level": "HIGH",
"faithfulness_score": 0.50,
"hallucination_score": 0.50,
"total_claims": 2,
"supported_claims": 1,
"contradicted_claims": 0,
"unsupported_claims": 1,
"partially_supported_claims": 0,
"processing_time_ms": 1,
"claims": [
{
"id": 1,
"text": "Python was released in 1991 by Guido van Rossum.",
"status": "SUPPORTED",
"hallucination_type": "NONE",
"confidence": 0.88,
"explanation": "Claim is directly supported and grounded by the source document passage.",
"best_evidence": {
"snippet": "The Python language was created by Guido van Rossum and first released in 1991."
}
},
{
"id": 2,
"text": "It was designed by James Gosling in 2005.",
"status": "UNSUPPORTED",
"hallucination_type": "EXTRINSIC",
"confidence": 0.92,
"explanation": "Extrinsic Hallucination: No corroborating evidence found anywhere in the trusted source documents.",
"missing_entities": ["2005", "James Gosling"]
}
]
}Healthcheck and uptime status.
curl http://localhost:8080/api/v1/healthThe engine includes a single-page dark/light web UI embedded inside the binary:
- Preset Demonstrations: Preloaded financial earnings, clinical trials, and hardware specs.
- Interactive Grounding Map: Color-coded visualization where users can click any highlighted sentence to immediately reveal its exact matching citation passage in the source document.
- Filterable Claims Table: Sort and filter claims by
SUPPORTED,CONTRADICTED, andUNSUPPORTED. - One-Click Export: Instant download of Markdown or JSON audit reports.
Running hallucidetect benchmark:
================================================================================
Running Built-In Hallucination Benchmark Test Suite...
[1/3] Testing: Financial Report Grounded vs Numeric Hallucination... PASS (Verdict: UNRELIABLE, Faithfulness: 25%)
[2/3] Testing: Clinical Trial Polarity Inversion... PASS (Verdict: UNRELIABLE, Faithfulness: 0%)
[3/3] Testing: Faithful Summary Grounding... PASS (Verdict: RELIABLE, Faithfulness: 100%)
Benchmark Complete: 3/3 test suites passed (100% accuracy).
================================================================================
.
βββ .github/
β βββ workflows/
β β βββ ci.yml # Matrix CI: tests, race checks, cross-platform builds
β β βββ security.yml # CodeQL static analysis & Gosec scanning
β βββ ISSUE_TEMPLATE/ # Bug report & feature request templates
β βββ PULL_REQUEST_TEMPLATE.md # PR checklist & review guidelines
β βββ dependabot.yml # Automated dependency & action security bumps
βββ cmd/
β βββ hallucidetect/
β βββ main.go # CLI tool, flags, and subcommands
βββ internal/
β βββ api/ # REST API handlers, routing, CORS
β βββ claim/ # Claim extraction & proposition decomposition
β βββ document/ # Inverted index, BM25 retrieval, chunking
β βββ engine/ # Master detector, heuristic NLI, LLM judge
β βββ models/ # Shared domain types & schemas
β βββ report/ # Terminal, Markdown, JSON, SARIF formatters
β βββ web/ # Embedded static UI (HTML, CSS, JS)
βββ testdata/ # Benchmark sample datasets
βββ Dockerfile # Multi-stage scratch/alpine container
βββ docker-compose.yml # Compose specification
βββ Makefile # Build, test, and run automation
βββ build.ps1 # Windows PowerShell build utility
βββ go.mod # Go module definition (zero external dependencies)
βββ CODE_OF_CONDUCT.md # Contributor Covenant Code of Conduct v2.1
βββ CONTRIBUTING.md # Contributor guidelines and workflow
βββ SECURITY.md # Security policy, threat model, and disclosure process
βββ LICENSE # MIT License
βββ README.md # Project documentation
- Local-First Execution: In default mode, VeriFact processes all claims locally on your machine with zero external network requests or third-party API exposure.
- Safe Credential Handling: When optional LLM judging is enabled, API keys are passed strictly in-memory and are never cached, persisted, or displayed in output logs.
- For vulnerability reporting and our security policy, please review SECURITY.md.
Contributions, bug reports, and suggestions are welcome! Please check our CONTRIBUTING.md guide and CODE_OF_CONDUCT.md.
Distributed under the MIT License. See LICENSE for details.