Skip to content

docs: reposition README as verification layer (refs #34, #31) #46

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Rahul Dass (rahuldass19) merged 2 commits into from
Jun 22, 2026
Merged

docs: reposition README as verification layer (refs #34, #31) #46

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8003339
docs: reposition README as verification layer (refs #34, #31)
rahuldass19 Jun 21, 2026
557b9ad
fix: address Sentry, CodeRabbit, Greptile review comments
rahuldass19 Jun 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
169 changes: 105 additions & 64 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,17 @@
<img src="assets/logo.svg" alt="QWED Logo" width="140" />

# 💸 QWED-Tax
**Deterministic Verification for Payroll, Tax, and Compliance**

> "Death, Taxes, and Deterministic Verification."
**The Verification Gate for AI-Generated Tax Decisions**

> Tax software answers: *"What is the correct calculation?"*
>
> QWED-Tax answers: *"Should this AI-generated tax decision be allowed to execute?"*

QWED-Tax sits between AI agents and execution systems (Gusto, Avalara, Stripe) —
verifying that tax decisions are legally sound before they execute.
Not a calculator. Not a filing platform. A deterministic verification layer
powered by Z3 and Decimal math.

[![Verified by QWED](https://img.shields.io/badge/Verified_by-QWED-00C853?style=flat&logo=checkmarx)](https://github.com/QWED-AI/qwed-tax)
[![100% Deterministic](https://img.shields.io/badge/100%25_Deterministic-QWED-0066CC?style=flat&logo=checkmarx)](https://docs.qwedai.com/docs/engines/overview#deterministic-first-philosophy)
Expand All @@ -18,8 +26,31 @@

---

## 🚨 The Problem: AI Hallucinations in Tax
AI agents are handling payroll and tax, but **LLMs are largely illiterate in tax law.**
## ⚔️ Why QWED-Tax?
Unlike calculators (Avalara) or executors (Gusto), QWED is a **Verifier**. We sit *between* the AI and the Execution.

| Solution | What They Do | The Risk | QWED's Role |
| :--- | :--- | :--- | :--- |
| **Avalara / Stripe** | **Calculate** tax based on inputs. | Garbage In, Garbage Out. If AI sends wrong input, tax is wrong. | **The Filter:** We verify inputs *before* API calls. |
| **Gusto / Check** | **Execute** payments and filings. | They execute erroneous commands (e.g., paying a W-2 as 1099). | **The Shield:** We block illegal payments *before* execution. |
| **Blue J / ChatGPT** | **Research** tax law. | Hallucination (85% accuracy). | **The Proof:** We verify the math & logic deterministically. |

## 🚨 The Problem: Unverified AI Tax Decisions

AI agents are making payroll and tax decisions that execute unchecked —
misclassifying workers, miscalculating withholding, and filing incorrect returns.

QWED-Tax is the verification gate:

```text
AI-generated tax decision
↓
Deterministic verification (Allow / Block / Unverifiable)
↓
Execution system (Gusto, Avalara, Stripe)
```

> *"Death, Taxes, and Deterministic Verification."*

## 🏗️ Architecture: The "Swiss Cheese" Defense

Expand All @@ -43,45 +74,12 @@ graph TD
style G fill:#ff4444,stroke:#333,stroke-width:2px,color:white
```

## 🔒 Zero-Data Leakage
Unlike cloud APIs check (Avalara/Vertex), `qwed-tax` runs **100% Locally**.
* **Privacy First:** Your payroll/trading data never leaves your server.
* **No API Latency:** Checks are instant (microseconds).
* **GDPR/DPDP Compliant:** Ideal for sensitive Fintech environments.

> 📖 **See [Determinism Guarantee](https://docs.qwedai.com/docs/engines/overview#deterministic-first-philosophy)** for how QWED ensures 100% reproducible verification.

## 🌐 TypeScript SDK (New!)
Run compliance checks proactively in the browser/frontend.

```bash
npm install @qwed-ai/tax
```

```typescript
import { TaxPreFlight } from '@qwed-ai/tax';

const result = TaxPreFlight.audit({
action: "hire",
worker_type: "1099",
worker_facts: { provides_tools: true, reimburses_expenses: true } // implies Employee
});

if (!result.allowed) {
alert(" Compliance Block: " + result.blocks.join(", "));
}
```

> 🔐 **Fail-Closed Contract:** `TaxPreFlight` is strict by design. Missing, ambiguous, or unsupported intent payloads are blocked (`allowed = false`) rather than treated as a successful verification.

### ⚔️ Why QWED-Tax?
Unlike calculators (Avalara) or executors (Gusto), QWED is a **Verifier**. We sit *between* the AI and the Execution.
## 🧠 Procedural Accuracy (MSLR Aligned)
Unlike standard calculators, `qwed-tax` verifies the **procedure**, not just the result. This aligns with **Multi-Step Legal Reasoning (MSLR)** to prevent "Right Answer, Wrong Logic" errors.

| Solution | What They Do | The Risk | QWED's Role |
| :--- | :--- | :--- | :--- |
| **Avalara / Stripe** | **Calculate** tax based on inputs. | Garbage In, Garbage Out. If AI sends wrong input, tax is wrong. | **The Filter:** We verify inputs *before* API calls. |
| **Gusto / Check** | **Execute** payments and filings. | They execute erroneous commands (e.g., paying a W-2 as 1099). | **The Shield:** We block illegal payments *before* execution. |
| **Blue J / ChatGPT** | **Research** tax law. | Hallucination (85% accuracy). | **The Proof:** We verify the math & logic deterministically. |
* **Step 1: Sanction Check** $\rightarrow$ Is this transaction legal? (e.g., `RelatedPartyGuard` blocks illegal loans *before* rate checks).
* **Step 2: Limit Check** $\rightarrow$ Is it within quota? (e.g., `RemittanceGuard` checks LRS limit *before* TCS).
* **Step 3: Calculation** $\rightarrow$ Apply math.

### 📊 Real World Failures We Blocked (From Audit Logs)
| Scenario | LLM Hallucinations | QWED Verdict |
Expand All @@ -91,24 +89,36 @@ Unlike calculators (Avalara) or executors (Gusto), QWED is a **Verifier**. We si
| **Crypto Tax** | "Deduct Bitcoin loss from Business Profit" | 🛑 **BLOCKED** (Sec 115BBH violation) |
| **Payroll** | "FICA Tax on $500k = $31,000" | 🛑 **BLOCKED** (Limit is $176k / ~$10k tax) |

## 🧠 Procedural Accuracy (MSLR Aligned)
Unlike standard calculators, `qwed-tax` verifies the **procedure**, not just the result. This aligns with **Multi-Step Legal Reasoning (MSLR)** to prevent "Right Answer, Wrong Logic" errors.

* **Step 1: Sanction Check** $\rightarrow$ Is this transaction legal? (e.g., `RelatedPartyGuard` blocks illegal loans *before* rate checks).
* **Step 2: Limit Check** $\rightarrow$ Is it within quota? (e.g., `RemittanceGuard` checks LRS limit *before* TCS).
* **Step 3: Calculation** $\rightarrow$ Apply math.

## 💡 What QWED Tax Verification System
## 💡 Verification Coverage
![QWED Security](https://img.shields.io/badge/QWED-Secured-blueviolet)

> **Enterprise-Grade Tax Code Verification Engine**
A deterministic verification layer for tax logic supported by `z3-solver` and `python-decimal`. It supports multiple jurisdictions.
> **Deterministic Tax Verification Layer for AI Agents**
A verification layer for tax decisions supported by `z3-solver` and `python-decimal`. It verifies claims across multiple jurisdictions — it does not calculate, file, or execute.

| Feature | US Jurisdiction (IRS) 🇺🇸 | India Jurisdiction (CBDT) 🇮🇳 |
| Feature | US (IRS) 🇺🇸 | India (CBDT / CBIC / FEMA) 🇮🇳 |
| :--- | :--- | :--- |
| **Engine** | `z3` (ABC Test), `decimal` | `z3` (Intraday Rules), `decimal` |
| **Key Guards** | Payroll, FICA Limit, W-2/1099 | Sec 115BBH (Crypto), GST (RCM) |
| **Status** | ✅ Production Ready | ✅ Production Ready |
| **Key Guards** | Payroll, FICA Limit, W-2/1099 | Crypto (Sec 115BBH), GST RCM (7 notified services), CGST/SGST/IGST split |
| **Status** | 🟢 Verification Layer | 🟢 Verification Layer |

> **Note:** Guards verify specific deterministic rules. Full tax compliance (GSTR filing, GSTN integration, HSN/SAC classification) is explicitly out of scope. See [What QWED-Tax Is Not](#-what-qwed-tax-is-not).

## 🚫 What QWED-Tax Is Not

QWED-Tax verifies decisions. It does not originate them, file them, or maintain the data pipelines that compliance platforms require.

Explicitly out of scope:

- **GSTN portal integration** / live GSTIN status lookup — QWED validates GSTIN format and checksum, not registration status
- **GSTR-1 / GSTR-2B / GSTR-3B reconciliation** — filing workflows belong in a compliance platform
- **e-Invoicing / IRN generation** — execution-side operations, not verification
- **HSN/SAC classification** — corpus maintenance is a data-curation problem, not a verification problem
- **Tax filing or return preparation** — QWED verifies claims; it does not originate filings
- **Regulatory change tracking as a service** — notifications, circulars, per-state rate updates
- **Payroll processing or execution** — QWED verifies payroll math; it does not run payroll
- **Tax calculation as a standalone engine** — QWED verifies a claimed result against statutory rules; it does not compute taxes for filing

If a feature requires live data sync, classification-corpus maintenance, or filing workflows, it belongs in a compliance platform — not in QWED-Tax.

## 🛡️ The Guards

Expand All @@ -118,7 +128,7 @@ A deterministic verification layer for tax logic supported by `z3-solver` and `p
3. **ReciprocityGuard**: Deterministically verifies state tax withholding (NY vs NJ rules).
4. **NexusGuard**: Verifies **Economic Nexus** thresholds ($100k/$500k sales) to catch missing tax liabilities.

### 🇮🇳 India (Income Tax / GST / FEMA)
### 🇮🇳 India (CBDT / CBIC / FEMA)
1. **CryptoTaxGuard**: Enforces **Section 115BBH** (No set-off of VDA losses).
2. **InvestmentGuard**: Distinguishes **Intraday (Speculative)** from **Delivery (Capital Gains)** using strict rules.
3. **GSTGuard**:
Expand All @@ -132,6 +142,14 @@ A deterministic verification layer for tax logic supported by `z3-solver` and `p
* **InputCreditGuard**: Blocks ITC on 'Blocked List' (Sec 17(5)) like Food/Motor Vehicles.
* **TDSGuard**: Enforces withholding tax (1% vs 10%) on Contractor/Professional payments.

## 🔒 Zero-Data Leakage
Unlike cloud APIs (Avalara/Vertex), `qwed-tax` runs **100% Locally**.
* **Privacy First:** Your payroll/trading data never leaves your server.
* **No API Latency:** Checks are instant (microseconds).
* **GDPR/DPDP Compliant:** Ideal for sensitive Fintech environments.

> 📖 **See [Determinism Guarantee](https://docs.qwedai.com/docs/engines/overview#deterministic-first-philosophy)** for how QWED ensures 100% reproducible verification.

## 📦 Installation
```bash
pip install qwed-tax
Expand All @@ -156,14 +174,37 @@ in_tax = TaxVerifier(jurisdiction="INDIA")
res = in_tax.verify_india_crypto(losses={"VDA": -5000}, gains={"BUSINESS": 50000})
print(res.message)
# -> "⚠️ Section 115BBH Alert: VDA loss cannot be set off."
```

## 🧾 Accounts Payable (AP) Automation
`qwed-tax` now secures the entire "Procure-to-Pay" cycle for AI Agents:
## 🧾 Accounts Payable Verification
`qwed-tax` verifies tax decisions in the Procure-to-Pay cycle for AI Agents:
* **Validation:** Checks GSTIN/VAT ID formats.
* **Compliance:** Blocks Input Tax Credit (ITC) on "Personal" categories (Food, Cars, Gifts).
* **Withholding:** Auto-calculates TDS/Retention amounts before commercial payment.
* **Verification:** Blocks Input Tax Credit (ITC) on "Personal" categories (Food, Cars, Gifts).
* **Withholding:** Verifies TDS/Retention amounts before commercial payment.

## 🌐 TypeScript SDK
Run verification checks proactively in the browser/frontend.

```bash
npm install @qwed-ai/tax
```

```typescript
import { TaxPreFlight } from '@qwed-ai/tax';

const result = TaxPreFlight.audit({
action: "hire",
worker_type: "1099",
worker_facts: { provides_tools: true, reimburses_expenses: true } // implies Employee
});

if (!result.allowed) {
alert(" Verification Block: " + result.blocks.join(", "));
}
Comment thread
greptile-apps[bot] marked this conversation as resolved.
```

> 🔐 **Fail-Closed Contract:** `TaxPreFlight` is strict by design. Missing, ambiguous, or unsupported intent payloads are blocked (`allowed = false`) rather than treated as a successful verification.

## ⚡ Usage (Frontend)
```python
from qwed_tax.verifier import TaxPreFlight
Expand Down Expand Up @@ -193,11 +234,11 @@ Check the `examples/` directory for runnable scripts:
- `examples/demo_advanced.py`: Complex Investment & Trading checks.

## 🗺️ Roadmap
We have a massive vision for Global Tax Verification.
Expanding verification guard coverage to more jurisdictions and tax rules.
Check out our **[Detailed Roadmap](ROADMAP.md)** for 2026 plans including:
- 🇬🇧 UK (HMRC) & 🇨🇦 Canada (CRA) Support
- Transfer Pricing & BEPS Guards
- ERP Integrations (SAP/Oracle)
- 🇬🇧 UK (HMRC) & 🇨🇦 Canada (CRA) Verification Guards
- Transfer Pricing & BEPS Verification Guards
- ERP Verification Connectors — verify tax decisions before they enter SAP/Oracle

## 📦 Related Packages

Expand Down
Loading