# Environment Setup Guide

## Groq API Integration (FREE!)

The ALU Chatbot now supports **FREE Groq API** for handling non-ALU questions.

### Features:
- ✅ **100% FREE**: 14,400 requests/day
- ✅ **Fast**: 500+ tokens/second
- ✅ **Smart**: Uses Llama 3.1 70B model
- ✅ **Optional**: System works perfectly without it!

---

## How It Works:

1. **ALU Questions** → Uses ALU Knowledge Base (primary)
2. **Weak Matches** (score < 50) → Falls back to Groq
3. **Non-ALU Questions** → Groq handles them

---

## Setup Instructions:

### Step 1: Get FREE Groq API Key

1. Visit: https://console.groq.com/
2. Sign up (free)
3. Go to API Keys section
4. Create a new API key
5. Copy the key (starts with `gsk_...`)

### Step 2: Add to Hugging Face Secrets

1. Go to your Hugging Face Space: https://huggingface.co/spaces/Ngum/alu-student-companion
2. Click **Settings** tab
3. Scroll to **Repository secrets**
4. Click **New secret**
5. Name: `GROQ_API_KEY`
6. Value: Paste your Groq API key
7. Click **Add secret**

### Step 3: Restart Space

The space will automatically restart and load the Groq integration!

---

## Testing:

### Check if Groq is enabled:

```bash
curl https://ngum-alu-student-companion.hf.space/health
```

Look for `groq_fallback` in the response:

```json
{
  "components": {
    "groq_fallback": {
      "enabled": true,
      "model": "llama-3.1-70b-versatile",
      "free_tier": "14,400 requests/day"
    }
  }
}
```

### Test with non-ALU question:

```bash
curl -X POST https://ngum-alu-student-companion.hf.space/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "What is the capital of France?"}'
```

Should return a Groq-generated response!

---

## Local Development:

Create a `.env` file in the project root:

```bash
# .env
GROQ_API_KEY=gsk_your_key_here
CORS_ALLOWED_ORIGINS=http://localhost:3000
```

Then run:

```bash
cd backend
python main.py
```

---

## Important Notes:

- ⚠️ **Groq is OPTIONAL** - The chatbot works perfectly without it!
- ✅ **ALU questions always use ALU Knowledge Base first**
- ✅ **Groq only activates for weak matches or non-ALU questions**
- ✅ **No cost** - Completely FREE tier
- ✅ **No breaking changes** - Existing functionality preserved

---

## Troubleshooting:

### Groq not working?

1. Check API key is set correctly in Hugging Face secrets
2. Check health endpoint shows `"enabled": true`
3. Check logs for Groq initialization messages
4. Verify API key is valid at https://console.groq.com/

### System still works without Groq?

Yes! That's intentional. Groq is an enhancement, not a requirement.

---

## Questions?

The system will automatically:
- Use ALU Knowledge Base for ALU questions
- Fall back to Groq for weak matches
- Handle errors gracefully
- Continue working even if Groq fails

No manual intervention needed! 🚀