Refactoring App Structure (#1)

README.md

@@ -7,7 +7,7 @@ sdk: docker
 sdk_version: 7.1.0
 secrets:
   - GITHUB_TOKEN
-app_file: app_with_confluence.py
+app_file: app.py
 pinned: false
 license: apache-2.0
 short_description: Fraud Model Explainability Assistant using Strands Agents

app.py

@@ -1,672 +1,285 @@
+#!/usr/bin/env python
 """
 Fraud Model Explainability Assistant - Strands Agents
-
 An AI-powered assistant that helps fraud analysts and executives understand
 why specific applications were flagged as fraudulent, translating complex
 model outputs into actionable insights.
 
+Author: Fraud Model Data Science Team
+
 Use Cases:
 - Executive briefings on fraud decisions
 - Fair lending compliance documentation
 - Analyst investigation support
 - Model decision audit trails
 
-Author: Fraud Model Data Science Team
+Production-Ready Confluence Integration (FastAPI Version)
+
+Features:
+- Comprehensive logging and monitoring
+- Error handling and recovery
+- Scheduled re-ingestion for keeping data fresh
+- Performance metrics tracking
+- FastAPI + uvicorn for Docker deployment
+
+Prerequisites:
+    - Configure .env with Confluence credentials
 """
 
 import os
-import random
+import sys
+import json
 import warnings
-from datetime import datetime, timedelta
+import logging
+import time
+from functools import lru_cache
 from typing import Optional
+from datetime import datetime
 
-# Suppress asyncio "Invalid file descriptor" warnings in containerized environments
-# These are harmless cleanup warnings during garbage collection
+# Suppress ResourceWarning for cleaner output
 warnings.filterwarnings("ignore", category=ResourceWarning)
 os.environ["PYTHONWARNINGS"] = "ignore::ResourceWarning"
 
-import gradio as gr
-from strands import Agent, tool
+# Load environment variables from .env file
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    print("⚠ Warning: python-dotenv not installed. Install with: pip install python-dotenv")
+    print("   Environment variables must be set manually.")
+
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import HTMLResponse
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+
+from strands import Agent
 from strands.models.openai import OpenAIModel
 
+# Import confluence-ingestor
+from confluence_ingestor import ConfluenceRAG
+from confluence_ingestor.adapters.strands import (
+    create_confluence_search_tool,
+    create_confluence_loader_tool,
+)
+
+# Import your existing fraud tools
+from utils import (
+    get_application_summary,
+    explain_fraud_score,
+    compare_to_population,
+    check_fair_lending_flags,
+    get_identity_network,
+    get_model_performance,
+    SYSTEM_PROMPT as ORIGINAL_PROMPT,
+)
+
 
 # =============================================================================
-# MOCK DATA GENERATORS
+# LOGGING CONFIGURATION
 # =============================================================================
-# In production, these would connect to your actual data systems
-# (e.g., Snowflake, feature store, model serving infrastructure)
 
-def generate_mock_application(app_id: str) -> dict:
-    """Generate realistic mock application data for demo purposes."""
-    random.seed(hash(app_id) % 2**32)
-    
-    risk_level = random.choice(["low", "medium", "high", "very_high"])
-    
-    base_data = {
-        "application_id": app_id,
-        "timestamp": (datetime.now() - timedelta(days=random.randint(0, 30))).isoformat(),
-        "portfolio": random.choice(["Retail Card", "Payment Solutions", "CareCredit"]),
-        "requested_credit_line": random.randint(500, 25000),
-        "fraud_score": {
-            "low": random.randint(150, 350),
-            "medium": random.randint(400, 550),
-            "high": random.randint(600, 750),
-            "very_high": random.randint(800, 950)
-        }[risk_level],
-        "fraud_score_percentile": {
-            "low": random.randint(5, 30),
-            "medium": random.randint(40, 60),
-            "high": random.randint(75, 90),
-            "very_high": random.randint(92, 99)
-        }[risk_level],
-        "decision": "FLAGGED" if risk_level in ["high", "very_high"] else "APPROVED",
-        "risk_level": risk_level,
-    }
-    
-    # Features that contribute to fraud scoring
-    if risk_level in ["high", "very_high"]:
-        base_data["features"] = {
-            "ssn_issue_date_vs_credit_age_mismatch": random.uniform(0.7, 0.95),
-            "device_velocity_30d": random.randint(5, 15),
-            "address_type": random.choice(["CMRA", "PO_BOX", "VACANT"]),
-            "phone_type": random.choice(["VOIP", "PREPAID"]),
-            "email_domain_age_days": random.randint(1, 30),
-            "application_velocity_14d": random.randint(3, 8),
-            "identity_linkage_count": random.randint(4, 12),
-            "credit_inquiry_spike": True,
-            "synthetic_id_score": random.uniform(0.75, 0.98),
-        }
-    else:
-        base_data["features"] = {
-            "ssn_issue_date_vs_credit_age_mismatch": random.uniform(0.0, 0.2),
-            "device_velocity_30d": random.randint(1, 2),
-            "address_type": "RESIDENTIAL",
-            "phone_type": "POSTPAID",
-            "email_domain_age_days": random.randint(365, 3650),
-            "application_velocity_14d": random.randint(0, 1),
-            "identity_linkage_count": random.randint(0, 2),
-            "credit_inquiry_spike": False,
-            "synthetic_id_score": random.uniform(0.05, 0.25),
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    handlers=[
+        logging.FileHandler('fraud_assistant_confluence.log'),
+        logging.StreamHandler()
+    ]
+)
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# METRICS TRACKING
+# =============================================================================
+
+class ConfluenceMetrics:
+    """Track Confluence integration performance metrics."""
+
+    def __init__(self):
+        self.search_count = 0
+        self.cache_hits = 0
+        self.cache_misses = 0
+        self.errors = 0
+        self.last_ingestion = None
+        self.query_times = []
+
+    def record_search(self, cached: bool = False, duration: float = 0.0):
+        """Record a search query."""
+        self.search_count += 1
+        if cached:
+            self.cache_hits += 1
+        else:
+            self.cache_misses += 1
+        self.query_times.append(duration)
+
+    def record_error(self):
+        """Record an error."""
+        self.errors += 1
+
+    def record_ingestion(self):
+        """Record a data ingestion."""
+        self.last_ingestion = datetime.now()
+
+    def get_stats(self) -> dict:
+        """Get current metrics."""
+        return {
+            "total_searches": self.search_count,
+            "cache_hit_rate": (
+                self.cache_hits / self.search_count
+                if self.search_count > 0
+                else 0.0
+            ),
+            "avg_query_time": (
+                sum(self.query_times) / len(self.query_times)
+                if self.query_times
+                else 0.0
+            ),
+            "errors": self.errors,
+            "last_ingestion": str(self.last_ingestion) if self.last_ingestion else None,
         }
-    
-    return base_data
+
+
+# Global metrics instance
+_metrics = ConfluenceMetrics()
 
 
 # =============================================================================
-# FRAUD EXPLAINABILITY TOOLS
+# CONFLUENCE INITIALIZATION
 # =============================================================================
 
-@tool
-def get_application_summary(application_id: str) -> str:
-    """
-    Retrieve basic information about a credit application including
-    fraud score, decision, portfolio, and timestamp.
-    
-    Args:
-        application_id: The unique identifier for the application (e.g., "APP-12345")
-    
-    Returns:
-        A summary of the application details and fraud assessment
-    """
-    app = generate_mock_application(application_id)
-    
-    return f"""
-APPLICATION SUMMARY
-==================
-Application ID: {app['application_id']}
-Submission Date: {app['timestamp'][:10]}
-Portfolio: {app['portfolio']}
-Requested Credit Line: ${app['requested_credit_line']:,}
-
-FRAUD ASSESSMENT
-----------------
-Fraud Score: {app['fraud_score']} / 1000
-Risk Percentile: {app['fraud_score_percentile']}th percentile
-Risk Level: {app['risk_level'].upper()}
-Decision: {app['decision']}
-"""
+_confluence_rag: Optional[ConfluenceRAG] = None
 
 
-@tool
-def explain_fraud_score(application_id: str) -> str:
-    """
-    Get detailed SHAP-style feature attribution explanation for why an 
-    application received its fraud score. Shows which factors contributed
-    most to the risk assessment.
-    
-    Args:
-        application_id: The unique identifier for the application
-    
-    Returns:
-        Detailed breakdown of contributing factors with impact scores
-    """
-    app = generate_mock_application(application_id)
-    features = app["features"]
-    
-    # Simulate SHAP values (in production, these come from your model)
-    explanations = []
-    
-    if features["ssn_issue_date_vs_credit_age_mismatch"] > 0.5:
-        explanations.append({
-            "feature": "SSN Issue Date vs Credit Age Mismatch",
-            "value": f"{features['ssn_issue_date_vs_credit_age_mismatch']:.0%}",
-            "impact": "+187 points",
-            "direction": "INCREASES RISK",
-            "explanation": "SSN was issued recently but credit file shows longer history, a key synthetic ID indicator"
-        })
-    
-    if features["device_velocity_30d"] > 3:
-        explanations.append({
-            "feature": "Device Velocity (30 days)",
-            "value": f"{features['device_velocity_30d']} applications",
-            "impact": "+142 points",
-            "direction": "INCREASES RISK",
-            "explanation": "Same device fingerprint linked to multiple applications in short period"
-        })
-    
-    if features["address_type"] in ["CMRA", "PO_BOX", "VACANT"]:
-        explanations.append({
-            "feature": "Address Type",
-            "value": features["address_type"],
-            "impact": "+98 points",
-            "direction": "INCREASES RISK",
-            "explanation": f"Address classified as {features['address_type']} (Commercial Mail Receiving Agency or high-risk type)"
-        })
-    
-    if features["synthetic_id_score"] > 0.6:
-        explanations.append({
-            "feature": "Synthetic Identity Score",
-            "value": f"{features['synthetic_id_score']:.0%}",
-            "impact": "+156 points",
-            "direction": "INCREASES RISK",
-            "explanation": "Composite score from ensemble model indicates high probability of synthetic identity"
-        })
-    
-    if features["application_velocity_14d"] > 2:
-        explanations.append({
-            "feature": "Application Velocity (14 days)",
-            "value": f"{features['application_velocity_14d']} applications",
-            "impact": "+78 points",
-            "direction": "INCREASES RISK",
-            "explanation": "Multiple credit applications submitted in short timeframe"
-        })
-    
-    if features["email_domain_age_days"] < 60:
-        explanations.append({
-            "feature": "Email Domain Age",
-            "value": f"{features['email_domain_age_days']} days",
-            "impact": "+45 points",
-            "direction": "INCREASES RISK",
-            "explanation": "Email address created very recently"
-        })
-    
-    if features["phone_type"] in ["VOIP", "PREPAID"]:
-        explanations.append({
-            "feature": "Phone Type",
-            "value": features["phone_type"],
-            "impact": "+62 points",
-            "direction": "INCREASES RISK",
-            "explanation": "Non-traditional phone type associated with higher fraud rates"
-        })
-    
-    # If low risk, show protective factors
-    if app["risk_level"] == "low":
-        explanations = [
-            {
-                "feature": "Established Credit History",
-                "value": "12+ years",
-                "impact": "-120 points",
-                "direction": "DECREASES RISK",
-                "explanation": "Long credit history consistent with SSN issue date"
-            },
-            {
-                "feature": "Stable Contact Information",
-                "value": "Verified",
-                "impact": "-85 points",
-                "direction": "DECREASES RISK",
-                "explanation": "Phone and address verified with multiple data sources"
-            },
-            {
-                "feature": "Low Application Velocity",
-                "value": "1 in 90 days",
-                "impact": "-45 points",
-                "direction": "DECREASES RISK",
-                "explanation": "Normal application pattern"
+def init_confluence():
+    """Initialize Confluence RAG with logging and metrics."""
+    global _confluence_rag
+
+    if _confluence_rag is None:
+        logger.info("Initializing Confluence integration...")
+
+        required_vars = ["CONFLUENCE_URL", "CONFLUENCE_EMAIL", "CONFLUENCE_API_TOKEN"]
+        missing_vars = [var for var in required_vars if not os.getenv(var)]
+
+        if missing_vars:
+            error_msg = f"Missing required environment variables: {', '.join(missing_vars)}"
+            logger.error(error_msg)
+            print(f"\n❌ ERROR: {error_msg}")
+            print("\n📝 Setup Instructions:")
+            print("   1. Copy .env.example to .env:")
+            print("      cp .env.example .env")
+            print("   2. Edit .env with your Confluence credentials")
+            print("   3. See CONFLUENCE_SETUP_GUIDE.md for detailed setup instructions")
+            print("\n⚠  App will run WITHOUT Confluence integration.\n")
+            raise ValueError(f"Missing Confluence credentials: {', '.join(missing_vars)}")
+
+        try:
+            _confluence_rag = ConfluenceRAG.from_env(
+                embedding_provider="huggingface",
+                vector_store_type="chroma",
+            )
+
+            spaces = {
+                "Acquisitio": 10,
             }
-        ]
-    
-    # Format output
-    output = f"""
-FRAUD SCORE EXPLANATION
-=======================
-Application ID: {application_id}
-Final Fraud Score: {app['fraud_score']} / 1000
-Model: XGBoost Fraud Ensemble v3.2
-
-TOP CONTRIBUTING FACTORS (ranked by impact):
---------------------------------------------
-"""
-    
-    for i, exp in enumerate(sorted(explanations, key=lambda x: abs(int(x["impact"].split()[0])), reverse=True), 1):
-        output += f"""
-{i}. {exp['feature']}
-   Value: {exp['value']}
-   Impact: {exp['impact']} ({exp['direction']})
-   → {exp['explanation']}
-"""
-    
-    return output
 
+            for space_key, max_pages in spaces.items():
+                try:
+                    logger.info(f"Ingesting Confluence space: {space_key}")
+                    stats = _confluence_rag.ingest_space(
+                        space_key, max_pages=max_pages, force=False
+                    )
+
+                    if stats.get("skipped"):
+                        logger.info(f"{space_key}: {stats['reason']}")
+                        print(f"   ✓ {space_key}: {stats['reason']}")
+                    else:
+                        logger.info(f"{space_key}: Ingested {stats['pages']} pages")
+                        print(f"   ✓ {space_key}: {stats['pages']} pages indexed")
+
+                    try:
+                        from confluence_ingestor import ConfluenceClient
+                        client = ConfluenceClient.from_env()
+                        pages = client.load_space(space_key, max_pages=max_pages)
+
+                        if pages:
+                            logger.info(f"Pages in {space_key} ({len(pages)} total):")
+                            print(f"   📄 Pages in {space_key}:")
+                            for i, page in enumerate(pages, 1):
+                                logger.info(f"      {i}. {page.title} (ID: {page.page_id})")
+                                print(f"      {i}. {page.title}")
+                        else:
+                            logger.warning(f"No pages found in space: {space_key}")
+                    except Exception as page_list_error:
+                        logger.warning(f"Could not retrieve page titles for {space_key}: {page_list_error}")
+
+                except Exception as e:
+                    logger.error(f"Failed to ingest {space_key}: {e}")
+                    print(f"   ⚠ {space_key}: Failed - {e}")
+                    _metrics.record_error()
+
+            _metrics.record_ingestion()
+            logger.info("Confluence integration ready!")
+            print("✅ Confluence integration ready!")
+
+        except Exception as e:
+            logger.error(f"Confluence initialization failed: {e}")
+            _metrics.record_error()
+            raise
+
+    return _confluence_rag
 
-@tool
-def compare_to_population(application_id: str, comparison_group: str = "approved") -> str:
-    """
-    Compare an application's features to the approved or denied population
-    to show how unusual the applicant's characteristics are.
-    
-    Args:
-        application_id: The unique identifier for the application
-        comparison_group: Either "approved" or "denied" population to compare against
-    
-    Returns:
-        Statistical comparison showing how the application differs from typical cases
-    """
-    app = generate_mock_application(application_id)
-    features = app["features"]
-    
-    # Mock population statistics
-    population_stats = {
-        "approved": {
-            "ssn_credit_mismatch_mean": 0.08,
-            "ssn_credit_mismatch_std": 0.12,
-            "device_velocity_mean": 1.2,
-            "device_velocity_std": 0.8,
-            "synthetic_score_mean": 0.15,
-            "synthetic_score_std": 0.10,
-            "app_velocity_mean": 0.5,
-            "app_velocity_std": 0.7,
-        },
-        "denied": {
-            "ssn_credit_mismatch_mean": 0.72,
-            "ssn_credit_mismatch_std": 0.18,
-            "device_velocity_mean": 6.5,
-            "device_velocity_std": 3.2,
-            "synthetic_score_mean": 0.78,
-            "synthetic_score_std": 0.15,
-            "app_velocity_mean": 4.2,
-            "app_velocity_std": 2.1,
-        }
-    }
-    
-    stats = population_stats.get(comparison_group, population_stats["approved"])
-    
-    def calc_z_score(value, mean, std):
-        if std == 0:
-            return 0
-        return (value - mean) / std
-    
-    comparisons = [
-        {
-            "feature": "SSN/Credit Age Mismatch",
-            "applicant_value": f"{features['ssn_issue_date_vs_credit_age_mismatch']:.0%}",
-            "population_mean": f"{stats['ssn_credit_mismatch_mean']:.0%}",
-            "z_score": calc_z_score(features['ssn_issue_date_vs_credit_age_mismatch'], 
-                                    stats['ssn_credit_mismatch_mean'], 
-                                    stats['ssn_credit_mismatch_std'])
-        },
-        {
-            "feature": "Device Velocity (30d)",
-            "applicant_value": str(features['device_velocity_30d']),
-            "population_mean": f"{stats['device_velocity_mean']:.1f}",
-            "z_score": calc_z_score(features['device_velocity_30d'], 
-                                    stats['device_velocity_mean'], 
-                                    stats['device_velocity_std'])
-        },
-        {
-            "feature": "Synthetic ID Score",
-            "applicant_value": f"{features['synthetic_id_score']:.0%}",
-            "population_mean": f"{stats['synthetic_score_mean']:.0%}",
-            "z_score": calc_z_score(features['synthetic_id_score'], 
-                                    stats['synthetic_score_mean'], 
-                                    stats['synthetic_score_std'])
-        },
-        {
-            "feature": "Application Velocity (14d)",
-            "applicant_value": str(features['application_velocity_14d']),
-            "population_mean": f"{stats['app_velocity_mean']:.1f}",
-            "z_score": calc_z_score(features['application_velocity_14d'], 
-                                    stats['app_velocity_mean'], 
-                                    stats['app_velocity_std'])
-        },
-    ]
-    
-    output = f"""
-POPULATION COMPARISON ANALYSIS
-==============================
-Application ID: {application_id}
-Comparison Group: {comparison_group.upper()} applications (last 12 months)
-Sample Size: {'847,293' if comparison_group == 'approved' else '23,847'} applications
-
-FEATURE COMPARISON:
--------------------
-{"Feature":<30} {"Applicant":<15} {"Population Mean":<18} {"Z-Score":<10} {"Assessment"}
-{"-"*95}
-"""
-    
-    for comp in comparisons:
-        z = comp["z_score"]
-        if abs(z) > 3:
-            assessment = "⚠️  EXTREME OUTLIER"
-        elif abs(z) > 2:
-            assessment = "🔶 SIGNIFICANT DEVIATION"
-        elif abs(z) > 1:
-            assessment = "🔷 MILD DEVIATION"
-        else:
-            assessment = "✅ WITHIN NORMAL"
-        
-        output += f"{comp['feature']:<30} {comp['applicant_value']:<15} {comp['population_mean']:<18} {z:>+.2f}σ      {assessment}\n"
-    
-    # Summary
-    extreme_count = sum(1 for c in comparisons if abs(c["z_score"]) > 2)
-    
-    output += f"""
-SUMMARY:
---------
-{extreme_count} of {len(comparisons)} features show significant deviation (|z| > 2σ) from {comparison_group} population.
-"""
-    
-    if extreme_count >= 2:
-        output += f"This application's profile is statistically unusual compared to typically {comparison_group} applications."
-    
-    return output
 
+# =============================================================================
+# SCHEDULED RE-INGESTION
+# =============================================================================
 
-@tool
-def check_fair_lending_flags(application_id: str) -> str:
-    """
-    Check for potential fair lending concerns in the fraud decision.
-    Reviews whether protected class proxies may have influenced the score
-    and provides compliance documentation.
-    
-    Args:
-        application_id: The unique identifier for the application
-    
-    Returns:
-        Fair lending compliance assessment and documentation
-    """
-    app = generate_mock_application(application_id)
-    
-    # Mock fair lending analysis
-    output = f"""
-FAIR LENDING COMPLIANCE REVIEW
-==============================
-Application ID: {application_id}
-Review Date: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
-Model: XGBoost Fraud Ensemble v3.2
-
-PROTECTED CLASS PROXY ANALYSIS:
--------------------------------
-The following features were analyzed for potential correlation with protected characteristics:
-
-✅ Geography-Based Features:
-   - ZIP code used only for velocity calculations, not scoring
-   - No direct geographic risk scoring applied
-   - Compliant with ECOA geographic restrictions
-
-✅ Name-Based Features:
-   - No name-based features used in fraud model
-   - Identity verification uses SSN/DOB only
-   
-✅ Age-Related Features:
-   - Credit age features measure account history, not applicant age
-   - SSN issuance analysis targets synthetic ID patterns, not age discrimination
-   - Model tested for age disparate impact: PASSED (adverse impact ratio: 0.94)
-
-⚠️  REVIEW ITEMS:
------------------
-"""
-    
-    if app["features"].get("phone_type") in ["VOIP", "PREPAID"]:
-        output += """
-• Phone Type Feature:
-  - VOIP/Prepaid flagged as risk factor
-  - Documented business justification: 73% of confirmed synthetic fraud uses VOIP
-  - Disparate impact testing: PASSED (ratio: 0.89)
-  - Alternative considered: None available with equivalent predictive power
-"""
-    
-    if app["features"].get("address_type") in ["CMRA", "PO_BOX"]:
-        output += """
-• Address Type Feature:
-  - CMRA/PO Box flagged as risk factor  
-  - Documented business justification: Required for synthetic ID detection
-  - Disparate impact testing: PASSED (ratio: 0.91)
-  - Accommodations: Manual review pathway available for legitimate CMRA users
-"""
-    
-    output += f"""
-MODEL VALIDATION STATUS:
-------------------------
-Last Disparate Impact Test: 2024-11-15
-Last Adverse Action Review: 2024-12-01
-Model Risk Rating: LOW
-SR 11-7 Compliance: COMPLIANT
-
-ADVERSE ACTION REASON CODES:
-----------------------------
-If this application is denied, the following reason codes apply:
-"""
-    
-    if app["decision"] == "FLAGGED":
-        reasons = [
-            "FA01 - Unable to verify identity information",
-            "FA03 - Inconsistent application information",
-            "FA07 - High-risk contact information patterns",
-        ]
-        for i, reason in enumerate(reasons, 1):
-            output += f"  {i}. {reason}\n"
-    else:
-        output += "  N/A - Application approved\n"
-    
-    output += """
-DOCUMENTATION:
---------------
-This analysis is auto-generated for compliance documentation.
-Full model documentation available in Model Risk Management system.
-Contact: model-governance@company.com
-"""
-    
-    return output
+def setup_scheduled_ingestion():
+    """Set up scheduled Confluence re-ingestion for keeping data fresh."""
+    try:
+        from apscheduler.schedulers.background import BackgroundScheduler
+    except ImportError:
+        logger.warning("apscheduler not installed. Scheduled ingestion disabled.")
+        logger.warning("Install with: pip install apscheduler")
+        return None
 
+    def refresh_confluence():
+        """Re-ingest Confluence spaces to pick up new content."""
+        logger.info("Starting scheduled Confluence re-ingestion...")
 
-@tool
-def get_identity_network(application_id: str) -> str:
-    """
-    Analyze the identity linkage network for an application, showing
-    connections to other applications via shared attributes (device,
-    phone, email, address, SSN patterns).
-    
-    Args:
-        application_id: The unique identifier for the application
-    
-    Returns:
-        Network analysis showing linked applications and risk patterns
-    """
-    app = generate_mock_application(application_id)
-    features = app["features"]
-    
-    linkage_count = features.get("identity_linkage_count", 0)
-    
-    output = f"""
-IDENTITY NETWORK ANALYSIS
-=========================
-Application ID: {application_id}
-Analysis Date: {datetime.now().strftime('%Y-%m-%d')}
-
-LINKAGE SUMMARY:
-----------------
-Total Linked Applications: {linkage_count}
-"""
-    
-    if linkage_count > 3:
-        # Generate mock linked applications for high-risk cases
-        random.seed(hash(application_id) % 2**32)
-        
-        link_types = {
-            "device_fingerprint": random.randint(2, min(linkage_count, 8)),
-            "phone_number": random.randint(1, min(linkage_count, 4)),
-            "email_pattern": random.randint(1, min(linkage_count, 3)),
-            "address": random.randint(1, min(linkage_count, 5)),
-        }
-        
-        output += f"""
-LINKAGE BREAKDOWN:
-------------------
-• Device Fingerprint Links: {link_types['device_fingerprint']} applications
-• Phone Number Links: {link_types['phone_number']} applications  
-• Email Pattern Links: {link_types['email_pattern']} applications
-• Address Links: {link_types['address']} applications
-
-LINKED APPLICATION DETAILS:
----------------------------
-"""
-        
-        statuses = ["CONFIRMED_FRAUD", "FLAGGED", "DENIED", "CHARGED_OFF", "APPROVED"]
-        weights = [0.3, 0.25, 0.2, 0.15, 0.1] if app["risk_level"] in ["high", "very_high"] else [0.05, 0.1, 0.15, 0.1, 0.6]
-        
-        for i in range(min(linkage_count, 6)):
-            linked_id = f"APP-{random.randint(10000, 99999)}"
-            link_type = random.choice(list(link_types.keys()))
-            status = random.choices(statuses, weights=weights)[0]
-            days_ago = random.randint(1, 180)
-            
-            status_emoji = {
-                "CONFIRMED_FRAUD": "🔴",
-                "FLAGGED": "🟠", 
-                "DENIED": "🟡",
-                "CHARGED_OFF": "🔴",
-                "APPROVED": "🟢"
-            }
-            
-            output += f"  {status_emoji.get(status, '⚪')} {linked_id} | {link_type.replace('_', ' ').title()} | {status} | {days_ago}d ago\n"
-        
-        # Risk assessment
-        fraud_links = sum(1 for _ in range(linkage_count) if random.random() < 0.4)
-        
-        output += f"""
-NETWORK RISK ASSESSMENT:
-------------------------
-• Confirmed Fraud in Network: {fraud_links} application(s)
-• Network Risk Score: {min(100, linkage_count * 12 + fraud_links * 25)}/100
-• Ring Pattern Detected: {"YES ⚠️" if linkage_count > 5 else "NO"}
-• Velocity Anomaly: {"YES ⚠️" if features.get('device_velocity_30d', 0) > 5 else "NO"}
-
-RECOMMENDATION:
----------------
-{"⚠️  HIGH-RISK NETWORK - Manual review recommended" if linkage_count > 5 else "🔶 ELEVATED RISK - Monitor for additional activity"}
-"""
-    
-    else:
-        output += """
-LINKAGE BREAKDOWN:
-------------------
-• Device Fingerprint Links: 0-1 applications
-• Phone Number Links: 0 applications
-• Email Pattern Links: 0 applications
-• Address Links: 1 application (same household likely)
-
-NETWORK RISK ASSESSMENT:
-------------------------
-• Network Risk Score: LOW
-• No suspicious patterns detected
-• Normal application profile
-
-✅ No concerning identity network patterns identified.
-"""
-    
-    return output
+        try:
+            rag = init_confluence()
+            spaces = ["Acquisitio"]
 
+            for space in spaces:
+                logger.info(f"Re-ingesting {space}...")
+                stats = rag.ingest_space(space, max_pages=100, force=True)
+                logger.info(f"{space}: Updated {stats['pages']} pages")
 
-@tool
-def get_model_performance(model_name: str = "xgboost_fraud_v3.2", portfolio: str = "all") -> str:
-    """
-    Retrieve current performance metrics for a fraud detection model,
-    including precision, recall, KS statistic, and financial impact.
-    
-    Args:
-        model_name: Name of the fraud model (default: xgboost_fraud_v3.2)
-        portfolio: Portfolio to filter by ("Retail Card", "Payment Solutions", "CareCredit", or "all")
-    
-    Returns:
-        Model performance metrics and trends
-    """
-    output = f"""
-MODEL PERFORMANCE DASHBOARD
-===========================
-Model: {model_name}
-Portfolio: {portfolio.upper()}
-Reporting Period: Last 30 Days
-Generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
-
-DETECTION METRICS:
-------------------
-                        Current     Prior Month     Δ Change
-Fraud Detection Rate:   87.3%       84.1%          +3.2% ✅
-Precision (PPV):        34.2%       31.8%          +2.4% ✅
-False Positive Rate:    2.1%        2.4%           -0.3% ✅
-KS Statistic:           0.72        0.69           +0.03 ✅
-Gini Coefficient:       0.81        0.78           +0.03 ✅
-AUC-ROC:                0.91        0.89           +0.02 ✅
-
-FINANCIAL IMPACT:
------------------
-                        Current     Prior Month     Δ Change
-Fraud Losses Prevented: $4.2M       $3.8M          +$400K ✅
-False Positive Cost:    $890K       $920K          -$30K  ✅
-Net Benefit:            $3.31M      $2.88M         +$430K ✅
-ROI:                    372%        317%           +55%   ✅
-
-VOLUME METRICS:
----------------
-Applications Scored:    1,247,832
-High-Risk Flags:        26,847 (2.15%)
-Manual Reviews:         8,421
-Confirmed Fraud:        9,182
-"""
-    
-    if portfolio != "all":
-        output += f"""
-PORTFOLIO BREAKDOWN ({portfolio}):
-{'='*40}
-Applications:           {random.randint(200000, 500000):,}
-Fraud Rate:             {random.uniform(0.5, 1.2):.2f}%
-Detection Rate:         {random.uniform(82, 92):.1f}%
-"""
-    
-    output += """
-MODEL HEALTH:
--------------
-✅ Feature Drift (PSI): 0.08 (threshold: 0.25)
-✅ Score Distribution: Stable
-✅ Latency P99: 45ms (SLA: 100ms)
-⚠️  Challenger Model: +2.1% lift in shadow mode - review scheduled
-
-TREND ALERT:
-------------
-📈 Synthetic ID fraud attempts up 23% MoM - model adapting well
-📉 First-party fraud stable at historical levels
-"""
-    
-    return output
+            _metrics.record_ingestion()
+            logger.info("Scheduled re-ingestion completed successfully")
+
+        except Exception as e:
+            logger.error(f"Scheduled re-ingestion failed: {e}")
+            _metrics.record_error()
+
+    scheduler = BackgroundScheduler()
+    scheduler.add_job(refresh_confluence, 'cron', hour=2)
+    scheduler.start()
+
+    logger.info("Scheduled re-ingestion enabled (runs daily at 2 AM)")
+    return scheduler
 
 
 # =============================================================================
-# SYSTEM PROMPT
+# ENHANCED SYSTEM PROMPT
 # =============================================================================
 
-SYSTEM_PROMPT = """
+ENHANCED_PROMPT = """
 You are a Fraud Model Explainability Assistant for a major financial services company.
-Your role is to help fraud analysts, data scientists, and executives understand 
+Your role is to help fraud analysts, data scientists, and executives understand
 fraud model decisions and their implications.
 
 You have access to tools that can:
@@ -676,6 +289,8 @@ You have access to tools that can:
 4. Check for fair lending compliance concerns
 5. Analyze identity networks and linkages
 6. Show model performance metrics
+7. **Search company Confluence documentation** for policies, procedures, and guidelines
+8. **Load full Confluence pages** to extract specific information
 
 When answering questions:
 - Be precise and data-driven
@@ -684,12 +299,19 @@ When answering questions:
 - Always mention fair lending implications when relevant
 - Provide actionable insights, not just data
 
+**CRITICAL: How to Handle Confluence Information Requests**
+When users ask you to "report", "list", "find", "show", or "provide" specific information from documents:
+1. **FIRST**: Use the confluence_search tool to find the relevant document and identify its title
+2. **SECOND**: Use the confluence_loader tool with BOTH space_key AND page_title parameters to load that specific page
+3. **THIRD**: Extract and present the requested information directly in your response from the loaded content
+4. **FOURTH**: Provide the Confluence page citation/link as a reference for verification
+
 For flagged applications, structure your response as:
 1. Quick summary (score, decision, risk level)
 2. Top contributing factors
 3. How unusual this is compared to the population
-4. Any compliance considerations
-5. Recommended next steps
+4. Any compliance considerations (extract relevant policies from Confluence, then cite sources)
+5. Recommended next steps (reference procedures from playbooks if available)
 
 Remember: Your explanations may be used in regulatory examinations and audits,
 so be accurate and thorough.
@@ -697,135 +319,607 @@ so be accurate and thorough.
 
 
 # =============================================================================
-# AGENT SETUP
+# AGENT CREATION
 # =============================================================================
 
-def create_agent():
-    """Create and configure the Strands fraud explainability agent."""
-    openai_api_key = os.environ.get('OPENAI_API_KEY')
+_cached_agent = None
+
+
+def create_enhanced_agent():
+    """Create fraud agent with Confluence integration."""
+    global _cached_agent
     
-    tools = [
-        get_application_summary,
-        explain_fraud_score,
-        compare_to_population,
-        check_fair_lending_flags,
-        get_identity_network,
-        get_model_performance,
-    ]
+    if _cached_agent is not None:
+        return _cached_agent
     
+    openai_api_key = os.environ.get("OPENAI_API_KEY")
+
+    try:
+        rag = init_confluence()
+
+        search_confluence = create_confluence_search_tool(rag=rag, k=5)
+        load_confluence_page = create_confluence_loader_tool(max_pages=10)
+
+        tools = [
+            get_application_summary,
+            explain_fraud_score,
+            compare_to_population,
+            check_fair_lending_flags,
+            get_identity_network,
+            get_model_performance,
+            search_confluence,
+            load_confluence_page,
+        ]
+
+        system_prompt = ENHANCED_PROMPT
+
+    except Exception as e:
+        logger.error(f"Confluence initialization failed: {e}")
+        print(f"⚠ Confluence disabled: {e}")
+        _metrics.record_error()
+
+        tools = [
+            get_application_summary,
+            explain_fraud_score,
+            compare_to_population,
+            check_fair_lending_flags,
+            get_identity_network,
+            get_model_performance,
+        ]
+
+        system_prompt = ORIGINAL_PROMPT
+
     if openai_api_key:
         model = OpenAIModel(
             client_args={"api_key": openai_api_key},
             model_id="gpt-4o",
-            params={"temperature": 0.1, "max_tokens": 2048}
+            params={"temperature": 0.1, "max_tokens": 2048},
         )
-        return Agent(model=model, system_prompt=SYSTEM_PROMPT, tools=tools)
+        _cached_agent = Agent(model=model, system_prompt=system_prompt, tools=tools)
     else:
-        # Default to Bedrock
-        return Agent(system_prompt=SYSTEM_PROMPT, tools=tools)
+        _cached_agent = Agent(system_prompt=system_prompt, tools=tools)
+    
+    return _cached_agent
 
 
-def query(question: str) -> str:
-    """Process a question using the fraud explainability agent."""
+def query_agent(question: str) -> str:
+    """Process question with the enhanced agent."""
     try:
-        agent = create_agent()
+        logger.info(f"Processing query: {question}")
+        agent = create_enhanced_agent()
         result = agent(question)
+        logger.info("Query completed successfully")
         return str(result)
     except Exception as e:
-        return f"Error processing question: {str(e)}"
+        logger.error(f"Query failed: {e}")
+        _metrics.record_error()
+        return f"Error: {str(e)}"
 
 
 # =============================================================================
-# GRADIO INTERFACE
+# FASTAPI APPLICATION
 # =============================================================================
 
-def process_question(question: str) -> str:
-    """Wrapper for Gradio interface."""
-    return query(question)
+app = FastAPI(title="Fraud Model Explainability Assistant")
 
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+    allow_credentials=True,
+)
 
-# Create the interface (Gradio 6.0 compatible)
-with gr.Blocks(title="Fraud Model Explainability Assistant") as iface:
-    gr.Markdown("""
-    # 🔍 Fraud Model Explainability Assistant
-    
-    An AI-powered assistant that helps you understand fraud model decisions, 
-    investigate flagged applications, and ensure fair lending compliance.
-    
-    **Capabilities:**
-    - Explain why applications were flagged (SHAP-style feature attribution)
-    - Compare applications to approved/denied populations
-    - Analyze identity networks and linkages
-    - Check fair lending compliance
-    - Review model performance metrics
-    """)
-    
-    with gr.Row():
-        with gr.Column(scale=2):
-            question_input = gr.Textbox(
-                label="Ask a Question",
-                placeholder="e.g., Why was application APP-12345 flagged as high risk?",
-                lines=3
-            )
-            submit_btn = gr.Button("🔍 Analyze", variant="primary")
-        
-    with gr.Row():
-        output = gr.Textbox(
-            label="Analysis Results",
-            lines=25
+
+class QuestionRequest(BaseModel):
+    question: str
+
+
+class AnswerResponse(BaseModel):
+    answer: str
+    metrics: dict
+
+
+@app.get("/")
+async def index():
+    """Serve the main UI."""
+    return HTMLResponse(content=get_ui_html())
+
+
+@app.post("/api/ask", response_model=AnswerResponse)
+async def ask_question(request: QuestionRequest):
+    """Process a question and return the answer."""
+    try:
+        answer = query_agent(request.question)
+        return AnswerResponse(
+            answer=answer,
+            metrics=_metrics.get_stats()
         )
+    except Exception as e:
+        logger.error(f"API error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/metrics")
+async def get_metrics():
+    """Get current performance metrics."""
+    return _metrics.get_stats()
+
+
+@app.get("/api/health")
+async def health_check():
+    """Health check endpoint."""
+    return {
+        "status": "healthy",
+        "confluence_initialized": _confluence_rag is not None,
+        "metrics": _metrics.get_stats()
+    }
+
+
+# =============================================================================
+# HTML UI
+# =============================================================================
+
+def get_ui_html() -> str:
+    """Generate the chat UI HTML."""
+    
+    example_questions = [
+        "Why was application APP-78432 flagged as high risk?",
+        "Explain the fraud score for APP-12345 and compare it to approved applications",
+        "Check fair lending compliance for APP-55555 and cite relevant policies",
+        "Show me the identity network analysis for APP-78432",
+        "What's the current model performance for the Retail Card portfolio?",
+        "What does our fair lending policy say about synthetic ID detection?",
+        "Find the model validation report for XGBoost v3.2",
+        "What are the procedures for escalating high-risk applications?",
+    ]
     
-    gr.Markdown("### 💡 Example Questions")
-    
-    examples = gr.Examples(
-        examples=[
-            ["Why was application APP-78432 flagged as high risk?"],
-            ["Explain the fraud score for APP-12345 and compare it to approved applications"],
-            ["Check fair lending compliance for application APP-55555"],
-            ["Show me the identity network analysis for APP-78432"],
-            ["What's the current model performance for the Retail Card portfolio?"],
-            ["I need to present APP-99999 to the CCO. Give me a complete risk summary with compliance review."],
-            ["Compare APP-12345 to the denied population and explain if this looks like synthetic ID fraud"],
-        ],
-        inputs=question_input
-    )
-    
-    submit_btn.click(fn=process_question, inputs=question_input, outputs=output)
-    question_input.submit(fn=process_question, inputs=question_input, outputs=output)
-    
-    gr.Markdown("""
-    ---
-    *Powered by Amazon Strands Agents SDK | Demo with synthetic data*
+    examples_json = json.dumps(example_questions)
     
-    **Note:** This demo uses mock data. In production, tools would connect to:
-    - Feature Store / Data Warehouse
-    - Model Serving Infrastructure  
-    - SHAP/Model Interpretation Services
-    - Compliance Documentation Systems
-    """)
+    return f"""
+    <!DOCTYPE html>
+    <html lang="en">
+    <head>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <title>Fraud Model Explainability Assistant</title>
+        <style>
+            * {{
+                box-sizing: border-box;
+                margin: 0;
+                padding: 0;
+            }}
+            
+            body {{
+                font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
+                background: linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%);
+                min-height: 100vh;
+                color: #e0e0e0;
+            }}
+            
+            .container {{
+                max-width: 1200px;
+                margin: 0 auto;
+                padding: 20px;
+            }}
+            
+            header {{
+                text-align: center;
+                padding: 30px 0;
+                border-bottom: 1px solid rgba(255,255,255,0.1);
+                margin-bottom: 30px;
+            }}
+            
+            h1 {{
+                font-size: 2.5rem;
+                background: linear-gradient(90deg, #00d4ff, #7b2cbf);
+                -webkit-background-clip: text;
+                -webkit-text-fill-color: transparent;
+                background-clip: text;
+                margin-bottom: 10px;
+            }}
+            
+            .subtitle {{
+                color: #888;
+                font-size: 1.1rem;
+            }}
+            
+            .main-content {{
+                display: grid;
+                grid-template-columns: 1fr 300px;
+                gap: 30px;
+            }}
+            
+            @media (max-width: 900px) {{
+                .main-content {{
+                    grid-template-columns: 1fr;
+                }}
+            }}
+            
+            .chat-section {{
+                background: rgba(255,255,255,0.05);
+                border-radius: 16px;
+                padding: 20px;
+                backdrop-filter: blur(10px);
+                border: 1px solid rgba(255,255,255,0.1);
+            }}
+            
+            .input-area {{
+                display: flex;
+                gap: 10px;
+                margin-bottom: 20px;
+            }}
+            
+            textarea {{
+                flex: 1;
+                padding: 15px;
+                border: 2px solid rgba(255,255,255,0.1);
+                border-radius: 12px;
+                background: rgba(0,0,0,0.3);
+                color: #fff;
+                font-size: 1rem;
+                resize: vertical;
+                min-height: 80px;
+                transition: border-color 0.3s;
+            }}
+            
+            textarea:focus {{
+                outline: none;
+                border-color: #00d4ff;
+            }}
+            
+            button {{
+                padding: 15px 30px;
+                background: linear-gradient(135deg, #00d4ff, #7b2cbf);
+                color: white;
+                border: none;
+                border-radius: 12px;
+                font-size: 1rem;
+                font-weight: 600;
+                cursor: pointer;
+                transition: transform 0.2s, box-shadow 0.2s;
+            }}
+            
+            button:hover:not(:disabled) {{
+                transform: translateY(-2px);
+                box-shadow: 0 10px 30px rgba(0,212,255,0.3);
+            }}
+            
+            button:disabled {{
+                opacity: 0.5;
+                cursor: not-allowed;
+            }}
+            
+            .response-area {{
+                background: rgba(0,0,0,0.3);
+                border-radius: 12px;
+                padding: 20px;
+                min-height: 400px;
+                max-height: 600px;
+                overflow-y: auto;
+            }}
+            
+            .response-area pre {{
+                white-space: pre-wrap;
+                word-wrap: break-word;
+                font-family: 'Fira Code', 'Consolas', monospace;
+                font-size: 0.9rem;
+                line-height: 1.6;
+            }}
+            
+            .loading {{
+                display: flex;
+                align-items: center;
+                justify-content: center;
+                gap: 10px;
+                padding: 40px;
+                color: #00d4ff;
+            }}
+            
+            .spinner {{
+                width: 24px;
+                height: 24px;
+                border: 3px solid rgba(0,212,255,0.2);
+                border-top-color: #00d4ff;
+                border-radius: 50%;
+                animation: spin 1s linear infinite;
+            }}
+            
+            @keyframes spin {{
+                to {{ transform: rotate(360deg); }}
+            }}
+            
+            .sidebar {{
+                display: flex;
+                flex-direction: column;
+                gap: 20px;
+            }}
+            
+            .card {{
+                background: rgba(255,255,255,0.05);
+                border-radius: 12px;
+                padding: 20px;
+                border: 1px solid rgba(255,255,255,0.1);
+            }}
+            
+            .card h3 {{
+                color: #00d4ff;
+                margin-bottom: 15px;
+                font-size: 1rem;
+            }}
+            
+            .example-btn {{
+                display: block;
+                width: 100%;
+                padding: 10px;
+                margin-bottom: 8px;
+                background: rgba(0,0,0,0.3);
+                color: #ccc;
+                border: 1px solid rgba(255,255,255,0.1);
+                border-radius: 8px;
+                font-size: 0.85rem;
+                text-align: left;
+                cursor: pointer;
+                transition: all 0.2s;
+            }}
+            
+            .example-btn:hover {{
+                background: rgba(0,212,255,0.1);
+                border-color: #00d4ff;
+                color: #fff;
+            }}
+            
+            .metrics {{
+                display: grid;
+                grid-template-columns: 1fr 1fr;
+                gap: 10px;
+            }}
+            
+            .metric {{
+                background: rgba(0,0,0,0.3);
+                padding: 12px;
+                border-radius: 8px;
+                text-align: center;
+            }}
+            
+            .metric-value {{
+                font-size: 1.5rem;
+                font-weight: bold;
+                color: #00d4ff;
+            }}
+            
+            .metric-label {{
+                font-size: 0.75rem;
+                color: #888;
+                margin-top: 4px;
+            }}
+            
+            .features {{
+                list-style: none;
+            }}
+            
+            .features li {{
+                padding: 8px 0;
+                border-bottom: 1px solid rgba(255,255,255,0.05);
+                font-size: 0.9rem;
+            }}
+            
+            .features li:last-child {{
+                border-bottom: none;
+            }}
+            
+            .features li::before {{
+                content: "✓ ";
+                color: #00d4ff;
+            }}
+            
+            footer {{
+                text-align: center;
+                padding: 30px;
+                color: #666;
+                font-size: 0.9rem;
+                margin-top: 40px;
+            }}
+        </style>
+    </head>
+    <body>
+        <div class="container">
+            <header>
+                <h1>🔍 Fraud Model Explainability Assistant</h1>
+                <p class="subtitle">Production-Ready with Confluence Integration</p>
+            </header>
+            
+            <div class="main-content">
+                <div class="chat-section">
+                    <div class="input-area">
+                        <textarea 
+                            id="questionInput" 
+                            placeholder="Ask a question about fraud models, applications, or policies..."
+                            onkeydown="if(event.key === 'Enter' && !event.shiftKey) {{ event.preventDefault(); askQuestion(); }}"
+                        ></textarea>
+                        <button id="askBtn" onclick="askQuestion()">🔍 Analyze</button>
+                    </div>
+                    
+                    <div class="response-area" id="responseArea">
+                        <pre id="responseText">Welcome! Ask me about:
+                        
+• Application fraud scores and explanations
+• Fair lending compliance checks
+• Identity network analysis
+• Model performance metrics
+• Confluence documentation and policies
+
+Enter your question above and click "Analyze" to get started.</pre>
+                    </div>
+                </div>
+                
+                <div class="sidebar">
+                    <div class="card">
+                        <h3>📊 Performance Metrics</h3>
+                        <div class="metrics">
+                            <div class="metric">
+                                <div class="metric-value" id="totalSearches">0</div>
+                                <div class="metric-label">Searches</div>
+                            </div>
+                            <div class="metric">
+                                <div class="metric-value" id="cacheRate">0%</div>
+                                <div class="metric-label">Cache Rate</div>
+                            </div>
+                            <div class="metric">
+                                <div class="metric-value" id="avgTime">0s</div>
+                                <div class="metric-label">Avg Time</div>
+                            </div>
+                            <div class="metric">
+                                <div class="metric-value" id="errors">0</div>
+                                <div class="metric-label">Errors</div>
+                            </div>
+                        </div>
+                    </div>
+                    
+                    <div class="card">
+                        <h3>💡 Example Questions</h3>
+                        <div id="examplesContainer"></div>
+                    </div>
+                    
+                    <div class="card">
+                        <h3>✨ Production Features</h3>
+                        <ul class="features">
+                            <li>Structured logging</li>
+                            <li>Performance tracking</li>
+                            <li>Error monitoring</li>
+                            <li>Daily auto-refresh (2 AM)</li>
+                            <li>Confluence integration</li>
+                        </ul>
+                    </div>
+                </div>
+            </div>
+            
+            <footer>
+                Powered by Strands Agents + Confluence Integration • FastAPI Backend
+            </footer>
+        </div>
+        
+        <script>
+            const examples = {examples_json};
+            
+            // Populate examples
+            const examplesContainer = document.getElementById('examplesContainer');
+            examples.slice(0, 5).forEach(q => {{
+                const btn = document.createElement('button');
+                btn.className = 'example-btn';
+                btn.textContent = q.length > 50 ? q.substring(0, 50) + '...' : q;
+                btn.title = q;
+                btn.onclick = () => {{
+                    document.getElementById('questionInput').value = q;
+                    askQuestion();
+                }};
+                examplesContainer.appendChild(btn);
+            }});
+            
+            async function askQuestion() {{
+                const input = document.getElementById('questionInput');
+                const btn = document.getElementById('askBtn');
+                const responseArea = document.getElementById('responseArea');
+                const responseText = document.getElementById('responseText');
+                
+                const question = input.value.trim();
+                if (!question) return;
+                
+                btn.disabled = true;
+                btn.textContent = '⏳ Processing...';
+                responseArea.innerHTML = '<div class="loading"><div class="spinner"></div>Analyzing your question...</div>';
+                
+                try {{
+                    const response = await fetch('/api/ask', {{
+                        method: 'POST',
+                        headers: {{
+                            'Content-Type': 'application/json',
+                        }},
+                        body: JSON.stringify({{ question }}),
+                    }});
+                    
+                    if (!response.ok) {{
+                        throw new Error(`HTTP error! status: ${{response.status}}`);
+                    }}
+                    
+                    const data = await response.json();
+                    
+                    responseArea.innerHTML = '<pre id="responseText"></pre>';
+                    document.getElementById('responseText').textContent = data.answer;
+                    
+                    // Update metrics
+                    if (data.metrics) {{
+                        document.getElementById('totalSearches').textContent = data.metrics.total_searches || 0;
+                        document.getElementById('cacheRate').textContent = 
+                            ((data.metrics.cache_hit_rate || 0) * 100).toFixed(0) + '%';
+                        document.getElementById('avgTime').textContent = 
+                            (data.metrics.avg_query_time || 0).toFixed(2) + 's';
+                        document.getElementById('errors').textContent = data.metrics.errors || 0;
+                    }}
+                    
+                }} catch (error) {{
+                    responseArea.innerHTML = '<pre id="responseText" style="color: #ff6b6b;"></pre>';
+                    document.getElementById('responseText').textContent = 'Error: ' + error.message;
+                }} finally {{
+                    btn.disabled = false;
+                    btn.textContent = '🔍 Analyze';
+                }}
+            }}
+            
+            // Fetch initial metrics
+            async function fetchMetrics() {{
+                try {{
+                    const response = await fetch('/api/metrics');
+                    const metrics = await response.json();
+                    document.getElementById('totalSearches').textContent = metrics.total_searches || 0;
+                    document.getElementById('cacheRate').textContent = 
+                        ((metrics.cache_hit_rate || 0) * 100).toFixed(0) + '%';
+                    document.getElementById('avgTime').textContent = 
+                        (metrics.avg_query_time || 0).toFixed(2) + 's';
+                    document.getElementById('errors').textContent = metrics.errors || 0;
+                }} catch (e) {{
+                    console.log('Could not fetch metrics:', e);
+                }}
+            }}
+            
+            fetchMetrics();
+            setInterval(fetchMetrics, 30000);
+        </script>
+    </body>
+    </html>
+    """
 
 
 # =============================================================================
-# MAIN
+# MAIN ENTRYPOINT
 # =============================================================================
 
 if __name__ == "__main__":
-    import sys
-    
-    if "--demo" in sys.argv:
-        print("\n" + "="*70)
-        print("FRAUD MODEL EXPLAINABILITY ASSISTANT - DEMO")
-        print("="*70 + "\n")
-        
-        test_questions = [
-            "Why was application APP-78432 flagged as high risk?",
-            "What's the model performance for Retail Card?",
-        ]
-        
-        for q in test_questions:
-            print(f"Question: {q}")
-            print("-" * 50)
-            print(query(q))
-            print("\n")
-    else:
-        iface.launch(ssr_mode=False)
+    import uvicorn
+
+    # Pre-initialize Confluence
+    try:
+        init_confluence()
+    except Exception as e:
+        logger.error(f"Confluence initialization failed: {e}")
+        print(f"Warning: Confluence initialization failed: {e}")
+        print("App will run without Confluence integration.")
+
+    # Set up scheduled re-ingestion
+    scheduler = setup_scheduled_ingestion()
+
+    # Launch FastAPI with uvicorn
+    logger.info("Launching FastAPI server...")
+    print("\n" + "=" * 60)
+    print("Fraud Model Explainability Assistant")
+    print("  - FastAPI backend on port 7860")
+    print("  - Confluence integration enabled")
+    print("  - Scheduled refresh at 2 AM daily")
+    print("=" * 60 + "\n")
+
+    uvicorn.run(
+        app,
+        host="0.0.0.0",
+        port=7860,
+        reload=False
+    )

app_with_confluence.py

@@ -1,925 +0,0 @@
-#!/usr/bin/env python
-"""
-Fraud Model Explainability Assistant - Strands Agents
-An AI-powered assistant that helps fraud analysts and executives understand
-why specific applications were flagged as fraudulent, translating complex
-model outputs into actionable insights.
-
-Author: Fraud Model Data Science Team
-
-Use Cases:
-- Executive briefings on fraud decisions
-- Fair lending compliance documentation
-- Analyst investigation support
-- Model decision audit trails
-
-Production-Ready Confluence Integration (FastAPI Version)
-
-Features:
-- Comprehensive logging and monitoring
-- Error handling and recovery
-- Scheduled re-ingestion for keeping data fresh
-- Performance metrics tracking
-- FastAPI + uvicorn for Docker deployment
-
-Prerequisites:
-    - Configure .env with Confluence credentials
-"""
-
-import os
-import sys
-import json
-import warnings
-import logging
-import time
-from functools import lru_cache
-from typing import Optional
-from datetime import datetime
-
-# Suppress ResourceWarning for cleaner output
-warnings.filterwarnings("ignore", category=ResourceWarning)
-os.environ["PYTHONWARNINGS"] = "ignore::ResourceWarning"
-
-# Load environment variables from .env file
-try:
-    from dotenv import load_dotenv
-    load_dotenv()
-except ImportError:
-    print("⚠ Warning: python-dotenv not installed. Install with: pip install python-dotenv")
-    print("   Environment variables must be set manually.")
-
-from fastapi import FastAPI, HTTPException
-from fastapi.responses import HTMLResponse
-from fastapi.middleware.cors import CORSMiddleware
-from pydantic import BaseModel
-
-from strands import Agent
-from strands.models.openai import OpenAIModel
-
-# Import confluence-ingestor
-from confluence_ingestor import ConfluenceRAG
-from confluence_ingestor.adapters.strands import (
-    create_confluence_search_tool,
-    create_confluence_loader_tool,
-)
-
-# Import your existing fraud tools
-from app import (
-    get_application_summary,
-    explain_fraud_score,
-    compare_to_population,
-    check_fair_lending_flags,
-    get_identity_network,
-    get_model_performance,
-    SYSTEM_PROMPT as ORIGINAL_PROMPT,
-)
-
-
-# =============================================================================
-# LOGGING CONFIGURATION
-# =============================================================================
-
-logging.basicConfig(
-    level=logging.INFO,
-    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-    handlers=[
-        logging.FileHandler('fraud_assistant_confluence.log'),
-        logging.StreamHandler()
-    ]
-)
-
-logger = logging.getLogger(__name__)
-
-
-# =============================================================================
-# METRICS TRACKING
-# =============================================================================
-
-class ConfluenceMetrics:
-    """Track Confluence integration performance metrics."""
-
-    def __init__(self):
-        self.search_count = 0
-        self.cache_hits = 0
-        self.cache_misses = 0
-        self.errors = 0
-        self.last_ingestion = None
-        self.query_times = []
-
-    def record_search(self, cached: bool = False, duration: float = 0.0):
-        """Record a search query."""
-        self.search_count += 1
-        if cached:
-            self.cache_hits += 1
-        else:
-            self.cache_misses += 1
-        self.query_times.append(duration)
-
-    def record_error(self):
-        """Record an error."""
-        self.errors += 1
-
-    def record_ingestion(self):
-        """Record a data ingestion."""
-        self.last_ingestion = datetime.now()
-
-    def get_stats(self) -> dict:
-        """Get current metrics."""
-        return {
-            "total_searches": self.search_count,
-            "cache_hit_rate": (
-                self.cache_hits / self.search_count
-                if self.search_count > 0
-                else 0.0
-            ),
-            "avg_query_time": (
-                sum(self.query_times) / len(self.query_times)
-                if self.query_times
-                else 0.0
-            ),
-            "errors": self.errors,
-            "last_ingestion": str(self.last_ingestion) if self.last_ingestion else None,
-        }
-
-
-# Global metrics instance
-_metrics = ConfluenceMetrics()
-
-
-# =============================================================================
-# CONFLUENCE INITIALIZATION
-# =============================================================================
-
-_confluence_rag: Optional[ConfluenceRAG] = None
-
-
-def init_confluence():
-    """Initialize Confluence RAG with logging and metrics."""
-    global _confluence_rag
-
-    if _confluence_rag is None:
-        logger.info("Initializing Confluence integration...")
-
-        required_vars = ["CONFLUENCE_URL", "CONFLUENCE_EMAIL", "CONFLUENCE_API_TOKEN"]
-        missing_vars = [var for var in required_vars if not os.getenv(var)]
-
-        if missing_vars:
-            error_msg = f"Missing required environment variables: {', '.join(missing_vars)}"
-            logger.error(error_msg)
-            print(f"\n❌ ERROR: {error_msg}")
-            print("\n📝 Setup Instructions:")
-            print("   1. Copy .env.example to .env:")
-            print("      cp .env.example .env")
-            print("   2. Edit .env with your Confluence credentials")
-            print("   3. See CONFLUENCE_SETUP_GUIDE.md for detailed setup instructions")
-            print("\n⚠  App will run WITHOUT Confluence integration.\n")
-            raise ValueError(f"Missing Confluence credentials: {', '.join(missing_vars)}")
-
-        try:
-            _confluence_rag = ConfluenceRAG.from_env(
-                embedding_provider="huggingface",
-                vector_store_type="chroma",
-            )
-
-            spaces = {
-                "Acquisitio": 10,
-            }
-
-            for space_key, max_pages in spaces.items():
-                try:
-                    logger.info(f"Ingesting Confluence space: {space_key}")
-                    stats = _confluence_rag.ingest_space(
-                        space_key, max_pages=max_pages, force=False
-                    )
-
-                    if stats.get("skipped"):
-                        logger.info(f"{space_key}: {stats['reason']}")
-                        print(f"   ✓ {space_key}: {stats['reason']}")
-                    else:
-                        logger.info(f"{space_key}: Ingested {stats['pages']} pages")
-                        print(f"   ✓ {space_key}: {stats['pages']} pages indexed")
-
-                    try:
-                        from confluence_ingestor import ConfluenceClient
-                        client = ConfluenceClient.from_env()
-                        pages = client.load_space(space_key, max_pages=max_pages)
-
-                        if pages:
-                            logger.info(f"Pages in {space_key} ({len(pages)} total):")
-                            print(f"   📄 Pages in {space_key}:")
-                            for i, page in enumerate(pages, 1):
-                                logger.info(f"      {i}. {page.title} (ID: {page.page_id})")
-                                print(f"      {i}. {page.title}")
-                        else:
-                            logger.warning(f"No pages found in space: {space_key}")
-                    except Exception as page_list_error:
-                        logger.warning(f"Could not retrieve page titles for {space_key}: {page_list_error}")
-
-                except Exception as e:
-                    logger.error(f"Failed to ingest {space_key}: {e}")
-                    print(f"   ⚠ {space_key}: Failed - {e}")
-                    _metrics.record_error()
-
-            _metrics.record_ingestion()
-            logger.info("Confluence integration ready!")
-            print("✅ Confluence integration ready!")
-
-        except Exception as e:
-            logger.error(f"Confluence initialization failed: {e}")
-            _metrics.record_error()
-            raise
-
-    return _confluence_rag
-
-
-# =============================================================================
-# SCHEDULED RE-INGESTION
-# =============================================================================
-
-def setup_scheduled_ingestion():
-    """Set up scheduled Confluence re-ingestion for keeping data fresh."""
-    try:
-        from apscheduler.schedulers.background import BackgroundScheduler
-    except ImportError:
-        logger.warning("apscheduler not installed. Scheduled ingestion disabled.")
-        logger.warning("Install with: pip install apscheduler")
-        return None
-
-    def refresh_confluence():
-        """Re-ingest Confluence spaces to pick up new content."""
-        logger.info("Starting scheduled Confluence re-ingestion...")
-
-        try:
-            rag = init_confluence()
-            spaces = ["Acquisitio"]
-
-            for space in spaces:
-                logger.info(f"Re-ingesting {space}...")
-                stats = rag.ingest_space(space, max_pages=100, force=True)
-                logger.info(f"{space}: Updated {stats['pages']} pages")
-
-            _metrics.record_ingestion()
-            logger.info("Scheduled re-ingestion completed successfully")
-
-        except Exception as e:
-            logger.error(f"Scheduled re-ingestion failed: {e}")
-            _metrics.record_error()
-
-    scheduler = BackgroundScheduler()
-    scheduler.add_job(refresh_confluence, 'cron', hour=2)
-    scheduler.start()
-
-    logger.info("Scheduled re-ingestion enabled (runs daily at 2 AM)")
-    return scheduler
-
-
-# =============================================================================
-# ENHANCED SYSTEM PROMPT
-# =============================================================================
-
-ENHANCED_PROMPT = """
-You are a Fraud Model Explainability Assistant for a major financial services company.
-Your role is to help fraud analysts, data scientists, and executives understand
-fraud model decisions and their implications.
-
-You have access to tools that can:
-1. Retrieve application summaries and fraud scores
-2. Explain why applications received specific fraud scores (SHAP-style explanations)
-3. Compare applications to approved/denied populations statistically
-4. Check for fair lending compliance concerns
-5. Analyze identity networks and linkages
-6. Show model performance metrics
-7. **Search company Confluence documentation** for policies, procedures, and guidelines
-8. **Load full Confluence pages** to extract specific information
-
-When answering questions:
-- Be precise and data-driven
-- Highlight the most important risk factors first
-- Explain technical concepts in business terms when speaking to executives
-- Always mention fair lending implications when relevant
-- Provide actionable insights, not just data
-
-**CRITICAL: How to Handle Confluence Information Requests**
-When users ask you to "report", "list", "find", "show", or "provide" specific information from documents:
-1. **FIRST**: Use the confluence_search tool to find the relevant document and identify its title
-2. **SECOND**: Use the confluence_loader tool with BOTH space_key AND page_title parameters to load that specific page
-3. **THIRD**: Extract and present the requested information directly in your response from the loaded content
-4. **FOURTH**: Provide the Confluence page citation/link as a reference for verification
-
-For flagged applications, structure your response as:
-1. Quick summary (score, decision, risk level)
-2. Top contributing factors
-3. How unusual this is compared to the population
-4. Any compliance considerations (extract relevant policies from Confluence, then cite sources)
-5. Recommended next steps (reference procedures from playbooks if available)
-
-Remember: Your explanations may be used in regulatory examinations and audits,
-so be accurate and thorough.
-""".strip()
-
-
-# =============================================================================
-# AGENT CREATION
-# =============================================================================
-
-_cached_agent = None
-
-
-def create_enhanced_agent():
-    """Create fraud agent with Confluence integration."""
-    global _cached_agent
-    
-    if _cached_agent is not None:
-        return _cached_agent
-    
-    openai_api_key = os.environ.get("OPENAI_API_KEY")
-
-    try:
-        rag = init_confluence()
-
-        search_confluence = create_confluence_search_tool(rag=rag, k=5)
-        load_confluence_page = create_confluence_loader_tool(max_pages=10)
-
-        tools = [
-            get_application_summary,
-            explain_fraud_score,
-            compare_to_population,
-            check_fair_lending_flags,
-            get_identity_network,
-            get_model_performance,
-            search_confluence,
-            load_confluence_page,
-        ]
-
-        system_prompt = ENHANCED_PROMPT
-
-    except Exception as e:
-        logger.error(f"Confluence initialization failed: {e}")
-        print(f"⚠ Confluence disabled: {e}")
-        _metrics.record_error()
-
-        tools = [
-            get_application_summary,
-            explain_fraud_score,
-            compare_to_population,
-            check_fair_lending_flags,
-            get_identity_network,
-            get_model_performance,
-        ]
-
-        system_prompt = ORIGINAL_PROMPT
-
-    if openai_api_key:
-        model = OpenAIModel(
-            client_args={"api_key": openai_api_key},
-            model_id="gpt-4o",
-            params={"temperature": 0.1, "max_tokens": 2048},
-        )
-        _cached_agent = Agent(model=model, system_prompt=system_prompt, tools=tools)
-    else:
-        _cached_agent = Agent(system_prompt=system_prompt, tools=tools)
-    
-    return _cached_agent
-
-
-def query_agent(question: str) -> str:
-    """Process question with the enhanced agent."""
-    try:
-        logger.info(f"Processing query: {question}")
-        agent = create_enhanced_agent()
-        result = agent(question)
-        logger.info("Query completed successfully")
-        return str(result)
-    except Exception as e:
-        logger.error(f"Query failed: {e}")
-        _metrics.record_error()
-        return f"Error: {str(e)}"
-
-
-# =============================================================================
-# FASTAPI APPLICATION
-# =============================================================================
-
-app = FastAPI(title="Fraud Model Explainability Assistant")
-
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=["*"],
-    allow_methods=["*"],
-    allow_headers=["*"],
-    allow_credentials=True,
-)
-
-
-class QuestionRequest(BaseModel):
-    question: str
-
-
-class AnswerResponse(BaseModel):
-    answer: str
-    metrics: dict
-
-
-@app.get("/")
-async def index():
-    """Serve the main UI."""
-    return HTMLResponse(content=get_ui_html())
-
-
-@app.post("/api/ask", response_model=AnswerResponse)
-async def ask_question(request: QuestionRequest):
-    """Process a question and return the answer."""
-    try:
-        answer = query_agent(request.question)
-        return AnswerResponse(
-            answer=answer,
-            metrics=_metrics.get_stats()
-        )
-    except Exception as e:
-        logger.error(f"API error: {e}")
-        raise HTTPException(status_code=500, detail=str(e))
-
-
-@app.get("/api/metrics")
-async def get_metrics():
-    """Get current performance metrics."""
-    return _metrics.get_stats()
-
-
-@app.get("/api/health")
-async def health_check():
-    """Health check endpoint."""
-    return {
-        "status": "healthy",
-        "confluence_initialized": _confluence_rag is not None,
-        "metrics": _metrics.get_stats()
-    }
-
-
-# =============================================================================
-# HTML UI
-# =============================================================================
-
-def get_ui_html() -> str:
-    """Generate the chat UI HTML."""
-    
-    example_questions = [
-        "Why was application APP-78432 flagged as high risk?",
-        "Explain the fraud score for APP-12345 and compare it to approved applications",
-        "Check fair lending compliance for APP-55555 and cite relevant policies",
-        "Show me the identity network analysis for APP-78432",
-        "What's the current model performance for the Retail Card portfolio?",
-        "What does our fair lending policy say about synthetic ID detection?",
-        "Find the model validation report for XGBoost v3.2",
-        "What are the procedures for escalating high-risk applications?",
-    ]
-    
-    examples_json = json.dumps(example_questions)
-    
-    return f"""
-    <!DOCTYPE html>
-    <html lang="en">
-    <head>
-        <meta charset="UTF-8">
-        <meta name="viewport" content="width=device-width, initial-scale=1.0">
-        <title>Fraud Model Explainability Assistant</title>
-        <style>
-            * {{
-                box-sizing: border-box;
-                margin: 0;
-                padding: 0;
-            }}
-            
-            body {{
-                font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
-                background: linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%);
-                min-height: 100vh;
-                color: #e0e0e0;
-            }}
-            
-            .container {{
-                max-width: 1200px;
-                margin: 0 auto;
-                padding: 20px;
-            }}
-            
-            header {{
-                text-align: center;
-                padding: 30px 0;
-                border-bottom: 1px solid rgba(255,255,255,0.1);
-                margin-bottom: 30px;
-            }}
-            
-            h1 {{
-                font-size: 2.5rem;
-                background: linear-gradient(90deg, #00d4ff, #7b2cbf);
-                -webkit-background-clip: text;
-                -webkit-text-fill-color: transparent;
-                background-clip: text;
-                margin-bottom: 10px;
-            }}
-            
-            .subtitle {{
-                color: #888;
-                font-size: 1.1rem;
-            }}
-            
-            .main-content {{
-                display: grid;
-                grid-template-columns: 1fr 300px;
-                gap: 30px;
-            }}
-            
-            @media (max-width: 900px) {{
-                .main-content {{
-                    grid-template-columns: 1fr;
-                }}
-            }}
-            
-            .chat-section {{
-                background: rgba(255,255,255,0.05);
-                border-radius: 16px;
-                padding: 20px;
-                backdrop-filter: blur(10px);
-                border: 1px solid rgba(255,255,255,0.1);
-            }}
-            
-            .input-area {{
-                display: flex;
-                gap: 10px;
-                margin-bottom: 20px;
-            }}
-            
-            textarea {{
-                flex: 1;
-                padding: 15px;
-                border: 2px solid rgba(255,255,255,0.1);
-                border-radius: 12px;
-                background: rgba(0,0,0,0.3);
-                color: #fff;
-                font-size: 1rem;
-                resize: vertical;
-                min-height: 80px;
-                transition: border-color 0.3s;
-            }}
-            
-            textarea:focus {{
-                outline: none;
-                border-color: #00d4ff;
-            }}
-            
-            button {{
-                padding: 15px 30px;
-                background: linear-gradient(135deg, #00d4ff, #7b2cbf);
-                color: white;
-                border: none;
-                border-radius: 12px;
-                font-size: 1rem;
-                font-weight: 600;
-                cursor: pointer;
-                transition: transform 0.2s, box-shadow 0.2s;
-            }}
-            
-            button:hover:not(:disabled) {{
-                transform: translateY(-2px);
-                box-shadow: 0 10px 30px rgba(0,212,255,0.3);
-            }}
-            
-            button:disabled {{
-                opacity: 0.5;
-                cursor: not-allowed;
-            }}
-            
-            .response-area {{
-                background: rgba(0,0,0,0.3);
-                border-radius: 12px;
-                padding: 20px;
-                min-height: 400px;
-                max-height: 600px;
-                overflow-y: auto;
-            }}
-            
-            .response-area pre {{
-                white-space: pre-wrap;
-                word-wrap: break-word;
-                font-family: 'Fira Code', 'Consolas', monospace;
-                font-size: 0.9rem;
-                line-height: 1.6;
-            }}
-            
-            .loading {{
-                display: flex;
-                align-items: center;
-                justify-content: center;
-                gap: 10px;
-                padding: 40px;
-                color: #00d4ff;
-            }}
-            
-            .spinner {{
-                width: 24px;
-                height: 24px;
-                border: 3px solid rgba(0,212,255,0.2);
-                border-top-color: #00d4ff;
-                border-radius: 50%;
-                animation: spin 1s linear infinite;
-            }}
-            
-            @keyframes spin {{
-                to {{ transform: rotate(360deg); }}
-            }}
-            
-            .sidebar {{
-                display: flex;
-                flex-direction: column;
-                gap: 20px;
-            }}
-            
-            .card {{
-                background: rgba(255,255,255,0.05);
-                border-radius: 12px;
-                padding: 20px;
-                border: 1px solid rgba(255,255,255,0.1);
-            }}
-            
-            .card h3 {{
-                color: #00d4ff;
-                margin-bottom: 15px;
-                font-size: 1rem;
-            }}
-            
-            .example-btn {{
-                display: block;
-                width: 100%;
-                padding: 10px;
-                margin-bottom: 8px;
-                background: rgba(0,0,0,0.3);
-                color: #ccc;
-                border: 1px solid rgba(255,255,255,0.1);
-                border-radius: 8px;
-                font-size: 0.85rem;
-                text-align: left;
-                cursor: pointer;
-                transition: all 0.2s;
-            }}
-            
-            .example-btn:hover {{
-                background: rgba(0,212,255,0.1);
-                border-color: #00d4ff;
-                color: #fff;
-            }}
-            
-            .metrics {{
-                display: grid;
-                grid-template-columns: 1fr 1fr;
-                gap: 10px;
-            }}
-            
-            .metric {{
-                background: rgba(0,0,0,0.3);
-                padding: 12px;
-                border-radius: 8px;
-                text-align: center;
-            }}
-            
-            .metric-value {{
-                font-size: 1.5rem;
-                font-weight: bold;
-                color: #00d4ff;
-            }}
-            
-            .metric-label {{
-                font-size: 0.75rem;
-                color: #888;
-                margin-top: 4px;
-            }}
-            
-            .features {{
-                list-style: none;
-            }}
-            
-            .features li {{
-                padding: 8px 0;
-                border-bottom: 1px solid rgba(255,255,255,0.05);
-                font-size: 0.9rem;
-            }}
-            
-            .features li:last-child {{
-                border-bottom: none;
-            }}
-            
-            .features li::before {{
-                content: "✓ ";
-                color: #00d4ff;
-            }}
-            
-            footer {{
-                text-align: center;
-                padding: 30px;
-                color: #666;
-                font-size: 0.9rem;
-                margin-top: 40px;
-            }}
-        </style>
-    </head>
-    <body>
-        <div class="container">
-            <header>
-                <h1>🔍 Fraud Model Explainability Assistant</h1>
-                <p class="subtitle">Production-Ready with Confluence Integration</p>
-            </header>
-            
-            <div class="main-content">
-                <div class="chat-section">
-                    <div class="input-area">
-                        <textarea 
-                            id="questionInput" 
-                            placeholder="Ask a question about fraud models, applications, or policies..."
-                            onkeydown="if(event.key === 'Enter' && !event.shiftKey) {{ event.preventDefault(); askQuestion(); }}"
-                        ></textarea>
-                        <button id="askBtn" onclick="askQuestion()">🔍 Analyze</button>
-                    </div>
-                    
-                    <div class="response-area" id="responseArea">
-                        <pre id="responseText">Welcome! Ask me about:
-                        
-• Application fraud scores and explanations
-• Fair lending compliance checks
-• Identity network analysis
-• Model performance metrics
-• Confluence documentation and policies
-
-Enter your question above and click "Analyze" to get started.</pre>
-                    </div>
-                </div>
-                
-                <div class="sidebar">
-                    <div class="card">
-                        <h3>📊 Performance Metrics</h3>
-                        <div class="metrics">
-                            <div class="metric">
-                                <div class="metric-value" id="totalSearches">0</div>
-                                <div class="metric-label">Searches</div>
-                            </div>
-                            <div class="metric">
-                                <div class="metric-value" id="cacheRate">0%</div>
-                                <div class="metric-label">Cache Rate</div>
-                            </div>
-                            <div class="metric">
-                                <div class="metric-value" id="avgTime">0s</div>
-                                <div class="metric-label">Avg Time</div>
-                            </div>
-                            <div class="metric">
-                                <div class="metric-value" id="errors">0</div>
-                                <div class="metric-label">Errors</div>
-                            </div>
-                        </div>
-                    </div>
-                    
-                    <div class="card">
-                        <h3>💡 Example Questions</h3>
-                        <div id="examplesContainer"></div>
-                    </div>
-                    
-                    <div class="card">
-                        <h3>✨ Production Features</h3>
-                        <ul class="features">
-                            <li>Structured logging</li>
-                            <li>Performance tracking</li>
-                            <li>Error monitoring</li>
-                            <li>Daily auto-refresh (2 AM)</li>
-                            <li>Confluence integration</li>
-                        </ul>
-                    </div>
-                </div>
-            </div>
-            
-            <footer>
-                Powered by Strands Agents + Confluence Integration • FastAPI Backend
-            </footer>
-        </div>
-        
-        <script>
-            const examples = {examples_json};
-            
-            // Populate examples
-            const examplesContainer = document.getElementById('examplesContainer');
-            examples.slice(0, 5).forEach(q => {{
-                const btn = document.createElement('button');
-                btn.className = 'example-btn';
-                btn.textContent = q.length > 50 ? q.substring(0, 50) + '...' : q;
-                btn.title = q;
-                btn.onclick = () => {{
-                    document.getElementById('questionInput').value = q;
-                    askQuestion();
-                }};
-                examplesContainer.appendChild(btn);
-            }});
-            
-            async function askQuestion() {{
-                const input = document.getElementById('questionInput');
-                const btn = document.getElementById('askBtn');
-                const responseArea = document.getElementById('responseArea');
-                const responseText = document.getElementById('responseText');
-                
-                const question = input.value.trim();
-                if (!question) return;
-                
-                btn.disabled = true;
-                btn.textContent = '⏳ Processing...';
-                responseArea.innerHTML = '<div class="loading"><div class="spinner"></div>Analyzing your question...</div>';
-                
-                try {{
-                    const response = await fetch('/api/ask', {{
-                        method: 'POST',
-                        headers: {{
-                            'Content-Type': 'application/json',
-                        }},
-                        body: JSON.stringify({{ question }}),
-                    }});
-                    
-                    if (!response.ok) {{
-                        throw new Error(`HTTP error! status: ${{response.status}}`);
-                    }}
-                    
-                    const data = await response.json();
-                    
-                    responseArea.innerHTML = '<pre id="responseText"></pre>';
-                    document.getElementById('responseText').textContent = data.answer;
-                    
-                    // Update metrics
-                    if (data.metrics) {{
-                        document.getElementById('totalSearches').textContent = data.metrics.total_searches || 0;
-                        document.getElementById('cacheRate').textContent = 
-                            ((data.metrics.cache_hit_rate || 0) * 100).toFixed(0) + '%';
-                        document.getElementById('avgTime').textContent = 
-                            (data.metrics.avg_query_time || 0).toFixed(2) + 's';
-                        document.getElementById('errors').textContent = data.metrics.errors || 0;
-                    }}
-                    
-                }} catch (error) {{
-                    responseArea.innerHTML = '<pre id="responseText" style="color: #ff6b6b;"></pre>';
-                    document.getElementById('responseText').textContent = 'Error: ' + error.message;
-                }} finally {{
-                    btn.disabled = false;
-                    btn.textContent = '🔍 Analyze';
-                }}
-            }}
-            
-            // Fetch initial metrics
-            async function fetchMetrics() {{
-                try {{
-                    const response = await fetch('/api/metrics');
-                    const metrics = await response.json();
-                    document.getElementById('totalSearches').textContent = metrics.total_searches || 0;
-                    document.getElementById('cacheRate').textContent = 
-                        ((metrics.cache_hit_rate || 0) * 100).toFixed(0) + '%';
-                    document.getElementById('avgTime').textContent = 
-                        (metrics.avg_query_time || 0).toFixed(2) + 's';
-                    document.getElementById('errors').textContent = metrics.errors || 0;
-                }} catch (e) {{
-                    console.log('Could not fetch metrics:', e);
-                }}
-            }}
-            
-            fetchMetrics();
-            setInterval(fetchMetrics, 30000);
-        </script>
-    </body>
-    </html>
-    """
-
-
-# =============================================================================
-# MAIN ENTRYPOINT
-# =============================================================================
-
-if __name__ == "__main__":
-    import uvicorn
-
-    # Pre-initialize Confluence
-    try:
-        init_confluence()
-    except Exception as e:
-        logger.error(f"Confluence initialization failed: {e}")
-        print(f"Warning: Confluence initialization failed: {e}")
-        print("App will run without Confluence integration.")
-
-    # Set up scheduled re-ingestion
-    scheduler = setup_scheduled_ingestion()
-
-    # Launch FastAPI with uvicorn
-    logger.info("Launching FastAPI server...")
-    print("\n" + "=" * 60)
-    print("Fraud Model Explainability Assistant")
-    print("  - FastAPI backend on port 7860")
-    print("  - Confluence integration enabled")
-    print("  - Scheduled refresh at 2 AM daily")
-    print("=" * 60 + "\n")
-
-    uvicorn.run(
-        app,
-        host="0.0.0.0",
-        port=7860,
-        reload=False
-    )

utils.py

@@ -0,0 +1,685 @@
+"""
+Fraud Model Explainability Assistant - Shared Utilities
+
+This module contains shared tools, mock data generators, and configuration constants
+used by the Fraud Model Explainability Assistant.
+"""
+
+import os
+import random
+import warnings
+from datetime import datetime, timedelta
+from typing import Optional
+
+# Suppress asyncio "Invalid file descriptor" warnings in containerized environments
+# These are harmless cleanup warnings during garbage collection
+warnings.filterwarnings("ignore", category=ResourceWarning)
+os.environ["PYTHONWARNINGS"] = "ignore::ResourceWarning"
+
+from strands import tool
+
+
+# =============================================================================
+# MOCK DATA GENERATORS
+# =============================================================================
+# In production, these would connect to your actual data systems
+# (e.g., Snowflake, feature store, model serving infrastructure)
+
+def generate_mock_application(app_id: str) -> dict:
+    """Generate realistic mock application data for demo purposes."""
+    random.seed(hash(app_id) % 2**32)
+    
+    risk_level = random.choice(["low", "medium", "high", "very_high"])
+    
+    base_data = {
+        "application_id": app_id,
+        "timestamp": (datetime.now() - timedelta(days=random.randint(0, 30))).isoformat(),
+        "portfolio": random.choice(["Retail Card", "Payment Solutions", "CareCredit"]),
+        "requested_credit_line": random.randint(500, 25000),
+        "fraud_score": {
+            "low": random.randint(150, 350),
+            "medium": random.randint(400, 550),
+            "high": random.randint(600, 750),
+            "very_high": random.randint(800, 950)
+        }[risk_level],
+        "fraud_score_percentile": {
+            "low": random.randint(5, 30),
+            "medium": random.randint(40, 60),
+            "high": random.randint(75, 90),
+            "very_high": random.randint(92, 99)
+        }[risk_level],
+        "decision": "FLAGGED" if risk_level in ["high", "very_high"] else "APPROVED",
+        "risk_level": risk_level,
+    }
+    
+    # Features that contribute to fraud scoring
+    if risk_level in ["high", "very_high"]:
+        base_data["features"] = {
+            "ssn_issue_date_vs_credit_age_mismatch": random.uniform(0.7, 0.95),
+            "device_velocity_30d": random.randint(5, 15),
+            "address_type": random.choice(["CMRA", "PO_BOX", "VACANT"]),
+            "phone_type": random.choice(["VOIP", "PREPAID"]),
+            "email_domain_age_days": random.randint(1, 30),
+            "application_velocity_14d": random.randint(3, 8),
+            "identity_linkage_count": random.randint(4, 12),
+            "credit_inquiry_spike": True,
+            "synthetic_id_score": random.uniform(0.75, 0.98),
+        }
+    else:
+        base_data["features"] = {
+            "ssn_issue_date_vs_credit_age_mismatch": random.uniform(0.0, 0.2),
+            "device_velocity_30d": random.randint(1, 2),
+            "address_type": "RESIDENTIAL",
+            "phone_type": "POSTPAID",
+            "email_domain_age_days": random.randint(365, 3650),
+            "application_velocity_14d": random.randint(0, 1),
+            "identity_linkage_count": random.randint(0, 2),
+            "credit_inquiry_spike": False,
+            "synthetic_id_score": random.uniform(0.05, 0.25),
+        }
+    
+    return base_data
+
+
+# =============================================================================
+# FRAUD EXPLAINABILITY TOOLS
+# =============================================================================
+
+@tool
+def get_application_summary(application_id: str) -> str:
+    """
+    Retrieve basic information about a credit application including
+    fraud score, decision, portfolio, and timestamp.
+    
+    Args:
+        application_id: The unique identifier for the application (e.g., "APP-12345")
+    
+    Returns:
+        A summary of the application details and fraud assessment
+    """
+    app = generate_mock_application(application_id)
+    
+    return f"""
+APPLICATION SUMMARY
+==================
+Application ID: {app['application_id']}
+Submission Date: {app['timestamp'][:10]}
+Portfolio: {app['portfolio']}
+Requested Credit Line: ${app['requested_credit_line']:,}
+
+FRAUD ASSESSMENT
+----------------
+Fraud Score: {app['fraud_score']} / 1000
+Risk Percentile: {app['fraud_score_percentile']}th percentile
+Risk Level: {app['risk_level'].upper()}
+Decision: {app['decision']}
+"""
+
+
+@tool
+def explain_fraud_score(application_id: str) -> str:
+    """
+    Get detailed SHAP-style feature attribution explanation for why an 
+    application received its fraud score. Shows which factors contributed
+    most to the risk assessment.
+    
+    Args:
+        application_id: The unique identifier for the application
+    
+    Returns:
+        Detailed breakdown of contributing factors with impact scores
+    """
+    app = generate_mock_application(application_id)
+    features = app["features"]
+    
+    # Simulate SHAP values (in production, these come from your model)
+    explanations = []
+    
+    if features["ssn_issue_date_vs_credit_age_mismatch"] > 0.5:
+        explanations.append({
+            "feature": "SSN Issue Date vs Credit Age Mismatch",
+            "value": f"{features['ssn_issue_date_vs_credit_age_mismatch']:.0%}",
+            "impact": "+187 points",
+            "direction": "INCREASES RISK",
+            "explanation": "SSN was issued recently but credit file shows longer history, a key synthetic ID indicator"
+        })
+    
+    if features["device_velocity_30d"] > 3:
+        explanations.append({
+            "feature": "Device Velocity (30 days)",
+            "value": f"{features['device_velocity_30d']} applications",
+            "impact": "+142 points",
+            "direction": "INCREASES RISK",
+            "explanation": "Same device fingerprint linked to multiple applications in short period"
+        })
+    
+    if features["address_type"] in ["CMRA", "PO_BOX", "VACANT"]:
+        explanations.append({
+            "feature": "Address Type",
+            "value": features["address_type"],
+            "impact": "+98 points",
+            "direction": "INCREASES RISK",
+            "explanation": f"Address classified as {features['address_type']} (Commercial Mail Receiving Agency or high-risk type)"
+        })
+    
+    if features["synthetic_id_score"] > 0.6:
+        explanations.append({
+            "feature": "Synthetic Identity Score",
+            "value": f"{features['synthetic_id_score']:.0%}",
+            "impact": "+156 points",
+            "direction": "INCREASES RISK",
+            "explanation": "Composite score from ensemble model indicates high probability of synthetic identity"
+        })
+    
+    if features["application_velocity_14d"] > 2:
+        explanations.append({
+            "feature": "Application Velocity (14 days)",
+            "value": f"{features['application_velocity_14d']} applications",
+            "impact": "+78 points",
+            "direction": "INCREASES RISK",
+            "explanation": "Multiple credit applications submitted in short timeframe"
+        })
+    
+    if features["email_domain_age_days"] < 60:
+        explanations.append({
+            "feature": "Email Domain Age",
+            "value": f"{features['email_domain_age_days']} days",
+            "impact": "+45 points",
+            "direction": "INCREASES RISK",
+            "explanation": "Email address created very recently"
+        })
+    
+    if features["phone_type"] in ["VOIP", "PREPAID"]:
+        explanations.append({
+            "feature": "Phone Type",
+            "value": features["phone_type"],
+            "impact": "+62 points",
+            "direction": "INCREASES RISK",
+            "explanation": "Non-traditional phone type associated with higher fraud rates"
+        })
+    
+    # If low risk, show protective factors
+    if app["risk_level"] == "low":
+        explanations = [
+            {
+                "feature": "Established Credit History",
+                "value": "12+ years",
+                "impact": "-120 points",
+                "direction": "DECREASES RISK",
+                "explanation": "Long credit history consistent with SSN issue date"
+            },
+            {
+                "feature": "Stable Contact Information",
+                "value": "Verified",
+                "impact": "-85 points",
+                "direction": "DECREASES RISK",
+                "explanation": "Phone and address verified with multiple data sources"
+            },
+            {
+                "feature": "Low Application Velocity",
+                "value": "1 in 90 days",
+                "impact": "-45 points",
+                "direction": "DECREASES RISK",
+                "explanation": "Normal application pattern"
+            }
+        ]
+    
+    # Format output
+    output = f"""
+FRAUD SCORE EXPLANATION
+=======================
+Application ID: {application_id}
+Final Fraud Score: {app['fraud_score']} / 1000
+Model: XGBoost Fraud Ensemble v3.2
+
+TOP CONTRIBUTING FACTORS (ranked by impact):
+--------------------------------------------
+"""
+    
+    for i, exp in enumerate(sorted(explanations, key=lambda x: abs(int(x["impact"].split()[0])), reverse=True), 1):
+        output += f"""
+{i}. {exp['feature']}
+   Value: {exp['value']}
+   Impact: {exp['impact']} ({exp['direction']})
+   → {exp['explanation']}
+"""
+    
+    return output
+
+
+@tool
+def compare_to_population(application_id: str, comparison_group: str = "approved") -> str:
+    """
+    Compare an application's features to the approved or denied population
+    to show how unusual the applicant's characteristics are.
+    
+    Args:
+        application_id: The unique identifier for the application
+        comparison_group: Either "approved" or "denied" population to compare against
+    
+    Returns:
+        Statistical comparison showing how the application differs from typical cases
+    """
+    app = generate_mock_application(application_id)
+    features = app["features"]
+    
+    # Mock population statistics
+    population_stats = {
+        "approved": {
+            "ssn_credit_mismatch_mean": 0.08,
+            "ssn_credit_mismatch_std": 0.12,
+            "device_velocity_mean": 1.2,
+            "device_velocity_std": 0.8,
+            "synthetic_score_mean": 0.15,
+            "synthetic_score_std": 0.10,
+            "app_velocity_mean": 0.5,
+            "app_velocity_std": 0.7,
+        },
+        "denied": {
+            "ssn_credit_mismatch_mean": 0.72,
+            "ssn_credit_mismatch_std": 0.18,
+            "device_velocity_mean": 6.5,
+            "device_velocity_std": 3.2,
+            "synthetic_score_mean": 0.78,
+            "synthetic_score_std": 0.15,
+            "app_velocity_mean": 4.2,
+            "app_velocity_std": 2.1,
+        }
+    }
+    
+    stats = population_stats.get(comparison_group, population_stats["approved"])
+    
+    def calc_z_score(value, mean, std):
+        if std == 0:
+            return 0
+        return (value - mean) / std
+    
+    comparisons = [
+        {
+            "feature": "SSN/Credit Age Mismatch",
+            "applicant_value": f"{features['ssn_issue_date_vs_credit_age_mismatch']:.0%}",
+            "population_mean": f"{stats['ssn_credit_mismatch_mean']:.0%}",
+            "z_score": calc_z_score(features['ssn_issue_date_vs_credit_age_mismatch'], 
+                                    stats['ssn_credit_mismatch_mean'], 
+                                    stats['ssn_credit_mismatch_std'])
+        },
+        {
+            "feature": "Device Velocity (30d)",
+            "applicant_value": str(features['device_velocity_30d']),
+            "population_mean": f"{stats['device_velocity_mean']:.1f}",
+            "z_score": calc_z_score(features['device_velocity_30d'], 
+                                    stats['device_velocity_mean'], 
+                                    stats['device_velocity_std'])
+        },
+        {
+            "feature": "Synthetic ID Score",
+            "applicant_value": f"{features['synthetic_id_score']:.0%}",
+            "population_mean": f"{stats['synthetic_score_mean']:.0%}",
+            "z_score": calc_z_score(features['synthetic_id_score'], 
+                                    stats['synthetic_score_mean'], 
+                                    stats['synthetic_score_std'])
+        },
+        {
+            "feature": "Application Velocity (14d)",
+            "applicant_value": str(features['application_velocity_14d']),
+            "population_mean": f"{stats['app_velocity_mean']:.1f}",
+            "z_score": calc_z_score(features['application_velocity_14d'], 
+                                    stats['app_velocity_mean'], 
+                                    stats['app_velocity_std'])
+        },
+    ]
+    
+    output = f"""
+POPULATION COMPARISON ANALYSIS
+==============================
+Application ID: {application_id}
+Comparison Group: {comparison_group.upper()} applications (last 12 months)
+Sample Size: {'847,293' if comparison_group == 'approved' else '23,847'} applications
+
+FEATURE COMPARISON:
+-------------------
+{"Feature":<30} {"Applicant":<15} {"Population Mean":<18} {"Z-Score":<10} {"Assessment"}
+{"-"*95}
+"""
+    
+    for comp in comparisons:
+        z = comp["z_score"]
+        if abs(z) > 3:
+            assessment = "⚠️  EXTREME OUTLIER"
+        elif abs(z) > 2:
+            assessment = "🔶 SIGNIFICANT DEVIATION"
+        elif abs(z) > 1:
+            assessment = "🔷 MILD DEVIATION"
+        else:
+            assessment = "✅ WITHIN NORMAL"
+        
+        output += f"{comp['feature']:<30} {comp['applicant_value']:<15} {comp['population_mean']:<18} {z:>+.2f}σ      {assessment}\n"
+    
+    # Summary
+    extreme_count = sum(1 for c in comparisons if abs(c["z_score"]) > 2)
+    
+    output += f"""
+SUMMARY:
+--------
+{extreme_count} of {len(comparisons)} features show significant deviation (|z| > 2σ) from {comparison_group} population.
+"""
+    
+    if extreme_count >= 2:
+        output += f"This application's profile is statistically unusual compared to typically {comparison_group} applications."
+    
+    return output
+
+
+@tool
+def check_fair_lending_flags(application_id: str) -> str:
+    """
+    Check for potential fair lending concerns in the fraud decision.
+    Reviews whether protected class proxies may have influenced the score
+    and provides compliance documentation.
+    
+    Args:
+        application_id: The unique identifier for the application
+    
+    Returns:
+        Fair lending compliance assessment and documentation
+    """
+    app = generate_mock_application(application_id)
+    
+    # Mock fair lending analysis
+    output = f"""
+FAIR LENDING COMPLIANCE REVIEW
+==============================
+Application ID: {application_id}
+Review Date: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
+Model: XGBoost Fraud Ensemble v3.2
+
+PROTECTED CLASS PROXY ANALYSIS:
+-------------------------------
+The following features were analyzed for potential correlation with protected characteristics:
+
+✅ Geography-Based Features:
+   - ZIP code used only for velocity calculations, not scoring
+   - No direct geographic risk scoring applied
+   - Compliant with ECOA geographic restrictions
+
+✅ Name-Based Features:
+   - No name-based features used in fraud model
+   - Identity verification uses SSN/DOB only
+   
+✅ Age-Related Features:
+   - Credit age features measure account history, not applicant age
+   - SSN issuance analysis targets synthetic ID patterns, not age discrimination
+   - Model tested for age disparate impact: PASSED (adverse impact ratio: 0.94)
+
+⚠️  REVIEW ITEMS:
+-----------------
+"""
+    
+    if app["features"].get("phone_type") in ["VOIP", "PREPAID"]:
+        output += """
+• Phone Type Feature:
+  - VOIP/Prepaid flagged as risk factor
+  - Documented business justification: 73% of confirmed synthetic fraud uses VOIP
+  - Disparate impact testing: PASSED (ratio: 0.89)
+  - Alternative considered: None available with equivalent predictive power
+"""
+    
+    if app["features"].get("address_type") in ["CMRA", "PO_BOX"]:
+        output += """
+• Address Type Feature:
+  - CMRA/PO Box flagged as risk factor  
+  - Documented business justification: Required for synthetic ID detection
+  - Disparate impact testing: PASSED (ratio: 0.91)
+  - Accommodations: Manual review pathway available for legitimate CMRA users
+"""
+    
+    output += f"""
+MODEL VALIDATION STATUS:
+------------------------
+Last Disparate Impact Test: 2024-11-15
+Last Adverse Action Review: 2024-12-01
+Model Risk Rating: LOW
+SR 11-7 Compliance: COMPLIANT
+
+ADVERSE ACTION REASON CODES:
+----------------------------
+If this application is denied, the following reason codes apply:
+"""
+    
+    if app["decision"] == "FLAGGED":
+        reasons = [
+            "FA01 - Unable to verify identity information",
+            "FA03 - Inconsistent application information",
+            "FA07 - High-risk contact information patterns",
+        ]
+        for i, reason in enumerate(reasons, 1):
+            output += f"  {i}. {reason}\n"
+    else:
+        output += "  N/A - Application approved\n"
+    
+    output += """
+DOCUMENTATION:
+--------------
+This analysis is auto-generated for compliance documentation.
+Full model documentation available in Model Risk Management system.
+Contact: model-governance@company.com
+"""
+    
+    return output
+
+
+@tool
+def get_identity_network(application_id: str) -> str:
+    """
+    Analyze the identity linkage network for an application, showing
+    connections to other applications via shared attributes (device,
+    phone, email, address, SSN patterns).
+    
+    Args:
+        application_id: The unique identifier for the application
+    
+    Returns:
+        Network analysis showing linked applications and risk patterns
+    """
+    app = generate_mock_application(application_id)
+    features = app["features"]
+    
+    linkage_count = features.get("identity_linkage_count", 0)
+    
+    output = f"""
+IDENTITY NETWORK ANALYSIS
+=========================
+Application ID: {application_id}
+Analysis Date: {datetime.now().strftime('%Y-%m-%d')}
+
+LINKAGE SUMMARY:
+----------------
+Total Linked Applications: {linkage_count}
+"""
+    
+    if linkage_count > 3:
+        # Generate mock linked applications for high-risk cases
+        random.seed(hash(application_id) % 2**32)
+        
+        link_types = {
+            "device_fingerprint": random.randint(2, min(linkage_count, 8)),
+            "phone_number": random.randint(1, min(linkage_count, 4)),
+            "email_pattern": random.randint(1, min(linkage_count, 3)),
+            "address": random.randint(1, min(linkage_count, 5)),
+        }
+        
+        output += f"""
+LINKAGE BREAKDOWN:
+------------------
+• Device Fingerprint Links: {link_types['device_fingerprint']} applications
+• Phone Number Links: {link_types['phone_number']} applications  
+• Email Pattern Links: {link_types['email_pattern']} applications
+• Address Links: {link_types['address']} applications
+
+LINKED APPLICATION DETAILS:
+---------------------------
+"""
+        
+        statuses = ["CONFIRMED_FRAUD", "FLAGGED", "DENIED", "CHARGED_OFF", "APPROVED"]
+        weights = [0.3, 0.25, 0.2, 0.15, 0.1] if app["risk_level"] in ["high", "very_high"] else [0.05, 0.1, 0.15, 0.1, 0.6]
+        
+        for i in range(min(linkage_count, 6)):
+            linked_id = f"APP-{random.randint(10000, 99999)}"
+            link_type = random.choice(list(link_types.keys()))
+            status = random.choices(statuses, weights=weights)[0]
+            days_ago = random.randint(1, 180)
+            
+            status_emoji = {
+                "CONFIRMED_FRAUD": "🔴",
+                "FLAGGED": "🟠", 
+                "DENIED": "🟡",
+                "CHARGED_OFF": "🔴",
+                "APPROVED": "🟢"
+            }
+            
+            output += f"  {status_emoji.get(status, '⚪')} {linked_id} | {link_type.replace('_', ' ').title()} | {status} | {days_ago}d ago\n"
+        
+        # Risk assessment
+        fraud_links = sum(1 for _ in range(linkage_count) if random.random() < 0.4)
+        
+        output += f"""
+NETWORK RISK ASSESSMENT:
+------------------------
+• Confirmed Fraud in Network: {fraud_links} application(s)
+• Network Risk Score: {min(100, linkage_count * 12 + fraud_links * 25)}/100
+• Ring Pattern Detected: {"YES ⚠️" if linkage_count > 5 else "NO"}
+• Velocity Anomaly: {"YES ⚠️" if features.get('device_velocity_30d', 0) > 5 else "NO"}
+
+RECOMMENDATION:
+---------------
+{"⚠️  HIGH-RISK NETWORK - Manual review recommended" if linkage_count > 5 else "🔶 ELEVATED RISK - Monitor for additional activity"}
+"""
+    
+    else:
+        output += """
+LINKAGE BREAKDOWN:
+------------------
+• Device Fingerprint Links: 0-1 applications
+• Phone Number Links: 0 applications
+• Email Pattern Links: 0 applications
+• Address Links: 1 application (same household likely)
+
+NETWORK RISK ASSESSMENT:
+------------------------
+• Network Risk Score: LOW
+• No suspicious patterns detected
+• Normal application profile
+
+✅ No concerning identity network patterns identified.
+"""
+    
+    return output
+
+
+@tool
+def get_model_performance(model_name: str = "xgboost_fraud_v3.2", portfolio: str = "all") -> str:
+    """
+    Retrieve current performance metrics for a fraud detection model,
+    including precision, recall, KS statistic, and financial impact.
+    
+    Args:
+        model_name: Name of the fraud model (default: xgboost_fraud_v3.2)
+        portfolio: Portfolio to filter by ("Retail Card", "Payment Solutions", "CareCredit", or "all")
+    
+    Returns:
+        Model performance metrics and trends
+    """
+    output = f"""
+MODEL PERFORMANCE DASHBOARD
+===========================
+Model: {model_name}
+Portfolio: {portfolio.upper()}
+Reporting Period: Last 30 Days
+Generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
+
+DETECTION METRICS:
+------------------
+                        Current     Prior Month     Δ Change
+Fraud Detection Rate:   87.3%       84.1%          +3.2% ✅
+Precision (PPV):        34.2%       31.8%          +2.4% ✅
+False Positive Rate:    2.1%        2.4%           -0.3% ✅
+KS Statistic:           0.72        0.69           +0.03 ✅
+Gini Coefficient:       0.81        0.78           +0.03 ✅
+AUC-ROC:                0.91        0.89           +0.02 ✅
+
+FINANCIAL IMPACT:
+-----------------
+                        Current     Prior Month     Δ Change
+Fraud Losses Prevented: $4.2M       $3.8M          +$400K ✅
+False Positive Cost:    $890K       $920K          -$30K  ✅
+Net Benefit:            $3.31M      $2.88M         +$430K ✅
+ROI:                    372%        317%           +55%   ✅
+
+VOLUME METRICS:
+---------------
+Applications Scored:    1,247,832
+High-Risk Flags:        26,847 (2.15%)
+Manual Reviews:         8,421
+Confirmed Fraud:        9,182
+"""
+    
+    if portfolio != "all":
+        output += f"""
+PORTFOLIO BREAKDOWN ({portfolio}):
+{'='*40}
+Applications:           {random.randint(200000, 500000):,}
+Fraud Rate:             {random.uniform(0.5, 1.2):.2f}%
+Detection Rate:         {random.uniform(82, 92):.1f}%
+"""
+    
+    output += """
+MODEL HEALTH:
+-------------
+✅ Feature Drift (PSI): 0.08 (threshold: 0.25)
+✅ Score Distribution: Stable
+✅ Latency P99: 45ms (SLA: 100ms)
+⚠️  Challenger Model: +2.1% lift in shadow mode - review scheduled
+
+TREND ALERT:
+------------
+📈 Synthetic ID fraud attempts up 23% MoM - model adapting well
+📉 First-party fraud stable at historical levels
+"""
+    
+    return output
+
+
+# =============================================================================
+# SYSTEM PROMPT
+# =============================================================================
+
+SYSTEM_PROMPT = """
+You are a Fraud Model Explainability Assistant for a major financial services company.
+Your role is to help fraud analysts, data scientists, and executives understand 
+fraud model decisions and their implications.
+
+You have access to tools that can:
+1. Retrieve application summaries and fraud scores
+2. Explain why applications received specific fraud scores (SHAP-style explanations)
+3. Compare applications to approved/denied populations statistically
+4. Check for fair lending compliance concerns
+5. Analyze identity networks and linkages
+6. Show model performance metrics
+
+When answering questions:
+- Be precise and data-driven
+- Highlight the most important risk factors first
+- Explain technical concepts in business terms when speaking to executives
+- Always mention fair lending implications when relevant
+- Provide actionable insights, not just data
+
+For flagged applications, structure your response as:
+1. Quick summary (score, decision, risk level)
+2. Top contributing factors
+3. How unusual this is compared to the population
+4. Any compliance considerations
+5. Recommended next steps
+
+Remember: Your explanations may be used in regulatory examinations and audits,
+so be accurate and thorough.
+""".strip()