┌─────────────────────────────────────────────────────────────────────────────┐
│                    TRADE FINANCE INSTRUMENTS                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    LETTER OF CREDIT (LC)                            │   │
│  │  Bank guarantees payment to exporter on behalf of importer.         │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    BILL OF EXCHANGE                                  │   │
│  │  Written order from exporter to importer to pay a specified sum.    │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    DOCUMENTARY COLLECTION                           │   │
│  │  Banks handle shipping documents for payment.                       │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    BANK GUARANTEE                                    │   │
│  │  Bank promises to pay if the buyer defaults.                        │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    FORFAITING                                       │   │
│  │  Purchase of medium-term receivables without recourse.             │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                    BLOCKCHAIN TRANSFORMATION OF TRADE FINANCE               │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Traditional Process:                                                       │
│  ┌─────┐    ┌─────┐    ┌─────┐    ┌─────┐    ┌─────┐                     │
│  │Apply│───▶│Issue│───▶│Ship │───▶│Docs │───▶│Pay  │                     │
│  │ LC  │    │ LC  │    │Goods│    │Sent │    │    │                     │
│  └─────┘    └─────┘    └─────┘    └─────┘    └─────┘                     │
│  Time: 5-10 days, Cost: High, Risk: High                                  │
│                                                                             │
│  Blockchain-Enabled Process:                                                │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │  Smart Contract executes automatically:                             │   │
│  │  1. LC issued on-chain                                              │   │
│  │  2. Trade documents digitised                                       │   │
│  │  3. Shipment tracked via IoT                                        │   │
│  │  4. Document verification                                           │   │
│  │  5. Automatic payment release                                       │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│  Time: Hours, Cost: Low, Risk: Low                                       │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

# ===================================================================
# MODULE 3, LESSON 2: TRADE FINANCE
# ===================================================================

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import seaborn as sns
from datetime import datetime, timedelta
import random
from typing import Dict, List, Tuple
import warnings
warnings.filterwarnings('ignore')

print("="*70)
print("TRADE FINANCE – BLOCKCHAIN APPLICATIONS")
print("="*70)

# ----------------------------------------------------------------
# PART A: TRADE FINANCE DATA GENERATION
# ----------------------------------------------------------------

print("\n" + "-"*60)
print("PART A: Trade Finance Data Generation")
print("-"*60)

class TradeFinanceDataGenerator:
    """
    Generate realistic trade finance transaction data.
    """
    def __init__(self):
        self.exporters = [f"Exporter_{i}" for i in range(1, 21)]
        self.importers = [f"Importer_{i}" for i in range(1, 16)]
        self.banks = [f"Bank_{i}" for i in range(1, 11)]
        self.countries = ["China", "USA", "Germany", "UK", "Japan", "France", 
                         "Italy", "Brazil", "India", "Australia", "Singapore"]
        self.commodities = ["Electronics", "Automotive", "Pharmaceuticals", 
                           "Textiles", "Agricultural", "Chemicals", 
                           "Machinery", "Energy", "Metals", "Consumer Goods"]
        self.instruments = ["Letter of Credit", "Documentary Collection", 
                           "Bank Guarantee", "Forfaiting", "Supply Chain Finance"]
        
        self.periods = {
            'USD': (10000, 10000000),
            'EUR': (10000, 9000000),
            'GBP': (8000, 8000000),
            'CNY': (70000, 70000000),
            'JPY': (1000000, 1000000000)
        }
    
    def generate_trade_data(self, num_transactions: int = 500) -> pd.DataFrame:
        """
        Generate simulated trade finance transaction data.
        """
        data = []
        for i in range(num_transactions):
            tx_date = datetime.now() - timedelta(days=random.randint(1, 365))
            shipment_date = tx_date + timedelta(days=random.randint(5, 30))
            payment_date = shipment_date + timedelta(days=random.randint(0, 60))
            
            currency = random.choice(list(self.periods.keys()))
            min_val, max_val = self.periods[currency]
            value = random.uniform(min_val, max_val)
            
            statuses = ['Initiated', 'Approved', 'Issued', 'Shipped', 
                       'Documented', 'Paid', 'Completed', 'Disputed']
            
            data.append({
                'transaction_id': f'TF-{i+1:06d}',
                'exporter': random.choice(self.exporters),
                'importer': random.choice(self.importers),
                'bank': random.choice(self.banks),
                'country_export': random.choice(self.countries),
                'country_import': random.choice([c for c in self.countries if c != '']),
                'commodity': random.choice(self.commodities),
                'instrument': random.choice(self.instruments),
                'value': round(value, 2),
                'currency': currency,
                'transaction_date': tx_date,
                'shipment_date': shipment_date,
                'payment_date': payment_date,
                'status': random.choices(statuses, weights=[0.05, 0.10, 0.15, 0.20, 0.15, 0.20, 0.10, 0.05])[0],
                'is_financed': random.choice([True, False]),
                'finance_rate': random.uniform(0.02, 0.08),
                'document_count': random.randint(5, 25)
            })
        
        return pd.DataFrame(data)

