ZeroHallucinationAI: Neuro-Symbolic Verification Gateway for LLMs
Real-time formal verification, in-flight auto-correction, and SHA-256 Merkle proof auditing for LLM outputs — powered by Microsoft Z3 SMT solvers and first-principles physics invariants.
Why ZeroHallucinationAI? (Before vs. After)
LLMs predict likely tokens — they don't formally verify math, logic, or physical units. One wrong number in robotics, aerospace telemetry, or finance can break downstream systems.
Prompt: "How long can a 10 kWh battery power a 100 kW motor?"
- Without verification (typical LLM hallucination):
❌ "A 10 kWh battery powers a 100 kW motor for 5 hours." - Through ZeroHallucinationAI Gateway (
< 1.5 msoverhead):
✅ "The rover battery has a 10 kWh capacity and powers a 100 kW motor for 0.1 hours across the terrain."
(Caught via $E = P \cdot t$, auto-corrected in-flight, and sealed with a SHA-256 Merkle proof certificate.)
👉 Try the Live Web Demo on Hugging Face Spaces — no local setup required.
⚡ 30-Second Quickstart (Cross-Platform)
1. Install
git clone https://github.com/mahmudulmd/ZeroHallucinationAI.git
cd ZeroHallucinationAI
pip install -r requirements.txt
Or install the package directly:
pip install zerohallucination
2. Start the Drop-In OpenAI/Grok Proxy Gateway
python -m zerohallucination.gateway
# Or with uvicorn:
uvicorn zerohallucination.gateway:app --host 127.0.0.1 --port 8081
3. Point Any OpenAI SDK / LangChain / AutoGen Client to It
from openai import OpenAI
client = OpenAI(
base_url="http://127.0.0.1:8081/v1",
api_key="sk-zerohallucination"
)
response = client.chat.completions.create(
model="zerohallucination-grok-2",
messages=[{"role": "user", "content": "How long can a 10 kWh battery power a 100 kW motor?"}],
stream=False
)
print(response.choices[0].message.content)
# Output: "The rover battery has a 10 kWh capacity and powers a 100 kW motor for 0.1 hours across the terrain."
# Corrected mathematically in ~1.2 ms!
4. Other Execution Modes (CLI, Web Dashboard, Benchmarks)
- Web UI Truth Dashboard (
http://127.0.0.1:8080):python web_server.py(or double-clickdashboard.baton Windows) - Interactive Terminal Prover:
python interactive.py(orinteractive.baton Windows) - Automated Benchmark & Merkle Proof Suite:
python demo.py(orrun.baton Windows) - Gateway Verification Tests:
python test_gateway.py - Windows One-Click Gateway Launcher:
gateway.bat
🧠 Architecture
[ AI Client Application ]
│
OpenAI / Grok API Call │ (base_url: http://127.0.0.1:8081/v1)
▼
┌──────────────────────────────────────────────────┐
│ ZeroHallucination Proxy Gateway (v2.2) │
│ - Fast SSE Token Stream Interception │
│ - HTTP Header Invariant Telemetry │
└─────────────────────────┬────────────────────────┘
│
▼
┌──────────────────────────────────────────────────┐
│ Claim Decomposition Layer │
│ Extracts: Arithmetic, SMT, Logic, Physics │
└──────┬─────────────┬─────────────┬───────────────┘
│ │ │
┌────────────────┴┐ ┌──────┴──────┐ ┌┴────────────────┐
▼ ▼ ▼ ▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌───────────────────┐
│ AST Symbolic │ │ Microsoft Z3 │ │ DAG Partial │ │ First-Principles │
│ Arithmetic │ │ SMT Solver │ │ Order │ │ Physics & Units │
│ Prover │ │ (First-Order)│ │ Transitivity │ │ (Thermodynamics) │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └─────────┬─────────┘
│ │ │ │
└────────────────┼────────────────┼───────────────────┘
│
▼
┌────────────────────────────────────────────────┐
│ Cryptographic Merkle Tree Auditor │
│ - Computes SHA-256 Merkle Proof Root │
│ - Issues Tamper-Evident Certificate │
│ - Generates Sound Auto-Correction │
└────────────────────────┬───────────────────────┘
│
▼
[ Formally Verified Output ]
🔬 Core Capabilities
1. First-Principles Physics & Dimensional Invariants
- Conservation of Energy: $E = P \cdot t$ (Batteries, power draw, duration)
- Kinematic Invariants: $v = d / t$ (Trajectory speeds, rover travel, orbital times)
- Newtonian Dynamics: $F = m \cdot a$ (Rocket thrust, payload acceleration)
- Electrical Power: $P = V \cdot I$ (High-voltage power systems)
2. Algebraic & Logical Consistency (Microsoft Z3 SMT + DAG)
- Evaluates arithmetic expressions via AST symbolic verification.
- Checks first-order logic constraints and transitive ordering ($A > B, B > C \implies A > C$) to catch contradictions mid-stream.
3. Cryptographic Merkle Proof Certificates (Audit & Compliance)
Every assertion evaluated by the engine is hashed and structured into a binary Merkle tree for EU AI Act / SEC audit trails:
{
"certificate_id": "ZH-CERT-FFA961536883",
"merkle_root": "6b1bf6b89acf4ca3da3e962866e2fa812d7ade0b1244457cd08d010726d5a828",
"tamper_proof_seal": "347403e1229e958bf2b646f67974f3f97a256d6e9e688e20e26c96836e22af36",
"leaf_nodes": [
{"type": "INPUT_SPEC", "hash": "3cac53ed49d543c2..."},
{"type": "PROOF_LEMMA_0", "hash": "0cc002d621da07ca..."},
{"type": "CERTIFIED_OUTPUT", "hash": "00be8e04719117e4..."}
]
}
🏆 Benchmark & Verification Summary
- Average Verification Latency:
< 1.5 ms - Algebraic SMT Latency (Z3):
< 65 ms - Verified Invariant Leakage Rate:
0.00%across supported mathematical, physical, and transitive invariant checks - Compatibility: Drop-in OpenAI / Grok wire-compatible API with SSE streaming
💬 Feedback & Edge Cases Welcome
Testing an LLM prompt that slips past verification or triggers a tricky edge case?
Please open a GitHub Issue with the prompt and output — real-world edge cases directly help expand the invariant ruleset.
🛡️ Authorship, Contact & Licensing
- Creator & Author: Md Mahmudul Hoque
- Contact:
mahmudulhoque934@gmail.com - Origin: Panchagarh, Bangladesh
- Copyright & License: © 2026 Md Mahmudul Hoque. All Rights Reserved. See
LICENSE.mdfor full intellectual property and commercial licensing terms. For enterprise licensing or custom integrations, reach out via email.
Metadata
Release files for zerohallucination 2.2.0
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 |
|---|---|---|---|---|
| zerohallucination-2.2.0.tar.gz | 80.7 kB | Without provenance | Details for zerohallucination-2.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| zerohallucination-2.2.0-py3-none-any.whl | Python 3 | none | any | Details for zerohallucination-2.2.0-py3-none-any.whl |
Total release size: 169.9 kB
Release files / zerohallucination-2.2.0.tar.gz
| Download URL | zerohallucination-2.2.0.tar.gz |
|---|---|
| Size | 80.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
46f4b8e7c97d4f7712b76341b03b7f4d0fe66c9dac7cd1d535c0b8c44e24d4ad
|
|
BLAKE2b-256 checksum How to use checksums |
4d9ef88c2596647330dabc81427ef19f0b1be98ea29ac9d9016e53fab84674a3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Release files / zerohallucination-2.2.0-py3-none-any.whl
| Download URL | zerohallucination-2.2.0-py3-none-any.whl |
|---|---|
| Size | 89.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dbb66c83c92172d97ef4efe6fa74043cb5b769c299a914df32c336c0ad30b222
|
|
BLAKE2b-256 checksum How to use checksums |
c13d8608f70d00264d1de1eda167f752ef933e6bb11dd12adb5a0ddf13d77cce
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Security for zerohallucination 2.2.0
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.