RAG Assistant — Retrieval-Augmented Generation Project

A simple, complete Retrieval-Augmented Generation (RAG) project built with plain Python files (no notebooks), ChromaDB, sentence-transformers, and OpenRouter, wrapped in a Streamlit UI.

Pipeline

documents
  -> preprocessing
  -> chunking
  -> vector representation
  -> vector store
  -> context retrieval
  -> prompting
  -> Streamlit UI

Project Structure

.
├── 01_documents.py              # Stage 1: load raw documents (.txt, .md, .pdf)
├── 02_preprocessing.py          # Stage 2: clean and normalize text
├── 03_chunking.py                # Stage 3: split text into overlapping chunks
├── 04_vector_representation.py  # Stage 4: embed chunks (sentence-transformers)
├── 05_create_chroma_store.py    # Stage 5: build/persist the ChromaDB vector store
├── 06_retrieve_context.py       # Stage 6: retrieve relevant chunks for a question
├── 07_prompting.py               # Stage 7: build prompt + call OpenRouter (LLM)
├── streamlit_app.py              # Streamlit UI wiring every stage together
├── requirements.txt
├── .gitignore
├── .env.example                  # Template only — never commit your real .env
├── data/
│   └── sample_document.txt       # Example source document
└── README.md

Each numbered file can also be run directly (e.g. python 03_chunking.py) to see that pipeline stage working in isolation — useful for debugging and for the lab sequence walkthrough.

How the files connect

Because Python module names can't start with a digit, the numbered stage files are loaded dynamically with importlib wherever one stage needs another (e.g. 03_chunking.py loads 02_preprocessing.py). streamlit_app.py loads 07_prompting.py as a module named rag, and stage 7 internally loads stage 6, which loads stage 5, and so on down to stage 1. You never need to do this manually — it's already wired up in every file.

1. Installation Guide (local)

Prerequisites: Python 3.10+

# 1. Clone your repository (or unzip the project)
git clone <your-repo-url>
cd <your-repo-folder>

# 2. Create and activate a virtual environment
python -m venv venv
source venv/bin/activate      # Windows: venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure your API key locally
cp .env.example .env
# then open .env and paste your real OpenRouter key into OPENROUTER_API_KEY

Get a free OpenRouter API key at https://openrouter.ai/keys.

Run the pipeline stages individually (optional, for testing)

python 01_documents.py
python 02_preprocessing.py
python 03_chunking.py
python 04_vector_representation.py
python 05_create_chroma_store.py
python 06_retrieve_context.py
python 07_prompting.py

Run the Streamlit app locally

streamlit run streamlit_app.py

Then open the local URL Streamlit prints (usually http://localhost:8501), click "Build / Rebuild Vector Store" in the sidebar, and start asking questions.

2. API Key Rules (important)

• Never write your real API key inside any .py file.
• Never commit or upload your real .env file — .gitignore already excludes it.
• Locally, keys are read from environment variables (via .env + python-dotenv).
• On Streamlit Cloud, keys are read from Streamlit secrets (TOML), not from files.

3. GitHub Upload Guide

git init
git add .
git commit -m "Initial commit: complete RAG project"
git branch -M main
git remote add origin https://github.com/<your-username>/<your-repo-name>.git
git push -u origin main

Before pushing, double-check:

• .env is not staged (git status should not show it — .gitignore blocks it)
• No API key appears anywhere in any tracked file
• chroma_store/ is not committed (it's local-only, ignored by .gitignore)

4. Streamlit Deployment Guide

1. Push your repository to GitHub (see above).

2. Go to https://share.streamlit.io and sign in.

3. Click "New app", select your repository, branch, and set the main file path to streamlit_app.py.

4. Before (or after) deploying, open your app, click "Manage app" → "Secrets", and add:

   OPENROUTER_API_KEY = "your_openrouter_key_here"
   OPENROUTER_MODEL = "openai/gpt-4o-mini"

5. Click Deploy. streamlit_app.py automatically reads these secrets and injects them into the RAG pipeline at runtime — no code changes needed.

6. Once deployed, open the app, build the vector store from the sidebar, and test a question to confirm everything works end-to-end.

5. Final Submission Checklist

• All required Python files exist (01_documents.py → 07_prompting.py, streamlit_app.py).
• requirements.txt exists.
• Real API key is not included in the ZIP file or GitHub repository.
• Streamlit secrets are configured in valid TOML format at deploy time.
• The Streamlit app runs successfully.
• The answer uses retrieved context (the LLM is only called when context is found).
• The answer cites sources (filenames shown alongside every generated answer).

Notes on design choices

• Embeddings run locally (sentence-transformers, model all-MiniLM-L6-v2) so the project only needs one paid API key (OpenRouter, for generation) — not two.
• ChromaDB is used as the vector store, persisted to a local chroma_store/ folder.
• OpenRouter is used for the generation step, defaulting to openai/gpt-4o-mini, matching the API key rules in the instructions.
• If retrieval returns no chunks, the app never calls the LLM and instead shows a clear "not enough information" message — this guarantees answers are always grounded in retrieved documents when they are given at all.