Upload 37 files

.dockerignore

@@ -0,0 +1,24 @@
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.so
+*.egg
+*.egg-info
+dist
+build
+.git
+.gitignore
+.env
+.venv
+venv/
+ENV/
+*.log
+.DS_Store
+.vscode
+.idea
+*.swp
+*.swo
+*~
+

.gitignore

@@ -0,0 +1,66 @@
+# 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 environments
+venv/
+ENV/
+env/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Environment variables
+.env
+.env.local
+
+# Logs
+*.log
+logs/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Playwright
+.playwright/
+ms-playwright/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Jupyter
+.ipynb_checkpoints
+
+# Project specific
+*.pdf
+*.csv
+*.xlsx
+temp/
+tmp/
+

DEBUG_ERROR.md

@@ -0,0 +1,132 @@
+# Debugging the D1_TYPE_ERROR
+
+## Understanding the Error
+
+The error `"Internal error: D1_TYPE_ERROR: Type 'object' not supported for value '[object Object]'"` is coming from the **quiz page backend** (likely Cloudflare D1 database), not from our server.
+
+This suggests:
+1. ✅ Our server is working correctly
+2. ✅ The request is reaching the quiz page
+3. ❌ The quiz page backend is rejecting our answer format
+
+## Possible Causes
+
+### 1. Wrong URL
+You're using: `https://tds-llm-analysis.s-anand.net/demo`
+
+This is a **demo endpoint**, not a quiz page. You need to:
+- Go to the actual quiz page first
+- Get the quiz page URL
+- Use that URL in your request
+
+### 2. Answer Format Issue
+The quiz page might expect:
+- A simple string instead of a JSON object
+- A specific JSON structure
+- A different data type
+
+### 3. Quiz Page Backend Issue
+The quiz page's database (D1) might have issues with:
+- Complex nested objects
+- Certain data types
+- The way we're serializing the answer
+
+## How to Debug
+
+### Step 1: Check Server Logs
+
+When you run the server, you should see detailed logs:
+```powershell
+python -m app.main
+```
+
+Look for:
+- "Submitting answer to: ..."
+- "Payload: ..."
+- "Response status: ..."
+- "Error response: ..."
+
+### Step 2: Test with a Simple Answer
+
+Try submitting a simple string answer first:
+
+```powershell
+# Test with simple answer
+$body = @{
+    email = "24f2005753@ds.study.iitm.ac.in"
+    secret = "EasyQuiz"
+    url = "https://tds-llm-analysis.s-anand.net/demo"
+} | ConvertTo-Json
+
+# But wait - you need the actual quiz page URL, not the demo endpoint!
+```
+
+### Step 3: Verify the Quiz Page URL
+
+The URL should be:
+- A quiz page (like `https://tds-llm-analysis.s-anand.net/quiz/123`)
+- NOT the demo endpoint (`/demo`)
+
+### Step 4: Check What the Quiz Page Expects
+
+1. Open the quiz page in a browser
+2. Look at the page source
+3. Find the submit URL
+4. Check what format the answer should be in
+
+## Quick Fixes to Try
+
+### Fix 1: Use Correct URL
+```powershell
+# Get the actual quiz page URL first
+# Then use that URL, not the demo endpoint
+$body = @{
+    email = "24f2005753@ds.study.iitm.ac.in"
+    secret = "EasyQuiz"
+    url = "https://tds-llm-analysis.s-anand.net/actual-quiz-page"  # Change this!
+} | ConvertTo-Json
+```
+
+### Fix 2: Check Server Response
+The server now logs more details. Check the terminal where `python -m app.main` is running to see:
+- What payload is being sent
+- What response is received
+- Any error details
+
+### Fix 3: Test with curl for Better Error Messages
+```powershell
+curl.exe -X POST http://127.0.0.1:8000/demo `
+  -H "Content-Type: application/json" `
+  -d '{\"email\":\"24f2005753@ds.study.iitm.ac.in\",\"secret\":\"EasyQuiz\",\"url\":\"https://tds-llm-analysis.s-anand.net/demo\"}' `
+  -v
+```
+
+The `-v` flag shows verbose output including headers and response details.
+
+## What I've Fixed
+
+I've updated the code to:
+1. ✅ Better error handling in `_submit_answer`
+2. ✅ More detailed logging
+3. ✅ Better JSON serialization handling
+4. ✅ Logs the full payload and response
+
+## Next Steps
+
+1. **Check the server logs** when you make the request
+2. **Verify you're using the correct quiz page URL** (not the demo endpoint)
+3. **Look at the detailed error in the logs** to see what the quiz page is rejecting
+4. **Try with a simpler answer format** if the logs show serialization issues
+
+## Expected Behavior
+
+When working correctly:
+1. Server loads the quiz page
+2. Extracts the question
+3. Solves it
+4. Finds the submit URL
+5. Submits the answer
+6. Returns the response
+
+The error you're seeing happens at step 5 - the quiz page backend is rejecting our submission.
+

Dockerfile

@@ -0,0 +1,58 @@
+# Use Python 3.10 slim image
+FROM python:3.10-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    wget \
+    gnupg \
+    ca-certificates \
+    fonts-liberation \
+    libasound2 \
+    libatk-bridge2.0-0 \
+    libatk1.0-0 \
+    libatspi2.0-0 \
+    libcups2 \
+    libdbus-1-3 \
+    libdrm2 \
+    libgbm1 \
+    libgtk-3-0 \
+    libnspr4 \
+    libnss3 \
+    libxcomposite1 \
+    libxdamage1 \
+    libxfixes3 \
+    libxkbcommon0 \
+    libxrandr2 \
+    xdg-utils \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Install Playwright browsers
+RUN playwright install chromium
+RUN playwright install-deps chromium
+
+# Copy application code
+COPY app/ ./app/
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+ENV PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
+
+# Expose port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import requests; requests.get('http://localhost:8000/health')"
+
+# Run the application
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+

ENV_SETUP.md

@@ -0,0 +1,316 @@
+# Environment Variables Setup Guide
+
+This guide explains how to set the required environment variables for the IITM LLM Quiz Solver.
+
+## Required Variables
+
+- `QUIZ_SECRET`: Secret key for API authentication (required)
+- `OPENAI_API_KEY`: OpenAI API key for LLM features (optional)
+- `OPENROUTER_API_KEY`: OpenRouter key (e.g., GPT-5-nano) – optional fallback or alternative
+
+---
+
+## Method 1: Windows (PowerShell)
+
+### Temporary (Current Session Only)
+
+Open PowerShell and run:
+
+```powershell
+$env:QUIZ_SECRET = "EasyQuiZ"
+$env:OPENAI_API_KEY = "sk-your-openai-api-key-here"
+$env:OPENROUTER_API_KEY = "sk-or-your-openrouter-key"
+```
+
+### Permanent (System-Wide)
+
+1. **Using PowerShell (Admin):**
+```powershell
+[System.Environment]::SetEnvironmentVariable("QUIZ_SECRET", "your_secret_key_here", "User")
+[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-your-openai-api-key-here", "User")
+[System.Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "sk-or-your-openrouter-key", "User")
+```
+
+2. **Using GUI:**
+   - Press `Win + R`, type `sysdm.cpl`, press Enter
+   - Go to "Advanced" tab → Click "Environment Variables"
+   - Under "User variables", click "New"
+   - Add `QUIZ_SECRET` with your value
+   - Add `OPENAI_API_KEY` with your value
+   - Click OK to save
+
+### Using .env File (Recommended for Development)
+
+1. Create a `.env` file in the project root:
+```env
+QUIZ_SECRET=your_secret_key_here
+OPENAI_API_KEY=sk-your-openai-api-key-here
+OPENROUTER_API_KEY=sk-or-your-openrouter-key
+```
+
+2. Install python-dotenv:
+```bash
+pip install python-dotenv
+```
+
+3. Update `app/main.py` to load .env file (add at the top):
+```python
+from dotenv import load_dotenv
+load_dotenv()
+```
+
+---
+
+## Method 2: Linux/Mac (Bash)
+
+### Temporary (Current Session Only)
+
+Open terminal and run:
+
+```bash
+export QUIZ_SECRET="your_secret_key_here"
+export OPENAI_API_KEY="sk-your-openai-api-key-here"
+export OPENROUTER_API_KEY="sk-or-your-openrouter-key"
+```
+
+### Permanent (Add to Shell Profile)
+
+Add to `~/.bashrc` or `~/.zshrc`:
+
+```bash
+echo 'export QUIZ_SECRET="your_secret_key_here"' >> ~/.bashrc
+echo 'export OPENAI_API_KEY="sk-your-openai-api-key-here"' >> ~/.bashrc
+echo 'export OPENROUTER_API_KEY="sk-or-your-openrouter-key"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### Using .env File (Recommended for Development)
+
+Same as Windows method above.
+
+---
+
+## Method 3: Hugging Face Spaces
+
+### Step-by-Step Instructions
+
+1. **Go to your Space:**
+   - Navigate to https://huggingface.co/spaces
+   - Open your Space
+
+2. **Access Settings:**
+   - Click on "Settings" in the top menu
+   - Select "Variables and secrets" from the left sidebar
+
+3. **Add Variables:**
+   - Click "New variable" or "New secret"
+   - For `QUIZ_SECRET`:
+     - Key: `QUIZ_SECRET`
+     - Value: Your secret key
+     - Type: Variable (or Secret if you want it hidden)
+   - For `OPENAI_API_KEY`:
+     - Key: `OPENAI_API_KEY`
+     - Value: Your OpenAI API key (starts with `sk-`)
+     - Type: Secret (recommended for API keys)
+
+4. **Save:**
+   - Click "Save" or "Add variable"
+   - The Space will automatically rebuild with new variables
+
+### Important Notes for HF Spaces:
+- Variables are available to your Docker container
+- Secrets are hidden from logs but accessible in code
+- Changes require a rebuild (automatic)
+- `PORT` is usually set automatically by HF Spaces
+
+---
+
+## Method 4: Docker (Local)
+
+### Using docker run:
+
+```bash
+docker run -e QUIZ_SECRET="your_secret" -e OPENAI_API_KEY="sk-your-key" -p 8000:8000 your-image
+```
+
+### Using docker-compose.yml:
+
+Create `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+services:
+  app:
+    build: .
+    ports:
+      - "8000:8000"
+    environment:
+      - QUIZ_SECRET=${QUIZ_SECRET}
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+    env_file:
+      - .env  # Optional: load from .env file
+```
+
+Then run:
+```bash
+docker-compose up
+```
+
+---
+
+## Verification
+
+### Method 1: Using the Check Script (Easiest)
+
+Run the included verification script:
+
+```bash
+python check_env.py
+```
+
+This will show:
+- ✓/✗ status for each variable
+- Masked values (for security)
+- Warnings if values look incorrect
+- Next steps
+
+### Method 2: Command Line
+
+**Windows (PowerShell):**
+```powershell
+# Check if set (shows value - be careful!)
+echo $env:QUIZ_SECRET
+echo $env:OPENAI_API_KEY
+
+# Check if set (just true/false)
+if ($env:QUIZ_SECRET) { Write-Host "QUIZ_SECRET is set" } else { Write-Host "QUIZ_SECRET is NOT set" }
+```
+
+**Linux/Mac:**
+```bash
+# Check if set (shows value - be careful!)
+echo $QUIZ_SECRET
+echo $OPENAI_API_KEY
+
+# Check if set (just true/false)
+[ -n "$QUIZ_SECRET" ] && echo "QUIZ_SECRET is set" || echo "QUIZ_SECRET is NOT set"
+[ -n "$OPENAI_API_KEY" ] && echo "OPENAI_API_KEY is set" || echo "OPENAI_API_KEY is NOT set"
+```
+
+### Method 3: Python Script
+
+**Quick check:**
+```python
+import os
+print("QUIZ_SECRET:", "✓ Set" if os.getenv("QUIZ_SECRET") else "✗ Not set")
+print("OPENAI_API_KEY:", "✓ Set" if os.getenv("OPENAI_API_KEY") else "✗ Not set (optional)")
+```
+
+**Detailed check:**
+```python
+import os
+
+quiz_secret = os.getenv("QUIZ_SECRET")
+openai_key = os.getenv("OPENAI_API_KEY")
+
+if quiz_secret:
+    print(f"✓ QUIZ_SECRET: Set (length: {len(quiz_secret)})")
+else:
+    print("✗ QUIZ_SECRET: NOT SET")
+
+if openai_key:
+    print(f"✓ OPENAI_API_KEY: Set (starts with: {openai_key[:3]})")
+else:
+    print("✗ OPENAI_API_KEY: NOT SET (optional)")
+```
+
+### Method 4: Test the API
+
+Start the server and test:
+
+```bash
+# Start server
+python -m app.main
+
+# In another terminal, test health endpoint
+curl http://localhost:8000/health
+
+# Test with invalid secret (should return 403)
+curl -X POST http://localhost:8000/solve \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test@test.com","secret":"wrong","url":"https://example.com"}'
+```
+
+If you get `{"error":"forbidden"}`, the secret validation is working!
+
+---
+
+## Security Best Practices
+
+1. **Never commit secrets to Git:**
+   - Add `.env` to `.gitignore` (already included)
+   - Use environment variables or secrets management
+
+2. **Use strong secrets:**
+   - `QUIZ_SECRET`: Use a long random string (32+ characters)
+   - Generate with: `python -c "import secrets; print(secrets.token_urlsafe(32))"`
+
+3. **Rotate keys regularly:**
+   - Change `QUIZ_SECRET` periodically
+   - Regenerate OpenAI API keys if compromised
+
+4. **For production:**
+   - Use secret management services (AWS Secrets Manager, Azure Key Vault, etc.)
+   - Never hardcode secrets in code
+   - Use different secrets for dev/staging/production
+
+---
+
+## Quick Start Script
+
+Create `setup_env.sh` (Linux/Mac) or `setup_env.ps1` (Windows):
+
+**setup_env.sh:**
+```bash
+#!/bin/bash
+export QUIZ_SECRET="your_secret_key_here"
+export OPENAI_API_KEY="sk-your-openai-api-key-here"
+python -m app.main
+```
+
+**setup_env.ps1:**
+```powershell
+$env:QUIZ_SECRET = "your_secret_key_here"
+$env:OPENAI_API_KEY = "sk-your-openai-api-key-here"
+python -m app.main
+```
+
+---
+
+## Troubleshooting
+
+### Variable not found?
+- Restart your terminal/IDE after setting variables
+- Check spelling (case-sensitive)
+- Verify with `echo $VARIABLE_NAME` or `echo $env:VARIABLE_NAME`
+
+### HF Spaces not picking up variables?
+- Ensure variables are saved in Settings
+- Check Space logs for errors
+- Rebuild the Space manually if needed
+
+### Docker not using variables?
+- Check `docker-compose.yml` syntax
+- Use `docker run -e` for single container
+- Verify with `docker exec container env`
+
+---
+
+## Need Help?
+
+If you encounter issues:
+1. Check the application logs
+2. Verify variable names match exactly
+3. Ensure no extra spaces in values
+4. Test with a simple `print(os.getenv("VAR"))` in Python
+

EXPLAIN_OUTPUT.md

@@ -0,0 +1,119 @@
+# Understanding the PowerShell Setup Output
+
+## What Happened (Lines 26-41)
+
+Let me break down what you saw:
+
+### Line 26-28: QUIZ_SECRET Setup
+```
+QUIZ_SECRET is not set
+Enter your QUIZ_SECRET (or press Enter to generate one): EasyQuiz
+QUIZ_SECRET set for this session
+```
+
+**What this means:**
+- ✅ The script detected `QUIZ_SECRET` wasn't set
+- ✅ You entered `EasyQuiz` as your secret
+- ✅ The variable is now set **for this PowerShell session only**
+
+### Line 29: OPENAI_API_KEY
+```
+OPENAI_API_KEY is already set
+```
+
+**What this means:**
+- ✅ Your OpenAI API key was already configured (probably from a previous session or system-wide)
+
+### Line 31: Success Message
+```
+Environment variables configured!
+```
+
+**What this means:**
+- ✅ Both variables are now available in your current PowerShell window
+
+### Lines 33-35: Permanent Setup Commands
+```
+To make these permanent, run:
+[System.Environment]::SetEnvironmentVariable("QUIZ_SECRET", " + EasyQuiz + ", "User")
+[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", " + sk-proj-... + ", "User")
+```
+
+**⚠️ IMPORTANT:** There's a display bug here - the output shows string concatenation instead of the actual command. The correct commands should be:
+
+```powershell
+[System.Environment]::SetEnvironmentVariable("QUIZ_SECRET", "EasyQuiz", "User")
+[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "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", "User")
+```
+
+## What "Set for this session" Means
+
+**Current Status:**
+- ✅ Variables are set **only in this PowerShell window**
+- ✅ You can run `python -m app.main` right now and it will work
+- ❌ If you close this window, the variables will be lost
+- ❌ If you open a new PowerShell window, variables won't be there
+
+## What You Should Do
+
+### Option 1: Use It Now (Temporary - Current Session Only)
+
+Just run the server in the **same PowerShell window**:
+```powershell
+python -m app.main
+```
+
+This will work until you close the window.
+
+### Option 2: Make It Permanent (Recommended)
+
+Run these commands to make variables permanent:
+
+```powershell
+[System.Environment]::SetEnvironmentVariable("QUIZ_SECRET", "EasyQuiz", "User")
+[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "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", "User")
+```
+
+**After running these:**
+- ✅ Variables will be available in ALL new PowerShell windows
+- ✅ You need to close and reopen PowerShell for changes to take effect
+- ✅ Variables persist even after restarting your computer
+
+### Option 3: Verify It's Working
+
+Run the check script:
+```powershell
+python check_env.py
+```
+
+You should see:
+```
+✓ QUIZ_SECRET: Set (Easy...Quiz)
+✓ OPENAI_API_KEY: Set (sk-...4UA)
+✓ Status: Ready to run
+```
+
+## Quick Summary
+
+| Status | Meaning | Action Needed |
+|--------|---------|---------------|
+| ✅ "set for this session" | Works in current window only | Run server now, or make permanent |
+| ✅ "already set" | Variable exists | Nothing needed |
+| ⚠️ Lines 33-35 | Display bug (shows wrong format) | Use corrected commands above |
+
+## Next Steps
+
+1. **Test it now** (in the same window):
+   ```powershell
+   python check_env.py
+   python -m app.main
+   ```
+
+2. **Make it permanent** (optional but recommended):
+   ```powershell
+   [System.Environment]::SetEnvironmentVariable("QUIZ_SECRET", "EasyQuiz", "User")
+   [System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "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", "User")
+   ```
+
+3. **Close and reopen PowerShell** (if you made it permanent)
+

FIX_SERVER.md

@@ -0,0 +1,89 @@
+# Fix: Server "Not Found" Error
+
+## The Problem
+
+You have a server running on port 8000, but it's **NOT our FastAPI app**. It's returning "Not Found" for all endpoints.
+
+## Solution: Stop and Restart
+
+### Step 1: Stop the Wrong Server
+
+Run this to stop whatever is on port 8000:
+
+```powershell
+# Find and stop process on port 8000
+$portInfo = netstat -ano | findstr :8000 | findstr LISTENING
+if ($portInfo) {
+    $pid = ($portInfo -split '\s+')[-1]
+    Stop-Process -Id $pid -Force
+    Write-Host "Stopped process $pid"
+    Start-Sleep -Seconds 2
+}
+```
+
+### Step 2: Start the Correct Server
+
+In a **NEW PowerShell terminal**, run:
+
+```powershell
+# Navigate to project
+cd C:\Users\tarun\IITMTdsPrj2
+
+# Set environment variables
+$env:QUIZ_SECRET = "EasyQuiz"
+$env:OPENAI_API_KEY = "eyJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6IjI0ZjIwMDU3NTNAZHMuc3R1ZHkuaWl0bS5hYy5pbiJ9.eji7L5I62M9YHoeEKE8ao6eTw8dFjgDIMP9C3lOUXc4"
+
+# Start the server
+python -m app.main
+```
+
+You should see:
+```
+INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
+```
+
+**Keep this terminal open!**
+
+### Step 3: Test in Another Terminal
+
+Open a **NEW PowerShell window** and test:
+
+```powershell
+# Test health endpoint
+Invoke-RestMethod -Uri "http://127.0.0.1:8000/health"
+
+# Test demo endpoint
+$body = @{
+    email = "24f2005753@ds.study.iitm.ac.in"
+    secret = "EasyQuiz"
+    url = "https://tds-llm-analysis.s-anand.net/demo"
+} | ConvertTo-Json
+
+Invoke-RestMethod -Uri "http://127.0.0.1:8000/demo" -Method POST -ContentType "application/json" -Body $body
+```
+
+## Quick One-Liner to Stop Server
+
+```powershell
+Get-NetTCPConnection -LocalPort 8000 -ErrorAction SilentlyContinue | Select-Object -ExpandProperty OwningProcess | ForEach-Object { Stop-Process -Id $_ -Force }; Write-Host "Stopped all processes on port 8000"
+```
+
+## Verify Server is Running
+
+After starting, test:
+
+```powershell
+# Should return: {"status":"healthy"}
+Invoke-RestMethod -Uri "http://127.0.0.1:8000/health"
+```
+
+If you get "Not Found", the wrong server is still running.
+
+## Summary
+
+1. ✅ Stop whatever is on port 8000
+2. ✅ Start our FastAPI server: `python -m app.main`
+3. ✅ Test endpoints in a new terminal
+4. ✅ Keep server terminal open while testing
+
+

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 IITM LLM Quiz Solver
+
+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.
+

QUICK_CHECK.md

@@ -0,0 +1,131 @@
+# Quick Check Guide - PowerShell
+
+## Issue: "Not Found" Error
+
+The error `{"detail":"Not Found"}` means:
+- ❌ Server is not running, OR
+- ❌ Server needs to be restarted to see the new `/env-check` endpoint
+
+## Issue: QUIZ_SECRET Not Set
+
+The test shows `QUIZ_SECRET` is `false` because:
+- ❌ Environment variable was only set in a previous PowerShell session
+- ❌ You need to set it again in the current session
+
+## Solution: Step-by-Step
+
+### Step 1: Set Environment Variables (Current Session)
+
+```powershell
+$env:QUIZ_SECRET = "EasyQuiz"
+$env:OPENAI_API_KEY = "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"
+```
+
+### Step 2: Verify Variables Are Set
+
+```powershell
+python test_env.json.py
+```
+
+**Expected Output:**
+```json
+{
+  "status": "ok",
+  "variables": {
+    "QUIZ_SECRET": {
+      "set": true,
+      "length": 8,
+      "preview": "Easy...Quiz"
+    },
+    ...
+  },
+  "ready": true
+}
+```
+
+### Step 3: Start the Server
+
+```powershell
+python -m app.main
+```
+
+Wait for: `Uvicorn running on http://0.0.0.0:8000`
+
+### Step 4: Test the API (In a NEW PowerShell Window)
+
+**Important:** Open a NEW PowerShell window (keep server running in the first one)
+
+```powershell
+# Set variables again in the new window
+$env:QUIZ_SECRET = "EasyQuiz"
+
+# Test the endpoint
+Invoke-RestMethod -Uri http://localhost:8000/env-check | ConvertTo-Json
+```
+
+**Or use curl (PowerShell alias):**
+```powershell
+curl http://localhost:8000/env-check
+```
+
+## Alternative: Use the Test Script (No Server Needed)
+
+Instead of starting the server, just run:
+
+```powershell
+# Set variables
+$env:QUIZ_SECRET = "EasyQuiz"
+
+# Check (no server needed)
+python test_env.json.py
+```
+
+This gives you JSON output without needing the server running.
+
+## Make Variables Permanent (Recommended)
+
+To avoid setting variables every time:
+
+```powershell
+[System.Environment]::SetEnvironmentVariable("QUIZ_SECRET", "EasyQuiz", "User")
+[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "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", "User")
+```
+
+Then **close and reopen PowerShell** for changes to take effect.
+
+## Quick Test Commands
+
+### All-in-One Test (No Server)
+```powershell
+$env:QUIZ_SECRET = "EasyQuiz"
+python test_env.json.py
+```
+
+### Test with Server Running
+```powershell
+# Terminal 1: Start server
+$env:QUIZ_SECRET = "EasyQuiz"
+python -m app.main
+
+# Terminal 2: Test API
+$env:QUIZ_SECRET = "EasyQuiz"
+Invoke-RestMethod -Uri http://localhost:8000/env-check | ConvertTo-Json
+```
+
+## Troubleshooting
+
+### "Not Found" Error
+- ✅ Make sure server is running
+- ✅ Restart server after code changes
+- ✅ Check URL is correct: `http://localhost:8000/env-check`
+
+### "QUIZ_SECRET is required"
+- ✅ Set variable: `$env:QUIZ_SECRET = "EasyQuiz"`
+- ✅ Verify: `python test_env.json.py`
+- ✅ Make permanent to avoid setting every time
+
+### Server Won't Start
+- ✅ Check if port 8000 is available
+- ✅ Install dependencies: `pip install -r requirements.txt`
+- ✅ Check for errors in the terminal
+

QUICK_START.md

@@ -0,0 +1,110 @@
+# Quick Start Guide
+
+## 1. Install Dependencies
+
+```bash
+pip install -r requirements.txt
+playwright install chromium
+```
+
+## 2. Set Environment Variables
+
+### Option A: Use Setup Scripts (Recommended)
+
+**Windows:**
+```powershell
+.\setup_env.ps1
+```
+
+**Linux/Mac:**
+```bash
+source setup_env.sh
+```
+
+### Option B: Manual Setup
+
+**Windows PowerShell:**
+```powershell
+$env:QUIZ_SECRET = "your_secret_here"
+$env:OPENAI_API_KEY = "sk-your-key-here"  # Optional
+```
+
+**Linux/Mac:**
+```bash
+export QUIZ_SECRET="your_secret_here"
+export OPENAI_API_KEY="sk-your-key-here"  # Optional
+```
+
+### Option C: Use .env File
+
+Create `.env` file:
+```env
+QUIZ_SECRET=your_secret_here
+OPENAI_API_KEY=sk-your-key-here
+```
+
+## 3. Verify Setup
+
+```bash
+python check_env.py
+```
+
+You should see:
+```
+✓ QUIZ_SECRET: Set (xxxx...xxxx)
+✓ OPENAI_API_KEY: Set (sk-...xxxx)  [if set]
+✓ Status: Ready to run
+```
+
+## 4. Start the Server
+
+```bash
+python -m app.main
+```
+
+Or:
+```bash
+uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+## 5. Test the API
+
+**Health Check:**
+```bash
+curl http://localhost:8000/health
+```
+
+**Test Quiz Solving:**
+```bash
+curl -X POST http://localhost:8000/demo \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "test@example.com",
+    "secret": "your_secret_here",
+    "url": "https://example.com/quiz"
+  }'
+```
+
+## Troubleshooting
+
+### "QUIZ_SECRET is NOT SET"
+- Run the setup script again
+- Or manually set: `export QUIZ_SECRET="your_secret"` (Linux/Mac)
+- Or: `$env:QUIZ_SECRET = "your_secret"` (Windows)
+
+### "Module not found"
+- Run: `pip install -r requirements.txt`
+
+### "Playwright browser not found"
+- Run: `playwright install chromium`
+
+### Server won't start
+- Check if port 8000 is available
+- Change port: `export PORT=8001` then restart
+
+## Next Steps
+
+- See [ENV_SETUP.md](ENV_SETUP.md) for detailed environment setup
+- See [README.md](README.md) for full documentation
+- Deploy to Hugging Face Spaces (see README.md)
+

README.md

@@ -1,11 +1,265 @@
----
-title: Prj2
-emoji: 😻
-colorFrom: pink
-colorTo: purple
-sdk: docker
-pinned: false
-license: mit
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# IITM LLM Quiz Solver
+
+A complete Python project with FastAPI that acts as an API endpoint to automatically solve dynamic quiz tasks using a headless browser and optional LLM reasoning.
+
+## Features
+
+- 🚀 FastAPI-based REST API
+- 🌐 Playwright for headless browser automation
+- 🤖 OpenAI GPT integration for complex reasoning
+- 📊 Data processing (CSV, JSON, PDF, etc.)
+- 🔄 Recursive quiz solving
+- ⚡ Async/await for performance
+- 🐳 Docker support for easy deployment
+
+## Project Structure
+
+```
+/app
+  - main.py              # FastAPI server
+  - solver.py            # Quiz solving logic
+  - browser.py           # Playwright helper
+  - llm.py               # GPT helper
+  - utils.py             # Utility functions
+/Dockerfile
+/requirements.txt
+/README.md
+/LICENSE
+```
+
+## Installation
+
+### Local Development
+
+1. Clone the repository:
+```bash
+git clone <repository-url>
+cd IITMTdsPrj2
+```
+
+2. Install Python dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+3. Install Playwright browsers:
+```bash
+playwright install chromium
+```
+
+4. Set environment variables:
+
+   **Quick Setup (Windows PowerShell):**
+   ```powershell
+   .\setup_env.ps1
+   ```
+
+   **Quick Setup (Linux/Mac):**
+   ```bash
+   source setup_env.sh
+   ```
+
+   **Manual Setup (choose whichever LLM provider you prefer):**
+   ```bash
+   # Windows PowerShell
+   $env:QUIZ_SECRET = "your_secret_key"
+   $env:OPENAI_API_KEY = "sk-your-openai-api-key"      # Optional - OpenAI
+   $env:OPENROUTER_API_KEY = "sk-or-your-openrouter"   # Optional - OpenRouter GPT-5-nano
+   
+   # Linux/Mac
+   export QUIZ_SECRET="your_secret_key"
+   export OPENAI_API_KEY="sk-your-openai-api-key"        # Optional
+   export OPENROUTER_API_KEY="sk-or-your-openrouter"     # Optional
+   ```
+
+   **Or use .env file:**
+   - Copy `.env.example` to `.env` (if available)
+   - Fill in your values
+   - The app will automatically load it
+
+   📖 **See [ENV_SETUP.md](ENV_SETUP.md) for detailed instructions**
+
+5. Run the server:
+```bash
+python -m app.main
+# or
+uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+## API Endpoints
+
+### POST /solve
+
+Main endpoint to solve a quiz.
+
+**Request Body:**
+```json
+{
+  "email": "user@example.com",
+  "secret": "your_secret",
+  "url": "https://example.com/quiz"
+}
+```
+
+**Response:**
+- `200 OK`: Quiz solved successfully
+- `400 Bad Request`: Invalid request format
+- `403 Forbidden`: Invalid secret
+- `500 Internal Server Error`: Server error
+- `504 Gateway Timeout`: Request timeout (>3 minutes)
+
+### POST /demo
+
+Demo endpoint for testing (same as `/solve` but with more lenient error handling).
+
+**Request Body:** Same as `/solve`
+
+### GET /health
+
+Health check endpoint.
+
+**Response:**
+```json
+{
+  "status": "healthy"
+}
+```
+
+## Deployment on Hugging Face Spaces
+
+### Method 1: Using Dockerfile (Recommended)
+
+1. **Create a new Space on Hugging Face:**
+   - Go to https://huggingface.co/spaces
+   - Create a new Space
+   - Select "Docker" as the SDK
+
+2. **Upload your files:**
+   - Upload all project files to your Space
+   - Ensure `Dockerfile` is in the root directory
+
+3. **Set Environment Variables:**
+   - Go to Space Settings → Variables and secrets
+   - Add the following:
+     - `QUIZ_SECRET`: Your secret key for authentication
+     - `OPENAI_API_KEY`: Your OpenAI API key (optional)
+     - `OPENROUTER_API_KEY`: Your OpenRouter key (e.g., GPT-5-nano)
+     - `PORT`: 8000 (usually set automatically)
+
+4. **Deploy:**
+   - Hugging Face will automatically build and deploy your Docker container
+   - The API will be available at: `https://<your-username>-<space-name>.hf.space`
+
+### Method 2: Using Docker Compose (Alternative)
+
+If you need more control, you can use `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+services:
+  app:
+    build: .
+    ports:
+      - "8000:8000"
+    environment:
+      - QUIZ_SECRET=${QUIZ_SECRET}
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+```
+
+## Environment Variables
+
+| Variable | Description | Required | Default |
+|----------|-------------|----------|---------|
+| `QUIZ_SECRET` | Secret key for API authentication | Yes | `default_secret_change_me` |
+| `OPENAI_API_KEY` | OpenAI API key for LLM features | No | - |
+| `OPENROUTER_API_KEY` | OpenRouter key (e.g., GPT-5-nano) | No | - |
+| `OPENROUTER_MODEL` | Override OpenRouter model (default gpt-5-nano) | No | `gpt-5-nano` |
+| `PORT` | Server port | No | `8000` |
+
+## Testing
+
+### Test with curl:
+
+```bash
+curl -X POST "https://tds-llm-analysis.s-anand.net/demo" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "test@example.com",
+    "secret": "your_secret",
+    "url": "https://example.com/quiz"
+  }'
+```
+
+### Test with Python:
+
+```python
+import requests
+
+response = requests.post(
+    "https://tds-llm-analysis.s-anand.net/demo",
+    json={
+        "email": "test@example.com",
+        "secret": "your_secret",
+        "url": "https://example.com/quiz"
+    }
+)
+
+print(response.json())
+```
+
+## How It Works
+
+1. **Request Validation**: Validates email, secret, and URL format
+2. **Secret Authentication**: Checks secret against expected value (403 if wrong)
+3. **Page Loading**: Uses Playwright to load and render the quiz page
+4. **Content Extraction**: Extracts all text, HTML, links, and images
+5. **Submit URL Detection**: Automatically finds the submit URL from page content
+6. **Question Solving**: 
+   - Extracts question text
+   - Tries multiple strategies:
+     - Check if answer is in page
+     - Download and process data files (CSV, JSON, PDF)
+     - Use LLM for complex reasoning
+7. **Answer Submission**: Submits answer to detected submit URL
+8. **Recursive Solving**: If response contains next URL, solves recursively
+9. **Response**: Returns final result
+
+## Solver Strategies
+
+The solver uses multiple strategies in order:
+
+1. **Direct Answer Extraction**: Checks if answer is already in page
+2. **Data File Processing**: Downloads and processes CSV, JSON, PDF files
+3. **LLM Reasoning**: Uses GPT-4o-mini (OpenAI) or GPT-5-nano (OpenRouter) for complex questions
+4. **Fallback**: Returns question analysis if all else fails
+
+## Error Handling
+
+- Invalid JSON → 400 Bad Request
+- Wrong secret → 403 Forbidden
+- Page load errors → 500 with error details
+- Timeout (>3 min) → 504 Gateway Timeout
+- All errors are logged for debugging
+
+## Limitations
+
+- Maximum recursion depth: 10 quizzes
+- Timeout: 3 minutes per request
+- Requires internet connection for external URLs
+- OpenAI API key needed for LLM features (optional)
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+## Support
+
+For issues and questions, please open an issue on the repository.
+

