REGULATORY DATA FEEDS
(OFAC, FATF, FinCEN, local watchlists)
         ↓
[INGESTION AGENT] — normalise, deduplicate, version
         ↓
TRANSACTION STREAM (real-time)
         ↓
[SCREENING AGENT] — rule-based + Claude analysis
         ↓ 
         ├── LOW RISK → auto-clear + audit log
         ├── MEDIUM RISK → flag + evidence package → analyst queue
         └── HIGH RISK → block + SAR draft → senior review
                    ↓
         [AUDIT TRAIL AGENT] — immutable decision log
                    ↓
         [REPORTING AGENT] — SAR generation, regulatory reporting

from anthropic import Anthropic
from datetime import datetime
import hashlib
import json

client = Anthropic()

class RegulatoryIngestionAgent:
    def __init__(self, db_connection, audit_logger):
        self.db = db_connection
        self.audit = audit_logger

    async def ingest_watchlist_update(
        self, 
        source: str,
        raw_data: bytes,
        update_metadata: dict
    ) -> dict:
        """
        Ingests watchlist updates with full provenance tracking.
        Every entry gets a source, version and effective date.
        """

        # Parse with Claude for flexible format handling
        response = client.messages.create(
            model="claude-sonnet-4-5",
            max_tokens=4000,
            system="""Parse regulatory watchlist data into 
            structured entities. Handle variations in format
            across different regulatory sources.

            Extract for each entity:
            - canonical_name (primary identifier)
            - aliases (all alternative names)
            - entity_type (individual/organisation/vessel/aircraft)
            - identifiers (passport, tax ID, registration numbers)
            - addresses (with country codes)
            - listing_reason (sanctions program or crime category)
            - effective_date
            - source_reference (regulatory document ID)

            Return JSON array of entities.
            Flag any entries with ambiguous identity markers.""",
            messages=[{
                "role": "user",
                "content": f"Source: {source}\n\n{raw_data.decode('utf-8', errors='replace')}"
            }]
        )

        entities = json.loads(response.content[0].text)

        # Version control for watchlist entries
        for entity in entities:
            entity['_provenance'] = {
                'source': source,
                'ingest_timestamp': datetime.utcnow().isoformat(),
                'source_document_hash': hashlib.sha256(raw_data).hexdigest(),
                'regulatory_effective_date': update_metadata.get('effective_date'),
                'version_id': self.generate_version_id(entity, source)
            }

        await self.db.upsert_watchlist_entities(entities)

        self.audit.log({
            'event': 'watchlist_update_ingested',
            'source': source,
            'entities_added': len(entities),
            'timestamp': datetime.utcnow().isoformat()
        })

        return {
            'entities_processed': len(entities),
            'flagged_for_review': [e for e in entities if e.get('ambiguous')]
        }