# Generate data
data_gen = TradeFinanceDataGenerator()
trade_data = data_gen.generate_trade_data(500)

print(f"Generated {len(trade_data)} trade transactions")
print("\nSample Trade Data:")
print(trade_data.head(10).to_string(index=False))

# ----------------------------------------------------------------
# PART B: TRADE FINANCE ANALYTICS
# ----------------------------------------------------------------

print("\n" + "-"*60)
print("PART B: Trade Finance Analytics")
print("-"*60)

class TradeFinanceAnalytics:
    """
    Analytics for trade finance transactions.
    """
    def __init__(self, df: pd.DataFrame):
        self.df = df.copy()
        self._preprocess()
    
    def _preprocess(self):
        """Preprocess data for analysis."""
        # Calculate days to completion
        self.df['days_to_completion'] = (self.df['payment_date'] - self.df['transaction_date']).dt.days
        
        # Calculate financing value
        self.df['financing_value'] = np.where(
            self.df['is_financed'],
            self.df['value'] * (1 + self.df['finance_rate']),
            0
        )
        
        # Status categories
        status_order = ['Initiated', 'Approved', 'Issued', 'Shipped', 
                       'Documented', 'Paid', 'Completed', 'Disputed']
        self.df['status_category'] = pd.Categorical(self.df['status'], 
                                                    categories=status_order, 
                                                    ordered=True)
    
    def get_summary_metrics(self) -> Dict:
        """Get summary metrics."""
        total_value = self.df['value'].sum()
        financed_value = self.df[self.df['is_financed']]['value'].sum()
        avg_days = self.df['days_to_completion'].mean()
        avg_docs = self.df['document_count'].mean()
        completed_pct = (self.df['status'] == 'Completed').mean()
        
        return {
            'Total Transactions': len(self.df),
            'Total Trade Value': f"{self.df['currency'].iloc[0]} {total_value:,.2f}",
            'Financed Transactions': self.df['is_financed'].sum(),
            'Financed Value': f"{self.df['currency'].iloc[0]} {financed_value:,.2f}",
            'Average Days to Completion': f"{avg_days:.1f}",
            'Average Documents per Transaction': f"{avg_docs:.1f}",
            'Completed Rate': f"{completed_pct:.1%}"
        }
    
    def analyze_by_instrument(self) -> pd.DataFrame:
        """Analyse by trade finance instrument."""
        return self.df.groupby('instrument').agg({
            'transaction_id': 'count',
            'value': ['sum', 'mean', 'std'],
            'days_to_completion': 'mean',
            'document_count': 'mean'
        }).round(2)
    
    def analyze_by_commodity(self) -> pd.DataFrame:
        """Analyse by commodity."""
        return self.df.groupby('commodity').agg({
            'transaction_id': 'count',
            'value': 'sum',
            'days_to_completion': 'mean'
        }).round(2)
    
    def get_efficiency_metrics(self) -> pd.DataFrame:
        """
        Calculate efficiency metrics by stage.
        """
        stages = ['Initiated', 'Approved', 'Issued', 'Shipped', 'Documented', 'Paid', 'Completed']
        stage_counts = self.df['status_category'].value_counts()
        
        # Calculate conversion rates
        conversion_rates = []
        for i in range(len(stages)-1):
            current = stage_counts.get(stages[i], 0)
            next_stage = stage_counts.get(stages[i+1], 0)
            rate = next_stage / current if current > 0 else 0
            conversion_rates.append(rate)
        
        metrics = pd.DataFrame({
            'Stage': stages[:-1],
            'Count': [stage_counts.get(s, 0) for s in stages[:-1]],
            'Conversion Rate': conversion_rates
        })
        return metrics