SET_API_KEY.md

@@ -0,0 +1,66 @@
+# Setting LLM API Keys
+
+You can use either OpenAI or OpenRouter (or both) for LLM reasoning. Set whichever keys you have.
+
+## Option A: OpenRouter (GPT-5-nano, etc.)
+
+### Quick Setup (Current Session)
+```powershell
+$env:OPENROUTER_API_KEY = "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"
+$env:OPENROUTER_MODEL = "gpt-5-nano"   # optional override
+```
+
+### Make It Permanent
+```powershell
+[System.Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "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", "User")
+[System.Environment]::SetEnvironmentVariable("OPENROUTER_MODEL", "gpt-5-nano", "User")
+```
+
+### .env Example
+```env
+OPENROUTER_API_KEY=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
+OPENROUTER_MODEL=gpt-5-nano
+```
+
+### Hugging Face Spaces
+- `OPENROUTER_API_KEY`: `sk-or-...`
+- `OPENROUTER_MODEL`: `gpt-5-nano` (optional, defaults to this)
+
+---
+
+## Option B: OpenAI (GPT-4o, etc.)
+
+### Quick Setup
+```powershell
+$env:OPENAI_API_KEY = "sk-your-openai-api-key"
+```
+
+Or run:
+```powershell
+.\set_api_key.ps1
+```
+
+### Make It Permanent
+```powershell
+[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-your-openai-api-key", "User")
+```
+
+### .env Example
+```env
+OPENAI_API_KEY=sk-your-openai-api-key
+```
+
+### Hugging Face Spaces
+- `OPENAI_API_KEY`: `sk-...`
+
+---
+
+## Verification
+
+Run:
+```powershell
+python test_env.json.py
+```
+
+You should see at least one of the LLM keys marked as `set`, and `llm_enabled: true`.
+

