Aigenthix/Graph_RAG7

1---2title: Graph RAG Chatbot3emoji: 🤖4colorFrom: blue5colorTo: purple6sdk: docker7sdk_version: "1.0"8python_version: "3.11"9app_file: app.py10pinned: false11---12 13# 🤖 Graph RAG Chatbot14 15A production-ready **Retrieval-Augmented Generation (RAG) chatbot** with **Knowledge Graph visualization**, powered by Groq's fast LLM API and built with Flask.16 17## ✨ Features18 19- 📤 **Document Upload**: Support for PDF, CSV, and TXT files (up to 50MB)20- 📊 **Knowledge Graph Building**: Automatic graph construction from documents using NetworkX21- 📈 **Graph Visualization**: Interactive visualization of knowledge graphs with Matplotlib22- 💬 **RAG-Powered Chat**: Query documents using semantic search + Groq Mixtral LLM23- ⚡ **Real-time Updates**: Background processing with live progress tracking24- 📱 **Responsive UI**: Modern, mobile-friendly interface (tested on all devices)25- 🔐 **Secure**: API keys managed via environment secrets (never exposed)26- 🚀 **Production Ready**: Docker containerized, health checks enabled27 28## 🎯 How It Works29 30### Document Processing Pipeline31```32Upload Document33    ↓34Text Extraction (PDF/CSV/TXT)35    ↓36Text Chunking (Recursive character splitting)37    ↓38Knowledge Graph Building (NetworkX)39    ↓40Graph Visualization (Matplotlib PNG)41    ↓42Chunk Embeddings (SentenceTransformers)43    ↓44Document Ready for Queries45```46 47### Query Processing with RAG48```49User Question50    ↓51Embed Query52    ↓53Find Similar Document Chunks (Cosine similarity)54    ↓55Send Top-3 Chunks + Question to Groq56    ↓57LLM Generates Answer58    ↓59Return Answer + Sources + Confidence60```61 62## 🚀 Quick Start63 64### Prerequisites65- Groq API Key (free at https://console.groq.com)66- Docker (optional, but recommended)67 68### Option 1: Docker Compose (Recommended) ⭐69 70```bash71# Clone or download the repository72cd graph-rag-chatbot73 74# Create environment file75cp .env.example .env76 77# Edit .env and add your GROQ_API_KEY78# GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx79 80# Start the application81docker-compose up -d82 83# Access at http://localhost:786084```85 86### Option 2: Python Virtual Environment87 88```bash89# Create virtual environment90python -m venv venv91source venv/bin/activate  # On Windows: venv\Scripts\activate92 93# Install dependencies94pip install -r requirements.txt95 96# Set API key97export GROQ_API_KEY="your_groq_api_key"  # On Windows: set GROQ_API_KEY=...98 99# Run the application100python app.py101 102# Access at http://localhost:7860103```104 105### Option 3: Hugging Face Spaces (Already Deployed)106 107If running on HF Spaces:1081. The app is already running at this Space URL1092. GROQ_API_KEY is configured as a repository secret1103. Just upload a document and start asking questions!111 112## 📚 Usage Guide113 114### Uploading Documents115 1161. Click the **Upload Zone** or drag & drop files1172. Supported formats: PDF, CSV, TXT1183. Maximum file size: 50MB1194. Status progression:120   - 🟡 **queued** → Processing will start soon121   - 🟠 **processing** → Building graph and embeddings122   - 🟢 **ready** → Ready for queries, graph available123 124### Viewing Knowledge Graphs125 1261. Once document status is "ready", click **"📈 View Full Graph"**1272. Or switch to the **"Knowledge Graph"** tab1283. Select the document from the dropdown1294. Graph shows:130   - 🔵 Blue nodes = Document chunks131   - 🟢 Green nodes = Extracted entities (keywords)132   - Edges = Relationships between chunks and entities133 134### Asking Questions135 1361. Select a document from the dropdown1372. Type your question in the chat box1383. Press **Enter** or click **Send**1394. Bot responds with:140   - Answer based on document content141   - Source chunks used142   - Confidence score143 144## 🔌 API Endpoints145 146### `GET /`147Serves the main web interface (HTML/CSS/JS)148 149### `GET /api/documents`150Get list of all documents and their status151```json152{153  "documents": {154    "example.pdf": {155      "status": "ready",156      "chunks": 15,157      "entities": 42,158      "graph_image": "/graph-image/example.pdf",159      "progress": 100160    }161  },162  "api_key_set": true,163  "timestamp": "2024-06-27T10:30:00"164}165```166 167### `POST /api/upload`168Upload documents for processing169```bash170curl -X POST \171  -F "files=@document.pdf" \172  http://localhost:7860/api/upload173```174 175Response:176```json177{178  "success": true,179  "message": "✅ 1 file(s) queued for processing",180  "successful": 1,181  "failed": 0,182  "files": ["document.pdf"]183}184```185 186### `POST /api/query`187Query a document with RAG188```bash189curl -X POST \190  -H "Content-Type: application/json" \191  -d '{192    "query": "What is the main topic?",193    "document": "example.pdf"194  }' \195  http://localhost:7860/api/query196```197 198Response:199```json200{201  "answer": "The main topic is...",202  "sources": ["Chunk 1", "Chunk 3"],203  "confidence": 0.92204}205```206 207### `GET /graph-image/{filename}`208Download the graph visualization PNG for a document209 210### `DELETE /api/delete/{filename}`211Delete a document and its graph data212 213## ⚙️ Configuration214 215### Environment Variables216 217```env218GROQ_API_KEY=your_groq_api_key_here    # Required: LLM API access219PORT=7860                              # Optional: Application port (default: 7860)220FLASK_ENV=production                   # Optional: Flask environment mode221```222 223### Customizable Parameters (in app.py)224 225**Chunk Size** (line ~66):226```python227chunk_size=500,        # Size of text chunks in characters228chunk_overlap=100      # Overlap between chunks for context229```230 231**Embedding Model** (line ~27):232```python233embedding_model = SentenceTransformer('all-MiniLM-L6-v2')234# Lightweight, fast model (~27MB)235# Change to 'all-mpnet-base-v2' for higher quality (slower)236```237 238**LLM Configuration** (line ~153):239```python240model="mixtral-8x7b-32768",  # Fast, powerful open model241max_tokens=500               # Response length242```243 244**Similarity Threshold** (line ~164):245```python246if similarities[i] > 0.3  # Increase for stricter matching247```248 249## 🧪 Testing250 251Run the test suite to verify all features:252 253```bash254# Upload a test document255# Check if status changes to "ready"256# View the knowledge graph257# Ask a question and verify response258# Delete the document259```260 261See `TESTING.md` for 15+ comprehensive test cases with procedures.262 263## 📦 Technology Stack264 265| Component | Technology | Purpose |266|-----------|-----------|---------|267| Backend | Flask 2.3.3 | Web framework |268| LLM | Groq Mixtral 8x7b | Language model for answers |269| Embeddings | SentenceTransformers | Document/query embeddings |270| Graphs | NetworkX 3.1 | Graph algorithms |271| Visualization | Matplotlib 3.7.2 | Graph visualization |272| Frontend | HTML5/CSS3/JavaScript | Web interface |273| Containerization | Docker 20.10+ | Deployment |274| Orchestration | Docker Compose 1.29+ | Multi-container management |275 276## 📊 Performance277 278### Processing Speed279| Operation | Time |280|-----------|------|281| App startup (cold) | 30-60s (first run, model download) |282| App startup (warm) | 2-3s |283| Small file upload (<5MB) | 5-10s |284| Medium file (5-20MB) | 15-30s |285| Large file (20-50MB) | 30-60s |286| Query response | 2-5s |287| Graph visualization | <1s |288 289### Resource Requirements290- **CPU**: 2 vCPU recommended291- **RAM**: 4GB minimum, 8GB recommended292- **Disk**: 10GB for models + data293- **Network**: 100Mbps+ for first setup294 295### Concurrent Processing296- Multiple documents: 3+ simultaneous uploads297- Multiple queries: 5+ concurrent requests298- UI responsiveness: Always responsive299 300## 🔐 Security301 302✅ **API Key Protection**303- GROQ_API_KEY stored in environment (never in code)304- Never exposed to frontend305- Injected at runtime306 307✅ **Data Privacy**308- Files stored server-side only309- No data sent to third parties (except Groq for queries)310- User queries only sent to Groq311 312✅ **Container Security**313- Minimal Python slim base image314- No root user privileges required315- Health checks enabled316- Resource limits supported317 318✅ **Input Validation**319- File type verification320- File size limits (50MB)321- Sanitized error messages322 323## 🐛 Troubleshooting324 325### "GROQ_API_KEY not configured"326**Solution**: 327- Check `.env` file has your API key328- In HF Spaces: Verify secret is added in Settings329- Restart the application330 331### Port 7860 already in use332**Solution**:333```bash334# Use different port335PORT=8000 python app.py336 337# Or find and stop the process338lsof -i :7860  # Mac/Linux339netstat -ano | findstr :7860  # Windows340```341 342### Graph doesn't load343**Solution**:344- Ensure document status is "ready" (wait 3-5 seconds)345- Check `data/graph_data/` folder exists346- Verify write permissions347- Check browser console (F12) for errors348 349### Chat not responding350**Solution**:351- Verify GROQ_API_KEY is set352- Check document status is "ready"353- Verify internet connectivity354- Check application logs355 356### Model download too slow357**Solution**:358- This is normal on first run (30-60 seconds)359- Model is cached after first download360- Subsequent starts are instant361 362## 📁 Project Structure363 364```365graph-rag-chatbot/366├── app.py                      # Main Flask application367├── templates/368│   └── index.html             # Web interface369├── requirements.txt            # Python dependencies370├── Dockerfile                 # Container definition371├── docker-compose.yml         # Docker Compose config372├── .env.example              # Configuration template373├── data/374│   ├── uploads/              # Uploaded documents375│   └── graph_data/           # Generated graphs376└── README.md                 # This file377```378 379## 🚀 Deployment380 381### Local Deployment382See Quick Start section above383 384### Docker Deployment385```bash386docker build -t graph-rag-chatbot .387docker run -p 7860:7860 \388  -e GROQ_API_KEY=your_key \389  -v $(pwd)/data:/app/data \390  graph-rag-chatbot391```392 393### Hugging Face Spaces394This Space is already configured for HF Spaces deployment:395- SDK: Docker396- App file: app.py397- Secrets: GROQ_API_KEY (set in Space Settings)398 399### Cloud Deployment (AWS/Azure/GCP)400See `DEPLOYMENT_CHECKLIST.md` for detailed instructions401 402## 💡 Tips & Best Practices403 404✅ **Performance**405- Use Docker Compose for easiest setup406- Test with CSV first (fastest processing)407- Larger chunks = better context but slower processing408- Smaller chunks = faster processing but less context409 410✅ **Customization**411- Colors: Edit CSS in `index.html` (~line 50)412- Title: Edit HTML title and headers413- Upload limit: Change `MAX_CONTENT_LENGTH` in `app.py`414- Add more file types in `DocumentProcessor` class415 416✅ **Production**417- Set `FLASK_ENV=production`418- Use Gunicorn instead of Flask dev server419- Enable HTTPS/SSL420- Add authentication if needed421- Monitor logs and metrics422 423## 📞 Support424 425### Documentation Files426- **START_HERE.md** - Quick overview and FAQ427- **QUICKSTART.md** - 5-minute setup guide428- **TESTING.md** - Test cases and procedures429- **DEPLOYMENT_CHECKLIST.md** - Production readiness430- **PROJECT_STRUCTURE.md** - Architecture details431 432### Getting Help4331. Check the relevant documentation file above4342. Review the troubleshooting section4353. Check application logs: `docker-compose logs -f`4364. Verify API key is set correctly437 438## 📝 Known Limitations439 4401. **Storage**: Ephemeral (HF Spaces free tier)441   - Solution: Upgrade to persistent storage442 4432. **Processing Speed**: Single machine444   - Solution: Use GPU tier or distributed processing445 4463. **Concurrency**: Python GIL limitation447   - Solution: Use Gunicorn with multiple workers448 4494. **Graph Complexity**: Limited to 500 nodes for visualization450   - Solution: Implement hierarchical layouts451 4525. **API Rate Limits**: Groq free tier (30 req/min)453   - Solution: Upgrade Groq plan or implement caching454 455## 🎯 Future Enhancements456 457- [ ] User authentication458- [ ] Persistent database (PostgreSQL)459- [ ] Vector database (ChromaDB/Pinecone)460- [ ] Advanced graph algorithms461- [ ] Conversation memory462- [ ] Export to PDF reports463- [ ] Multi-language support464- [ ] WebSocket for real-time updates465- [ ] API rate limiting466- [ ] Advanced analytics467 468## 📄 License469 470MIT License - Feel free to use for personal or commercial projects471 472## 🙏 Credits473 474- **Framework**: Flask475- **LLM**: Groq API476- **Embeddings**: Hugging Face SentenceTransformers477- **Graphs**: NetworkX478- **Visualization**: Matplotlib479- **Deployment**: Docker480 481---482 483## Quick Links484 485| Link | Purpose |486|------|---------|487| [Groq Console](https://console.groq.com) | Get API key |488| [GitHub Issues](https://github.com/yourusername/graph-rag-chatbot/issues) | Report issues |489| [Documentation](./README.md) | Full docs |490 491---492 493**Created**: June 27, 2024  494**Version**: 1.0.0  495**Status**: ✅ Production Ready496 497Made with ❤️ for Knowledge Graph RAG applications498