Metadata-Version: 2.4
Name: zerohallucination
Version: 2.2.0
Summary: Enterprise Neuro-Symbolic Invariant Shield & SMT Verifier for Foundation Models
Home-page: https://github.com/mahmudulmd/ZeroHallucinationAI
Author: Md Mahmudul Hoque
Author-email: Md Mahmudul Hoque <mahmudulhoque934@gmail.com>
License: Proprietary / Dual Licensing - Copyright (c) 2026 Md Mahmudul Hoque
Project-URL: Homepage, https://github.com/mahmudulmd/ZeroHallucinationAI
Project-URL: Bug Tracker, https://github.com/mahmudulmd/ZeroHallucinationAI/issues
Keywords: hallucination,llm,neuro-symbolic,smt-solver,formal-verification,physics,merkle-proof
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.22.0
Requires-Dist: requests>=2.28.0
Requires-Dist: z3-solver>=4.12.0
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 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](https://img.shields.io/badge/Live%20Demo-Hugging%20Face%20Space-blue)](https://huggingface.co/spaces/mahmudulhq/zerohallucination)
[![PyPI](https://img.shields.io/badge/PyPI-zerohallucination-green)](https://pypi.org/project/zerohallucination/)
[![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-blue)](https://www.python.org/downloads/)

---

## 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](https://huggingface.co/spaces/mahmudulhq/zerohallucination)** — no local setup required.

---

## ⚡ 30-Second Quickstart (Cross-Platform)

### 1. Install
```bash
git clone https://github.com/mahmudulmd/ZeroHallucinationAI.git
cd ZeroHallucinationAI
pip install -r requirements.txt
```
Or install the package directly:
```bash
pip install zerohallucination
```

### 2. Start the Drop-In OpenAI/Grok Proxy Gateway
```bash
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
```python
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:
```json
{
  "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](https://github.com/mahmudulmd/ZeroHallucinationAI/issues) 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`](LICENSE.md) for full intellectual property and commercial licensing terms. For enterprise licensing or custom integrations, reach out via email.
