╔══════════════════════════════════════════════════════════════════╗
║ 📄 Ask ANY question in plain English about Indian company ║
║ filings, annual reports & SEBI regulations ║
║ ║
║ 🔍 Get back a precise, cited answer sourced directly from ║
║ 2,735 indexed document chunks — no hallucinations ║
║ ║
║ ⚡ Powered by Hybrid RAG: BM25 + Vector Search + Cross-Encoder ║
╚══════════════════════════════════════════════════════════════════╝
FilingIQ is a production-grade Retrieval-Augmented Generation (RAG) system built to make financial and compliance research 10× faster. It combines semantic vector search, BM25 keyword retrieval, and a cross-encoder reranker — then feeds the best evidence to LLaMA 3.3 70B running on Groq's ultra-fast inference to produce grounded, citation-backed answers.
|
|
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
│ FilingIQ RAG Architecture │
└─────────────────────────────────────────────────────────────────────────────┘
┌──────────┐ HTTP/REST ┌─────────────────────────────────────────┐
│ │ ─────────────────► │ FastAPI Backend │
│ Browser │ │ (src/api.py · Port 8000) │
│ Frontend │ ◄───────────────── │ /chat · /query · /health · / │
│ :3000 │ JSON Response └──────────────────┬──────────────────────┘
└──────────┘ │
▼
┌──────────────────────────────────────┐
│ Retriever Pipeline │
│ (src/retrieve.py) │
│ │
│ ┌─────────────┐ ┌──────────────┐ │
│ │ BM25 Index │ │ ChromaDB │ │
│ │ (keyword) │ │ (vector DB) │ │
│ └──────┬──────┘ └──────┬───────┘ │
│ └────────┬────────┘ │
│ │ 15 candidates │
│ ▼ │
│ ┌───────────────────────────────┐ │
│ │ Cross-Encoder Reranker │ │
│ │ ms-marco-MiniLM-L-6-v2 │ │
│ │ → Top 3 most relevant chunks │ │
│ └───────────────┬───────────────┘ │
└──────────────────┼───────────────────┘
│
▼
┌──────────────────────────────────────┐
│ Groq LLM API │
│ LLaMA-3.3-70B-Versatile │
│ Temperature=0 · Max tokens=1024 │
│ → Citation-grounded answer │
└──────────────────────────────────────┘
═══════════════════════ INGESTION PIPELINE (Offline) ═══════════════════════
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────┐
│ PDF Files │───►│ PyMuPDF │───►│ Text │───►│ all- │
│ (data/raw/) │ │ Parser │ │ Chunker │ │ MiniLM- │
│ │ │ • Skip OCR │ │ 400 tok │ │ L6-v2 │
│ 11 docs │ │ • Strip H/F │ │ 50 overlap │ │ Embedder │
└──────────────┘ └──────────────┘ └──────────────┘ └─────┬──────┘
│
▼
┌──────────────────┐
│ ChromaDB │
│ Persistent │
│ Vector Store │
│ (./db/) │
│ 2,735 chunks │
└──────────────────┘
flowchart TD
A[👤 User Query] --> B[Query Embedding\nall-MiniLM-L6-v2]
A --> C[BM25 Tokenization\nrank-bm25]
B --> D[ChromaDB\nVector Search\nTop-15 candidates]
C --> E[BM25 Keyword\nSearch]
D --> F{Fusion &\nDeduplication}
E --> F
F --> G[Cross-Encoder\nReranker\nms-marco-MiniLM-L-6-v2]
G --> H[Top-3\nReranked Chunks]
H --> I[Prompt Builder\nSOURCE BLOCKS\nformat]
I --> J[Groq API\nLLaMA 3.3 70B]
J --> K[✅ Cited Answer\nwith Source References]
style A fill:#6366f1,color:#fff
style K fill:#22c55e,color:#fff
style J fill:#f97316,color:#fff
style G fill:#8b5cf6,color:#fff
style D fill:#3b82f6,color:#fff
| Layer | Technology | Version | Purpose |
|---|---|---|---|
| 🌐 API Framework |  |
0.111.0 |
REST endpoints, Pydantic validation, Swagger UI |
| 🗄️ Vector Database |  |
1.5.9 |
Persistent local vector store with cosine similarity |
| 🧬 Embeddings |  |
5.5.1 |
all-MiniLM-L6-v2 — 384-dim dense embeddings |
| 📊 Reranker |  |
— | ms-marco-MiniLM-L-6-v2 cross-encoder |
| 🔠 Keyword Search | rank-bm25 |
0.2.2 |
BM25Okapi sparse retrieval |
| 🤖 LLM |  |
70B | Instruction-tuned, 128k context |
| ⚡ LLM Inference |  |
— | Ultra-fast LPU inference (300+ tok/s) |
| 📄 PDF Parsing | PyMuPDF (fitz) |
1.24.1 |
Block-level text extraction, header/footer removal |
| 🐍 Runtime |  |
3.12+ |
Async-ready, type-safe |
| 🐳 Containerization |  |
Latest | Multi-service single container |
| 🌐 Frontend |    |
Vanilla | Zero-dependency chat UI |
| 🔧 Server |  |
0.24.0 |
ASGI production server |
filingiq/
│
├── 📂 src/ # Core application logic
│ ├── 🐍 api.py # FastAPI app · 4 endpoints · CORS · startup init
│ ├── 🔄 ingest.py # PDF → Chunks → Embeddings → ChromaDB pipeline
│ ├── 🔍 retrieve.py # Hybrid retrieval · reranking · Groq LLM generation
│ └── ✅ verify_env.py # Pre-flight environment validator
│
├── 📂 frontend/
│ └── 🌐 index.html # Vanilla JS chat UI · Fetch API · source citations
│
├── 📂 db/ # ChromaDB persistent vector store (2,735 chunks)
│
├── 📂 data/ # (Not committed) Place raw PDFs here
│ └── raw/ # 11 PDF filings go here for ingestion
│
├── 📂 .github/
│ └── workflows/ # CI/CD pipeline configuration
│
├── 🐳 Dockerfile # Python 3.12-slim · dual-port · health check
├── 🐙 docker-compose.yml # One-command orchestration
├── ⚙️ config.py # All tuneable parameters in one place
├── 📋 requirements.txt # 9 pinned production dependencies
├── 🚫 .gitignore # Excludes venv, .env, raw PDFs
└── 📖 README.md # This file
# 1. Clone the repository
git clone https://github.com/hitdepani/filingiq.git
cd filingiq
# 2. Create your environment file
echo "GROQ_API_KEY=your_groq_api_key_here" > .env
# 3. Run with a single command
docker run -p 8000:8000 -p 3000:3000 --env-file .env filingiq:latest🌐 Open http://localhost:3000 in your browser — that's it!
# 1. Clone & enter directory
git clone https://github.com/hitdepani/filingiq.git
cd filingiq
# 2. Create virtual environment
python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate
# 3. Install dependencies
pip install -r requirements.txt
# 4. Set your API key
echo "GROQ_API_KEY=your_groq_api_key_here" > .env
# 5. Start the API backend
uvicorn src.api:app --reload --host 0.0.0.0 --port 8000
# 6. Serve the frontend (new terminal)
python -m http.server 3000 --directory frontend| Service | URL |
|---|---|
| 💬 Chat UI | http://localhost:3000 |
| 📖 API Docs (Swagger) | http://localhost:8000/docs |
| ❤️ Health Check | http://localhost:8000/health |
🟢 GET /health — Service status & chunk count
// Response 200 OK
{
"status": "healthy",
"chunks_indexed": 2735,
"message": "FilingIQ API is running"
}🔵 POST /chat — Frontend-optimized Q&A
// Request
{ "question": "What was Reliance's revenue in FY2024?" }
// Response 200 OK
{
"answer": "Reliance Industries reported a consolidated revenue of ₹9,01,378 crore in FY2024. [SOURCE 1]",
"sources": [
"Reliance Industries | FY2024 | Page 87",
"Reliance Industries | FY2024 | Page 92"
]
}🟣 POST /query — Debug mode with full relevance scores
// Request
{ "question": "What are SEBI's insider trading disclosure requirements?" }
// Response 200 OK
{
"answer": "SEBI's Prohibition of Insider Trading Regulations 2015 require... [SOURCE 1]",
"sources": [
{
"id": "sebi_regulation_insider_trading_2015_p3_c0",
"company": "SEBI",
"year": "2015",
"page": 3,
"relevance": 0.94,
"content": "Every insider shall maintain a structured digital database..."
}
],
"chunks_used": 3
}To add new documents to the knowledge base:
# 1. Place your PDFs in the raw data directory
cp your_annual_report.pdf data/raw/
# 2. Register the file in config.py → FILING_REGISTRY list
# Example entry:
# {"file": "your_annual_report.pdf", "company": "YourCo", "doc_type": "annual_report", "year": "FY2025"}
# 3. Run the ingestion pipeline
python src/ingest.pyWhat happens under the hood:
PDF File
↓ detect_pdf_type() → Skip scanned/OCR-only PDFs
↓ parse_pdf() → PyMuPDF block extraction
↓ is_header_footer() → Strip 8% top/bottom margin noise
↓ clean_text() → Normalize whitespace, dashes, quotes
↓ chunk_document() → 400-token chunks, 50-token overlap
↓ embed_and_store_batch() → Encode in batches of 16 (~100MB RAM)
↓ ChromaDB.add() → Persistent vector storage
| Metric | Value |
|---|---|
| 📦 Total document chunks indexed | 2,735 |
| 🏢 Companies covered | 4 (Reliance, TCS, Infosys, SEBI) |
| 📅 Years covered | FY2024 · FY2025 · FY2026 |
| 📄 Total documents | 11 PDFs |
| ⏱️ Average end-to-end query latency | ~2–3 seconds |
| 🧩 Chunk size | 400 tokens |
| 🔀 Chunk overlap | 50 tokens |
| 🔍 Vector search candidates | Top 15 |
| 🎯 Final chunks fed to LLM | Top 3 (after reranking) |
| 💾 Embedding dimensions | 384 (all-MiniLM-L6-v2) |
| 🔢 LLM max output tokens | 1,024 |
All parameters live in config.py:
# ── LLM ──────────────────────────────────────────────────────────
LLM_MODEL = "llama-3.3-70b-versatile" # Groq-hosted LLaMA 3.3
LLM_BASE_URL = "https://api.groq.com/openai/v1"
# ── Embeddings & Reranker (100% local, no API needed) ────────────
EMBEDDING_MODEL = "all-MiniLM-L6-v2" # 384-dim, fast & accurate
RERANKER_MODEL = "cross-encoder/ms-marco-MiniLM-L-6-v2"
# ── Chunking ──────────────────────────────────────────────────────
CHUNK_SIZE = 400 # tokens (~1,600 chars)
CHUNK_OVERLAP = 50 # tokens of context carry-over
# ── Retrieval ─────────────────────────────────────────────────────
TOP_K_RETRIEVAL = 15 # candidates from vector search
TOP_K_RERANK = 3 # final chunks sent to LLM- Hybrid BM25 + vector retrieval
- Cross-encoder reranking
- Citation-aware answer generation
- Docker deployment
- Swagger API documentation
- 🔐 User authentication & role-based access
- 💬 Multi-turn conversational follow-ups (chat memory)
- 📤 Export answers to PDF / DOCX
- 🔎 Advanced filters by company, year, document type
- 📈 Analytics dashboard — usage & retrieval insights
- 🌏 Support for BSE/NSE filing formats
- 🔄 Auto-ingest from SEBI EDGAR API
Contributions are warmly welcome!
# Fork → Clone → Branch → Code → PR
git checkout -b feature/your-feature-name
git commit -m "feat: add amazing feature"
git push origin feature/your-feature-nameTo add support for new document types, extend the FILING_REGISTRY in config.py and drop the PDFs into data/raw/.
This project is licensed under the MIT License — use it, extend it, ship it.
Built with ❤️ by Hit Depani
"Making financial research smarter, faster, and verifiable — one filing at a time."
⭐ Star this repo if FilingIQ helped you! ⭐