Skip to main content

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.

Live Demo PyPI Python 3.9+


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 ms overhead):
    ✅ "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-click dashboard.bat on Windows)
  • Interactive Terminal Prover: python interactive.py (or interactive.bat on Windows)
  • Automated Benchmark & Merkle Proof Suite: python demo.py (or run.bat on 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.md for 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)

Source distribution for zerohallucination 2.2.0
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)

Table of built distributions (wheels) for zerohallucination 2.2.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

2.2.0 This release

2 release files No 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