DEPLOYMENT.md

# Deployment Guide for Students

This guide will help you deploy your LLM Code Deployment API to Hugging Face Spaces so instructors can send you tasks and grade your work.

## Prerequisites

1. ✅ GitHub account with a personal access token
2. ✅ Hugging Face account (free)
3. ✅ AIPipe token from https://aipipe.org/login
4. ✅ IIT Madras email (@ds.study.iitm.ac.in) for free AIPipe access

## Step-by-Step Deployment

### Step 1: Get Your AIPipe Token

1. Visit **https://aipipe.org/login**
2. Sign in with your **@ds.study.iitm.ac.in** email
3. Copy your API token (starts with `pk_`)
4. **Important**: You get $2/month free. Don't exceed this limit!

### Step 2: Create GitHub Personal Access Token

1. Go to https://github.com/settings/tokens
2. Click **"Generate new token"** → **"Generate new token (classic)"**
3. Give it a name like "LLM Code Deployment"
4. Select scopes: ✅ **repo** (all permissions)
5. Click **"Generate token"**
6. **Copy the token immediately** (you won't see it again)

### Step 3: Create a Hugging Face Space

1. Go to **https://huggingface.co/new-space**
2. Choose a name (e.g., `llm-code-deploy-yourname`)
3. Select **Docker** as the SDK
4. Make it **Public**
5. Click **Create Space**

### Step 4: Configure Environment Variables

In your Space, go to **Settings** → **Variables and secrets**:

Add these **environment variables** (not secrets):

| Variable | Value |
|----------|-------|
| `STUDENT_EMAIL` | Your email (e.g., `yourname@ds.study.iitm.ac.in`) |
| `STUDENT_SECRET` | A secret phrase (e.g., `mySecretKey123`) |
| `GITHUB_USERNAME` | Your GitHub username |
| `LLM_PROVIDER` | `aipipe` |
| `LLM_MODEL` | `google/gemini-2.0-flash-lite-001` |

Add these as **secrets** (hidden values):

| Secret | Value |
|--------|-------|
| `GITHUB_TOKEN` | Your GitHub personal access token |
| `AIPIPE_TOKEN` | Your AIPipe token |

### Step 5: Deploy Your Code

**Option A: Push from Local Repository**

```bash
# Clone your repository
git clone https://github.com/YOUR_USERNAME/tds-p1.git
cd tds-p1

# Add Hugging Face Space as remote
git remote add space https://huggingface.co/spaces/YOUR_HF_USERNAME/YOUR_SPACE_NAME

# Push to Space
git push space main
```

**Option B: Upload Files Directly**

1. In your Space, click **Files** → **Add file**
2. Upload these files:
   - `Dockerfile`
   - `requirements.txt`
   - All `.py` files
   - `templates/` folder
   - `.gitignore`

### Step 6: Wait for Build

1. Go to the **Logs** tab
2. Wait for the build to complete (5-10 minutes)
3. Look for: `Application startup complete` in the logs

### Step 7: Test Your Deployment

Your API endpoint will be:
```
https://YOUR_HF_USERNAME-YOUR_SPACE_NAME.hf.space/api/build
```

Test it:
```bash
curl https://YOUR_HF_USERNAME-YOUR_SPACE_NAME.hf.space/health
```

Expected response:
```json
{
  "status": "healthy",
  "active_tasks": 0,
  "timestamp": "2025-01-16T10:30:00.123456"
}
```

### Step 8: Submit to Instructors

1. Go to the instructor's Google Form
2. Submit:
   - **API Endpoint**: `https://YOUR_HF_USERNAME-YOUR_SPACE_NAME.hf.space/api/build`
   - **Secret**: Same value you used in `STUDENT_SECRET`
   - **Email**: Same value you used in `STUDENT_EMAIL`

## What Happens Next?

1. **Instructors send tasks** → Your API receives a JSON request
2. **Code generation** → LLM generates a web app based on the task
3. **GitHub deployment** → New repo is created and pushed
4. **Pages deployment** → GitHub Pages is enabled
5. **Notification** → Your API notifies the evaluation endpoint
6. **Grading** → Instructors run automated checks

## Monitoring Your Deployment

### View Logs

In your Space:
- **Logs** tab shows real-time activity
- Look for task requests, code generation, and deployment status

### Check GitHub

Generated repos will appear at:
```
https://github.com/YOUR_GITHUB_USERNAME/
```

Each task creates a new repo like:
```
sum-of-sales-abc12
markdown-to-html-def34
```

### Monitor AIPipe Usage

Visit https://aipipe.org/usage to see:
- How much of your $2/month quota you've used
- Number of API calls made
- Estimated cost

## Troubleshooting

### Space won't build
**Error**: Build fails with dependency errors

**Solution**:
1. Check `Dockerfile` is present and correct
2. Verify `requirements.txt` has all dependencies
3. Review **Logs** for specific error messages

### Invalid secret error
**Error**: `401 Unauthorized: Invalid secret`

**Solution**:
1. Check `STUDENT_SECRET` matches what you submitted in the form
2. Verify `STUDENT_EMAIL` is correct
3. Test with the exact same values

### GitHub authentication fails
**Error**: `Failed to create repository`

**Solution**:
1. Verify `GITHUB_TOKEN` is set as a **secret** (not variable)
2. Ensure token has `repo` permissions
3. Check token hasn't expired (they last 1 year by default)

### LLM API errors
**Error**: `LLM generation failed: 401 Unauthorized`

**Solution**:
1. Verify `AIPIPE_TOKEN` is correct
2. Check you haven't exceeded $2/month quota
3. Try a different model: `anthropic/claude-3-haiku`

### GitHub Pages not deploying
**Error**: `Pages URL returns 404`

**Solution**:
1. Wait 60-120 seconds for Pages to activate
2. Check repo is **public** (not private)
3. Verify Pages is enabled in repo settings

## Cost Optimization

### Recommended Models (Cheapest to Most Expensive)

1. **google/gemini-2.0-flash-lite-001** ✅ Recommended
   - $0.00001/1K tokens (cheapest)
   - ~$0.02 per task
   - ~100 tasks per $2

2. **anthropic/claude-3-haiku**
   - $0.00025/1K tokens
   - ~$0.50 per task
   - ~4 tasks per $2

3. **openai/gpt-4.1-nano**
   - $0.0004/1K tokens
   - ~$0.80 per task
   - ~2.5 tasks per $2

### Tips to Reduce Costs

- ✅ Use Gemini Flash Lite (default)
- ✅ Test locally before deploying
- ✅ Monitor usage at https://aipipe.org/usage
- ❌ Don't use GPT-4 or Claude Sonnet (expensive)
- ❌ Don't test excessively (each test costs money)

## Alternative: Run Locally (No Cost)

If you prefer not to use AIPipe, run the instructor evaluation locally:

```bash
# Set up with your own Anthropic/OpenAI key
echo "LLM_PROVIDER=anthropic" >> .env
echo "ANTHROPIC_API_KEY=sk-ant-your-key" >> .env

# Run student API locally
uv run python main.py student-api

# Use ngrok to expose it publicly
ngrok http 8000
```

Then submit the ngrok URL to instructors.

## FAQ

### Can I use a different LLM provider?

Yes! Change these environment variables:

**For Anthropic Claude:**
```
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-your-key
LLM_MODEL=claude-3-5-sonnet-20241022
```

**For OpenAI:**
```
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-key
LLM_MODEL=gpt-4-turbo-preview
```

### How long does code generation take?

- Gemini Flash Lite: 2-5 seconds
- Claude Haiku: 3-7 seconds
- GPT-4: 5-15 seconds

Plus:
- GitHub deployment: 30-60 seconds
- Pages activation: 30-120 seconds
- **Total**: ~2-5 minutes per task

### Can I see the generated code before deployment?

Yes! Check the logs:
```bash
# View logs in real-time
curl https://YOUR_SPACE.hf.space/api/status/TASK_ID
```

Or check the generated repo on GitHub after deployment.

### What if I exceed the $2 limit?

1. AIPipe will block your requests
2. Use your own API key (see alternative providers above)
3. Contact instructors for assistance

### How many tasks will I receive?

Instructors may send:
- **Round 1**: 1-3 tasks
- **Round 2**: 1-3 update tasks per Round 1 task
- **Total**: 2-9 tasks

With Gemini Flash Lite (~$0.02/task), you'll use ~$0.18 total. Well within the $2 limit!

## Support

If you encounter issues:

1. **Check logs**: Space → Logs tab
2. **Review this guide**: Especially troubleshooting section
3. **Test locally**: Run the API locally to debug
4. **Ask instructors**: In the course forum or office hours

## Next Steps

After deployment:
1. ✅ Submit your endpoint to the Google Form
2. ✅ Wait for tasks from instructors
3. ✅ Monitor logs and GitHub for activity
4. ✅ Check evaluation results after deadline

Good luck! 🚀