Upload README.md

README.md

@@ -1,12 +1,149 @@
 ---
-title: FinLit App V0
-emoji: 😻
+title: Hindi Banking Voice Assistant
+emoji: 🏦
 colorFrom: yellow
-colorTo: pink
+colorTo: green
 sdk: gradio
-sdk_version: 6.8.0
+sdk_version: 4.44.0
 app_file: app.py
-pinned: false
+pinned: true
+license: mit
+suggested_hardware: cpu-basic
+short_description: Hindi voice assistant for banking & govt schemes
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🏦 बैंकिंग सहायक — 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 से सलाह लें।