START_SERVER.md

@@ -0,0 +1,90 @@
+# How to Start the Server
+
+## The Problem
+
+The "Not Found" error means the server is **not running**. You need to start it first.
+
+## Solution: Start the Server
+
+### Step 1: Open a PowerShell Terminal
+
+Make sure you're in the project directory:
+```powershell
+cd C:\Users\tarun\IITMTdsPrj2
+```
+
+### Step 2: Set Environment Variables
+
+```powershell
+$env:QUIZ_SECRET = "EasyQuiz"
+$env:OPENAI_API_KEY = "eyJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6IjI0ZjIwMDU3NTNAZHMuc3R1ZHkuaWl0bS5hYy5pbiJ9.eji7L5I62M9YHoeEKE8ao6eTw8dFjgDIMP9C3lOUXc4"
+```
+
+### Step 3: Start the Server
+
+```powershell
+python -m app.main
+```
+
+You should see:
+```
+INFO:     Started server process [...]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
+```
+
+**Keep this terminal open!** The server runs in this window.
+
+### Step 4: Test in Another Terminal
+
+Open a **NEW PowerShell window** and run:
+
+```powershell
+# Set variables again (in the new window)
+$env:QUIZ_SECRET = "EasyQuiz"
+
+# Test the API
+$body = @{
+    email = "24f2005753@ds.study.iitm.ac.in"
+    secret = "EasyQuiz"
+    url = "https://tds-llm-analysis.s-anand.net/demo"
+} | ConvertTo-Json
+
+Invoke-RestMethod -Uri "http://127.0.0.1:8000/demo" -Method POST -ContentType "application/json" -Body $body
+```
+
+## Quick Test Script
+
+I've created a test script. After starting the server, run:
+
+```powershell
+.\test_server.ps1
+```
+
+This will test all endpoints and show you what's working.
+
+## Troubleshooting
+
+### "Module not found" error
+```powershell
+pip install -r requirements.txt
+```
+
+### "Port already in use" error
+Another process is using port 8000. Either:
+- Stop the other process
+- Change the port: `$env:PORT = "8001"` then restart
+
+### Server starts but endpoints don't work
+- Make sure you're using the correct URL: `http://127.0.0.1:8000` or `http://localhost:8000`
+- Check for errors in the server terminal
+- Restart the server after code changes
+
+## Summary
+
+1. ✅ Start server: `python -m app.main` (keep terminal open)
+2. ✅ Open new terminal for testing
+3. ✅ Set variables in new terminal
+4. ✅ Test API endpoints
+

TEST_API.md

@@ -0,0 +1,222 @@
+# How to Check Environment Variables (JSON Format)
+
+## Method 1: Using the Test Script (Easiest)
+
+Run this command:
+```bash
+python test_env.json.py
+```
+
+**Example Output:**
+```json
+{
+  "status": "ok",
+  "variables": {
+    "QUIZ_SECRET": {
+      "set": true,
+      "length": 8,
+      "preview": "Easy...Quiz"
+    },
+    "OPENAI_API_KEY": {
+      "set": true,
+      "length": 200,
+      "preview": "sk-proj...4UA",
+      "valid_format": true
+    },
+    "PORT": {
+      "set": true,
+      "value": "8000"
+    }
+  },
+  "ready": true,
+  "llm_enabled": true,
+  "message": "Ready to run"
+}
+```
+
+## Method 2: Using the API Endpoint
+
+### Step 1: Start the Server
+```bash
+python -m app.main
+```
+
+### Step 2: Check Environment Variables
+
+**Using curl:**
+```bash
+curl http://localhost:8000/env-check
+```
+
+**Using PowerShell:**
+```powershell
+Invoke-RestMethod -Uri http://localhost:8000/env-check -Method Get | ConvertTo-Json
+```
+
+**Using Python:**
+```python
+import requests
+response = requests.get("http://localhost:8000/env-check")
+print(response.json())
+```
+
+**Example JSON Response:**
+```json
+{
+  "status": "ok",
+  "variables": {
+    "QUIZ_SECRET": {
+      "set": true,
+      "length": 8,
+      "preview": "Easy...Quiz"
+    },
+    "OPENAI_API_KEY": {
+      "set": true,
+      "length": 200,
+      "preview": "sk-proj...4UA",
+      "valid_format": true
+    },
+    "PORT": {
+      "set": true,
+      "value": "8000"
+    }
+  },
+  "ready": true,
+  "llm_enabled": true
+}
+```
+
+## Method 3: Test the Full API
+
+### Health Check
+```bash
+curl http://localhost:8000/health
+```
+**Response:**
+```json
+{
+  "status": "healthy"
+}
+```
+
+### Test Quiz Endpoint (with wrong secret - should return 403)
+```bash
+curl -X POST http://localhost:8000/solve \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "test@example.com",
+    "secret": "wrong_secret",
+    "url": "https://example.com"
+  }'
+```
+**Expected Response (403):**
+```json
+{
+  "detail": {
+    "error": "forbidden"
+  }
+}
+```
+
+### Test Quiz Endpoint (with correct secret)
+```bash
+curl -X POST http://localhost:8000/solve \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "test@example.com",
+    "secret": "EasyQuiz",
+    "url": "https://example.com/quiz"
+  }'
+```
+
+## Method 4: Quick PowerShell Test
+
+```powershell
+# Check variables directly
+$env:QUIZ_SECRET
+$env:OPENAI_API_KEY
+
+# Test with API (if server is running)
+$response = Invoke-RestMethod -Uri http://localhost:8000/env-check
+$response | ConvertTo-Json -Depth 10
+```
+
+## JSON Response Fields Explained
+
+| Field | Description |
+|-------|-------------|
+| `status` | Always "ok" if script runs |
+| `variables.QUIZ_SECRET.set` | `true` if QUIZ_SECRET is set |
+| `variables.QUIZ_SECRET.length` | Length of the secret |
+| `variables.QUIZ_SECRET.preview` | Masked preview (first 4 + last 4 chars) |
+| `variables.OPENAI_API_KEY.set` | `true` if API key is set |
+| `variables.OPENAI_API_KEY.valid_format` | `true` if key starts with "sk-" |
+| `ready` | `true` if QUIZ_SECRET is set (required) |
+| `llm_enabled` | `true` if OPENAI_API_KEY is set (optional) |
+| `message` | Human-readable status message |
+
+## Quick Test Commands
+
+### All-in-One Test (PowerShell)
+```powershell
+# 1. Check variables
+python test_env.json.py
+
+# 2. Start server (in another terminal)
+python -m app.main
+
+# 3. Test API (in another terminal)
+Invoke-RestMethod -Uri http://localhost:8000/env-check | ConvertTo-Json
+```
+
+### All-in-One Test (Bash/Linux)
+```bash
+# 1. Check variables
+python test_env.json.py
+
+# 2. Start server (in another terminal)
+python -m app.main
+
+# 3. Test API (in another terminal)
+curl http://localhost:8000/env-check | python -m json.tool
+```
+
+## Expected Results
+
+### ✅ Everything Working:
+```json
+{
+  "ready": true,
+  "llm_enabled": true,
+  "variables": {
+    "QUIZ_SECRET": { "set": true },
+    "OPENAI_API_KEY": { "set": true, "valid_format": true }
+  }
+}
+```
+
+### ⚠️ Missing QUIZ_SECRET:
+```json
+{
+  "ready": false,
+  "llm_enabled": true,
+  "variables": {
+    "QUIZ_SECRET": { "set": false },
+    "OPENAI_API_KEY": { "set": true }
+  },
+  "message": "QUIZ_SECRET is required"
+}
+```
+
+### ⚠️ Missing OPENAI_API_KEY (still works, but no LLM):
+```json
+{
+  "ready": true,
+  "llm_enabled": false,
+  "variables": {
+    "QUIZ_SECRET": { "set": true },
+    "OPENAI_API_KEY": { "set": false }
+  }
+}
+```
+

TEST_POWERSHELL.md

