> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwedai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# QWED Tax: tax verification for AI agents
> QWED Tax verifies payroll and tax actions for AI agents before execution, with deterministic checks for IRS and CBDT rule compliance.
> "Death, Taxes, and Deterministic Verification."
**QWED-Tax** is the deterministic verification layer for Agentic Finance. It protects AI Agents from making costly tax errors by proofing inputs against **IRS (US)** and **CBDT (India)** rules before any transaction is executed.
## The problem
AI agents (LLMs) are handling payroll and tax, but they are largely illiterate in tax law. They hallucinate rates, misclassify workers, and ignore nexus thresholds.
### Real world failures
| Scenario | LLM Hallucination | QWED Verdict |
| :------------------- | :-------------------------------------------- | :---------------------------------------- |
| **Worker Hire** | "Hiring contractor (1099) who uses my laptop" | **BLOCKED** (Misclassification Risk) |
| **Sales Tax** | "No tax in NY for \$600k sales" | **BLOCKED** (Nexus Violation) |
| **Payroll** | "FICA Tax on $500k = $ 31,000" | **BLOCKED** (Limit is $176k / ~$ 10k tax) |
| **W-4 Exempt** | "Employee claims exempt with \$5k liability" | **BLOCKED** (IRS Pub 505 Violation) |
| **Transfer Pricing** | "Charge related party 50% below market" | **BLOCKED** (Arm's Length Deviation) |
## Guard coverage
QWED-Tax ships with **20+ deterministic guards** across three jurisdictions:
| Category | Guards | Jurisdiction |
| :------------------------ | :---------------------------------------------------------- | :------------ |
| **Payroll** | PayrollGuard, WithholdingGuard, ReciprocityGuard | US |
| **Worker classification** | ClassificationGuard (IRS Common Law + ABC Test) | US |
| **Sales tax** | NexusGuard | US |
| **1099 filing** | Form1099Guard | US |
| **Crypto/VDA** | CryptoTaxGuard | India |
| **Trading** | InvestmentGuard, SpeculationGuard, CapitalGainsGuard | India |
| **GST/AP** | GSTGuard, InputCreditGuard, TDSGuard | India |
| **Corporate** | RelatedPartyGuard, ValuationGuard | India |
| **Banking** | DepositRateGuard | India |
| **Set-off matrix** | InterHeadAdjustmentGuard | India |
| **Cross-border** | RemittanceGuard, DTAAGuard, TransferPricingGuard, PoEMGuard | International |
| **Address** | AddressGuard | US |
## Accounts payable automation
`qwed-tax` secures the entire "Procure-to-Pay" cycle for AI Agents:
* **Validation:** Checks GSTIN/VAT ID formats via `InputCreditGuard.verify_gstin_format()`.
* **Compliance:** Blocks Input Tax Credit (ITC) on "Personal" categories (Food, Cars, Gifts).
* **Withholding:** Auto-calculates TDS/Retention amounts before commercial payment via `TDSGuard`.
## 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.
## Architecture
QWED-Tax acts as the **Pre-Flight Middleware** between your AI Agent and Fintech APIs (like Gusto, Stripe, or Avalara).
```mermaid theme={null}
graph TD
A["AI Agent"] -->|"Intent"| B{"QWED-Tax Pre-Flight"}
subgraph "Deterministic Guards"
C["Personal Tax
(Payroll, 1099 vs W2)"]
D["Trading Tax
(F&O, Crypto, STCG)"]
E["Corporate Tax
(Sec 185 Loans, Valuations)"]
F["Cross-Border
(DTAA, PoEM, Transfer Pricing)"]
end
B --> C & D & E & F
C & D & E & F -->|"Audit Result"| B
B -- "Verified" --> G["Fintech API (Avalara/Gusto)"]
B -- "Blocked" --> H["Stop & Throw Error"]
style B fill:#00C853,stroke:#333,stroke-width:2px,color:white
style H fill:#ff4444,stroke:#333,stroke-width:2px,color:white
```
The system supports two entry points:
* **`TaxPreFlight`** — Intent-based auditor that routes each transaction to the guards required for its declared `action` and **fails closed** on missing, malformed, or unsupported intents.
* **`TaxVerifier`** — Jurisdiction-scoped verifier (`US` or `INDIA`) for direct guard access.
## Z3 theorem prover integration
Several guards use the **Z3 SMT solver** for formal verification instead of heuristic rules:
* **WithholdingGuard** — Proves W-4 exempt status validity against IRS Pub 505 rules.
* **ReciprocityGuard** — Proves correct state withholding under reciprocity agreements.
* **ClassificationGuard (ABC Test)** — Proves worker classification under CA AB5 / NJ / MA laws.
* **InvestmentGuard** — Proves correct tax head classification for stock market transactions.
This means QWED-Tax does not just check rules — it **formally proves** that the AI's tax logic is consistent.
## Zero-data leakage
Unlike cloud API checks (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.
## Data models
QWED-Tax uses strict Pydantic models with `Decimal` precision to prevent floating-point errors in financial calculations.
Represents a single payroll record for verification.
Employee identifier
Gross pay amount
List of tax withholdings
List of deductions
Net pay calculated by the AI/system
Currency code (USD, EUR, GBP)
Represents a payment to a contractor for 1099 filing checks.
Contractor identifier
NEC, RENT, ROYALTIES, ATTORNEY, or HEALTHCARE
Payment amount
Tax year
Input for the ABC Test classification guard.
Worker identifier
ABC Test criterion A
ABC Test criterion B
ABC Test criterion C
US state code
Input for W-4 withholding verification.
Employee identifier
Whether exempt status is claimed
Prior year tax liability
Whether a refund is expected this year
Input for `ReciprocityGuard` — describes where an employee lives and works.
Employee identifier
Employee's residence address
Employee's work address (or HQ if remote)
Whether the employee works remotely
A US address used by `AddressGuard` and `WorkArrangement`.
Street address
City name
US state enum
Five-digit ZIP code
Standard result returned by payroll verification guards.
Whether the check passed
Deterministically recalculated net pay
Difference between claimed and calculated
Human-readable verdict
Always SYMBOLIC (Z3-powered)
## Installation
```bash theme={null}
pip install qwed-tax
```