🏦 Loan Default Early Warning System

AI-powered credit risk assessment using OpenAI function calling and Agent Lightning framework.

Features

• 🤖 Multi-tool AI agent for comprehensive risk analysis
• 📊 Interactive Streamlit dashboard with visualizations
• 📈 Historical trend analysis (6-month data)
• 🎯 Portfolio-level risk monitoring
• ⚡ Built with Microsoft Agent Lightning pattern

👉 Read more on Agent Lightning Documentation

Project Structure

loan_risk_agent/
├── cli_runner.py          # CLI entrypoint for evaluations/examples
├── streamlit_app.py       # Streamlit-based interactive demo
├── requirements.txt       # Python dependencies
├── agent/                 # Agent implementation and orchestration
│   ├── __init__.py
│   └── risk_agent.py
├── data/                  # Dataset loader and sample CSV
│   ├── __init__.py
│   ├── loan_data.py
│   └── loan_risk_samples.csv
├── tools/                 # Helper utilities for preprocessing and metrics
│   ├── __init__.py
│   └── risk_tools.py
├── ui/                    # Visualization helpers for Streamlit app
│   ├── __init__.py
│   └── visualizations.py

Installation

Note: Agent Lightning is designed for Unix-based systems and relies on Linux process forking, signal handling, and async I/O semantics, which are not fully supported on native Windows. That’s why it runs reliably only on WSL or Docker.

Clone the Repository

git clone https://github.com/divakarkumarp/agent-lightning-playground.git

cd loan_risk_agent

Setup Instructions (WSL2 or Linux)

1. Install WSL2 (Windows Subsystem for Linux):

   wsl --install

   Restart your computer if prompted.
2. Open WSL:

   wsl

3. Update the system:

   sudo apt update && sudo apt upgrade -y

4. Install Python 3.11+ and required tools:

   sudo apt install python3 python3-pip python3-venv -y

5. Navigate to your project directory (Windows files are accessible under /mnt/):

   cd /mnt/e/dev25/Building-Agentic-AI/agent_lightning

6. Create and activate a virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate

7. Install dependencies:

   pip install -r requirements.txt

Running the Project

Streamlit UI (Recommended for Quick Exploration)

streamlit run streamlit_app.py

CLI Runner (Scripts, Batch Evaluation, Quick Examples)

python cli_runner.py --help
python cli_runner.py run-example

Agent Workflow Architectures

Agent workflows in this project are designed to handle loan risk assessment tasks efficiently. The architecture leverages:

flowchart TD
    Start([👤 User Input:<br>'Assess LOAN002 default risk']) --> StreamlitUI[🎨 Streamlit Dashboard<br>or CLI Mode]
    
    StreamlitUI --> AgentInit[🤖 Initialize Risk Agent<br>Model: gpt-4o-mini<br>Temp: 0.2]
    
    AgentInit --> SystemPrompt[💬 System Prompt:<br>'You are a credit risk analyst.<br>ALWAYS use tools to gather data']
    
    SystemPrompt --> FirstLLM[🧠 First OpenAI Call<br>Analyze query and decide tools]
    
    FirstLLM --> ToolDecision{Agent decides which<br>tools to call}
    
    ToolDecision -->|Tool 1| Tool1[📋 get_loan_details<br>LOAN002]
    ToolDecision -->|Tool 2| Tool2[💳 analyze_payment_behavior<br>LOAN002]
    ToolDecision -->|Tool 3| Tool3[📊 check_credit_utilization<br>LOAN002]
    ToolDecision -->|Tool 4| Tool4[⚠️ calculate_risk_score<br>LOAN002]
    
    Tool1 --> DB1[(💾 LOAN_DATABASE)]
    DB1 --> Result1[Borrower: Priya Retail<br>Amount: ₹2M<br>Outstanding: ₹1.8M<br>Credit: 650<br>Industry: Retail]
    
    Tool2 --> DB2[(💾 PAYMENT_HISTORY)]
    DB2 --> Result2[Late Payments: 5<br>Bounced: 2<br>Avg Days Late: 18.5<br>Trend: Worsening]
    
    Tool3 --> DB3[(💾 CREDIT_UTILIZATION)]
    DB3 --> Result3[Current: 92%<br>6-Month Avg: 75%<br>Trend: Sharply Increasing]
    
    Tool4 --> AllDB[(💾 ALL DATA)]
    AllDB --> Result4[Risk Score: 75/100<br>Category: HIGH<br>Factors: 6 identified<br>Default Prob: 75%]
    
    Result1 --> Collect[📦 Collect All Tool Results<br>Build message history]
    Result2 --> Collect
    Result3 --> Collect
    Result4 --> Collect
    
    Collect --> SecondLLM[🧠 Second OpenAI Call<br>Synthesize results into report]
    
    SecondLLM --> FinalReport[📋 Generate Final Assessment:<br><br>HIGH RISK - 75/100<br><br>Risk Factors:<br>• Low credit score 650<br>• 5 late payments<br>• 2 bounced payments<br>• Very high utilization 92%<br>• Worsening payment trend<br>• Sharply increasing utilization<br><br>Recommended Action:<br>Urgent review needed]
    
    FinalReport --> Visualizations[📊 Create Visualizations]
    
    Visualizations --> Chart1[📈 Credit Score Trend<br>6-month line chart]
    Visualizations --> Chart2[📊 Utilization Trend<br>Area chart with threshold]
    Visualizations --> Chart3[⚠️ Payment Delay Chart<br>Color-coded bars]
    Visualizations --> Chart4[🎯 Risk Gauge<br>Speedometer 0-100]
    
    Chart1 & Chart2 & Chart3 & Chart4 --> Display[🖥️ Display in Streamlit<br>with interactive Plotly charts]
    
    FinalReport -.->|If Agent Lightning enabled| Trace[⚡ Trace Collection:<br>Log tool calls<br>Log timing<br>Log tokens used]
    
    Trace -.->|Send to| Lightning[🌐 Agent Lightning Server<br>RL Training in background]
    
    Lightning -.->|MDP Conversion| Training[🎓 RL Policy Optimization:<br>Reward based on accuracy<br>Update tool selection weights]
    
    Training -.->|Deploy improved model| ToolDecision
    
    Display --> End([🏁 END:<br>User sees complete assessment<br>with interactive visualizations])
    
    style AgentInit fill:#667eea,color:#fff,stroke:#333,stroke-width:4px
    style FirstLLM fill:#764ba2,color:#fff,stroke:#333,stroke-width:3px
    style SecondLLM fill:#764ba2,color:#fff,stroke:#333,stroke-width:3px
    style Collect fill:#9f7aea,color:#fff,stroke:#333,stroke-width:2px
    style FinalReport fill:#48bb78,color:#fff,stroke:#333,stroke-width:3px
    style Display fill:#48bb78,color:#fff,stroke:#333,stroke-width:2px
    style Lightning fill:#f56565,color:#fff,stroke:#333,stroke-width:2px

Loading

Development Notes

• The primary agent logic lives in agent/risk_agent.py.
• Small helpers and feature transforms are in tools/risk_tools.py.
• To extend: add preprocessing functions in tools/, update agent/ logic for new policies, and wire visualizations in ui/visualizations.py.