RiskLens AI — Credit Analyst Copilot

RiskLens AI is a production-ready demo of an AI-powered credit analyst copilot for SME lending. It combines real-time financial trend analysis, machine learning-based anomaly and fraud detection, LLM-powered risk narratives, intelligent policy Q&A, document extraction, and voice-driven workflows with comprehensive audit trails for regulatory compliance.

🎯 Core Features

1. Role-Based Credit Workflow

The application implements a complete credit analyst workflow with three distinct user personas:

Applicant: Track application status, upload financial documents, submit transactions, and monitor fraud alerts in real-time
Analyst: Manage application queue, run financial & anomaly analysis, generate AI-powered risk narratives, and forward recommendations to managers
Manager: Review forwarded applications, approve/reject loans with documented decisions, monitor portfolio-level fraud patterns, and audit analyst activities

Status pipeline: submitted → under_analysis → forwarded_to_manager → reviewed → approved|rejected|more_info_needed

Implementation: React Router with role-based page access control in src/App.tsx (lines 97-127); state managed via AppContext for applications, risk outputs, audit log, and transactions.

2. Financial Health Dashboard

Real-time dashboard with dual-view layouts optimized for each user role:

Applicant Dashboard

Application Tracking: Current status, analyst assigned, submission timestamp, loan purpose/amount
Recent Transactions: Last 10 transactions with fraud status indicators
Fraud Status Badge: Visual alert for suspicious/confirmed fraud transactions
Quick Stats: Active applications count, total pipeline value

Analyst Dashboard

Application Queue: Filtered by analyst or manager role, sorted by risk level
Anomaly Heatmap: Color-coded risk scores (green/yellow/red) across applications
AI Confidence: Statistical confidence scores for risk assessments
Pipeline Analytics: Submitted, under_analysis, forwarded, reviewed counts
Trend Analysis: Average processing time, anomaly detection rate

Manager Dashboard

Pending Decisions: Applications forwarded for approval with decision deadline tracking
Fraud Monitor: Real-time transaction heatmap, network graph visualization of fraud relationships
Audit Activity Feed: Analyst actions (submitted, analyzed, forwarded) with timestamps
Portfolio Risk Metrics: Total loan value at risk, concentration by industry/risk tier
Call History: Log of fraud alert calls triggered, outcomes

Implementation: Recharts for visualizations; Framer Motion for animated transitions; responsive grid layouts via Tailwind. Code in src/pages/Dashboard.tsx (lines 33-547).

3. Financial Metrics Engine

Automated computation of lending-relevant financial metrics from uploaded CSV/PDF data:

Computed Metrics

Liquidity Ratios: Current ratio, quick ratio, cash ratio
Profitability: Gross margin %, net margin %, ROA, ROE
Efficiency: Asset turnover, inventory turnover (where applicable)
Growth Rates: 12-month revenue growth %, expense growth %, net income CAGR
Volatility: Standard deviation of monthly cash flow, expense variance, revenue stability score
Debt Metrics: Debt-to-equity, debt service coverage ratio (if debt/interest data present)

Trend Analysis

12-month rolling averages for revenue, expenses, net income, cash flow
Month-over-month percentage changes
Seasonal decomposition (if data spans 24+ months)
Confidence intervals (95%) for trend projections

Implementation: src/services/metricsEngine.ts (lines 58-109); parses CSV transactions and aggregates by month. Zero external dependencies—all calculation is rule-based for explainability.

4. Anomaly & Fraud Detection

Multi-stage statistical and heuristic anomaly detection without ML black boxes:

Detection Methods

A. Statistical Outliers

Z-Score Thresholding: Flag transactions > 2.5σ from mean amount
IQR Method: Mark as outlier if Q3 + 1.5×IQR or Q1 - 1.5×IQR
Isolation: Detect low-frequency transactions (fewer than 1 per month)

B. Fraud Heuristics

Round-Tripping: Detect circular cash flows (A → B → C → A) within 7-day window; flag as high-risk
Amount Spikes: Transaction 200%+ above recent average in same category
Irregular Timing: Transactions outside business hours (23:00–06:00)
Frequency Anomalies: 3x+ increase in transaction count vs. baseline week
Duplicate Patterns: Same amount/recipient within 24 hours

C. Business Logic Flags

Weekend/holiday transactions for B2B businesses (configurable)
High-velocity small transactions (structuring indicator)
Cross-border transfers with insufficient documentation

Anomaly Scoring

Each detected anomaly receives a confidence score (0–100):

High severity (80–100): Round-tripping, >300% amount spike
Medium severity (50–79): 200% spike, irregular timing + unusual frequency
Low severity (20–49): Minor spikes, isolated frequency anomalies

Implementation: src/services/anomalyDetector.ts (lines 11-199); rule-based classification ensures explainability for credit committees.

5. AI Risk Explanations (Gemini 1.5)

LLM-powered narrative generation for risk assessments using Google's Gemini API with production-grade safety and resilience:

Risk Narrative Generation

Generates a 200–400-word narrative covering:

Financial Health Summary: Key metrics interpretation (e.g., "healthy cash flow but declining margin")
Red Flags Identified: Prioritized list of anomalies and their business implications
Fraud Risk Assessment: Probability estimate based on detected signals
Recommendation: APPROVE / REVIEW / REJECT with confidence level
Regulatory Notes: Compliance considerations (e.g., structuring indicators)

Prompt Engineering: Context-aware prompts with transaction history, metrics, anomalies, and loan parameters to guide response tone and structure.

Per-Anomaly Explanations

When an analyst clicks "Explain with AI" on an individual anomaly:

What It Means: Plain-language interpretation of the detected pattern
Why It Matters: Business risk implications
Frequency Baseline: How unusual this pattern is statistically
False Positive Likelihood: Confidence that this is genuine concern vs. noise

Example: For a round-tripping anomaly: "Three transactions form a circular pattern (Invoice A → Check to Vendor B → Vendor B transfers to your account) within 48 hours, suggesting potential cash acceleration or layering activity. This pattern appears in ~2% of legitimate SME transactions."

Safety & Reliability

Caching: Identical requests within 24 hours use cached responses (reduces latency, cost)
Retry Logic: Exponential backoff (3 attempts, 1–4 second intervals)
Safety Settings: Blocked content categories disabled for financial context; all outputs reviewed before display
Fallback: Pre-computed explanations for demo mode; graceful degradation if API unavailable

Implementation: src/lib/gemini.ts (lines 37-479); integration points in src/pages/ApplicationDetail.tsx (lines 602-654) and src/components/dashboard/AnomalyAlerts.tsx (lines 168-193).

6. Policy Copilot & Q&A

Intelligent policy assistant combining keyword search with optional LLM summarization:

Policy Retrieval

Synthetic Policy Database: 70+ pre-loaded credit policy snippets covering loan criteria, fraud triggers, documentation requirements, industry exceptions (src/data/policySnippets.ts, lines 13-94)
Keyword Search: TF-IDF-like matching on query against policy snippet titles and content
Multi-Match: Returns top 3–5 relevant snippets with relevance scores

Gemini Summarization

Takes retrieved snippets and user query
Generates concise direct answer (2–3 sentences)
Includes policy reference number and approval criteria
Maintains consistency with bank's tone

Example Workflow

User Query: "Can we approve seasonal businesses?" Retrieved Snippets:

"SME Criteria: Industry-specific guidelines—seasonal businesses may require higher reserves"
"Cash Flow: Minimum 12-month operating history required"

Gemini Summary: "Yes, seasonal businesses are eligible under SME criteria, provided they document 12+ months of operating history and maintain reserves 20% above average monthly expenses. Reference: Policy 4.2.1."

Implementation: src/components/dashboard/PolicyCopilot.tsx (lines 27-95); policy data in src/data/policySnippets.ts.

7. Document Processing & Extraction

LLM-powered document understanding for bank statements, tax returns, and financial reports:

Supported Formats

CSV (direct import, auto-parsed into transaction records)
TXT (parsed as semi-structured data)
PDF (metadata only; content extraction planned)

Extraction Pipeline

Upload & Preview: User uploads file; content displayed in preview pane
Gemini Analysis: Sends document content to Gemini with extraction prompt
Structured Output: Extract key fields:
- Business name, tax ID, industry
- Period covered (start/end date)
- Total revenue, expenses, net income
- Key line items (by category)
- Anomalies detected in document (e.g., unusually high expense categories)
Validation: Check for required fields; flag incomplete/ambiguous data

Extraction Example

Input Document (Bank Statement):

Statement for: Acme Corp
Period: Jan 1 – Mar 31, 2025
Deposits: $150,000
Withdrawals: $120,000
Average Daily Balance: $25,000

Extracted Data:

{
  "business_name": "Acme Corp",
  "revenue": 150000,
  "expenses": 120000,
  "net_income": 30000,
  "analysis_period": "Q1 2025",
  "anomalies": ["Unusual spike in withdrawals on Feb 15"]
}

Implementation: src/pages/DocumentsPage.tsx (lines 31-182); Gemini integration via src/lib/gemini.ts (lines 481-538).

8. Transaction Monitoring & Fraud Analysis

Real-time transaction submission and fraud scoring with optional voice-based fraud alerts:

Transaction Submission (Applicant)

Submit individual transaction record: date, amount, payee, category, description
Each transaction auto-scored for fraud likelihood
Immediate feedback: ✅ Low Risk / ⚠️ Suspicious / 🚨 High Risk
Pattern matching against historical anomalies

Fraud Analytics (Manager)

Heatmap Visualization: Transactions plotted on 2D grid (amount vs. frequency) with color intensity indicating fraud probability
Network Graph: Visualize transaction relationships; identify circular patterns, common counterparties, money flow clusters
Filtering & Sorting: By amount, date, category, payee, fraud score
Batch Actions: Flag multiple transactions, initiate voice call

Fraud Scoring Algorithm

Baseline Score: 0–100 derived from anomaly detection
Boosters:
- Round-tripping detected: +40 points
- Amount spike (>200%): +25 points
- Irregular timing: +15 points
- Frequency spike: +20 points
- Known fraud patterns in network: +30 points
Suppressors:
- Transaction matches documented invoice: -15 points
- Payee is known vendor: -10 points
- Within seasonal variance: -10 points

Voice Alert Integration

Manager clicks "Call to Verify" on high-fraud transaction
Triggers Python FastAPI voice-agent service to initiate Twilio call
Voice agent asks standard verification questions
Call outcome logged in audit trail

Implementation:

Transaction submission: src/pages/TransactionsPage.tsx (lines 59-116)
Fraud analytics: src/pages/TransactionsPage.tsx (lines 445-683)
Fraud scoring: src/lib/gemini.ts (lines 551-646)
Voice agent: voice-agent/main.py (lines 73-285) and voice-agent/websocket_handler.py

9. Voice Assistant & Briefings

Multi-modal voice interaction powered by ElevenLabs or browser TTS:

Executive Risk Brief (Text-to-Speech)

One-click generation of spoken 2–3 minute briefing covering:

Top 3 Risk Factors: Ranked by severity
Overall Recommendation: APPROVE / REVIEW / REJECT
Key Anomalies: Most critical findings
Next Steps: Suggested follow-up actions

Voice Engine Options:

ElevenLabs TTS (production): Premium natural voice, 11 voices available, streaming support, accent/emotion control
Browser TTS (fallback): Native browser SpeechSynthesis API, works offline, no API key required

Output: Audio streamed to browser with play/pause/download controls.

Voice Call Integration (Python Service)

Real-Time Conversational Agent: Powered by ElevenLabs Conversational AI + custom prompts
Fraud Alert Calls: Automated outbound calls for suspicious transactions
Agent Types: Fraud verifier, KYC interviewer, loan status checker
Call Routing: Dynamic transfer between agents mid-call
Audio Bridge: Browser WebSocket ↔ ElevenLabs Conversational WS ↔ Twilio SIP

Implementation:

Text-to-speech: src/components/voice/VoiceAssistant.tsx (lines 75-105)
Voice agent service: voice-agent/main.py, voice-agent/websocket_handler.py
Frontend dialer: voice-agent/static/app.js (lines 100-331)

10. Risk Report Generation

Downloadable PDF risk assessment reports with comprehensive metrics and visualizations:

Report Sections

Executive Summary: 1-page overview with recommendation, confidence, key metrics
Financial Analysis: Charts for revenue, expenses, net income trends (12-month); calculated ratios
Anomaly Report: Detailed table of all detected anomalies with severity, confidence, explanation
AI Risk Narrative: Full LLM-generated narrative (from feature #5)
Decision Log: Analyst and manager notes, timestamps, approval/rejection reason
Appendix: Policy references, methodology (z-score, IQR, heuristics explained)

Visualizations

Line charts: Revenue/expense trends with confidence bands
Heatmap: Monthly net income by year
Table: Anomaly details with color-coded severity
Waterfall: Revenue → Expenses → Net Income flow

Export Options

PDF (with branding, formal layout)
CSV (metrics, anomalies, decision log)

Implementation: src/lib/pdfReport.ts (lines 8-298); uses jsPDF + HTML2Canvas for PDF generation.

11. Audit Trail & Compliance

Comprehensive logging of all analyst and manager actions for regulatory review:

Logged Events

Application submission (with auto-generated timestamp, applicant ID)
Analysis start/completion (analyst ID, duration, AI models used)
Forward to manager (analyst notes, risk score snapshot)
Approval/Rejection/More Info (manager ID, decision, rationale, timestamp)
AI explanation generated (model version, prompt hash for reproducibility)
Transaction fraud call initiated (manager ID, transaction ID, call outcome)
Policy query (analyst query text, retrieved snippets, timestamp)

Audit Log Table (`audit_log` in Supabase)

CREATE TABLE audit_log (
  id UUID PRIMARY KEY,
  application_id UUID REFERENCES applications(id),
  action VARCHAR (e.g., 'submitted', 'analyzed', 'forwarded', 'approved'),
  actor_id VARCHAR,
  actor_role VARCHAR,
  details JSONB (action-specific data),
  timestamp TIMESTAMP WITH TIME ZONE,
  ip_address INET (optional)
);

Audit Dashboard (Manager-Only)

Timeline view of all actions on an application
Filter by actor, action type, date range
Export audit log for compliance reports

Implementation: Logged in src/pages/ApplicationDetail.tsx (lines 602-654); accessible in src/pages/AuditTrailPage.tsx; stored in Supabase audit_log table.

12. Supabase Backend Integration

Optional SQL backend for persistent storage, authentication, and real-time sync:

Database Schema (`supabase/migrations/001_initial_schema.sql`)

applications Table:

- id (UUID primary key)
- applicant_id (foreign key to auth.users)
- analyst_id (optional, assigned when analysis starts)
- manager_id (optional, assigned when forwarded)
- status (pending → analyzing → reviewed → approved/rejected/more_info)
- industry (e.g., retail, manufacturing, services)
- loan_amount (numeric, in currency)
- loan_purpose (text)
- business_size (e.g., micro, small, medium)
- years_in_business (integer)
- created_at, updated_at (timestamps)
- metadata (JSONB: custom fields)

documents Table:

- id (UUID primary key)
- application_id (foreign key)
- file_name (text)
- file_type (csv, pdf, txt)
- uploaded_by (user ID)
- extracted_json (JSONB: structured extracted data)
- created_at

risk_outputs Table:

- id (UUID primary key)
- application_id (foreign key)
- financial_metrics (JSONB: computed metrics)
- anomalies (JSONB array: detected anomalies + confidence)
- ai_explanation (text: full LLM narrative)
- recommendation (APPROVE/REVIEW/REJECT)
- confidence_score (0–100)
- risk_factors (JSONB array: top 5 risk factors ranked)
- created_at

audit_log Table: (As described in feature #11)

transactions Table:

- id (UUID primary key)
- application_id (foreign key)
- date, amount, payee, category, description
- fraud_score (0–100)
- fraud_status (low_risk, suspicious, high_risk)
- created_at

Row-Level Security (RLS)

Applicants can view only their own applications
Analysts can view applications assigned to them + those forwarded to their manager
Managers can view all forwarded applications + audit logs
Audit logs are append-only (insert-only, no updates/deletes)

Real-Time Sync (Optional)

Frontend subscribes to application status changes
Notifications push to dashboard when application forwarded or decision made
Audit log updated in real-time for manager monitoring

Implementation:

Supabase client: src/lib/supabase.ts (lines 3-10)
SQL migrations: supabase/migrations/001_initial_schema.sql (lines 11-131)
Optional backend integration points in src/App.tsx (lines 57-70)

🏗️ Architecture

Frontend (TypeScript, 78%)

src/
├── main.tsx                     # React root entry
├── App.tsx                      # Global context, routes, role-based pages
├── types/                       # TypeScript interfaces (Application, RiskOutput, Transaction, etc.)
├── components/
│   ├── layout/                  # Sidebar, header, outlet (Framer Motion animations)
│   ├── dashboard/               # Dashboard views (applicant, analyst, manager)
│   ├── upload/                  # File upload, CSV parsing, preview
│   ├── voice/                   # Voice assistant UI, TTS controls
│   └── [other UI components]
├── pages/
│   ├── Login.tsx                # Demo mode switcher (applicant/analyst/manager)
│   ├── Dashboard.tsx            # Role-specific dashboards
│   ├── ApplicationDetail.tsx     # Full application view + analysis pipeline UI
│   ├── DocumentsPage.tsx        # Document upload & extraction
│   ├── TransactionsPage.tsx     # Transaction submission & fraud analytics
│   ├── PolicyPage.tsx           # Policy Q&A interface
│   └── AuditTrailPage.tsx       # Manager-only audit log
├── services/
│   ├── metricsEngine.ts         # Financial metrics calculation
│   ├── anomalyDetector.ts       # Statistical & heuristic anomaly detection
│   ├── analysisPipeline.ts      # Orchestrate parse → metrics → anomalies → AI
│   └── fileParser.ts            # CSV/PDF/TXT parsing
├── lib/
│   ├── gemini.ts                # Gemini API integration (caching, retry, safety)
│   ├── elevenlabs.ts            # ElevenLabs TTS integration
│   ├── supabase.ts              # Supabase client + optional backend calls
│   ├── pdfReport.ts             # PDF report generation
│   └── utils.ts                 # Common utilities (formatting, validation)
├── data/
│   ├── synthetic.ts             # 3 pre-baked SME applications + synthetic transactions
│   ├── policySnippets.ts        # 70+ policy snippets for Q&A
│   └── constants.ts             # UI strings, color scales, thresholds
└── styles/
    └── globals.css              # Tailwind + custom CSS

Backend (Python, 7.4%)

voice-agent/
├── main.py                      # FastAPI app, routes, Twilio webhooks
├── config.py                    # ElevenLabs, Twilio, LLM config
├── agents.py                    # Agent personas, prompts, transfer logic
├── websocket_handler.py         # WS bridge: browser ↔ ElevenLabs Conversational
├── requirements.txt             # FastAPI, ElevenLabs, Twilio, python-dotenv
└── static/
    ├── index.html               # Phone dialer UI
    └── app.js                   # Phone UI logic + WebSocket client

Database (PL/pgSQL, 1%)

supabase/migrations/
└── 001_initial_schema.sql       # Tables: applications, documents, risk_outputs, audit_log, transactions

🚀 Getting Started

Prerequisites

Node.js 18+ (for frontend)
Python 3.9+ (for voice-agent service, optional)
Supabase account (optional, for persistent backend)
API Keys (optional, for live AI/voice):
- Google AI Studio API key (Gemini)
- ElevenLabs API key
- Twilio account (for voice calls)

Installation

1. Frontend Setup

git clone https://github.com/smshozab/RiskLens-AI.git
cd RiskLens-AI

# Install dependencies
npm install

# Copy environment template
cp .env.example .env.local

# Optional: Add API keys to .env.local
# VITE_GEMINI_API_KEY=your_key
# VITE_ELEVENLABS_API_KEY=your_key
# VITE_SUPABASE_URL=your_url
# VITE_SUPABASE_ANON_KEY=your_key

# Start dev server
npm run dev

Access: Open http://localhost:5173 in your browser

2. Backend Setup (Optional)

cd voice-agent

# Create Python virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with Twilio, ElevenLabs, Gemini credentials

# Start FastAPI server
uvicorn main:app --reload --port 8000

3. Supabase Setup (Optional)

# Create Supabase project at https://supabase.com
# Copy project URL and anon key to .env.local

# Run migrations
# Option A: Use Supabase UI → SQL Editor → paste supabase/migrations/001_initial_schema.sql
# Option B: Use CLI
supabase db push

# Create private Storage bucket named "documents"

Quick Demo (No Setup Required)

Open http://localhost:5173
Click "Launch Demo Experience"
Select persona: Applicant, Analyst, or Manager
Explore pre-loaded applications and synthetic data

Demo Applications:

QuickTrade Logistics: High-risk case with multiple anomalies (round-tripping, amount spikes)
GreenLeaf Organics: Healthy profile, low risk, strong metrics
Meridian Textiles: Borderline case (declining revenue, but stable cash flow)

📋 Environment Variables

Frontend (`.env.local`)

# Supabase (optional)
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your_anon_key

# AI Services (optional)
VITE_GEMINI_API_KEY=your_gemini_api_key
VITE_GEMINI_MODEL=gemini-1.5-pro  # or gemini-1.5-flash

# Voice Services (optional)
VITE_ELEVENLABS_API_KEY=your_elevenlabs_key
VITE_ELEVENLABS_VOICE_ID=Adam  # or other voice ID

# Feature Flags
VITE_ENABLE_VOICE_AGENT=true
VITE_ENABLE_SUPABASE=false

Backend (`voice-agent/.env`)

# ElevenLabs
ELEVENLABS_API_KEY=your_key
ELEVENLABS_AGENT_ID=your_agent_id

# Twilio
TWILIO_ACCOUNT_SID=your_sid
TWILIO_AUTH_TOKEN=your_token
TWILIO_PHONE_NUMBER=+1234567890

# LLM
OPENAI_API_KEY=your_key  # or Gemini key

# Server
FRONTEND_URL=http://localhost:5173
VOICE_AGENT_PORT=8000

🛠️ API Reference

Frontend Services

Anomaly Detection

import { detectAnomalies } from '@/services/anomalyDetector';

const anomalies = detectAnomalies(transactions, {
  zScoreThreshold: 2.5,
  iqrMultiplier: 1.5,
  detectRoundTripping: true,
  detectFrequencySpikes: true,
});

// Output: Array<Anomaly>
// - type: 'amount_spike' | 'round_trip' | 'irregular_timing' | ...
// - severity: 'low' | 'medium' | 'high'
// - confidence: number (0-100)
// - explanation: string

Metrics Engine

import { computeMetrics } from '@/services/metricsEngine';

const metrics = computeMetrics(transactions, options);

// Output: FinancialMetrics
// - revenue: number
// - expenses: number
// - netIncome: number
// - cashFlow: number
// - ratios: { currentRatio, quickRatio, debtToEquity, ... }
// - trends: { revenueGrowth%, expenseGrowth%, volatility, ... }

Gemini Integration

import { generateRiskNarrative, explainAnomaly, generateFraudScore } from '@/lib/gemini';

// Risk narrative
const narrative = await generateRiskNarrative(application, metrics, anomalies);

// Per-anomaly explanation
const explanation = await explainAnomaly(anomaly, context);

// Fraud scoring
const score = await generateFraudScore(transaction, historicalContext);

PDF Report

import { generateRiskReport } from '@/lib/pdfReport';

const pdf = await generateRiskReport(application, metrics, anomalies, narrative);
// Returns Blob; trigger download or email

Backend API (Voice Agent)

Endpoints

POST /api/agents - List available agents

{
  "agents": [
    { "id": "fraud_verifier", "name": "Fraud Verification Agent", "prompt": "..." },
    { "id": "kyc_interviewer", "name": "KYC Interviewer", "prompt": "..." }
  ]
}

POST /api/trigger-fraud - Initiate fraud alert call

{
  "phone": "+1234567890",
  "transaction_id": "txn_123",
  "amount": 5000,
  "payee": "Unknown Vendor",
  "callback_url": "https://yourapp.com/webhook"
}

WS /ws/call - Real-time call audio bridge

Browser streams audio → Python → ElevenLabs Conversational WS → Twilio SIP
Bidirectional audio; supports agent transfer via message

WS /ws/signal - Call events (incoming, missed, transfer, etc.)

🔐 Security & Compliance

Data Privacy

Row-Level Security (RLS): Supabase RLS policies enforce data isolation by role/ownership
Encryption in Transit: HTTPS (frontend) + TLS (API)
Encryption at Rest: Supabase Postgres encryption enabled
No PII in Logs: Personal info redacted from audit trail (only IDs, not names)

Responsible AI

Advisory Only: All AI outputs explicitly labeled as recommendations; final credit decisions with human analysts
Explainability: Anomaly detection uses transparent heuristics (z-score, IQR) not ML black boxes
Audit Trail: Every AI explanation logged (model version, prompt hash, timestamp)
Bias Mitigation: Synthetic data only in demo; production requires fairness assessment

Limitations & Risks

False Positives: Anomaly detection may flag legitimate business patterns (seasonal spikes, one-time large transactions)
False Negatives: Sophisticated fraud may evade heuristic-based detection; requires ML models in production
Synthetic Data: Demo uses made-up applications; real deployment requires validated pipelines and access controls
Policy Q&A: Currently keyword-based; production needs RAG (retrieval-augmented generation) over official policy documents
Voice Call: May trigger false positives; always require human verification before credit decision impact

📦 Tech Stack Details

Frontend Dependencies

React 18.2.0: UI framework
TypeScript 5.x: Type safety
Vite 6.x: Build tool (fast dev server, optimized builds)
TailwindCSS 3.x: Utility-first CSS framework
Framer Motion 10.x: Animation library (smooth page transitions, micro-interactions)
Recharts 2.x: React charting library (line, bar, heatmap visualizations)
React Router 6.x: Client-side routing with role-based access
@google/generative-ai: Gemini API client library
jsPDF + html2canvas: PDF generation
date-fns: Date formatting utilities

Backend Dependencies (Voice Agent)

FastAPI: Async web framework
python-dotenv: Environment variable management
ElevenLabs SDK: Conversational AI + TTS integration
Twilio SDK: Phone call management
aiohttp: Async HTTP client
websockets: WebSocket server for audio bridge

Database

PostgreSQL 15 (via Supabase): ACID compliance, JSON support, RLS
PL/pgSQL: Stored procedures for audit logic (optional)

Deployment-Ready

Docker: Containerization ready for voice-agent (Dockerfile can be created)
CI/CD: GitHub Actions workflows can be added
Scaling: Vite builds to static assets (CDN-ready); FastAPI auto-scales with ASGI server (Gunicorn + Uvicorn)

🗺️ Roadmap & Planned Features

Phase 2 (Planned)

Policy RAG: Full retrieval-augmented generation over bank policy documents; semantic search with embeddings
Document LLM (Enhanced): PDF content extraction, bank statement parsing, automated categorization
ML Anomaly Detection: Isolation Forest + LSTM models for temporal pattern detection (production-grade fraud scoring)
Portfolio Views: Sector concentration, watchlist, stress testing scenarios
Supabase Auth: Full authentication integration (currently demo-mode)
Mobile App: React Native client for applicants and field analysts

Phase 3 (Future)

Graph Analysis: Network analysis to detect fraud rings, money laundering patterns
Regulatory Reporting: Automated SAR (Suspicious Activity Report) generation
Multi-Language: Localization for credit copilot in 5+ languages
API for Third Parties: Expose RiskLens API for bank partners

📝 Demo Flow (Recommended)

For Analysts

Login: Select "Analyst" in demo mode
Dashboard: View application queue (3 apps: high/healthy/borderline risk)
Open QuickTrade Logistics: See high-risk application
Explore Analysis:
- View 12-month financial trends (declining revenue, volatile cash flow)
- Check anomalies detected (round-tripping, 3x transaction spike)
- Click "Explain with AI" on a specific anomaly
- Read full AI-generated risk narrative
Decision: Click "Forward to Manager" with analyst notes
Alternative: Upload a CSV file to run the full pipeline in real-time

For Managers

Login: Select "Manager" in demo mode
Dashboard: See forwarded applications awaiting decision
Fraud Monitor: Visualize transaction heatmap; identify suspicious patterns
Open QuickTrade Logistics:
- Review analyst's recommendation
- Check audit trail (who analyzed, when, AI explanation used)
- Make decision: Approve / Reject / Request More Info
Decision Logged: See decision recorded in audit trail with timestamp

For Applicants

Login: Select "Applicant" in demo mode
Dashboard: See application status, assigned analyst, submission date
Submit Transaction: Add a sample transaction; view fraud score
Monitor Status: Check for analyst progress, manager decision

🤝 Contributing

Contributions welcome! Areas for help:

Add ML anomaly detection models (Isolation Forest, LSTM)
Implement full Supabase auth + edge functions
Build mobile app (React Native)
Add i18n (internationalization)
Expand policy database with real bank policies
Write integration tests for analysis pipeline

📄 License

[Specify your license here, e.g., MIT, Apache 2.0]

💬 Support & Questions

Demo Issues: Check .env.local is configured correctly; see Getting Started
Supabase: Refer to Supabase docs
Gemini API: Google AI Studio
ElevenLabs: ElevenLabs docs

🙏 Acknowledgments

Built with ❤️ for hackathons, credit teams, and responsible AI practitioners. Special thanks to Supabase, Gemini, and ElevenLabs for powerful APIs.

Last Updated: June 2026 | Version: 1.0 | Status: Production-Ready Demo

Name		Name	Last commit message	Last commit date
dist		dist
node_modules		node_modules
public		public
src		src
supabase/migrations		supabase/migrations
voice-agent		voice-agent
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts

Latest commit

History

Folders and files

Repository files navigation

RiskLens AI — Credit Analyst Copilot

🎯 Core Features

1. Role-Based Credit Workflow

2. Financial Health Dashboard

Applicant Dashboard

Analyst Dashboard

Manager Dashboard

3. Financial Metrics Engine

Computed Metrics

Trend Analysis

4. Anomaly & Fraud Detection

Detection Methods

Anomaly Scoring

5. AI Risk Explanations (Gemini 1.5)

Risk Narrative Generation

Per-Anomaly Explanations

Safety & Reliability

6. Policy Copilot & Q&A

Policy Retrieval

Gemini Summarization

Example Workflow

7. Document Processing & Extraction

Supported Formats

Extraction Pipeline

Extraction Example

8. Transaction Monitoring & Fraud Analysis

Transaction Submission (Applicant)

Fraud Analytics (Manager)

Fraud Scoring Algorithm

Voice Alert Integration

9. Voice Assistant & Briefings

Executive Risk Brief (Text-to-Speech)

Voice Call Integration (Python Service)

10. Risk Report Generation

Report Sections

Visualizations

Export Options

11. Audit Trail & Compliance

Logged Events

Audit Log Table (audit_log in Supabase)

Audit Dashboard (Manager-Only)

12. Supabase Backend Integration

Database Schema (supabase/migrations/001_initial_schema.sql)

Row-Level Security (RLS)

Real-Time Sync (Optional)

🏗️ Architecture

Frontend (TypeScript, 78%)

Backend (Python, 7.4%)

Database (PL/pgSQL, 1%)

🚀 Getting Started

Prerequisites

Installation

1. Frontend Setup

2. Backend Setup (Optional)

3. Supabase Setup (Optional)

Quick Demo (No Setup Required)

📋 Environment Variables

Frontend (.env.local)

Backend (voice-agent/.env)

🛠️ API Reference

Frontend Services

Anomaly Detection

Metrics Engine

Gemini Integration

PDF Report

Backend API (Voice Agent)

Endpoints

🔐 Security & Compliance

Data Privacy

Responsible AI

Limitations & Risks

📦 Tech Stack Details

Frontend Dependencies

Backend Dependencies (Voice Agent)

Database

Deployment-Ready

Audit Log Table (`audit_log` in Supabase)

Database Schema (`supabase/migrations/001_initial_schema.sql`)

Frontend (`.env.local`)

Backend (`voice-agent/.env`)