Technical Guide: Detecting AI Hallucinations with Halgorithem

Practical Summary and Core Functionality

Halgorithem, also known by its codename CORE (Claim-Oriented Recognition Engine), is a deterministic library designed to identify AI hallucinations by comparing generated text against trusted source material. Unlike probabilistic methods, Halgorithem extracts factual claims from AI output and cross-references them with provided documents to assign a specific status to each claim. The tool categorizes findings into statuses such as SUPPORTED, WEAK_SUPPORT, CONTRADICTION, HALLUCINATION, UNVERIFIABLE_DENIAL, or ERROR. By utilizing semantic similarity via sentence-transformer embeddings and deterministic guardrails for specific data types like dates, numbers, and units, it provides a structured approach to verifying AI-generated content within data pipelines.

Prerequisites and Installation

To utilize Halgorithem, users must have a Python environment configured. The library is installed via pip, and it relies on spaCy for linguistic processing. While the tool can function with a minimal configuration, it is recommended to install a larger spaCy model for improved accuracy. If no spaCy model is detected, the library defaults to spacy.blank("en") to prevent system crashes, albeit with reduced linguistic precision. The installation process is straightforward:

python -m pip install -e .
python -m spacy download en_core_web_lg

Users should ensure their environment can handle local model caching, as the tool prioritizes offline operation to maintain deterministic behavior and data privacy.

The CORE Verification Pipeline

The HalgorithemVerifier provides a robust pipeline for processing AI output. This workflow involves document ingestion followed by three distinct verification layers: similarity retrieval using sentence-transformers/all-mpnet-base-v2, sentence-level Natural Language Inference (NLI) via cross-encoder/nli-deberta-v3-large, and atomic claim NLI using REBEL-style triplets from Babelscape/rebel-large. This multi-stage approach ensures that claims are evaluated not just on surface-level word matching, but on semantic and logical consistency. All model loads are local by default, ensuring the pipeline remains network-free during execution. If specific components like REBEL or DeBERTa are missing, the system falls back to deterministic local checks and logs the event in the diagnostics output.

Workflow and Usage Examples

Halgorithem supports both in-memory document verification and file-based analysis. For quick testing, users can pass strings directly to the compare_to_docs method. For production-grade pipelines, the library allows for file-path ingestion, which is useful for verifying large datasets against source files. The following example demonstrates the basic implementation for comparing AI output against a known source:

from Halgorithem import Halgorithm

algo = Halgorithm()

results = algo.compare_to_docs(
    truth_docs=[
        {
            "file_id": 1,
            "file_path": "source.txt",
            "text": "BASIC was created in 1964 by John Kemeny at Dartmouth College.",
        }
    ],
    ai_output="BASIC was created in 1972 by NASA.",
)

for result in results:
    print(result["status"], result["claim"], result["reason"])

Interpreting Output and Verdicts

The output of a Halgorithem verification is a structured JSON object containing detailed metadata for every claim extracted from the AI response. Key fields include the status, confidence score, matched_source, and unsupported_terms. The status field is critical for automated decision-making in pipelines. For instance, a SUPPORTED verdict indicates strong evidence, while CONTRADICTION flags direct conflicts. UNVERIFIABLE_DENIAL is used when an AI denies a fact that is not present in the source, highlighting the limitation that absence of evidence is not evidence of absence. Users should monitor the warning field for potential issues during the parsing or verification process.

Limitations and Runtime Hardening

While Halgorithem is designed for robustness, it has documented limitations. The rule-based entity-role detection is limited to common patterns and does not handle complex, arbitrary grammar. Semantic verification is dependent on the quality of the local sentence-transformer model; while a lexical hashing fallback exists, it is less sensitive to meaning. Furthermore, table-like facts are most accurately processed when row values are physically proximate in the source text. The tool is hardened against common runtime errors, such as empty files, malformed UTF-8 encoding, or missing dependencies, ensuring that the pipeline continues to function even when encountering malformed input or missing model files.

Benchmark and Quality Assurance

To ensure reliability, Halgorithem includes a built-in benchmark suite accessible via bench.py. This suite evaluates the engine across various categories, including paraphrases, date mismatches, entity-role swaps, and multi-source disagreement. The benchmark reports accuracy metrics, confusion matrices, and failure logs, allowing developers to set pass/fail thresholds for their specific use cases. The test suite is designed to be entirely network-free, relying solely on local documents. This focus on local, deterministic testing makes the library suitable for CI/CD environments where consistency and reproducibility are paramount. Users are encouraged to review the official documentation for further details on benchmark configuration.

Target Audience and Use Cases

Halgorithem is intended for developers and data engineers building AI-driven applications who require a deterministic method to audit model outputs. It is particularly useful in domains where factual accuracy is non-negotiable, such as technical documentation, legal analysis, or research synthesis. By integrating Halgorithem into a data pipeline, teams can automatically flag potential hallucinations before they reach end-users. Because the tool operates locally and avoids external API calls for the verification logic itself, it is an appropriate choice for organizations with strict data privacy requirements. It is not intended for real-time creative writing tasks where semantic nuance might be secondary to stylistic generation.