> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwedai.tech/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), ABCClassificationGuard (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 structure **and the 15th-digit checksum** 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<br/>(Payroll, 1099 vs W2)"]
    D["Trading Tax<br/>(F&O, Crypto, STCG)"]
    E["Corporate Tax<br/>(Sec 185 Loans, Valuations)"]
    F["Cross-Border<br/>(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.
* **ABCClassificationGuard** — Proves worker classification under CA AB5 / NJ / MA laws.
* **InvestmentGuard** — Proves correct tax head classification for stock market transactions.

`ReciprocityGuard` is a deterministic lookup against a fixed reciprocity-pair table — it does not use Z3. See the [ReciprocityGuard reference](https://docs.qwedai.tech/tax/guards.md#reciprocityguard-state-tax) for the current contract.

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.

**Core models**

**PayrollEntry** `BaseModel`

Represents a single payroll record for verification.

**properties**

**employee\_id** `str` *required*

Employee identifier

**gross\_pay** `Decimal` *required*

Gross pay amount

**taxes** `List[TaxEntry]` *required*

List of tax withholdings

**deductions** `List[DeductionEntry]` *required*

List of deductions

**net\_pay\_claimed** `Decimal` *required*

Net pay calculated by the AI/system

**currency** `Currency` (default: USD)

Currency code (USD, EUR, GBP)

**ContractorPayment** `BaseModel`

Represents a payment to a contractor for 1099 filing checks.

**properties**

**contractor\_id** `str` *required*

Contractor identifier

**payment\_type** `PaymentType` *required*

NEC, RENT, ROYALTIES, ATTORNEY, or HEALTHCARE

**amount** `Decimal` *required*

Payment amount

**calendar\_year** `int` *required*

Tax year

**WorkerClassificationParams** `BaseModel`

Input for the ABC Test classification guard.

**properties**

**worker\_id** `str` *required*

Worker identifier

**freedom\_from\_control** `bool` *required*

ABC Test criterion A

**work\_outside\_usual\_business** `bool` *required*

ABC Test criterion B

**customarily\_engaged\_independently** `bool` *required*

ABC Test criterion C

**state** `State` *required*

US state code

**W4Form** `BaseModel`

Input for W-4 withholding verification.

**properties**

**employee\_id** `str` *required*

Employee identifier

**claim\_exempt** `bool` *required*

Whether exempt status is claimed

**tax\_liability\_last\_year** `float` *required*

Prior year tax liability

**expect\_refund\_this\_year** `bool` *required*

Whether a refund is expected this year

**WorkArrangement** `BaseModel`

Input for `ReciprocityGuard` — describes where an employee lives and works.

**properties**

**employee\_id** `str` *required*

Employee identifier

**residence\_address** `Address` *required*

Employee's residence address

**work\_address** `Address` *required*

Employee's work address (or HQ if remote)

**is\_remote** `bool` (default: false)

Whether the employee works remotely

**Address** `BaseModel`

A US address used by `AddressGuard` and `WorkArrangement`.

**properties**

**street** `str` *required*

Street address

**city** `str` *required*

City name

**state** `State` *required*

US state enum

**zip\_code** `str` *required*

Five-digit ZIP code

**VerificationResult** `BaseModel`

Standard result returned by payroll verification guards.

**properties**

**verified** `bool` *required*

Whether the check passed

**recalculated\_net\_pay** `Decimal` *required*

Deterministically recalculated net pay

**discrepancy** `Decimal` *required*

Difference between claimed and calculated

**message** `str` *required*

Human-readable verdict

**verification\_mode** `str` (default: SYMBOLIC)

Always SYMBOLIC (Z3-powered)

## Installation

```bash theme={null}
pip install qwed-tax
```


## Related topics

- [QWED Tax guards for AI payroll and tax verification](https://docs.qwedai.tech/tax/guards.md)
- [QWED: deterministic verification for LLMs and AI agents](https://docs.qwedai.tech/intro.md)
- [QWED Tax integration for AI payroll and tax workflows](https://docs.qwedai.tech/tax/integration.md)
- [QWED UCP: transaction verification for AI commerce](https://docs.qwedai.tech/ucp/overview.md)
- [QWED UCP guards for AI commerce verification](https://docs.qwedai.tech/ucp/guards.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.