README.md

metadata

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) ⭐

# 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

# 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

{
  "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

curl -X POST \
  -F "files=@document.pdf" \
  http://localhost:7860/api/upload

Response:

{
  "success": true,
  "message": "✅ 1 file(s) queued for processing",
  "successful": 1,
  "failed": 0,
  "files": ["document.pdf"]
}

POST /api/query

Query a document with RAG

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the main topic?",
    "document": "example.pdf"
  }' \
  http://localhost:7860/api/query

Response:

{
  "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

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):

chunk_size=500,        # Size of text chunks in characters
chunk_overlap=100      # Overlap between chunks for context

Embedding Model (line ~27):

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):

model="mixtral-8x7b-32768",  # Fast, powerful open model
max_tokens=500               # Response length

Similarity Threshold (line ~164):

if similarities[i] > 0.3  # Increase for stricter matching

🧪 Testing

Run the test suite to verify all features:

# 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:

# 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

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	Get API key
GitHub Issues	Report issues
Documentation	Full docs

---

Created: June 27, 2024
Version: 1.0.0
Status: ✅ Production Ready

Made with ❤️ for Knowledge Graph RAG applications