QUICKSTART.md

🚀 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 OpenRouter API Key

1. Go to openrouter.ai
2. Sign up / Login
3. Go to Keys → Create new key
4. Copy your API key

2️⃣ Set Up Locally

# Install dependencies
pip install -r requirements.txt

# Create environment file
cp .env.example .env

# Edit .env and add your API key
# OPENROUTER_API_KEY=your_key_here

3️⃣ Run It!

python app.py

Visit http://localhost:7860 🎉

🌐 Deploy to Hugging Face Spaces (FREE)

Option A: Fork Existing Space

1. Visit: https://huggingface.co/spaces/burtenshaw/karpathy-llm-council
2. Click "⋮" → "Duplicate this Space"
3. Settings → Repository secrets → Add OPENROUTER_API_KEY
4. Done! Your space will auto-deploy

Option B: Create New Space

1. Go to huggingface.co/new-space
2. Choose Gradio SDK 6.0.0
3. Clone and push your code:

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

4. Settings → Repository secrets → Add OPENROUTER_API_KEY

🎯 Usage Examples

Simple Question

Question: What is the capital of France?
⏱️ Response time: ~30 seconds
💰 Cost: ~$0.01

Complex Analysis

Question: Compare pros and cons of renewable energy
⏱️ Response time: ~90 seconds
💰 Cost: ~$0.07

🔧 Use Improved Models

Replace these files to use latest stable models:

# Backup originals
mv backend/config.py backend/config_old.py
mv backend/openrouter.py backend/openrouter_old.py

# Use improved versions
mv backend/config_improved.py backend/config.py
mv backend/openrouter_improved.py backend/openrouter.py

Improved models:

• DeepSeek V3 (Chat & Reasoner)
• Claude 3.7 Sonnet
• GPT-4o
• Gemini 2.0 Flash Thinking
• QwQ 32B

📊 Monitor Usage

Check your costs at: openrouter.ai/activity

Typical costs:

• Budget Council: $0.01-0.03 per query
• Balanced Council: $0.05-0.15 per query
• Premium Council: $0.20-0.50 per query

❓ Troubleshooting

"All models failed to respond"

• ✅ Check API key in .env
• ✅ Verify OpenRouter credit balance
• ✅ Test API key: https://openrouter.ai/playground

Space won't start on HF

• ✅ Check logs in Space → Logs tab
• ✅ Verify secret name is exact: OPENROUTER_API_KEY
• ✅ Ensure requirements.txt is present

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
• Original Project: https://github.com/machine-theory/lm-council

💡 Tips

1. Start with Budget Council to test without spending much
2. Use Premium Council for important questions
3. Monitor costs in OpenRouter dashboard
4. Set spending limits to avoid surprises

🎨 Customization

Edit backend/config.py to:

• Change council models
• Adjust chairman model
• Modify timeouts
• Configure retries

See DEPLOYMENT_GUIDE.md for preset configurations!

---

Need Help? Check DEPLOYMENT_GUIDE.md for comprehensive documentation.