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
```bash
cd /path/to/project
cp .env.example .env
# Edit .env and paste your API key:
# GROQ_API_KEY=your_actual_key_here
```

### 3. Launch
```bash
docker-compose up -d
```

### 4. Access
Open browser: http://localhost:7860

✅ **Done!** Your app is running.

---

## Alternative: Local Python Setup

### 1. Create environment
```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

### 2. Install dependencies
```bash
pip install -r requirements.txt
```

### 3. Set API key
```bash
export GROQ_API_KEY="your_api_key_here"  # On Windows: set GROQ_API_KEY=...
```

### 4. Run app
```bash
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
```bash
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`:
```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"
```bash
# Linux/Mac
echo "GROQ_API_KEY=your_key" >> .env

# Windows
echo GROQ_API_KEY=your_key >> .env
```

### Port 7860 in use?
```bash
# 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?
```bash
# 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

```bash
# 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

```bash
# 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!**