class TransactionScreeningAgent:

    RISK_THRESHOLDS = {
        'auto_clear': 0.25,
        'analyst_review': 0.6,
        'block_and_escalate': 0.85
    }

    async def screen_transaction(
        self, 
        transaction: dict
    ) -> dict:
        """
        Screens transaction against watchlists and risk models.
        Returns decision with full reasoning chain for audit trail.
        """

        # Fast rule-based pre-screen
        rule_matches = await self.run_rule_engine(transaction)

        if rule_matches['exact_match']:
            return self.build_decision(
                transaction, 
                risk_score=0.95,
                decision='BLOCK',
                reasoning_type='exact_watchlist_match',
                evidence=rule_matches
            )

        # Claude analysis for fuzzy matching and context
        entity_context = await self.get_entity_context(
            transaction['counterparty']
        )

        response = client.messages.create(
            model="claude-sonnet-4-5",
            max_tokens=1500,
            system="""You are a compliance analyst screening 
            financial transactions. Analyse the transaction
            against the provided entity context and risk factors.

            Provide a structured risk assessment with:
            1. Risk score (0.0-1.0)
            2. Primary risk factors (list each with evidence)
            3. Mitigating factors (if any)
            4. Decision rationale (2-3 sentences, auditor-readable)
            5. Recommended action: AUTO_CLEAR / ANALYST_REVIEW / BLOCK
            6. Confidence level: HIGH / MEDIUM / LOW

            Be specific. Cite the exact data points that 
            influenced the score. Vague rationale fails audits.

            Return as JSON with schema:
            {
                "risk_score": float,
                "risk_factors": [{"factor": str, "evidence": str, "weight": str}],
                "mitigating_factors": [str],
                "decision_rationale": str,
                "recommended_action": str,
                "confidence": str,
                "additional_checks_required": [str]
            }""",
            messages=[{
                "role": "user",
                "content": f"""Transaction details:
Amount: {transaction['amount']} {transaction['currency']}
Counterparty: {transaction['counterparty_name']}
Counterparty country: {transaction['counterparty_country']}
Transaction type: {transaction['type']}
Reference: {transaction.get('reference', 'None')}
Originating account risk tier: {transaction['account_risk_tier']}

Entity context from watchlist database:
{json.dumps(entity_context, indent=2)}

Fuzzy name match results:
{json.dumps(rule_matches['fuzzy_matches'], indent=2)}"""
            }]
        )

        analysis = json.loads(response.content[0].text)

        return self.build_decision(
            transaction,
            risk_score=analysis['risk_score'],
            decision=analysis['recommended_action'],
            reasoning_type='claude_analysis',
            evidence=analysis
        )

    def build_decision(
        self, 
        transaction: dict,
        risk_score: float,
        decision: str,
        reasoning_type: str,
        evidence: dict
    ) -> dict:
        """
        Builds the decision record that goes to audit trail.
        Every field that an auditor might ask about is explicit.
        """
        return {
            'transaction_id': transaction['id'],
            'screening_timestamp': datetime.utcnow().isoformat(),
            'decision': decision,
            'risk_score': risk_score,
            'reasoning_type': reasoning_type,
            'evidence': evidence,
            'agent_version': AGENT_VERSION,
            'watchlist_versions_consulted': self.get_active_watchlist_versions(),
            'regulatory_basis': self.get_applicable_regulations(transaction),
            'human_review_required': risk_score >= self.RISK_THRESHOLDS['analyst_review']
        }

class AuditTrailAgent:

    def __init__(self, immutable_store):
        # Immutable store — append only, no updates, no deletes
        self.store = immutable_store

    async def record_decision(self, decision_record: dict) -> str:
        """
        Records a compliance decision with full provenance.
        Returns the immutable record ID for reference.
        """

        # Generate explainability summary for human review
        response = client.messages.create(
            model="claude-sonnet-4-5",
            max_tokens=800,
            system="""Generate a plain-language explanation of 
            this compliance decision suitable for regulator review.

            The explanation must:
            1. State the decision and its risk basis clearly
            2. Identify the specific factors that drove the decision
            3. Note any watchlist matches with regulatory references
            4. Explain what additional review was triggered, if any
            5. Be written so a non-technical compliance officer
               can understand and defend it

            Maximum 200 words. No jargon. No model internals.
            The reader is an auditor, not a data scientist.""",
            messages=[{
                "role": "user",
                "content": json.dumps(decision_record, indent=2)
            }]
        )

        human_readable_explanation = response.content[0].text

        audit_record = {
            **decision_record,
            'human_readable_explanation': human_readable_explanation,
            'record_created_at': datetime.utcnow().isoformat(),
            'record_id': self.generate_record_id(decision_record)
        }

        record_id = await self.store.append(audit_record)

        return record_id

    async def generate_examination_report(
        self,
        date_range: tuple,
        transaction_ids: list = None,
        include_auto_cleared: bool = False
    ) -> dict:
        """
        Generates examination-ready compliance report.
        Format designed for regulatory examination.
        """

        records = await self.store.query(
            date_range=date_range,
            transaction_ids=transaction_ids,
            include_auto_cleared=include_auto_cleared
        )

        response = client.messages.create(
            model="claude-sonnet-4-5",
            max_tokens=3000,
            system="""Compile a compliance examination report 
            from transaction screening records.

            Structure the report as regulators expect:
            1. Executive summary (screening volume, decision distribution)
            2. High-risk transaction summary (blocked and escalated)
            3. Watchlist match analysis (by source, match type)
            4. False positive analysis (analyst overrides)
            5. System performance metrics
            6. Notable patterns or anomalies

            Be factual. Cite specific transaction IDs for examples.
            Format for readability — this goes to regulators.""",
            messages=[{
                "role": "user",
                "content": f"Records for period {date_range}:\n{json.dumps(records, indent=2)}"
            }]
        )

        return {
            'report': response.content[0].text,
            'record_count': len(records),
            'period': date_range,
            'generated_at': datetime.utcnow().isoformat()
        }