initial commit: multimodal RAG engine with guardrails and tests

.cursorignore

@@ -0,0 +1,11 @@
+node_modules/
+.git/
+dist/
+build/
+venv/
+.venv/
+__pycache__/
+*.log
+*.csv
+*.xlsx
+*.pdf

.gitattributes

@@ -0,0 +1,12 @@
+/hf_cache_v2/models--BAAI--bge-reranker-v2-m3/snapshots/953dc6f6f85a1b2dbfca4c34a2796e7dde08d41e/tokenizer.json filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.pdiparams filter=lfs diff=lfs merge=lfs -text
+*.pdmodel filter=lfs diff=lfs merge=lfs -text
+*.db filter=lfs diff=lfs merge=lfs -text
+*.pyc filter=lfs diff=lfs merge=lfs -text
+*.pdf filter=lfs diff=lfs merge=lfs -text
+*.json filter=lfs diff=lfs merge=lfs -text
+*.info filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text

.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: Python CI Workflow
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Install Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+          pip install pytest
+
+      - name: Run Pytest Evaluation Suite
+        run: |
+          pytest tests/test_guardrail_eval.py -v

.gitignore

@@ -0,0 +1,19 @@
+venv/ 
+.venv/ 
+hf_models_v2/ 
+.hf_home/ 
+.hf_cache/ 
+.hf_cache_v2/ 
+docling_models/ 
+assets/ 
+data_cache/ 
+*.qdrant/ 
+data/ 
+*.db 
+*.bin 
+*.onnx 
+*.safetensors 
+*.sqlite 
+qdrant_db/ 
+.env 
+.env* 

.paddleocr/whl/cls/ch_ppocr_mobile_v2.0_cls_infer/inference.pdiparams

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d1efda1b80e174b4fcb168a035ac96c1af4938892bd86a55f300a6027105d08c
+size 539978

.paddleocr/whl/cls/ch_ppocr_mobile_v2.0_cls_infer/inference.pdiparams.info

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ee0c2eaa4c09814802bf520c01dfdbc1345dc2879dc9e67424d32c7b0ee88e59
+size 18545

.paddleocr/whl/cls/ch_ppocr_mobile_v2.0_cls_infer/inference.pdmodel

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3c4337ec61722a20b1dca2e5bfaffc313c0592bc89ad6e0d45168224186f6683
+size 1624487

.paddleocr/whl/det/en/en_PP-OCRv3_det_infer/inference.pdiparams

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:83676ec730627ab4502f401410a4b6a3ce1c0bb98fa249b71db055b6bddae051
+size 2377917

.paddleocr/whl/det/en/en_PP-OCRv3_det_infer/inference.pdiparams.info

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2fe414d9eadf914bf44e3f9ba212988a6f26f364e4f87c6d0af57438ffffc0c4
+size 26392

.paddleocr/whl/det/en/en_PP-OCRv3_det_infer/inference.pdmodel

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c4bfb1b05d9d1d5a760801eaf6d20180ef7e47bcc675fb17d1f3a89da5fef427
+size 1590133

.paddleocr/whl/rec/en/en_PP-OCRv4_rec_infer/inference.pdiparams

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:75f64a1ffb70c56b7a25655963ca16f5bf3286202e3f52ac972bee05cdee2f56
+size 7607269

.paddleocr/whl/rec/en/en_PP-OCRv4_rec_infer/inference.pdiparams.info

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:710d9f3d7c503067ae708f4bc3adc6973c0d6391adb7a1470c36eb70da6b5b83
+size 102540

.paddleocr/whl/rec/en/en_PP-OCRv4_rec_infer/inference.pdmodel

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:85b952f05f709af259cfe4254012aa7208bef0998f71f57a15495446f25ccd43
+size 2517366

Dockerfile

@@ -0,0 +1,24 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+ENV HF_HOME=/app/hf_cache
+ENV TRANSFORMERS_CACHE=/app/hf_cache
+
+RUN apt-get update && apt-get install -y build-essential
+
+COPY requirements.txt .
+
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Pre-download embedding model
+RUN python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')"
+
+# Pre-download reranker
+RUN python -c "from sentence_transformers import CrossEncoder; CrossEncoder('cross-encoder/ms-marco-MiniLM-L-6-v2')"
+
+COPY . .
+
+EXPOSE 8080
+
+CMD uvicorn app.main:app --host 0.0.0.0 --port $PORT

