README_SPACES.md

metadata

title: LLM Code Deployment API
emoji: 🚀
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860

LLM Code Deployment - Student API

This is a Hugging Face Space that hosts the student API endpoint for the LLM Code Deployment project. It receives build requests, generates code using LLMs, and deploys to GitHub Pages.

Setup on Hugging Face Spaces

1. Create a New Space

1. Go to https://huggingface.co/new-space
2. Choose a name for your Space
3. Select Docker as the SDK
4. Click Create Space

2. Configure Environment Variables

Go to your Space's Settings → Variables and secrets tab and add:

Required:

• STUDENT_EMAIL - Your email address (matching the submission form)
• STUDENT_SECRET - Your secret key (matching the submission form)
• GITHUB_TOKEN - Your GitHub personal access token (with repo permissions)
• GITHUB_USERNAME - Your GitHub username
• AIPIPE_TOKEN - Your AIPipe token from https://aipipe.org/login

Optional (advanced):

• LLM_PROVIDER - aipipe (default), anthropic, or openai
• LLM_MODEL - Model name (default: google/gemini-2.0-flash-lite-001)
• AIPIPE_BASE_URL - AIPipe endpoint (default: https://aipipe.org/openrouter/v1)

3. 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
4. You get $2 per month free - don't exceed this

4. Deploy the Code

Option A: Clone from GitHub

git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
cd YOUR_REPO
git remote add space https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE
git push space main

Option B: Direct Upload

1. Upload all project files to your Space via the web interface
2. Ensure Dockerfile, requirements.txt, and all code files are present

5. Wait for Build

The Space will automatically build using the Dockerfile. This may take 5-10 minutes.

6. Get Your API Endpoint

Once deployed, your endpoint will be:

https://YOUR_USERNAME-YOUR_SPACE.hf.space/api/build

Use this URL when submitting to the instructor's Google Form.

Testing Your Deployment

Test your endpoint locally first:

curl -X POST https://YOUR_USERNAME-YOUR_SPACE.hf.space/api/build \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@ds.study.iitm.ac.in",
    "secret": "your-secret",
    "task": "test-task-123",
    "round": 1,
    "nonce": "test-nonce-456",
    "brief": "Create a simple Hello World page with Bootstrap",
    "checks": ["Page displays Hello World"],
    "evaluation_url": "https://example.com/evaluate",
    "attachments": []
  }'

Expected response:

{
  "status": "accepted",
  "message": "Task test-task-123-1 accepted for processing",
  "task": "test-task-123",
  "round": 1
}

Health Check

Check if your Space is running:

curl https://YOUR_USERNAME-YOUR_SPACE.hf.space/health

Monitoring

View logs in the Logs tab of your Space to monitor:

• Task requests received
• Code generation progress
• GitHub deployment status
• Evaluation notification results

Troubleshooting

Space won't start

• Check the Logs tab for build errors
• Ensure all environment variables are set correctly
• Verify Dockerfile and requirements.txt are present

Authentication errors

• Verify STUDENT_SECRET matches what you submitted in the form
• Check STUDENT_EMAIL is correct
• Ensure GITHUB_TOKEN has repo permissions

LLM generation fails

• Verify AIPIPE_TOKEN is set and valid
• Check you haven't exceeded the $2/month quota
• Review logs for specific error messages

GitHub deployment fails

• Ensure GITHUB_TOKEN has correct permissions
• Check GITHUB_USERNAME is correct
• Verify token hasn't expired

Cost Management

AIPipe Limits:

• Free tier: $2 per month for @ds.study.iitm.ac.in emails
• Models recommended:
  • google/gemini-2.0-flash-lite-001 (cheapest)
  • anthropic/claude-3-haiku (good quality)
  • openai/gpt-4.1-nano (balanced)

Monitoring usage:

• Check https://aipipe.org/usage
• Each code generation uses ~1000-2000 tokens
• Budget for ~50-100 task submissions per month

Local Development

To test locally before deploying to Spaces:

# Set environment variables
cp .env.example .env
# Edit .env with your credentials

# Run with Docker
docker build -t llm-code-deploy .
docker run -p 7860:7860 --env-file .env llm-code-deploy

# Or run directly with Python
uv run python main.py student-api

Support

For issues:

1. Check the project README.md
2. Review Hugging Face Spaces documentation
3. Contact the course instructors

License

MIT License - See LICENSE file