Asset Source Tracing

from datetime import date, timedelta
from typing import List, Optional
from dataclasses import dataclass

@dataclass
class Transaction:
    date: date
    amount: float
    description: str
    type: str  # deposit, withdrawal, transfer
    category: Optional[str] = None

@dataclass
class LargeDeposit:
    date: date
    amount: float
    description: str
    source_documented: bool
    source_type: Optional[str]
    documentation: Optional[str]

class AssetSourceTracer:
    """Trace assets to legitimate sources"""
    
    LARGE_DEPOSIT_THRESHOLD = 0.5  # 50% of monthly income
    ABSOLUTE_THRESHOLD = 10000     # $10,000 always flagged
    SEASONING_DAYS = 60            # Standard seasoning requirement
    
    def analyze_bank_statements(self, 
                                 statements: list,
                                 monthly_income: float,
                                 closing_date: date) -> dict:
        """Analyze bank statements for asset sourcing"""
        
        result = {
            "large_deposits": [],
            "undocumented_sources": [],
            "seasoning_issues": [],
            "circular_transfers": [],
            "gift_correlations": [],
            "risk_score": 0.0
        }
        
        # Extract all transactions
        all_transactions = []
        for statement in statements:
            transactions = self.extract_transactions(statement)
            all_transactions.extend(transactions)
        
        # Identify large deposits
        threshold = max(
            monthly_income * self.LARGE_DEPOSIT_THRESHOLD,
            self.ABSOLUTE_THRESHOLD
        )
        
        large_deposits = [
            t for t in all_transactions 
            if t.type == "deposit" and t.amount >= threshold
        ]
        
        for deposit in large_deposits:
            # Check if source is identifiable
            source = self.identify_source(deposit)
            
            large_dep = LargeDeposit(
                date=deposit.date,
                amount=deposit.amount,
                description=deposit.description,
                source_documented=source["documented"],
                source_type=source["type"],
                documentation=source.get("documentation")
            )
            
            result["large_deposits"].append(large_dep)
            
            if not source["documented"]:
                result["undocumented_sources"].append({
                    "deposit": large_dep,
                    "action": "Request source documentation"
                })
                result["risk_score"] += 0.2
        
        # Check seasoning
        for deposit in large_deposits:
            days_before_closing = (closing_date - deposit.date).days
            if days_before_closing < self.SEASONING_DAYS:
                result["seasoning_issues"].append({
                    "deposit_date": str(deposit.date),
                    "amount": deposit.amount,
                    "days_before_closing": days_before_closing,
                    "required_days": self.SEASONING_DAYS
                })
                result["risk_score"] += 0.15
        
        # Detect circular transfers
        transfers = [t for t in all_transactions if "transfer" in t.type.lower()]
        circular = self.detect_circular_transfers(transfers)
        result["circular_transfers"] = circular
        if circular:
            result["risk_score"] += 0.3
        
        result["risk_score"] = min(result["risk_score"], 1.0)
        
        return result
    
    def identify_source(self, transaction: Transaction) -> dict:
        """Identify the source of a deposit"""
        
        description = transaction.description.lower()
        
        # Payroll patterns
        payroll_keywords = ["payroll", "salary", "direct deposit", "wages", "adp", "paychex"]
        if any(kw in description for kw in payroll_keywords):
            return {
                "type": "payroll",
                "documented": True,
                "confidence": 0.95
            }
        
        # Transfer patterns
        if "transfer" in description:
            return {
                "type": "transfer",
                "documented": False,  # Need source account statement
                "action": "Provide source account statement",
                "confidence": 0.5
            }
        
        # Wire patterns
        if "wire" in description:
            return {
                "type": "wire",
                "documented": False,
                "action": "Provide wire documentation",
                "confidence": 0.3
            }
        
        # Cash/check deposits
        if "cash" in description or "check" in description:
            if transaction.amount > 10000:
                return {
                    "type": "cash_or_check",
                    "documented": False,
                    "action": "Provide source documentation",
                    "confidence": 0.2
                }
        
        # Unknown
        return {
            "type": "unknown",
            "documented": False,
            "action": "Identify and document source",
            "confidence": 0.1
        }
    
    def correlate_gift_funds(self, 
                             gift_letters: list,
                             transactions: list) -> dict:
        """Correlate gift letters with actual deposits"""
        
        correlations = {
            "matched": [],
            "unmatched_letters": [],
            "unmatched_deposits": []
        }
        
        gift_deposits = []
        
        for letter in gift_letters:
            donor = letter["donor_name"].lower()
            amount = letter["amount"]
            gift_date = letter["date"]
            
            # Look for matching deposit
            matched = False
            for txn in transactions:
                if txn.type != "deposit":
                    continue
                
                # Amount within 5%
                amount_match = abs(txn.amount - amount) / amount < 0.05
                
                # Date within 30 days
                date_diff = abs((txn.date - gift_date).days)
                date_match = date_diff <= 30
                
                # Donor name in description
                name_match = donor in txn.description.lower()
                
                if amount_match and date_match:
                    correlations["matched"].append({
                        "letter": letter,
                        "deposit": txn,
                        "name_match": name_match,
                        "verified": name_match
                    })
                    matched = True
                    break
            
            if not matched:
                correlations["unmatched_letters"].append(letter)
        
        return correlations
    
    def detect_circular_transfers(self, transfers: list) -> list:
        """Detect circular transfer patterns"""
        
        circular = []
        
        # Group by rough amount (within 10%)
        for i, t1 in enumerate(transfers):
            for t2 in transfers[i+1:]:
                # Opposite directions
                if t1.amount * t2.amount < 0:  # One positive, one negative
                    # Similar amounts
                    if abs(abs(t1.amount) - abs(t2.amount)) / max(abs(t1.amount), abs(t2.amount)) < 0.1:
                        # Within 30 days
                        if abs((t1.date - t2.date).days) <= 30:
                            circular.append({
                                "transfer1": t1,
                                "transfer2": t2,
                                "pattern": "offsetting_transfers",
                                "risk": "medium"
                            })
        
        return circular
    
    def check_business_distribution(self,
                                    personal_statements: list,
                                    business_statements: list,
                                    tax_returns: list) -> dict:
        """Validate business distributions for self-employed"""
        
        result = {
            "distributions_found": [],
            "issues": [],
            "risk_score": 0.0
        }
        
        # Find transfers from business to personal
        for p_stmt in personal_statements:
            for txn in p_stmt.get("transactions", []):
                if txn["type"] == "deposit":
                    desc = txn["description"].lower()
                    
                    # Business name patterns
                    if any(term in desc for term in ["llc", "corp", "inc", "consulting"]):
                        distribution = {
                            "date": txn["date"],
                            "amount": txn["amount"],
                            "from": txn["description"]
                        }
                        result["distributions_found"].append(distribution)
                        
                        # Verify against business statements
                        if not business_statements:
                            result["issues"].append({
                                "type": "missing_business_statements",
                                "distribution": distribution,
                                "action": "Request business bank statements"
                            })
                            result["risk_score"] += 0.25
        
        return result
    
    def extract_transactions(self, statement: dict) -> List[Transaction]:
        """Extract transactions from bank statement"""
        
        transactions = []
        
        for txn in statement.get("transactions", []):
            transactions.append(Transaction(
                date=txn["date"],
                amount=txn["amount"],
                description=txn.get("description", ""),
                type=self.categorize_transaction(txn)
            ))
        
        return transactions
    
    def categorize_transaction(self, txn: dict) -> str:
        """Categorize transaction type"""
        
        amount = txn["amount"]
        desc = txn.get("description", "").lower()
        
        if amount > 0:
            if "transfer" in desc:
                return "transfer_in"
            return "deposit"
        else:
            if "transfer" in desc:
                return "transfer_out"
            return "withdrawal"