# Calculate analytics
analytics = TradeFinanceAnalytics(trade_data)

# Display summary metrics
summary = analytics.get_summary_metrics()
print("\nTrade Finance Summary Metrics:")
for key, value in summary.items():
    print(f"  {key}: {value}")

# Instrument analysis
print("\nAnalysis by Instrument:")
instrument_data = analytics.analyze_by_instrument()
print(instrument_data.head(10).to_string())

# ----------------------------------------------------------------
# PART C: VISUALISE TRADE FINANCE DATA
# ----------------------------------------------------------------

print("\n" + "-"*60)
print("PART C: Trade Finance Visualisation")
print("-"*60)

# Create visualisations
fig, axes = plt.subplots(2, 2, figsize=(14, 10))

# 1. Status distribution
ax1 = axes[0, 0]
status_counts = trade_data['status'].value_counts()
ax1.pie(status_counts.values, labels=status_counts.index, autopct='%1.1f%%', startangle=90)
ax1.set_title('Trade Transaction Status Distribution')

# 2. Value by instrument
ax2 = axes[0, 1]
instrument_value = trade_data.groupby('instrument')['value'].sum().sort_values()
ax2.barh(instrument_value.index, instrument_value.values, color='teal', alpha=0.7)
ax2.set_xlabel('Total Value')
ax2.set_title('Trade Value by Instrument')
ax2.grid(True, alpha=0.3)

# 3. Days to completion by instrument
ax3 = axes[1, 0]
instrument_days = trade_data.groupby('instrument')['days_to_completion'].mean().sort_values()
ax3.bar(instrument_days.index, instrument_days.values, color='orange', alpha=0.7)
ax3.set_ylabel('Average Days')
ax3.set_title('Average Days to Completion by Instrument')
ax3.set_xticklabels(instrument_days.index, rotation=45, ha='right')
ax3.grid(True, alpha=0.3)

# 4. Financing rate by instrument
ax4 = axes[1, 1]
financing_by_instrument = trade_data.groupby('instrument')['is_financed'].mean()
ax4.bar(financing_by_instrument.index, financing_by_instrument.values, color='green', alpha=0.7)
ax4.set_ylabel('Financing Rate')
ax4.set_title('Financing Rate by Instrument')
ax4.set_xticklabels(financing_by_instrument.index, rotation=45, ha='right')
ax4.grid(True, alpha=0.3)

plt.tight_layout()
plt.savefig('trade_finance_analytics.png', dpi=300, bbox_inches='tight')
plt.show()
print("Trade finance analytics chart saved as 'trade_finance_analytics.png'")

# ----------------------------------------------------------------
# PART D: SMART CONTRACT FOR LETTER OF CREDIT
# ----------------------------------------------------------------

print("\n" + "-"*60)
print("PART D: Smart Contract for Letter of Credit Simulation")
print("-"*60)

class LCState:
    """States for a Letter of Credit."""
    CREATED = "created"
    APPROVED = "approved"
    ISSUED = "issued"
    SHIPPED = "shipped"
    DOCS_SUBMITTED = "docs_submitted"
    DOCS_VERIFIED = "docs_verified"
    PAID = "paid"
    COMPLETED = "completed"
    DISPUTED = "disputed"

