Harshavard21/FinRAG

<div align="center">

FinRAG — Production Financial AI Assistant


🔴 Live Production Demo on Hugging Face Spaces 🔴

An enterprise-grade Retrieval-Augmented Generation (RAG) system built over the official BSE Annual Reports of 17 major Indian companies. FinRAG leverages advanced hybrid retrieval, cross-encoder reranking, and semantic caching to deliver lightning-fast, 100% grounded financial insights.

</div>

📑 Table of Contents

• —Project Overview
• —Core Features & UI
• —Production RAG Architecture
• —Tech Stack
• —Companies Covered
• —Local Setup & Running

🎯 Project Overview

FinRAG 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.

🚀 Core Features & UI

Main Interface

[image]

Interactive Chat (Grounded Q&A)

Ask 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. [image]

💡 Natural Language Explanations

[image]

Automated KPI Dashboard

Automatically 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. [image]

Cross-Document Compare Mode

A 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"). [image]

🧠 Production RAG Architecture

FinRAG implements state-of-the-art information retrieval techniques to ensure enterprise-grade accuracy.

flowchart TD
    A[BSE PDFs] -->|PyMuPDF + pdfplumber| B(Smart Ingestion & OCR)
    B --> C(Hierarchical Chunking)
    C -->|Parent/Child Nodes| D{Embedding & Indexing}
    D -->|Dense Vectors| E[(Qdrant HNSW)]
    D -->|Sparse Terms| F[(BM25 Index)]
    
    G[User Query] --> H(Query Expansion)
    H --> I[Hybrid Retrieval]
    E --> I
    F --> I
    I -->|Rank Fusion RRF| J(BGE Cross-Encoder Reranker)
    J -->|Top-K Chunks| K(Llama 3.3 70B via Groq)
    K --> L[Streaming Response with Citations]
    
    G -.->|If >95% Match| M(In-Memory Semantic Cache)
    M -.->|Instant 50ms Hit| L

Advanced Concepts Used:

• —Hierarchical Chunking: Splits documents into small chunks for precise searching, but passes the larger surrounding "parent" context to the LLM to prevent data fragmentation.
• —Hybrid Search (Dense + Sparse): Combines Semantic vector search (Qdrant) with exact keyword matching (BM25) and fuses the scores using Reciprocal Rank Fusion (RRF).
• —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.
• —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.

🛠️ Tech Stack

• —Backend / API: Python 3.12, FastAPI, Uvicorn
• —Frontend UI: Vanilla JS, HTML, CSS (Custom Glassmorphism UI)
• —Vector Database: Qdrant (Local via Docker)
• —Embeddings: BAAI/bge-large-en-v1.5
• —Reranker: BAAI/bge-reranker-base
• —LLM Inference: Llama 3.3 70B (Powered by Groq LPUs for ultra-low latency)

🏢 Companies Covered

Data includes FY2024–FY2025 BSE Annual Reports for 17 major entities across IT, Banking, FMCG, and Infrastructure:

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.

⚙️ Local Setup & Running

1. 1.Clone & Install Dependencies

git clone https://github.com/yourusername/finrag.git
cd finrag
pip install -r requirements.txt

1. 1.Set Environment Variables Create a .env file in the root directory and add your API keys:

GROQ_API_KEY=gsk_your_groq_api_key_here
QDRANT_URL=https://your-cluster-url.aws.cloud.qdrant.io
QDRANT_API_KEY=your_qdrant_cloud_api_key

1. 1.Run the Application Locally Since the vectors are hosted on Qdrant Cloud, no local Docker container is needed for the database!

streamlit run app/main.py

1. 1.Open the UI Navigate to http://localhost:8501/ in your browser.

☁️ Cloud Deployment (Hugging Face Spaces)

This application is fully containerized and currently deployed on Hugging Face Spaces using Docker.

• —Git LFS: Used to efficiently store and serve the 23 heavy PDF Annual Reports without bloating the Git history.
• —Secrets Management: API keys (Groq & Qdrant) are securely injected into the Docker container via HF Secrets.
• —CI/CD: Pushing to the HF remote triggers an automatic Docker rebuild and zero-downtime deployment.