@@ -0,0 +1,175 @@
+# Testing the API with PowerShell
+
+## The Problem
+
+The error `D1_TYPE_ERROR: Type 'object' not supported for value '[object Object]'` occurs because PowerShell needs the JSON body to be properly formatted.
+
+## Solution: Correct PowerShell Syntax
+
+### Method 1: Using PowerShell Object (Recommended)
+
+```powershell
+# Create body as PowerShell object, then convert to JSON
+$body = @{
+    email = "24f2005753@ds.study.iitm.ac.in"
+    secret = "EasyQuiz"
+    url = "https://tds-llm-analysis.s-anand.net/demo"
+} | ConvertTo-Json
+
+# Send request
+Invoke-RestMethod `
+    -Uri "http://127.0.0.1:8000/solve" `
+    -Method POST `
+    -ContentType "application/json" `
+    -Body $body
+```
+
+### Method 2: Using Here-String (Alternative)
+
+```powershell
+$body = @'
+{
+    "email": "24f2005753@ds.study.iitm.ac.in",
+    "secret": "EasyQuiz",
+    "url": "https://tds-llm-analysis.s-anand.net/demo"
+}
+'@
+
+Invoke-RestMethod `
+    -Uri "http://127.0.0.1:8000/solve" `
+    -Method POST `
+    -ContentType "application/json" `
+    -Body $body
+```
+
+### Method 3: Using the Test Script
+
+Run the provided test script:
+
+```powershell
+.\test_api.ps1
+```
+
+## Common Issues and Fixes
+
+### Issue 1: JSON String Not Properly Formatted
+
+**Wrong:**
+```powershell
+-Body '{
+    "email": "...",
+    "secret": "...",
+    "url": "..."
+}'
+```
+
+**Right:**
+```powershell
+$body = @{
+    email = "..."
+    secret = "..."
+    url = "..."
+} | ConvertTo-Json
+
+-Body $body
+```
+
+### Issue 2: Server Not Running
+
+Make sure the server is running:
+```powershell
+python -m app.main
+```
+
+### Issue 3: Wrong Endpoint
+
+Try the `/demo` endpoint instead:
+```powershell
+$body = @{
+    email = "24f2005753@ds.study.iitm.ac.in"
+    secret = "EasyQuiz"
+    url = "https://tds-llm-analysis.s-anand.net/demo"
+} | ConvertTo-Json
+
+Invoke-RestMethod `
+    -Uri "http://127.0.0.1:8000/demo" `
+    -Method POST `
+    -ContentType "application/json" `
+    -Body $body
+```
+
+## Complete Example
+
+```powershell
+# Step 1: Set environment variables
+$env:QUIZ_SECRET = "EasyQuiz"
+
+# Step 2: Start server (in one terminal)
+# python -m app.main
+
+# Step 3: Test API (in another terminal)
+$body = @{
+    email = "24f2005753@ds.study.iitm.ac.in"
+    secret = "EasyQuiz"
+    url = "https://tds-llm-analysis.s-anand.net/demo"
+} | ConvertTo-Json
+
+$response = Invoke-RestMethod `
+    -Uri "http://127.0.0.1:8000/demo" `
+    -Method POST `
+    -ContentType "application/json" `
+    -Body $body
+
+# Display response
+$response | ConvertTo-Json -Depth 10
+```
+
+## Using curl (Alternative)
+
+If PowerShell gives you trouble, use curl:
+
+```powershell
+curl.exe -X POST http://127.0.0.1:8000/demo `
+  -H "Content-Type: application/json" `
+  -d '{\"email\":\"24f2005753@ds.study.iitm.ac.in\",\"secret\":\"EasyQuiz\",\"url\":\"https://tds-llm-analysis.s-anand.net/demo\"}'
+```
+
+Or save JSON to a file:
+
+```powershell
+# Create request.json
+@'
+{
+    "email": "24f2005753@ds.study.iitm.ac.in",
+    "secret": "EasyQuiz",
+    "url": "https://tds-llm-analysis.s-anand.net/demo"
+}
+'@ | Out-File -FilePath request.json -Encoding utf8
+
+# Send request
+curl.exe -X POST http://127.0.0.1:8000/demo `
+  -H "Content-Type: application/json" `
+  -d "@request.json"
+```
+
+## Error Handling
+
+```powershell
+try {
+    $response = Invoke-RestMethod `
+        -Uri "http://127.0.0.1:8000/solve" `
+        -Method POST `
+        -ContentType "application/json" `
+        -Body $body
+    
+    $response | ConvertTo-Json -Depth 10
+}
+catch {
+    Write-Host "Error: $($_.Exception.Message)" -ForegroundColor Red
+    if ($_.ErrorDetails.Message) {
+        Write-Host $_.ErrorDetails.Message -ForegroundColor Yellow
+    }
+}
+```
+
+

__init__.py

@@ -0,0 +1,3 @@
+# IITM LLM Quiz Solver
+__version__ = "1.0.0"
+

browser.py

@@ -0,0 +1,247 @@
+"""
+Playwright browser helper for loading and interacting with quiz pages.
+"""
+import asyncio
+import logging
+from typing import Optional, Dict, Any, List
+from playwright.async_api import async_playwright, Browser, Page, BrowserContext
+import time
+
+logger = logging.getLogger(__name__)
+
+
+class BrowserHelper:
+    """Helper class for managing Playwright browser sessions."""
+    
+    def __init__(self):
+        self.browser: Optional[Browser] = None
+        self.context: Optional[BrowserContext] = None
+        self.page: Optional[Page] = None
+        self.playwright = None
+    
+    async def start(self, headless: bool = True) -> None:
+        """
+        Start Playwright browser.
+        
+        Args:
+            headless: Run in headless mode
+        """
+        try:
+            self.playwright = await async_playwright().start()
+            self.browser = await self.playwright.chromium.launch(
+                headless=headless,
+                args=[
+                    '--no-sandbox',
+                    '--disable-setuid-sandbox',
+                    '--disable-dev-shm-usage',
+                    '--disable-accelerated-2d-canvas',
+                    '--disable-gpu'
+                ]
+            )
+            self.context = await self.browser.new_context(
+                viewport={'width': 1920, 'height': 1080},
+                user_agent='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
+            )
+            self.page = await self.context.new_page()
+            logger.info("Browser started successfully")
+        except Exception as e:
+            logger.error(f"Error starting browser: {e}")
+            raise
+    
+    async def load_page(self, url: str, wait_time: int = 5, timeout: int = 30000) -> Dict[str, Any]:
+        """
+        Load a page and extract all content.
+        
+        Args:
+            url: URL to load
+            wait_time: Seconds to wait for page to load
+            timeout: Page load timeout in milliseconds
+            
+        Returns:
+            Dictionary with page content
+        """
+        if not self.page:
+            await self.start()
+        
+        try:
+            logger.info(f"Loading page: {url}")
+            await self.page.goto(url, wait_until='networkidle', timeout=timeout)
+            
+            # Wait for dynamic content
+            await asyncio.sleep(wait_time)
+            
+            # Extract page content
+            content = {
+                'url': url,
+                'title': await self.page.title(),
+                'text': await self.page.inner_text('body'),
+                'html': await self.page.content(),
+                'screenshot': await self.page.screenshot(full_page=True),
+            }
+            
+            # Try to extract all visible text elements
+            try:
+                content['all_text'] = await self.page.evaluate("""
+                    () => {
+                        const walker = document.createTreeWalker(
+                            document.body,
+                            NodeFilter.SHOW_TEXT,
+                            null,
+                            false
+                        );
+                        let text = [];
+                        let node;
+                        while (node = walker.nextNode()) {
+                            if (node.textContent.trim()) {
+                                text.push(node.textContent.trim());
+                            }
+                        }
+                        return text.join('\\n');
+                    }
+                """)
+            except Exception as e:
+                logger.warning(f"Error extracting all text: {e}")
+                content['all_text'] = content['text']
+            
+            # Extract links
+            try:
+                content['links'] = await self.page.evaluate("""
+                    () => {
+                        const links = Array.from(document.querySelectorAll('a[href]'));
+                        return links.map(a => ({text: a.textContent.trim(), href: a.href}));
+                    }
+                """)
+            except Exception as e:
+                logger.warning(f"Error extracting links: {e}")
+                content['links'] = []
+            
+            # Extract images
+            try:
+                content['images'] = await self.page.evaluate("""
+                    () => {
+                        const images = Array.from(document.querySelectorAll('img[src]'));
+                        return images.map(img => ({alt: img.alt, src: img.src}));
+                    }
+                """)
+            except Exception as e:
+                logger.warning(f"Error extracting images: {e}")
+                content['images'] = []
+            
+            logger.info(f"Page loaded successfully: {content['title']}")
+            return content
+            
+        except Exception as e:
+            logger.error(f"Error loading page {url}: {e}")
+            raise
+    
+    async def click_element(self, selector: str) -> bool:
+        """
+        Click an element on the page.
+        
+        Args:
+            selector: CSS selector
+            
+        Returns:
+            True if successful
+        """
+        try:
+            await self.page.click(selector)
+            await asyncio.sleep(1)
+            return True
+        except Exception as e:
+            logger.error(f"Error clicking element {selector}: {e}")
+            return False
+    
+    async def fill_input(self, selector: str, value: str) -> bool:
+        """
+        Fill an input field.
+        
+        Args:
+            selector: CSS selector
+            value: Value to fill
+            
+        Returns:
+            True if successful
+        """
+        try:
+            await self.page.fill(selector, value)
+            return True
+        except Exception as e:
+            logger.error(f"Error filling input {selector}: {e}")
+            return False
+    
+    async def wait_for_element(self, selector: str, timeout: int = 10000) -> bool:
+        """
+        Wait for an element to appear.
+        
+        Args:
+            selector: CSS selector
+            timeout: Timeout in milliseconds
+            
+        Returns:
+            True if element found
+        """
+        try:
+            await self.page.wait_for_selector(selector, timeout=timeout)
+            return True
+        except Exception as e:
+            logger.warning(f"Element {selector} not found: {e}")
+            return False
+    
+    async def evaluate_script(self, script: str) -> Any:
+        """
+        Execute JavaScript on the page.
+        
+        Args:
+            script: JavaScript code to execute
+            
+        Returns:
+            Result of script execution
+        """
+        try:
+            return await self.page.evaluate(script)
+        except Exception as e:
+            logger.error(f"Error evaluating script: {e}")
+            return None
+    
+    async def close(self) -> None:
+        """Close browser and cleanup."""
+        try:
+            if self.page:
+                await self.page.close()
+            if self.context:
+                await self.context.close()
+            if self.browser:
+                await self.browser.close()
+            if self.playwright:
+                await self.playwright.stop()
+            logger.info("Browser closed")
+        except Exception as e:
+            logger.error(f"Error closing browser: {e}")
+
+
+# Global browser instance
+_browser: Optional[BrowserHelper] = None
+
+
+async def get_browser() -> BrowserHelper:
+    """
+    Get or create a browser instance.
+    
+    Returns:
+        BrowserHelper instance
+    """
+    global _browser
+    if _browser is None:
+        _browser = BrowserHelper()
+        await _browser.start()
+    return _browser
+
+
+async def cleanup_browser() -> None:
+    """Cleanup browser instance."""
+    global _browser
+    if _browser:
+        await _browser.close()
+        _browser = None
+

check_and_start.ps1

@@ -0,0 +1,78 @@
+# Script to check if server is running and help start it
+# Usage: .\check_and_start.ps1
+
+Write-Host "IITM LLM Quiz Solver - Server Check" -ForegroundColor Cyan
+Write-Host "====================================" -ForegroundColor Cyan
+Write-Host ""
+
+# Check if port 8000 is in use
+Write-Host "Checking if server is running on port 8000..." -ForegroundColor Yellow
+$portCheck = Test-NetConnection -ComputerName localhost -Port 8000 -InformationLevel Quiet -WarningAction SilentlyContinue
+
+if ($portCheck) {
+    Write-Host "✓ Port 8000 is open - server might be running" -ForegroundColor Green
+    Write-Host ""
+    Write-Host "Testing /health endpoint..." -ForegroundColor Yellow
+    try {
+        $health = Invoke-RestMethod -Uri "http://127.0.0.1:8000/health" -Method GET -TimeoutSec 2 -ErrorAction Stop
+        Write-Host "✓ Server is running and responding!" -ForegroundColor Green
+        Write-Host "  Health status: $($health.status)" -ForegroundColor Gray
+        Write-Host ""
+        Write-Host "Testing /demo endpoint..." -ForegroundColor Yellow
+        Write-Host "  (This will make a test request)" -ForegroundColor Gray
+        
+        # Set variables
+        if (-not $env:QUIZ_SECRET) {
+            $env:QUIZ_SECRET = "EasyQuiz"
+        }
+        
+        $body = @{
+            email = "24f2005753@ds.study.iitm.ac.in"
+            secret = "EasyQuiz"
+            url = "https://tds-llm-analysis.s-anand.net/demo"
+        } | ConvertTo-Json
+        
+        try {
+            $response = Invoke-RestMethod `
+                -Uri "http://127.0.0.1:8000/demo" `
+                -Method POST `
+                -ContentType "application/json" `
+                -Body $body `
+                -TimeoutSec 30 `
+                -ErrorAction Stop
+            
+            Write-Host "✓ /demo endpoint works!" -ForegroundColor Green
+            Write-Host "  Response:" -ForegroundColor Gray
+            $response | ConvertTo-Json -Depth 10 | Write-Host
+        } catch {
+            Write-Host "✗ /demo endpoint failed" -ForegroundColor Red
+            Write-Host "  Error: $($_.Exception.Message)" -ForegroundColor Yellow
+            if ($_.ErrorDetails.Message) {
+                Write-Host "  Details: $($_.ErrorDetails.Message)" -ForegroundColor Yellow
+            }
+        }
+    } catch {
+        Write-Host "✗ Server is not responding correctly" -ForegroundColor Red
+        Write-Host "  Error: $($_.Exception.Message)" -ForegroundColor Yellow
+        Write-Host ""
+        Write-Host "The port is open but the server might not be our FastAPI app." -ForegroundColor Yellow
+        Write-Host "Please check if you have the correct server running." -ForegroundColor Yellow
+    }
+} else {
+    Write-Host "✗ Port 8000 is NOT open - server is NOT running" -ForegroundColor Red
+    Write-Host ""
+    Write-Host "To start the server:" -ForegroundColor Yellow
+    Write-Host "  1. Set environment variables:" -ForegroundColor Cyan
+    Write-Host "     `$env:QUIZ_SECRET = 'EasyQuiz'" -ForegroundColor Gray
+    Write-Host "     `$env:OPENAI_API_KEY = 'your-key-here'" -ForegroundColor Gray
+    Write-Host ""
+    Write-Host "  2. Start the server:" -ForegroundColor Cyan
+    Write-Host "     python -m app.main" -ForegroundColor Gray
+    Write-Host ""
+    Write-Host "  3. Keep that terminal open and test in another terminal" -ForegroundColor Cyan
+}
+
+Write-Host ""
+Write-Host "====================================" -ForegroundColor Cyan
+
+

check_env.py

