antihallucination 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- antihallucination-0.2.0/LICENSE +21 -0
- antihallucination-0.2.0/PKG-INFO +249 -0
- antihallucination-0.2.0/README.md +213 -0
- antihallucination-0.2.0/antihallucination/__init__.py +58 -0
- antihallucination-0.2.0/antihallucination/__main__.py +3 -0
- antihallucination-0.2.0/antihallucination/checks.py +509 -0
- antihallucination-0.2.0/antihallucination/cli.py +201 -0
- antihallucination-0.2.0/antihallucination/core.py +334 -0
- antihallucination-0.2.0/antihallucination/data.py +199 -0
- antihallucination-0.2.0/antihallucination/errors.py +5 -0
- antihallucination-0.2.0/antihallucination/facts.py +227 -0
- antihallucination-0.2.0/antihallucination/lexicon.py +113 -0
- antihallucination-0.2.0/antihallucination/mcp_server.py +266 -0
- antihallucination-0.2.0/antihallucination/numbers.py +312 -0
- antihallucination-0.2.0/antihallucination/prompt.py +176 -0
- antihallucination-0.2.0/antihallucination/py.typed +0 -0
- antihallucination-0.2.0/antihallucination/receipt.py +145 -0
- antihallucination-0.2.0/antihallucination/text.py +116 -0
- antihallucination-0.2.0/antihallucination/writers/__init__.py +12 -0
- antihallucination-0.2.0/antihallucination/writers/claude.py +90 -0
- antihallucination-0.2.0/antihallucination/writers/openai_compatible.py +128 -0
- antihallucination-0.2.0/antihallucination/writing.py +116 -0
- antihallucination-0.2.0/antihallucination.egg-info/PKG-INFO +249 -0
- antihallucination-0.2.0/antihallucination.egg-info/SOURCES.txt +41 -0
- antihallucination-0.2.0/antihallucination.egg-info/dependency_links.txt +1 -0
- antihallucination-0.2.0/antihallucination.egg-info/entry_points.txt +3 -0
- antihallucination-0.2.0/antihallucination.egg-info/requires.txt +15 -0
- antihallucination-0.2.0/antihallucination.egg-info/top_level.txt +1 -0
- antihallucination-0.2.0/pyproject.toml +59 -0
- antihallucination-0.2.0/setup.cfg +4 -0
- antihallucination-0.2.0/tests/test_cli.py +169 -0
- antihallucination-0.2.0/tests/test_compose.py +291 -0
- antihallucination-0.2.0/tests/test_examples.py +84 -0
- antihallucination-0.2.0/tests/test_mcp_server.py +132 -0
- antihallucination-0.2.0/tests/test_numbers.py +151 -0
- antihallucination-0.2.0/tests/test_prompt.py +128 -0
- antihallucination-0.2.0/tests/test_readme.py +85 -0
- antihallucination-0.2.0/tests/test_real_model.py +51 -0
- antihallucination-0.2.0/tests/test_receipt.py +130 -0
- antihallucination-0.2.0/tests/test_verify.py +191 -0
- antihallucination-0.2.0/tests/test_write.py +135 -0
- antihallucination-0.2.0/tests/test_writer_claude.py +120 -0
- antihallucination-0.2.0/tests/test_writers.py +104 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 CryptoCapi
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,249 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: antihallucination
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Your numbers decide; the AI only writes. Every figure, direction and name an AI writes is checked against your data.
|
|
5
|
+
Author: CryptoCapi
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/Jegoba90/anti-hallucination
|
|
8
|
+
Project-URL: Issues, https://github.com/Jegoba90/anti-hallucination/issues
|
|
9
|
+
Keywords: llm,hallucination,guardrails,fact-checking,reports,nlg
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Operating System :: OS Independent
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
18
|
+
Classifier: Topic :: Text Processing :: Linguistic
|
|
19
|
+
Classifier: Typing :: Typed
|
|
20
|
+
Requires-Python: >=3.11
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Requires-Dist: httpx>=0.27
|
|
24
|
+
Provides-Extra: claude
|
|
25
|
+
Requires-Dist: anthropic>=2.8.0; extra == "claude"
|
|
26
|
+
Provides-Extra: mcp
|
|
27
|
+
Requires-Dist: mcp>=2.3.0; extra == "mcp"
|
|
28
|
+
Requires-Dist: typing_extensions>=4.12; extra == "mcp"
|
|
29
|
+
Provides-Extra: dev
|
|
30
|
+
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
31
|
+
Requires-Dist: mypy>=1.10; extra == "dev"
|
|
32
|
+
Requires-Dist: ruff==0.14.9; extra == "dev"
|
|
33
|
+
Requires-Dist: anthropic>=2.8.0; extra == "dev"
|
|
34
|
+
Requires-Dist: mcp>=2.3.0; extra == "dev"
|
|
35
|
+
Dynamic: license-file
|
|
36
|
+
|
|
37
|
+
# Anti-Hallucination
|
|
38
|
+
|
|
39
|
+
**Your numbers decide; the AI only writes.**
|
|
40
|
+
|
|
41
|
+
A Python layer for any text an AI writes from data: a sales report, a monthly
|
|
42
|
+
metrics summary, a finance update, a summary of tickets or articles. Your code
|
|
43
|
+
computes the figures and decides the verdicts. The AI writes with placeholders
|
|
44
|
+
and never sees a value. Every sentence is checked against your data before it
|
|
45
|
+
goes out; a sentence that fails is dropped or replaced by one you wrote, never
|
|
46
|
+
repaired. Each decision is kept in a receipt you can verify and run again.
|
|
47
|
+
|
|
48
|
+
*Experimental (v0.2). The checks use only the Python standard library.*
|
|
49
|
+
|
|
50
|
+
## Install
|
|
51
|
+
|
|
52
|
+
Requires Python 3.11 or later.
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
pip install antihallucination
|
|
56
|
+
|
|
57
|
+
# To let Claude write the drafts as well:
|
|
58
|
+
pip install "antihallucination[claude]"
|
|
59
|
+
|
|
60
|
+
# To use it from Claude Desktop, Claude Code or any MCP client:
|
|
61
|
+
pip install "antihallucination[mcp]"
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## How it works
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
from antihallucination import Fact, compose, verify
|
|
68
|
+
|
|
69
|
+
facts = [
|
|
70
|
+
Fact("sales", 1250, unit="units", subject="sales"),
|
|
71
|
+
Fact("sales_change", -3.2, unit="%", change=True, subject="sales"),
|
|
72
|
+
]
|
|
73
|
+
|
|
74
|
+
# The writer (any LLM, or a person) writes placeholders; Python writes the figures.
|
|
75
|
+
draft = "Sales fell {sales_change:abs} to {sales}. Next quarter will be better."
|
|
76
|
+
result = compose(draft, facts, locale="en")
|
|
77
|
+
print(result.text)
|
|
78
|
+
# Sales fell 3.2% to 1,250 units.
|
|
79
|
+
|
|
80
|
+
# A text someone already wrote, figures typed in, checked against the same facts.
|
|
81
|
+
report = verify("Sales grew 5% to 1,300 units.", facts, locale="en")
|
|
82
|
+
print([(finding.check, finding.span) for finding in report.findings])
|
|
83
|
+
# [('unbacked_number', '5%'), ('unbacked_number', '1,300'), ('direction_contradiction', 'grew')]
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
The forecast in the draft was dropped. `result.decisions` says why, sentence by
|
|
87
|
+
sentence, and `result.receipt` holds the inputs, each decision and a SHA-256
|
|
88
|
+
digest.
|
|
89
|
+
|
|
90
|
+
- `compose()` is for text you are about to publish: the writer uses
|
|
91
|
+
placeholders (`{sales}`, `{sales_change:abs}`, `{sales_change:signed}`) and
|
|
92
|
+
never types a figure.
|
|
93
|
+
- `verify()` is for text someone already wrote: every figure must match one of
|
|
94
|
+
your facts at the precision written, or appear in a label or a source.
|
|
95
|
+
- `Label` and `classify()` hold verdicts your rules decided ("a slight
|
|
96
|
+
decline"), so the writer places them instead of choosing them.
|
|
97
|
+
- `Source` holds a text the writer may summarize. A sentence that cites it as
|
|
98
|
+
`[id]` may only state what that source says.
|
|
99
|
+
- `fallbacks` hold sentences you wrote. When a sentence about the same subject
|
|
100
|
+
fails, yours goes out in its place.
|
|
101
|
+
|
|
102
|
+
## What it checks
|
|
103
|
+
|
|
104
|
+
| Check | `compose()` | `verify()` |
|
|
105
|
+
|---|---|---|
|
|
106
|
+
| Figures | The writer types none. A sentence that cites a source may copy that source's figures | Each figure is a fact rounded to the precision written, or appears in a label or a source |
|
|
107
|
+
| Signs and directions | «fell» or «cayeron» must agree with the sign of the change; a move with no change or source behind it is flagged | Same |
|
|
108
|
+
| Names | Each proper name must appear in your facts, labels, sources or `known_names` | Same |
|
|
109
|
+
| Forecasts, certainty, causes | Dropped by default, from word lists in Spanish and English | Same |
|
|
110
|
+
| Data in every sentence | A sentence must carry a placeholder or cite a source | A sentence must carry a figure or verdict from your data, a move checked against a change, or a citation |
|
|
111
|
+
|
|
112
|
+
Figures are read the way their language writes them: «1.250» is a thousand two
|
|
113
|
+
hundred and fifty in Spanish and one and a quarter in English, «1,2 millones»
|
|
114
|
+
and «4bn» carry their scale, and «tres» or «twenty-five» are figures too.
|
|
115
|
+
|
|
116
|
+
**What it can show:** no digit or numeric character (², ½, Ⅲ) in a composed
|
|
117
|
+
text was typed by the writer; each comes from your facts, labels and fallbacks,
|
|
118
|
+
or from the source its sentence cites. In a verified text, each figure written
|
|
119
|
+
in digits matches a fact or appears in a label or source. Numbers written in
|
|
120
|
+
words are caught from a list. Every sentence that goes out carries something
|
|
121
|
+
from your data or cites a source, whatever its words: «performance remains
|
|
122
|
+
within the expected parameters» carries nothing and is cut.
|
|
123
|
+
|
|
124
|
+
**What it cannot show:** that your facts are right, or that a sentence carrying
|
|
125
|
+
your data claims no more than it in words the lists do not contain («sales were
|
|
126
|
+
{sales}, a solid result»). Word lists only catch the phrasings they hold;
|
|
127
|
+
keeping verdicts in labels and figures in placeholders does not depend on them.
|
|
128
|
+
A name that opens a sentence is not checked. The receipt's digest is unkeyed:
|
|
129
|
+
it shows that a receipt is internally consistent, not who issued it.
|
|
130
|
+
|
|
131
|
+
## Let a model write
|
|
132
|
+
|
|
133
|
+
```python
|
|
134
|
+
from antihallucination import write
|
|
135
|
+
from antihallucination.writers import ClaudeWriter # pip install "antihallucination[claude]"
|
|
136
|
+
|
|
137
|
+
written = write("A two-sentence sales summary for the board.", facts, writer=ClaudeWriter(), locale="en")
|
|
138
|
+
print(written.text)
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
The model is told each placeholder, what it measures, the shape Python will
|
|
142
|
+
write («N units») and which way each change went. It is never shown a value.
|
|
143
|
+
Its draft then goes through `compose()`. If a sentence fails, the model is asked
|
|
144
|
+
again with the reasons, still without values; the attempt with fewer failed
|
|
145
|
+
sentences goes out, and a sentence that still fails is dropped or replaced by
|
|
146
|
+
your fallback.
|
|
147
|
+
|
|
148
|
+
`ClaudeWriter` runs `claude-opus-5-5` through the Anthropic SDK, with the
|
|
149
|
+
server-side fallback on: if the model declines, the API runs the request again
|
|
150
|
+
on another model. `OpenAICompatibleWriter.openai(model)`, `.groq(model)` and
|
|
151
|
+
`.ollama(model)` cover OpenAI, Groq and local models. Any function that takes
|
|
152
|
+
`(system, prompt)` and returns text is a writer too.
|
|
153
|
+
|
|
154
|
+
## From the command line
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
antihallucination verify examples/saas/written_by_an_ai.txt --data examples/saas/data.json
|
|
158
|
+
antihallucination compose examples/saas/draft.txt --data examples/saas/data.json --receipt receipt.json
|
|
159
|
+
antihallucination receipt receipt.json --data examples/saas/data.json
|
|
160
|
+
antihallucination write --data examples/saas/data.json --brief "A short monthly update for the team."
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
`python -m antihallucination` works the same. The data file holds the facts,
|
|
164
|
+
labels, sources, fallbacks and known names; a label can be decided by
|
|
165
|
+
thresholds from a fact. [`antihallucination/data.py`](https://github.com/Jegoba90/anti-hallucination/blob/main/antihallucination/data.py)
|
|
166
|
+
documents its format. The exit status is 0 when every sentence passed, 1 when
|
|
167
|
+
some failed, 2 when the input cannot be read and 3 when the writer failed.
|
|
168
|
+
|
|
169
|
+
## Use it from Claude or any MCP client
|
|
170
|
+
|
|
171
|
+
No code needed: an assistant that speaks MCP writes the text, and the layer
|
|
172
|
+
writes every figure and checks every sentence before the text reaches you. The
|
|
173
|
+
server calls no model and no network, so your data stays on your machine.
|
|
174
|
+
|
|
175
|
+
Claude Code:
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
claude mcp add --transport stdio --scope user anti-hallucination -- python -m antihallucination.mcp_server
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Claude Desktop, in `claude_desktop_config.json` (on Windows in
|
|
182
|
+
`%APPDATA%\Claude\`, on macOS in `~/Library/Application Support/Claude/`):
|
|
183
|
+
|
|
184
|
+
```json
|
|
185
|
+
{
|
|
186
|
+
"mcpServers": {
|
|
187
|
+
"anti-hallucination": {
|
|
188
|
+
"command": "python",
|
|
189
|
+
"args": ["-m", "antihallucination.mcp_server"]
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Use the `python` you installed the package with (on macOS it may be
|
|
196
|
+
`python3`). The installed `antihallucination-mcp` command starts the same
|
|
197
|
+
server. Then give the assistant your figures and ask it to write with the
|
|
198
|
+
anti-hallucination tools:
|
|
199
|
+
|
|
200
|
+
| Tool | What it does |
|
|
201
|
+
|---|---|
|
|
202
|
+
| `prepare_report` | Gives the placeholders and the rules for a brief, without any figure |
|
|
203
|
+
| `compose_report` | Fills a draft written with placeholders, keeps the sentences that pass, and returns the text, why each sentence went out or not, and a receipt |
|
|
204
|
+
| `verify_text` | Checks a text that already has its figures |
|
|
205
|
+
| `check_receipt` | Verifies a receipt and runs its decision again |
|
|
206
|
+
|
|
207
|
+
The assistant has seen your figures, so here the guarantee is not that it never
|
|
208
|
+
saw them: it is that none of them reaches the text unless Python writes it.
|
|
209
|
+
|
|
210
|
+
## Examples
|
|
211
|
+
|
|
212
|
+
| Example | Language | What it shows |
|
|
213
|
+
|---|---|---|
|
|
214
|
+
| [`examples/saas/`](https://github.com/Jegoba90/anti-hallucination/tree/main/examples/saas) | English | Monthly SaaS metrics: invented figures and a forecast are replaced by your sentences |
|
|
215
|
+
| [`examples/support/`](https://github.com/Jegoba90/anti-hallucination/tree/main/examples/support) | English | A summary of support tickets: each sentence may only state what the ticket it cites says |
|
|
216
|
+
| [`examples/sales/`](https://github.com/Jegoba90/anti-hallucination/tree/main/examples/sales) | Spanish | A quarterly sales report, with a verdict decided by thresholds |
|
|
217
|
+
| [`examples/sales_report.py`](https://github.com/Jegoba90/anti-hallucination/blob/main/examples/sales_report.py) | Spanish | The same report from Python, with both modes and the receipt |
|
|
218
|
+
|
|
219
|
+
Each folder has a `data.json`, a text written with figures typed in
|
|
220
|
+
(`written_by_an_ai.txt`) and a draft with placeholders (`draft.txt`).
|
|
221
|
+
|
|
222
|
+
## Tested with a real model
|
|
223
|
+
|
|
224
|
+
On 2026-11-16 `openai/gpt-oss-120b`, on Groq, wrote four drafts of the Spanish
|
|
225
|
+
sales report. It typed no figure. In the first draft one sentence carried no
|
|
226
|
+
data, «El desempeño general se mantiene dentro de los parámetros esperados», and
|
|
227
|
+
passed every check; the rule that every sentence must carry data came from it,
|
|
228
|
+
and the three drafts after it kept all their sentences. The drafts are kept in
|
|
229
|
+
[`tests/fixtures/real_model/`](https://github.com/Jegoba90/anti-hallucination/tree/main/tests/fixtures/real_model) and judged on every
|
|
230
|
+
test run. Claude has not run against the live API yet. The record is in
|
|
231
|
+
[`docs/pruebas-2026-11-16.md`](https://github.com/Jegoba90/anti-hallucination/blob/main/docs/pruebas-2026-11-16.md).
|
|
232
|
+
|
|
233
|
+
## Where it comes from
|
|
234
|
+
|
|
235
|
+
This is the method of the engine behind [CryptoCapi](https://cryptocapi.com),
|
|
236
|
+
where the model writes one line per news note and Python writes every market
|
|
237
|
+
figure. [anti-hallucination-crypto-agent](https://github.com/Jegoba90/anti-hallucination-crypto-agent)
|
|
238
|
+
shows that engine's output and seals in a terminal.
|
|
239
|
+
|
|
240
|
+
## Development
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
pip install -e ".[dev]"
|
|
244
|
+
pytest
|
|
245
|
+
mypy .
|
|
246
|
+
ruff check .
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
MIT license.
|
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
# Anti-Hallucination
|
|
2
|
+
|
|
3
|
+
**Your numbers decide; the AI only writes.**
|
|
4
|
+
|
|
5
|
+
A Python layer for any text an AI writes from data: a sales report, a monthly
|
|
6
|
+
metrics summary, a finance update, a summary of tickets or articles. Your code
|
|
7
|
+
computes the figures and decides the verdicts. The AI writes with placeholders
|
|
8
|
+
and never sees a value. Every sentence is checked against your data before it
|
|
9
|
+
goes out; a sentence that fails is dropped or replaced by one you wrote, never
|
|
10
|
+
repaired. Each decision is kept in a receipt you can verify and run again.
|
|
11
|
+
|
|
12
|
+
*Experimental (v0.2). The checks use only the Python standard library.*
|
|
13
|
+
|
|
14
|
+
## Install
|
|
15
|
+
|
|
16
|
+
Requires Python 3.11 or later.
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
pip install antihallucination
|
|
20
|
+
|
|
21
|
+
# To let Claude write the drafts as well:
|
|
22
|
+
pip install "antihallucination[claude]"
|
|
23
|
+
|
|
24
|
+
# To use it from Claude Desktop, Claude Code or any MCP client:
|
|
25
|
+
pip install "antihallucination[mcp]"
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## How it works
|
|
29
|
+
|
|
30
|
+
```python
|
|
31
|
+
from antihallucination import Fact, compose, verify
|
|
32
|
+
|
|
33
|
+
facts = [
|
|
34
|
+
Fact("sales", 1250, unit="units", subject="sales"),
|
|
35
|
+
Fact("sales_change", -3.2, unit="%", change=True, subject="sales"),
|
|
36
|
+
]
|
|
37
|
+
|
|
38
|
+
# The writer (any LLM, or a person) writes placeholders; Python writes the figures.
|
|
39
|
+
draft = "Sales fell {sales_change:abs} to {sales}. Next quarter will be better."
|
|
40
|
+
result = compose(draft, facts, locale="en")
|
|
41
|
+
print(result.text)
|
|
42
|
+
# Sales fell 3.2% to 1,250 units.
|
|
43
|
+
|
|
44
|
+
# A text someone already wrote, figures typed in, checked against the same facts.
|
|
45
|
+
report = verify("Sales grew 5% to 1,300 units.", facts, locale="en")
|
|
46
|
+
print([(finding.check, finding.span) for finding in report.findings])
|
|
47
|
+
# [('unbacked_number', '5%'), ('unbacked_number', '1,300'), ('direction_contradiction', 'grew')]
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The forecast in the draft was dropped. `result.decisions` says why, sentence by
|
|
51
|
+
sentence, and `result.receipt` holds the inputs, each decision and a SHA-256
|
|
52
|
+
digest.
|
|
53
|
+
|
|
54
|
+
- `compose()` is for text you are about to publish: the writer uses
|
|
55
|
+
placeholders (`{sales}`, `{sales_change:abs}`, `{sales_change:signed}`) and
|
|
56
|
+
never types a figure.
|
|
57
|
+
- `verify()` is for text someone already wrote: every figure must match one of
|
|
58
|
+
your facts at the precision written, or appear in a label or a source.
|
|
59
|
+
- `Label` and `classify()` hold verdicts your rules decided ("a slight
|
|
60
|
+
decline"), so the writer places them instead of choosing them.
|
|
61
|
+
- `Source` holds a text the writer may summarize. A sentence that cites it as
|
|
62
|
+
`[id]` may only state what that source says.
|
|
63
|
+
- `fallbacks` hold sentences you wrote. When a sentence about the same subject
|
|
64
|
+
fails, yours goes out in its place.
|
|
65
|
+
|
|
66
|
+
## What it checks
|
|
67
|
+
|
|
68
|
+
| Check | `compose()` | `verify()` |
|
|
69
|
+
|---|---|---|
|
|
70
|
+
| Figures | The writer types none. A sentence that cites a source may copy that source's figures | Each figure is a fact rounded to the precision written, or appears in a label or a source |
|
|
71
|
+
| Signs and directions | «fell» or «cayeron» must agree with the sign of the change; a move with no change or source behind it is flagged | Same |
|
|
72
|
+
| Names | Each proper name must appear in your facts, labels, sources or `known_names` | Same |
|
|
73
|
+
| Forecasts, certainty, causes | Dropped by default, from word lists in Spanish and English | Same |
|
|
74
|
+
| Data in every sentence | A sentence must carry a placeholder or cite a source | A sentence must carry a figure or verdict from your data, a move checked against a change, or a citation |
|
|
75
|
+
|
|
76
|
+
Figures are read the way their language writes them: «1.250» is a thousand two
|
|
77
|
+
hundred and fifty in Spanish and one and a quarter in English, «1,2 millones»
|
|
78
|
+
and «4bn» carry their scale, and «tres» or «twenty-five» are figures too.
|
|
79
|
+
|
|
80
|
+
**What it can show:** no digit or numeric character (², ½, Ⅲ) in a composed
|
|
81
|
+
text was typed by the writer; each comes from your facts, labels and fallbacks,
|
|
82
|
+
or from the source its sentence cites. In a verified text, each figure written
|
|
83
|
+
in digits matches a fact or appears in a label or source. Numbers written in
|
|
84
|
+
words are caught from a list. Every sentence that goes out carries something
|
|
85
|
+
from your data or cites a source, whatever its words: «performance remains
|
|
86
|
+
within the expected parameters» carries nothing and is cut.
|
|
87
|
+
|
|
88
|
+
**What it cannot show:** that your facts are right, or that a sentence carrying
|
|
89
|
+
your data claims no more than it in words the lists do not contain («sales were
|
|
90
|
+
{sales}, a solid result»). Word lists only catch the phrasings they hold;
|
|
91
|
+
keeping verdicts in labels and figures in placeholders does not depend on them.
|
|
92
|
+
A name that opens a sentence is not checked. The receipt's digest is unkeyed:
|
|
93
|
+
it shows that a receipt is internally consistent, not who issued it.
|
|
94
|
+
|
|
95
|
+
## Let a model write
|
|
96
|
+
|
|
97
|
+
```python
|
|
98
|
+
from antihallucination import write
|
|
99
|
+
from antihallucination.writers import ClaudeWriter # pip install "antihallucination[claude]"
|
|
100
|
+
|
|
101
|
+
written = write("A two-sentence sales summary for the board.", facts, writer=ClaudeWriter(), locale="en")
|
|
102
|
+
print(written.text)
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
The model is told each placeholder, what it measures, the shape Python will
|
|
106
|
+
write («N units») and which way each change went. It is never shown a value.
|
|
107
|
+
Its draft then goes through `compose()`. If a sentence fails, the model is asked
|
|
108
|
+
again with the reasons, still without values; the attempt with fewer failed
|
|
109
|
+
sentences goes out, and a sentence that still fails is dropped or replaced by
|
|
110
|
+
your fallback.
|
|
111
|
+
|
|
112
|
+
`ClaudeWriter` runs `claude-opus-5-5` through the Anthropic SDK, with the
|
|
113
|
+
server-side fallback on: if the model declines, the API runs the request again
|
|
114
|
+
on another model. `OpenAICompatibleWriter.openai(model)`, `.groq(model)` and
|
|
115
|
+
`.ollama(model)` cover OpenAI, Groq and local models. Any function that takes
|
|
116
|
+
`(system, prompt)` and returns text is a writer too.
|
|
117
|
+
|
|
118
|
+
## From the command line
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
antihallucination verify examples/saas/written_by_an_ai.txt --data examples/saas/data.json
|
|
122
|
+
antihallucination compose examples/saas/draft.txt --data examples/saas/data.json --receipt receipt.json
|
|
123
|
+
antihallucination receipt receipt.json --data examples/saas/data.json
|
|
124
|
+
antihallucination write --data examples/saas/data.json --brief "A short monthly update for the team."
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
`python -m antihallucination` works the same. The data file holds the facts,
|
|
128
|
+
labels, sources, fallbacks and known names; a label can be decided by
|
|
129
|
+
thresholds from a fact. [`antihallucination/data.py`](https://github.com/Jegoba90/anti-hallucination/blob/main/antihallucination/data.py)
|
|
130
|
+
documents its format. The exit status is 0 when every sentence passed, 1 when
|
|
131
|
+
some failed, 2 when the input cannot be read and 3 when the writer failed.
|
|
132
|
+
|
|
133
|
+
## Use it from Claude or any MCP client
|
|
134
|
+
|
|
135
|
+
No code needed: an assistant that speaks MCP writes the text, and the layer
|
|
136
|
+
writes every figure and checks every sentence before the text reaches you. The
|
|
137
|
+
server calls no model and no network, so your data stays on your machine.
|
|
138
|
+
|
|
139
|
+
Claude Code:
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
claude mcp add --transport stdio --scope user anti-hallucination -- python -m antihallucination.mcp_server
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Claude Desktop, in `claude_desktop_config.json` (on Windows in
|
|
146
|
+
`%APPDATA%\Claude\`, on macOS in `~/Library/Application Support/Claude/`):
|
|
147
|
+
|
|
148
|
+
```json
|
|
149
|
+
{
|
|
150
|
+
"mcpServers": {
|
|
151
|
+
"anti-hallucination": {
|
|
152
|
+
"command": "python",
|
|
153
|
+
"args": ["-m", "antihallucination.mcp_server"]
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Use the `python` you installed the package with (on macOS it may be
|
|
160
|
+
`python3`). The installed `antihallucination-mcp` command starts the same
|
|
161
|
+
server. Then give the assistant your figures and ask it to write with the
|
|
162
|
+
anti-hallucination tools:
|
|
163
|
+
|
|
164
|
+
| Tool | What it does |
|
|
165
|
+
|---|---|
|
|
166
|
+
| `prepare_report` | Gives the placeholders and the rules for a brief, without any figure |
|
|
167
|
+
| `compose_report` | Fills a draft written with placeholders, keeps the sentences that pass, and returns the text, why each sentence went out or not, and a receipt |
|
|
168
|
+
| `verify_text` | Checks a text that already has its figures |
|
|
169
|
+
| `check_receipt` | Verifies a receipt and runs its decision again |
|
|
170
|
+
|
|
171
|
+
The assistant has seen your figures, so here the guarantee is not that it never
|
|
172
|
+
saw them: it is that none of them reaches the text unless Python writes it.
|
|
173
|
+
|
|
174
|
+
## Examples
|
|
175
|
+
|
|
176
|
+
| Example | Language | What it shows |
|
|
177
|
+
|---|---|---|
|
|
178
|
+
| [`examples/saas/`](https://github.com/Jegoba90/anti-hallucination/tree/main/examples/saas) | English | Monthly SaaS metrics: invented figures and a forecast are replaced by your sentences |
|
|
179
|
+
| [`examples/support/`](https://github.com/Jegoba90/anti-hallucination/tree/main/examples/support) | English | A summary of support tickets: each sentence may only state what the ticket it cites says |
|
|
180
|
+
| [`examples/sales/`](https://github.com/Jegoba90/anti-hallucination/tree/main/examples/sales) | Spanish | A quarterly sales report, with a verdict decided by thresholds |
|
|
181
|
+
| [`examples/sales_report.py`](https://github.com/Jegoba90/anti-hallucination/blob/main/examples/sales_report.py) | Spanish | The same report from Python, with both modes and the receipt |
|
|
182
|
+
|
|
183
|
+
Each folder has a `data.json`, a text written with figures typed in
|
|
184
|
+
(`written_by_an_ai.txt`) and a draft with placeholders (`draft.txt`).
|
|
185
|
+
|
|
186
|
+
## Tested with a real model
|
|
187
|
+
|
|
188
|
+
On 2026-11-16 `openai/gpt-oss-120b`, on Groq, wrote four drafts of the Spanish
|
|
189
|
+
sales report. It typed no figure. In the first draft one sentence carried no
|
|
190
|
+
data, «El desempeño general se mantiene dentro de los parámetros esperados», and
|
|
191
|
+
passed every check; the rule that every sentence must carry data came from it,
|
|
192
|
+
and the three drafts after it kept all their sentences. The drafts are kept in
|
|
193
|
+
[`tests/fixtures/real_model/`](https://github.com/Jegoba90/anti-hallucination/tree/main/tests/fixtures/real_model) and judged on every
|
|
194
|
+
test run. Claude has not run against the live API yet. The record is in
|
|
195
|
+
[`docs/pruebas-2026-11-16.md`](https://github.com/Jegoba90/anti-hallucination/blob/main/docs/pruebas-2026-11-16.md).
|
|
196
|
+
|
|
197
|
+
## Where it comes from
|
|
198
|
+
|
|
199
|
+
This is the method of the engine behind [CryptoCapi](https://cryptocapi.com),
|
|
200
|
+
where the model writes one line per news note and Python writes every market
|
|
201
|
+
figure. [anti-hallucination-crypto-agent](https://github.com/Jegoba90/anti-hallucination-crypto-agent)
|
|
202
|
+
shows that engine's output and seals in a terminal.
|
|
203
|
+
|
|
204
|
+
## Development
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
pip install -e ".[dev]"
|
|
208
|
+
pytest
|
|
209
|
+
mypy .
|
|
210
|
+
ruff check .
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
MIT license.
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
"""Numbers decide; the AI only writes.
|
|
2
|
+
|
|
3
|
+
Your code computes the facts and decides the verdicts. A writer (any LLM, or a
|
|
4
|
+
person) puts them into words. This package fills in every figure from your
|
|
5
|
+
facts, checks every sentence against your facts, labels and sources, publishes
|
|
6
|
+
only what passes and keeps a receipt of each decision.
|
|
7
|
+
|
|
8
|
+
from antihallucination import Fact, compose
|
|
9
|
+
|
|
10
|
+
facts = [Fact("ventas", 1250, unit="unidades", subject="ventas"),
|
|
11
|
+
Fact("variacion", -3.2, unit="%", change=True, subject="ventas")]
|
|
12
|
+
result = compose("Las ventas cayeron {variacion:abs} hasta {ventas}.", facts, locale="es")
|
|
13
|
+
result.text # 'Las ventas cayeron 3,2 % hasta 1.250 unidades.'
|
|
14
|
+
|
|
15
|
+
write() asks a model for the draft (antihallucination.writers has Claude and
|
|
16
|
+
OpenAI-compatible writers; any function (system, prompt) -> str works) and
|
|
17
|
+
sends it through compose(). The model is told the placeholders, never a value.
|
|
18
|
+
The command line is python -m antihallucination.
|
|
19
|
+
|
|
20
|
+
What it can show: every figure in the text came from your facts (compose) or
|
|
21
|
+
matches them (verify), and every name is in your evidence. What it cannot:
|
|
22
|
+
that your facts are right, or that no sentence claims more than the lists in
|
|
23
|
+
lexicon.py know how to catch.
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
__version__ = "0.2.0"
|
|
27
|
+
|
|
28
|
+
from .checks import Finding, Policy
|
|
29
|
+
from .errors import WriterError
|
|
30
|
+
from .core import Decision, ReplayCheck, ReplayStatus, Result, compose, replay, verify
|
|
31
|
+
from .facts import Fact, Label, Source, classify
|
|
32
|
+
from .receipt import RECIPE, Receipt, ReceiptCheck, ReceiptStatus, verify_receipt
|
|
33
|
+
from .writing import Written, write
|
|
34
|
+
|
|
35
|
+
__all__ = [
|
|
36
|
+
"RECIPE",
|
|
37
|
+
"__version__",
|
|
38
|
+
"Decision",
|
|
39
|
+
"Fact",
|
|
40
|
+
"Finding",
|
|
41
|
+
"Label",
|
|
42
|
+
"Policy",
|
|
43
|
+
"Receipt",
|
|
44
|
+
"ReceiptCheck",
|
|
45
|
+
"ReceiptStatus",
|
|
46
|
+
"ReplayCheck",
|
|
47
|
+
"ReplayStatus",
|
|
48
|
+
"Result",
|
|
49
|
+
"Source",
|
|
50
|
+
"Written",
|
|
51
|
+
"WriterError",
|
|
52
|
+
"classify",
|
|
53
|
+
"compose",
|
|
54
|
+
"replay",
|
|
55
|
+
"verify",
|
|
56
|
+
"verify_receipt",
|
|
57
|
+
"write",
|
|
58
|
+
]
|