class LetterOfCredit:
    """
    Simulate a blockchain-based Letter of Credit.
    """
    def __init__(self, lc_id: str, importer: str, exporter: str, bank: str, amount: float, expiry_date: datetime):
        self.lc_id = lc_id
        self.importer = importer
        self.exporter = exporter
        self.bank = bank
        self.amount = amount
        self.expiry_date = expiry_date
        self.state = LCState.CREATED
        self.documents = []
        self.verified_docs = []
        self.history = [('created', datetime.now())]
        self.created_at = datetime.now()
    
    def approve(self, approver: str) -> bool:
        if approver != self.bank:
            print(f"Only bank can approve. Approver: {approver}")
            return False
        if self.state != LCState.CREATED:
            return False
        self.state = LCState.APPROVED
        self.history.append(('approved', datetime.now()))
        print(f"LC {self.lc_id} APPROVED by {approver}")
        return True
    
    def issue(self, issuer: str) -> bool:
        if issuer != self.bank:
            print(f"Only bank can issue. Issuer: {issuer}")
            return False
        if self.state != LCState.APPROVED:
            return False
        self.state = LCState.ISSUED
        self.history.append(('issued', datetime.now()))
        print(f"LC {self.lc_id} ISSUED")
        return True
    
    def ship_goods(self, shipper: str) -> bool:
        if shipper != self.exporter:
            print(f"Only exporter can ship. Shipper: {shipper}")
            return False
        if self.state != LCState.ISSUED:
            return False
        self.state = LCState.SHIPPED
        self.history.append(('shipped', datetime.now()))
        print(f"Goods for LC {self.lc_id} SHIPPED by {shipper}")
        return True
    
    def submit_documents(self, submitter: str, docs: List[str]) -> bool:
        if submitter != self.exporter:
            print(f"Only exporter can submit documents. Submitter: {submitter}")
            return False
        if self.state not in [LCState.ISSUED, LCState.SHIPPED]:
            return False
        self.documents = docs
        self.state = LCState.DOCS_SUBMITTED
        self.history.append(('docs_submitted', datetime.now()))
        print(f"Documents for LC {self.lc_id} SUBMITTED by {submitter}")
        return True
    
    def verify_documents(self, verifier: str) -> bool:
        if verifier != self.bank:
            print(f"Only bank can verify documents. Verifier: {verifier}")
            return False
        if self.state != LCState.DOCS_SUBMITTED:
            return False
        
        # Simulate verification (some random success)
        is_verified = random.random() > 0.1  # 90% success rate
        
        if is_verified:
            self.verified_docs = self.documents
            self.state = LCState.DOCS_VERIFIED
            self.history.append(('docs_verified', datetime.now()))
            print(f"Documents for LC {self.lc_id} VERIFIED")
            return True
        else:
            self.state = LCState.DISPUTED
            self.history.append(('disputed', datetime.now()))
            print(f"Documents for LC {self.lc_id} DISPUTED")
            return False
    
    def pay(self, payer: str) -> bool:
        if payer != self.importer:
            print(f"Only importer can pay. Payer: {payer}")
            return False
        if self.state != LCState.DOCS_VERIFIED:
            return False
        self.state = LCState.PAID
        self.history.append(('paid', datetime.now()))
        print(f"LC {self.lc_id} PAID: ${self.amount:,.2f}")
        return True
    
    def complete(self) -> bool:
        if self.state != LCState.PAID:
            return False
        self.state = LCState.COMPLETED
        self.history.append(('completed', datetime.now()))
        print(f"LC {self.lc_id} COMPLETED")
        return True
    
    def get_state(self) -> str:
        return self.state
    
    def get_history(self) -> List[Tuple[str, datetime]]:
        return self.history
    
    def get_summary(self) -> Dict:
        return {
            'lc_id': self.lc_id,
            'state': self.state,
            'amount': self.amount,
            'importer': self.importer,
            'exporter': self.exporter,
            'bank': self.bank,
            'created_at': self.created_at,
            'documents': len(self.documents),
            'verified_docs': len(self.verified_docs),
            'history': self.history
        }

# Simulate LC process
lc = LetterOfCredit(
    lc_id='LC-001',
    importer='Importer_ABC',
    exporter='Exporter_XYZ',
    bank='TradeBank',
    amount=500000,
    expiry_date=datetime.now() + timedelta(days=60)
)

print("\nLetter of Credit Process Simulation:")
print(f"Created LC {lc.lc_id} for ${lc.amount:,.2f}")

# Process steps
lc.approve('TradeBank')
lc.issue('TradeBank')
lc.ship_goods('Exporter_XYZ')
lc.submit_documents('Exporter_XYZ', ['Invoice', 'Bill of Lading', 'Certificate of Origin', 'Insurance'])
lc.verify_documents('TradeBank')

