ComplianceGuard should verify policy, not own policy

[rahuldass19]

Summary

ComplianceGuard currently maintains AML thresholds, high-risk country lists, and KYC rules internally as hardcoded class attributes. This creates two problems:

1. Maintenance burden — Thresholds and country lists change when FATF updates its grey list or when FinCEN changes BSA thresholds. A verification library should not require updates every time a regulator changes a number.

2. False sense of completeness — The hardcoded lists are simplified subsets (e.g., only 13 high-risk countries when FATF tracks 20+). Users may assume the library provides complete regulatory coverage when it does not.

Current Design

class ComplianceGuard:
    def __init__(self):
        self.aml_thresholds = {
            "USA": 10000,
            "EU": 10000,
            "UK": 10000,
        }
        self.high_risk_countries = {"KP", "IR", "SY", ...}

    def verify_aml_flag(self, amount, country_code, llm_flagged, jurisdiction="USA"):
        threshold = self.aml_thresholds.get(jurisdiction, 10000)
        is_high_risk = country_code.upper() in self.high_risk_countries
        should_flag = amount >= threshold or is_high_risk
        ...

Proposed Change

Accept policy as a parameter so the caller provides the current rules:

class ComplianceGuard:
    def verify_aml_flag(self, amount, country_code, llm_flagged, policy):
        threshold = policy.get_aml_threshold(jurisdiction)
        is_high_risk = policy.is_high_risk(country_code)
        should_flag = amount >= threshold or is_high_risk
        ...

Rationale

QWED philosophy: "Rules are inputs. Verification is the product."

ComplianceGuard should verify that an LLM's decision matches a given policy. It should not define the policy itself. This keeps the library free from regulatory maintenance burden and avoids a false sense of completeness.

Migration Path

1. Add policy parameter to all ComplianceGuard methods (with backward-compatible default for existing callers)
2. Deprecate hardcoded aml_thresholds and high_risk_countries
3. Remove hardcoded values in next major version

Labels

architecture, P1"

[rahuldass19]

Adding a concrete interface sketch so a contributor picking this up knows exactly what shape the policy object should take.

Proposed CompliancePolicy protocol:

from typing import Protocol
from decimal import Decimal

class CompliancePolicy(Protocol):
    """Caller-provided regulatory policy. ComplianceGuard verifies against this."""

    def get_aml_threshold(self, jurisdiction: str) -> Decimal:
        """Return the CTR/AML reporting threshold for a jurisdiction (e.g., 10000 for USA)."""
        ...

    def is_high_risk(self, country_code: str) -> bool:
        """Return True if the country is on the caller's high-risk/sanctions list."""
        ...

    def get_transaction_limit(self, jurisdiction: str, account_type: str) -> Decimal:
        """Return the max transaction limit for a given jurisdiction and account type."""
        ...

Backward-compatible migration:

Ship a DefaultCompliancePolicy dataclass implementing this protocol with the current hardcoded values (USA/EU/UK thresholds at 10000, existing FATF grey list subset). This becomes the default parameter:

class ComplianceGuard:
    def __init__(self, policy: CompliancePolicy | None = None):
        self.policy = policy or DefaultCompliancePolicy()

    def verify_aml_flag(self, amount, country_code, llm_flagged, jurisdiction="USA"):
        threshold = self.policy.get_aml_threshold(jurisdiction)
        is_high_risk = self.policy.is_high_risk(country_code)
        should_flag = amount >= threshold or is_high_risk
        # ... rest of Z3 verification logic unchanged

This way:

• Existing callers (ComplianceGuard() with no args) keep working identically
• New callers can inject their own up-to-date policy without waiting for a library release
• The hardcoded lists move from "library truth" to "convenient default" — which is what they actually are

Deprecation path:

1. This PR: Add policy param + DefaultCompliancePolicy, keep self.aml_thresholds as a read-only property delegating to policy (no breaking change)
2. Next minor: Add deprecation warning when accessing self.aml_thresholds / self.high_risk_countries directly
3. Next major (v3.0): Remove hardcoded attributes entirely

The Protocol approach also makes it trivial for enterprise users to plug in a live policy service (e.g., fetching current FATF lists from an API) without modifying QWED Finance source.