Upload 10 files

.dockerignore

@@ -0,0 +1,12 @@
+.venv
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+build/
+dist/
+*.egg-info
+.git
+.gitignore
+.env
+tests/

.env.example

@@ -0,0 +1,15 @@
+# Example .env file for GEMINI_PROJECT
+# Copy this to a file named .env and fill in real values. DO NOT commit your .env to source control.
+
+# Gemini (Google Generative AI) API key
+GEMINI_API_KEY=your_gemini_api_key_here
+
+# GitHub personal access token with permissions to create/update repos and configure pages.
+# Minimum scopes: 'repo' (or 'public_repo' for public-only), and 'pages' if available.
+GITHUB_TOKEN=your_github_personal_access_token_here
+
+# Your GitHub username (used to construct Pages URL)
+GITHUB_USERNAME=your_github_username_here
+
+# A shared secret expected by the evaluation server (keeps endpoints secure)
+STUDENT_SECRET=your_student_secret_here

.gitignore

@@ -0,0 +1,75 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+.venv/
+venv/
+ENV/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Environment variables
+.env
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+generated_tasks/
+
+# Test files and documentation (not needed in production)
+test_*.json
+test_*.py
+test_*.ps1
+*_test.json
+chess_game_*.json
+postman_test.json
+captcha_solver_*.html
+fixed_captcha_solver.html
+run.ps1
+
+# Documentation files (optional - keep README.md only)
+ARCHITECTURE_GUIDE.md
+ASSIGNMENT_COMPLIANCE.md
+DEPLOY_CHECKLIST.md
+JSON_REQUEST_GUIDE.md
+README_HF.md
+TESTING.md
+
+# Scripts and tests directories
+scripts/
+tests/
+.github/
+*.log

Dockerfile

