Skip to content

About

High-precision, sub-millisecond LLM hallucination and fact verification engine in Go. Decomposes claims, grounds against source documents, detects numeric distortions, and flags unreliable AI answers.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

56 Commits

Folders and files

Repository files navigation

πŸ›‘οΈ LLM Hallucination Detector (VeriFact)

CI Pipeline Security Policy CodeQL Analysis Go Version Accuracy Benchmark License Zero Dependency

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.


🌟 Overview

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.


πŸ“ System Architecture

                       β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                       β”‚       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        β”‚
                       β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

πŸ”¬ Hallucination Taxonomy

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

πŸš€ Key Features

  1. 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.
  2. 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.
  3. 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!
  4. CI/CD Quality Gates: Built-in --fail-on-hallucination flag returning exit code 1 when hallucinations are detected, blocking ungrounded answers from merging or shipping.
  5. Multi-Format Export: Generates rich ANSI terminal output, GitHub-flavored Markdown reports, JSON payloads, and OASIS SARIF v2.1.0 for GitHub Code Scanning.

πŸ“¦ Installation

From Source (Go 1.22+)

git clone https://github.com/ATLURI0001/llm-hallucination-detector.git
cd llm-hallucination-detector
go build -o hallucidetect ./cmd/hallucidetect

Via Docker

docker build -t hallucidetect .
docker run -p 8080:8080 hallucidetect

πŸ’» CLI Usage Guide

1. Check Inline Text

hallucidetect 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 table

2. Verify Text from Files with Markdown Output

hallucidetect check \
  -s testdata/financial_source.txt \
  -a testdata/financial_answer.txt \
  -f markdown \
  -o audit_report.md

3. CI/CD Pipeline Gate

hallucidetect check \
  -s reference_docs.txt \
  -a model_output.txt \
  --fail-on-hallucination
# Exits with 0 if faithful, 1 if hallucination detected

4. Launch Embedded Web Dashboard

hallucidetect serve --port 8080
# Open http://localhost:8080 in your browser

5. Run Verification Benchmark

hallucidetect benchmark

🌐 REST API Reference

When launched with hallucidetect serve, the engine exposes high-performance HTTP endpoints.

POST /api/v1/verify

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"]
    }
  ]
}

GET /api/v1/health

Healthcheck and uptime status.

curl http://localhost:8080/api/v1/health

πŸ–₯️ Interactive Web UI Dashboard

The 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, and UNSUPPORTED.
  • One-Click Export: Instant download of Markdown or JSON audit reports.

πŸ“Š Benchmark Suite Results

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).
================================================================================

πŸ“ Repository Structure

.
β”œβ”€β”€ .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

πŸ”’ Security & Privacy

  • 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.

🀝 Contributing

Contributions, bug reports, and suggestions are welcome! Please check our CONTRIBUTING.md guide and CODE_OF_CONDUCT.md.


πŸ“œ License

Distributed under the MIT License. See LICENSE for details.

About

High-precision, sub-millisecond LLM hallucination and fact verification engine in Go. Decomposes claims, grounds against source documents, detects numeric distortions, and flags unreliable AI answers.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages