---
title: Career Success TenzorX
emoji: ๐
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
---
PlacementIQ
Agentic AI Career Risk Intelligence Platform
A Poonawalla Fincorp initiative โ AI-powered education-loan placement risk prediction for lenders,
built on a multi-agent architecture with real-time market intelligence.
---
## ๐ฌ Demo & Live Preview
> **๐ฅ Full Demo Video** โ [**Watch on Google Drive**](https://drive.google.com/drive/folders/1yOtAta0nSEQPCaNb2IFFw2OgZiMW4W31?usp=sharing)
>
> A walkthrough of the working prototype covering all 8 pages, the 5 AI agents, real-time market intelligence, drift monitoring, and the cold-start scoring engine.
| Surface | URL (when running locally) |
|---|---|
| ๐ **Frontend (React)** | [http://localhost:5173](http://localhost:5173) |
| โก **Backend API (FastAPI)** | [http://localhost:8001](http://localhost:8001) |
| ๐ **Interactive API Docs (Swagger)** | [http://localhost:8001/docs](http://localhost:8001/docs) |
---
## ๐ Table of Contents
1. [Overview](#-overview)
2. [Key Features](#-key-features)
3. [Architecture](#-architecture)
4. [The AI Agent System](#-the-ai-agent-system)
5. [Tech Stack](#-tech-stack)
6. [Getting Started](#-getting-started)
7. [Quick Verification](#-quick-verification)
8. [Outputs โ Working Prototype Screenshots](#-outputs--working-prototype-screenshots)
9. [API Reference](#-api-reference)
10. [Frontend Pages](#-frontend-pages)
11. [Configuration](#-configuration)
12. [Model Performance](#-model-performance)
13. [Project Structure](#-project-structure)
---
## ๐ Overview
**PlacementIQ** is an intelligent risk-assessment platform purpose-built for **education-loan portfolios**. It predicts whether a borrower (student) will secure employment within **3 / 6 / 12 months** of graduation โ enabling **proactive intervention** before loan defaults occur.
The platform combines **deterministic ML models** for speed with **LLM-powered agents** for contextual depth, all grounded in **live market data** from public APIs.
| Layer | Technology | Purpose |
|---|---|---|
| ๐งฎ **ML Scoring Engine** | XGBoost + LightGBM | Fast, deterministic base risk scores (~50ms) |
| ๐ **SHAP Explainability** | TreeExplainer | Feature-level contribution to each score |
| ๐ค **Multi-Agent AI System** | LLM Orchestrator (5 agents) | Deep contextual reasoning & intervention planning |
| ๐ **Real Market Data** | World Bank + India job portals | Live demand signals, macro-climate index |
---
## ๐งฉ Key Features
- โ
**Hybrid AI** โ ML models for speed + LLM agents for depth
- ๐ **Real Market Data** โ World Bank macro indicators + India job-portal signals
- ๐ฌ **SHAP Explainability** โ Every score includes feature-level explanations
- ๐ **Multi-Provider LLM** โ Switch between Groq, Anthropic, OpenAI, OpenRouter via `.env`
- โก **In-Memory Caching** โ Prevents LLM rate limiting during portfolio scans
- ๐ **Dark / Light Themes** โ Full theme toggle with Poonawalla Fincorp branding
- ๐ก **32 API Endpoints** โ Comprehensive REST API for all platform capabilities
- ๐ **PSI Drift Monitoring** โ Automated model-stability tracking
- ๐ **Compliance-Ready** โ Audit trail + exportable reports for RBI FLDG guidelines
- ๐งช **Cold-Start Scoring** โ Synthetic placement scoring for institutes with no history
---
## ๐๏ธ Architecture
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ React Frontend (Vite + React 19) โ
โ Dashboard โ Portfolio โ Heatmap โ Reports โ Institutes โ
โ AI Agents โ Admin Panel โ Student Profile โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ REST API (JSON)
โโโโโโโโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ FastAPI Backend (port 8001) โ
โ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโ โ
โ โ Scoring โ โ Agent โ โ Real Data โ โ
โ โ Engine โ โ Orchestrator โ โ Fetcher โ โ
โ โ (XGB+LGBM) โ โ (5 agents) โ โ (World Bank) โ โ
โ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโ โ
โ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโ โ
โ โ SHAP โ โ Tool โ โ Data โ โ
โ โ Explainer โ โ Registry โ โ Generator โ โ
โ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
---
## ๐ค The AI Agent System
Five specialized **LLM-powered agents** replace formerly static, hard-coded systems:
| # | Agent | Replaces | Purpose |
|---|---|---|---|
| 1 | **NBA Agent** | Static rule tables | Recommends highest-ROI interventions using SHAP drivers + EMI data |
| 2 | **Explainability Agent** | Hard-coded NLG templates | Translates ML outputs into human-readable risk narratives |
| 3 | **Market Intelligence Agent** | Static WoW thresholds | Detects placement shocks from live labour-market signals |
| 4 | **Career Path Agent** | Static adjacency maps | Recommends career pivots weighted by regional demand |
| 5 | **Offer Survival Agent** | Secondary classifiers | Scores probability of offer revocation using company-health signals |
### ๐ Multi-Provider LLM Support
Switch providers via a single `.env` variable โ no code changes:
| Provider | Model | Best For |
|---|---|---|
| **Groq** | `llama-3.3-70b-versatile` | โก Fastest inference |
| **Anthropic** | `claude-sonnet-3.5` | ๐ ๏ธ Best tool use |
| **OpenRouter** | Aggregator (Claude / Llama / Gemini) | ๐ Flexibility |
| **OpenAI** | `gpt-4o` | ๐ง General purpose |
---
## ๐ ๏ธ Tech Stack
### Backend
| Technology | Version | Purpose |
|---|---|---|
| Python | 3.10+ | Runtime |
| FastAPI | Latest | REST API framework |
| XGBoost | Latest | Classification model |
| LightGBM | Latest | Salary regression model |
| SHAP | Latest | Model explainability |
| LiteLLM | โฅ 1.50 | Multi-provider LLM abstraction |
| Pandas / NumPy | Latest | Data processing |
| Uvicorn | Latest | ASGI server |
### Frontend
| Technology | Version | Purpose |
|---|---|---|
| React | 19 | UI framework |
| Vite | 8 | Build tool & dev server |
| React Router | 7 | Client-side routing |
| Recharts | 3 | Data visualisation |
| Lucide React | Latest | Icon system |
| Axios | Latest | HTTP client |
### Design System
- **Brand**: Poonawalla Fincorp corporate identity
- **Primary Colours**: Navy `#1B2C5E` ยท Corporate Blue `#1E56C7`
- **Typography**: Lato + Inter
- **Themes**: Dark mode (default) + Light mode toggle
---
## ๐ Getting Started
### Prerequisites
| Requirement | Minimum Version |
|---|---|
| **Python** | 3.10+ |
| **Node.js** | 18+ |
| **npm** | 9+ |
| **Git** | Any |
### 1๏ธโฃ Clone the Repository
```bash
git clone https://github.com/your-org/PlacementIQ.git
cd PlacementIQ
```
### 2๏ธโฃ Backend Setup
```bash
cd backend
# Create & activate virtual environment
python -m venv venv
# Windows
.\venv\Scripts\activate
# macOS / Linux
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
```
### 3๏ธโฃ Configure Environment
Create a `.env` file in the `backend/` directory:
```env
# Choose your LLM provider: groq | anthropic | openrouter | openai
PROVIDER=groq
# Provide the matching API key
GROQ_API_KEY=gsk_your_key_here
# ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=sk-...
# OPENROUTER_API_KEY=sk-or-...
```
> ๐ก **Note**: The LLM API key is only required for **agentic features** (NBA, Explainability, Career Paths, Offer Survival). Core ML scoring, the heatmap, shock detection, and all dashboard features work without any key.
### 4๏ธโฃ Generate Synthetic Data
```bash
python data_generator.py
```
Produces `data/synthetic_students.csv` with **10,000 student records**.
### 5๏ธโฃ Start the Backend
```bash
python main.py
```
Backend runs on **[http://localhost:8001](http://localhost:8001)**. Verify:
```bash
curl http://localhost:8001/health
# โ {"status":"ok","students_loaded":10000}
```
### 6๏ธโฃ Frontend Setup
In a **new terminal**:
```bash
cd frontend
npm install
npm run dev
```
Frontend runs on **[http://localhost:5173](http://localhost:5173)**. Open it in your browser.
---
## โ
Quick Verification
After setup, verify these work:
| Check | URL / Action | Expected |
|---|---|---|
| Backend health | `GET http://localhost:8001/health` | `{"status":"ok"}` |
| Dashboard loads | Open `http://localhost:5173` | Portfolio overview with risk cards |
| Student data | `GET http://localhost:8001/api/v1/students?limit=5` | JSON array of 5 students |
| Heatmap data | `GET http://localhost:8001/api/v1/heatmap/demand` | 18-cell demand grid |
| Theme toggle | Click sun/moon icon in sidebar | Switches dark โ light mode |
---
## ๐ธ Outputs โ Working Prototype Screenshots
> All screenshots captured from the live prototype running at `http://localhost:5173` (Frontend) + `http://localhost:8001` (Backend, 10,000 students loaded).
> ๐ฌ **Prefer a video?** [**Watch the full demo on Google Drive โ**](https://drive.google.com/drive/folders/1yOtAta0nSEQPCaNb2IFFw2OgZiMW4W31?usp=sharing)
### ๐๏ธ Quick Index
| # | Module | Output |
|---|---|---|
| 1โ3 | **Dashboard** | Cohort overview, charts, priority watchlist |
| 4 | **Heatmap** | Field ร Region demand grid |
| 5โ7 | **Reports & Drift** | PSI monitor, bulk scoring, score history |
| 8โ10 | **Institutes** | Momentum, peer velocity, cold-start |
| 11โ12 | **AI Agents** | Command centre + live pipeline output |
| 13โ15 | **Admin Panel** | Risk thresholds, NBA costs, model + fairness |
---
### 1. Portfolio Cohort Dashboard โ Overview
> Main landing page. Real-time KPIs: **10,000** total portfolio ยท **1,441 HIGH-risk** students ยท **36.4%** 6-month placement velocity ยท **7.31** avg CGPA ยท **5 AI agents** active. Includes a live placement-shock alert (IT Services) and the Early Alert Engine summary.
---
### 2. Dashboard โ Risk Distribution, Placement Velocity & Regional Breakdown
> Three analytics panels: (1) Donut chart splitting 10K students into High / Medium / Low risk bands. (2) Placement-velocity progress bars for 3-month (2.8%), 6-month (36.4%) and 12-month (80.3%) horizons. (3) Top Regions bar chart and Course Mix breakdown (MBA 3,408 ยท Engineering 3,302 ยท Nursing 3,290).
---
### 3. Priority Student Watchlist
> Filterable table of at-risk students. Columns: Student ID, Course + Tier + Region, CGPA (colour-coded), Monthly EMI, 6M placement status (dot indicator), Risk Band badge (HIGH / MEDIUM / LOW), and a one-click **Analyze** button. Filter tabs for ALL / HIGH / MEDIUM / LOW.
---
### 4. Dynamic Employability Heatmap
> Real-time **Field ร Region demand grid** sourced from World Bank + India job-portal data. Rows: Engineering, MBA, Nursing. Columns: Bengaluru, Hyderabad, Delhi NCR, Pune, Mumbai, Chennai. Each cell shows a demand score (0โ100), YoY trend, and risk level. Avg demand: Engineering 73/100, MBA 75/100, Nursing 76/100.
---
### 5. Reports & Analytics โ Model Drift Monitor (PSI)
> Population Stability Index panel. **Overall PSI: 0.025 (STABLE)** ยท Last 30 days ยท No alerts. Feature-level PSI bars for `lgbm`, `field_demand_score`, `behavioral_activity_score`, `macro_climate_index`, `fd`, `internship_months` โ all within acceptable drift bounds.
---
### 6. Reports & Analytics โ Bulk Portfolio Scoring (F-09)
> Batch scoring tool: paste up to **1,000 Student IDs**, click **Run Batch Score**. Results table shows Risk Band, 6M placement probability, Expected Salary, and EMI Comfort ratio per student. Example: STU-2026-00001 โ **HIGH** risk, 99% prob, โน99,000 salary, 0.28ร EMI comfort.
---
### 7. Reports & Analytics โ 90-Day Score History & Trend (F-11)
> Longitudinal view of a student's placement-probability trajectory over **90 days** (FebโApr 2026). Line chart with weekly snapshots and risk-band threshold lines. STU-2026-00003 shows an **Improving** trend, crossing from MEDIUM toward LOW risk band.
---
### 8. Institute Intelligence โ Momentum Index (10.12)
> Horizontal bar chart ranking institutes by recruiter-visits-to-offers ratio. **IIT Bombay** STRONG (1.2ร) ยท **BITS Pilani** STABLE (1.16ร) ยท **NIT Pune** STABLE (0.97ร). Alert flags **3 institutes** in declining momentum โ automatic tier-score adjustments applied.
---
### 9. Institute Intelligence โ Batch Peer Velocity Tracker (F-11)
> Cohort-level placement-velocity grid broken down by **Course ร Institute Tier**. Cards show total cohort size, % placed, and alert status (Critical / Stable / Normal). Identifies Engineering Tier-A 2026 cohorts as **Critical** โ lagging, students urgently need intervention.
---
### 10. Institute Intelligence โ Cold-Start Scoring (F-09)
> AI-based **synthetic scoring for new institutes** with no historical placement data (PRD 9.17). Input: NAAC Grade + City Tier. Output for "New Engineering College, Pune" (B+, Tier 2): **75.3%** synthetic placement probability ยท **โน50,000** avg salary forecast ยท **MEDIUM** confidence. Nearest reference institutes shown.
---
### 11. Agentic AI Command Center โ 5 Live Agents
> Real-time view of all 5 AI agents: **NBA Agent**, **Explainability Agent**, **Market Intel Agent**, **Career Path Agent**, **Offer Survival Agent**. Live Agent Demo panel + System Architecture Flow diagram show how the orchestrator routes between ML models and JSON responses.
---
### 12. Agentic AI โ Live Pipeline JSON Output
> Full agentic-pipeline execution result for **STU-2026-00001**. Shows raw JSON response from the orchestrator: `risk_band`, `placement_score`, `salary_range`, `shap_values`, `recommendations`, `confidence`, `percentage`, `data_gap` โ alongside the Agent Capabilities & Tools reference table.
---
### 13. Admin Configuration Panel โ Risk Band & EMI Thresholds (F-12)
> Lender-configurable risk thresholds. Dual sliders set **HIGH / MEDIUM cutoffs** for 6-month placement probability. **EMI Comfort Tier** sliders set Comfortable / Adequate / Tight boundaries. Lender profile: Demo Fincorp ยท UNO-DEMO-001 ยท 50,000 max students ยท MFA enabled.
---
### 14. Admin โ Early Alert Engine & NBA Intervention Cost Table
> **Early Alert Engine**: configurable Critical CGPA threshold (6) and Medium CGPA threshold (7), max 100 alerts per run. **NBA Intervention Cost Table** lists ROI inputs used by the Next-Best-Action simulator: Mock Interviews โน0 ยท Python Analytics Course โน2,000 ยท Improve IQI Score โน1,500 ยท Behavioral Activity โน500 ยท Diversify Applications โน0.
---
### 15. Admin โ Model Configuration & Fairness Audit (16.2)
> **Champion model card**: v2.0-prototype ยท deployed 2026-05-01 ยท F1\_6m = **0.86** ยท Salary MAPE = **0.126** ยท PSI = **0.025** ยท traffic 100%. Challenger slot inactive. **Model Fairness Audit**: Region disparity 2.6% โ
ยท Course disparity 0.6% โ
ยท **Institute Tier disparity 80.5% โ** (exceeds 10% threshold, 30-day SLA).
---
## ๐ก API Reference
### Core Endpoints
| Method | Endpoint | Description |
|---|---|---|
| `POST` | `/api/v1/score/student` | Full agentic scoring (ML + AI agents) |
| `POST` | `/api/v1/score/student/fast` | ML-only scoring (~50ms) |
| `POST` | `/api/v1/score/batch` | Batch scoring (up to 1,000 students) |
| `GET` | `/api/v1/students?limit=N` | List students from portfolio |
| `GET` | `/api/v1/student/{id}` | Full scored profile for a student |
| `GET` | `/api/v1/cohort/summary` | Portfolio-level aggregates |
### AI Agent Endpoints
| Method | Endpoint | Description |
|---|---|---|
| `GET` | `/api/v1/student/{id}/career-paths` | Career-pivot recommendations |
| `GET` | `/api/v1/student/{id}/offer-survival?company=X` | Offer revocation probability |
| `GET` | `/api/v1/shocks/active` | Active placement shocks (real data) |
### Monitoring & Compliance
| Method | Endpoint | Description |
|---|---|---|
| `GET` | `/api/v1/model/drift` | PSI drift monitoring |
| `GET` | `/api/v1/model/metadata` | Model version & metrics |
| `GET` | `/api/v1/student/{id}/history` | 90-day score history |
| `GET` | `/api/v1/student/{id}/audit-report` | Compliance audit report |
| `GET` | `/api/v1/alerts/active` | Early-alert engine |
| `GET` | `/api/v1/heatmap/demand` | Employability heatmap |
| `GET` | `/api/v1/cohort/velocity` | Peer placement velocity |
| `POST` | `/api/v1/feedback` | Outcome submission (retraining loop) |
| `POST` | `/api/v1/institute/cold-start` | New-institute scoring |
๐ Full interactive docs: **[http://localhost:8001/docs](http://localhost:8001/docs)**
---
## ๐ Frontend Pages
| Page | Route | Description |
|---|---|---|
| **Dashboard** | `/` | Portfolio KPIs, risk distribution, watchlist, top alerts |
| **Portfolio** | `/students` | Student search, filters, individual risk cards |
| **Student Profile** | `/student/:id` | Deep dive: SHAP, NBA, score history, simulations |
| **Heatmap** | `/heatmap` | Field ร Region demand grid with trend indicators |
| **Reports & Drift** | `/reports` | PSI drift, feature stability, audit export |
| **Institutes** | `/institutes` | Institute benchmarking, cold-start scoring |
| **AI Agents** | `/agentic` | Agent activity viewer, orchestration flow |
| **Admin Panel** | `/admin` | Model config, provider settings, data management |
---
## ๐ Configuration
### Environment Variables
| Variable | Required | Description |
|---|---|---|
| `PROVIDER` | Optional | LLM provider: `groq`, `anthropic`, `openrouter`, `openai` |
| `GROQ_API_KEY` | If using Groq | Groq API key |
| `ANTHROPIC_API_KEY` | If using Anthropic | Anthropic API key |
| `OPENAI_API_KEY` | If using OpenAI | OpenAI API key |
| `OPENROUTER_API_KEY` | If using OpenRouter | OpenRouter API key |
| `RECOVERY_COST_INR` | Optional | Default loan-recovery cost (โน180,000) |
| `SHOCK_THRESHOLD_WOW` | Optional | Week-over-week drop threshold for shock detection (0.15) |
---
## ๐ Model Performance
| Metric | Value |
|---|---|
| Classification F1 (6-month) | **0.86** |
| Salary MAPE | **12.6%** |
| Training records | 8,000 |
| Evaluation records | 2,000 |
| Inference latency (ML-only) | ~50 ms |
| Inference latency (full agentic) | ~3โ5 s |
| Population Stability Index (PSI) | 0.025 (STABLE) |
---
## ๐ Project Structure
```
PlacementIQ/
โโโ README.md
โโโ PlacementIQ_PRD_v2.md # Product Requirements Document
โโโ PLACEMENTIQ_AGENTIC_IMPLEMENTATION.md
โ
โโโ backend/
โ โโโ main.py # FastAPI app โ 32 endpoints
โ โโโ scoring_engine.py # XGBoost + LightGBM + SHAP pipeline
โ โโโ model_pipeline.py # Model training & persistence
โ โโโ data_generator.py # Synthetic student data (10K records)
โ โโโ real_data_fetcher.py # World Bank + India market data
โ โโโ config.py # Environment & provider configuration
โ โโโ requirements.txt # Python dependencies
โ โโโ .env # API keys (not committed)
โ โโโ agents/
โ โ โโโ orchestrator.py # Agent orchestration & parallelisation
โ โ โโโ provider.py # Multi-LLM provider abstraction
โ โ โโโ base_agent.py # Base agent class (tool calling)
โ โ โโโ tools.py # Tool registry with caching layer
โ โ โโโ nba_agent.py # Next-Best-Action recommendations
โ โ โโโ explainability_agent.py # Human-readable risk narratives
โ โ โโโ market_agent.py # Placement-shock detection
โ โ โโโ career_path_agent.py # Career-pivot recommendations
โ โ โโโ offer_survival_agent.py # Offer-revocation probability
โ โโโ data/
โ โ โโโ synthetic_students.csv # Generated student dataset
โ โ โโโ market_data.json # Cached market intelligence
โ โโโ models/ # Trained model artefacts
โ
โโโ frontend/
โ โโโ index.html
โ โโโ package.json
โ โโโ vite.config.js
โ โโโ public/
โ โ โโโ favicon.svg
โ โ โโโ icons.svg
โ โโโ src/
โ โโโ main.jsx # App entry point
โ โโโ App.jsx # Layout, sidebar, routing
โ โโโ App.css # Theme-specific glassmorphism
โ โโโ index.css # Design system tokens (800+ lines)
โ โโโ components/
โ โ โโโ Background3D.jsx # Animated 3D background
โ โโโ context/
โ โ โโโ ThemeContext.jsx # Dark / Light theme provider
โ โโโ pages/
โ โโโ Dashboard.jsx # Portfolio overview + risk cards
โ โโโ StudentProfile.jsx # Individual student deep dive
โ โโโ Heatmap.jsx # Field ร Region demand grid
โ โโโ Reports.jsx # Drift monitoring + audit
โ โโโ Institutes.jsx # Institute benchmarking
โ โโโ AgenticInsights.jsx # AI-agent activity viewer
โ โโโ Admin.jsx # Settings + configuration
โ
โโโ docs/
โ โโโ screenshots/ # Prototype output screenshots (15 files)
โ
โโโ .gitignore
```
---
๐ฌ Watch the Full Demo Video ๐ฌ
PlacementIQ โ Built by Team TenzorX for Poonawalla Fincorp
Career Risk Intelligence โข Agentic AI โข Education Loan Analytics
ยฉ 2026 Poonawalla Fincorp ยท All rights reserved ยท Proprietary