# 🚀 Quick Start Guide - LLM Council

## 📦 What You Have

A sophisticated multi-LLM system where multiple AI models:
1. **Individually answer** your question
2. **Rank each other's** responses anonymously  
3. **Synthesize** a final best answer

## ⚡ Quick Setup (5 minutes)

### 1️⃣ Get API Keys

**OpenAI API Key** (for GPT models):
1. Go to [platform.openai.com](https://platform.openai.com/)
2. Sign up / Login
3. Go to API Keys → Create new secret key
4. Copy your API key (starts with `sk-`)

**HuggingFace API Key** (for FREE models):
1. Go to [huggingface.co](https://huggingface.co/)
2. Sign up / Login
3. Go to Settings → Access Tokens → Create new token
4. Copy your token (starts with `hf_`)

### 2️⃣ Set Up Locally

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

# Create environment file
echo OPENAI_API_KEY=your_openai_key_here > .env
echo HUGGINGFACE_API_KEY=your_hf_token_here >> .env
```

### 3️⃣ Run It!

```bash
python app.py
```

Visit `http://localhost:7860` 🎉

## 🌐 Deploy to Hugging Face Spaces (FREE)

### Step 1: Create New Space
1. Go to [huggingface.co/new-space](https://huggingface.co/new-space)
2. Choose Gradio SDK 6.0.0
3. Clone and push your code:
```bash
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE
cd YOUR_SPACE
cp -r ../llm_council/* .
git add .
git commit -m "Initial commit"
git push
```

### Step 2: Add API Keys as Secrets
1. Go to your Space → Settings → Repository secrets
2. Add first secret:
   - Name: `OPENAI_API_KEY`
   - Value: (your OpenAI API key starting with `sk-`)
3. Add second secret:
   - Name: `HUGGINGFACE_API_KEY`
   - Value: (your HuggingFace token starting with `hf_`)
4. Space will auto-restart and deploy!

## 🎯 Usage Examples

### Simple Question
```
Question: What is the capital of France?
⏱️ Response time: ~20-40 seconds
💰 Cost: ~$0.001-0.005 (90% cheaper with FREE HF models!)
```

### Complex Analysis
```
Question: Compare pros and cons of renewable energy
⏱️ Response time: ~60-120 seconds
💰 Cost: ~$0.005-0.015 (3 FREE HF models + 2 cheap OpenAI models)
```

## 🤖 Current Models

**FREE HuggingFace Models** (60% of council):
- Meta Llama 3.3 70B Instruct
- Qwen 2.5 72B Instruct
- Mistral Mixtral 8x7B Instruct

**OpenAI Models** (40% of council):
- GPT-4o-mini (very cheap)
- GPT-3.5-turbo (ultra cheap)

**Chairman**: GPT-4o-mini (final synthesis)

## 📊 Monitor Usage

**OpenAI Costs**: Check at [platform.openai.com/usage](https://platform.openai.com/usage)

**HuggingFace**: FREE! No monitoring needed

Typical costs per query:
- **Current Setup**: $0.001-0.01 (90-99% cheaper than alternatives!)
- 3 models are completely FREE (HuggingFace)
- Only pay for OpenAI models (GPT-4o-mini, GPT-3.5-turbo)

## ❓ Troubleshooting

**"401 Unauthorized" errors**
- ✅ Check both API keys in .env (locally) or Space secrets (HuggingFace)
- ✅ Verify OpenAI key starts with `sk-`
- ✅ Verify HuggingFace key starts with `hf_`
- ✅ Ensure OpenAI account has credits (check billing)

**Space won't start on HF**
- ✅ Check logs in Space → Logs tab
- ✅ Verify secret names are exact: `OPENAI_API_KEY` and `HUGGINGFACE_API_KEY`
- ✅ Ensure requirements.txt is present
- ✅ Both secrets must be added (not just one)

**Slow responses**
- ✅ Normal! 3 stages take 45-135 seconds
- ✅ Use Budget Council for faster results
- ✅ Reduce number of council members

## 📚 Full Documentation

- **Complete Guide**: See `DEPLOYMENT_GUIDE.md`
- **Code Analysis**: See `CODE_ANALYSIS.md`

## 💡 Tips

1. **Already using FREE models!** - 3 out of 5 models cost nothing
2. **Very cheap**: Only ~$0.001-0.01 per query (OpenAI portion)
3. **Monitor OpenAI usage** at platform.openai.com/usage
4. **Set OpenAI spending limits** in billing settings to avoid surprises

## 🎨 Customization

Edit `backend/config_free.py` to:
- Change council models (add more FREE HuggingFace models!)
- Adjust chairman model
- Modify timeouts
- Configure retries

**FREE HuggingFace models you can add**:
- `meta-llama/Llama-3.1-405B-Instruct` (huge!)
- `mistralai/Mistral-Nemo-Instruct-2407`
- `microsoft/Phi-3.5-MoE-instruct`

See `backend/config_free.py` for examples!

---

**Need Help?** Check `DEPLOYMENT_GUIDE.md` for comprehensive documentation.