README.md

---
title: Enterprise Loan AI
emoji: 🏦
colorFrom: yellow
colorTo: gray
sdk: docker
pinned: false
license: mit
---

# 🏦 Enterprise Loan AI: Adaptive Predictive Ecosystem

**Enterprise-grade financial decision engine combining Hybrid ML Logic with Mistral Large 3 Generative Insights.**

---

## 🏗️ 1. System Architecture

The ecosystem operates as a high-fidelity diagnostic pipeline, ensuring mathematical rigor before AI interpretation.

```mermaid
graph TD
    User((User)) -->|Submit Application| UI(React/Vite Frontend)
    UI -->|API POST /predict| API(FastAPI Backend)
    
    subgraph "Hybrid Inference Engine"
        API -->|1. Deterministic Map| ML(sklearn Random Forest)
        ML -->|Probabilities| ADVISOR(NVIDIA NIM Mistral-3)
        ADVISOR -->|2. Structured Narrative| RESPONSE(Final JSON Packet)
    end
    
    RESPONSE -->|Persistence| DB[(SQLite / PostgreSQL)]
    RESPONSE -->|Visual Analytics| DASH(Radar & Distribution Charts)
    DASH -->|Render| User
```

---

## 📂 2. Repository Structure

```text
├── backend/              # FastAPI Application Source
│   ├── db/               # Persistence & Data Models
│   ├── logic/            # Deterministic ML Engine (sklearn)
│   ├── services/         # LLM Advisor (NVIDIA NIM Integration)
│   ├── main.py           # API Entry Point & Startup Logic
│   └── requirements.txt  # Python Dependencies
├── data/                 # Training datasets (CSV)
├── frontend/             # React (Vite) Application
│   ├── src/
│   │   ├── components/   # Modular UI Components (Charts, Form, Sidebar)
│   │   ├── App.jsx       # State-Based Navigation & Layout
│   │   └── index.css     # Premium UI Design System
│   └── package.json      # Node.js Dependencies
├── Dockerfile            # Multi-stage Production Build
├── .dockerignore         # Docker Build Exclusions
├── .gitignore            # Git Excluded Files
└── .env.example          # Environment Management Template
```

---

## 🚀 3. End-to-End Setup Guide

### **A. Local Development**

#### **1. Backend (Python 3.11+)**
```powershell
# Create Virtual Environment
python -m venv venv
.\venv\Scripts\activate

# Install Project as Editable Package
pip install -e .

# Start Server
uvicorn backend.main:app --reload --port 8000
```

#### **2. Frontend (Node.js 20+)**
```powershell
cd frontend
npm install
npm run dev
```

### **B. Environment Configuration**
Create a `.env` file in the root directory:
```env
# Required for AI Analysis
NVIDIA_API_KEY=your_key_here

# Required for Persistent Cloud Backups (Optional)
HF_TOKEN=your_huggingface_write_token
HF_REPO_ID=your_username/your_space_name
```

### **C. Cloud Synchronization (New)**
The system now features an **Automated Cloud Sync** service. 
- When running in a Docker/Hugging Face environment with a valid `HF_TOKEN`, the system will automatically back up your assessment history to your Space's repository every time you make a new prediction or clear the history.
- This ensures your data persists even if the Space's ephemeral container is restarted.

---

## 🐳 4. Production Deployment (Hugging Face)

This project is optimized for deployment as a **Hugging Face Space** using the **Docker** runtime.

### **1. Build & Run Locally**
```powershell
# Build Image
docker build -t loan-prediction-app .

# Run Container (History persistence requires /app/data volume)
docker run -d -p 7860:7860 --name loan-app loan-prediction-app
```

### **2. Deploy to Hugging Face**
1. Create a new Space on [huggingface.co](https://huggingface.co/spaces) selecting the **Docker** SDK.
2. In the Space **Settings**:
   - Add your `NVIDIA_API_KEY` as a **Secret**.
   - (Optional) Enable **Persistent Storage** and mount to `/app/data`.
3. Push your code. The Space will automatically build and launch your dashboard.

---

## ✅ 5. Platform Features
- **Deterministic Math**: Validated Random Forest scoring.
- **AI Narrative Sub-Cards**: Readable, point-by-point financial insights.
- **Radar Comparisons**: Real-time benchmarking against successful profiles.
- **ChatGPT History Sidebar**: Persistent task tracking with "Clear History" support.

---
*Built for High-Trust Lending Environments.*