Production-grade LLM Hallucination Detection: Benchmarks, Metrics, and RAG Pipeline

// src/handler.ts
import express, { Request, Response } from "express";
import fetch from "node-fetch";

type ID = string;

interface RAGRequest {
  query: string;
  userId: ID;
  contextIds?: ID[];
  traceId?: ID;
}

interface RetrievedDoc {
  id: ID;
  text: string;
  score: number;
}

interface LLMResponse {
  text: string;
  tokens: number;
  model: string;
}

interface DetectorScores {
  retrievalGrounding: number; // 0..1
  nliEntailment: number; // 0..1
  learnedJudge: number; // 0..1 (lower = more hallucination)
  aggregatedScore: number; // 0..1 (higher = trustworthy)
  reasons?: string[];
}

interface Decision {
  pass: boolean;
  reason: string;
  scores: DetectorScores;
  action: "return" | "fallback" | "human_review";
  traceId: ID;
}

const app = express();
app.use(express.json());

/* Placeholder implementations - replace with production connectors */

async function retrieveDocs(query: string, k = 5): Promise<RetrievedDoc[]> {
  // Connect to your dense retriever/vector DB here
  // Example response:
  return [
    { id: "doc:1", text: "Clinical guidance on X ...", score: 0.92 },
    { id: "doc:2", text: "Study Y shows ...", score: 0.88 },
  ].slice(0, k);
}

async function callLLM(prompt: string, model = "gpt-4o-mini"): Promise<LLMResponse> {
  // Replace with production LLM client
  const resp = await fetch("https://example-llm/predict", { method: "POST", body: JSON.stringify({ prompt, model }) });
  const json = await resp.json();
  return { text: json.output_text as string, tokens: json.tokens as number, model };
}

function lexicalGroundingScore(response: string, docs: RetrievedDoc[]): number {
  // Cheap heuristic: ratio of named entities / assertions present in docs (simplified)
  // Use real NER/fuzzy matching in production
  const docText = docs.map((d) => d.text).join(" ");
  const assertions = Array.from(new Set(response.match(/\b[A-Z][a-z]{2,}\b/g) ?? []));
  if (assertions.length === 0) return 0.8; // nothing risky -> optimistic
  const present = assertions.filter((a) => docText.indexOf(a) !== -1).length;
  return present / assertions.length;
}

async function nliEntailmentScore(response: string, docs: RetrievedDoc[]): Promise<number> {
  // Call an NLI microservice; return entailment probability aggregated
  // Placeholder: return 0.9 for demonstration
  return 0.9;
}

async function learnedJudgeScore(response: string, docs: RetrievedDoc[]): Promise<number> {
  // A small evaluator model (e.g., 7B) returns probability that response is grounded
  // Placeholder: call external evaluator
  const resp = await fetch("https://example-eval/predict", { method: "POST", body: JSON.stringify({ response, docs }) });
  const json = await resp.json();
  return json.groundedProb as number;
}

function aggregateScores(scores: Omit<DetectorScores, "aggregatedScore">): DetectorScores {
  const weights = { retrievalGrounding: 0.35, nliEntailment: 0.35, learnedJudge: 0.30 };
  const aggregated =
    scores.retrievalGrounding * weights.retrievalGrounding +
    scores.nliEntailment * weights.nliEntailment +
    scores.learnedJudge * weights.learnedJudge;
  return { ...scores, aggregatedScore: aggregated };
}

function decisionFromScores(scores: DetectorScores, traceId: ID): Decision {
  const passThreshold = 0.7;
  if (scores.aggregatedScore >= passThreshold) {
    return { pass: true, reason: "trusted", action: "return", scores, traceId };
  }
  if (scores.aggregatedScore >= 0.5) {
    return { pass: false, reason: "uncertain", action: "fallback", scores, traceId };
  }
  return { pass: false, reason: "likely_hallucination", action: "human_review", scores, traceId };
}

/* Handler */
app.post("/api/generate", async (req: Request<{}, {}, RAGRequest>, res: Response) => {
  const traceId = req.body.traceId ?? `trace_${Date.now()}`;
  const query = req.body.query;

  const docs = await retrieveDocs(query, 5);
  const prompt = `Context:\n${docs.map((d) => d.text).join("\n---\n")}\n\nUser: ${query}\nAssistant:`;
  const llm = await callLLM(prompt);

  const retrievalGrounding = lexicalGroundingScore(llm.text, docs);
  const nliEntailment = await nliEntailmentScore(llm.text, docs);
  const learnedJudge = await learnedJudgeScore(llm.text, docs);

  let scores: DetectorScores = { retrievalGrounding, nliEntailment, learnedJudge, aggregatedScore: 0, reasons: [] };
  scores = aggregateScores(scores);

  const decision = decisionFromScores(scores, traceId);

  // Emit observability event (replace with real telemetry)
  console.log("observability.event", { traceId, query, decision, llmMeta: { model: llm.model, tokens: llm.tokens } });

  if (decision.action === "return") {
    res.json({ traceId, response: llm.text, decision });
    return;
  } else if (decision.action === "fallback") {
    res.json({ traceId, response: "I'm not confident in the answer. Would you like a human verification?", decision });
    return;
  } else {
    res.status(202).json({ traceId, message: "Requires human review", decision });
    return;
  }
});

export default app;

# eval/auroc.py
from typing import List
import json
import math
import numpy as np
from sklearn.metrics import roc_auc_score

def load_examples(path: str) -> List[dict]:
    with open(path, "r", encoding="utf-8") as fh:
        return [json.loads(line) for line in fh]

def compute_auroc(examples: List[dict], score_field: str = "aggregatedScore", label_field: str = "is_correct") -> float:
    scores = [float(ex[score_field]) for ex in examples]
    labels = [1 if ex[label_field] else 0 for ex in examples]
    if len(set(labels)) < 2:
        raise ValueError("Need both positive and negative labels to compute AUROC")
    return float(roc_auc_score(labels, scores))

if __name__ == "__main__":
    import sys
    examples = load_examples(sys.argv[1])
    auroc = compute_auroc(examples)
    print(f"AUROC: {auroc:.4f}")