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 · 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.