Skip to main content

Examples & Use Cases

Real-world examples of using QWED-UCP for commerce verification.

Example 1: E-commerce Checkout

Scenario

An AI shopping assistant helps a user buy flowers online. The AI calculates discounts and taxes.

The Checkout Data

checkout = {
    "currency": "USD",
    "status": "ready_for_complete",
    "line_items": [
        {
            "id": "red-roses-dozen",
            "quantity": 2,
            "item": {
                "name": "Red Roses (Dozen)",
                "price": 49.99
            }
        },
        {
            "id": "crystal-vase",
            "quantity": 1,
            "item": {
                "name": "Crystal Vase",
                "price": 29.99
            }
        }
    ],
    "totals": [
        {"type": "subtotal", "amount": 129.97},  # 2×49.99 + 29.99
        {"type": "discount", "amount": 12.99},   # 10% off
        {"type": "tax", "amount": 9.62},         # 8.25% tax
        {"type": "shipping", "amount": 5.99},
        {"type": "total", "amount": 132.59}
    ]
}

Verification

from qwed_ucp import UCPVerifier

verifier = UCPVerifier()
result = verifier.verify_checkout(checkout)

# Verification breakdown:
# ✅ Line Items: 2×49.99 + 1×29.99 = 129.97
# ✅ Discount: 10% of 129.97 = 12.997 ≈ 12.99
# ✅ Tax: 8.25% of (129.97 - 12.99) = 9.65 ≈ 9.62 (within tolerance)
# ✅ Total: 129.97 - 12.99 + 9.62 + 5.99 = 132.59

Example 2: International Currency (Japan)

Scenario

AI agent booking a hotel in Tokyo. JPY has no decimal places.

Correct (Verified)

checkout_japan = {
    "currency": "JPY",
    "line_items": [
        {"id": "hotel-room", "quantity": 3, "item": {"price": 15000}}
    ],
    "totals": [
        {"type": "subtotal", "amount": 45000},
        {"type": "tax", "amount": 4500},  # 10% consumption tax
        {"type": "total", "amount": 49500}
    ]
}

result = verifier.verify_checkout(checkout_japan)
# ✅ VERIFIED - No decimals, math correct

Incorrect (Blocked)

checkout_japan_bad = {
    "currency": "JPY",
    "totals": [
        {"type": "total", "amount": 49500.50}  # JPY can't have decimals!
    ]
}

result = verifier.verify_checkout(checkout_japan_bad)
# ❌ FAILED: JPY amounts cannot have decimal places

Example 3: Discount Validation

Scenario

AI applies a “20% off” coupon. Need to verify the math.

Percentage Discount

from qwed_ucp.guards import DiscountGuard
from decimal import Decimal

guard = DiscountGuard()

# AI claims: 20% of $150 = $30
result = guard.verify_percentage_discount(
    subtotal=Decimal("150.00"),
    discount_amount=Decimal("30.00"),
    percentage=Decimal("20")
)
# ✅ VERIFIED: 20% of 150 = 30

AI Makes Mistake

# AI claims: 20% of $150 = $35 (WRONG!)
result = guard.verify_percentage_discount(
    subtotal=Decimal("150.00"),
    discount_amount=Decimal("35.00"),
    percentage=Decimal("20")
)
# ❌ FAILED: 20% of $150 = $30, not $35
# Error: Discount calculation mismatch: expected $30.00, got $35.00

Example 4: State Machine Transitions

Scenario

Checkout progresses through states. Invalid transitions should be blocked.

Valid Flow

from qwed_ucp.guards import StateGuard

guard = StateGuard()

# Step 1: Empty cart
guard.verify({"status": "incomplete", "line_items": []})
# ✅ Valid: incomplete can be empty

# Step 2: Items added, ready
guard.verify({"status": "ready_for_complete", "line_items": [{"id": "item1"}]})
# ✅ Valid: ready_for_complete has items

# Step 3: Completed
guard.verify({"status": "completed", "order": {"id": "ORD-123"}})
# ✅ Valid: completed has order object

Invalid Transition (Blocked)

# Trying to go backwards: completed → ready_for_complete
guard.verify_transition(
    from_state="completed",
    to_state="ready_for_complete"
)
# ❌ FAILED: Cannot transition from 'completed' to 'ready_for_complete'

Example 5: FastAPI Production Setup

Full Implementation

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List
from qwed_ucp.middleware.fastapi import QWEDUCPMiddleware
import logging

# Configure logging
logging.basicConfig(level=logging.INFO)

app = FastAPI(title="Commerce API with QWED-UCP")

# Add verification middleware
app.add_middleware(
    QWEDUCPMiddleware,
    verify_paths=["/api/v1/checkout"],
    on_failure="reject",  # or "log" to just log without blocking
    tolerance=0.01
)

