Spaces:
Paused
Paused
| title: Graph RAG Chatbot | |
| emoji: 🤖 | |
| colorFrom: blue | |
| colorTo: purple | |
| sdk: docker | |
| sdk_version: "1.0" | |
| python_version: "3.11" | |
| app_file: app.py | |
| pinned: false | |
| # 🤖 Graph RAG Chatbot | |
| A production-ready **Retrieval-Augmented Generation (RAG) chatbot** with **Knowledge Graph visualization**, powered by Groq's fast LLM API and built with Flask. | |
| ## ✨ Features | |
| - 📤 **Document Upload**: Support for PDF, CSV, and TXT files (up to 50MB) | |
| - 📊 **Knowledge Graph Building**: Automatic graph construction from documents using NetworkX | |
| - 📈 **Graph Visualization**: Interactive visualization of knowledge graphs with Matplotlib | |
| - 💬 **RAG-Powered Chat**: Query documents using semantic search + Groq Mixtral LLM | |
| - ⚡ **Real-time Updates**: Background processing with live progress tracking | |
| - 📱 **Responsive UI**: Modern, mobile-friendly interface (tested on all devices) | |
| - 🔐 **Secure**: API keys managed via environment secrets (never exposed) | |
| - 🚀 **Production Ready**: Docker containerized, health checks enabled | |
| ## 🎯 How It Works | |
| ### Document Processing Pipeline | |
| ``` | |
| Upload Document | |
| ↓ | |
| Text Extraction (PDF/CSV/TXT) | |
| ↓ | |
| Text Chunking (Recursive character splitting) | |
| ↓ | |
| Knowledge Graph Building (NetworkX) | |
| ↓ | |
| Graph Visualization (Matplotlib PNG) | |
| ↓ | |
| Chunk Embeddings (SentenceTransformers) | |
| ↓ | |
| Document Ready for Queries | |
| ``` | |
| ### Query Processing with RAG | |
| ``` | |
| User Question | |
| ↓ | |
| Embed Query | |
| ↓ | |
| Find Similar Document Chunks (Cosine similarity) | |
| ↓ | |
| Send Top-3 Chunks + Question to Groq | |
| ↓ | |
| LLM Generates Answer | |
| ↓ | |
| Return Answer + Sources + Confidence | |
| ``` | |
| ## 🚀 Quick Start | |
| ### Prerequisites | |
| - Groq API Key (free at https://console.groq.com) | |
| - Docker (optional, but recommended) | |
| ### Option 1: Docker Compose (Recommended) ⭐ | |
| ```bash | |
| # Clone or download the repository | |
| cd graph-rag-chatbot | |
| # Create environment file | |
| cp .env.example .env | |
| # Edit .env and add your GROQ_API_KEY | |
| # GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| # Start the application | |
| docker-compose up -d | |
| # Access at http://localhost:7860 | |
| ``` | |
| ### Option 2: Python Virtual Environment | |
| ```bash | |
| # Create virtual environment | |
| python -m venv venv | |
| source venv/bin/activate # On Windows: venv\Scripts\activate | |
| # Install dependencies | |
| pip install -r requirements.txt | |
| # Set API key | |
| export GROQ_API_KEY="your_groq_api_key" # On Windows: set GROQ_API_KEY=... | |
| # Run the application | |
| python app.py | |
| # Access at http://localhost:7860 | |
| ``` | |
| ### Option 3: Hugging Face Spaces (Already Deployed) | |
| If running on HF Spaces: | |
| 1. The app is already running at this Space URL | |
| 2. GROQ_API_KEY is configured as a repository secret | |
| 3. Just upload a document and start asking questions! | |
| ## 📚 Usage Guide | |
| ### Uploading Documents | |
| 1. Click the **Upload Zone** or drag & drop files | |
| 2. Supported formats: PDF, CSV, TXT | |
| 3. Maximum file size: 50MB | |
| 4. Status progression: | |
| - 🟡 **queued** → Processing will start soon | |
| - 🟠 **processing** → Building graph and embeddings | |
| - 🟢 **ready** → Ready for queries, graph available | |
| ### Viewing Knowledge Graphs | |
| 1. Once document status is "ready", click **"📈 View Full Graph"** | |
| 2. Or switch to the **"Knowledge Graph"** tab | |
| 3. Select the document from the dropdown | |
| 4. Graph shows: | |
| - 🔵 Blue nodes = Document chunks | |
| - 🟢 Green nodes = Extracted entities (keywords) | |
| - Edges = Relationships between chunks and entities | |
| ### Asking Questions | |
| 1. Select a document from the dropdown | |
| 2. Type your question in the chat box | |
| 3. Press **Enter** or click **Send** | |
| 4. Bot responds with: | |
| - Answer based on document content | |
| - Source chunks used | |
| - Confidence score | |
| ## 🔌 API Endpoints | |
| ### `GET /` | |
| Serves the main web interface (HTML/CSS/JS) | |
| ### `GET /api/documents` | |
| Get list of all documents and their status | |
| ```json | |
| { | |
| "documents": { | |
| "example.pdf": { | |
| "status": "ready", | |
| "chunks": 15, | |
| "entities": 42, | |
| "graph_image": "/graph-image/example.pdf", | |
| "progress": 100 | |
| } | |
| }, | |
| "api_key_set": true, | |
| "timestamp": "2024-06-27T10:30:00" | |
| } | |
| ``` | |
| ### `POST /api/upload` | |
| Upload documents for processing | |
| ```bash | |
| curl -X POST \ | |
| -F "files=@document.pdf" \ | |
| http://localhost:7860/api/upload | |
| ``` | |
| Response: | |
| ```json | |
| { | |
| "success": true, | |
| "message": "✅ 1 file(s) queued for processing", | |
| "successful": 1, | |
| "failed": 0, | |
| "files": ["document.pdf"] | |
| } | |
| ``` | |
| ### `POST /api/query` | |
| Query a document with RAG | |
| ```bash | |
| curl -X POST \ | |
| -H "Content-Type: application/json" \ | |
| -d '{ | |
| "query": "What is the main topic?", | |
| "document": "example.pdf" | |
| }' \ | |
| http://localhost:7860/api/query | |
| ``` | |
| Response: | |
| ```json | |
| { | |
| "answer": "The main topic is...", | |
| "sources": ["Chunk 1", "Chunk 3"], | |
| "confidence": 0.92 | |
| } | |
| ``` | |
| ### `GET /graph-image/{filename}` | |
| Download the graph visualization PNG for a document | |
| ### `DELETE /api/delete/{filename}` | |
| Delete a document and its graph data | |
| ## ⚙️ Configuration | |
| ### Environment Variables | |
| ```env | |
| GROQ_API_KEY=your_groq_api_key_here # Required: LLM API access | |
| PORT=7860 # Optional: Application port (default: 7860) | |
| FLASK_ENV=production # Optional: Flask environment mode | |
| ``` | |
| ### Customizable Parameters (in app.py) | |
| **Chunk Size** (line ~66): | |
| ```python | |
| chunk_size=500, # Size of text chunks in characters | |
| chunk_overlap=100 # Overlap between chunks for context | |
| ``` | |
| **Embedding Model** (line ~27): | |
| ```python | |
| embedding_model = SentenceTransformer('all-MiniLM-L6-v2') | |
| # Lightweight, fast model (~27MB) | |
| # Change to 'all-mpnet-base-v2' for higher quality (slower) | |
| ``` | |
| **LLM Configuration** (line ~153): | |
| ```python | |
| model="mixtral-8x7b-32768", # Fast, powerful open model | |
| max_tokens=500 # Response length | |
| ``` | |
| **Similarity Threshold** (line ~164): | |
| ```python | |
| if similarities[i] > 0.3 # Increase for stricter matching | |
| ``` | |
| ## 🧪 Testing | |
| Run the test suite to verify all features: | |
| ```bash | |
| # Upload a test document | |
| # Check if status changes to "ready" | |
| # View the knowledge graph | |
| # Ask a question and verify response | |
| # Delete the document | |
| ``` | |
| See `TESTING.md` for 15+ comprehensive test cases with procedures. | |
| ## 📦 Technology Stack | |
| | Component | Technology | Purpose | | |
| |-----------|-----------|---------| | |
| | Backend | Flask 2.3.3 | Web framework | | |
| | LLM | Groq Mixtral 8x7b | Language model for answers | | |
| | Embeddings | SentenceTransformers | Document/query embeddings | | |
| | Graphs | NetworkX 3.1 | Graph algorithms | | |
| | Visualization | Matplotlib 3.7.2 | Graph visualization | | |
| | Frontend | HTML5/CSS3/JavaScript | Web interface | | |
| | Containerization | Docker 20.10+ | Deployment | | |
| | Orchestration | Docker Compose 1.29+ | Multi-container management | | |
| ## 📊 Performance | |
| ### Processing Speed | |
| | Operation | Time | | |
| |-----------|------| | |
| | App startup (cold) | 30-60s (first run, model download) | | |
| | App startup (warm) | 2-3s | | |
| | Small file upload (<5MB) | 5-10s | | |
| | Medium file (5-20MB) | 15-30s | | |
| | Large file (20-50MB) | 30-60s | | |
| | Query response | 2-5s | | |
| | Graph visualization | <1s | | |
| ### Resource Requirements | |
| - **CPU**: 2 vCPU recommended | |
| - **RAM**: 4GB minimum, 8GB recommended | |
| - **Disk**: 10GB for models + data | |
| - **Network**: 100Mbps+ for first setup | |
| ### Concurrent Processing | |
| - Multiple documents: 3+ simultaneous uploads | |
| - Multiple queries: 5+ concurrent requests | |
| - UI responsiveness: Always responsive | |
| ## 🔐 Security | |
| ✅ **API Key Protection** | |
| - GROQ_API_KEY stored in environment (never in code) | |
| - Never exposed to frontend | |
| - Injected at runtime | |
| ✅ **Data Privacy** | |
| - Files stored server-side only | |
| - No data sent to third parties (except Groq for queries) | |
| - User queries only sent to Groq | |
| ✅ **Container Security** | |
| - Minimal Python slim base image | |
| - No root user privileges required | |
| - Health checks enabled | |
| - Resource limits supported | |
| ✅ **Input Validation** | |
| - File type verification | |
| - File size limits (50MB) | |
| - Sanitized error messages | |
| ## 🐛 Troubleshooting | |
| ### "GROQ_API_KEY not configured" | |
| **Solution**: | |
| - Check `.env` file has your API key | |
| - In HF Spaces: Verify secret is added in Settings | |
| - Restart the application | |
| ### Port 7860 already in use | |
| **Solution**: | |
| ```bash | |
| # Use different port | |
| PORT=8000 python app.py | |
| # Or find and stop the process | |
| lsof -i :7860 # Mac/Linux | |
| netstat -ano | findstr :7860 # Windows | |
| ``` | |
| ### Graph doesn't load | |
| **Solution**: | |
| - Ensure document status is "ready" (wait 3-5 seconds) | |
| - Check `data/graph_data/` folder exists | |
| - Verify write permissions | |
| - Check browser console (F12) for errors | |
| ### Chat not responding | |
| **Solution**: | |
| - Verify GROQ_API_KEY is set | |
| - Check document status is "ready" | |
| - Verify internet connectivity | |
| - Check application logs | |
| ### Model download too slow | |
| **Solution**: | |
| - This is normal on first run (30-60 seconds) | |
| - Model is cached after first download | |
| - Subsequent starts are instant | |
| ## 📁 Project Structure | |
| ``` | |
| graph-rag-chatbot/ | |
| ├── app.py # Main Flask application | |
| ├── templates/ | |
| │ └── index.html # Web interface | |
| ├── requirements.txt # Python dependencies | |
| ├── Dockerfile # Container definition | |
| ├── docker-compose.yml # Docker Compose config | |
| ├── .env.example # Configuration template | |
| ├── data/ | |
| │ ├── uploads/ # Uploaded documents | |
| │ └── graph_data/ # Generated graphs | |
| └── README.md # This file | |
| ``` | |
| ## 🚀 Deployment | |
| ### Local Deployment | |
| See Quick Start section above | |
| ### Docker Deployment | |
| ```bash | |
| docker build -t graph-rag-chatbot . | |
| docker run -p 7860:7860 \ | |
| -e GROQ_API_KEY=your_key \ | |
| -v $(pwd)/data:/app/data \ | |
| graph-rag-chatbot | |
| ``` | |
| ### Hugging Face Spaces | |
| This Space is already configured for HF Spaces deployment: | |
| - SDK: Docker | |
| - App file: app.py | |
| - Secrets: GROQ_API_KEY (set in Space Settings) | |
| ### Cloud Deployment (AWS/Azure/GCP) | |
| See `DEPLOYMENT_CHECKLIST.md` for detailed instructions | |
| ## 💡 Tips & Best Practices | |
| ✅ **Performance** | |
| - Use Docker Compose for easiest setup | |
| - Test with CSV first (fastest processing) | |
| - Larger chunks = better context but slower processing | |
| - Smaller chunks = faster processing but less context | |
| ✅ **Customization** | |
| - Colors: Edit CSS in `index.html` (~line 50) | |
| - Title: Edit HTML title and headers | |
| - Upload limit: Change `MAX_CONTENT_LENGTH` in `app.py` | |
| - Add more file types in `DocumentProcessor` class | |
| ✅ **Production** | |
| - Set `FLASK_ENV=production` | |
| - Use Gunicorn instead of Flask dev server | |
| - Enable HTTPS/SSL | |
| - Add authentication if needed | |
| - Monitor logs and metrics | |
| ## 📞 Support | |
| ### Documentation Files | |
| - **START_HERE.md** - Quick overview and FAQ | |
| - **QUICKSTART.md** - 5-minute setup guide | |
| - **TESTING.md** - Test cases and procedures | |
| - **DEPLOYMENT_CHECKLIST.md** - Production readiness | |
| - **PROJECT_STRUCTURE.md** - Architecture details | |
| ### Getting Help | |
| 1. Check the relevant documentation file above | |
| 2. Review the troubleshooting section | |
| 3. Check application logs: `docker-compose logs -f` | |
| 4. Verify API key is set correctly | |
| ## 📝 Known Limitations | |
| 1. **Storage**: Ephemeral (HF Spaces free tier) | |
| - Solution: Upgrade to persistent storage | |
| 2. **Processing Speed**: Single machine | |
| - Solution: Use GPU tier or distributed processing | |
| 3. **Concurrency**: Python GIL limitation | |
| - Solution: Use Gunicorn with multiple workers | |
| 4. **Graph Complexity**: Limited to 500 nodes for visualization | |
| - Solution: Implement hierarchical layouts | |
| 5. **API Rate Limits**: Groq free tier (30 req/min) | |
| - Solution: Upgrade Groq plan or implement caching | |
| ## 🎯 Future Enhancements | |
| - [ ] User authentication | |
| - [ ] Persistent database (PostgreSQL) | |
| - [ ] Vector database (ChromaDB/Pinecone) | |
| - [ ] Advanced graph algorithms | |
| - [ ] Conversation memory | |
| - [ ] Export to PDF reports | |
| - [ ] Multi-language support | |
| - [ ] WebSocket for real-time updates | |
| - [ ] API rate limiting | |
| - [ ] Advanced analytics | |
| ## 📄 License | |
| MIT License - Feel free to use for personal or commercial projects | |
| ## 🙏 Credits | |
| - **Framework**: Flask | |
| - **LLM**: Groq API | |
| - **Embeddings**: Hugging Face SentenceTransformers | |
| - **Graphs**: NetworkX | |
| - **Visualization**: Matplotlib | |
| - **Deployment**: Docker | |
| --- | |
| ## Quick Links | |
| | Link | Purpose | | |
| |------|---------| | |
| | [Groq Console](https://console.groq.com) | Get API key | | |
| | [GitHub Issues](https://github.com/yourusername/graph-rag-chatbot/issues) | Report issues | | |
| | [Documentation](./README.md) | Full docs | | |
| --- | |
| **Created**: June 27, 2024 | |
| **Version**: 1.0.0 | |
| **Status**: ✅ Production Ready | |
| Made with ❤️ for Knowledge Graph RAG applications | |