Spaces:
Sleeping
Sleeping
| title: PDF Explainer Using RAG | |
| emoji: 📚 | |
| colorFrom: blue | |
| colorTo: green | |
| sdk: docker | |
| pinned: false | |
| license: mit | |
| short_description: A pdf explainer using retrieval-augmented generation (RAG) | |
| # 📄 PDF Explainer Using RAG | |
| A powerful AI-powered chatbot that allows you to upload PDF documents and ask intelligent questions about their content using Retrieval-Augmented Generation (RAG) technology. | |
| <p align="center"><img src="app_screenshot.png" width="900"/></p> | |
| ## 🚀 Features | |
| - **🤖 Smart AI Assistant**: Works as a general-purpose chatbot even without uploaded documents | |
| - **📤 PDF Upload & Processing**: Upload single or multiple PDF documents with automatic text extraction | |
| - **🎯 RAG-Powered Responses**: Uses advanced embedding models to find relevant document content | |
| - **💬 Streaming Responses**: Real-time streaming chat interface for smooth conversations | |
| - **🔄 Multiple Uploads**: Add more PDFs during conversations to expand the knowledge base | |
| - **📊 Table Support**: Enhanced extraction of tables and structured content from PDFs | |
| - **🏷️ Source Citations**: Responses include filename and page number references | |
| - **🐳 Docker Ready**: Easy deployment with Docker containerization | |
| ## 🛠️ Technologies Used | |
| - **Frontend**: [Gradio](https://gradio.app/) - Interactive web interface | |
| - **LLM**: [Groq](https://groq.com/) with Llama 3.1 8B Instant model | |
| - **PDF Processing**: [PyMuPDF4LLM](https://pypi.org/project/pymupdf4llm/) - Optimized for LLM workflows | |
| - **Vector Database**: [ChromaDB](https://www.trychroma.com/) - Efficient similarity search | |
| - **Embeddings**: [BGE-small-en-v1.5](https://huggingface.co/BAAI/bge-small-en-v1.5) - High-quality text embeddings | |
| - **Text Chunking**: [LangChain Text Splitters](https://python.langchain.com/docs/modules/data_connection/document_transformers/) - Intelligent text segmentation | |
| ## 📋 Prerequisites | |
| - Python 3.8+ | |
| - Groq API key (free at [console.groq.com](https://console.groq.com)) | |
| ## 🔧 Installation | |
| ### Local Setup | |
| 1. **Clone the repository**: | |
| ```bash | |
| git clone https://github.com/your-username/pdf-explainer-using-rag.git | |
| cd pdf-explainer-using-rag | |
| ``` | |
| 2. **Create virtual environment**: | |
| ```bash | |
| python -m venv proj_env | |
| source proj_env/bin/activate # On Windows: proj_env\Scripts\activate | |
| ``` | |
| 3. **Install dependencies**: | |
| ```bash | |
| pip install -r requirements.txt | |
| ``` | |
| 4. **Set up environment variables**: | |
| ```bash | |
| # Create .env file | |
| echo "GROQ_API_KEY=your_groq_api_key_here" > .env | |
| ``` | |
| 5. **Run the application**: | |
| ```bash | |
| cd app | |
| python app.py | |
| ``` | |
| 6. **Access the application**: | |
| Open your browser and go to `http://localhost:7860` | |
| ### Docker Setup | |
| 1. **Build the Docker image**: | |
| ```bash | |
| docker build -t pdf-explainer . | |
| ``` | |
| 2. **Run the container**: | |
| ```bash | |
| docker run -p 7860:7860 -e GROQ_API_KEY=your_groq_api_key_here pdf-explainer | |
| ``` | |
| 3. **Access the application**: | |
| Open your browser and go to `http://localhost:7860` | |
| ## 🎯 Usage | |
| ### Getting Started | |
| 1. **Open the application** in your web browser | |
| 2. **Start chatting** immediately - the AI works as a general assistant without any uploads | |
| 3. **Upload PDFs** (optional) using the file upload section | |
| 4. **Ask questions** about your documents - the AI will automatically find and use relevant content | |
| ### Example Workflows | |
| **General Chat** (No PDFs needed): | |
| ``` | |
| User: "What are the benefits of renewable energy?" | |
| AI: [Provides general knowledge response] | |
| ``` | |
| **Document-Specific Questions** (After uploading PDFs): | |
| ``` | |
| User: "What is the main conclusion of the research paper?" | |
| AI: "According to the research paper (research_paper.pdf, Page 15), | |
| the main conclusion is that renewable energy adoption..." | |
| ``` | |
| **Multi-Document Analysis**: | |
| ``` | |
| User: "Compare the methodologies mentioned in both documents" | |
| AI: "Comparing the methodologies: | |
| From methodology_paper.pdf (Page 3): [methodology A details] | |
| From comparison_study.pdf (Page 7): [methodology B details]..." | |
| ``` | |
| ## 📁 Project Structure | |
| ``` | |
| pdf-explainer-using-rag/ | |
| ├── app/ | |
| │ ├── app.py # Main Gradio application | |
| │ ├── llm.py # LLM integration with RAG | |
| │ ├── retrieval.py # PDF processing and vector operations | |
| ├── Dockerfile # Docker configuration | |
| ├── .dockerignore # Docker ignore rules | |
| ├── .gitignore # Git ignore rules | |
| └── requirements.txt # Python dependencies | |
| └── README.md # This file | |
| ``` | |
| ## ⚙️ Configuration | |
| ### Environment Variables | |
| | Variable | Description | Required | | |
| |----------|-------------|----------| | |
| | `GROQ_API_KEY` | Your Groq API key for LLM access | Yes | | |
| ### Customizable Parameters | |
| **In `retrieval.py`**: | |
| - `chunk_size`: Text chunk size (default: 500) | |
| - `chunk_overlap`: Overlap between chunks (default: 150) | |
| - `top_k`: Number of retrieved documents (default: 5) | |
| **In `llm.py`**: | |
| - `model`: Groq model name (default: "llama-3.1-8b-instant") | |
| - `temperature`: Response creativity (default: 0.7) | |
| ## 🔍 How It Works | |
| 1. **PDF Upload**: Documents are parsed using PyMuPDF4LLM with markdown formatting | |
| 2. **Text Processing**: Content is cleaned and split into semantic chunks | |
| 3. **Embedding**: Text chunks are converted to vectors using BGE embeddings | |
| 4. **Storage**: Vectors and metadata are stored in ChromaDB | |
| 5. **Retrieval**: User questions trigger similarity search for relevant chunks | |
| 6. **Generation**: LLM generates responses using retrieved context and chat history | |
| ## 🚀 Deployment Options | |
| ### Local Development | |
| - Run directly with Python for development and testing | |
| ### Docker Container | |
| - Production-ready containerized deployment | |
| - Includes pre-downloaded embedding models for faster startup | |
| ### Cloud Deployment | |
| - Compatible with any cloud platform supporting Docker | |
| - Requires Groq API key as environment variable | |
| ## 🤝 Contributing | |
| 1. Fork the repository | |
| 2. Create a feature branch (`git checkout -b feature/amazing-feature`) | |
| 3. Commit your changes (`git commit -m 'Add amazing feature'`) | |
| 4. Push to the branch (`git push origin feature/amazing-feature`) | |
| 5. Open a Pull Request | |