if lc.get_state() == LCState.DOCS_VERIFIED:
    lc.pay('Importer_ABC')
    lc.complete()

print(f"\nFinal State: {lc.get_state()}")
print("\nTransaction History:")
for action, time in lc.get_history():
    print(f"  {action}: {time.strftime('%Y-%m-%d %H:%M')}")

# ----------------------------------------------------------------
# PART E: TRADE FINANCE EFFICIENCY IMPROVEMENT
# ----------------------------------------------------------------

print("\n" + "-"*60)
print("PART E: Trade Finance Efficiency Improvement Analysis")
print("-"*60)

efficiency_data = {
    'Metric': [
        'Processing Time (days)',
        'Document Preparation (hours)',
        'Approval Time (days)',
        'Payment Settlement (days)',
        'Fraud Risk (Scale 1-10)',
        'Transaction Cost (basis points)'
    ],
    'Traditional': [
        10,
        48,
        5,
        3,
        7,
        150
    ],
    'Blockchain-Enabled': [
        2,
        2,
        0.5,
        0.5,
        2,
        30
    ],
    'Improvement': [
        '80%',
        '96%',
        '90%',
        '83%',
        '71%',
        '80%'
    ]
}

efficiency_df = pd.DataFrame(efficiency_data)
print(efficiency_df.to_string(index=False))

# Visualise efficiency comparison
fig, axes = plt.subplots(1, 2, figsize=(14, 5))

# Metric comparison (select metrics)
metrics_to_plot = ['Processing Time (days)', 'Transaction Cost (basis points)']
traditional_values = [10, 150]
blockchain_values = [2, 30]

ax1 = axes[0]
x = np.arange(len(metrics_to_plot))
width = 0.35
ax1.bar(x - width/2, traditional_values, width, label='Traditional', color='red', alpha=0.7)
ax1.bar(x + width/2, blockchain_values, width, label='Blockchain-Enabled', color='green', alpha=0.7)
ax1.set_xticks(x)
ax1.set_xticklabels(metrics_to_plot)
ax1.set_ylabel('Value')
ax1.set_title('Efficiency Improvement')
ax1.legend()
ax1.grid(True, alpha=0.3)

# Improvement percentages
ax2 = axes[1]
improvements = [80, 96, 90, 83, 71, 80]
metric_names = ['Processing Time', 'Document Prep', 'Approval', 'Settlement', 'Fraud Risk', 'Cost']
ax2.barh(metric_names, improvements, color='blue', alpha=0.7)
ax2.set_xlabel('Improvement (%)')
ax2.set_title('Blockchain Efficiency Improvement by Metric')
ax2.grid(True, alpha=0.3)

plt.tight_layout()
plt.savefig('trade_finance_efficiency.png', dpi=300, bbox_inches='tight')
plt.show()
print("Trade finance efficiency chart saved as 'trade_finance_efficiency.png'")

# ----------------------------------------------------------------
# PART F: SUMMARY AND RECOMMENDATIONS
# ----------------------------------------------------------------

print("\n" + "="*70)
print("PART F: Summary and Recommendations")
print("="*70)

print("""
Trade Finance with Blockchain – Key Takeaways:

1. Trade finance includes LCs, bills of exchange, documentary collections, and guarantees.
2. Traditional trade finance is paper-heavy, slow, expensive, and fraud-prone.
3. Blockchain enables digital letters of credit, automated document verification, and smart payments.
4. Key platforms: TradeLens, Contour, Marco Polo, Komgo.
5. Smart contracts automate payment release upon document verification.
6. Benefits: reduced time (80%), lower costs, increased transparency, reduced fraud.
7. Blockchain enables SME access to trade financing.

Recommendations:
  - Digitise letters of credit and trade documents.
  - Implement smart contracts for automatic payment release.
  - Integrate IoT and supply chain tracking for real-time visibility.
  - Build a network of trusted participants (banks, traders, logistics).
  - Ensure regulatory compliance across jurisdictions.
  - Start with a single trade corridor and expand.
  - Use hybrid approaches (on-chain verification, off-chain data) for scalability.
""")