From 800333945af450fbf36a0a55d4e65b190b4f84b1 Mon Sep 17 00:00:00 2001 From: Rahul Date: Mon, 22 Jun 2026 02:59:52 +0530 Subject: [PATCH 1/2] docs: reposition README as verification layer (refs #34, #31) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace title/subtitle with verifier-first positioning - Move comparison table directly below opening (strongest identity proof) - Reframe problem statement around AI-agent-era gate - Move Procedural Accuracy section up (key differentiator) - Remove 'Production Ready' status claims → 'Verification Layer' - Add explicit Non-Goals section (GSTN, GSTR, e-Invoicing, HSN/SAC, filing, etc.) - Fix broken heading 'What QWED Tax Verification System' → 'Verification Coverage' - Replace 'Enterprise-Grade Tax Code Verification Engine' → 'Deterministic Tax Verification Layer for AI Agents' - Accounts Payable: 'Automation → Verification' language - Roadmap: 'ERP Integrations → ERP Verification Connectors', remove platform language - Reorder sections: identity → comparison → problem → architecture → procedural accuracy → coverage → non-goals → guards → privacy → install → SDK → examples → roadmap --- README.md | 169 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 105 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index 26bfd9a..a351715 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,17 @@ QWED Logo # 💸 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) @@ -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: + +``` +AI-generated tax decision + ↓ +Deterministic verification (Allow / Block / Unverifiable) + ↓ +Execution system (Gusto, Avalara, Stripe) +``` + +> *"Death, Taxes, and Deterministic Verification."* ## 🏗️ Architecture: The "Swiss Cheese" Defense @@ -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 | @@ -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 @@ -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**: @@ -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 @@ -157,13 +175,36 @@ 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(" 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. + ## ⚡ Usage (Frontend) ```python from qwed_tax.verifier import TaxPreFlight @@ -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 From 557b9ada18e8ea5803caead2f53c315350aa645d Mon Sep 17 00:00:00 2001 From: Rahul Date: Mon, 22 Jun 2026 15:36:14 +0530 Subject: [PATCH 2/2] fix: address Sentry, CodeRabbit, Greptile review comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Move closing code fence before Accounts Payable heading (Sentry) - Fix heading level ### → ## for Why QWED-Tax? (CodeRabbit, Greptile P2) - Add text language specifier to ASCII diagram code block (CodeRabbit) - Replace 'Compliance Block' → 'Verification Block' in TS example (Greptile P2) --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index a351715..1a021e3 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ powered by Z3 and Decimal math. --- -### ⚔️ Why QWED-Tax? +## ⚔️ 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 | @@ -42,7 +42,7 @@ misclassifying workers, miscalculating withholding, and filing incorrect returns QWED-Tax is the verification gate: -``` +```text AI-generated tax decision ↓ Deterministic verification (Allow / Block / Unverifiable) @@ -174,13 +174,13 @@ 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 Verification `qwed-tax` verifies tax decisions in the Procure-to-Pay cycle for AI Agents: * **Validation:** Checks GSTIN/VAT ID formats. * **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. @@ -199,7 +199,7 @@ const result = TaxPreFlight.audit({ }); if (!result.allowed) { - alert(" Compliance Block: " + result.blocks.join(", ")); + alert(" Verification Block: " + result.blocks.join(", ")); } ```