Dockerfile.streamlit

@@ -0,0 +1,13 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+COPY requirements-streamlit.txt .
+
+RUN pip install --no-cache-dir -r requirements-streamlit.txt
+
+COPY streamlit_ui ./streamlit_ui
+
+EXPOSE 8080
+
+CMD ["streamlit","run","streamlit_ui/Streamlitapp.py","--server.port=8080","--server.address=0.0.0.0"]

README.md

@@ -0,0 +1,264 @@
+# Financial Regulatory RAG System
+
+A production-style Retrieval-Augmented Generation (RAG) system for financial regulatory Q&A that reduces hallucination using hybrid retrieval, cross-encoder reranking, and source-grounded responses. Achieved ~0.875 Recall@5 using hybrid retrieval + cross-encoder reranking on RBI regulatory data
+
+## Why it matters
+- Financial compliance requires accurate, verifiable answers — hallucinated responses can lead to regulatory and financial risk  
+- This system ensures responses are grounded in official RBI regulatory documents  
+
+## What makes it better
+- Hybrid Retrieval (BM25 + FAISS) for keyword + semantic search  
+- Cross-Encoder Reranking improving Recall@5 from ~0.75 → ~0.875  
+- Source-grounded responses to reduce hallucination  
+- Quantitative evaluation using Recall@k and RAGAS metrics  
+- Production-ready deployment using FastAPI + Cloud Run + Streamlit UI  
+
+---
+# Live Demo
+
+🔗 **Streamlit App:**  
+https://financial-rag-ui-912628415543.us-central1.run.app/
+
+🔗 **API Docs:**  
+https://financial-rag-api-912628415543.us-central1.run.app/docs
+
+---
+# System Architecture
+
+```
+User Query
+   ↓
+Streamlit UI
+   ↓
+FastAPI API (/query endpoint)
+   ↓
+Hybrid Retrieval
+   • BM25 Retriever
+   • FAISS Vector Search
+   ↓
+Cross-Encoder Reranking
+(cross-encoder/ms-marco-MiniLM-L-6-v2)
+   ↓
+Context Construction
+   ↓
+LLM Answer Generation
+   ↓
+Final Response
+```
+
+---
+
+# Key Features
+
+## Hybrid Retrieval
+Combines **BM25 lexical search** and **FAISS dense vector search** to improve retrieval accuracy.
+
+## Cross-Encoder Reranking
+Documents are reranked using: cross-encoder/ms-marco-MiniLM-L-6-v2
+This improves answer quality by selecting the most relevant context.
+
+## Source Attribution
+The system returns the **document source and page number** used to generate the answer.  
+This ensures responses are grounded in the original financial regulatory documents and helps reduce hallucinations.
+
+## FastAPI Backend
+Provides a scalable REST API.
+
+Endpoint:
+
+```
+POST /query
+```
+
+Returns:
+
+- Generated answer
+- Response latency
+- Metadata
+
+## Streamlit UI
+Interactive interface to ask compliance-related questions.
+
+## Cloud Deployment
+The system is containerized using **Docker** and deployed on **Google Cloud Run**.
+
+---
+
+# Tech Stack
+
+| Component | Technology |
+|--------|--------|
+Backend API | FastAPI |
+Frontend | Streamlit |
+Vector Database | FAISS |
+Embeddings | sentence-transformers/all-MiniLM-L6-v2 |
+Reranker | cross-encoder/ms-marco-MiniLM-L-6-v2 |
+Retrieval | Hybrid (BM25 + FAISS) |
+LLM | OpenRouter (Llama 3 / Open-source models)
+Deployment | Docker + Google Cloud Run |
+
+---
+
+# Retrieval Evaluation
+
+We evaluated retrieval performance using Recall@5 on a manually labeled dataset derived from RBI KYC guidelines.
+
+| Method              | Recall@5 |
+|---------------------|---------|
+| BM25                | 0.50    |
+| FAISS               | 0.875   |
+| Hybrid              | 0.75    |
+| Hybrid + Reranking  | 0.875   |
+
+- Dense retrieval (FAISS) performed best for semantic regulatory data
+- BM25 underperformed due to lack of strong keyword signals
+- Hybrid improved baseline retrieval
+- Cross-encoder reranking significantly improved result ordering
+
+👉 Reranking improved Hybrid performance from ~0.75 → ~0.875
+
+---
+
+## Limitations
+
+While the system performs well on structured regulatory queries, several limitations were observed:
+   1. Sensitivity to Query Quality
+   - The system struggles with vague or poorly phrased queries  
+   - Retrieval performance depends heavily on how clearly the query matches document intent  
+
+   2. Context Window Constraints
+   - Only top-k retrieved chunks are passed to the LLM  
+   - Important information may be missed if not retrieved in top results  
+
+   3. Hallucination Risk
+   - If retrieval fails or returns weak context, the LLM may generate partially incorrect answers  
+   - This was observed in edge cases with ambiguous queries  
+
+   4. Dataset Limitations
+   - Performance is tied to the quality and coverage of the RBI document  
+   - Missing or incomplete sections can lead to incomplete answers  
+
+   5. Retrieval Bias
+   - Dense retrieval (FAISS) dominates performance due to semantic nature of data  
+   - BM25 contributes less in this domain, reducing hybrid effectiveness  
+
+   6. Computational Overhead
+   - Cross-encoder reranking improves accuracy but increases latency  
+   - Not optimal for real-time high-throughput systems without optimization  
+
+---
+
+# Retrieval Pipeline
+
+1. User submits a question
+2. Hybrid retriever fetches candidate documents
+3. BM25 search retrieves keyword matches
+4. FAISS performs dense vector similarity search
+5. Cross-Encoder reranks retrieved documents
+6. Top documents are selected as context
+7. LLM generates the final answer
+8. API returns the response with latency metadata
+9.  Response includes source citation for transparency
+
+---
+
+# API Usage
+
+## Query Endpoint
+
+```
+POST /query
+```
+
+### Example Request
+
+```json
+{
+ "question": "Under which Rule should suspicious transactions be reported to FIU-IND?"
+}
+```
+
+### Example Response
+
+```json
+{
+ "question": "...",
+ "answer": "...",
+ "sources": ["Finance_RBI.pdf (Page 14)"],
+ "latency_seconds": 1.42
+}
+```
+
+---
+
+# Project Structure
+
+```
+rag-system-v2
+│
+├── app
+│   ├── ingestion.py
+│   ├── vector.py
+│   ├── retriever.py
+│   ├── llm.py
+│   └── main.py
+│
+├── Data
+│   └── Vector
+│
+├── streamlit_ui
+│   └── StreamlitApp.py
+│
+├── evaluate.py
+├── Dockerfile
+├── Dockerfile.streamlit
+├── requirements.txt
+└── README.md
+```
+
+---
+
+# Installation
+
+### Clone Repository
+git clone https://github.com/supriyap19967-creator/rag-systm-v2
+cd rag-systm-v2
+
+### Install Dependencies
+pip install -r requirements.txt
+
+### Run FastAPI Server
+uvicorn app.main:app --reload
+
+### Run Streamlit UI
+streamlit run streamlit_ui/StreamlitApp.py
+
+---
+
+# Deployment
+
+### Build Docker Image
+docker build -t financial-rag-api .
+
+### Deploy to Google Cloud Run
+gcloud run deploy financial-rag-api
+
+# Future Improvements
+
+- Query rewriting for handling vague user inputs  
+- Lightweight reranking models to reduce latency  
+- Multi-document reasoning for complex queries  
+- Evaluation on larger and more diverse datasets  
+
+# Example Questions
+
+- How must suspicious transactions be reported?
+- What penalties apply for delayed reporting?
+- Under which rule should suspicious transactions be reported to FIU-IND?
+
+---
+
+# Author
+
+**Supriya**  
+AI / ML Engineer | Generative AI

