An educational Python project to demonstrate how RAG (Retrieval-Augmented Generation) systems work.

This project implements a complete RAG system from scratch, showing each component of the process:

• Document loading
• Processing and chunking
• Embedding generation
• Vector storage
• Information retrieval
• Answer generation with LLMs

• Python 3.10 or higher
• Node.js 18+ (for the frontend)
• OpenAI API Key (to use GPT models)

1. Create virtual environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install dependencies

pip install -r requirements.txt
pip install -r backend/requirements.txt

3. Configure environment variables

Copy the .env.example file to .env and configure your API key:

cp .env.example .env

Edit .env and add your OpenAI API Key:

OPENAI_API_KEY=your_api_key_here

cd frontend
npm install

1. Start Backend:

# In one terminal
source venv/bin/activate
cd backend
python main.py

The backend will be at http://localhost:8000

2. Start Frontend:

# In another terminal
cd frontend
npm run dev

The frontend will be at http://localhost:5173

Run the Streamlit application:

streamlit run app/main.py

Explore the educational notebooks in the notebooks/ folder:

1. 01_data_loading.ipynb - Document loading
2. 02_embeddings.ipynb - Embedding generation
3. 03_retrieval.ipynb - Retrieval system
4. 04_full_rag.ipynb - Complete RAG system

from src.document_loader import DocumentLoader
from src.text_splitter import TextSplitter
from src.embeddings import EmbeddingGenerator
from src.vector_store import VectorStore
from src.retriever import Retriever
from src.rag_chain import RAGChain

# 1. Load documents
loader = DocumentLoader()
documents = loader.load_directory("./data/documents")

# 2. Split into chunks
splitter = TextSplitter(chunk_size=1000, chunk_overlap=200)
chunks = splitter.split_documents(documents)

# 3. Generate embeddings
embedding_gen = EmbeddingGenerator()
chunks_with_embeddings = embedding_gen.generate_embeddings_for_chunks(chunks)

# 4. Store in vector store
vector_store = VectorStore(collection_name="my_rag", reset=True)
vector_store.add_chunks(chunks_with_embeddings)

# 5. Create retriever and RAG chain
retriever = Retriever(vector_store, embedding_gen, top_k=3)
rag_chain = RAGChain(retriever, model_name="gpt-3.5-turbo")

# 6. Ask a question
result = rag_chain.query("What is RAG?")
print(result['answer'])

rag-playground/
├── src/                    # Main source code
│   ├── document_loader.py  # Document loading
│   ├── text_splitter.py    # Chunk splitting
│   ├── embeddings.py       # Embedding generation
│   ├── vector_store.py     # Vector database
│   ├── retriever.py        # Retrieval system
│   ├── rag_chain.py        # Complete RAG chain
│   └── utils.py            # Utilities
├── backend/                # FastAPI Backend
│   ├── main.py             # API server
│   └── requirements.txt    # Backend dependencies
├── frontend/               # React Frontend
│   ├── src/
│   │   ├── components/     # React components
│   │   └── App.jsx         # Main app
│   └── package.json        # Frontend dependencies
├── app/                    # Streamlit application
│   └── main.py             # Web interface
├── data/                   # Data
│   ├── documents/          # Example documents
│   └── vector_db/          # Vector database (generated)
├── notebooks/              # Educational notebooks
├── tests/                  # Unit tests
└── requirements.txt        # Python dependencies

You can configure various aspects of the system by editing the .env file:

• OPENAI_API_KEY: Your OpenAI API key
• LLM_MODEL: Model to use (default: gpt-3.5-turbo)
• LLM_TEMPERATURE: Temperature for generation (0.0-1.0)
• EMBEDDING_MODEL: Embedding model (default: sentence-transformers/all-MiniLM-L6-v2)
• CHUNK_SIZE: Chunk size (default: 1000)
• CHUNK_OVERLAP: Overlap between chunks (default: 200)
• TOP_K: Number of chunks to retrieve (default: 3)

Run tests with pytest:

pytest tests/

The project includes example documents in data/documents/:

• sample1.txt - Introduction to RAG
• sample2.txt - Embeddings and vector representations
• sample3.md - Chunking and processing

You can add your own documents to experiment.

This project demonstrates:

1. Document Loading: How to load different formats (PDF, TXT, MD, DOCX)
2. Chunking: Strategies for splitting documents into manageable fragments
3. Embeddings: How to convert text into vector representations
4. Vector Stores: Storage and search of embeddings
5. Retrieval: How to find relevant information using similarity
6. RAG Chain: Combination of retrieval and generation with LLMs

• Python 3.10+
• LangChain - Framework for LLM applications
• ChromaDB - Vector database
• Sentence Transformers - Embedding models
• OpenAI API - Language models
• FastAPI - REST API

• React 19 - UI framework
• Tailwind CSS - Styling
• Vite - Build tool

• Streamlit - Alternative web interface
• PyPDF2 - PDF processing

This is an open-source educational project. Feel free to use and modify it.

Contributions are welcome! If you find bugs or have suggestions, please open an issue or submit a pull request.

• LangChain Documentation
• ChromaDB Documentation
• Sentence Transformers
• RAG Paper

• This project requires an OpenAI API key to function completely
• Embedding models are downloaded automatically the first time
• The vector database is created automatically in data/vector_db/

Enjoy exploring RAG! 🚀