Metadata-Version: 2.4
Name: qwed
Version: 2.2.0
Summary: The Deterministic Verification Protocol for AI - 8 verification engines for math, logic, code, SQL, facts, images, and more.
Project-URL: Homepage, https://qwedai.com
Project-URL: Documentation, https://docs.qwedai.com
Project-URL: Repository, https://github.com/QWED-AI/qwed-verification
Project-URL: Changelog, https://github.com/QWED-AI/qwed-verification/blob/main/CHANGELOG.md
Author-email: QWED Team <rahul@qwedai.com>
License: Apache-2.0
License-File: LICENSE
Keywords: ai,code-security,deterministic,fact-checking,llm,logic,math,sql-validation,symbolic,verification
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.1.0
Requires-Dist: bcrypt>=4.0.1
Requires-Dist: click>=8.1.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: networkx>=3.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: passlib[bcrypt]>=1.7.4
Requires-Dist: pydantic[email]>=2.0.0
Requires-Dist: pyjwt>=2.8.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: requests>=2.31.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: sqlglot>=20.0.0
Requires-Dist: sqlmodel>=0.0.14
Requires-Dist: sympy>=1.12
Requires-Dist: uvicorn>=0.20.0
Requires-Dist: z3-solver>=4.12.0
Provides-Extra: dev
Requires-Dist: docker>=7.0.0; extra == 'dev'
Requires-Dist: freezegun>=1.4.0; extra == 'dev'
Requires-Dist: matplotlib>=3.7.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3.1; extra == 'dev'
Requires-Dist: pytest-xdist>=3.3.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0.1; extra == 'dev'
Provides-Extra: server
Requires-Dist: opentelemetry-api>=1.20.0; extra == 'server'
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == 'server'
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.41b0; extra == 'server'
Requires-Dist: opentelemetry-instrumentation-requests>=0.41b0; extra == 'server'
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'server'
Requires-Dist: prometheus-client>=0.19.0; extra == 'server'
Requires-Dist: psycopg2-binary>=2.9.9; extra == 'server'
Requires-Dist: redis>=5.0.0; extra == 'server'
Provides-Extra: symbolic
Requires-Dist: crosshair-tool>=0.0.100; extra == 'symbolic'
Description-Content-Type: text/markdown

