Aigenthix/Graph_RAG7

🤖 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. 1.The app is already running at this Space URL
2. 2.GROQAPIKEY is configured as a repository secret
3. 3.Just upload a document and start asking questions!

📚 Usage Guide

Uploading Documents

1. 1.Click the Upload Zone or drag & drop files
2. 2.Supported formats: PDF, CSV, TXT
3. 3.Maximum file size: 50MB
4. 4.Status progression:
5. 5.🟡 queued → Processing will start soon
6. 6.🟠 processing → Building graph and embeddings
7. 7.🟢 ready → Ready for queries, graph available

Viewing Knowledge Graphs

1. 1.Once document status is "ready", click "📈 View Full Graph"
2. 2.Or switch to the "Knowledge Graph" tab
3. 3.Select the document from the dropdown
4. 4.Graph shows:
5. 5.🔵 Blue nodes = Document chunks
6. 6.🟢 Green nodes = Extracted entities (keywords)
7. 7.Edges = Relationships between chunks and entities

Asking Questions

1. 1.Select a document from the dropdown
2. 2.Type your question in the chat box
3. 3.Press Enter or click Send
4. 4.Bot responds with:
5. 5.Answer based on document content
6. 6.Source chunks used
7. 7.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

📊 Performance

Processing Speed

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

• —GROQAPIKEY 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

"GROQAPIKEY 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 GROQAPIKEY 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: GROQAPIKEY (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. 1.Check the relevant documentation file above
2. 2.Review the troubleshooting section
3. 3.Check application logs: docker-compose logs -f
4. 4.Verify API key is set correctly

📝 Known Limitations

1. 1.Storage: Ephemeral (HF Spaces free tier)
2. 2.Solution: Upgrade to persistent storage

1. 1.Processing Speed: Single machine
2. 2.Solution: Use GPU tier or distributed processing

1. 1.Concurrency: Python GIL limitation
2. 2.Solution: Use Gunicorn with multiple workers

1. 1.Graph Complexity: Limited to 500 nodes for visualization
2. 2.Solution: Implement hierarchical layouts

1. 1.API Rate Limits: Groq free tier (30 req/min)
2. 2.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

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

Made with ❤️ for Knowledge Graph RAG applications