README.md

---
title: Hindi Banking Voice Assistant
emoji: 🏦
colorFrom: yellow
colorTo: green
sdk: gradio
sdk_version: 5.9.1
python: 13.1
app_file: app.py
pinned: true
license: mit
suggested_hardware: cpu-basic
short_description: Hindi voice assistant for banking & govt schemes
---

# 🏦 बैंकिंग सहायक — Hindi Banking Voice Assistant

A voice-powered AI assistant for Indian users to understand banking, loans, and government financial schemes — entirely in **Hindi**. Runs on **CPU Basic** (free tier) via HF Inference API.

## 🔑 Setup (Required — One Time)

1. Go to your Space → **Settings → Secrets**
2. Add secret → **Name:** `HF_TOKEN` | **Value:** your free HF read token from [hf.co/settings/tokens](https://hf.co/settings/tokens)

That's it. All 3 models are called via API — nothing loads into the Space's RAM.

---

## 🤖 Models Used

| Role | Model |
|------|-------|
| Speech-to-Text | `openai/whisper-large-v3-turbo` |
| LLM | `Telugu-LLM-Labs/Indic-gemma-7b-finetuned-sft-Navarasa-2.0` |
| Text-to-Speech | `ai4bharat/indic-parler-tts` |

---

## 🔄 Pipeline

```
🎤 Hindi Audio
    ↓
[HF API] openai/whisper-large-v3-turbo      →  Hindi transcript
    ↓
Jargon Normalization (local, pure Python)   →  kist→EMI, zamanat→collateral ...
    ↓
Keyword RAG Retrieval (local, pure Python)  →  top 3 relevant KB passages
    ↓
[HF API] Indic-gemma-7b (Navarasa 2.0)     →  Hindi answer grounded in KB
    ↓
[HF API] ai4bharat/indic-parler-tts         →  Hindi speech audio
    ↓
🔊 Answer (audio + text + citations)
```

**Local compute:** ~50 MB RAM for knowledge base + retriever. Zero GPU required.

---

## ⏱️ Expected Response Times (free tier)

| Step | Time |
|------|------|
| STT (Whisper API) | 5–10s |
| RAG Retrieval | < 1s |
| LLM (Indic-Gemma API) | 15–40s (cold start up to 60s) |
| TTS (Parler API) | 10–20s |
| **Total** | **~30–70s per query** |

> First call may be slower due to HF cold start. The app retries automatically.

---

## 📖 Knowledge Base Coverage

### Banks (12)
SBI, HDFC Bank, ICICI Bank, Axis Bank, Kotak Mahindra Bank, PNB, Bank of Baroda, Canara Bank, Union Bank of India, Indian Bank, Small Finance Banks (AU / Ujjivan / Equitas / Jana), Regional Rural Banks & Co-operative Banks, NBFCs (Bajaj Finance / Muthoot / Manappuram)

### Government Credit Schemes (11)

| Scheme | Coverage |
|--------|----------|
| PM Mudra Yojana | Shishu / Kishore / Tarun loans up to ₹10L (Tarun Plus ₹20L) |
| Stand-Up India | SC/ST & women entrepreneurs ₹10L–₹1Cr |
| PM SVANidhi | Street vendors ₹10K → ₹20K → ₹50K |
| PMEGP + KVIC | Employment generation with 15–35% govt subsidy |
| CGTMSE + ECLGS | Collateral-free MSME loans |
| PM Awas Yojana CLSS | Home loan interest subsidy for EWS / LIG / MIG |
| Kisan Credit Card | Agricultural credit at effective 4% p.a. |
| PM Vishwakarma | Artisan loans at 5% concessional rate |
| PMJDY + Overdraft | Zero-balance accounts + ₹10,000 overdraft |
| Vidya Lakshmi + CSIS | Education loans + interest subsidy |
| NRLM-SHG | Women Self Help Group bank linkage program |

### Social Security Schemes (6)

| Scheme | Benefit |
|--------|---------|
| PMJJBY | ₹2 lakh life insurance at ₹436/year |
| PMSBY | ₹2 lakh accident insurance at ₹20/year |
| Atal Pension Yojana | Guaranteed monthly pension for unorganized sector |
| PM-KISAN | ₹6,000/year direct income support for farmers |
| EPFO / EPF / EPS | Provident fund & pension for formal employees |
| PMFBY | Crop insurance at 1.5–2% farmer premium |
| MGNREGS | 100 days guaranteed employment per year |

### Financial Terms & Concepts
EMI, CIBIL Score, KYC documents, MCLR & Repo Rate, Collateral & Guarantor, Moratorium & Loan Restructuring, Processing Fees & Prepayment Charges, NPA & OTS, Loan types (home / personal / vehicle / gold / education / LAP), UPI / NEFT / RTGS, FD / RD, Microfinance (JLG / SHG), Consumer Rights & RBI Ombudsman

---

## 📁 Repository Structure

```
app.py              Gradio app + HF Inference API pipeline (STT → RAG → LLM → TTS)
rag_pipeline.py     Jargon normalization map, keyword retriever, prompt builder
knowledge_base.py   40+ documents in English (retrieved, answers given in Hindi)
requirements.txt    Minimal: gradio, requests, soundfile, numpy
README.md           This file (HF Space config + documentation)
```

---

## 💡 Design Principles

- **Grounded answers only** — LLM responds only from retrieved KB content, not hallucinations
- **Always in Hindi** — STT, LLM prompt, and TTS all enforce Hindi throughout
- **One follow-up at a time** — conversational, not overwhelming
- **Spoken-friendly output** — short sentences, no technical jargon in answers
- **Graceful fallback** — says "बैंक से संपर्क करें" when information is unavailable
- **Extensible** — adding a new language requires only changing STT language code + TTS voice description

---

## 📝 Example Questions

- मुझे होम लोन के लिए कौन से दस्तावेज़ चाहिए?
- EMI क्या होती है और कैसे calculate होती है?
- मुद्रा लोन कैसे मिलेगा?
- CIBIL score क्या होता है?
- PM Awas Yojana में subsidy कैसे मिलती है?
- जन धन खाता कैसे खोलें?
- किसान क्रेडिट कार्ड क्या है?
- महिला स्वयं सहायता समूह को loan कैसे मिलेगा?

---

> ⚠️ **Disclaimer:** This assistant provides general information only. For actual financial decisions, please consult your bank or a certified financial advisor.
> यह assistant केवल सामान्य जानकारी देता है। वित्तीय निर्णयों के लिए अपने बैंक या certified advisor से सलाह लें।