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.
Files changed (43) hide show
  1. antihallucination-0.2.0/LICENSE +21 -0
  2. antihallucination-0.2.0/PKG-INFO +249 -0
  3. antihallucination-0.2.0/README.md +213 -0
  4. antihallucination-0.2.0/antihallucination/__init__.py +58 -0
  5. antihallucination-0.2.0/antihallucination/__main__.py +3 -0
  6. antihallucination-0.2.0/antihallucination/checks.py +509 -0
  7. antihallucination-0.2.0/antihallucination/cli.py +201 -0
  8. antihallucination-0.2.0/antihallucination/core.py +334 -0
  9. antihallucination-0.2.0/antihallucination/data.py +199 -0
  10. antihallucination-0.2.0/antihallucination/errors.py +5 -0
  11. antihallucination-0.2.0/antihallucination/facts.py +227 -0
  12. antihallucination-0.2.0/antihallucination/lexicon.py +113 -0
  13. antihallucination-0.2.0/antihallucination/mcp_server.py +266 -0
  14. antihallucination-0.2.0/antihallucination/numbers.py +312 -0
  15. antihallucination-0.2.0/antihallucination/prompt.py +176 -0
  16. antihallucination-0.2.0/antihallucination/py.typed +0 -0
  17. antihallucination-0.2.0/antihallucination/receipt.py +145 -0
  18. antihallucination-0.2.0/antihallucination/text.py +116 -0
  19. antihallucination-0.2.0/antihallucination/writers/__init__.py +12 -0
  20. antihallucination-0.2.0/antihallucination/writers/claude.py +90 -0
  21. antihallucination-0.2.0/antihallucination/writers/openai_compatible.py +128 -0
  22. antihallucination-0.2.0/antihallucination/writing.py +116 -0
  23. antihallucination-0.2.0/antihallucination.egg-info/PKG-INFO +249 -0
  24. antihallucination-0.2.0/antihallucination.egg-info/SOURCES.txt +41 -0
  25. antihallucination-0.2.0/antihallucination.egg-info/dependency_links.txt +1 -0
  26. antihallucination-0.2.0/antihallucination.egg-info/entry_points.txt +3 -0
  27. antihallucination-0.2.0/antihallucination.egg-info/requires.txt +15 -0
  28. antihallucination-0.2.0/antihallucination.egg-info/top_level.txt +1 -0
  29. antihallucination-0.2.0/pyproject.toml +59 -0
  30. antihallucination-0.2.0/setup.cfg +4 -0
  31. antihallucination-0.2.0/tests/test_cli.py +169 -0
  32. antihallucination-0.2.0/tests/test_compose.py +291 -0
  33. antihallucination-0.2.0/tests/test_examples.py +84 -0
  34. antihallucination-0.2.0/tests/test_mcp_server.py +132 -0
  35. antihallucination-0.2.0/tests/test_numbers.py +151 -0
  36. antihallucination-0.2.0/tests/test_prompt.py +128 -0
  37. antihallucination-0.2.0/tests/test_readme.py +85 -0
  38. antihallucination-0.2.0/tests/test_real_model.py +51 -0
  39. antihallucination-0.2.0/tests/test_receipt.py +130 -0
  40. antihallucination-0.2.0/tests/test_verify.py +191 -0
  41. antihallucination-0.2.0/tests/test_write.py +135 -0
  42. antihallucination-0.2.0/tests/test_writer_claude.py +120 -0
  43. 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
+ ]
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ raise SystemExit(main())