@@ -0,0 +1,93 @@
+"""
+Quick script to check if environment variables are set correctly.
+Run: python check_env.py
+"""
+import os
+import sys
+
+def check_env():
+    """Check and display environment variable status."""
+    print("=" * 50)
+    print("IITM LLM Quiz Solver - Environment Check")
+    print("=" * 50)
+    print()
+    
+    # Check QUIZ_SECRET
+    quiz_secret = os.getenv("QUIZ_SECRET")
+    if quiz_secret:
+        # Show first and last 4 chars for security
+        masked = f"{quiz_secret[:4]}...{quiz_secret[-4:]}" if len(quiz_secret) > 8 else "***"
+        print(f"✓ QUIZ_SECRET: Set ({masked})")
+        print(f"  Length: {len(quiz_secret)} characters")
+    else:
+        print("✗ QUIZ_SECRET: NOT SET (Required)")
+        print("  Set it with: export QUIZ_SECRET='your_secret' (Linux/Mac)")
+        print("  Or: $env:QUIZ_SECRET = 'your_secret' (Windows PowerShell)")
+    
+    print()
+    
+    # Check OpenAI key
+    openai_key = os.getenv("OPENAI_API_KEY")
+    if openai_key:
+        masked = f"{openai_key[:7]}...{openai_key[-4:]}" if len(openai_key) > 11 else "***"
+        print(f"✓ OPENAI_API_KEY: Set ({masked})")
+        print(f"  Length: {len(openai_key)} characters")
+        if not openai_key.startswith("sk-"):
+            print("  ⚠ Warning: OpenAI keys usually start with 'sk-'")
+    else:
+        print("✗ OPENAI_API_KEY: NOT SET (Optional)")
+        print("  Set it with: export OPENAI_API_KEY='sk-your-key' (Linux/Mac)")
+        print("  Or: $env:OPENAI_API_KEY = 'sk-your-key' (Windows PowerShell)")
+    
+    print()
+    
+    # Check OpenRouter key
+    openrouter_key = os.getenv("OPENROUTER_API_KEY")
+    if openrouter_key:
+        masked = f"{openrouter_key[:6]}...{openrouter_key[-4:]}" if len(openrouter_key) > 10 else "***"
+        print(f"✓ OPENROUTER_API_KEY: Set ({masked})")
+        print(f"  Length: {len(openrouter_key)} characters")
+        if not openrouter_key.startswith("sk-or-"):
+            print("  ⚠ Warning: OpenRouter keys usually start with 'sk-or-'")
+        model = os.getenv("OPENROUTER_MODEL", "gpt-5-nano")
+        print(f"  Model: {model}")
+    else:
+        print("✗ OPENROUTER_API_KEY: NOT SET (Optional)")
+        print("  Set it with: export OPENROUTER_API_KEY='sk-or-your-key' (Linux/Mac)")
+        print("  Or: $env:OPENROUTER_API_KEY = 'sk-or-your-key' (Windows PowerShell)")
+    
+    print()
+    
+    # Check PORT (optional)
+    port = os.getenv("PORT", "8000")
+    print(f"PORT: {port} (default: 8000)")
+    
+    print()
+    print("=" * 50)
+    
+    # Summary
+    if quiz_secret:
+        print("✓ Status: Ready to run (QUIZ_SECRET is set)")
+        if openai_key or openrouter_key:
+            provider = []
+            if openai_key:
+                provider.append("OpenAI")
+            if openrouter_key:
+                provider.append("OpenRouter")
+            print(f"✓ LLM features: Enabled via {', '.join(provider)}")
+        else:
+            print("⚠ LLM features: Disabled (no LLM API keys set)")
+    else:
+        print("✗ Status: NOT READY - QUIZ_SECRET is required")
+        sys.exit(1)
+    
+    print("=" * 50)
+    print()
+    print("To start the server, run:")
+    print("  python -m app.main")
+    print("  or")
+    print("  uvicorn app.main:app --host 0.0.0.0 --port 8000")
+
+if __name__ == "__main__":
+    check_env()
+

llm.py

