space_config.md

# Hugging Face Spaces Deployment Guide 🤗

## Quick Deployment Steps

### Step 1: Create a New Space
1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Enter Space name: `graph-rag-chatbot`
4. Select Owner: Your username
5. License: MIT (or your preference)
6. Space SDK: **Docker**
7. Visibility: Public (or Private)
8. Click "Create Space"

### Step 2: Upload Files
After creation, clone the Space:

```bash
git clone https://huggingface.co/spaces/YOUR_USERNAME/graph-rag-chatbot
cd graph-rag-chatbot

# Copy all project files into this directory
cp -r /path/to/local/project/* .

# Add and commit
git add .
git commit -m "Initial Graph RAG chatbot deployment"
git push
```

The Space will automatically build and deploy once files are pushed.

### Step 3: Configure Secrets
1. Go to your Space page → Settings
2. Scroll to "Repository secrets"
3. Add a new secret:
   - **Name**: `GROQ_API_KEY`
   - **Value**: Paste your Groq API key (from https://console.groq.com)
4. Click "Add secret"

The app will automatically use this environment variable.

## Files Structure for HF Spaces

```
your-space-repo/
├── Dockerfile              # Docker image definition
├── app.py                  # Main Flask application
├── requirements.txt        # Python dependencies
├── .dockerignore          # Files to skip
├── templates/
│   └── index.html        # Frontend
└── README.md             # Documentation
```

## What HF Spaces Does

1. **Detects Dockerfile**: Automatically reads and executes it
2. **Builds Image**: Installs all dependencies from requirements.txt
3. **Runs Container**: Starts your app on port 7860 (default HF Spaces port)
4. **Injects Secrets**: Environment variables are automatically available
5. **Public URL**: Your app is accessible at https://huggingface.co/spaces/YOUR_USERNAME/graph-rag-chatbot

## Important Notes

### Port Configuration
- HF Spaces automatically exposes port **7860**
- Our Dockerfile and app use port 7860 ✓
- No changes needed!

### Environment Variables
- HF Spaces automatically injects secrets as environment variables
- Our app reads: `os.getenv('GROQ_API_KEY')`
- This automatically works! ✓

### Storage
- `/app/data` directory persists between deployments
- Uploaded files and graphs are stored here
- **Note**: HF Spaces has ephemeral storage by default
  - Data is cleared when Space sleeps
  - Upgrade to persistent storage if needed (paid feature)

### CPU/GPU
- Free tier: 2 vCPU, 16GB RAM
- Sufficient for document processing
- Optional: Upgrade for faster embeddings

## Troubleshooting HF Spaces Deployment

### "App failed to build"
Check the build logs:
1. Go to Space page → Settings
2. Scroll to "Logs" section
3. Review Docker build output
4. Common issues:
   - Wrong Dockerfile syntax
   - Missing requirements
   - File paths incorrect

### "App is sleeping"
- Free tier spaces sleep after inactivity
- Click the Space to wake it up
- Or upgrade to a paid GPU/CPU tier

### "GROQ_API_KEY not found"
1. Verify secret is added in Space Settings
2. Restart the Space (go to Settings → Restart)
3. Wait 2-3 minutes for environment to reload

### "Port connection refused"
- Ensure Dockerfile exposes port 7860
- Check `EXPOSE 7860` is in Dockerfile ✓
- Check `PORT=7860` in environment

## Example Dockerfile for HF Spaces

Our current Dockerfile is optimized for HF Spaces:

```dockerfile
FROM python:3.11-slim
WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y gcc g++ && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY app.py .
COPY templates/ templates/

# Create data directories
RUN mkdir -p data/uploads data/graph_data

# Set environment
ENV PORT=7860
EXPOSE 7860

# Run the app
CMD ["python", "app.py"]
```

✓ Ready for HF Spaces!

## Monitoring and Logs

### View Application Logs
1. Space page → Settings → Logs
2. Shows real-time application output
3. Useful for debugging issues

### Monitor Space Health
1. Space page → Settings → Info
2. Shows CPU/RAM usage
3. Storage usage
4. Build/deployment status

## Upgrade Options

### 1. Persistent Storage
- Free tier: 50GB ephemeral
- Paid: Unlimited persistent storage
- Price: ~$5/month

### 2. GPU Support
- Free tier: 2vCPU CPU
- Paid: T4 GPU (~$6.50/day), A100 GPU (~$9/day)
- Benefit: 10-50x faster embeddings

### 3. Persistent CPU
- Free tier: Sleeps after inactivity
- Paid: Always on
- Prices vary by vCPU count

## Deployment Complete! 🎉

Your Graph RAG Chatbot is now live on Hugging Face Spaces!

**Share your Space URL**: https://huggingface.co/spaces/YOUR_USERNAME/graph-rag-chatbot

## API Rate Limits (Groq)

- Free tier: 30 requests/minute
- Contact Groq for higher limits
- Implement caching to reduce API calls

## Next Steps

1. Upload test documents (PDF, CSV, TXT)
2. Generate knowledge graphs
3. Test the chat functionality
4. Share your Space with others!
5. Customize styling/features as needed

---

**Questions?** Check the main README.md for detailed documentation.