Upload README.md

README.md

@@ -1,277 +1,272 @@
----
-sdk: docker
----
-# IITM LLM Quiz Solver
-title: IITM LLM Quiz Solver
-emoji: 🧠
-colorFrom: green
-colorTo: blue
- sdk: docker
- sdk_version: "0"
- app_file: app/main.py
-pinned: false
----
-
-
-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.
+---
+title: IITM LLM Quiz Solver
+emoji: 🧠
+colorFrom: green
+colorTo: blue
+sdk: docker
+sdk_version: "0"
+app_file: app/main.py
+pinned: false
+---
+
+
+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            # All quiz solving logic (browser, LLM, calculations, handlers - consolidated)
+/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.
+