Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/TangibleResearch/Halgorithem/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through cloning the repository, setting up a Python environment, and running a verification check against a local truth file. By the end you will have a working script that extracts claims from AI-generated text and prints a per-claim report.
The Engine class in engine.py calls the OpenAI API to generate responses. If you only want to verify existing AI output — not generate it — you can use the Halgorithm class directly and no API key is required.
1

Clone the repository and create a virtual environment

Clone the project and isolate its dependencies in a virtual environment:
git clone https://github.com/TangibleResearch/Halgorithem.git
cd Halgorithem
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
2

Install dependencies

Install all required packages from the project’s requirements file:
pip install -r requirements.txt
3

Download the spaCy language model

Halgorithem uses spaCy for tokenization and entity recognition. Download the large English model:
python -m spacy download en_core_web_lg
4

Write a verification script

Create a file called verify.py in the project root. This example loads a local truth document, passes AI output to compare_to_files(), and prints a report:
from Halgorithem import Halgorithm

algo = Halgorithm(sentences_per_chunk=2, sentence_overlap=1)

# The AI-generated text you want to verify
ai_output = (
    "BASIC was developed in 1964 at Dartmouth College. "
    "It was created by NASA to help students learn programming. "
    "BASIC was interpreted in early versions and used on time-sharing systems."
)

# Compare claims against one or more local truth files
results = algo.compare_to_files(
    truth_file_paths=["sources/basic.txt", "sources/basic2.txt"],
    ai_output=ai_output,
    threshold=0.30,
)

algo.print_report(results)
You can also pass pre-loaded document dicts using compare_to_docs() if you have already read the text into memory:
docs = algo.load_files(["sources/basic.txt", "sources/basic2.txt"])

results = algo.compare_to_docs(
    truth_docs=docs,
    ai_output=ai_output,
    threshold=0.30,
)

algo.print_report(results)
5

Run it and read the output

Execute the script:
python verify.py
You will see output similar to this:
Halgorithm Report
================================================================================
Strongly supported: 2  Weak: 1  Issues: 1
Confidence: 68.75%  —  not reliable
================================================================================
Claim #2 | HALLUCINATION | score 0.183

BASIC was created by NASA to help students learn programming.

Reason: No matching chunk found
Unsupported terms: NASA
Each flagged claim shows the status, similarity score, and unsupported terms so you can trace exactly why the claim failed.
The threshold parameter controls how strict verification is. The default is 0.30. Lowering it flags more claims as hallucinations; raising it is more permissive. Start at 0.30 and adjust based on how much noise appears in your results.

​
Next steps

How it works

Understand the full claim-extraction and scoring pipeline.

AI pipeline integration

Add verification to LangGraph, CrewAI, PydanticAI, or AutoGen workflows.

Build docs developers (and LLMs) love

Get started for freeTalk to us