Skip to content

AI Agent: New Loan Features

Overview

Enhanced the AI Agent with 6 new loan-related tools to provide staff with comprehensive loan management insights through natural language conversations.

New Tools Added

1. get_loan_repayments

  • Description: Get repayment history for a specific loan
  • Parameters:
  • loan_id (required): The loan ID
  • page_size (optional): Results per page (default: 10)
  • page_number (optional): Page number (default: 1)
  • Returns: List of repayments with amount, payment date, reference, and status
  • Example: "Show me the repayment history for loan 456"

2. get_loan_installments

  • Description: Get installment schedule for a specific loan
  • Parameters:
  • loan_id (required): The loan ID
  • page_size (optional): Results per page (default: 10)
  • page_number (optional): Page number (default: 1)
  • Returns: List of installments with due dates, principal, interest, total amount, and status
  • Example: "What is the installment schedule for loan 789?"

3. get_loan_balance

  • Description: Get current loan balance and repayment status
  • Parameters:
  • loan_id (required): The loan ID
  • Returns: Principal amount, total repaid, outstanding balance, status, and currency
  • Example: "What is the outstanding balance for loan 789?"

4. list_collection_cases

  • Description: Get collection cases and actions for a specific loan
  • Parameters:
  • loan_id (required): The loan ID
  • page_size (optional): Results per page (default: 10)
  • page_number (optional): Page number (default: 1)
  • Returns: Collection cases with case number, status, and action counts
  • Example: "List all collection cases for loan 123"

5. get_loan_score_history

  • Description: Get loan scoring history for a customer/borrower
  • Parameters:
  • borrower_id (required): Customer identity ID
  • page_size (optional): Results per page (default: 10)
  • page_number (optional): Page number (default: 1)
  • Returns: List of score logs with scores, risk levels, and dates
  • Example: "Get the loan score history for customer 456"

6. get_blacklist_status

  • Description: Check if a customer is blacklisted for loans
  • Parameters:
  • borrower_id (required): Customer identity ID
  • Returns: Blacklist status, reason, and date if blacklisted
  • Example: "Is customer 789 blacklisted?"

Files Modified

1. controller/ai_agent.py

  • Added imports: LoanRepayment, LoanBlacklist, LoanScoreLog from models.loan
  • Updated SYSTEM_PROMPT: Documented new loan detail tools
  • Added to OPENAI_TOOLS: 6 new tool definitions with parameters and descriptions
  • Enhanced execute_tool(): Added handlers for all 6 new loan tools with proper serialization

2. docs/ai_agent_module.md

  • Reorganized Tools section: Grouped tools by category (Customer & Transactions, Loan Products & Applications, Loan Management & Details, Staff & Organization, Transaction Insights, Onboarding)
  • Added NEW badge: Highlighted new loan management tools
  • Updated Example prompts: Added 5 new example prompts demonstrating the new features

Implementation Details

Tool Design Principles

  1. Relationship-based queries: Leverages existing ORM relationships (loan.repayments, loan.installments, loan.cases)
  2. Safe serialization: Uses _serialize() helper and JSON-safe conversions for decimal/datetime types
  3. Error handling: Wrapped in try-catch with CustomException handling
  4. Pagination support: Most tools support page_size and page_number parameters
  5. User-friendly output: Returns clean, LLM-friendly JSON without internal IDs unless necessary

Integration Points

  • All tools use existing LoanService methods (get_loan())
  • Direct database queries for complex filtering (e.g., LoanScoreLog, blacklist status)
  • Respects existing permission model via current_user parameter

Usage Examples

User: "Show me the repayment history for loan 456"
Agent: Lists all repayments with dates and amounts

User: "What is the outstanding balance for loan 789?"
Agent: Returns principal, repaid, and outstanding amounts

User: "Is customer 123 blacklisted?"
Agent: Confirms blacklist status and reason if applicable

User: "List all collection cases for loan 456"
Agent: Shows all collection cases and related actions

User: "Get the loan score history for customer 789"
Agent: Shows scoring history with risk levels

User: "What are the installments for loan 456?"
Agent: Displays full installment schedule with payment dates

Benefits

  1. Enhanced Visibility: Staff can quickly access comprehensive loan details through conversational AI
  2. Self-Service: Reduces need to manually query databases or multiple screens
  3. Better Decision Making: Instant access to repayment history, scoring, and blacklist status
  4. Operational Efficiency: Speeds up loan inquiries and customer service

Testing Recommendations

  1. Test with various loan IDs (with/without repayments, installments, collection cases)
  2. Verify pagination works correctly for large datasets
  3. Test with blacklisted and non-blacklisted customers
  4. Verify proper error handling for non-existent loans/customers
  5. Test multi-turn conversations combining new tools with existing ones

Future Enhancements

  1. Add loan fraud case information
  2. Add loan guarantee and collateral details
  3. Add loan products comparison
  4. Add affordability analysis tool
  5. Add loan statement generation