__pycache__/app.cpython-310.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:943c7c4aa6cd54a522f66a03efc609286488fe8805be1ded7240e8a914489fbf
+size 23802

__pycache__/app.cpython-314.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:03267d74083e07075bae266c4da415b5a235519d4b20fed607d6ac4b48444245
+size 40221

__pycache__/chunk_and_count.cpython-310.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ef7fa92c612ca97d2d4cb69d9de9a975b84efda8d95e3f8586d0f43872e29ada
+size 12045

__pycache__/compliance_safety.cpython-310.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6b20fccd40964a8f1bccae645f9cc9cceab1f1a536337291c3cb999b4f94b3c1
+size 14741

__pycache__/compliance_safety.cpython-314.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6a1fe79339bf7415493f20004fcd51d831648ef8b5c139a0ea7b8d470a590889
+size 16038

__pycache__/deploy_all_2126.cpython-310.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:57dcc0bec30f22c08a2de69f148ca800b8c4d2dbb02e71a828994eef8405823b
+size 8561

__pycache__/deploy_csv_only.cpython-310.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:453a8912803d599b17428949a493cea94fc6532368932a315c293554fbba2a6f
+size 4607

__pycache__/deploy_text_only.cpython-310.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cd1103672a132cf3d44e5791d1e9e5539cdace3d5ef84ccab5ed94fd9617b539
+size 4470