@@ -0,0 +1,33 @@
+FROM python:3.12-slim
+
+# Prevent Python from writing .pyc files and buffer stdout/stderr
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+# Install system deps required by some packages (git, build tools)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    build-essential \
+ && rm -rf /var/lib/apt/lists/*
+
+# Copy only requirements first to leverage Docker layer caching
+COPY requirements.txt /app/requirements.txt
+
+# Install Python dependencies
+RUN python -m pip install --upgrade pip && \
+    pip install --no-cache-dir -r /app/requirements.txt
+
+# Copy project
+COPY . /app
+
+# Create the generated_tasks directory
+RUN mkdir -p /app/generated_tasks
+
+# Expose the port Spaces will route to (use PORT env variable default 8080)
+EXPOSE 8080
+ENV PORT=8080
+
+# Start Uvicorn; allow PORT override from environment (used by Spaces)
+CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port ${PORT}"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aman Sachin Kujur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,11 +1,485 @@
 ---
-title: TDS Project
-emoji: 👁
+title: Gemini Task Automation
+emoji: 🤖
 colorFrom: blue
-colorTo: red
+colorTo: purple
 sdk: docker
+app_port: 8080
 pinned: false
-license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🤖 Gemini Task Automation System
+
+**An AI-powered task automation service that receives task descriptions, generates complete web applications using Gemini AI, and automatically deploys them to GitHub Pages.**
+
+## 🎯 What Does This Project Do?
+
+This is an **automated code generation and deployment pipeline** that:
+
+1. **Receives Task Requests** via REST API (POST /ready endpoint)
+2. **Generates Code** using Google's Gemini AI based on natural language descriptions
+3. **Creates GitHub Repositories** automatically for each task
+4. **Deploys to GitHub Pages** making the generated apps instantly accessible
+5. **Notifies Completion** by sending deployment details to a callback URL
+
+### 🔄 Complete Workflow
+
+```
+User sends task request → API validates → Gemini generates code → 
+Creates GitHub repo → Commits & pushes → Enables GitHub Pages → 
+Sends notification with live URL
+```
+
+## ✨ Key Features
+
+- **Fully Generic** - No hardcoded templates, pure AI-driven generation
+- **Background Processing** - Returns HTTP 200 immediately, processes asynchronously
+- **Round-based Updates** - Round 1 creates new repos, Round 2+ updates existing ones
+- **Attachment Support** - Can include images (logos, mockups, sample data) for AI context
+- **Robust Error Handling** - Detailed logging with specific error types
+- **JSON Schema Enforcement** - Ensures structured, parseable AI responses
+- **Exponential Backoff** - Retries for GitHub API operations
+- **Docker Ready** - Production-ready containerization
+
+## 📋 How It Works (Technical Deep Dive)
+
+### 1️⃣ Request Reception
+```json
+POST /ready
+{
+  "email": "user@example.com",
+  "secret": "auth-token",
+  "task": "chess-game",
+  "round": 1,
+  "brief": "Create a chess game with...",
+  "checks": ["Has license", "Works in browser"],
+  "evaluation_url": "https://callback.example.com",
+  "attachments": []
+}
+```
+
+### 2️⃣ AI Code Generation
+- Sends task brief + checks + attachments to **Gemini 2.5 Flash**
+- Uses **JSON schema** to enforce structured output
+- AI generates all files (HTML, CSS, JS, README, LICENSE)
+- Returns: `{"files": [{"path": "index.html", "content": "..."}]}`
+
+### 3️⃣ GitHub Repository Setup
+- **Round 1:** Creates new repository via GitHub API
+- **Round 2+:** Clones existing repo, updates files
+- Configures git with user credentials
+- Commits with descriptive messages
+
+### 4️⃣ Deployment
+- Pushes to GitHub with retry logic (5 attempts, exponential backoff)
+- Enables GitHub Pages via API
+- Waits for Pages to become active
+
+### 5️⃣ Notification
+- POSTs deployment results to `evaluation_url`:
+```json
+{
+  "email": "user@example.com",
+  "task": "chess-game",
+  "repo_url": "https://github.com/user/chess-game",
+  "pages_url": "https://user.github.io/chess-game",
+  "commit_sha": "abc123..."
+}
+```
+
+## 🚀 Deployment Options
+
+### Option 1: Docker (Recommended)
+```bash
+docker build -t gemini-automation .
+docker run -p 8080:8080 \
+  -e GEMINI_API_KEY=your_key \
+  -e GITHUB_TOKEN=your_token \
+  -e GITHUB_USERNAME=your_username \
+  -e STUDENT_SECRET=your_secret \
+  gemini-automation
+```
+
+### Option 2: Cloud Platform
+Deploy to any platform supporting Docker:
+- **Hugging Face Spaces** (includes GPU option)
+- **Google Cloud Run** (serverless, auto-scaling)
+- **AWS ECS/Fargate** (enterprise-grade)
+- **Azure Container Instances** (pay-per-use)
+- **DigitalOcean App Platform** (simple, affordable)
+
+### Option 3: Local Development
+```bash
+# 1. Clone repository
+git clone https://github.com/YOUR_USERNAME/GEMINI_TDS_PROJECT1.git
+cd GEMINI_TDS_PROJECT1
+
+# 2. Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # Linux/Mac
+# OR
+.venv\Scripts\Activate.ps1  # Windows
+
+# 3. Install dependencies
+pip install -r requirements.txt
+
+# 4. Configure environment
+cp .env.example .env
+# Edit .env with your API keys
+
+# 5. Run server
+uvicorn main:app --reload --port 8080
+```
+
+Access at: `http://localhost:8080`
+
+## 🔑 Required API Keys
+
+### 1. Google Gemini API Key
+- Go to: https://aistudio.google.com/app/apikey
+- Click "Create API Key"
+- Copy the key (starts with `AIza...`)
+- **Free tier:** 15 requests/minute, 1500 requests/day
+
+### 2. GitHub Personal Access Token
+- Go to: GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
+- Click "Generate new token (classic)"
+- Select scopes: `repo` (full control of private repositories)
+- Generate and copy token (starts with `ghp_...`)
+- **Never commit this token!**
+
+### 3. Student Secret (Custom Auth)
+- Create your own secret string (e.g., `my-secret-key-12345`)
+- Used to authenticate incoming requests
+- Can be any string you choose
+
+## ⚙️ Environment Variables
+
+Create a `.env` file in the project root:
+
+```env
+GEMINI_API_KEY=AIzaSy...your_key_here
+GITHUB_TOKEN=ghp_...your_token_here
+GITHUB_USERNAME=your_github_username
+STUDENT_SECRET=your_custom_secret_string
+```
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GEMINI_API_KEY` | ✅ Yes | Google Generative AI API key for code generation |
+| `GITHUB_TOKEN` | ✅ Yes | GitHub PAT with `repo` scope for repo operations |
+| `GITHUB_USERNAME` | ✅ Yes | Your GitHub username for repository creation |
+| `STUDENT_SECRET` | ✅ Yes | Shared secret for authenticating incoming requests |
+
+## 📊 Project Architecture
+
+```
+┌─────────────┐      ┌──────────────┐      ┌─────────────┐
+│   Client    │─────▶│  FastAPI     │─────▶│  Gemini AI  │
+│  (Postman)  │◀─────│  /ready      │◀─────│  (Code Gen) │
+└─────────────┘      └──────────────┘      └─────────────┘
+                            │
+                            ▼
+                     ┌──────────────┐
+                     │  GitPython   │
+                     │  (Local Ops) │
+                     └──────────────┘
+                            │
+                            ▼
+                     ┌──────────────┐      ┌─────────────┐
+                     │  GitHub API  │─────▶│GitHub Pages │
+                     │ (Create Repo)│      │  (Deploy)   │
+                     └──────────────┘      └─────────────┘
+                            │
+                            ▼
+                     ┌──────────────┐
+                     │ Callback URL │
+                     │ (Notify Done)│
+                     └──────────────┘
+```
+
+## 🛠️ Technology Stack
+
+| Component | Technology | Purpose |
+|-----------|-----------|---------|
+| **API Framework** | FastAPI | High-performance REST API |
+| **AI Model** | Gemini 2.5 Flash | Code generation from natural language |
+| **Validation** | Pydantic | Request/config validation |
+| **Git Operations** | GitPython | Local repo management |
+| **GitHub Integration** | GitHub REST API | Repo creation, Pages deployment |
+| **Async Tasks** | asyncio | Background task processing |
+| **HTTP Client** | httpx | Async HTTP requests |
+| **Container** | Docker | Production deployment |
+
+## 📁 Project Structure
+
+```
+GEMINI_TDS_PROJECT1/
+├── main.py              # FastAPI app + orchestration logic
+├── config.py            # Environment config with validation
+├── models.py            # Pydantic request/response models
+├── requirements.txt     # Python dependencies
+├── Dockerfile           # Production container definition
+├── .dockerignore        # Docker build exclusions
+├── .gitignore           # Git exclusions
+├── .env.example         # Template for environment variables
+├── LICENSE              # MIT license
+└── README.md            # This file
+```
+
+## 📖 API Documentation
+
+### POST /ready
+
+**Description:** Submit a task for AI-powered code generation and deployment
+
+**Request Body:**
+```json
+{
+  "email": "user@example.com",
+  "secret": "your_student_secret",
+  "task": "unique-task-id",
+  "round": 1,
+  "nonce": "unique-request-id",
+  "brief": "Detailed description of what to build...",
+  "checks": ["Requirement 1", "Requirement 2"],
+  "evaluation_url": "https://webhook.site/your-id",
+  "attachments": [
+    {
+      "name": "logo.png",
+      "url": "data:image/png;base64,iVBORw0KGgo..."
+    }
+  ]
+}
+```
+
+**Response:**
+```json
+{
+  "message": "Task received successfully!",
+  "task_id": "unique-task-id"
+}
+```
+
+**Status Codes:**
+- `200 OK` - Task accepted, processing in background
+- `403 Forbidden` - Invalid secret
+- `422 Unprocessable Entity` - Invalid request format
+
+### Callback Notification
+
+When deployment completes, the API POSTs to your `evaluation_url`:
+
+```json
+{
+  "email": "user@example.com",
+  "task": "unique-task-id",
+  "round": 1,
+  "nonce": "unique-request-id",
+  "repo_url": "https://github.com/username/unique-task-id",
+  "commit_sha": "abc123def456...",
+  "pages_url": "https://username.github.io/unique-task-id"
+}
+```
+
+## 🧪 Testing
+
+### Test with Postman / cURL
+
+**1. Get a webhook URL:**
+- Go to https://webhook.site
+- Copy your unique URL
+
+**2. Send test request:**
+
+```bash
+curl -X POST http://localhost:8080/ready \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "test@example.com",
+    "secret": "your_student_secret",
+    "task": "hello-world-test",
+    "round": 1,
+    "nonce": "test-001",
+    "brief": "Create a simple hello world webpage with a gradient background and centered text saying Hello World!",
+    "checks": ["Has index.html", "Has MIT license", "Text displays"],
+    "evaluation_url": "YOUR_WEBHOOK_URL_HERE",
+    "attachments": []
+  }'
+```
+
+**3. Check results:**
+- API returns immediately: `{"message": "Task received successfully!"}`
+- Watch webhook.site for completion notification (~30-60 seconds)
+- Visit the `pages_url` in notification to see live site
+
+### Example Tasks
+
+<details>
+<summary><b>Calculator App</b></summary>
+
+```json
+{
+  "email": "test@example.com",
+  "secret": "your_secret",
+  "task": "calculator-app",
+  "round": 1,
+  "nonce": "calc-001",
+  "brief": "Create a calculator with: 1) Basic operations (+, -, ×, ÷), 2) Clear button, 3) Decimal support, 4) Keyboard input, 5) Responsive design with Tailwind CSS",
+  "checks": [
+    "Has MIT license",
+    "README explains usage",
+    "Calculator performs addition",
+    "Calculator performs subtraction",
+    "Has clear button",
+    "Responsive design"
+  ],
+  "evaluation_url": "https://webhook.site/your-id",
+  "attachments": []
+}
+```
+</details>
+
+<details>
+<summary><b>Todo List</b></summary>
+
+```json
+{
+  "email": "test@example.com",
+  "secret": "your_secret",
+  "task": "todo-list-app",
+  "round": 1,
+  "nonce": "todo-001",
+  "brief": "Create a todo list with: 1) Add new tasks, 2) Mark tasks as complete, 3) Delete tasks, 4) LocalStorage persistence, 5) Filter by All/Active/Completed, 6) Task counter, 7) Beautiful UI with animations",
+  "checks": [
+    "Can add tasks",
+    "Can mark complete",
+    "Can delete tasks",
+    "Tasks persist on refresh",
+    "Has filter buttons",
+    "Shows task count"
+  ],
+  "evaluation_url": "https://webhook.site/your-id",
+  "attachments": []
+}
+```
+</details>
+
+<details>
+<summary><b>Chess Game (With Attachments)</b></summary>
+
+```json
+{
+  "email": "test@example.com",
+  "secret": "your_secret",
+  "task": "chess-game-pro",
+  "round": 1,
+  "nonce": "chess-001",
+  "brief": "Create a chess game with: 1) Full chess rules, 2) Drag-and-drop pieces, 3) Move validation, 4) Check/Checkmate detection, 5) Timed modes (Blitz 5min, Rapid 10min), 6) Move history, 7) Captured pieces display",
+  "checks": [
+    "All pieces move correctly",
+    "Check detection works",
+    "Checkmate ends game",
+    "Timer counts down",
+    "Move history displays"
+  ],
+  "evaluation_url": "https://webhook.site/your-id",
+  "attachments": []
+}
+```
+</details>
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**Problem:** `403 Forbidden` response
+- **Solution:** Check that `secret` in request matches `STUDENT_SECRET` env var
+
+**Problem:** Task accepted but no notification received
+- **Solution:** Check Hugging Face Space logs or local console for errors. Common causes:
+  - Invalid GitHub token or insufficient permissions
+  - Gemini API quota exceeded
+  - Invalid evaluation_url
+
+**Problem:** GitHub API errors (403, 404)
+- **Solution:** Verify GitHub token has `repo` scope:
+  ```bash
+  curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user
+  ```
+
+**Problem:** Gemini AI returns invalid JSON
+- **Solution:** Check logs for response. The system now has improved error handling with specific error messages.
+
+**Problem:** Pages deployment times out
+- **Solution:** GitHub Pages can take 1-2 minutes to activate. The system retries 5 times with exponential backoff.
+
+### Debug Mode
+
+Enable detailed logging:
+```python
+# In main.py, add at top:
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+Or set environment variable:
+```bash
+export LOG_LEVEL=DEBUG  # Linux/Mac
+$env:LOG_LEVEL="DEBUG"  # Windows PowerShell
+```
+
+### Viewing Logs
+
+**Docker:**
+```bash
+docker logs -f CONTAINER_ID
+```
+
+**Hugging Face Space:**
+Go to Space → "Logs" tab
+
+## 🔒 Security Best Practices
+
+1. **Never commit `.env` file** - Already in `.gitignore`
+2. **Rotate API keys regularly** - Every 90 days recommended
+3. **Use environment-specific secrets** - Different keys for dev/prod
+4. **Limit GitHub token scope** - Only `repo` or `public_repo` needed
+5. **Validate incoming requests** - `secret` field prevents unauthorized access
+6. **Monitor API usage** - Check Gemini and GitHub API quotas
+
+## 📈 Performance & Limits
+
+| Metric | Value | Notes |
+|--------|-------|-------|
+| Average task duration | 30-60s | Depends on complexity |
+| Gemini API rate limit | 15/min | Free tier |
+| GitHub API rate limit | 5000/hour | Authenticated |
+| Max attachment size | ~10MB | Base64 encoding adds 33% |
+| Concurrent tasks | Unlimited | Background processing |
+
+## 🤝 Contributing
+
+Contributions welcome! Areas for improvement:
+- [ ] Add support for GitLab/Bitbucket deployment
+- [ ] Implement task queue with Redis
+- [ ] Add progress tracking API
+- [ ] Support multiple AI models (Claude, GPT-4)
+- [ ] Add unit tests
+- [ ] Implement rate limiting
+- [ ] Add metrics/monitoring
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details
+
+## 🙏 Acknowledgments
+
+- **Google Gemini AI** - Code generation capabilities
+- **FastAPI** - Modern Python web framework
+- **GitHub** - Repository hosting and Pages deployment
+- **Hugging Face** - Spaces platform for easy deployment
+
+---
+
+**Built for TDS Project 1** - Automated task generation and deployment system

config.py

@@ -0,0 +1,49 @@
+# config.py
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from functools import lru_cache
+from dotenv import load_dotenv
+from typing import Optional
+from pathlib import Path
+
+# Load .env early so environment variables are available to Pydantic Settings.
+project_root = Path(__file__).resolve().parent
+load_dotenv(dotenv_path=project_root / '.env')
+
+
+# Define the structure for all required secrets/config
+class Settings(BaseSettings):
+    # API Keys/Tokens — optional at construction time; validated explicitly.
+    GEMINI_API_KEY: Optional[str] = None
+    GITHUB_TOKEN: Optional[str] = None
+
+    # Project-specific variables
+    STUDENT_SECRET: Optional[str] = None
+    GITHUB_USERNAME: Optional[str] = None
+
+    # Define which file to load settings from (keeps behavior explicit)
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    def validate_required(self) -> None:
+        """Perform explicit validation and raise a clear error if any required
+        environment variable is missing or empty.
+        """
+        missing = []
+        for name in ("GEMINI_API_KEY", "GITHUB_TOKEN", "STUDENT_SECRET", "GITHUB_USERNAME"):
+            val = getattr(self, name, None)
+            if val is None or (isinstance(val, str) and val.strip() == ""):
+                missing.append(name)
+
+        if missing:
+            raise RuntimeError(
+                "Missing required environment variables: " + ", ".join(missing) +
+                ".\nPlease create a .env file (see .env.example) or set these in your environment."
+            )
+
+
+# Use lru_cache to load the settings only once, improving performance
+@lru_cache()
+def get_settings():
+    """Returns the cached settings object and validates required vars."""
+    settings = Settings()
+    settings.validate_required()
+    return settings

main.py

@@ -0,0 +1,713 @@
+from fastapi import FastAPI, HTTPException
+from starlette.responses import JSONResponse
+from models import TaskRequest # Ensure models.py is available
+from config import get_settings
+import asyncio
+import httpx # Used for making the HTTP notification call
+import json # For parsing the structured JSON response from the LLM
+import os # For configuration and file system operations
+import base64
+import re
+import git  # For local Git operations
+import time
+import shutil
+import stat # For robust cleanup on Windows
+
+# Assuming this model is defined elsewhere
+# --- Configuration and Setup ---
+settings = get_settings()
+
+# --- Helper Function for Security ---
+def verify_secret(secret_from_request: str) -> bool:
+    """Checks if the provided secret matches the expected student secret."""
+    return secret_from_request == settings.STUDENT_SECRET
+
+# --- GITHUB CONSTANTS ---
+GITHUB_API_BASE = "https://api.github.com"
+# Pages URL is constructed dynamically using the username from settings
+GITHUB_PAGES_BASE = f"https://{settings.GITHUB_USERNAME}.github.io"
+# --------------------------
+
+# LLM Configuration
+GEMINI_API_URL = "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-preview-05-20:generateContent"
+# NOTE: API key is left empty (or read from environment) as per instructions; 
+# the execution environment is assumed to handle the required authentication.
+GEMINI_API_KEY = settings.GEMINI_API_KEY 
+# Initialize the FastAPI application
+app = FastAPI(
+    title="Automated Task Receiver & Processor",
+    description="Endpoint for receiving task assignments and triggering AI code generation/deployment."
+)
+
+# Global storage for the last received task (for demonstration purposes)
+received_task_data = {}
+
+# --- REFACTORING: SPLIT deploy_to_github ---
+
+async def setup_local_repo(local_path: str, repo_name: str, repo_url_auth: str, repo_url_http: str, round_index: int) -> git.Repo:
+    """Handles creating the remote repo (R1) or cloning the existing one (R2+) into an EMPTY directory."""
+    
+    github_username = settings.GITHUB_USERNAME
+    github_token = settings.GITHUB_TOKEN
+    
+    headers = {
+        "Authorization": f"token {github_token}",
+        "Accept": "application/vnd.github.v3+json",
+        "X-GitHub-Api-Version": "2022-11-28"
+    }
+
+    async with httpx.AsyncClient(timeout=45) as client:
+        try:
+            # 1. CREATE or INITIALIZE REPO / CLONE EXISTING REPO
+            if round_index == 1:
+                print(f"   -> R1: Creating remote repository '{repo_name}'...")
+                payload = {"name": repo_name, "private": False, "auto_init": True}
+                response = await client.post(f"{GITHUB_API_BASE}/user/repos", json=payload, headers=headers)
+                response.raise_for_status()
+
+                # Initialize local git repo in the EMPTY path
+                repo = git.Repo.init(local_path)
+                repo.create_remote('origin', repo_url_auth)
+                print("   -> R1: Local git repository initialized.")
+            
+            elif round_index >= 2:
+                # Crucial part for Round 2: Cloning the existing work into the EMPTY local_path
+                print(f"   -> R{round_index}: Cloning existing repository from {repo_url_http}...")
+                # local_path is guaranteed to be empty due to the cleanup and directory creation in the main function
+                repo = git.Repo.clone_from(repo_url_auth, local_path)
+                print(f"   -> R{round_index}: Repository cloned and ready for update.")
+            
+            return repo
+
+        except httpx.HTTPStatusError as e:
+            print(f"--- [API ERROR] GitHub API call failed with status {e.response.status_code}: {e.response.text} ---")
+            raise Exception("GitHub API call failed during repository setup.")
+        except git.GitCommandError as e:
+            print(f"--- [GIT ERROR] Failed to perform git operation: {e} ---")
+            raise Exception("Git operation failed during repository setup.")
+
+
+async def commit_and_publish(repo: git.Repo, task_id: str, round_index: int, repo_name: str) -> dict:
+    """Handles adding, committing, pushing, and configuring GitHub Pages after files are saved."""
+
+    github_username = settings.GITHUB_USERNAME
+    github_token = settings.GITHUB_TOKEN
+    
+    headers = {
+        "Authorization": f"token {github_token}",
+        "Accept": "application/vnd.github.v3+json",
+        "X-GitHub-Api-Version": "2022-11-28"
+    }
+    repo_url_http = f"https://github.com/{github_username}/{repo_name}"
+
+    async with httpx.AsyncClient(timeout=45) as client:
+        try:
+            # 1. CONFIGURE GIT USER (required for commits in Docker)
+            repo.config_writer().set_value("user", "name", "TDS AutoDeploy Bot").release()
+            repo.config_writer().set_value("user", "email", "bot@tds-project.local").release()
+            
+            # 2. ADD, COMMIT, AND PUSH FILES
+            # The new files (generated and attachments) are now in the local_path.
+            repo.git.add(A=True)
+            commit_message = f"Task {task_id} - Round {round_index}: LLM-generated app update/creation"
+            repo.index.commit(commit_message)
+            commit_sha = repo.head.object.hexsha
+            print(f"   -> Files committed. SHA: {commit_sha}")
+
+            # Ensure main branch consistency and push
+            repo.git.branch('-M', 'main')
+            print("   -> Branch renamed to 'main'.")
+            repo.git.push('--set-upstream', 'origin', 'main', force=True)
+            print("   -> Changes pushed to remote 'main' branch.")
+
+            # Wait for GitHub to register the branch
+            print("   -> Waiting 10 seconds for GitHub to register the main branch...")
+            await asyncio.sleep(10)
+
+            # 2. ENABLE GITHUB PAGES WITH ROBUST RETRIES
+            print("   -> Enabling GitHub Pages with robust retries...")
+            pages_api_url = f"{GITHUB_API_BASE}/repos/{github_username}/{repo_name}/pages"
+            pages_payload = {"source": {"branch": "main", "path": "/"}}
+            pages_max_retries = 5
+            pages_base_delay = 3
+
+            for retry_attempt in range(pages_max_retries):
+                try:
+                    pages_response = await client.get(pages_api_url, headers=headers)
+                    is_configured = (pages_response.status_code == 200)
+
+                    if is_configured:
+                        print(f"   -> Pages exists. Updating configuration (Attempt {retry_attempt + 1}).")
+                        (await client.put(pages_api_url, json=pages_payload, headers=headers)).raise_for_status()
+                    else:
+                        print(f"   -> Creating Pages configuration (Attempt {retry_attempt + 1}).")
+                        (await client.post(pages_api_url, json=pages_payload, headers=headers)).raise_for_status()
+
+                    print("   -> Pages configuration successful.")
+                    break
+                
+                except httpx.HTTPStatusError as e:
+                    if e.response.status_code == 422 and "main branch must exist" in e.response.text and retry_attempt < pages_max_retries - 1:
+                        delay = pages_base_delay * (2 ** retry_attempt)
+                        print(f"   -> [Timing Issue] Branch not recognized. Retrying in {delay} seconds...")
+                        await asyncio.sleep(delay)
+                    else:
+                        raise
+            else:
+                raise Exception("Failed to configure GitHub Pages after multiple retries due to branch existence.")
+
+            # 3. CONSTRUCT RETURN VALUES
+            print("   -> Waiting 5 seconds for GitHub Pages deployment...")
+            await asyncio.sleep(5)
+
+            pages_url = f"{GITHUB_PAGES_BASE}/{repo_name}/"
+
+            return {
+                "repo_url": repo_url_http,
+                "commit_sha": commit_sha,
+                "pages_url": pages_url
+            }
+
+        except git.GitCommandError as e:
+            print(f"--- [GIT ERROR] Failed to perform git operation: {e} ---")
+            raise Exception("Git operation failed during deployment.")
+        except httpx.HTTPStatusError as e:
+            print(f"--- [API ERROR] GitHub API call failed with status {e.response.status_code}: {e.response.text} ---")
+            raise Exception("GitHub API call failed during deployment.")
+        except Exception as e:
+            print(f"--- [CRITICAL ERROR] Deployment failed: {e} ---")
+            raise
+
+# --- REMOVED: Original deploy_to_github (replaced by setup_local_repo and commit_and_publish) ---
+# The function name deploy_to_github is now DELETED.
+
+        
+def data_uri_to_gemini_part(data_uri: str) -> dict:
+    """
+    Extracts Base64 data and MIME type from a Data URI and formats it 
+    as the 'inlineData' structure required for a Gemini API multimodal part.
+    """
+    if not data_uri or not data_uri.startswith("data:"):
+        print("ERROR: Invalid Data URI provided.")
+        return None
+
+    try:
+        # Extract MIME type and Base64 part using regex
+        match = re.search(r"data:(?P<mime_type>[^;]+);base64,(?P<base64_data>.*)", data_uri, re.IGNORECASE)
+        if not match:
+            print("ERROR: Could not parse MIME type or base64 data from URI.")
+            return None
+
+        mime_type = match.group('mime_type')
+        base64_data = match.group('base64_data')
+
+        # Check if it's a known image type to ensure we only send images to the LLM
+        if not mime_type.startswith("image/"):
+            print(f"Skipping attachment with non-image MIME type: {mime_type}")
+            return None
+        
+        return {
+            "inlineData": {
+                "data": base64_data,  # The Base64 string itself
+                "mimeType": mime_type
+            }
+        }
+    except Exception as e:
+        print(f"ERROR creating Gemini Part from URI: {e}")
+        return None
+
+def is_image_data_uri(data_uri: str) -> bool:
+    """Checks if the data URI refers to an image based on the MIME type."""
+    if not data_uri.startswith("data:"):
+        return False
+    # Check for "image/" prefix in the MIME type part of the URI
+    return re.search(r"data:image/[^;]+;base64,", data_uri, re.IGNORECASE) is not None
+# --- Helper Functions for File System Operations ---
+
+async def save_generated_files_locally(task_id: str, files: dict) -> str:
+    """
+    Saves the generated files (index.html, README.md, LICENSE) into a local 
+    directory named after the task_id within the 'generated_tasks' folder.
+    Handles both old format {filename: content} and new format {"files": [{path, content}]}
+    """
+    base_dir = "/tmp/generated_tasks"
+    task_dir = os.path.join(base_dir, task_id)
+    
+    # Ensure the task-specific directory exists
+    # NOTE: This directory is created earlier in the main orchestration function
+    os.makedirs(task_dir, exist_ok=True)
+    
+    print(f"--- [LOCAL_SAVE] Saving files to: {task_dir} ---")
+    
+    # Handle new array-based format: {"files": [{"path": "...", "content": "..."}]}
+    if "files" in files and isinstance(files["files"], list):
+        files_list = files["files"]
+        for file_obj in files_list:
+            filename = file_obj.get("path", "")
+            content = file_obj.get("content", "")
+            
+            if not filename:
+                print(f"   -> WARNING: Skipping file with no path")
+                continue
+            
+            # Handle case where content is a list instead of string
+            if isinstance(content, list):
+                print(f"   -> WARNING: Content for {filename} is a list, joining with newlines")
+                content = "\n".join(str(item) for item in content)
+            elif not isinstance(content, str):
+                print(f"   -> WARNING: Content for {filename} is {type(content)}, converting to string")
+                content = str(content)
+                
+            file_path = os.path.join(task_dir, filename)
+            try:
+                # Create subdirectories if needed (e.g., "css/style.css")
+                os.makedirs(os.path.dirname(file_path), exist_ok=True)
+                
+                # Write the content to the file
+                with open(file_path, "w", encoding="utf-8") as f:
+                    f.write(content)
+                print(f"   -> Saved: {filename} (Size: {len(content)} bytes)")
+            except Exception as e:
+                print(f"   -> ERROR saving {filename}: {e}")
+                print(f"   -> Content type: {type(content)}, First 200 chars: {str(content)[:200]}")
+                raise Exception(f"Failed to save file {filename} locally.")
+    
+    # Handle old flat format: {filename: content} (for backwards compatibility)
+    else:
+        for filename, content in files.items():
+            # Handle case where content is a list instead of string
+            if isinstance(content, list):
+                print(f"   -> WARNING: Content for {filename} is a list, joining with newlines")
+                content = "\n".join(str(item) for item in content)
+            elif not isinstance(content, str):
+                print(f"   -> WARNING: Content for {filename} is {type(content)}, converting to string")
+                content = str(content)
+                
+            file_path = os.path.join(task_dir, filename)
+            try:
+                # Write the content to the file. Assuming content is a string (text files).
+                with open(file_path, "w", encoding="utf-8") as f:
+                    f.write(content)
+                print(f"   -> Saved: {filename} (Size: {len(content)} bytes)")
+            except Exception as e:
+                print(f"   -> ERROR saving {filename}: {e}")
+                raise Exception(f"Failed to save file {filename} locally.")
+
+    return task_dir
+
+
+# --- Helper Functions for External Services ---
+
+async def call_llm_for_code(prompt: str, task_id: str, image_parts: list) -> dict:
+    """
+    Calls the Gemini API to generate the web application code and structured
+    metadata (README and LICENSE), now supporting image inputs.
+    The response is strictly validated against a JSON schema.
+    """
+    print(f"--- [LLM_CALL] Attempting to generate code for Task: {task_id} using Gemini API ---")
+    
+    # Define system instruction for the model
+    system_prompt = (
+        "You are an expert full-stack engineer and technical writer. Your task is to generate "
+        "a complete web application with three files in a structured JSON response:\n\n"
+        "Return a JSON object with a 'files' array containing:\n"
+        "1. index.html - A single, complete, fully responsive HTML file using Tailwind CSS CDN for styling, "
+        "with all JavaScript inline. Must be production-ready and implement ALL requested features.\n"
+        "2. README.md - Professional project documentation with title, description, features, usage instructions.\n"
+        "3. LICENSE - Full text of the MIT License.\n\n"
+        "Example response structure:\n"
+        "{\n"
+        '  "files": [\n'
+        '    {"path": "index.html", "content": "<!DOCTYPE html>..."},\n'
+        '    {"path": "README.md", "content": "# Project Title\\n\\n..."},\n'
+        '    {"path": "LICENSE", "content": "MIT License\\n\\nCopyright..."}\n'
+        "  ]\n"
+        "}\n\n"
+        "Make the application beautiful, functional, and complete. Use modern design principles."
+    )
+    
+    # Define the JSON response structure with proper array-based file list
+    response_schema = {
+        "type": "OBJECT",
+        "properties": {
+            "files": {
+                "type": "ARRAY",
+                "items": {
+                    "type": "OBJECT",
+                    "properties": {
+                        "path": {"type": "STRING", "description": "File name (e.g., 'index.html', 'README.md', 'LICENSE')"},
+                        "content": {"type": "STRING", "description": "Full content of the file"}
+                    },
+                    "required": ["path", "content"]
+                }
+            }
+        },
+        "required": ["files"]
+    }
+
+    # --- CONSTRUCT THE CONTENTS FIELD ---
+    contents = []
+    
+    if image_parts:
+        # Combine image parts and the text prompt.
+        all_parts = image_parts + [
+            { "text": prompt } 
+        ]
+        contents.append({ "parts": all_parts })
+    else:
+        # If no images, use the original structure with only the text prompt
+        contents.append({ "parts": [{ "text": prompt }] })
+
+    # Construct the final API payload
+    payload = {
+        "contents": contents,  
+        "systemInstruction": { "parts": [{ "text": system_prompt }] },
+        "generationConfig": {
+            "responseMimeType": "application/json",
+            "responseSchema": response_schema
+        }
+    }
+    
+    # Use exponential backoff for the API call 
+    max_retries = 5  # Increased from 3 to 5
+    base_delay = 2   # Increased from 1 to 2
+    
+    for attempt in range(max_retries):
+        try:
+            # Construct the URL with the API key
+            url = f"{GEMINI_API_URL}?key={GEMINI_API_KEY}"
+            # Increased timeout from 60s to 180s for complex tasks
+            async with httpx.AsyncClient(timeout=180.0) as client:
+                response = await client.post(
+                    url, 
+                    json=payload,
+                    headers={"Content-Type": "application/json"}
+                )
+                response.raise_for_status() # Raises an exception for 4xx/5xx status codes
+                
+                # Parse the response to get the structured JSON text
+                result = response.json()
+                
+                # Extract the generated JSON string from the result
+                json_text = result['candidates'][0]['content']['parts'][0]['text']
+                
+                # The LLM output is a JSON string, so we need to parse it into a Python dict
+                generated_files = json.loads(json_text)
+                
+                print(f"--- [LLM_CALL] Successfully generated files on attempt {attempt + 1}. ---")
+                return generated_files
+
+        except httpx.HTTPStatusError as e:
+            print(f"--- [LLM_CALL] HTTP Error on attempt {attempt + 1}: {e.response.status_code} - {e.response.text[:500]} ---")
+        except KeyError as e:
+            print(f"--- [LLM_CALL] KeyError on attempt {attempt + 1}: Missing expected key {e} in LLM response. ---")
+            print(f"--- [LLM_CALL] Full response: {result if 'result' in locals() else 'No response received'} ---")
+        except json.JSONDecodeError as e:
+            print(f"--- [LLM_CALL] JSON Decode Error on attempt {attempt + 1}: {e} ---")
+            print(f"--- [LLM_CALL] Raw LLM output that failed to parse: {json_text[:1000] if 'json_text' in locals() else 'No text extracted'} ---")
+        except httpx.RequestError as e:
+            # Catches network errors
+            print(f"--- [LLM_CALL] Network Error on attempt {attempt + 1}: {type(e).__name__}: {str(e)} ---")
+        
+        if attempt < max_retries - 1:
+            delay = base_delay * (2 ** attempt)
+            print(f"--- [LLM_CALL] Retrying LLM call in {delay} seconds... ---")
+            await asyncio.sleep(delay)
+
+    # If all retries fail, we raise an exception which is caught downstream
+    print("--- [LLM_CALL] Failed to generate code after multiple retries. ---")
+    raise Exception("LLM Code Generation Failure")
+
+
+async def notify_evaluation_server(
+    evaluation_url: str, 
+    email: str,          
+    task_id: str, 
+    round_index: int,    
+    nonce: str, 
+    repo_url: str,
+    commit_sha: str,     
+    pages_url: str       
+) -> bool:
+    """
+    Calls the evaluation_url to notify the server that the code has been deployed.
+    """
+    payload = {
+        "email": email,
+        "task": task_id,
+        "round": round_index,
+        "nonce": nonce,
+        "repo_url": repo_url,
+        "commit_sha": commit_sha,
+        "pages_url": pages_url  
+    }
+    
+    max_retries = 3
+    base_delay = 1
+    
+    print(f"--- [NOTIFICATION] Attempting to notify server at {evaluation_url} ---")
+    
+    for attempt in range(max_retries):
+        try:
+            async with httpx.AsyncClient(timeout=10) as client:
+                response = await client.post(evaluation_url, json=payload)
+                response.raise_for_status() # Raises an exception for 4xx/5xx status codes
+                
+                print(f"--- [NOTIFICATION] Successfully notified server. Response: {response.status_code} ---")
+                return True
+        except httpx.HTTPStatusError as e:
+            print(f"--- [NOTIFICATION] HTTP Error on attempt {attempt + 1}: {e}. ---")
+        except httpx.RequestError as e:
+            print(f"--- [NOTIFICATION] Request Error on attempt {attempt + 1}: {e}. ---")
+        
+        if attempt < max_retries - 1:
+            delay = base_delay * (2 ** attempt)
+            print(f"--- [NOTIFICATION] Retrying in {delay} seconds... ---")
+            await asyncio.sleep(delay)
+            
+    print(f"--- [NOTIFICATION] Failed to notify evaluation server after {max_retries} attempts. ---")
+    return False
+
+
+async def save_attachments_locally(task_dir: str, attachments: list) -> list:
+    """
+    Decodes and saves attachments (provided as Base64 Data URIs) into the task directory.
+    Returns a list of saved filenames.
+    """
+    saved_files = []
+    print(f"--- [ATTACHMENTS] Processing {len(attachments)} attachments for: {task_dir} ---")
+    
+    for attachment in attachments:
+        filename = attachment.name 
+        data_uri = attachment.url
+        
+        if not filename or not data_uri or not data_uri.startswith("data:"):
+            print(f"    -> WARNING: Skipping invalid attachment entry: {filename}")
+            continue
+
+        # Use regex to extract the Base64 part of the URI (after base64,)
+        match = re.search(r"base64,(.*)", data_uri, re.IGNORECASE)
+        if not match:
+            print(f"    -> ERROR: Could not find base64 data in URI for {filename}")
+            continue
+
+        base64_data = match.group(1)
+        file_path = os.path.join(task_dir, filename)
+
+        try:
+            # Decode the base64 string
+            file_bytes = base64.b64decode(base64_data)
+            
+            # Write the raw bytes to the file
+            with open(file_path, "wb") as f:
+                f.write(file_bytes)
+            
+            print(f"    -> Saved Attachment: {filename} (Size: {len(file_bytes)} bytes)")
+            saved_files.append(filename)
+            
+        except Exception as e:
+            print(f"    -> CRITICAL ERROR saving attachment {filename}: {e}")
+            raise Exception(f"Failed to save attachment {filename} locally.")
+
+    return saved_files
+# --- Main Orchestration Logic ---
+
+
+async def generate_files_and_deploy(task_data: TaskRequest):
+    """
+    The asynchronous background process that executes the main project workflow.
+    It adapts the LLM prompt for multi-round tasks and fixes the cloning order.
+    """
+    task_id = task_data.task
+    email = task_data.email         
+    round_index = task_data.round 
+    brief = task_data.brief
+    evaluation_url = task_data.evaluation_url
+    nonce = task_data.nonce
+    attachments = task_data.attachments
+    
+    
+    print(f"\n--- [PROCESS START] Starting background task for {task_id}, Round {round_index} ---")
+    
+    # Deployment configuration
+    repo_name = task_id.replace(' ', '-').lower()
+    github_username = settings.GITHUB_USERNAME
+    github_token = settings.GITHUB_TOKEN
+    repo_url_auth = f"https://{github_username}:{github_token}@github.com/{github_username}/{repo_name}.git"
+    repo_url_http = f"https://github.com/{github_username}/{repo_name}"
+    
+    try:
+        # 0. Setup local directory - use /tmp which is always writable
+        base_dir = "/tmp/generated_tasks"
+        local_path = os.path.join(base_dir, task_id)
+
+        # --- ROBUST CLEANUP LOGIC ---
+        # Crucial: Cleans up local directory before cloning or creating a new repo.
+        if os.path.exists(local_path):
+            print(f"--- [CLEANUP] Deleting existing local directory: {local_path} ---")
+            
+            def onerror(func, path, exc_info):
+                """Error handler for shutil.rmtree to handle permission issues."""
+                if exc_info[0] is PermissionError or 'WinError 5' in str(exc_info[1]):
+                    os.chmod(path, stat.S_IWUSR)
+                    func(path)
+                else:
+                    raise
+
+            try:
+                shutil.rmtree(local_path, onerror=onerror)
+                print("--- [CLEANUP] Directory deleted successfully. ---")
+            except Exception as e:
+                print(f"!!! CRITICAL: Failed to clean up directory. Error: {e}")
+                raise Exception(f"Failed to perform local cleanup: {e}")
+        
+        # Create the fresh, EMPTY directory (ready for clone or init)
+        os.makedirs(local_path, exist_ok=True)
+        # --- END ROBUST CLEANUP ---
+        
+        # 1. SETUP REPO (Clone or Init)
+        # MUST run before any files are saved to local_path.
+        print(f"--- [DEPLOYMENT] Setting up local Git repository for Round {round_index}... ---")
+        repo = await setup_local_repo(
+            local_path=local_path, 
+            repo_name=repo_name, 
+            repo_url_auth=repo_url_auth, 
+            repo_url_http=repo_url_http, 
+            round_index=round_index
+        ) 
+        
+        # 2. Process Attachments for LLM Input
+        image_parts = []
+        attachment_list_for_llm_prompt = []
+
+        for attachment in attachments:
+            # Check for image parts for LLM input
+            if is_image_data_uri(attachment.url):
+                gemini_part = data_uri_to_gemini_part(attachment.url)
+                if gemini_part:
+                    image_parts.append(gemini_part)
+            
+            # List all attachment names for the prompt
+            attachment_list_for_llm_prompt.append(attachment.name)
+
+        print(f"--- [LLM_INPUT] Found {len(image_parts)} image(s) to pass to LLM. ---")
+        
+        attachment_list_str = ", ".join(attachment_list_for_llm_prompt)
+        
+        # 3. AI Code Generation - Adapt Prompt for Round 2
+        
+        # --- MODIFICATION START: Adapting the LLM Prompt ---
+        if round_index > 1:
+            # For Round 2+, tell the LLM it's modifying existing work
+            llm_prompt = (
+                f"UPDATE INSTRUCTION (ROUND {round_index}): You must modify the existing project files "
+                f"(index.html, README.md, LICENSE) based on this new brief: '{brief}'. "
+                "You must replace all content in 'index.html', 'README.md', and 'LICENSE' with new, complete versions "
+                "that implement the requested modifications. The 'index.html' must remain a single, complete, "
+                "fully responsive HTML file using Tailwind CSS."
+            )
+        else:
+            # For Round 1, generate a new application
+            llm_prompt = (
+                f"Generate a complete, single-file HTML web application to achieve the following: {brief}. "
+                "Ensure your code is fully responsive, and uses Tailwind CSS. "
+                "Provide the code for the main web app, a README.md, and an MIT LICENSE."
+            )
+        
+        # Add attachment context if files were provided, regardless of round.
+        if attachment_list_str:
+             llm_prompt += f"\nAdditional context: The following files are available in the project root: {attachment_list_str}. "
+             llm_prompt += f"Ensure your code references these files correctly (if applicable)."
+        # --- MODIFICATION END ---
+        
+        # Call LLM
+        generated_files = await call_llm_for_code(llm_prompt, task_id, image_parts)
+        
+        # 4. Save Generated Code Locally
+        # This overwrites the cloned files (index.html, README.md, LICENSE)
+        await save_generated_files_locally(task_id, generated_files)
+        
+        # 5. Save Attachments Locally
+        # This adds attachments (like data.csv) to the local directory
+        # The attachment saving now happens *after* the clone/init, resolving the Round 2 error.
+        await save_attachments_locally(local_path, attachments)
+
+        # 6. COMMIT AND PUBLISH
+        print(f"--- [DEPLOYMENT] Committing and Publishing task {task_id}, Round {round_index} to GitHub... ---")
+        
+        deployment_info = await commit_and_publish(
+            repo=repo, 
+            task_id=task_id,
+            round_index=round_index,
+            repo_name=repo_name
+        )
+        
+        repo_url = deployment_info["repo_url"]
+        commit_sha = deployment_info["commit_sha"]
+        pages_url = deployment_info["pages_url"] 
+        
+        print(f"--- [DEPLOYMENT] Success! Repo: {repo_url}, Pages: {pages_url} ---")
+        
+        # 7. Notify the Evaluation Server
+        await notify_evaluation_server(
+            evaluation_url=evaluation_url, 
+            email=email,
+            task_id=task_id, 
+            round_index=round_index,
+            nonce=nonce, 
+            repo_url=repo_url,
+            commit_sha=commit_sha,
+            pages_url=pages_url
+        )
+
+    except Exception as e:
+        print(f"--- [CRITICAL FAILURE] Task {task_id} failed during processing: {e} ---")
+        
+    print(f"--- [PROCESS END] Background task for {task_id} completed. ---")
+
+
+# --- FastAPI Endpoint ---
+
+@app.post("/ready", status_code=200)
+async def receive_task(task_data: TaskRequest):
+    """
+    API endpoint that receives the task payload. 
+    It verifies the secret and starts the generation/deployment process in the background.
+    """
+    global received_task_data
+    
+    # 1. SECRET VERIFICATION (CRITICAL PROJECT REQUIREMENT)
+    if not verify_secret(task_data.secret):
+        print(f"--- FAILED SECRET VERIFICATION for task {task_data.task} ---")
+        raise HTTPException(
+            status_code=401, 
+            detail="Unauthorized: Secret does not match configured student secret."
+        )
+
+    # Store data and print initial confirmation
+    received_task_data = task_data.dict()
+    
+    print("--- TASK RECEIVED SUCCESSFULLY ---")
+    print(f"Task ID: {received_task_data['task']}, Round: {received_task_data['round']}")
+    
+    # Start the processing function in the background 
+    asyncio.create_task(generate_files_and_deploy(task_data))
+
+    # Respond immediately with 200 OK to the evaluation server
+    return JSONResponse(
+        status_code=200,
+        content={"status": "ready", "message": f"Task {task_data.task} received and processing started."}
+    )
+
+@app.get("/")
+async def root():
+    return {"message": "Task Receiver Service is running. Post to /ready to submit a task."}
+
+@app.get("/status")
+async def get_status():
+    global received_task_data
+    if received_task_data:
+        # Note: This status only shows the last received request, not the live status of the background task.
+        return {"last_received_task": received_task_data}
+    else:
+        return {"message": "Awaiting first task submission to /ready"}

models.py

@@ -0,0 +1,81 @@
+from pydantic import BaseModel, Field, EmailStr
+from typing import List
+
+# Data model for attachments (like the sample image)
+class Attachment(BaseModel):
+    name: str = Field(..., description="Name of the attached file (e.g., 'sample.png')")
+    url: str = Field(..., description="The content encoded as a data URI (data:image/png;base64,...)")
+
+# The main data model for the incoming task payload
+class TaskRequest(BaseModel):
+    # Student email ID
+    email: EmailStr = Field(..., description="Student email ID")
+    # Student-provided secret
+    secret: str = Field(..., description="Student-provided secret")
+    # A unique task ID.
+    task: str = Field(..., description="A unique task ID (e.g., 'captcha-solver-...')")
+    # There will be multiple rounds per task. This is the round index
+    round: int = Field(..., description="The round index (e.g., 1)")
+    # Pass this nonce back to the evaluation URL
+    nonce: str = Field(..., description="Pass this nonce back to the evaluation URL below")
+    # brief: mentions what the app needs to do
+    brief: str = Field(..., description="Brief description of what the app needs to do")
+    # checks: mention how it will be evaluated
+    checks: List[str] = Field(..., description="Evaluation checks (e.g., license, readme quality)")
+    # Send repo & commit details to the URL below
+    evaluation_url: str = Field(..., description="URL to send repo & commit details")
+    # Attachments will be encoded as data URIs
+    attachments: List[Attachment] = Field(..., description="Attachments encoded as data URIs")
+
+
+
+# from pydantic import BaseModel, EmailStr
+# from typing import List, Optional
+
+# # Defines the structure for an individual attachment, like a sample captcha image
+# class Attachment(BaseModel):
+#     """
+#     Represents an attachment provided in the task payload.
+#     The 'url' is expected to be a data URI (e.g., base64 encoded image).
+#     """
+#     name: str
+#     url: str
+
+# # Defines the complete structure of the JSON request body
+# class TaskRequest(BaseModel):
+#     """
+#     The main model representing the task request sent by the evaluation server.
+#     """
+#     email: EmailStr  # Enforces a valid email format
+#     secret: str
+#     task: str
+#     round: int
+#     nonce: str
+#     brief: str
+#     checks: List[str]  # A list of strings detailing the evaluation checks
+#     evaluation_url: str
+#     attachments: List[Attachment] # A list of Attachment objects
+
+#     # Configuration for Pydantic to allow validation from dicts/JSON
+#     class Config:
+#         schema_extra = {
+#             "example": {
+#                 "email": "student@example.com",
+#                 "secret": "my-secure-token",
+#                 "task": "captcha-solver-12345",
+#                 "round": 1,
+#                 "nonce": "ab12-cd34-ef56",
+#                 "brief": "Create a captcha solver that handles ?url=https://.../image.png.",
+#                 "checks": [
+#                     "Repo has MIT license",
+#                     "README.md is professional"
+#                 ],
+#                 "evaluation_url": "https://example.com/notify",
+#                 "attachments": [
+#                     {
+#                         "name": "sample.png",
+#                         "url": "data:image/png;base64,iVBORw..."
+#                     }
+#                 ]
+#             }
+#         }