
anti-hallucination
io.github.Jegoba90/anti-hallucination
Checks AI-written reports against your data: Python writes each figure and drops failing sentences.
Documentation
Your numbers decide. The AI only writes.
Turn your data into AI-written reports with checked figures, sentence-level decisions, and receipts you can replay.
Quick start · Examples · MCP setup · Service · Checks · Contribute
Reports built from your data
A sales summary should use the sales you measured. A support report should keep the customer counts in your tickets. Your code owns the figures and verdicts; Anti-Hallucination lets a writer put them into words, then checks each sentence before it goes out.
| What you need | What you get |
|---|---|
| Keep figures under your control | Python fills {placeholders} from your facts instead of asking a model to type the values |
| Check a draft you already have | verify() flags unsupported figures, conflicting directions, and other rule violations |
| Decide what happens when a check fails | Drop the sentence or replace it with a fallback you supplied |
| Explain the output | A decision for each sentence, plus a receipt you can verify and replay |
| Fit your workflow | Python library, command line, and an MCP server; English and Spanish checks |
Use it for sales reports, SaaS metrics, finance summaries, and support digests.
The checks run locally and use the Python standard library. The package also
installs httpx for optional calls to model providers.
Quick start
Python 3.11+ · The example below runs locally without an API key.
pip install antihallucination
from antihallucination import Fact, compose, verify
facts = [
Fact("sales", 1250, unit="units", subject="sales"),
Fact("sales_change", -3.2, unit="%", change=True, subject="sales"),
]
# The writer uses placeholders. Python fills the figures.
draft = "Sales fell {sales_change:abs} to {sales}. Next quarter will be better."
result = compose(draft, facts, locale="en")
print(result.text)
# Sales fell 3.2% to 1,250 units.
# Check an existing draft against the same facts.
report = verify("Sales grew 5% to 1,300 units.", facts, locale="en")
print([(finding.check, finding.span) for finding in report.findings])
# [('unbacked_number', '5%'), ('unbacked_number', '1,300'), ('direction_contradiction', 'grew')]
The forecast is dropped. The measured decline stays. In the second draft,
both invented figures and the conflicting direction are flagged.
result.decisions explains what happened to each sentence;
result.receipt records the inputs and decisions with a SHA-256 digest.
Let a model write the draft
Install the Claude extra and set ANTHROPIC_API_KEY:
pip install "antihallucination[claude]"
Using the facts from above:
from antihallucination import write
from antihallucination.writers import ClaudeWriter
written = write(
"A two-sentence sales summary for the board.",
facts,
writer=ClaudeWriter(),
locale="en",
)
print(written.text)
write() gives the writer placeholder names, formatting rules, and change
directions while withholding the numeric values in Fact.value. It checks
the draft and can ask for another attempt with the reasons a sentence failed.
Source text, labels, and your brief can still contain numbers.
Prefer another provider? OpenAICompatibleWriter.openai(model),
.groq(model), and .ollama(model) use the same writing pipeline. You can
also pass any function with the signature (system, prompt) -> str.
How it works
The LLM only chooses the words: it writes placeholders instead of your figures,
and Python checks each sentence of the draft and writes the figures into the
sentences that pass. verify() runs the same checks on a text that already has
its figures.
- Facts hold values your code computed. Labels hold verdicts your rules
chose, such as “a slight decline”;
classify()can choose them by threshold. - Computed changes come from two facts:
percent_change()anddifference()compute them exactly, so neither you nor the writer does the arithmetic. The receipt records them as computed, and from which facts. - Sources hold evidence a draft can cite with
[id]. A citation provides context for the checks; it does not prove that the sentence follows from the source. - Fallbacks are sentences you wrote. A failed sentence can be replaced by a fallback for the same subject; otherwise it is dropped.
- Receipts keep the inputs, decisions, and a digest so you can check their consistency and replay the run.
What it checks
| Check | compose() — a draft with placeholders | verify() — existing text |
|---|---|---|
| Figures | Python fills placeholders; figures copied from a cited source are also allowed | Each figure must match a fact at the written precision, or occur in a label or permitted source |
| Signs and directions | A word such as “fell” or “cayeron” must agree with the change; unsupported movement is flagged | Same |
| Names | Checks proper names against facts, labels, sources, and known_names | Same |
| Forecasts, certainty, causes | Flags phrases from English and Spanish word lists by default | Same |
| Data in every sentence | Requires a placeholder, a checked direction, or a source citation | Requires a figure, a verdict from your data, a checked direction, or a citation |
Number parsing follows the locale: 1.250 means a thousand two hundred and
fifty in Spanish, while 1,250 means that in English. It also handles scales
such as 1,2 millones and 4bn, and a vocabulary of numbers written in words.
Large inputs
Checking time grows in line with the size of the text and the data together, for every kind of input found to be slow but one, at the end of this section. On the test machine, a 256 KB report of about 5,000 sentences takes 0.7 s, and the slowest text or mix of text and data found takes 1.1 s.
When the text matches the data over and over, such as one figure that stands
for thousands of facts, the work and the receipt would keep growing. The
checks stop at 200,000 matches and raise TooManyMatches. The examples, made
256 KB long, use at most 6,500.
Two test files keep this from coming back: tests/test_long_texts.py and
tests/test_large_data.py time 17 inputs that took from 6 to more than 25
seconds before, and each must now finish within 3 seconds. The faster code was
also compared with the code before it on tens of thousands of random texts and
data sets, and gave the same receipt, digest included, for every one.
tools/compare_versions.py repeats that comparison against any git ref, and
tools/timing.py shows how each kind of input grows. The
test record
has the numbers.
One case is still slow in the library: data that gives thousands of facts the same subject, named in thousands of sentences (4,000 of each take 17 s). The service stops any request at its time limit.
Examples
Each example includes a data file, a draft with placeholders, and a text written with figures. The test suite checks their expected outputs.
| Example | What it demonstrates |
|---|---|
| SaaS metrics · English | Invented revenue figures, a cause, and a forecast are caught; supplied fallbacks keep the report useful |
| Support digest · English | A ticket summary changes 23 customers to 32 and invents a cause; checks catch both |
| Sales report · Spanish | A draft claims growth while the supplied change is −3.2% |
| Python walkthrough | Run both modes, inspect the decisions, and replay the receipt |
Use with MCP
Use the same checks from Claude Code, Claude Desktop, or another MCP client.
The server exposes four tools and makes no model or network calls itself. It
is listed in the official MCP Registry
as io.github.Jegoba90/anti-hallucination.
Claude Code with uv, which fetches the package on first run:
claude mcp add --transport stdio --scope user anti-hallucination -- uvx --with "antihallucination[mcp]" antihallucination mcp
Claude Code with pip:
pip install "antihallucination[mcp]"
claude mcp add --transport stdio --scope user anti-hallucination -- python -m antihallucination.mcp_server
Claude Desktop configuration
Add this to claude_desktop_config.json:
{
"mcpServers": {
"anti-hallucination": {
"command": "uvx",
"args": ["--with", "antihallucination[mcp]", "antihallucination", "mcp"]
}
}
}
The file is in %APPDATA%\Claude\ on Windows and
~/Library/Application Support/Claude/ on macOS. With pip instead of uv, use
"command": "python" and "args": ["-m", "antihallucination.mcp_server"],
with the Python where you installed the extra; this may be python3 or an
absolute path. antihallucination mcp and antihallucination-mcp launch the
same server.
| Tool | Purpose |
|---|---|
prepare_report | Build the writing instructions with placeholders and rules |
compose_report | Fill the draft, run checks, and return text, decisions, and a receipt |
verify_text | Check an existing text against the supplied data |
check_receipt | Verify receipt consistency and replay its decisions |
How an assistant uses them. The server sends these steps to the client as its instructions, so the model follows them without a prompt:
prepare_reportwith the user's figures asfacts: it returns a placeholder for each figure and the rules.- The model writes its draft with those placeholders and types no figure.
compose_reportwith the draft and the same data: Python writes every figure, and the result holds the finaltext, a decision for each sentence, and a receipt.
verify_text checks a text that already has its figures, and check_receipt
replays a receipt.
The assistant supplies the data. It may already have seen, calculated, or
changed the values. The server checks the text against what it receives; it
does not establish where those values came from. What it can take off the
assistant is the arithmetic: a change between two figures goes in as
{"compute": "percent_change", "from": "...", "to": "..."}, and the server
computes it. Each receipt shows which figures were computed and which were
supplied. Client and model privacy policies still apply.
Privacy and data flow
The four MCP tools run checks on the server's machine, make no outbound model or network calls, and return results to your MCP client. They do not save reports or receipts to disk. Your client may send tool inputs and outputs to its model provider or keep them in conversation history.
Optional writers used through write() or the CLI write command send prompts
to the provider you select. Prompts include source text, the brief, and labels;
placeholders for fact values do not anonymize that content. Receipts contain
fact values and report text, so treat them as sensitive as the original data.
Read the privacy policy for destinations, stored outputs, retention, and self-hosted service details.
Run it as a service
For teams that would rather call an endpoint than add Python to their agent. One container serves the same checks two ways: a REST API for agents in any language, and MCP over HTTP for Claude Code and other MCP clients. It calls no model, keeps nothing between requests, and runs inside your own network.
export ANTIHALLUCINATION_TOKEN=$(openssl rand -hex 32)
docker run -d -p 8000:8000 -e ANTIHALLUCINATION_TOKEN ghcr.io/jegoba90/anti-hallucination
The service ships from v0.3.0 on, and each release publishes the image. docker build -t anti-hallucination . builds it from this repository.
Without Docker, run pip install "antihallucination[server]" and then
antihallucination serve.
| Route | Body | Does |
|---|---|---|
POST /v1/compose | draft, data, locale, writer | Fill a draft with placeholders and keep what passes |
POST /v1/verify | text, data, locale, writer | Check a text that already has its figures |
POST /v1/prepare | brief, data, locale | The placeholders and rules to hand a writer |
POST /v1/receipt | receipt, data | Verify a receipt and replay its decision |
/mcp | The same four tools over MCP | |
GET /health | Status and version |
data is the JSON of the command line's data file, and its locale is the
default; writer names who wrote the text, for the receipt. Responses match
the MCP tools' output.
curl -s localhost:8000/v1/verify \
-H "Authorization: Bearer $ANTIHALLUCINATION_TOKEN" -H "Content-Type: application/json" \
-d '{"text": "Sales grew 5% to 1,300 units.", "locale": "en", "data": {"facts": [
{"name": "sales", "value": 1250, "unit": "units", "subject": "sales"},
{"name": "sales_change", "value": -3.2, "unit": "%", "change": true, "subject": "sales"}]}}'
To connect Claude Code:
claude mcp add --transport http anti-hallucination http://your-host:8000/mcp \
--header "Authorization: Bearer <token>"
Every route except /health needs the token. Without
ANTIHALLUCINATION_TOKEN the service only starts on 127.0.0.1, so the
container will not start without one. Make the token long and random, as
openssl rand -hex 32 does. The service refuses a token shorter than 16
characters.
The service speaks plain HTTP. Without TLS, the token and every report travel in clear text, so anyone on the network path can read and reuse them. Put it behind a proxy that terminates TLS (nginx, Caddy, a cloud load balancer), or reach it only inside a private network you trust. Do not expose its port to the internet directly.
A request must send its body with Content-Type: application/json, or it gets
415. A service on 127.0.0.1 also refuses a Host or Origin header that is
not local, with 421 or 403, on both the REST routes and /mcp. That keeps
a web page from reaching it through the visitor's browser. A proxy on the same
machine must pass a local Host, or the service must listen on another
address, with a token.
Each request is limited, and one past a limit gets 413 while the service
goes on:
| Limit | Default | Set it with |
|---|---|---|
| Request size | 256 KB | ANTIHALLUCINATION_MAX_BODY or --max-body (bytes) |
| Time to check it | 10 s | ANTIHALLUCINATION_TIMEOUT or --timeout (seconds) |
| Memory to check it (Linux and macOS) | 1024 MB | ANTIHALLUCINATION_MAX_MEMORY or --max-memory (MB; 0 for none) |
Each request's checks run in a worker process of their own, so one that runs
long can be stopped without stopping the others. A text that matches the data
more than 200,000 times (say, one figure that stands for thousands of facts) is
refused by the checks themselves, in the library too: TooManyMatches.
A fact's value takes at most 40 digits written out in full: 1e39 and 1e-39
fit, 1e40 does not. The receipt writes every digit, so without this limit a
64-byte request with 1e-10000000 would get a 10 MB answer. A longer value is
refused with 400, and with ValueError in the library.
Command line
antihallucination verify examples/saas/written_by_an_ai.txt --data examples/saas/data.json
antihallucination compose examples/saas/draft.txt --data examples/saas/data.json --receipt receipt.json
antihallucination receipt receipt.json --data examples/saas/data.json
antihallucination write --data examples/saas/data.json --brief "A short monthly update for the team."
python -m antihallucination works too. The data file holds facts, labels,
sources, fallbacks, and known names; its format is documented in
antihallucination/data.py.
Exit codes: 0 all sentences passed, 1 checks failed, 2 invalid input,
3 writer failure.
Scope and limitations
Experimental · v0.3. This is a layer of explicit rules for text generated from supplied data. It is not a general factuality or semantic entailment checker.
- It does not establish that your facts are true or that your sources support every possible paraphrase. A source citation alone is not proof.
- Names, directions, forecasts, certainty, causes, and numbers written in words use heuristics and word lists. Phrasings outside those rules can pass; a name at the start of a sentence is not checked.
- A sentence can carry a valid figure and still add an unsupported opinion. Put verdicts in labels and keep human review where it matters.
- A receipt's SHA-256 digest checks internal consistency. It is unkeyed and does not authenticate the author or the origin of the data.
The test record includes real Groq drafts and a Claude Code MCP session, along with what has and has not been tested live. CI runs the tests on Python 3.11, 3.13, and 3.14, plus minimal-install and installed-wheel checks. The security review lists what was found before v0.3.0, how each point was fixed, and what remains.
Contributing
Found a phrasing the checks miss? Have a report that needs a clearer decision? Open an issue with a small example, or read the contribution guide to run the checks and submit a change.
pip install -e ".[dev]"
pytest tests/ -v
mypy .
ruff check .
Origin and license
Extracted from the reporting engine behind CryptoCapi, where it checks the market reports a crypto agent writes.
Released under the MIT license.
antihallucinationpip install antihallucination