Harshavard21/FinRAG
2
1---2title: FinRAG3emoji: 📈4colorFrom: blue5colorTo: indigo6sdk: docker7pinned: false8---9 10<div align="center">11 12# FinRAG — Production Financial AI Assistant13 141516171819[](https://huggingface.co/spaces/Harshavard21/FinRAG)20 21### 🔴 [Live Production Demo on Hugging Face Spaces](https://harshavard21-finrag.hf.space/) 🔴22 23> **An enterprise-grade Retrieval-Augmented Generation (RAG) system built over the official BSE Annual Reports of 17 major Indian companies.**24> FinRAG leverages advanced hybrid retrieval, cross-encoder reranking, and semantic caching to deliver lightning-fast, 100% grounded financial insights.25 26---27</div>28 29## 📑 Table of Contents30- [Project Overview](#-project-overview)31- [Core Features & UI](#-core-features--ui)32- [Production RAG Architecture](#-production-rag-architecture)33- [Tech Stack](#-tech-stack)34- [Companies Covered](#-companies-covered)35- [Local Setup & Running](#-local-setup--running)36 37---38 39## 🎯 Project Overview40 41FinRAG solves the hallucination problem in financial AI. It processes massive, complex PDF annual reports and transforms them into an interactive, highly-accurate AI assistant. Whether you need deep-dive qualitative analysis or exact quantitative metrics, every single claim the AI makes is backed by a direct, clickable citation linking directly to the source page of the official financial report.42 43---44 45## 🚀 Core Features & UI46 47### Main Interface4849 50### Interactive Chat (Grounded Q&A)51Ask natural language questions about any company's financial performance. Features a **Semantic Cache** for blazing-fast 50ms responses on repeated/similar queries, and clickable source badges that instantly open the exact PDF page where the AI found the data.5253 54#### 💡 Natural Language Explanations5556 57### Automated KPI Dashboard58Automatically extracts and displays key financial metrics (Revenue, Net Profit, EPS, ROE, NPA) into a beautiful, color-coded dashboard. Includes dynamically split Plotly charts (P&L vs Balance Sheet) that accurately represent data magnitude.5960 61### Cross-Document Compare Mode62A powerhouse analytical workspace capable of running parallel retrievals across different documents. You can instantly compare multiple companies (e.g., "HDFC vs ICICI Gross NPA") or track Year-over-Year trends for a single company (e.g., "TCS FY24 vs FY25 Revenue").6364 65---66 67## 🧠 Production RAG Architecture68 69FinRAG implements state-of-the-art information retrieval techniques to ensure enterprise-grade accuracy.70 71```mermaid72flowchart TD73 A[BSE PDFs] -->|PyMuPDF + pdfplumber| B(Smart Ingestion & OCR)74 B --> C(Hierarchical Chunking)75 C -->|Parent/Child Nodes| D{Embedding & Indexing}76 D -->|Dense Vectors| E[(Qdrant HNSW)]77 D -->|Sparse Terms| F[(BM25 Index)]78 79 G[User Query] --> H(Query Expansion)80 H --> I[Hybrid Retrieval]81 E --> I82 F --> I83 I -->|Rank Fusion RRF| J(BGE Cross-Encoder Reranker)84 J -->|Top-K Chunks| K(Llama 3.3 70B via Groq)85 K --> L[Streaming Response with Citations]86 87 G -.->|If >95% Match| M(In-Memory Semantic Cache)88 M -.->|Instant 50ms Hit| L89```90 91### Advanced Concepts Used:92- **Hierarchical Chunking:** Splits documents into small chunks for precise searching, but passes the larger surrounding "parent" context to the LLM to prevent data fragmentation.93- **Hybrid Search (Dense + Sparse):** Combines Semantic vector search (Qdrant) with exact keyword matching (BM25) and fuses the scores using **Reciprocal Rank Fusion (RRF)**.94- **Cross-Encoder Reranking:** The initial search pulls 30-50 candidates. A powerful `BAAI/bge-reranker-base` model then heavily scores and re-orders them to find the absolute top 3-5 most relevant chunks.95- **Semantic Caching:** A NumPy-powered in-memory vector cache that short-circuits the entire pipeline if a user asks a semantically similar question, saving expensive API tokens.96 97---98 99## 🛠️ Tech Stack100 101- **Backend / API:** Python 3.12, FastAPI, Uvicorn102- **Frontend UI:** Vanilla JS, HTML, CSS (Custom Glassmorphism UI)103- **Vector Database:** Qdrant (Local via Docker)104- **Embeddings:** `BAAI/bge-large-en-v1.5`105- **Reranker:** `BAAI/bge-reranker-base`106- **LLM Inference:** Llama 3.3 70B (Powered by Groq LPUs for ultra-low latency)107 108---109 110## 🏢 Companies Covered111 112Data includes **FY2024–FY2025** BSE Annual Reports for 17 major entities across IT, Banking, FMCG, and Infrastructure:113 114*Airtel, Axis Bank, Bajaj Finance, HCL, HDFC Bank, HUL, ICICI Bank, Infosys, ITC, Kotak Mahindra Bank, Karur Vysya Bank, L&T, Maruti Suzuki, MRF, ONGC, Reliance Industries, SBI, TCS.*115 116---117 118## ⚙️ Local Setup & Running119 1201. **Clone & Install Dependencies**121```bash122git clone https://github.com/yourusername/finrag.git123cd finrag124pip install -r requirements.txt125```126 1272. **Set Environment Variables**128Create a `.env` file in the root directory and add your API keys:129```env130GROQ_API_KEY=gsk_your_groq_api_key_here131QDRANT_URL=https://your-cluster-url.aws.cloud.qdrant.io132QDRANT_API_KEY=your_qdrant_cloud_api_key133```134 1353. **Run the Application Locally**136Since the vectors are hosted on Qdrant Cloud, no local Docker container is needed for the database!137```bash138streamlit run app/main.py139```140 1414. **Open the UI**142Navigate to `http://localhost:8501/` in your browser.143 144## ☁️ Cloud Deployment (Hugging Face Spaces)145This application is fully containerized and currently deployed on **Hugging Face Spaces** using Docker.146- **Git LFS**: Used to efficiently store and serve the 23 heavy PDF Annual Reports without bloating the Git history.147- **Secrets Management**: API keys (Groq & Qdrant) are securely injected into the Docker container via HF Secrets.148- **CI/CD**: Pushing to the HF remote triggers an automatic Docker rebuild and zero-downtime deployment.149