<div align="center">
  <img src="assets/logo.svg" alt="QWED Logo - AI Verification Engine" width="80" height="80">
  <h1>QWED Protocol</h1>
  <h3>Model Agnostic Verification Layer for AI</h3>
  
  > **QWED Verification** - Production-grade deterministic verification layer for Large Language Models. Works with **ANY LLM** - OpenAI, Anthropic, Gemini, Llama (via Ollama), or any local model. Detect and prevent AI hallucinations through 8 specialized verification engines. **Your LLM, Your Choice, Our Verification.**
  
  <p>
    <b>Don't fix the liar. Verify the lie.</b><br>
    <i>QWED does not reduce hallucinations. It makes them irrelevant.</i>
  </p>

  <p>
    <b>If an AI output cannot be proven, QWED will not allow it into production.</b>
  </p>

  <p>
    <b>🌐 Model Agnostic:</b> Local ($0) • Budget ($5/mo) • Premium ($100/mo) - You choose!
  </p>

  [![CI](https://github.com/QWED-AI/qwed-verification/actions/workflows/ci.yml/badge.svg)](https://github.com/QWED-AI/qwed-verification/actions/workflows/ci.yml)
  [![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)
  [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
  [![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](Dockerfile)
  [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18110785.svg)](https://doi.org/10.5281/zenodo.18110785)
  [![status](https://joss.theoj.org/papers/385abbd3a6733fc907f1780eb5b6c927/status.svg)](https://joss.theoj.org/papers/385abbd3a6733fc907f1780eb5b6c927)
  [![PyPI version](https://img.shields.io/pypi/v/qwed.svg)](https://pypi.org/project/qwed/)
  [![Contributors](https://img.shields.io/github/contributors/QWED-AI/qwed-verification)](https://github.com/QWED-AI/qwed-verification/graphs/contributors)
  
  [![GitHub stars](https://img.shields.io/github/stars/QWED-AI/qwed-verification?style=social)](https://github.com/QWED-AI/qwed-verification)
  [![GitHub forks](https://img.shields.io/github/forks/QWED-AI/qwed-verification?style=social)](https://github.com/QWED-AI/qwed-verification/fork)
  [![GitHub watchers](https://img.shields.io/github/watchers/QWED-AI/qwed-verification?style=social)](https://github.com/QWED-AI/qwed-verification)

  <br>

  **💖 Support QWED Development:**
  
  <a href="https://github.com/sponsors/rahuldass19"><img src="https://img.shields.io/github/sponsors/rahuldass19?style=for-the-badge&logo=githubsponsors&label=Sponsor&color=EA4AAA" alt="Sponsor on GitHub"></a>

  <br>
  
  [![Twitter](https://img.shields.io/badge/Twitter-@rahuldass29-1DA1F2?style=flat&logo=twitter&logoColor=white)](https://x.com/rahuldass29)
  [![LinkedIn](https://img.shields.io/badge/LinkedIn-Rahul%20Dass-0077B5?style=flat&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/rahul-dass-23b370b0/)
  [![Blog](https://img.shields.io/badge/Blog-Unreadable%20Code%20Benchmark-FF5722?style=flat&logo=docusaurus&logoColor=white)](https://docs.qwedai.com/blog/unreadable-code-agi-benchmark)

  <br>
  <a href="#-quick-start-install--verify-in-30-seconds">Quick Start</a> · 
  <a href="#-new-in-v210-client-side-verification">🆕 QWEDLocal</a> ·
  <a href="#-the-llm-hallucination-problem-why-ai-cant-be-trusted">The Problem</a> · 
  <a href="#-the-8-verification-engines-how-qwed-validates-llm-outputs">The 8 Engines</a> ·
  <a href="docs/INTEGRATION.md">🔌 Integration</a> ·
  <a href="docs/QWED_LOCAL.md">⚡ QWEDLocal</a> ·
  <a href="docs/CLI.md">🖥️ CLI</a> ·
  <a href="docs/OLLAMA_INTEGRATION.md">🆓 Ollama (FREE!)</a> ·
  <a href="https://docs.qwedai.com">📖 Full Documentation</a>
</div>

---

> **⚠️ What QWED Is (and Isn't)**
> 
> **QWED is:** An open-source engineering tool that combines existing verification libraries (SymPy, Z3, SQLGlot, AST) into a unified API for LLM output validation.
> 
> **QWED is NOT:** Novel research. We don't claim algorithmic innovation. We claim practical integration for production use cases.
> 
> **Works when:** Developer provides ground truth (expected values, schemas, contracts) and LLM generates structured output.
> 
> **Doesn't work when:** Specs come from natural language, outputs are freeform text, or verification domain is unsupported.

---

## 🚀 Quick Start: Install & Verify in 30 Seconds

```bash
# Install from PyPI (Recommended)
pip install qwed

# Or install from source
git clone https://github.com/QWED-AI/qwed-verification.git
cd qwed-verification
pip install -e .
```

```python
from qwed_sdk import QWEDClient

client = QWEDClient(api_key="your_key")

# The LLM says: "Derivative of x^2 is 3x" (Hallucination!)
response = client.verify_math(
    query="What is the derivative of x^2?",
    llm_output="3x" 
)

print(response)
# -> ❌ CORRECTED: The derivative is 2x. (Verified by SymPy)
```

### 🆕 **NEW:** Client-Side Verification (v2.1.0)

No backend server? No problem! Use **QWEDLocal**:

```python
from qwed_sdk import QWEDLocal

# FREE with Ollama (local LLMs)
client = QWEDLocal(
    base_url="http://localhost:11434/v1",
    model="llama3"
)

# Or use OpenAI
client = QWEDLocal(
    provider="openai",
    api_key="sk-...",
    model="gpt-4o-mini"
)

result = client.verify_math("What is 2+2?")
print(result.verified)  # True
print(result.value)  # 4
```

**Features:**
- ✅ Works with **ANY LLM** (Ollama, OpenAI, Anthropic, Gemini)
- ✅ **$0 cost** with local models
- ✅ **Smart caching** (50-80% cost savings)
- ✅ **100% private** (data never leaves your machine)

### 🔒 **NEW in v2.2.0:** PII Masking (Enterprise Privacy)

Automatically mask sensitive data before sending to LLMs:

```python
from qwed_sdk import QWEDLocal

# Enable PII masking (requires pip install 'qwed[pii]')
client = QWEDLocal(
    provider="openai",
    api_key="sk-...",
    mask_pii=True  # 🔒 Privacy protection
)

result = client.verify("My email is john@example.com")
# LLM sees: "My email is <EMAIL_ADDRESS>"

# Check what was masked
print(result.evidence['pii_masked'])
# {'pii_detected': 1, 'types': ['EMAIL_ADDRESS']}
```

**Compliance:**
- 🏥 **HIPAA** (Healthcare)
- 🏦 **PCI-DSS** (Finance)
- 🇪🇺 **GDPR** (EU Privacy)

**CLI:**
```bash
qwed verify "Email: user@example.com" --mask-pii
qwed pii "My SSN is 123-45-6789"  # Test detection
```

📖 **[PII Masking Guide →](docs/PII_MASKING.md)** | **[QWEDLocal Guide →](docs/QWED_LOCAL.md)** | **[CLI Reference →](docs/CLI.md)**

---

## 🚨 The LLM Hallucination Problem: Why AI Can't Be Trusted

Everyone is trying to fix AI hallucinations by **Fine-Tuning** (teaching it more data).

This is like forcing a student to memorize 1,000,000 math problems.

**What happens when they see the 1,000,001st problem? They guess.**

---

## 📊 The Proof: Why Enterprise AI Needs QWED Verification

We benchmarked **Claude Opus 4.5** (one of the world's best LLMs) on 215 critical tasks.

![QWED Benchmark Results - LLM Accuracy Testing](assets/benchmark_chart.png)

| Finding | Implication |
|---------|-------------|
| **Finance:** 73% accuracy | Banks can't use raw LLM for calculations |
| **Adversarial:** 85% accuracy | LLMs fall for authority bias tricks |
| **QWED:** 100% error detection | All 22 errors caught before production |

> **QWED doesn't compete with LLMs. We ENABLE them for production use.**

📄 [Full Benchmark Report →](BENCHMARKS.md)

---

## 🎯 Use Cases & Applications

QWED is designed for industries where AI errors have real consequences:

| Industry | Use Case | Risk Without QWED |
|----------|----------|-------------------|
| 🏦 **Financial Services** | Transaction validation, fraud detection | $12,889 error per miscalculation |
| 🏥 **Healthcare AI** | Drug interaction checking, diagnosis verification | Patient safety risks |
| ⚖️ **Legal Tech** | Contract analysis, compliance checking | Regulatory violations |
| 📚 **Educational AI** | AI tutoring, assessment systems | Misinformation to students |
| 🏭 **Manufacturing** | Process control, quality assurance | Production defects |

---

## ✅ The Solution: Verification Layer

**QWED** is the first open-source **Neurosymbolic AI Verification Layer**.

We combine:
- **Neural Networks** (LLMs) for natural language understanding
- **Symbolic Reasoning** (SymPy, Z3, AST) for deterministic verification

### The Core Philosophy: "The Untrusted Translator"

QWED operates on a strict principle: **Don't trust the LLM to compute or judge; trust it only to translate.**

**Example Flow:**
```
User Query: "If all A are B, and x is A, is x B?"

↓ (LLM translates)

Z3 DSL: Implies(A(x), B(x))

↓ (Z3 proves)

Result: TRUE (Proven by formal logic)
```

The LLM is an **Untrusted Translator**. The Symbolic Engine is the **Trusted Verifier**.

---

## 💡 How QWED Compares

### The "Judge" Problem

Most AI safety tools use **"LLM-as-a-Judge"** (asking GPT-4 to grade GPT-3.5). This is fundamentally unsafe:

- **Recursive Hallucination:** If the judge has the same bias as the generator, errors go undetected
- **Probabilistic Evaluation:** LLMs give probability, not proof
- **Subjectivity:** Different judges = different answers

**QWED introduces "Solver-as-a-Judge"**: Replace neural network opinions with compiler execution and mathematical proof.

### Comparison Table

| Feature | **QWED Protocol** | NeMo Guardrails | LangChain Evaluators |
|---------|-------------------|-----------------|----------------------|
| **The "Judge"** | Deterministic Solver (Z3/SymPy) | Semantic Matcher | Another LLM (GPT-4) |
| **Mechanism** | Translation to DSL | Vector Similarity | Prompt Engineering |
| **Verification Type** | Mathematical Proof | Policy Adherence | Consensus/Opinion |
| **Primary Goal** | Correctness (Truth) | Safety (Appropriateness) | Quality Score |
| **False Positives** | Near Zero (Logic-based) | Medium (Semantic drift) | High (Subjectivity) |
| **Works Offline** | ✅ Yes (QWEDLocal) | ❌ No | ❌ No |
| **Privacy** | ✅ 100% Local | ❌ Cloud-based | ❌ Cloud-based |

**QWED's Advantage:** When you need **proof**, not opinion.

---

## 🔬 The Verification Engines

QWED routes queries to specialized engines that act as DSL interpreters:


```
┌──────────────┐
│  User Query  │
└──────┬───────┘
       │
       ▼
┌──────────────────┐
│ LLM (The Guesser)│
│ GPT-4 / Claude   │
└──────┬───────────┘
       │ Unverified Output
       ▼
┌────────────────────┐
│  QWED Protocol     │
│  (Verification)    │
└──────┬─────────────┘
       │
   ┌───┴────┐
   ▼        ▼
❌ Reject  ✅ Verified
            │
            ▼
   ┌────────────────┐
   │ Your Application│
   └────────────────┘
```

---

## QWED 🆚 Traditional AI Safety Approaches

| Approach | Accuracy | Deterministic | Explainable | Best For |
|----------|----------|---------------|-------------|----------|
| **QWED Verification** | ✅ 99%+ | ✅ Yes | ✅ Full trace | Production AI |
| Fine-tuning / RLHF | ⚠️ ~85% | ❌ No | ❌ Black box | General improvement |
| RAG (Retrieval) | ⚠️ ~80% | ❌ No | ⚠️ Limited | Knowledge grounding |
| Prompt Engineering | ⚠️ ~70% | ❌ No | ⚠️ Limited | Quick fixes |
| Guardrails | ⚠️ Variable | ❌ No | ⚠️ Reactive | Content filtering |

> **QWED doesn't replace these - it complements them with mathematical certainty.**

---

## 🔧 The 8 Verification Engines: How QWED Validates LLM Outputs

We don't use another LLM to check your LLM. **That's circular logic.**

We use **Hard Engineering**:

| Engine | Tech Stack | What it Solves |
|--------|------------|----------------|
| **🧮 Math Verifier** | `SymPy` + `NumPy` | Calculus, Linear Algebra, Finance. No more `$1 + $1 = $3`. |
| **⚖️ Logic Verifier** | `Z3 Prover` | Formal Verification. Checks for logical contradictions. |
| **🛡️ Code Security** | `AST` + `Semgrep` | Catches `eval()`, secrets, vulnerabilities before code runs. |
| **📊 Stats Engine** | `Pandas` + `Wasm` | Sandboxed execution for trusted data analysis. |
| **🗄️ SQL Validator** | `SQLGlot` | Prevents Injection & validates schema. |
| **🔍 Fact Checker** | `TF-IDF` + `NLI` | Checks grounding against source docs. |
| **👁️ Image Verifier** | `OpenCV` + `Metadata` | Verifies image dimensions, format, pixel data. |
| **🤝 Consensus Engine** | `Multi-Provider` | Cross-checks GPT-4 vs Claude vs Gemini. |

---

## 🧠 The QWED Philosophy: Verification Over Correction

| ❌ Wrong Approach | ✅ QWED Approach |
|-------------------|------------------|
| "Let's fine-tune the model to be more accurate" | "Let's verify the output with math" |
| "Trust the AI's confidence score" | "Trust the symbolic proof" |
| "Add more training data" | "Add a verification layer" |
| "Hope it doesn't hallucinate" | "Catch hallucinations deterministically" |

**QWED = Query with Evidence and Determinism**

> **Probabilistic systems should not be trusted with deterministic tasks.**
> **If it can't be verified, it doesn't ship.**

---

## 🔌 LLM Framework Integrations

Already using an Agent framework? QWED drops right in.

### 🦜 LangChain

```python
from qwed_sdk.langchain import QWEDTool

tools = [QWEDTool(verification_type="math"), QWEDTool(verification_type="sql")]
```

### 🤖 CrewAI

```python
from qwed_sdk.crewai import QWEDVerifiedAgent

agent = QWEDVerifiedAgent(role="Analyst", allow_dangerous_code=False)
```

---

## 🌍 Multi-Language SDK Support

| Language | Package | Status |
|----------|---------|--------|
| 🐍 Python | `qwed` | ✅ Available on PyPI |
| 🟦 TypeScript | `@qwed-ai/sdk` | ✅ Available on npm |
| 🐹 Go | `qwed-go` | 🟡 Coming Soon |
| 🦀 Rust | `qwed` | 🟡 Coming Soon |

git clone https://github.com/QWED-AI/qwed-verification.git
cd qwed-verification
pip install -r requirements.txt
```

---

## 🎯 Real Example: The $12,889 Bug

**User asks AI:** "Calculate compound interest: $100K at 5% for 10 years"

**GPT-4 responds:** "$150,000"  
*(Used simple interest by mistake)*

**With QWED:**
```python
response = client.verify_math(
    query="Compound interest: $100K, 5%, 10 years",
    llm_output="$150,000"
)
# -> ❌ INCORRECT: Expected $162,889.46
#    Error: Used simple interest formula instead of compound
```

**Cost of not verifying:** $12,889 error per transaction 💸

---

## ❓ Frequently Asked Questions

### Q: How does QWED differ from RAG (Retrieval Augmented Generation)?
**A:** RAG improves the *input* to the LLM by grounding it in documents. QWED verifies the *output* deterministically. RAG adds knowledge; QWED adds certainty.

### Q: Can QWED work with any LLM?
**A:** Yes! QWED is model-agnostic and works with GPT-4, Claude, Gemini, Llama, Mistral, and any other LLM. We verify outputs, not models.

### Q: Does QWED replace fine-tuning?
**A:** No. Fine-tuning makes models better at tasks. QWED verifies they got it right. Use both.

### Q: Is QWED open source?
**A:** Yes! Apache 2.0 license. Enterprise features (audit logs, multi-tenancy) are in a separate repo.

### Q: What's the latency overhead?
**A:** Typically <100ms for most verifications. Math and logic proofs are instant. Consensus checks take longer (multiple API calls).

---

## 📚 Documentation & Resources

| Resource | Description |
|----------|-------------|
| [📖 Full Documentation](https://docs.qwedai.com) | Complete API reference and guides |
| [🔧 API Reference](https://docs.qwedai.com/docs/api/overview) | Endpoints and schemas |
| [📊 Benchmarks](https://docs.qwedai.com/blog/unreadable-code-agi-benchmark) | LLM accuracy testing results |
| [🤝 Contributing Guide](./CONTRIBUTING.md) | How to contribute to QWED |
| [🏗️ Architecture](./docs/ARCHITECTURE.md) | System design and engine internals |
| [🔒 Security Policy](./SECURITY.md) | Reporting vulnerabilities |

---

## 🏢 Enterprise Features

Need **observability**, **multi-tenancy**, **audit logs**, or **compliance exports**?

📧 Contact: **rahul@qwedai.com**

---

## 📄 License

Apache 2.0 - See [LICENSE](LICENSE)

---

## ⭐ Star History

[![Star History Chart](https://api.star-history.com/svg?repos=QWED-AI/qwed-verification&type=Date)](https://star-history.com/#QWED-AI/qwed-verification&Date)

<details>
<summary>If chart doesn't load, click here for alternatives</summary>

**Current Stars:** [![GitHub stars](https://img.shields.io/github/stars/QWED-AI/qwed-verification?style=social)](https://github.com/QWED-AI/qwed-verification/stargazers)

**View trend:** [Star History Page](https://star-history.com/#QWED-AI/qwed-verification&Date)

</details>

---

## 👥 Contributors

<a href="https://github.com/QWED-AI/qwed-verification/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=QWED-AI/qwed-verification" alt="QWED Contributors" />
</a>

---

## 📄 Citation

If you use QWED in your research or project, please cite our archived paper:

```bibtex
@software{dass2025qwed,
  author = {Dass, Rahul},
  title = {QWED Protocol: Deterministic Verification for Large Language Models},
  year = {2025},
  publisher = {Zenodo},
  version = {v1.0.0},
  doi = {10.5281/zenodo.18110785},
  url = {https://doi.org/10.5281/zenodo.18110785}
}
```

**Plain text:**
> Dass, R. (2025). QWED Protocol: Deterministic Verification for Large Language Models (Version v1.1.0). Zenodo. https://doi.org/10.5281/zenodo.18110785

---

## ✅ Using QWED in Your Project?

Add this badge to your README to show you're using verified AI:

```markdown
[![Verified by QWED](https://img.shields.io/badge/Verified_by-QWED-00C853?style=flat&logo=checkmarx)](https://github.com/QWED-AI/qwed-verification)
```

**Preview:**  
[![Verified by QWED](https://img.shields.io/badge/Verified_by-QWED-00C853?style=flat&logo=checkmarx)](https://github.com/QWED-AI/qwed-verification)

This badge tells users that your LLM outputs are deterministically verified, not just "hallucination-prone guesses."

---

<div align="center">
  
  ### ⭐ Star us if you believe AI needs verification
  
  <a href="https://github.com/QWED-AI/qwed-verification">
    <img src="https://img.shields.io/github/stars/QWED-AI/qwed-verification?style=social" alt="GitHub Stars">
  </a>
  
  <br><br>
  
  <h3>Ready to trust your AI?</h3>
  <p><i>"Safe AI is the only AI that scales."</i></p>
  <br>
  <a href="CONTRIBUTING.md">Contribute</a> · 
  <a href="docs/ARCHITECTURE.md">Architecture</a> · 
  <a href="SECURITY.md">Security</a> · 
  <a href="https://docs.qwedai.com">Documentation</a>
</div>
