How veneel77/rag-based-knowledge-assistant works
Purpose and Entry Points
This repository is a document-scoped RAG knowledge assistant: authenticated users upload PDF/TXT/DOCX files and ask questions grounded in retrieved document chunks. The service entry point is FastAPI in backend/app/main.py; the Streamlit client entry is root-level app.py (despite the README’s older frontend/app.py layout). Local prebuilt/indexing artifacts also exist in faiss.index, meta.pkl, and ingest_index.py.
Client/API Boundary
The Streamlit UI provides registration/login, document upload, chat, citations, and history views, then calls the FastAPI REST service. API routing is separated by resource:
• Authentication: backend/app/api/auth_api.py
• Document ingestion and management: backend/app/api/upload.py
• Question answering: backend/app/api/query.py
• Conversation history: backend/app/api/history.py
JWT authentication is the boundary enforcing user identity and document isolation across these routes.
Identity and Persistent Metadata
Authentication hashes passwords and issues/verifies JWTs through backend/app/auth/auth.py and backend/app/auth/jwt.py. SQLAlchemy-backed persistence in backend/app/models/database.py stores user, document/chunk metadata, and query history. SQLite is the intended current datastore, creating a single-node persistence boundary rather than a distributed database service.
Ingestion Pipeline
Upload processing coordinates the RAG write path:
1. Receive and validate the uploaded file in backend/app/api/upload.py.
2. Extract text from supported file formats in backend/app/rag/loader.py.
3. Split text into overlapping chunks in backend/app/rag/chunker.py.
4. Produce MiniLM embeddings in backend/app/rag/embedder.py.
5. Persist/search vectors via FAISS in backend/app/rag/vector_store.py, while document/chunk metadata is recorded in the database.
The upload endpoint is therefore the transaction-like integration point between filesystem upload data, SQL metadata, and vector-index state.
Retrieval and Generation Pipeline
A query enters backend/app/api/query.py, where retrieval orchestration in backend/app/rag/retriever.py embeds the user question and performs top-K similarity search against FAISS. Retrieved chunks and associated metadata become grounded context for backend/app/rag/generator.py, which calls Google Gemini and returns an answer plus source citations/similarity information. Query/answer records flow to backend/app/api/history.py and the database for later display.
Configuration, Runtimes, and External Dependencies
Runtime configuration, including Gemini credentials, JWT secret, chunk parameters, retrieval count, and limits, is centralized in backend/app/config.py, with env.example as the environment contract. Material dependencies are Python 3.10+, FastAPI/Uvicorn, Streamlit, SQLAlchemy/SQLite, sentence-transformers (all-MiniLM-L6-v2), FAISS, and Google Gemini API. Gemini is the only required remote inference service; embedding and vector search are intended to run locally.
Deployment Shape
The repository supports a two-container deployment: backend image definition in backend/Dockerfile, frontend image definition in frontend/Dockerfile, and composition/networking through docker-compose.yml. The API is expected on port 8000 and Streamlit on 8501. This is a single-host architecture with local SQLite and FAISS state, so stateful volumes and coordinated index/database updates are operationally important.
Main entry points: main.py FastAPI entry · retriever.py Retrieval orchestration · upload.py Upload routes · query.py Query routes
Components 17
Client
- Streamlit UI · Registration, uploads, chat, citations, and history.
app.py
FastAPI service
- FastAPI entry · Authenticated REST API on port 8000.
backend/app/main.py - Auth routes
backend/app/api/auth_api.py - Upload routes · Coordinates file validation, metadata, and indexing.
backend/app/api/upload.py - Query routes
backend/app/api/query.py - History routes
backend/app/api/history.py - Password + JWT · Hashes passwords and issues/verifies JWTs.
backend/app/auth/auth.py - JWT implementation
backend/app/auth/jwt.py - Runtime configuration · Centralizes credentials, limits, chunking, and retrieval settings.
backend/app/config.py
Ingestion pipeline
- Text extraction · Extracts supported PDF, TXT, and DOCX content.
backend/app/rag/loader.py - Chunking · Creates overlapping text chunks.
backend/app/rag/chunker.py
Retrieval and generation
- MiniLM embeddings · Embeds chunks and user questions locally.
backend/app/rag/embedder.py - Retrieval orchestration · Embeds questions and retrieves top-K chunks.
backend/app/rag/retriever.py - Grounded generator · Builds cited context and generates answers.
backend/app/rag/generator.py
Local state
Single-host persistent metadata and vector index.
- FAISS vector store · Persists vectors and executes similarity search.
backend/app/rag/vector_store.py - SQLite metadata DB · Stores users, documents, chunks, and query history.
backend/app/models/database.py
External inference
- Google Gemini · Required remote answer-generation service.
Connections 22
- Streamlit UI → FastAPI entry: REST + JWT
- FastAPI entry → Auth routes: routes
- FastAPI entry → Upload routes: routes
- FastAPI entry → Query routes: routes
- FastAPI entry → History routes: routes
- Auth routes → Password + JWT: authenticate
- Password + JWT → JWT implementation: issue / verify
- Upload routes → Text extraction: extract text
- Text extraction → Chunking: text
- Chunking → MiniLM embeddings: chunks
- MiniLM embeddings → FAISS vector store: chunk vectors
- Upload routes → SQLite metadata DB: document + chunk metadata
- Query routes → Retrieval orchestration: question
- Retrieval orchestration → MiniLM embeddings: embed question
- Retrieval orchestration → FAISS vector store: top-K search
- Retrieval orchestration → SQLite metadata DB: chunk metadata
- Retrieval orchestration → Grounded generator: grounded chunks
- Grounded generator → Google Gemini: generate answer
- Query routes → History routes: query / answer record
- History routes → SQLite metadata DB: history
- Runtime configuration → Password + JWT: JWT settings
- Runtime configuration → Grounded generator: Gemini credentials