class LineItem(BaseModel):
    id: str
    quantity: int
    price: float

class CheckoutRequest(BaseModel):
    currency: str
    line_items: List[LineItem]
    discount_percent: float = 0
    shipping: float = 0

@app.post("/api/v1/checkout")
async def process_checkout(request: CheckoutRequest):
    """
    Process checkout - QWED-UCP already verified the math!
    """
    # Calculate totals (these are already verified by middleware)
    subtotal = sum(item.price * item.quantity for item in request.line_items)
    discount = subtotal * (request.discount_percent / 100)
    tax = (subtotal - discount) * 0.0825  # 8.25% tax
    total = subtotal - discount + tax + request.shipping
    
    return {
        "status": "completed",
        "order_id": "ORD-" + str(hash(str(request)))[:8],
        "total": round(total, 2),
        "verified": True
    }

@app.exception_handler(HTTPException)
async def verification_error_handler(request, exc):
    if exc.status_code == 422:
        return JSONResponse(
            status_code=422,
            content={
                "error": "verification_failed",
                "message": exc.detail,
                "help": "Please recalculate and try again"
            }
        )
    raise exc

Example 6: Express.js Production Setup

Full Implementation

const express = require('express');
const { createQWEDUCPMiddleware, UCPVerifier } = require('qwed-ucp-middleware');

const app = express();
app.use(express.json());

// Create verifier with custom config
const verifier = new UCPVerifier({
    tolerance: 0.01,
    strictMode: true
});

// Add middleware to checkout routes
app.use('/api/checkout', createQWEDUCPMiddleware({
    verifier,
    onFailure: (error, req, res) => {
        res.status(422).json({
            error: 'verification_failed',
            guard: error.guard,
            message: error.message,
            expected: error.expected,
            actual: error.actual
        });
    }
}));

app.post('/api/checkout', (req, res) => {
    // If we reach here, math is verified!
    const orderId = 'ORD-' + Date.now();
    
    res.json({
        status: 'completed',
        orderId,
        verified: true
    });
});

// Error handler
app.use((err, req, res, next) => {
    console.error('Checkout error:', err);
    res.status(500).json({ error: 'internal_error' });
});

app.listen(3000, () => {
    console.log('Commerce API running on port 3000');
    console.log('QWED-UCP verification enabled');
});

Example 7: Testing with pytest

Unit Tests for Guards

import pytest
from decimal import Decimal
from qwed_ucp import UCPVerifier
from qwed_ucp.guards import MoneyGuard, LineItemsGuard

class TestMoneyGuard:
    def test_correct_total(self):
        guard = MoneyGuard()
        result = guard.verify({
            "totals": [
                {"type": "subtotal", "amount": 100.00},
                {"type": "discount", "amount": 10.00},
                {"type": "tax", "amount": 8.25},
                {"type": "total", "amount": 98.25}
            ]
        })
        assert result.verified is True

    def test_wrong_total(self):
        guard = MoneyGuard()
        result = guard.verify({
            "totals": [
                {"type": "subtotal", "amount": 100.00},
                {"type": "total", "amount": 99.00}  # Should be 100!
            ]
        })
        assert result.verified is False
        assert "mismatch" in result.error.lower()

class TestLineItemsGuard:
    def test_correct_line_math(self):
        guard = LineItemsGuard()
        result = guard.verify({
            "line_items": [
                {"quantity": 2, "item": {"price": 25.00}}
            ],
            "totals": [{"type": "subtotal", "amount": 50.00}]
        })
        assert result.verified is True

    def test_quantity_price_mismatch(self):
        guard = LineItemsGuard()
        result = guard.verify({
            "line_items": [
                {"quantity": 2, "item": {"price": 25.00}}
            ],
            "totals": [{"type": "subtotal", "amount": 60.00}]  # Wrong!
        })
        assert result.verified is False

Best Practices

1. Always Verify Before Payment

# Good: Verify first
if verifier.verify_checkout(checkout).verified:
    process_payment(checkout)
else:
    log_error_and_retry()

# Bad: Process without verification
process_payment(checkout)  # Could have wrong totals!

2. Use Middleware in Production

Middleware catches errors automatically:
# Instead of manual verification everywhere...
app.add_middleware(QWEDUCPMiddleware)

3. Log Verification Failures

result = verifier.verify_checkout(checkout)
if not result.verified:
    logger.error(f"Verification failed: {result.error}")
    logger.error(f"Failed guard: {result.failed_guard}")
    logger.error(f"Checkout data: {checkout}")

4. Set Appropriate Tolerance

# For most currencies: $0.01 tolerance
verifier = UCPVerifier(tolerance=Decimal("0.01"))

# For high-precision applications: stricter
verifier = UCPVerifier(tolerance=Decimal("0.001"))