@@ -0,0 +1,251 @@
+"""
+LLM helper module for OpenAI GPT integration.
+Used for reasoning, OCR, and complex question parsing.
+"""
+import os
+import logging
+from typing import Optional, Dict, Any
+import openai
+from openai import AsyncOpenAI
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# Initialize OpenAI client
+client: Optional[AsyncOpenAI] = None
+
+# OpenRouter configuration
+OPENROUTER_API_KEY = os.getenv("OPENROUTER_API_KEY")
+OPENROUTER_BASE_URL = os.getenv("OPENROUTER_BASE_URL", "https://openrouter.ai/api/v1")
+OPENROUTER_MODEL = os.getenv("OPENROUTER_MODEL", "gpt-5-nano")
+OPENROUTER_SITE_URL = os.getenv("OPENROUTER_SITE_URL", "http://localhost")
+OPENROUTER_APP_NAME = os.getenv("OPENROUTER_APP_NAME", "IITM LLM Quiz Solver")
+
+
+def initialize_llm() -> None:
+    """
+    Initialize OpenAI client with API key from environment.
+    """
+    global client
+    api_key = os.getenv("OPENAI_API_KEY")
+    if api_key:
+        client = AsyncOpenAI(api_key=api_key)
+        logger.info("OpenAI client initialized")
+    else:
+        if OPENROUTER_API_KEY:
+            logger.info("OPENAI_API_KEY not set, using OpenRouter only")
+        else:
+            logger.warning("No OPENAI_API_KEY or OPENROUTER_API_KEY set, LLM features will be disabled")
+
+
+async def ask_gpt(prompt: str, model: str = "gpt-4o-mini", max_tokens: int = 2000) -> Optional[str]:
+    """
+    Query OpenAI GPT model with a prompt.
+    
+    Args:
+        prompt: The prompt/question to ask
+        model: Model to use (default: gpt-4o-mini)
+        max_tokens: Maximum tokens in response
+        
+    Returns:
+        Response text or None if error
+    """
+    global client
+    
+    try:
+        if client:
+            response = await client.chat.completions.create(
+                model=model,
+                messages=[
+                    {"role": "system", "content": "You are a helpful assistant that solves quiz questions accurately and concisely."},
+                    {"role": "user", "content": prompt}
+                ],
+                max_tokens=max_tokens,
+                temperature=0.3
+            )
+            
+            answer = response.choices[0].message.content
+            logger.info(f"GPT response received (model: {model})")
+            return answer
+        else:
+            logger.warning("OpenAI client not initialized, attempting OpenRouter fallback")
+            return await ask_openrouter(prompt, max_tokens=max_tokens)
+        
+    except Exception as e:
+        logger.error(f"Error calling OpenAI API: {e}")
+        # Fallback to OpenRouter if configured
+        fallback = await ask_openrouter(prompt, max_tokens=max_tokens)
+        if fallback:
+            return fallback
+        return None
+
+
+async def ask_openrouter(prompt: str, model: Optional[str] = None, max_tokens: int = 2000) -> Optional[str]:
+    """
+    Query OpenRouter (e.g., GPT-5-nano) with a prompt.
+    
+    Args:
+        prompt: Prompt text
+        model: Model to use (defaults to OPENROUTER_MODEL)
+        max_tokens: Maximum tokens
+        
+    Returns:
+        Response text or None
+    """
+    if not OPENROUTER_API_KEY:
+        logger.warning("OPENROUTER_API_KEY not set, cannot call OpenRouter")
+        return None
+    
+    if not model:
+        model = OPENROUTER_MODEL
+    
+    url = f"{OPENROUTER_BASE_URL.rstrip('/')}/chat/completions"
+    headers = {
+        "Authorization": f"Bearer {OPENROUTER_API_KEY}",
+        "HTTP-Referer": OPENROUTER_SITE_URL,
+        "X-Title": OPENROUTER_APP_NAME,
+        "Content-Type": "application/json",
+    }
+    payload = {
+        "model": model,
+        "messages": [
+            {"role": "system", "content": "You are a helpful assistant that solves quiz questions accurately and concisely."},
+            {"role": "user", "content": prompt}
+        ],
+        "max_tokens": max_tokens,
+        "temperature": 0.2
+    }
+    
+    try:
+        async with httpx.AsyncClient(timeout=60) as http_client:
+            response = await http_client.post(url, headers=headers, json=payload)
+            response.raise_for_status()
+            data = response.json()
+            answer = data["choices"][0]["message"]["content"]
+            logger.info(f"OpenRouter response received (model: {model})")
+            return answer
+    except Exception as e:
+        logger.error(f"Error calling OpenRouter API: {e}")
+        return None
+
+
+async def parse_question_with_llm(question_text: str, context: str = "") -> Optional[Dict[str, Any]]:
+    """
+    Use LLM to parse and understand a quiz question.
+    
+    Args:
+        question_text: The question text
+        context: Additional context from the page
+        
+    Returns:
+        Parsed question structure or None
+    """
+    prompt = f"""Analyze this quiz question and provide a structured response:
+
+Question: {question_text}
+
+Context: {context}
+
+Please identify:
+1. What type of question is this? (scraping, calculation, API call, data analysis, etc.)
+2. What data or resources are needed?
+3. What is the expected answer format? (JSON, number, text, etc.)
+
+Respond in JSON format:
+{{
+    "type": "question_type",
+    "requirements": ["requirement1", "requirement2"],
+    "answer_format": "format_type",
+    "reasoning": "your reasoning"
+}}
+"""
+    
+    response = await ask_gpt(prompt)
+    if not response:
+        return None
+    
+    # Try to extract JSON from response
+    import json
+    import re
+    
+    json_match = re.search(r'\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}', response, re.DOTALL)
+    if json_match:
+        try:
+            return json.loads(json_match.group())
+        except json.JSONDecodeError:
+            pass
+    
+    return {"raw_response": response}
+
+
+async def solve_with_llm(question: str, available_data: Dict[str, Any]) -> Optional[str]:
+    """
+    Use LLM to solve a quiz question.
+    
+    Args:
+        question: The question text
+        available_data: Any data extracted from the page
+        
+    Returns:
+        Answer or None
+    """
+    prompt = f"""Solve this quiz question:
+
+Question: {question}
+
+Available Data:
+{available_data}
+
+Provide a clear, concise answer. If the answer should be in JSON format, provide valid JSON.
+If it's a calculation, show your work briefly.
+"""
+    
+    return await ask_gpt(prompt, max_tokens=3000)
+
+
+async def ocr_image_with_llm(image_base64: str) -> Optional[str]:
+    """
+    Use GPT-4 Vision to extract text from an image.
+    
+    Note: Requires GPT-4 Vision model (gpt-4o or gpt-4-vision-preview).
+    gpt-4o-mini does not support vision.
+    
+    Args:
+        image_base64: Base64 encoded image
+        
+    Returns:
+        Extracted text or None
+    """
+    global client
+    
+    if not client:
+        return None
+    
+    # Try vision-capable models
+    vision_models = ["gpt-4o", "gpt-4-vision-preview"]
+    
+    for model in vision_models:
+        try:
+            response = await client.chat.completions.create(
+                model=model,
+                messages=[
+                    {
+                        "role": "user",
+                        "content": [
+                            {"type": "text", "text": "Extract all text from this image. Return only the text content."},
+                            {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{image_base64}"}}
+                        ]
+                    }
+                ],
+                max_tokens=1000
+            )
+            
+            return response.choices[0].message.content
+            
+        except Exception as e:
+            logger.warning(f"Error with model {model}: {e}")
+            continue
+    
+    logger.error("No vision-capable model available")
+    return None
+

main.py

@@ -0,0 +1,250 @@
+"""
+FastAPI main server for IITM LLM Quiz Solver.
+"""
+import os
+import logging
+import asyncio
+from typing import Dict, Any, Optional
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field, field_validator
+import uvicorn
+
+# Try to load .env file if python-dotenv is available
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass  # python-dotenv is optional
+
+from app.solver import solve_quiz
+from app.utils import validate_secret
+from app.browser import cleanup_browser
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# Get secret from environment
+EXPECTED_SECRET = os.getenv("QUIZ_SECRET", "default_secret_change_me")
+
+# Lifespan context manager for startup and shutdown
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Lifespan context manager for startup and shutdown."""
+    # Startup
+    logger.info("Application starting up...")
+    yield
+    # Shutdown
+    logger.info("Shutting down, cleaning up browser...")
+    await cleanup_browser()
+
+# Initialize FastAPI app with lifespan
+app = FastAPI(
+    title="IITM LLM Quiz Solver",
+    description="API endpoint to automatically solve dynamic quiz tasks",
+    version="1.0.0",
+    lifespan=lifespan
+)
+
+
+class QuizRequest(BaseModel):
+    """Request model for quiz solving."""
+    email: str = Field(..., description="User email address")
+    secret: str = Field(..., description="Secret key for authentication")
+    url: str = Field(..., description="Quiz page URL")
+    
+    @field_validator('email')
+    @classmethod
+    def validate_email(cls, v):
+        if not v or '@' not in v:
+            raise ValueError('Invalid email format')
+        return v
+    
+    @field_validator('url')
+    @classmethod
+    def validate_url(cls, v):
+        if not v or not v.startswith(('http://', 'https://')):
+            raise ValueError('Invalid URL format')
+        return v
+
+
+@app.get("/")
+async def root():
+    """Root endpoint."""
+    return {
+        "message": "IITM LLM Quiz Solver API",
+        "version": "1.0.0",
+        "endpoints": {
+            "/solve": "POST - Solve a quiz",
+            "/health": "GET - Health check",
+            "/demo": "POST - Demo endpoint"
+        }
+    }
+
+
+@app.get("/health")
+async def health_check():
+    """Health check endpoint."""
+    return {"status": "healthy"}
+
+
+@app.get("/env-check")
+async def env_check():
+    """
+    Check environment variables status (returns JSON).
+    Useful for verifying configuration.
+    """
+    quiz_secret = os.getenv("QUIZ_SECRET")
+    openai_key = os.getenv("OPENAI_API_KEY")
+    openrouter_key = os.getenv("OPENROUTER_API_KEY")
+    port = os.getenv("PORT", "8000")
+    
+    return {
+        "status": "ok",
+        "variables": {
+            "QUIZ_SECRET": {
+                "set": quiz_secret is not None,
+                "length": len(quiz_secret) if quiz_secret else 0,
+                "preview": f"{quiz_secret[:4]}...{quiz_secret[-4:]}" if quiz_secret and len(quiz_secret) > 8 else "***" if quiz_secret else None
+            },
+            "OPENAI_API_KEY": {
+                "set": openai_key is not None,
+                "length": len(openai_key) if openai_key else 0,
+                "preview": f"{openai_key[:7]}...{openai_key[-4:]}" if openai_key and len(openai_key) > 11 else "***" if openai_key else None,
+                "valid_format": openai_key.startswith("sk-") if openai_key else False
+            },
+            "OPENROUTER_API_KEY": {
+                "set": openrouter_key is not None,
+                "length": len(openrouter_key) if openrouter_key else 0,
+                "preview": f"{openrouter_key[:7]}...{openrouter_key[-4:]}" if openrouter_key and len(openrouter_key) > 11 else "***" if openrouter_key else None,
+                "valid_format": openrouter_key.startswith("sk-or-") if openrouter_key else False
+            },
+            "PORT": {
+                "set": True,
+                "value": port
+            }
+        },
+        "ready": quiz_secret is not None,
+        "llm_enabled": any([openai_key, openrouter_key])
+    }
+
+
+@app.post("/solve")
+async def solve_quiz_endpoint(request: QuizRequest):
+    """
+    Main endpoint to solve a quiz.
+    
+    Validates secret and solves the quiz recursively.
+    """
+    try:
+        # Validate secret
+        if not validate_secret(request.secret, EXPECTED_SECRET):
+            logger.warning(f"Invalid secret provided for email: {request.email}")
+            raise HTTPException(
+                status_code=403,
+                detail={"error": "forbidden"}
+            )
+        
+        logger.info(f"Solving quiz for {request.email} at {request.url}")
+        
+        # Solve quiz with timeout
+        try:
+            result = await asyncio.wait_for(
+                solve_quiz(request.url, request.email, request.secret),
+                timeout=180.0  # 3 minutes
+            )
+            return result
+        except asyncio.TimeoutError:
+            logger.error("Quiz solving timed out")
+            raise HTTPException(
+                status_code=504,
+                detail={"error": "Request timeout - quiz solving took too long"}
+            )
+        except Exception as e:
+            logger.error(f"Error solving quiz: {e}", exc_info=True)
+            raise HTTPException(
+                status_code=500,
+                detail={"error": str(e)}
+            )
+            
+    except HTTPException:
+        raise
+    except ValueError as e:
+        logger.error(f"Validation error: {e}")
+        raise HTTPException(
+            status_code=400,
+            detail={"error": "Invalid request format", "message": str(e)}
+        )
+    except Exception as e:
+        logger.error(f"Unexpected error: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=500,
+            detail={"error": "Internal server error", "message": str(e)}
+        )
+
+
+@app.post("/demo")
+async def demo_endpoint(request: QuizRequest):
+    """
+    Demo endpoint for testing.
+    
+    Same as /solve but with more lenient error handling.
+    """
+    try:
+        # Validate secret (can be more lenient for demo)
+        if not validate_secret(request.secret, EXPECTED_SECRET):
+            logger.warning(f"Invalid secret in demo request")
+            return JSONResponse(
+                status_code=403,
+                content={"error": "forbidden"}
+            )
+        
+        logger.info(f"Demo: Solving quiz for {request.email} at {request.url}")
+        
+        # Solve quiz
+        try:
+            result = await asyncio.wait_for(
+                solve_quiz(request.url, request.email, request.secret),
+                timeout=180.0
+            )
+            return result
+        except asyncio.TimeoutError:
+            return JSONResponse(
+                status_code=504,
+                content={"error": "Request timeout"}
+            )
+        except Exception as e:
+            logger.error(f"Error in demo: {e}", exc_info=True)
+            return JSONResponse(
+                status_code=500,
+                content={"error": str(e)}
+            )
+            
+    except ValueError as e:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "Invalid request format", "message": str(e)}
+        )
+    except Exception as e:
+        logger.error(f"Unexpected error in demo: {e}", exc_info=True)
+        return JSONResponse(
+            status_code=500,
+            content={"error": "Internal server error", "message": str(e)}
+        )
+
+
+if __name__ == "__main__":
+    port = int(os.getenv("PORT", 8000))
+    uvicorn.run(
+        "app.main:app",
+        host="0.0.0.0",
+        port=port,
+        log_level="info"
+    )
+

requirements.txt

@@ -0,0 +1,14 @@
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+playwright==1.40.0
+requests==2.31.0
+beautifulsoup4==4.12.2
+pandas==2.1.3
+PyPDF2==3.0.1
+pdfplumber==0.10.3
+openai==1.3.5
+pydantic==2.5.0
+lxml==4.9.3
+html5lib==1.1
+python-dotenv==1.0.0
+

restart_server.ps1

@@ -0,0 +1,41 @@
+# Script to stop any server on port 8000 and start the correct one
+# Usage: .\restart_server.ps1
+
+Write-Host "IITM LLM Quiz Solver - Server Restart" -ForegroundColor Cyan
+Write-Host "=====================================" -ForegroundColor Cyan
+Write-Host ""
+
+# Find process using port 8000
+Write-Host "Finding process using port 8000..." -ForegroundColor Yellow
+$portInfo = netstat -ano | findstr :8000 | findstr LISTENING
+if ($portInfo) {
+    $pid = ($portInfo -split '\s+')[-1]
+    Write-Host "Found process ID: $pid" -ForegroundColor Yellow
+    
+    $process = Get-Process -Id $pid -ErrorAction SilentlyContinue
+    if ($process) {
+        Write-Host "Process: $($process.ProcessName) (PID: $pid)" -ForegroundColor Yellow
+        Write-Host ""
+        Write-Host "Stopping process..." -ForegroundColor Yellow
+        Stop-Process -Id $pid -Force -ErrorAction SilentlyContinue
+        Start-Sleep -Seconds 2
+        Write-Host "✓ Process stopped" -ForegroundColor Green
+    }
+} else {
+    Write-Host "No process found on port 8000" -ForegroundColor Green
+}
+
+Write-Host ""
+Write-Host "Setting environment variables..." -ForegroundColor Yellow
+$env:QUIZ_SECRET = "EasyQuiz"
+$env:OPENAI_API_KEY = "eyJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6IjI0ZjIwMDU3NTNAZHMuc3R1ZHkuaWl0bS5hYy5pbiJ9.eji7L5I62M9YHoeEKE8ao6eTw8dFjgDIMP9C3lOUXc4"
+Write-Host "✓ Environment variables set" -ForegroundColor Green
+
+Write-Host ""
+Write-Host "=====================================" -ForegroundColor Cyan
+Write-Host "Now start the server manually:" -ForegroundColor Yellow
+Write-Host "  python -m app.main" -ForegroundColor Cyan
+Write-Host ""
+Write-Host "Keep that terminal open, then test in another terminal!" -ForegroundColor Yellow
+
+

set_api_key.ps1

@@ -0,0 +1,20 @@
+# Quick script to set OpenAI API key
+# Usage: .\set_api_key.ps1
+
+$apiKey = "eyJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6IjI0ZjIwMDU3NTNAZHMuc3R1ZHkuaWl0bS5hYy5pbiJ9.eji7L5I62M9YHoeEKE8ao6eTw8dFjgDIMP9C3lOUXc4"
+
+Write-Host "Setting OPENAI_API_KEY for current session..." -ForegroundColor Cyan
+$env:OPENAI_API_KEY = $apiKey
+
+Write-Host "✓ OPENAI_API_KEY set" -ForegroundColor Green
+Write-Host ""
+Write-Host "To make it permanent, run:" -ForegroundColor Yellow
+Write-Host '[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "' + $apiKey + '", "User")' -ForegroundColor Gray
+Write-Host ""
+Write-Host "⚠️  Note: This looks like a JWT token, not a standard OpenAI API key." -ForegroundColor Yellow
+Write-Host "   OpenAI keys usually start with 'sk-'. If LLM features don't work," -ForegroundColor Yellow
+Write-Host "   you may need to get your actual OpenAI API key from:" -ForegroundColor Yellow
+Write-Host "   https://platform.openai.com/api-keys" -ForegroundColor Cyan
+Write-Host ""
+Write-Host "To verify, run: python test_env.json.py" -ForegroundColor Cyan
+

setup_env.ps1

@@ -0,0 +1,72 @@
+# Quick Environment Setup Script for Windows PowerShell
+# Usage: .\setup_env.ps1
+
+Write-Host "IITM LLM Quiz Solver - Environment Setup" -ForegroundColor Cyan
+Write-Host "========================================" -ForegroundColor Cyan
+Write-Host ""
+
+# Check if variables are already set
+$quizSecret = $env:QUIZ_SECRET
+$openaiKey = $env:OPENAI_API_KEY
+$openrouterKey = $env:OPENROUTER_API_KEY
+
+if ($quizSecret) {
+    Write-Host "QUIZ_SECRET is already set" -ForegroundColor Green
+} else {
+    Write-Host "QUIZ_SECRET is not set" -ForegroundColor Yellow
+    $secret = Read-Host "Enter your QUIZ_SECRET (or press Enter to generate one)"
+    if ([string]::IsNullOrWhiteSpace($secret)) {
+        # Generate a random secret
+        $secret = -join ((48..57) + (65..90) + (97..122) | Get-Random -Count 32 | ForEach-Object {[char]$_})
+        Write-Host "Generated secret: $secret" -ForegroundColor Cyan
+    }
+    $env:QUIZ_SECRET = $secret
+    Write-Host "QUIZ_SECRET set for this session" -ForegroundColor Green
+}
+
+if ($openaiKey) {
+    Write-Host "OPENAI_API_KEY is already set" -ForegroundColor Green
+} else {
+    Write-Host "OPENAI_API_KEY is not set (optional)" -ForegroundColor Yellow
+    $key = Read-Host "Enter your OPENAI_API_KEY (or press Enter to skip)"
+    if (-not [string]::IsNullOrWhiteSpace($key)) {
+        $env:OPENAI_API_KEY = $key
+        Write-Host "OPENAI_API_KEY set for this session" -ForegroundColor Green
+    }
+}
+
+if ($openrouterKey) {
+    Write-Host "OPENROUTER_API_KEY is already set" -ForegroundColor Green
+} else {
+    Write-Host "OPENROUTER_API_KEY is not set (optional, e.g., GPT-5-nano)" -ForegroundColor Yellow
+    $routerKey = Read-Host "Enter your OPENROUTER_API_KEY (or press Enter to skip)"
+    if (-not [string]::IsNullOrWhiteSpace($routerKey)) {
+        $env:OPENROUTER_API_KEY = $routerKey
+        Write-Host "OPENROUTER_API_KEY set for this session" -ForegroundColor Green
+    }
+}
+
+Write-Host ""
+Write-Host "Environment variables configured!" -ForegroundColor Green
+Write-Host ""
+Write-Host "To make these permanent, run:" -ForegroundColor Cyan
+Write-Host ('[System.Environment]::SetEnvironmentVariable("QUIZ_SECRET", "' + $env:QUIZ_SECRET + '", "User")') -ForegroundColor Gray
+if ($env:OPENAI_API_KEY) {
+    Write-Host ('[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "' + $env:OPENAI_API_KEY + '", "User")') -ForegroundColor Gray
+}
+if ($env:OPENROUTER_API_KEY) {
+    Write-Host ('[System.Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "' + $env:OPENROUTER_API_KEY + '", "User")') -ForegroundColor Gray
+}
+Write-Host ""
+Write-Host "Or copy and paste these commands:" -ForegroundColor Cyan
+Write-Host ('[System.Environment]::SetEnvironmentVariable("QUIZ_SECRET", "' + $env:QUIZ_SECRET + '", "User")') -ForegroundColor Yellow
+if ($env:OPENAI_API_KEY) {
+    Write-Host ('[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "' + $env:OPENAI_API_KEY + '", "User")') -ForegroundColor Yellow
+}
+if ($env:OPENROUTER_API_KEY) {
+    Write-Host ('[System.Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "' + $env:OPENROUTER_API_KEY + '", "User")') -ForegroundColor Yellow
+}
+Write-Host ""
+Write-Host "To start the server, run:" -ForegroundColor Cyan
+Write-Host "python -m app.main" -ForegroundColor Yellow
+

setup_env.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# Quick Environment Setup Script for Linux/Mac
+# Usage: source setup_env.sh  or  . setup_env.sh
+
+echo "IITM LLM Quiz Solver - Environment Setup"
+echo "========================================"
+echo ""
+
+# Check if variables are already set
+if [ -n "$QUIZ_SECRET" ]; then
+    echo "✓ QUIZ_SECRET is already set"
+else
+    echo "QUIZ_SECRET is not set"
+    read -p "Enter your QUIZ_SECRET (or press Enter to generate one): " secret
+    if [ -z "$secret" ]; then
+        # Generate a random secret
+        secret=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))" 2>/dev/null || openssl rand -base64 24)
+        echo "Generated secret: $secret"
+    fi
+    export QUIZ_SECRET="$secret"
+    echo "✓ QUIZ_SECRET set for this session"
+fi
+
+if [ -n "$OPENAI_API_KEY" ]; then
+    echo "✓ OPENAI_API_KEY is already set"
+else
+    echo "OPENAI_API_KEY is not set (optional)"
+    read -p "Enter your OPENAI_API_KEY (or press Enter to skip): " key
+    if [ -n "$key" ]; then
+        export OPENAI_API_KEY="$key"
+        echo "✓ OPENAI_API_KEY set for this session"
+    fi
+fi
+
+echo ""
+echo "Environment variables configured!"
+echo ""
+echo "To make these permanent, add to ~/.bashrc or ~/.zshrc:" 
+echo "export QUIZ_SECRET=\"$QUIZ_SECRET\"" 
+if [ -n "$OPENAI_API_KEY" ]; then
+    echo "export OPENAI_API_KEY=\"$OPENAI_API_KEY\""
+fi
+echo ""
+echo "To start the server, run:"
+echo "python -m app.main"
+

solver.py

@@ -0,0 +1,593 @@
+"""
+Quiz solver module - main logic for solving quizzes.
+"""
+import asyncio
+import json
+import logging
+import re
+from typing import Optional, Dict, Any, List
+import requests
+from bs4 import BeautifulSoup
+import pandas as pd
+import io
+import base64
+
+from app.browser import get_browser, cleanup_browser
+from app.llm import ask_gpt, parse_question_with_llm, solve_with_llm, initialize_llm
+from app.utils import extract_submit_url, clean_text, extract_json_from_text, is_valid_url
+
+logger = logging.getLogger(__name__)
+
+# Initialize LLM on module load
+initialize_llm()
+
+
+class QuizSolver:
+    """Main quiz solver class."""
+    
+    def __init__(self):
+        self.browser = None
+        self.max_recursion = 10
+        self.current_recursion = 0
+    
+    async def solve_quiz(self, url: str, email: str, secret: str) -> Dict[str, Any]:
+        """
+        Main entry point for solving a quiz.
+        
+        Args:
+            url: Quiz page URL
+            email: User email
+            secret: Secret key
+            
+        Returns:
+            Final response from quiz system
+        """
+        self.current_recursion = 0
+        self.browser = await get_browser()
+        
+        try:
+            return await self._solve_recursive(url, email, secret)
+        finally:
+            # Don't close browser here as it might be reused
+            pass
+    
+    async def _solve_recursive(self, url: str, email: str, secret: str) -> Dict[str, Any]:
+        """
+        Recursively solve quizzes.
+        
+        Args:
+            url: Current quiz URL
+            email: User email
+            secret: Secret key
+            
+        Returns:
+            Response from quiz system
+        """
+        if self.current_recursion >= self.max_recursion:
+            logger.error("Maximum recursion depth reached")
+            return {"error": "Maximum recursion depth reached"}
+        
+        self.current_recursion += 1
+        logger.info(f"Solving quiz {self.current_recursion}: {url}")
+        
+        try:
+            # Load the quiz page
+            page_content = await self.browser.load_page(url, wait_time=3)
+            
+            # Extract submit URL
+            submit_url = extract_submit_url(page_content['text'], url)
+            if not submit_url:
+                # Try from HTML
+                soup = BeautifulSoup(page_content['html'], 'html.parser')
+                submit_url = extract_submit_url(soup.get_text(), url)
+            
+            if not submit_url:
+                logger.error("Could not find submit URL")
+                return {"error": "Submit URL not found"}
+            
+            # Extract question and solve
+            question_text = self._extract_question(page_content)
+            logger.info(f"Question extracted: {question_text[:200]}...")
+            
+            # Solve the question
+            answer = await self._solve_question(question_text, page_content)
+            
+            # Ensure answer is in the correct format (string or simple JSON-serializable)
+            answer = self._normalize_answer(answer)
+            logger.info(f"Answer computed: {str(answer)[:200]}...")
+            
+            # Submit answer
+            response = await self._submit_answer(
+                submit_url, email, secret, url, answer
+            )
+            
+            # Check if there's a next quiz
+            if isinstance(response, dict) and 'url' in response:
+                next_url = response['url']
+                if next_url and next_url != url and is_valid_url(next_url):
+                    logger.info(f"Next quiz found: {next_url}")
+                    # Recursively solve next quiz
+                    next_response = await self._solve_recursive(next_url, email, secret)
+                    return next_response
+            
+            return response
+            
+        except Exception as e:
+            logger.error(f"Error solving quiz: {e}", exc_info=True)
+            return {"error": str(e)}
+    
+    def _extract_question(self, page_content: Dict[str, Any]) -> str:
+        """
+        Extract question text from page content.
+        
+        Args:
+            page_content: Page content dictionary
+            
+        Returns:
+            Question text
+        """
+        text = page_content.get('all_text', page_content.get('text', ''))
+        
+        # Try to find question markers
+        question_patterns = [
+            r'[Qq]uestion[:\s]+(.*?)(?:\n\n|\n[A-Z]|$)',
+            r'[Pp]roblem[:\s]+(.*?)(?:\n\n|\n[A-Z]|$)',
+            r'[Tt]ask[:\s]+(.*?)(?:\n\n|\n[A-Z]|$)',
+        ]
+        
+        for pattern in question_patterns:
+            match = re.search(pattern, text, re.DOTALL | re.IGNORECASE)
+            if match:
+                return clean_text(match.group(1))
+        
+        # If no pattern matches, return first substantial paragraph
+        paragraphs = [p.strip() for p in text.split('\n\n') if len(p.strip()) > 50]
+        if paragraphs:
+            return paragraphs[0]
+        
+        return clean_text(text[:1000])  # Return first 1000 chars
+    
+    async def _solve_question(self, question: str, page_content: Dict[str, Any]) -> Any:
+        """
+        Solve a quiz question using various strategies.
+        
+        Args:
+            question: Question text
+            page_content: Full page content
+            
+        Returns:
+            Answer (can be dict, list, string, number, etc.)
+        """
+        logger.info("Analyzing question type...")
+        
+        # Try to parse question with LLM first
+        parsed = await parse_question_with_llm(question, page_content.get('text', ''))
+        
+        # Extract data from page
+        available_data = self._extract_data_from_page(page_content)
+        
+        # Strategy 1: Check if answer is already in the page
+        answer_in_page = self._find_answer_in_page(page_content, question)
+        if answer_in_page:
+            logger.info("Answer found in page content")
+            return answer_in_page
+        
+        # Strategy 2: Check for data files/links to download
+        data_files = self._find_data_files(page_content)
+        if data_files:
+            logger.info(f"Found data files: {data_files}")
+            processed_data = await self._process_data_files(data_files)
+            if processed_data:
+                answer = await self._solve_with_data(question, processed_data)
+                if answer:
+                    return answer
+        
+        # Strategy 3: Use LLM to solve
+        logger.info("Attempting to solve with LLM...")
+        llm_answer = await solve_with_llm(question, available_data)
+        if llm_answer:
+            # Try to parse as JSON if it looks like JSON
+            json_answer = extract_json_from_text(llm_answer)
+            if json_answer:
+                return json_answer
+            return llm_answer
+        
+        # Strategy 4: Fallback - try to extract a simple answer from the question
+        # Many quiz pages have the answer in the question itself
+        simple_answer = self._extract_simple_answer(question, page_content)
+        if simple_answer:
+            logger.info("Extracted simple answer from question")
+            return simple_answer
+        
+        # Strategy 5: Last resort - return a default answer
+        logger.warning("Could not solve question, using default answer")
+        return "answer"
+    
+    def _extract_data_from_page(self, page_content: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Extract structured data from page.
+        
+        Args:
+            page_content: Page content dictionary
+            
+        Returns:
+            Dictionary of extracted data
+        """
+        data = {
+            'text': page_content.get('text', ''),
+            'html': page_content.get('html', ''),
+            'links': page_content.get('links', []),
+            'images': page_content.get('images', []),
+        }
+        
+        # Try to extract tables
+        try:
+            soup = BeautifulSoup(page_content.get('html', ''), 'html.parser')
+            tables = soup.find_all('table')
+            if tables:
+                data['tables'] = []
+                for table in tables:
+                    try:
+                        df = pd.read_html(str(table))[0]
+                        data['tables'].append(df.to_dict('records'))
+                    except:
+                        pass
+        except Exception as e:
+            logger.warning(f"Error extracting tables: {e}")
+        
+        # Try to extract JSON from page
+        json_data = extract_json_from_text(page_content.get('text', ''))
+        if json_data:
+            data['json'] = json_data
+        
+        return data
+    
+    def _find_answer_in_page(self, page_content: Dict[str, Any], question: str) -> Optional[Any]:
+        """
+        Check if answer is already present in page content.
+        
+        Args:
+            page_content: Page content
+            question: Question text
+            
+        Returns:
+            Answer if found, None otherwise
+        """
+        text = page_content.get('all_text', page_content.get('text', ''))
+        
+        # Look for answer patterns
+        answer_patterns = [
+            r'[Aa]nswer[:\s]+(.*?)(?:\n\n|$)',
+            r'[Ss]olution[:\s]+(.*?)(?:\n\n|$)',
+            r'[Rr]esult[:\s]+(.*?)(?:\n\n|$)',
+        ]
+        
+        for pattern in answer_patterns:
+            match = re.search(pattern, text, re.DOTALL | re.IGNORECASE)
+            if match:
+                answer_text = clean_text(match.group(1))
+                # Try to parse as JSON
+                json_answer = extract_json_from_text(answer_text)
+                if json_answer:
+                    return json_answer
+                return answer_text
+        
+        return None
+    
+    def _find_data_files(self, page_content: Dict[str, Any]) -> List[str]:
+        """
+        Find data files (CSV, JSON, PDF, etc.) linked in the page.
+        
+        Args:
+            page_content: Page content
+            
+        Returns:
+            List of file URLs
+        """
+        files = []
+        
+        # Check links
+        for link in page_content.get('links', []):
+            href = link.get('href', '')
+            if any(href.lower().endswith(ext) for ext in ['.csv', '.json', '.pdf', '.xlsx', '.txt']):
+                files.append(href)
+        
+        # Check text for file URLs
+        text = page_content.get('text', '')
+        file_pattern = r'https?://[^\s<>"\'\)]+\.(csv|json|pdf|xlsx|txt)'
+        matches = re.findall(file_pattern, text, re.IGNORECASE)
+        files.extend([m[0] for m in matches if m[0] not in files])
+        
+        return files
+    
+    async def _process_data_files(self, file_urls: List[str]) -> Dict[str, Any]:
+        """
+        Download and process data files.
+        
+        Args:
+            file_urls: List of file URLs
+            
+        Returns:
+            Dictionary of processed data
+        """
+        processed = {}
+        
+        for url in file_urls:
+            try:
+                logger.info(f"Downloading file: {url}")
+                response = requests.get(url, timeout=30)
+                response.raise_for_status()
+                
+                content_type = response.headers.get('content-type', '').lower()
+                filename = url.split('/')[-1]
+                
+                if 'csv' in content_type or filename.endswith('.csv'):
+                    df = pd.read_csv(io.StringIO(response.text))
+                    processed[filename] = df.to_dict('records')
+                    
+                elif 'json' in content_type or filename.endswith('.json'):
+                    processed[filename] = response.json()
+                    
+                elif 'pdf' in content_type or filename.endswith('.pdf'):
+                    # PDF processing - try pdfplumber first, then PyPDF2
+                    text = None
+                    
+                    # Try pdfplumber
+                    try:
+                        import pdfplumber
+                        with pdfplumber.open(io.BytesIO(response.content)) as pdf:
+                            text = ""
+                            for page in pdf.pages:
+                                page_text = page.extract_text()
+                                if page_text:
+                                    text += page_text + "\n"
+                        if text:
+                            processed[filename] = text.strip()
+                    except ImportError:
+                        logger.debug("pdfplumber not available")
+                    except Exception as e:
+                        logger.warning(f"Error reading PDF with pdfplumber {filename}: {e}")
+                    
+                    # Fallback to PyPDF2
+                    if not text or filename not in processed:
+                        try:
+                            import PyPDF2
+                            pdf_file = io.BytesIO(response.content)
+                            pdf_reader = PyPDF2.PdfReader(pdf_file)
+                            text = ""
+                            for page in pdf_reader.pages:
+                                page_text = page.extract_text()
+                                if page_text:
+                                    text += page_text + "\n"
+                            if text:
+                                processed[filename] = text.strip()
+                        except ImportError:
+                            logger.warning("Neither pdfplumber nor PyPDF2 available for PDF processing")
+                        except Exception as e:
+                            logger.warning(f"Error reading PDF with PyPDF2 {filename}: {e}")
+                
+                elif filename.endswith('.txt'):
+                    processed[filename] = response.text
+                    
+            except Exception as e:
+                logger.error(f"Error processing file {url}: {e}")
+                continue
+        
+        return processed
+    
+    def _normalize_answer(self, answer: Any) -> Any:
+        """
+        Normalize answer to ensure it's JSON-serializable and in correct format.
+        
+        Args:
+            answer: Raw answer (can be dict, list, string, etc.)
+            
+        Returns:
+            Normalized answer (preferably string or simple JSON)
+        """
+        if answer is None:
+            return "answer"
+        
+        # If it's a dict with question/analysis, extract a simple answer
+        if isinstance(answer, dict):
+            # If it contains an 'answer' key, use that
+            if 'answer' in answer:
+                return self._normalize_answer(answer['answer'])
+            # If it's an analysis dict, try to extract something useful
+            if 'question' in answer and len(answer) > 1:
+                # Return a simple string instead of the whole dict
+                return "answer"
+            # If it's a simple dict, convert to JSON string
+            if len(answer) <= 3:
+                try:
+                    return json.dumps(answer)
+                except:
+                    return str(answer)
+            # Complex dict - return as JSON string
+            try:
+                return json.dumps(answer)
+            except:
+                return str(answer)
+        
+        # If it's a list, convert to JSON string if small, otherwise string
+        if isinstance(answer, list):
+            if len(answer) <= 10:
+                try:
+                    return json.dumps(answer)
+                except:
+                    return str(answer)
+            return str(answer)
+        
+        # For strings, return as-is (but clean up)
+        if isinstance(answer, str):
+            # Remove excessive whitespace
+            answer = ' '.join(answer.split())
+            # If it's very long, truncate
+            if len(answer) > 1000:
+                answer = answer[:1000] + "..."
+            return answer
+        
+        # For other types, convert to string
+        return str(answer)
+    
+    def _extract_simple_answer(self, question: str, page_content: Dict[str, Any]) -> Optional[str]:
+        """
+        Try to extract a simple answer from the question or page.
+        
+        Args:
+            question: Question text
+            page_content: Page content
+            
+        Returns:
+            Simple answer string or None
+        """
+        text = page_content.get('all_text', page_content.get('text', ''))
+        combined = question + "\n\n" + text
+        
+        # Check if question says "anything" or similar - very common in demo quizzes
+        if re.search(r'"answer"\s*:\s*"anything\s+you\s+want"', combined, re.IGNORECASE):
+            return "answer"
+        if re.search(r'"answer"\s*:\s*"anything"', combined, re.IGNORECASE):
+            return "answer"
+        if re.search(r'anything\s+you\s+want|any\s+value|any\s+string|any\s+text|anything', question, re.IGNORECASE):
+            return "answer"
+        
+        # Look for patterns like "answer: X" or "the answer is X"
+        patterns = [
+            r'"answer"\s*:\s*"([^"]+)"',  # JSON format: "answer": "value"
+            r'[Aa]nswer[:\s]+["\']?([^"\'\n]+)["\']?',
+            r'[Tt]he\s+[Aa]nswer\s+[Ii]s[:\s]+["\']?([^"\'\n]+)["\']?',
+            r'[Yy]our\s+[Aa]nswer[:\s]+["\']?([^"\'\n]+)["\']?',
+        ]
+        
+        for pattern in patterns:
+            match = re.search(pattern, combined, re.IGNORECASE)
+            if match:
+                answer = match.group(1).strip()
+                # Skip if it's a placeholder or instruction
+                if answer and len(answer) < 200 and answer.lower() not in ['your email', 'your secret', 'anything you want', 'anything']:
+                    return answer
+        
+        return None
+    
+    async def _solve_with_data(self, question: str, data: Dict[str, Any]) -> Optional[Any]:
+        """
+        Solve question using processed data.
+        
+        Args:
+            question: Question text
+            data: Processed data dictionary
+            
+        Returns:
+            Answer or None
+        """
+        # Use LLM to solve with data
+        prompt = f"""Solve this question using the provided data:
+
+Question: {question}
+
+Data:
+{json.dumps(data, indent=2, default=str)}
+
+Provide the answer. If JSON format is required, return valid JSON.
+"""
+        
+        answer = await ask_gpt(prompt, max_tokens=3000)
+        if answer:
+            json_answer = extract_json_from_text(answer)
+            if json_answer:
+                return json_answer
+            return answer
+        
+        return None
+    
+    async def _submit_answer(self, submit_url: str, email: str, secret: str, 
+                            quiz_url: str, answer: Any) -> Dict[str, Any]:
+        """
+        Submit answer to the quiz system.
+        
+        Args:
+            submit_url: URL to submit answer to
+            email: User email
+            secret: Secret key
+            quiz_url: Original quiz URL
+            answer: Computed answer
+            
+        Returns:
+            Response from submission endpoint
+        """
+        # Ensure answer is JSON-serializable
+        try:
+            # Try to serialize answer to check if it's valid JSON
+            json.dumps(answer)
+        except (TypeError, ValueError) as e:
+            logger.warning(f"Answer is not JSON-serializable, converting to string: {e}")
+            # Convert complex objects to string representation
+            if isinstance(answer, (dict, list)):
+                answer = json.dumps(answer)
+            else:
+                answer = str(answer)
+        
+        payload = {
+            "email": email,
+            "secret": secret,
+            "url": quiz_url,
+            "answer": answer
+        }
+        
+        try:
+            logger.info(f"Submitting answer to: {submit_url}")
+            logger.debug(f"Payload: {json.dumps(payload, indent=2, default=str)}")
+            
+            response = requests.post(
+                submit_url,
+                json=payload,
+                headers={'Content-Type': 'application/json'},
+                timeout=60
+            )
+            
+            # Log response details
+            logger.info(f"Response status: {response.status_code}")
+            logger.debug(f"Response headers: {dict(response.headers)}")
+            
+            response.raise_for_status()
+            
+            try:
+                result = response.json()
+                logger.info(f"Submission successful: {result}")
+                return result
+            except json.JSONDecodeError:
+                logger.warning(f"Response is not JSON, returning text: {response.text[:500]}")
+                return {"response": response.text, "status_code": response.status_code}
+            
+        except requests.exceptions.HTTPError as e:
+            logger.error(f"HTTP error submitting answer: {e}")
+            if hasattr(e, 'response') and e.response is not None:
+                try:
+                    error_response = e.response.json()
+                    logger.error(f"Error response: {error_response}")
+                    return error_response
+                except:
+                    logger.error(f"Error response text: {e.response.text[:500]}")
+                    return {"error": e.response.text, "status_code": e.response.status_code}
+            return {"error": str(e)}
+        except requests.exceptions.RequestException as e:
+            logger.error(f"Error submitting answer: {e}", exc_info=True)
+            return {"error": str(e)}
+
+
+async def solve_quiz(url: str, email: str, secret: str) -> Dict[str, Any]:
+    """
+    Convenience function to solve a quiz.
+    
+    Args:
+        url: Quiz page URL
+        email: User email
+        secret: Secret key
+        
+    Returns:
+        Final response from quiz system
+    """
+    solver = QuizSolver()
+    return await solver.solve_quiz(url, email, secret)
+

test_api.ps1

@@ -0,0 +1,47 @@
+# PowerShell script to test the API correctly
+# Usage: .\test_api.ps1
+
+# Set variables if not already set
+if (-not $env:QUIZ_SECRET) {
+    $env:QUIZ_SECRET = "EasyQuiz"
+}
+
+# Create the request body as a PowerShell object (not a string)
+$body = @{
+    email = "24f2005753@ds.study.iitm.ac.in"
+    secret = "EasyQuiz"
+    url = "https://tds-llm-analysis.s-anand.net/demo"
+} | ConvertTo-Json
+
+Write-Host "Sending request to /solve endpoint..." -ForegroundColor Cyan
+Write-Host "Body: $body" -ForegroundColor Gray
+Write-Host ""
+
+try {
+    $response = Invoke-RestMethod `
+        -Uri "http://127.0.0.1:8000/solve" `
+        -Method POST `
+        -ContentType "application/json" `
+        -Body $body
+    
+    Write-Host "Response:" -ForegroundColor Green
+    $response | ConvertTo-Json -Depth 10
+}
+catch {
+    Write-Host "Error occurred:" -ForegroundColor Red
+    Write-Host $_.Exception.Message -ForegroundColor Red
+    
+    if ($_.ErrorDetails.Message) {
+        Write-Host "Details:" -ForegroundColor Yellow
+        Write-Host $_.ErrorDetails.Message -ForegroundColor Yellow
+    }
+    
+    if ($_.Response) {
+        $reader = New-Object System.IO.StreamReader($_.Exception.Response.GetResponseStream())
+        $responseBody = $reader.ReadToEnd()
+        Write-Host "Response Body:" -ForegroundColor Yellow
+        Write-Host $responseBody -ForegroundColor Yellow
+    }
+}
+
+

test_env.json.py

@@ -0,0 +1,50 @@
+"""
+Test script that outputs environment variables as JSON.
+Run: python test_env.json.py
+"""
+import os
+import json
+
+def get_env_json():
+    """Get environment variables status as JSON."""
+    quiz_secret = os.getenv("QUIZ_SECRET")
+    openai_key = os.getenv("OPENAI_API_KEY")
+    port = os.getenv("PORT", "8000")
+    openrouter_key = os.getenv("OPENROUTER_API_KEY")
+    
+    result = {
+        "status": "ok",
+        "variables": {
+            "QUIZ_SECRET": {
+                "set": quiz_secret is not None,
+                "length": len(quiz_secret) if quiz_secret else 0,
+                "preview": f"{quiz_secret[:4]}...{quiz_secret[-4:]}" if quiz_secret and len(quiz_secret) > 8 else "***" if quiz_secret else None
+            },
+            "OPENAI_API_KEY": {
+                "set": openai_key is not None,
+                "length": len(openai_key) if openai_key else 0,
+                "preview": f"{openai_key[:7]}...{openai_key[-4:]}" if openai_key and len(openai_key) > 11 else "***" if openai_key else None,
+                "valid_format": openai_key.startswith("sk-") if openai_key else False
+            },
+            "OPENROUTER_API_KEY": {
+                "set": openrouter_key is not None,
+                "length": len(openrouter_key) if openrouter_key else 0,
+                "preview": f"{openrouter_key[:7]}...{openrouter_key[-4:]}" if openrouter_key and len(openrouter_key) > 11 else "***" if openrouter_key else None,
+                "valid_format": openrouter_key.startswith("sk-or-") if openrouter_key else False
+            },
+            "PORT": {
+                "set": True,
+                "value": port
+            }
+        },
+        "ready": quiz_secret is not None,
+        "llm_enabled": any([openai_key, openrouter_key]),
+        "message": "Ready to run" if quiz_secret else "QUIZ_SECRET is required"
+    }
+    
+    return result
+
+if __name__ == "__main__":
+    result = get_env_json()
+    print(json.dumps(result, indent=2))
+

test_server.ps1

@@ -0,0 +1,94 @@
+# Test script to check if server is running and test endpoints
+# Usage: .\test_server.ps1
+
+Write-Host "Testing IITM LLM Quiz Solver API" -ForegroundColor Cyan
+Write-Host "=================================" -ForegroundColor Cyan
+Write-Host ""
+
+# Test 1: Health check
+Write-Host "1. Testing /health endpoint..." -ForegroundColor Yellow
+try {
+    $health = Invoke-RestMethod -Uri "http://127.0.0.1:8000/health" -Method GET -ErrorAction Stop
+    Write-Host "   ✓ Server is running!" -ForegroundColor Green
+    Write-Host "   Response: $($health | ConvertTo-Json)" -ForegroundColor Gray
+} catch {
+    Write-Host "   ✗ Server is NOT running or not accessible" -ForegroundColor Red
+    Write-Host "   Error: $($_.Exception.Message)" -ForegroundColor Red
+    Write-Host ""
+    Write-Host "   Please start the server first:" -ForegroundColor Yellow
+    Write-Host "   python -m app.main" -ForegroundColor Cyan
+    exit 1
+}
+
+Write-Host ""
+
+# Test 2: Root endpoint
+Write-Host "2. Testing / endpoint..." -ForegroundColor Yellow
+try {
+    $root = Invoke-RestMethod -Uri "http://127.0.0.1:8000/" -Method GET -ErrorAction Stop
+    Write-Host "   ✓ Root endpoint works!" -ForegroundColor Green
+    Write-Host "   Available endpoints:" -ForegroundColor Gray
+    $root.endpoints.PSObject.Properties | ForEach-Object {
+        Write-Host "     $($_.Name): $($_.Value)" -ForegroundColor Gray
+    }
+} catch {
+    Write-Host "   ✗ Root endpoint failed: $($_.Exception.Message)" -ForegroundColor Red
+}
+
+Write-Host ""
+
+# Test 3: Env check
+Write-Host "3. Testing /env-check endpoint..." -ForegroundColor Yellow
+try {
+    $envCheck = Invoke-RestMethod -Uri "http://127.0.0.1:8000/env-check" -Method GET -ErrorAction Stop
+    Write-Host "   ✓ Environment check works!" -ForegroundColor Green
+    Write-Host "   QUIZ_SECRET: $($envCheck.variables.QUIZ_SECRET.set)" -ForegroundColor Gray
+    Write-Host "   OPENAI_API_KEY: $($envCheck.variables.OPENAI_API_KEY.set)" -ForegroundColor Gray
+    Write-Host "   Ready: $($envCheck.ready)" -ForegroundColor Gray
+} catch {
+    Write-Host "   ✗ Env check failed: $($_.Exception.Message)" -ForegroundColor Red
+}
+
+Write-Host ""
+
+# Test 4: Demo endpoint (if server is running)
+Write-Host "4. Testing /demo endpoint..." -ForegroundColor Yellow
+Write-Host "   (This will make an actual request)" -ForegroundColor Gray
+
+# Set variables if not set
+if (-not $env:QUIZ_SECRET) {
+    $env:QUIZ_SECRET = "EasyQuiz"
+}
+
+$body = @{
+    email = "24f2005753@ds.study.iitm.ac.in"
+    secret = "EasyQuiz"
+    url = "https://tds-llm-analysis.s-anand.net/demo"
+} | ConvertTo-Json
+
+try {
+    Write-Host "   Sending request..." -ForegroundColor Gray
+    $response = Invoke-RestMethod `
+        -Uri "http://127.0.0.1:8000/demo" `
+        -Method POST `
+        -ContentType "application/json" `
+        -Body $body `
+        -ErrorAction Stop
+    
+    Write-Host "   ✓ Demo endpoint works!" -ForegroundColor Green
+    Write-Host "   Response:" -ForegroundColor Gray
+    $response | ConvertTo-Json -Depth 10 | Write-Host
+} catch {
+    Write-Host "   ✗ Demo endpoint failed" -ForegroundColor Red
+    Write-Host "   Status: $($_.Exception.Response.StatusCode.value__)" -ForegroundColor Yellow
+    if ($_.ErrorDetails.Message) {
+        Write-Host "   Error: $($_.ErrorDetails.Message)" -ForegroundColor Yellow
+    } else {
+        Write-Host "   Error: $($_.Exception.Message)" -ForegroundColor Yellow
+    }
+}
+
+Write-Host ""
+Write-Host "=================================" -ForegroundColor Cyan
+Write-Host "Test complete!" -ForegroundColor Cyan
+

utils.py

@@ -0,0 +1,180 @@
+"""
+Utility functions for the IITM LLM Quiz Solver.
+"""
+import re
+import json
+import logging
+from typing import Optional, Dict, Any
+from urllib.parse import urlparse, urljoin
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+
+def extract_submit_url(text: str, base_url: str) -> Optional[str]:
+    """
+    Extract submit URL from page text.
+    
+    Looks for patterns like:
+    - "Submit your answer to: https://example.com/submit"
+    - "Submit to: https://example.com/submit"
+    - "URL: https://example.com/submit"
+    
+    Args:
+        text: The page text content
+        base_url: Base URL for relative URL resolution
+        
+    Returns:
+        Extracted submit URL or None
+    """
+    # Common patterns for submit URLs
+    patterns = [
+        r'[Ss]ubmit\s+(?:your\s+)?(?:answer\s+)?(?:to|at|via):\s*(https?://[^\s<>"\'\)]+)',
+        r'[Ss]ubmit\s+[Tt]o:\s*(https?://[^\s<>"\'\)]+)',
+        r'[Uu][Rr][Ll]:\s*(https?://[^\s<>"\'\)]+)',
+        r'[Pp]ost\s+(?:to|at):\s*(https?://[^\s<>"\'\)]+)',
+        r'[Ss]end\s+(?:to|at):\s*(https?://[^\s<>"\'\)]+)',
+        r'(https?://[^\s<>"\'\)]*submit[^\s<>"\'\)]*)',
+        r'(https?://[^\s<>"\'\)]*answer[^\s<>"\'\)]*)',
+    ]
+    
+    for pattern in patterns:
+        matches = re.findall(pattern, text, re.IGNORECASE)
+        if matches:
+            url = matches[0].strip().rstrip('.,;:!?)}]{["\'')
+            # Validate URL
+            try:
+                parsed = urlparse(url)
+                if parsed.scheme and parsed.netloc:
+                    logger.info(f"Found submit URL: {url}")
+                    return url
+            except Exception as e:
+                logger.warning(f"Invalid URL pattern found: {url}, error: {e}")
+                continue
+    
+    # Try to find any URL that might be a submit endpoint
+    url_pattern = r'https?://[^\s<>"\'\)]+'
+    all_urls = re.findall(url_pattern, text)
+    for url in all_urls:
+        url_lower = url.lower()
+        if 'submit' in url_lower or 'answer' in url_lower:
+            try:
+                parsed = urlparse(url)
+                if parsed.scheme and parsed.netloc:
+                    logger.info(f"Found potential submit URL: {url}")
+                    return url
+            except:
+                continue
+    
+    # Try to find relative submit links (e.g. href="/submit")
+    rel_patterns = [
+        r'href=["\\\'](/[^"\\\']*submit[^"\\\']*)["\\\']',
+        r'(/[^\\s"<>\']*submit[^\\s"<>\']*)',
+    ]
+    for pattern in rel_patterns:
+        matches = re.findall(pattern, text, re.IGNORECASE)
+        if matches:
+            candidate = matches[0].strip().rstrip('.,;:!?)}]{["\'')
+            joined = urljoin(base_url, candidate)
+            logger.info(f"Found relative submit URL: {joined}")
+            return joined
+
+    logger.warning("No submit URL found in page text")
+    return None
+
+
+def validate_secret(secret: str, expected_secret: str) -> bool:
+    """
+    Validate the secret key.
+    
+    Args:
+        secret: Provided secret
+        expected_secret: Expected secret from environment
+        
+    Returns:
+        True if valid, False otherwise
+    """
+    return secret == expected_secret
+
+
+def clean_text(text: str) -> str:
+    """
+    Clean and normalize text content.
+    
+    Args:
+        text: Raw text content
+        
+    Returns:
+        Cleaned text
+    """
+    if not text:
+        return ""
+    
+    # Remove excessive whitespace
+    text = re.sub(r'\s+', ' ', text)
+    # Remove leading/trailing whitespace
+    text = text.strip()
+    
+    return text
+
+
+def extract_json_from_text(text: str) -> Optional[Dict[str, Any]]:
+    """
+    Try to extract JSON objects from text.
+    
+    Args:
+        text: Text that may contain JSON
+        
+    Returns:
+        Parsed JSON dict or None
+    """
+    # Try to find JSON blocks
+    json_pattern = r'\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}'
+    matches = re.findall(json_pattern, text, re.DOTALL)
+    
+    for match in matches:
+        try:
+            return json.loads(match)
+        except json.JSONDecodeError:
+            continue
+    
+    return None
+
+
+def is_valid_url(url: str) -> bool:
+    """
+    Validate if a string is a valid URL.
+    
+    Args:
+        url: URL string to validate
+        
+    Returns:
+        True if valid URL, False otherwise
+    """
+    try:
+        result = urlparse(url)
+        return all([result.scheme, result.netloc])
+    except Exception:
+        return False
+
+
+def sanitize_filename(filename: str) -> str:
+    """
+    Sanitize a filename by removing invalid characters.
+    
+    Args:
+        filename: Original filename
+        
+    Returns:
+        Sanitized filename
+    """
+    # Remove invalid characters
+    filename = re.sub(r'[<>:"/\\|?*]', '_', filename)
+    # Remove leading/trailing dots and spaces
+    filename = filename.strip('. ')
+    return filename
+