QUICKSTART.md

Quick Start Guide ⚡

Get your Graph RAG Chatbot running in 5 minutes!

Prerequisites

• Groq API Key (free at https://console.groq.com)
• One of: Docker, Python 3.8+, or Hugging Face account

---

🚀 Fastest Way: Docker Compose (Recommended)

1. Get API Key

1. Visit https://console.groq.com
2. Sign up/Login
3. Click "API Keys" → Create new API key
4. Copy the key

2. Configure

cd /path/to/project
cp .env.example .env
# Edit .env and paste your API key:
# GROQ_API_KEY=your_actual_key_here

3. Launch

docker-compose up -d

4. Access

Open browser: http://localhost:7860

✅ Done! Your app is running.

---

Alternative: Local Python Setup

1. Create environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install dependencies

pip install -r requirements.txt

3. Set API key

export GROQ_API_KEY="your_api_key_here"  # On Windows: set GROQ_API_KEY=...

4. Run app

python app.py

5. Access

Open: http://localhost:7860

---

Alternative: Hugging Face Spaces (No local setup!)

1. Create Space

1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Select "Docker" SDK
4. Fill in details → Create

2. Upload files

git clone https://huggingface.co/spaces/YOUR_USERNAME/graph-rag-chatbot
cd graph-rag-chatbot
cp /path/to/app.py .
cp /path/to/Dockerfile .
cp /path/to/requirements.txt .
cp -r /path/to/templates .
cp /path/to/.dockerignore .
git add -A
git commit -m "Initial upload"
git push

3. Add API key

In Space Settings → Repository secrets:

• Name: GROQ_API_KEY
• Value: your_api_key

✅ Done! App deploys automatically

---

Using the Application

Upload Documents

1. Click the upload area (or drag & drop)
2. Select PDF, CSV, or TXT file
3. Watch the progress bar
4. Status changes: queued → processing → ready

View Knowledge Graph

1. Click "📈 View Full Graph" (appears when ready)
2. Or go to "Knowledge Graph" tab
3. Select document from dropdown

Chat with Your Document

1. Select document from dropdown
2. Type your question
3. Click "Send" (or press Enter)
4. Read the answer!

---

Test Files

Quick CSV Test

Create test.csv:

Name,Role,Salary
Alice,Engineer,120000
Bob,Manager,110000
Carol,Designer,100000

Upload it and try asking:

• "Who is the highest paid?"
• "How many employees?"
• "What roles are in the data?"

---

Troubleshooting

"GROQ_API_KEY not found"

# Linux/Mac
echo "GROQ_API_KEY=your_key" >> .env

# Windows
echo GROQ_API_KEY=your_key >> .env

Port 7860 in use?

# Find what's using it
lsof -i :7860  # Mac/Linux
netstat -ano | findstr :7860  # Windows

# Use different port
PORT=8000 python app.py

Docker build fails?

# Clean and rebuild
docker-compose down
docker system prune -a
docker-compose up -d

Model download slow?

The embedding model (~400MB) downloads once on first run. This is normal and can take 2-3 minutes. Subsequent runs are instant.

---

Common Commands

# View logs
docker-compose logs -f

# Stop app
docker-compose down

# Restart
docker-compose restart

# See what's running
docker-compose ps

# Check file storage
ls -la data/

---

Feature Overview

Feature	Status	Notes
PDF Upload	✅	Up to 50MB
CSV Upload	✅	Auto-detected
TXT Upload	✅	Plain text
Knowledge Graph	✅	Auto-visualized
RAG Chat	✅	Uses Groq Mixtral
Real-time Updates	✅	Every 1.5s
Mobile UI	✅	Responsive
Multi-document	✅	Process in parallel
API Access	✅	JSON endpoints

---

API Quick Reference

# Upload file
curl -F "files=@document.pdf" http://localhost:7860/api/upload

# Get documents
curl http://localhost:7860/api/documents

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

# Delete document
curl -X DELETE http://localhost:7860/api/delete/doc.pdf

---

Next Steps

1. ✅ App running locally? Perfect!
2. 📤 Upload a test document
3. 📈 View the knowledge graph
4. 💬 Try asking a question
5. 🚀 Deploy to production (HF Spaces)

---

Need Help?

1. Check README.md for detailed docs
2. See TESTING.md for test cases
3. Review space_config.md for HF deployment
4. Check logs: docker-compose logs -f

---

You're all set! 🎉 Start exploring!