Repository avatar
AI Tools
v0.3.1
active

anti-hallucination

io.github.Jegoba90/anti-hallucination

Checks AI-written reports against your data: Python writes each figure and drops failing sentences.

Documentation

Anti-Hallucination

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.

PyPI version Official MCP Registry version Tests Python 3.11 or newer MIT license Status: experimental

M8ven Score

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 needWhat you get
Keep figures under your controlPython fills {placeholders} from your facts instead of asking a model to type the values
Check a draft you already haveverify() flags unsupported figures, conflicting directions, and other rule violations
Decide what happens when a check failsDrop the sentence or replace it with a fallback you supplied
Explain the outputA decision for each sentence, plus a receipt you can verify and replay
Fit your workflowPython 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.

The LLM writer chooses the words and nothing else: it gets placeholders and rules, none of your figures, which go straight to Python. compose() checks the draft sentence by sentence, with no model: a sentence that passes is kept and Python writes its figures; one that fails is replaced by your fallback or dropped. With write(), failed sentences get one retry with the reasons. Out come the text and a receipt. verify() runs the same checks on an existing text, such as a model's answer.

  • 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() and difference() 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

Checkcompose() — a draft with placeholdersverify() — existing text
FiguresPython fills placeholders; figures copied from a cited source are also allowedEach figure must match a fact at the written precision, or occur in a label or permitted source
Signs and directionsA word such as “fell” or “cayeron” must agree with the change; unsupported movement is flaggedSame
NamesChecks proper names against facts, labels, sources, and known_namesSame
Forecasts, certainty, causesFlags phrases from English and Spanish word lists by defaultSame
Data in every sentenceRequires a placeholder, a checked direction, or a source citationRequires 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.

ExampleWhat it demonstrates
SaaS metrics · EnglishInvented revenue figures, a cause, and a forecast are caught; supplied fallbacks keep the report useful
Support digest · EnglishA ticket summary changes 23 customers to 32 and invents a cause; checks catch both
Sales report · SpanishA draft claims growth while the supplied change is −3.2%
Python walkthroughRun 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.

ToolPurpose
prepare_reportBuild the writing instructions with placeholders and rules
compose_reportFill the draft, run checks, and return text, decisions, and a receipt
verify_textCheck an existing text against the supplied data
check_receiptVerify 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:

  1. prepare_report with the user's figures as facts: it returns a placeholder for each figure and the rules.
  2. The model writes its draft with those placeholders and types no figure.
  3. compose_report with the draft and the same data: Python writes every figure, and the result holds the final text, 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.

RouteBodyDoes
POST /v1/composedraft, data, locale, writerFill a draft with placeholders and keep what passes
POST /v1/verifytext, data, locale, writerCheck a text that already has its figures
POST /v1/preparebrief, data, localeThe placeholders and rules to hand a writer
POST /v1/receiptreceipt, dataVerify a receipt and replay its decision
/mcpThe same four tools over MCP
GET /healthStatus 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:

LimitDefaultSet it with
Request size256 KBANTIHALLUCINATION_MAX_BODY or --max-body (bytes)
Time to check it10 sANTIHALLUCINATION_TIMEOUT or --timeout (seconds)
Memory to check it (Linux and macOS)1024 MBANTIHALLUCINATION_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.

PYPI
antihallucination
Install Command
pip install antihallucination
Runtime: uvx