__pycache__/deploy_to_qdrant.cpython-310.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5c5957565f5d139d4b8fe23ae8476d8db12cbd7a34b014f979be68fd3049c855
+size 11297

__pycache__/deploy_to_qdrant.cpython-314.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7d6d2d576a5aabb19c7e266be43ab02af9466536f8036f0634ea865ada54fc05
+size 21111

__pycache__/deploy_visual_only.cpython-310.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d0906555d29a6d4829f3b68c78ed73069120374218228d8cb7c87438f7a07674
+size 5155

__pycache__/deploy_visual_only.cpython-314.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:15ee8750c8062596ced27550fd7de4b6041747d16aca087ef4085ef5eb9f3c46
+size 31704

__pycache__/evaluate.cpython-310.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4b0a829f3466d71db387729d674f0e393c7250104708545d685176e033a27a6e
+size 2410

__pycache__/gateway_guardrails.cpython-310.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3a1466f344a2d36a96b68a19abe510109bb5223b11c419d855e329f0285162a3
+size 17306

__pycache__/gateway_guardrails.cpython-314.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e16ddd174e33ef86c4f275ca351f103f45798e10ebdc0409a5675ffd7a957acf
+size 27990

__pycache__/ingest_data.cpython-310.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f234d98f6a831f0b3bb76bb22241d2a61b9ea76ca765a1038718defa84d48523
+size 30549

__pycache__/ingest_data.cpython-314.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3e36190843057a8faa9f9560b66180b98edf0c064d08c08c686265eb42b8abca
+size 50970

__pycache__/isolate_visual.cpython-314.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3f83f49ac7ae75d24110381a8f9c711d94998cc9e2e413957c41bbd39e5ab6b0
+size 15580

__pycache__/migrate_qdrant_cross_references.cpython-314.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:102423c4b25c7f9f0901795e2bc84cd05ff948da0ef8e7ea8a5e50e6e1b9aeb7
+size 7720

__pycache__/query_rag.cpython-310.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bc5a852df9863968409b1f467cef3bffe9f6b8965a98f09903c42f5dd253b009
+size 27701

__pycache__/query_rag.cpython-314.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fd12e695b9dd382e3cabec2ad097de9721295ce96d17fb33a823fff2b27a8f58
+size 40305

__pycache__/rag_invariants.cpython-310.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a4bec8d89680f875accc93f8925dd587b2f3dca2b31c42d2c9519523d7eb848b
+size 17785

__pycache__/rag_invariants.cpython-314.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f7efec23939c751a9370c5bd431aa60d7d52cf046f4081118a208a548bdf1608
+size 24027

__pycache__/reindex_sparse.cpython-314.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ec40a30ecf8e81ed87446d073a74cb8a1ff9e4e561f64ceb066aef7bb5b1820d
+size 23683

__pycache__/self_rag_utils.cpython-310.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:575ea4bd24a964e01727b1d5d5a110e33e5ca00e33989adadcccf90a7dff0573
+size 1148

__pycache__/self_rag_utils.cpython-314.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f01874b94703be7c9536f34a222a38e2f75bb66445edbff83aa41658be1927df
+size 1655

__pycache__/structural_vetting.cpython-310.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a1a18143117dcbe956d49132356d42089f350dacd3ae1271cfab54a2d1e43068
+size 6916

__pycache__/structural_vetting.cpython-314.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:88bf9ee31bbfe1a0b17f33c467c9787a58a67695702cadafa19b44a5b776af6e
+size 12232

__pycache__/test_bge_m3_embedding_components.cpython-310.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:08169715acd3e1bc8f117c558dbd9dcd4b28df3ddd18a3e5fb35cf5bf6749e36
+size 2130