FinBot — Intelligent Knowledge Assistant

FinBot is an internal RAG (Retrieval-Augmented Generation) Q&A assistant for FinSolve Technologies. Employees ask natural-language questions and receive cited answers drawn from company documents — but only the documents their role permits them to see.

What it does

• Cited answers — every response references the source document and page number
• Role-based access control (RBAC) — enforced at the vector database retrieval layer, not just the UI; restricted documents never reach the LLM regardless of how the question is phrased
• Semantic query routing — queries are classified by intent (finance, engineering, marketing, HR, cross-department) and intersected with the user's role before retrieval
• Guardrails — blocks prompt injection attempts, off-topic queries, PII in inputs, and enforces citation in outputs
• Multi-format ingestion — PDFs, Word documents, Markdown, and CSV files are all supported

Role & access matrix

Role	Collections accessible
employee	general
finance	general, finance
engineering	general, engineering
marketing	general, marketing
hr	general, hr — salary data, performance ratings, PII
c_level	all collections

Tech stack

Layer	Technology
Frontend	Next.js 15, TypeScript, Tailwind CSS
Backend	Python, FastAPI
Document parsing	Docling (hierarchical chunking)
Vector database	Qdrant
Embeddings	FastEmbed — BAAI/bge-small-en-v1.5 (local, no API key)
LLM	Groq — llama-3.3-70b-versatile
Query routing	semantic-router
Evaluation	RAGAs

Prerequisites

Requirement	Minimum	Recommended	Notes
Python	3.13	3.13+	Required by pyproject.toml
Node.js	18.18.0	20 LTS or 22 LTS	Next.js 15 hard requirement
npm	9+	bundled with Node.js 20/22	Used to install frontend deps
Docker	any	latest	Runs the Qdrant vector database
Groq API key	—	—	console.groq.com — free tier is sufficient

Why Node.js 18.18+? Next.js 15 dropped support for older Node.js versions. Node.js 20 (LTS) or 22 (LTS) are the safest choices.

Quick start

1. Clone and install Python dependencies

pip install -r requirements.txt

2. Configure environment

cp .env.example .env
# Edit .env and set GROQ_API_KEY=your_key_here

3. Start Qdrant

docker compose up -d

4. Ingest documents

python -m backend.ingestion.ingest

This reads all files from data/ and stores ~1,400 chunks in Qdrant. Embeddings are generated locally — no API calls required.

5. Start the backend API

uvicorn backend.api.app:app --reload --port 8000

6. Start the frontend

cd frontend
npm install
npm run dev

Open http://localhost:3000.

Demo accounts

Username	Password	Role
alice	password123	employee
bob	password123	finance
carol	password123	engineering
dave	password123	marketing
frank	password123	hr
eve	password123	c_level

The login page has one-click chips to fill these credentials.

Running tests

All tests live in backend/tests/. Run from the repo root:

# All 121 tests (unit + integration)
pytest

# Unit tests only — no Qdrant or API key needed (112 tests)
pytest -m "not integration"

# Integration RBAC tests only — requires Qdrant running (9 tests)
pytest -m integration

Evaluation

# RAGAs metrics on 56 ground-truth QA pairs
python -m backend.evaluation.evaluator

# Ablation study across 4 pipeline configurations
python -m backend.evaluation.ablation

Results are saved to data/eval/results.json and data/eval/ablation_results.json.

Data layout

data/
├── general/        → employee_handbook.pdf                     (all roles)
├── hr/             → hr_data.csv  ← salary, PII, performance   (hr + c_level only)
├── finance/        → quarterly reports, budgets                 (finance + c_level)
├── engineering/    → architecture docs, SLA, sprints            (engineering + c_level)
├── marketing/      → campaign reports, CAC/CLV                  (marketing + c_level)
└── eval/           → ground_truth.json, results                 (evaluation only)

Project structure

finbot/
├── backend/        → Python API, ingestion, retrieval, routing, guardrails, evaluation
├── frontend/       → Next.js chat interface and admin panel
├── data/           → Source documents and evaluation dataset
├── docker-compose.yml
└── requirements.txt

See backend/README.md and frontend/README.md for detailed documentation of each layer.