Skip to main content

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 Tests Python 3.11 or newer MIT license Status: experimental

Quick start  ·  Examples  ·  MCP setup  ·  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

Your facts + rules → Draft with placeholders → Sentence checks → Text + receipt
  • Facts hold values your code computed. Labels hold verdicts your rules chose, such as “a slight decline”; classify() can choose them by threshold.
  • 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.

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.

pip install "antihallucination[mcp]"

Claude Code:

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": "python",
      "args": ["-m", "antihallucination.mcp_server"]
    }
  }
}

The file is in %APPDATA%\Claude\ on Windows and ~/Library/Application Support/Claude/ on macOS. Use the Python executable where you installed the extra; this may be python3 or an absolute path. antihallucination-mcp launches 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

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. Client and model privacy policies still apply.

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.2. 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.

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. The original crypto agent shows the approach in a market-news workflow.

Released under the MIT license.

Metadata

Release files for antihallucination 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for antihallucination 0.2.1
File Size Uploaded Provenance Actions
antihallucination-0.2.1.tar.gz 70.6 kB With provenance Details for antihallucination-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for antihallucination 0.2.1
File Interpreter ABI Platform Actions
antihallucination-0.2.1-py3-none-any.whl Python 3 none any Details for antihallucination-0.2.1-py3-none-any.whl

Total release size: 125.0 kB

Release files / antihallucination-0.2.1.tar.gz

Download URL antihallucination-0.2.1.tar.gz
Size 70.6 kB
Tags Source
SHA-256 checksum
How to use checksums
ac8ed54bb23e09de37e509877bfcb39bb509b8893f9bbd92dd86d4fea92f8427
BLAKE2b-256 checksum
How to use checksums
cc1c2732d893ef73cbca88f116556c3cfe498527b50cda44bb5fcb4d1060a322
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / antihallucination-0.2.1-py3-none-any.whl

Download URL antihallucination-0.2.1-py3-none-any.whl
Size 54.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1c259524d49814a0b5d9741f3cdd8163d62b4850526fa306acb9ce9deb19082e
BLAKE2b-256 checksum
How to use checksums
b2251c9c3a3408e215931932d8df275a0ff3a10abe9ba096240e892a088c73c7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for antihallucination 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for antihallucination-0.2.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page