Welcome to the Full-Stack RAG (Retrieval-Augmented Generation) Chatbot project! This is a fast, efficient, and fully functional full-stack application. It allows users to upload multiple types of documents (PDF, DOCX, TXT, CSV), processes them into a vector database, and lets users chat with their documents using advanced AI.
This project features a clean modular backend architecture built with FastAPI and a beautiful, easy-to-use frontend built with Streamlit.
- Frontend: Streamlit (for a beautiful, fast Python-only UI)
- Backend: FastAPI (for high-performance API routing)
- AI Orchestration: LangChain (
0.3.x) - LLM: Groq API (
llama-3.1-8b-instant) for lightning-fast text generation. - Embeddings: HuggingFace
all-MiniLM-L6-v2(runs locally, completely free). - Vector Database: FAISS (Facebook AI Similarity Search) for fast chunk retrieval.
- Resilience: Tenacity (Automatic retry logic on API failures).
The codebase is organized following modern enterprise patterns to separate concerns, making it highly maintainable and scalable.
rag-chatbot/
│
├── core/
│ └── config.py # Centralized configuration, environment variables, and logger setup
│
├── models/
│ └── schemas.py # Pydantic models defining the API Request/Response shapes (e.g. ChatQuery)
│
├── services/
│ ├── llm_service.py # AI logic: Initializes Groq LLM, handles Chat Memory, and Summarization chains
│ └── vector_service.py # Data logic: Handles Document Loaders (PDF, TXT, DOCX, CSV), text chunking, and FAISS operations
│
├── api/
│ ├── __init__.py # Python package initializer
│ ├── upload.py # POST /upload: Endpoint logic for ingesting and indexing documents
│ ├── chat.py # POST /chat & POST /chat/stream: Endpoints for asking questions and streaming SSE responses
│ └── summarize.py # POST /summarize: Endpoint for executing map-reduce document summarization
│
├── main.py # FastAPI Application Entry Point: Initializes the app and includes all routers from api/
├── ui.py # Streamlit Frontend: The beautiful chat interface that connects to the FastAPI backend
│
├── start.sh # Deployment Script: Starts both FastAPI (background) and Streamlit (foreground) for Render deployment
├── Dockerfile # Container configuration for deploying the full-stack application
├── pyproject.toml # Dependency definitions (managed by 'uv')
└── uv.lock # Deterministic lockfile for dependencies
- Multi-Format Uploads: Supports
.pdf,.docx,.txt, and.csv. The backend dynamically chooses the optimal LangChain document loader. - Conversational Memory: The chatbot remembers previous questions in your session context, allowing for follow-up questions.
- Exact Quote Citations: Every answer includes the source file, page number, and the exact text quote used to generate the answer.
- Real-Time Streaming: Answers stream to the UI word-by-word via Server-Sent Events (SSE), just like ChatGPT.
- Auto-Summarization: A dedicated endpoint and UI button that utilizes Map-Reduce chains to summarize large documents.
To run this project locally, you will need:
- Python (3.11 or newer)
- A free Groq API Key (Get one at console.groq.com)
- The incredibly fast Python package manager
uv(Install viapip install uv).
1. Clone or download the repository to your local machine.
2. Install dependencies:
Using uv (recommended):
uv sync3. Setup your Environment Variables:
Create a file named .env in the root folder of the project (rag-chatbot/.env) and add your API key:
GROQ_API_KEY=your_actual_groq_api_key_here
# Optional Configurations
ENABLE_DOCS=true
EMBEDDING_MODEL=all-MiniLM-L6-v2
GROQ_MODEL=llama-3.1-8b-instantBecause this project features both a backend API and a frontend UI, you need to start both services.
Terminal 1 (Start the Backend API):
uv run uvicorn main:app --port 8000 --reloadTerminal 2 (Start the Streamlit UI):
uv run streamlit run ui.pyStreamlit will automatically open a browser tab to http://localhost:8501 where you can interact with the app.
This application is configured to run entirely inside a single Docker container, exposing only the Streamlit UI port (which natively connects to the internal FastAPI server). This is perfect for deploying on free tiers like Render!
1. Build the image:
docker build -t rag-app .2. Run the container:
docker run -p 8501:8501 rag-appOnce running, go to http://localhost:8501 in your browser. Both FastAPI and Streamlit are now running simultaneously inside the container via start.sh!
If you set ENABLE_DOCS=true in your .env, you can open your browser to http://127.0.0.1:8000/docs to test the API directly using a visual UI!
Otherwise, you can interact with the API backend directly using tools like Postman, curl, or your own frontend code:
- Endpoint:
GET / - Description: Checks if the server is running.
- Response:
{"message": "RAG chatbot API is running", "routes": [...]}
- Endpoint:
POST /upload - Description: Uploads a
.pdf,.docx,.txt, or.csvfile to be processed into the vector database. - Input: Form-Data with a
filefield. - Curl Example:
curl -X POST "http://127.0.0.1:8000/upload" -F "file=@path/to/your/document.pdf"
- Endpoint:
POST /chat - Description: Ask a question. The AI will answer using the context of the uploaded documents.
- Input: JSON body containing a
queryand an optionalsession_id. - Curl Example:
curl -X POST "http://127.0.0.1:8000/chat" \ -H "Content-Type: application/json" \ -d '{"query":"What is the main topic of the document?", "session_id":"my-session"}'
- Endpoint:
POST /chat/stream - Description: Streams the AI answer word-by-word via Server-Sent Events (SSE).
- Curl Example:
curl -N -X POST "http://127.0.0.1:8000/chat/stream" \ -H "Content-Type: application/json" \ -d '{"query":"Summarize the introduction."}'
- Endpoint:
POST /summarize - Description: Generates a full summary of the uploaded document using Map-Reduce.
- Curl Example:
curl -X POST "http://127.0.0.1:8000/summarize" \ -H "Content-Type: application/json" \ -d '{}'
Happy coding!