24f3001764/llm_code_deployment-1

1# LLM Code Deployment - Usage Guide2 3## Quick Start (Windows)4 5### 1. First Time Setup6 71. **Install Python 3.10+**8   - Download from https://www.python.org/downloads/9   - Make sure to check "Add Python to PATH" during installation10 112. **Install Dependencies**12   ```bash13   pip install -r requirements.txt14   ```15 163. **Configure Environment Variables**17   - Copy `.env.example` to `.env`18   - Fill in your credentials:19     ```20     STUDENT_SECRET=your-secret-from-google-form21     OPENAI_API_KEY=sk-your-openai-key22     GITHUB_TOKEN=ghp_your-github-token23     GITHUB_USERNAME=your-github-username24     ```25 264. **Validate Setup**27   ```bash28   python validate_setup.py29   ```30 31### 2. Running the Server32 33**Option A: Using the startup script (Recommended)**34```bash35python start.py36```37Or simply double-click `start.bat`38 39**Option B: Manual start**40```bash41python -m uvicorn src.main:app --host 0.0.0.0 --port 7860 --reload42```43 44### 3. Testing the API45 46**Option A: Using the test client**47```bash48python test\test_client.py49```50Or double-click `run_tests.bat`51 52**Option B: Using curl**53```bash54curl -X POST http://localhost:7860/request \55  -H "Content-Type: application/json" \56  -d @test_request.json57```58 59**Option C: Using the API docs**60- Open http://localhost:7860/docs in your browser61- Use the interactive Swagger UI62 63## API Endpoints64 65### Health Check66```http67GET /68```69Returns API status and version.70 71**Response:**72```json73{74  "status": "running",75  "service": "LLM Code Deployment API",76  "version": "1.0.0"77}78```79 80### Submit Task (Round 1)81```http82POST /request83```84 85**Request Body:**86```json87{88  "email": "student@example.com",89  "secret": "your-secret-key",90  "task": "task-001",91  "round": 1,92  "nonce": "unique-nonce-123",93  "brief": "Create a web page that displays weather information...",94  "checks": [95    "Page displays weather data",96    "Has search functionality",97    "Responsive design"98  ],99  "evaluation_url": "https://evaluation-endpoint.com/notify",100  "attachments": []101}102```103 104**Response:**105```json106{107  "status": "accepted",108  "message": "Task task-001 round 1 accepted for processing",109  "task": "task-001",110  "round": 1111}112```113 114### Submit Revision (Round 2)115Same as Round 1, but with `"round": 2` and updated brief.116 117### Check Task Status118```http119GET /status/{task_id}120```121 122**Response:**123```json124{125  "task-001-1": {126    "status": "completed",127    "completed_at": "2025-10-11T09:30:00",128    "repo_url": "https://github.com/username/task-001",129    "pages_url": "https://username.github.io/task-001/",130    "notification_sent": true131  }132}133```134 135## Workflow136 137### Round 1: Build and Deploy138 1391. **API receives request** → Returns 200 OK immediately1402. **Background processing starts:**141   - Decodes attachments (if any)142   - Generates app using OpenAI GPT-4143   - Scans code for secrets144   - Creates GitHub repository145   - Adds LICENSE and README146   - Pushes code147   - Enables GitHub Pages148   - Waits for deployment1493. **Sends notification** to evaluation_url with:150   - repo_url151   - commit_sha152   - pages_url153 154**Timeline:** ~60-90 seconds155 156### Round 2: Revision157 1581. **API receives revision request** → Returns 200 OK immediately1592. **Background processing:**160   - Generates updated app161   - Scans for secrets162   - Updates existing repository163   - Waits for redeployment1643. **Sends notification** with updated details165 166**Timeline:** ~60-90 seconds167 168## Troubleshooting169 170### Server won't start171 172**Problem:** `Configuration error: OPENAI_API_KEY not set`173- **Solution:** Create `.env` file with your API keys (copy from `.env.example`)174 175**Problem:** `ModuleNotFoundError: No module named 'fastapi'`176- **Solution:** Install dependencies: `pip install -r requirements.txt`177 178**Problem:** `Port 7860 already in use`179- **Solution:** Change port in `.env`: `PORT=8000`180 181### GitHub deployment fails182 183**Problem:** `Bad credentials`184- **Solution:** Check your `GITHUB_TOKEN` in `.env`185- Make sure token has `repo` and `workflow` scopes186 187**Problem:** `Repository already exists`188- **Solution:** The system auto-deletes existing repos. If it fails, manually delete the repo on GitHub.189 190**Problem:** `GitHub Pages not deploying`191- **Solution:** 192  - Check repository settings → Pages193  - Ensure source is set to `main` branch, `/` root194  - Wait 2-3 minutes for initial deployment195 196### LLM generation fails197 198**Problem:** `Invalid API key`199- **Solution:** Verify your OpenAI API key starts with `sk-`200 201**Problem:** `Rate limit exceeded`202- **Solution:** Wait a few minutes or upgrade your OpenAI plan203 204**Problem:** `Generated app is too simple`205- **Solution:** The system uses a fallback template if LLM fails. Check logs for errors.206 207### Notification fails208 209**Problem:** `Connection timeout to evaluation_url`210- **Solution:** System retries with exponential backoff (1, 2, 4, 8, 16 seconds)211- Check if evaluation_url is accessible212 213## Security Features214 215### Secret Scanning216The system automatically scans generated code for:217- API keys218- Tokens219- Passwords220- Private keys221- Database URLs222 223**Patterns detected:**224- OpenAI API keys (`sk-...`)225- GitHub tokens (`ghp_...`, `gho_...`, `ghs_...`)226- AWS credentials227- Bearer tokens228- Generic API keys and secrets229 230**Action taken:**231- Logs warnings if secrets detected232- Continues deployment (with warning)233- In production, consider auto-sanitizing or blocking234 235### Best Practices2361. Never hardcode secrets in generated apps2372. Use environment variables for configuration2383. Review generated code before deployment2394. Rotate tokens if accidentally exposed240 241## Monitoring242 243### Logs244All operations are logged with timestamps:245```2462025-10-11 09:30:00 - INFO - Received request for task: task-0012472025-10-11 09:30:05 - INFO - Generated app at: generated_apps/task-0012482025-10-11 09:30:30 - INFO - Created repo: https://github.com/user/task-0012492025-10-11 09:30:45 - INFO - GitHub Pages enabled2502025-10-11 09:31:00 - INFO - Evaluation notification successful251```252 253### Status Tracking254Check task status anytime:255```bash256curl http://localhost:7860/status/task-001257```258 259## Advanced Usage260 261### Custom LLM Model262Edit `src/llm_generator.py`:263```python264model="gpt-4-turbo-preview"  # Change to gpt-4, gpt-3.5-turbo, etc.265```266 267### Custom Timeout268Edit `src/config.py`:269```python270EVALUATION_TIMEOUT = 600  # 10 minutes (default)271```272 273### Custom Retry Logic274Edit `src/config.py`:275```python276RETRY_DELAYS = [1, 2, 4, 8, 16]  # Exponential backoff delays277```278 279### Adding Attachments280Attachments should be in data URI format:281```json282{283  "attachments": [284    {285      "name": "logo.png",286      "url": "data:image/png;base64,iVBORw0KGgoAAAANS..."287    }288  ]289}290```291 292## Production Deployment293 294### Hugging Face Spaces295 2961. **Create a new Space**297   - Go to https://huggingface.co/spaces298   - Click "Create new Space"299   - Choose "Docker" SDK300 3012. **Configure Secrets**302   - Go to Space Settings → Repository Secrets303   - Add:304     - `STUDENT_SECRET`305     - `OPENAI_API_KEY`306     - `GITHUB_TOKEN`307     - `GITHUB_USERNAME`308 3093. **Push Code**310   ```bash311   git remote add hf https://huggingface.co/spaces/username/space-name312   git push hf main313   ```314 3154. **Access API**316   - Your API will be at: `https://username-space-name.hf.space`317 318### Other Platforms319 320**Railway / Render / Fly.io:**321- Set environment variables in platform settings322- Deploy using Dockerfile323- Ensure port 7860 is exposed324 325**AWS / GCP / Azure:**326- Use container services (ECS, Cloud Run, Container Apps)327- Set up environment variables328- Configure load balancer if needed329 330## Performance Tips331 3321. **Use faster LLM models** for quicker generation (e.g., gpt-3.5-turbo)3332. **Increase timeout** for complex tasks3343. **Cache common templates** to reduce LLM calls3354. **Use database** for persistent state in production3365. **Add task queue** (Celery/RQ) for better scalability337 338## Support339 340- **Documentation:** See README.md, SETUP.md, ARCHITECTURE.md341- **Issues:** Check logs in console output342- **Testing:** Use test_client.py for debugging343- **Validation:** Run validate_setup.py before starting344 345---346 347**Version:** 1.0.0  348**Last Updated:** 2025-10-11349